Merge pull request #81 from KangarooKoala/hid-direction-documentation

Improve HID direction documentation (NFC)

Author: virtuald

commands2/button/commandjoystick.py

@@ -146,6 +146,9 @@ def getX(self) -> float:
         """
         Get the x position of the HID.
 
+        This depends on the mapping of the joystick connected to the current port. On most
+        joysticks, positive is to the right.
+
         :returns: the x position
         """
         return self._hid.getX()
@@ -154,6 +157,9 @@ def getY(self) -> float:
         """
         Get the y position of the HID.
 
+        This depends on the mapping of the joystick connected to the current port. On most
+        joysticks, positive is to the back.
+
         :returns: the y position
         """
         return self._hid.getY()
@@ -186,24 +192,34 @@ def getThrottle(self) -> float:
 
     def getMagnitude(self) -> float:
         """
-        Get the magnitude of the direction vector formed by the joystick's current position relative to
-        its origin.
+        Get the magnitude of the vector formed by the joystick's current position relative to its
+        origin.
 
         :returns: The magnitude of the direction vector
         """
         return self._hid.getMagnitude()
 
     def getDirectionRadians(self) -> float:
         """
-        Get the direction of the vector formed by the joystick and its origin in radians.
+        Get the direction of the vector formed by the joystick and its origin in radians. 0 is forward
+        and clockwise is positive. (Straight right is π/2.)
 
         :returns: The direction of the vector in radians
         """
+        # https://docs.wpilib.org/en/stable/docs/software/basic-programming/coordinate-system.html#joystick-and-controller-coordinate-system
+        # A positive rotation around the X axis moves the joystick right, and a
+        # positive rotation around the Y axis moves the joystick backward. When
+        # treating them as translations, 0 radians is measured from the right
+        # direction, and angle increases clockwise.
+        #
+        # It's rotated 90 degrees CCW (y is negated and the arguments are reversed)
+        # so that 0 radians is forward.
         return self._hid.getDirectionRadians()
 
     def getDirectionDegrees(self) -> float:
         """
-        Get the direction of the vector formed by the joystick and its origin in degrees.
+        Get the direction of the vector formed by the joystick and its origin in degrees. 0 is forward
+        and clockwise is positive. (Straight right is 90.)
 
         :returns: The direction of the vector in degrees
         """

commands2/button/commandps4controller.py

@@ -231,31 +231,31 @@ def touchpad(self, loop: Optional[EventLoop] = None) -> Trigger:
 
     def getLeftX(self) -> float:
         """
-        Get the X axis value of left side of the controller.
+        Get the X axis value of left side of the controller. Right is positive.
 
         :returns: the axis value.
         """
         return self._hid.getLeftX()
 
     def getRightX(self) -> float:
         """
-        Get the X axis value of right side of the controller.
+        Get the X axis value of right side of the controller. Right is positive.
 
         :returns: the axis value.
         """
         return self._hid.getRightX()
 
     def getLeftY(self) -> float:
         """
-        Get the Y axis value of left side of the controller.
+        Get the Y axis value of left side of the controller. Back is positive.
 
         :returns: the axis value.
         """
         return self._hid.getLeftY()
 
     def getRightY(self) -> float:
         """
-        Get the Y axis value of right side of the controller.
+        Get the Y axis value of right side of the controller. Back is positive.
 
         :returns: the axis value.
         """

commands2/button/commandxboxcontroller.py

@@ -213,31 +213,31 @@ def rightTrigger(
 
     def getLeftX(self) -> float:
         """
-        Get the X axis value of left side of the controller.
+        Get the X axis value of left side of the controller. Right is positive.
 
         :returns: The axis value.
         """
         return self._hid.getLeftX()
 
     def getRightX(self) -> float:
         """
-        Get the X axis value of right side of the controller.
+        Get the X axis value of right side of the controller. Right is positive.
 
         :returns: The axis value.
         """
         return self._hid.getRightX()
 
     def getLeftY(self) -> float:
         """
-        Get the Y axis value of left side of the controller.
+        Get the Y axis value of left side of the controller. Back is positive.
 
         :returns: The axis value.
         """
         return self._hid.getLeftY()
 
     def getRightY(self) -> float:
         """
-        Get the Y axis value of right side of the controller.
+        Get the Y axis value of right side of the controller. Back is positive.
 
         :returns: The axis value.
         """