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. * + *
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 */ diff --git a/wpilibNewCommands/src/main/native/cpp/frc2/command/button/CommandJoystick.cpp b/wpilibNewCommands/src/main/native/cpp/frc2/command/button/CommandJoystick.cpp index ae25fb05ea..2d36ef7cb6 100644 --- a/wpilibNewCommands/src/main/native/cpp/frc2/command/button/CommandJoystick.cpp +++ b/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(); } diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/button/CommandJoystick.h b/wpilibNewCommands/src/main/native/include/frc2/command/button/CommandJoystick.h index d1eeadfc2c..ee390d0aa5 100644 --- a/wpilibNewCommands/src/main/native/include/frc2/command/button/CommandJoystick.h +++ b/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. */ diff --git a/wpilibc/src/generate/main/native/include/frc/hid.h.jinja b/wpilibc/src/generate/main/native/include/frc/hid.h.jinja index 5f26fe2435..af6d46d36c 100644 --- a/wpilibc/src/generate/main/native/include/frc/hid.h.jinja +++ b/wpilibc/src/generate/main/native/include/frc/hid.h.jinja @@ -47,7 +47,7 @@ class {{ ConsoleName }}Controller : public GenericHID, {{ ConsoleName }}Controller& operator=({{ ConsoleName }}Controller&&) = default; {% 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. */ diff --git a/wpilibc/src/generated/main/native/include/frc/PS4Controller.h b/wpilibc/src/generated/main/native/include/frc/PS4Controller.h index ed8f5a5cf2..01e8c49c47 100644 --- a/wpilibc/src/generated/main/native/include/frc/PS4Controller.h +++ b/wpilibc/src/generated/main/native/include/frc/PS4Controller.h @@ -45,28 +45,28 @@ class PS4Controller : public GenericHID, PS4Controller& operator=(PS4Controller&&) = default; /** - * 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. */ diff --git a/wpilibc/src/generated/main/native/include/frc/PS5Controller.h b/wpilibc/src/generated/main/native/include/frc/PS5Controller.h index 3a1c9217ee..2fd6557e25 100644 --- a/wpilibc/src/generated/main/native/include/frc/PS5Controller.h +++ b/wpilibc/src/generated/main/native/include/frc/PS5Controller.h @@ -45,28 +45,28 @@ class PS5Controller : public GenericHID, PS5Controller& operator=(PS5Controller&&) = default; /** - * 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. */ diff --git a/wpilibc/src/generated/main/native/include/frc/StadiaController.h b/wpilibc/src/generated/main/native/include/frc/StadiaController.h index 025377f600..89b7dab339 100644 --- a/wpilibc/src/generated/main/native/include/frc/StadiaController.h +++ b/wpilibc/src/generated/main/native/include/frc/StadiaController.h @@ -45,28 +45,28 @@ class StadiaController : public GenericHID, StadiaController& operator=(StadiaController&&) = default; /** - * 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. */ diff --git a/wpilibc/src/generated/main/native/include/frc/XboxController.h b/wpilibc/src/generated/main/native/include/frc/XboxController.h index 222fc2b0f8..e69f9bdb02 100644 --- a/wpilibc/src/generated/main/native/include/frc/XboxController.h +++ b/wpilibc/src/generated/main/native/include/frc/XboxController.h @@ -45,28 +45,28 @@ class XboxController : public GenericHID, XboxController& operator=(XboxController&&) = default; /** - * 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. */ diff --git a/wpilibc/src/main/native/cpp/Joystick.cpp b/wpilibc/src/main/native/cpp/Joystick.cpp index b58a514cbd..8ee437a3f5 100644 --- a/wpilibc/src/main/native/cpp/Joystick.cpp +++ b/wpilibc/src/main/native/cpp/Joystick.cpp @@ -119,5 +119,13 @@ double Joystick::GetMagnitude() const { } units::radian_t Joystick::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 units::radian_t{std::atan2(GetX(), -GetY())}; } diff --git a/wpilibc/src/main/native/include/frc/Joystick.h b/wpilibc/src/main/native/include/frc/Joystick.h index 0f8e101491..399a304d84 100644 --- a/wpilibc/src/main/native/include/frc/Joystick.h +++ b/wpilibc/src/main/native/include/frc/Joystick.h @@ -148,6 +148,7 @@ class Joystick : public GenericHID { * Get the X value of the current joystick. * * This depends on the mapping of the joystick connected to the current port. + * On most joysticks, positive is to the right. */ double GetX() const; @@ -155,6 +156,7 @@ class Joystick : public GenericHID { * Get the Y value of the current joystick. * * This depends on the mapping of the joystick connected to the current port. + * On most joysticks, positive is to the back. */ double GetY() const; @@ -244,7 +246,7 @@ class Joystick : public GenericHID { BooleanEvent Top(EventLoop* loop) 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 @@ -252,7 +254,9 @@ class Joystick : public GenericHID { 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. */ diff --git a/wpilibj/src/generate/hids.json b/wpilibj/src/generate/hids.json index f27806458a..ed7d4f9e63 100644 --- a/wpilibj/src/generate/hids.json +++ b/wpilibj/src/generate/hids.json @@ -60,28 +60,32 @@ "left", "X" ], - "value": 0 + "value": 0, + "PositiveDirection": "Right" }, { "NameParts": [ "right", "X" ], - "value": 4 + "value": 4, + "PositiveDirection": "Right" }, { "NameParts": [ "left", "Y" ], - "value": 1 + "value": 1, + "PositiveDirection": "Back" }, { "NameParts": [ "right", "Y" ], - "value": 5 + "value": 5, + "PositiveDirection": "Back" } ], "triggers": [ @@ -175,28 +179,32 @@ "left", "X" ], - "value": 0 + "value": 0, + "PositiveDirection": "Right" }, { "NameParts": [ "left", "Y" ], - "value": 1 + "value": 1, + "PositiveDirection": "Back" }, { "NameParts": [ "right", "X" ], - "value": 2 + "value": 2, + "PositiveDirection": "Right" }, { "NameParts": [ "right", "Y" ], - "value": 5 + "value": 5, + "PositiveDirection": "Back" } ], "triggers": [ @@ -290,28 +298,32 @@ "left", "X" ], - "value": 0 + "value": 0, + "PositiveDirection": "Right" }, { "NameParts": [ "left", "Y" ], - "value": 1 + "value": 1, + "PositiveDirection": "Back" }, { "NameParts": [ "right", "X" ], - "value": 2 + "value": 2, + "PositiveDirection": "Right" }, { "NameParts": [ "right", "Y" ], - "value": 5 + "value": 5, + "PositiveDirection": "Back" } ], "triggers": [ @@ -412,28 +424,32 @@ "left", "X" ], - "value": 0 + "value": 0, + "PositiveDirection": "Right" }, { "NameParts": [ "right", "X" ], - "value": 3 + "value": 3, + "PositiveDirection": "Right" }, { "NameParts": [ "left", "Y" ], - "value": 1 + "value": 1, + "PositiveDirection": "Back" }, { "NameParts": [ "right", "Y" ], - "value": 4 + "value": 4, + "PositiveDirection": "Back" } ] } diff --git a/wpilibj/src/generate/hids.schema.json b/wpilibj/src/generate/hids.schema.json index 3b9dca3015..fa40e7d7f0 100644 --- a/wpilibj/src/generate/hids.schema.json +++ b/wpilibj/src/generate/hids.schema.json @@ -66,7 +66,8 @@ "type": "object", "required": [ "NameParts", - "value" + "value", + "PositiveDirection" ], "properties": { "NameParts": { @@ -80,6 +81,10 @@ "value": { "description": "The axis value", "type": "integer" + }, + "PositiveDirection": { + "description": "The positive direction of the axis.", + "type": "string" } } } diff --git a/wpilibj/src/generate/main/java/hid.java.jinja b/wpilibj/src/generate/main/java/hid.java.jinja index 242bf13f75..4becaf48b6 100644 --- a/wpilibj/src/generate/main/java/hid.java.jinja +++ b/wpilibj/src/generate/main/java/hid.java.jinja @@ -103,7 +103,7 @@ public class {{ ConsoleName }}Controller extends GenericHID implements Sendable } {% 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. */ diff --git a/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/PS4Controller.java b/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/PS4Controller.java index 70c1ce1c16..bf5ee2d59c 100644 --- a/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/PS4Controller.java +++ b/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/PS4Controller.java @@ -129,7 +129,7 @@ public class PS4Controller extends GenericHID implements Sendable { } /** - * 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. */ @@ -138,7 +138,7 @@ public class PS4Controller extends GenericHID implements Sendable { } /** - * 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. */ @@ -147,7 +147,7 @@ public class PS4Controller extends GenericHID implements Sendable { } /** - * 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. */ @@ -156,7 +156,7 @@ public class PS4Controller extends GenericHID implements Sendable { } /** - * 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. */ diff --git a/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/PS5Controller.java b/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/PS5Controller.java index 7cd5bfd5f1..48da8e8415 100644 --- a/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/PS5Controller.java +++ b/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/PS5Controller.java @@ -129,7 +129,7 @@ public class PS5Controller extends GenericHID implements Sendable { } /** - * 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. */ @@ -138,7 +138,7 @@ public class PS5Controller extends GenericHID implements Sendable { } /** - * 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. */ @@ -147,7 +147,7 @@ public class PS5Controller extends GenericHID implements Sendable { } /** - * 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. */ @@ -156,7 +156,7 @@ public class PS5Controller extends GenericHID implements Sendable { } /** - * 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. */ diff --git a/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/StadiaController.java b/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/StadiaController.java index 5443e5755b..f0a120bda1 100644 --- a/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/StadiaController.java +++ b/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/StadiaController.java @@ -127,7 +127,7 @@ public class StadiaController extends GenericHID implements Sendable { } /** - * 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. */ @@ -136,7 +136,7 @@ public class StadiaController extends GenericHID implements Sendable { } /** - * 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. */ @@ -145,7 +145,7 @@ public class StadiaController extends GenericHID implements Sendable { } /** - * 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. */ @@ -154,7 +154,7 @@ public class StadiaController extends GenericHID implements Sendable { } /** - * 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. */ diff --git a/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/XboxController.java b/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/XboxController.java index 78abae8ed7..04efec2217 100644 --- a/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/XboxController.java +++ b/wpilibj/src/generated/main/java/edu/wpi/first/wpilibj/XboxController.java @@ -121,7 +121,7 @@ public class XboxController extends GenericHID implements Sendable { } /** - * 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. */ @@ -130,7 +130,7 @@ public class XboxController extends GenericHID implements Sendable { } /** - * 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. */ @@ -139,7 +139,7 @@ public class XboxController extends GenericHID implements Sendable { } /** - * 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. */ @@ -148,7 +148,7 @@ public class XboxController extends GenericHID implements Sendable { } /** - * 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. */ diff --git a/wpilibj/src/main/java/edu/wpi/first/wpilibj/Joystick.java b/wpilibj/src/main/java/edu/wpi/first/wpilibj/Joystick.java index 08eebeef7d..8078eff208 100644 --- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/Joystick.java +++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/Joystick.java @@ -179,7 +179,7 @@ public class Joystick extends GenericHID { /** * Get the X value of the joystick. This depends on the mapping of the joystick connected to the - * current port. + * current port. On most joysticks, positive is to the right. * * @return The X value of the joystick. */ @@ -189,7 +189,7 @@ public class Joystick extends GenericHID { /** * Get the Y value of the joystick. This depends on the mapping of the joystick connected to the - * current port. + * current port. On most joysticks, positive is to the back. * * @return The Y value of the joystick. */ @@ -303,8 +303,8 @@ public class Joystick extends GenericHID { } /** - * 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 */ @@ -313,16 +313,26 @@ public class Joystick extends GenericHID { } /** - * 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 Math.atan2(getX(), -getY()); } /** - * 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 */