Merge branch 'main' into 2027

wpilibNewCommands/src/generate/main/java/commandhid.java.jinja

@@ -107,7 +107,7 @@ public class Command{{ ConsoleName }}Controller extends CommandGenericHID {
 {% endfor -%}
 {% for stick in sticks %}
   /**
-   * Get the {{ stick.NameParts[1] }} axis value of {{ stick.NameParts[0] }} side of the controller.
+   * Get the {{ stick.NameParts[1] }} axis value of {{ stick.NameParts[0] }} side of the controller. {{ stick.PositiveDirection }} is positive.
    *
    * @return The axis value.
    */

wpilibNewCommands/src/generate/main/native/include/frc2/command/button/commandhid.h.jinja

@@ -71,7 +71,7 @@ class Command{{ ConsoleName }}Controller : public CommandGenericHID {
 {% endfor -%}
 {% for stick in sticks %}
   /**
-   * Get the {{ stick.NameParts[1] }} axis value of {{ stick.NameParts[0] }} side of the controller.
+   * Get the {{ stick.NameParts[1] }} axis value of {{ stick.NameParts[0] }} side of the controller. {{ stick.PositiveDirection }} is positive.
    *
    * @return The axis value.
    */

wpilibNewCommands/src/generated/main/java/edu/wpi/first/wpilibj2/command/button/CommandPS4Controller.java

@@ -348,7 +348,7 @@ public class CommandPS4Controller extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
@@ -357,7 +357,7 @@ public class CommandPS4Controller extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
@@ -366,7 +366,7 @@ public class CommandPS4Controller extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
@@ -375,7 +375,7 @@ public class CommandPS4Controller extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */

wpilibNewCommands/src/generated/main/java/edu/wpi/first/wpilibj2/command/button/CommandPS5Controller.java

@@ -348,7 +348,7 @@ public class CommandPS5Controller extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
@@ -357,7 +357,7 @@ public class CommandPS5Controller extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
@@ -366,7 +366,7 @@ public class CommandPS5Controller extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
@@ -375,7 +375,7 @@ public class CommandPS5Controller extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */

wpilibNewCommands/src/generated/main/java/edu/wpi/first/wpilibj2/command/button/CommandStadiaController.java

@@ -370,7 +370,7 @@ public class CommandStadiaController extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
@@ -379,7 +379,7 @@ public class CommandStadiaController extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
@@ -388,7 +388,7 @@ public class CommandStadiaController extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
@@ -397,7 +397,7 @@ public class CommandStadiaController extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */

wpilibNewCommands/src/generated/main/java/edu/wpi/first/wpilibj2/command/button/CommandXboxController.java

@@ -338,7 +338,7 @@ public class CommandXboxController extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
@@ -347,7 +347,7 @@ public class CommandXboxController extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
@@ -356,7 +356,7 @@ public class CommandXboxController extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
@@ -365,7 +365,7 @@ public class CommandXboxController extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The axis value.
    */

wpilibNewCommands/src/generated/main/native/include/frc2/command/button/CommandPS4Controller.h

@@ -204,28 +204,28 @@ class CommandPS4Controller : public CommandGenericHID {
                                                 .GetDefaultButtonLoop()) const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
   double GetLeftX() const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
   double GetLeftY() const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
   double GetRightX() const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */

wpilibNewCommands/src/generated/main/native/include/frc2/command/button/CommandPS5Controller.h

@@ -204,28 +204,28 @@ class CommandPS5Controller : public CommandGenericHID {
                                                 .GetDefaultButtonLoop()) const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
   double GetLeftX() const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
   double GetLeftY() const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
   double GetRightX() const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */

wpilibNewCommands/src/generated/main/native/include/frc2/command/button/CommandStadiaController.h

@@ -216,28 +216,28 @@ class CommandStadiaController : public CommandGenericHID {
                                                 .GetDefaultButtonLoop()) const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
   double GetLeftX() const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
   double GetRightX() const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
   double GetLeftY() const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */

wpilibNewCommands/src/generated/main/native/include/frc2/command/button/CommandXboxController.h

@@ -190,28 +190,28 @@ class CommandXboxController : public CommandGenericHID {
                                                  .GetDefaultButtonLoop()) const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
   double GetLeftX() const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
   double GetRightX() const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */
   double GetLeftY() const;
 
   /**
-   * 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.
    *
    * @return The axis value.
    */

wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/button/CommandJoystick.java

@@ -173,6 +173,9 @@ public class CommandJoystick extends CommandGenericHID {
   /**
    * Get the x position of the HID.
    *
+   * <p>This depends on the mapping of the joystick connected to the current port. On most
+   * joysticks, positive is to the right.
+   *
    * @return the x position
    */
   public double getX() {
@@ -182,6 +185,9 @@ public class CommandJoystick extends CommandGenericHID {
   /**
    * Get the y position of the HID.
    *
+   * <p>This depends on the mapping of the joystick connected to the current port. On most
+   * joysticks, positive is to the back.
+   *
    * @return the y position
    */
   public double getY() {
@@ -218,8 +224,8 @@ public class CommandJoystick extends CommandGenericHID {
   }
 
   /**
-   * 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.
    *
    * @return The magnitude of the direction vector
    */
@@ -228,16 +234,26 @@ public class CommandJoystick extends CommandGenericHID {
   }
 
   /**
-   * 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.)
    *
    * @return The direction of the vector in radians
    */
   public double getDirectionRadians() {
+    // 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 m_hid.getDirectionRadians();
   }
 
   /**
-   * 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.)
    *
    * @return The direction of the vector in degrees
    */

wpilibNewCommands/src/main/native/cpp/frc2/command/button/CommandJoystick.cpp

@@ -26,5 +26,13 @@ double CommandJoystick::GetMagnitude() const {
 }
 
 units::radian_t CommandJoystick::GetDirection() const {
+  // 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 m_hid.GetDirection();
 }

wpilibNewCommands/src/main/native/include/frc2/command/button/CommandJoystick.h

@@ -56,7 +56,7 @@ class CommandJoystick : public CommandGenericHID {
   class Trigger Top(frc::EventLoop* loop = CommandScheduler::GetInstance()
                                                .GetDefaultButtonLoop()) const;
   /**
-   * Get the magnitude of the direction vector formed by the joystick's
+   * Get the magnitude of the vector formed by the joystick's
    * current position relative to its origin.
    *
    * @return The magnitude of the direction vector
@@ -64,7 +64,9 @@ class CommandJoystick : public CommandGenericHID {
   double GetMagnitude() const;
 
   /**
-   * Get the direction of the vector formed by the joystick and its origin.
+   * Get the direction of the vector formed by the joystick and its origin. 0 is
+   * forward and clockwise is positive. (Straight right is π/2 radians or 90
+   * degrees.)
    *
    * @return The direction of the vector.
    */