Merge branch 'main' into 2027

wpilibj/src/main/java/edu/wpi/first/wpilibj/AddressableLED.java

@@ -11,13 +11,57 @@ import edu.wpi.first.hal.PWMJNI;
 /**
  * A class for driving addressable LEDs, such as WS2812B, WS2815, and NeoPixels.
  *
- * <p>By default, the timing supports WS2812B and WS2815 LEDs, but is configurable using
- * setBitTiming()
+ * <p>By default, the timing supports WS2812B and WS2815 LEDs, but is configurable using {@link
+ * #setBitTiming(int, int, int, int)}
+ *
+ * <p>Some LEDs use a different color order than the default GRB. The color order is configurable
+ * using {@link #setColorOrder(ColorOrder)}.
  *
  * <p>Only 1 LED driver is currently supported by the roboRIO. However, multiple LED strips can be
  * connected in series and controlled from the single driver.
  */
 public class AddressableLED implements AutoCloseable {
+  /** Order that color data is sent over the wire. */
+  public enum ColorOrder {
+    /** RGB order. */
+    kRGB(AddressableLEDJNI.COLOR_ORDER_RGB),
+    /** RBG order. */
+    kRBG(AddressableLEDJNI.COLOR_ORDER_RBG),
+    /** BGR order. */
+    kBGR(AddressableLEDJNI.COLOR_ORDER_BGR),
+    /** BRG order. */
+    kBRG(AddressableLEDJNI.COLOR_ORDER_BRG),
+    /** GBR order. */
+    kGBR(AddressableLEDJNI.COLOR_ORDER_GBR),
+    /** GRB order. This is the default order. */
+    kGRB(AddressableLEDJNI.COLOR_ORDER_GRB);
+
+    /** The native value for this ColorOrder. */
+    public final int value;
+
+    ColorOrder(int value) {
+      this.value = value;
+    }
+
+    /**
+     * Gets a color order from an int value.
+     *
+     * @param value int value
+     * @return color order
+     */
+    public ColorOrder fromValue(int value) {
+      return switch (value) {
+        case AddressableLEDJNI.COLOR_ORDER_RBG -> kRBG;
+        case AddressableLEDJNI.COLOR_ORDER_BGR -> kBGR;
+        case AddressableLEDJNI.COLOR_ORDER_BRG -> kBRG;
+        case AddressableLEDJNI.COLOR_ORDER_GRB -> kGRB;
+        case AddressableLEDJNI.COLOR_ORDER_GBR -> kGBR;
+        case AddressableLEDJNI.COLOR_ORDER_RGB -> kRGB;
+        default -> kGRB;
+      };
+    }
+  }
+
   private final int m_pwmHandle;
   private final int m_handle;
 
@@ -42,6 +86,17 @@ public class AddressableLED implements AutoCloseable {
     }
   }
 
+  /**
+   * Sets the color order for this AddressableLED. The default order is GRB.
+   *
+   * <p>This will take effect on the next call to {@link #setData(AddressableLEDBuffer)}.
+   *
+   * @param order the color order
+   */
+  public void setColorOrder(ColorOrder order) {
+    AddressableLEDJNI.setColorOrder(m_handle, order.value);
+  }
+
   /**
    * Sets the length of the LED strip.
    *

wpilibj/src/main/java/edu/wpi/first/wpilibj/Joystick.java

@@ -178,7 +178,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.
    */
@@ -188,7 +188,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.
    */
@@ -302,8 +302,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
    */
@@ -312,16 +312,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
    */

wpilibj/src/main/java/edu/wpi/first/wpilibj/simulation/LinearSystemSim.java

@@ -75,10 +75,10 @@ public class LinearSystemSim<States extends Num, Inputs extends Num, Outputs ext
    * @param dt The time between updates in seconds.
    */
   public void update(double dt) {
-    // Update X. By default, this is the linear system dynamics X = Ax + Bu
+    // Update x. By default, this is the linear system dynamics xₖ₊₁ = Axₖ + Buₖ.
     m_x = updateX(m_x, m_u, dt);
 
-    // y = cx + du
+    // yₖ = Cxₖ + Duₖ
     m_y = m_plant.calculateY(m_x, m_u);
 
     // Add measurement noise.
@@ -164,6 +164,11 @@ public class LinearSystemSim<States extends Num, Inputs extends Num, Outputs ext
    */
   public void setState(Matrix<States, N1> state) {
     m_x = state;
+
+    // Update the output to reflect the new state.
+    //
+    //   yₖ = Cxₖ + Duₖ
+    m_y = m_plant.calculateY(m_x, m_u);
   }
 
   /**