Skip to content

Commit 3a04efd

Browse files
agasseragasser
committed
Add section about using joystick to drive
1 parent a460e3d commit 3a04efd

File tree

1 file changed

+124
-4
lines changed

1 file changed

+124
-4
lines changed

‎source/docs/software/coordinate-system.rst

Lines changed: 124 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Coordinate system
1+
Coordinate System
22
=================
33

44
Coordinate systems are used in FRC programming in several places. A few of the common places are: robot movement, joystick input, pose estimation, AprilTags, and path planning.
@@ -46,6 +46,126 @@ Joysticks, including the sticks on XBox controllers, don't use the same NWU coor
4646

4747
It's important to note that joystick axes values are rotations around the respective axes, not translations. In practical terms, this means:
4848

49-
- pushing forward on the joystick (toward the positive X axis) is a CW rotation around the Y axis, so you get a negative Y value.
50-
- pushing to the right (toward the postivie Y axis) is a CCW rotation around the X axis, so you get a positive X value.
51-
- twisting the joystick CW (toward the positive Y axis) is a CCW rotation around the Z axis, so you get a positive Z value.
49+
- pushing forward on the joystick (toward the positive X axis) is a CW rotation around the Y axis, so you get a negative Y value.
50+
- pushing to the right (toward the postivie Y axis) is a CCW rotation around the X axis, so you get a positive X value.
51+
- twisting the joystick CW (toward the positive Y axis) is a CCW rotation around the Z axis, so you get a positive Z value.
52+
53+
Using Joystick and XBox Controller input to drive a robot
54+
---------------------------------------------------------
55+
56+
You may have noticed, the coordinate system used by WPILib for the robot is not the same as the coordinate system used for joysticks. Care needs to be taken to understand the difference, and properly pass driver input to the drive subsystem.
57+
58+
Non-holonomic drivetrain example
59+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
60+
61+
Non-holonomic means the robot drivetrain cannot move side-to-side (strafe). This type of drivetrain can move forward and backward along the X axis, and rotate around the Z axis. Consider a common arcade drive scheme using a single joystick where the driver pushes the joystick forward/backwrd for forward/backward robot movement, and push the joystick left/right to rotate the robot left/right.
62+
63+
The code snippet below uses the ``DifferentialDrive`` and ``Joystick`` classes to drive the robot with the arcade scheme described above. ``DifferentialDrive`` uses the robot coordinate system defined above, and ``Joystick`` uses the joystick coordinate system.
64+
65+
.. tab-set-code::
66+
67+
.. code-block:: java
68+
69+
public void teleopPeriodic() {
70+
// Arcade drive with a given forward and turn rate
71+
myDrive.arcadeDrive(-driveStick.getY(), -driveStick.getX());
72+
}
73+
74+
.. code-block:: c++
75+
76+
void TeleopPeriodic() override {
77+
// Arcade drive with a given forward and turn rate
78+
myDrive.ArcadeDrive(-driveStick.GetY(), -driveStick.GetX());
79+
}
80+
81+
.. code-block:: python
82+
83+
def teleopPeriodic(self):
84+
# Arcade drive with a given forward and turn rate
85+
self.myDrive.arcadeDrive(-self.driveStick.getY(), -self.driveStick.getX())
86+
87+
The code calls the ``DifferentialDrive.arcadeDrive(xSpeed, zRotation)`` method, with values it gets from the ``Joystick`` class:
88+
89+
- The first argument is ``xSpeed``
90+
91+
- Robot: ``xSpeed`` is the speed along the robot's X axis, which is forward/backward.
92+
- Joystick: The driver sets forward/backward speed by rotating the joystick along its Y axis, which is pushing the joystick forward/backward.
93+
- Code: Moving the joystick forward is negative Y rotation, whereas robot forward is along the positive X axis. This means the joystick value needs to be inverted by placing a - (minus sign) in front of the value.
94+
95+
- The second argument is ``zRotation``
96+
97+
- Robot: ``zRotation`` is the speed of rotation along the robot's Z axis, which is rotating left/right.
98+
- Joystick: The driver sets rotation speed by rotating the joystick along its X axis, which is pushing the joystick left/right.
99+
- Code: Moving the joystick to the right is positive X rotation, whereas robot rotation is CCW positive. This means the joystick value needs to be inverted by placing a - (minus sign) in front of the value.
100+
101+
Mecanum drivetrain example
102+
^^^^^^^^^^^^^^^^^^^^^^^^^^
103+
104+
Mecanum drivetrains are holonomic, meaning they have the ability to move side-to-side. This type of drivetrain can move forward/backward and rotate around the Z axis like non-holonomic drivetrains, but it can also move side-to-side along the robot's Y axis. Consider a common arcade drive scheme using a single joystick where the driver pushes the joystick forward/backward for forward/backward robot movement, pushes the joystick left/right to move side-to-side, and twists the joystick to rotate the robot.
105+
106+
.. tab-set-code::
107+
108+
.. code-block:: java
109+
110+
public void teleopPeriodic() {
111+
// Drive using the X, Y, and Z axes of the joystick.
112+
m_robotDrive.driveCartesian(-m_stick.getY(), -m_stick.getX(), -m_stick.getZ());
113+
}
114+
115+
.. code-block:: c++
116+
117+
void TeleopPeriodic() override {
118+
// Drive using the X, Y, and Z axes of the joystick.
119+
m_robotDrive.driveCartesian(-m_stick.GetY(), -m_stick.GetX(), -m_stick.GetZ());
120+
}
121+
122+
.. code-block:: python
123+
124+
def teleopPeriodic(self):
125+
// Drive using the X, Y, and Z axes of the joystick.
126+
self.robotDrive.driveCartesian(-self.stick.getY(), -self.stick.getX(), -self.stick.getZ())
127+
128+
The code calls the ``MecanumDrive.driveCartesian(xSpeed, ySpeed, zRotation)`` method, with values it gets from the ``Joystick`` class:
129+
130+
- The first argument is ``xSpeed``
131+
132+
- Robot: ``xSpeed`` is the speed along the robot's X axis, which is forward/backward.
133+
- Joystick: The driver sets forward/backward speed by rotating the joystick along its Y axis, which is pushing the joystick forward/backward.
134+
- Code: Moving the joystick forward is negative Y rotation, whereas robot forward is along the positive X axis. This means the joystick value needs to be inverted by placing a - (minus sign) in front of the value.
135+
136+
137+
- The second argument is ``ySpeed``
138+
139+
- Robot: ``ySpeed`` is the speed along the robot's Y axis, which is left/right.
140+
- Joystick: The driver sets left/right speed by rotating the joystick along its X axis, which is pushing the joystick left/right.
141+
- Code: Moving the joystick to the right is positive X rotation, whereas robot right is along the negative Y axis. This means the joystick value needs to be inverted by placing a - (minus sign) in front of the value.
142+
143+
- The third argument is ``zRotation``
144+
145+
- Robot: ``zRotation`` is the speed of rotation along the robot's Z axis, which is rotating left/right.
146+
- Joystick: The driver sets rotation speed by twisting the joystick along its Z axis, which is twisting the joystick left/right.
147+
- Code: Twisting the joystick to the right is positive Z rotation, whereas robot rotation is CCW positive. This means the joystick value needs to be inverted by placing a - (minus sign) in front of the value.
148+
149+
Swerve drivetrain example
150+
^^^^^^^^^^^^^^^^^^^^^^^^^^
151+
152+
Like mecanum drivetrains, swerve drivetrains are holonomic and have the ability to move side-to-side. Joystick control can be handled the same way for all holonomic drivetrains, but WPILib doesn't have a built-in robot drive class for swerve. Swerve coding is described in other sections of this documentation, but an example of using joystick input to set ``ChassisSpeeds`` values is included below. Consider the same common arcade drive scheme described in the mecanum section above. The scheme uses a single joystick where the driver pushes the joystick forward/backward for forward/backward robot movement, pushes the joystick left/right to move side-to-side, and twists the joystick to rotate the robot.
153+
154+
.. tab-set-code::
155+
156+
.. code-block:: java
157+
158+
// Drive using the X, Y, and Z axes of the joystick.
159+
var speeds = new ChassisSpeeds(-m_stick.getY(), -m_stick.getX(), -m_stick.getZ());
160+
161+
.. code-block:: c++
162+
163+
// Drive using the X, Y, and Z axes of the joystick.
164+
frc::ChassisSpeeds speeds{-m_stick.GetY(), -m_stick.GetX(), -m_stick.GetZ()};
165+
166+
.. code-block:: python
167+
168+
// Drive using the X, Y, and Z axes of the joystick.
169+
speeds = ChassisSpeeds(-self.stick.getY(), -self.stick.getX(), -self.stick.getZ())
170+
171+
The three arguments to the ``ChassisSpeeds`` constructor are the same as ``driveCartesian`` in the mecanum section above; ``xSpeed``, ``ySpeed``, and ``zRotation``. See the description of the arguments, and their joystick input in the section above.

0 commit comments

Comments
 (0)