Coordinate Systems and Units
When software is used to get inputs from physical devices and send commands to physical devices, it is important to work in the coordinate systems and units that match the devices. At that same time there may be certain conventions that are more natural for human operators. The software needs to keep track of the different coordinate systems and units and do the necessary conversions.
Some of the coordinate systems used in FRC and the WPILib software are shown in the figure below. The drive systems and chassis use a North-West-Up (NWU) system to designate the positive directions. The forward direction is aligned with “North” so it is positive. Likewise, the left direction is aligned with “West” so it is positive. Any rotation about an axis is counterclockwise (CCW) about the axis when looking into the +axis. That means that rotation about the Z axis which represents turning is + when turning left.
Gyros and accelerometers often use a North-East-Down (NED) coordinate system, but it is important to check the documentation for the particular device and software libraries that provide the interface to make sure. Joysticks use angular rotations internally, but we usually think of moving forward-back and left-right, and the WPILib joystick and operator controller classes treat them this way. The conversion from angles to linear motion causes a swapping of axes and a reversal in direction that you need to be aware of.
The units of measurement also need to match the hardware interface and be easy to understand during testing, operation and analysis of log data. Motors work in angular units, but if they are driving a linear mechanism like an elevator or moving the drivetrain linearly, then units of position and speed are more natural using linear measurements. The software code that defines constants or works with units should be clear using good symbol naming and added comments when needed.
References:
WPILib Axis Conventions:
https://docs.wpilib.org/en/stable/docs/software/hardware-apis/motors/wpi-drive-classes.html#axis-conventions
Discussion