[wpilib,cmd] Cache HID wrappers (#8970)

Store DriverStation-owned GenericHID and Gamepad instances in Java and
C++, and expose the cached objects to Python bindings.

Move hand-written command gamepad and joystick wrappers to compose
cached CommandGenericHID instances plus typed HID wrappers, including a
Python CommandGamepad.

This will let us remove UserControls, while helping ensure that we don't
have state smashing between GenericHID objects.

Another bonus is without inheritance, intellisense will no longer show a
bunch of annoying methods, and instead just what actually exists.

---------

Co-authored-by: Peter Johnson <johnson.peter@gmail.com>

wpilibj/src/main/java/org/wpilib/driverstation/DriverStation.java

@@ -4,6 +4,8 @@
 
 package org.wpilib.driverstation;
 
+import java.util.concurrent.locks.Lock;
+import java.util.concurrent.locks.ReentrantLock;
 import org.wpilib.datalog.DataLog;
 import org.wpilib.driverstation.internal.DriverStationBackend;
 
@@ -11,6 +13,56 @@ import org.wpilib.driverstation.internal.DriverStationBackend;
 public final class DriverStation {
   private DriverStation() {}
 
+  private static final Lock m_dsLock = new ReentrantLock();
+  private static final GenericHID[] m_hids = new GenericHID[DriverStationBackend.JOYSTICK_PORTS];
+  private static final Gamepad[] m_gamepads = new Gamepad[DriverStationBackend.JOYSTICK_PORTS];
+
+  private static GenericHID getGenericHIDUnderLock(int port) {
+    GenericHID toRet = m_hids[port];
+    if (toRet == null) {
+      toRet = new GenericHID(port);
+      m_hids[port] = toRet;
+    }
+    return toRet;
+  }
+
+  /**
+   * Gets the GenericHID object for the given port. GenericHID objects are cached, so this will
+   * always return the same object for the same port.
+   *
+   * @param port The port index on the Driver Station that the controller is plugged into (0-5).
+   * @return The GenericHID object for the given port.
+   */
+  public static GenericHID getGenericHID(int port) {
+    m_dsLock.lock();
+    try {
+      return getGenericHIDUnderLock(port);
+    } finally {
+      m_dsLock.unlock();
+    }
+  }
+
+  /**
+   * Gets the Gamepad object for the given port. Gamepad objects are cached, so this will always
+   * return the same object for the same port.
+   *
+   * @param port The port index on the Driver Station that the controller is plugged into (0-5).
+   * @return The Gamepad object for the given port.
+   */
+  public static Gamepad getGamepad(int port) {
+    m_dsLock.lock();
+    try {
+      Gamepad toRet = m_gamepads[port];
+      if (toRet == null) {
+        toRet = new Gamepad(getGenericHIDUnderLock(port));
+        m_gamepads[port] = toRet;
+      }
+      return toRet;
+    } finally {
+      m_dsLock.unlock();
+    }
+  }
+
   /**
    * Starts logging DriverStation data to data log, including joystick data. Repeated calls are
    * ignored.

wpilibj/src/main/java/org/wpilib/driverstation/Gamepad.java

@@ -4,6 +4,11 @@
 
 package org.wpilib.driverstation;
 
+import java.util.EnumSet;
+import java.util.Objects;
+import org.wpilib.driverstation.GenericHID.HIDType;
+import org.wpilib.driverstation.GenericHID.RumbleType;
+import org.wpilib.driverstation.GenericHID.SupportedOutput;
 import org.wpilib.driverstation.internal.DriverStationBackend;
 import org.wpilib.event.BooleanEvent;
 import org.wpilib.event.EventLoop;
@@ -18,12 +23,8 @@ import org.wpilib.util.sendable.SendableBuilder;
  * <p>This class handles Gamepad input that comes from the Driver Station. Each time a value is
  * requested the most recent value is returned. There is a single class instance for each controller
  * and the mapping of ports to hardware buttons depends on the code in the Driver Station.
- *
- * <p>Only first party controllers from Generic are guaranteed to have the correct mapping, and only
- * through the official NI DS. Sim is not guaranteed to have the same mapping, as well as any 3rd
- * party controllers.
  */
-public class Gamepad extends GenericHID implements Sendable {
+public class Gamepad implements HIDDevice, Sendable {
   private static final double MAX_DEADBAND = Math.nextDown(1.0);
 
   /** Represents a digital button on a Gamepad. */
@@ -156,14 +157,35 @@ public class Gamepad extends GenericHID implements Sendable {
     return Math.clamp(deadband, 0.0, MAX_DEADBAND);
   }
 
+  private final GenericHID m_hid;
+
   /**
-   * Construct an instance of a controller.
+   * Get the underlying GenericHID object.
    *
-   * @param port The port index on the Driver Station that the controller is plugged into (0-5).
+   * @return the wrapped GenericHID object
+   */
+  @Override
+  public GenericHID getHID() {
+    return m_hid;
+  }
+
+  /**
+   * Construct an instance of a gamepad.
+   *
+   * @param port The port index on the Driver Station that the gamepad is plugged into (0-5).
    */
   public Gamepad(final int port) {
-    super(port);
-    HAL.reportUsage("HID", port, "Gamepad");
+    this(DriverStation.getGenericHID(port));
+  }
+
+  /**
+   * Construct an instance of a gamepad with a GenericHID object.
+   *
+   * @param hid The GenericHID object to use for this gamepad.
+   */
+  public Gamepad(final GenericHID hid) {
+    m_hid = Objects.requireNonNull(hid, "Provided HID object cannot be null");
+    HAL.reportUsage("HID", hid.getPort(), "Gamepad");
   }
 
   /**
@@ -1350,7 +1372,7 @@ public class Gamepad extends GenericHID implements Sendable {
    * @return The state of the button.
    */
   public boolean getButton(Button button) {
-    return getRawButton(button.value);
+    return m_hid.getRawButton(button.value);
   }
 
   /**
@@ -1364,7 +1386,7 @@ public class Gamepad extends GenericHID implements Sendable {
    * @return Whether the button was pressed since the last check.
    */
   public boolean getButtonPressed(Button button) {
-    return getRawButtonPressed(button.value);
+    return m_hid.getRawButtonPressed(button.value);
   }
 
   /**
@@ -1378,7 +1400,7 @@ public class Gamepad extends GenericHID implements Sendable {
    * @return Whether the button was released since the last check.
    */
   public boolean getButtonReleased(Button button) {
-    return getRawButtonReleased(button.value);
+    return m_hid.getRawButtonReleased(button.value);
   }
 
   /**
@@ -1389,7 +1411,7 @@ public class Gamepad extends GenericHID implements Sendable {
    * @return an event instance representing the button's digital signal attached to the given loop.
    */
   public BooleanEvent button(Button button, EventLoop loop) {
-    return super.button(button.value, loop);
+    return m_hid.button(button.value, loop);
   }
 
   /**
@@ -1399,7 +1421,7 @@ public class Gamepad extends GenericHID implements Sendable {
    * @return The value of the axis.
    */
   public double getAxis(Axis axis) {
-    return getRawAxis(axis.value);
+    return m_hid.getRawAxis(axis.value);
   }
 
   /**
@@ -1412,7 +1434,7 @@ public class Gamepad extends GenericHID implements Sendable {
    * @return an event instance that is true when the axis value is less than the provided threshold.
    */
   public BooleanEvent axisLessThan(Axis axis, double threshold, EventLoop loop) {
-    return super.axisLessThan(axis.value, threshold, loop);
+    return m_hid.axisLessThan(axis.value, threshold, loop);
   }
 
   /**
@@ -1426,15 +1448,115 @@ public class Gamepad extends GenericHID implements Sendable {
    *     threshold.
    */
   public BooleanEvent axisGreaterThan(Axis axis, double threshold, EventLoop loop) {
-    return super.axisGreaterThan(axis.value, threshold, loop);
+    return m_hid.axisGreaterThan(axis.value, threshold, loop);
+  }
+
+  /**
+   * Get the bitmask of axes for the gamepad.
+   *
+   * @return the number of axis for the current gamepad
+   */
+  public int getAxesAvailable() {
+    return m_hid.getAxesAvailable();
+  }
+
+  /**
+   * For the current gamepad, return the bitmask of available buttons.
+   *
+   * @return the bitmask of buttons for the current gamepad
+   */
+  public long getButtonsAvailable() {
+    return m_hid.getButtonsAvailable();
+  }
+
+  /**
+   * Get if the gamepad is connected.
+   *
+   * @return true if the gamepad is connected
+   */
+  public boolean isConnected() {
+    return m_hid.isConnected();
+  }
+
+  /**
+   * Get the type of the gamepad.
+   *
+   * @return the type of the gamepad.
+   */
+  public HIDType getGamepadType() {
+    return m_hid.getGamepadType();
+  }
+
+  /**
+   * Get the supported outputs for the gamepad.
+   *
+   * @return the supported outputs for the gamepad.
+   */
+  public EnumSet<SupportedOutput> getSupportedOutputs() {
+    return m_hid.getSupportedOutputs();
+  }
+
+  /**
+   * Get the name of the gamepad.
+   *
+   * @return the name of the gamepad.
+   */
+  public String getName() {
+    return m_hid.getName();
+  }
+
+  /**
+   * Set leds on the gamepad. If only mono is supported, the system will use the highest value
+   * passed in.
+   *
+   * @param r Red value from 0-255
+   * @param g Green value from 0-255
+   * @param b Blue value from 0-255
+   */
+  public void setLeds(int r, int g, int b) {
+    m_hid.setLeds(r, g, b);
+  }
+
+  /**
+   * Set the rumble output for the HID. The DS currently supports 4 rumble values: left rumble,
+   * right rumble, left trigger rumble, and right trigger rumble.
+   *
+   * @param type Which rumble value to set
+   * @param value The normalized value (0 to 1) to set the rumble to
+   */
+  public void setRumble(RumbleType type, double value) {
+    m_hid.setRumble(type, value);
+  }
+
+  /**
+   * Check if a touchpad finger is available.
+   *
+   * @param touchpad The touchpad to check.
+   * @param finger The finger to check.
+   * @return true if the touchpad finger is available.
+   */
+  public boolean getTouchpadFingerAvailable(int touchpad, int finger) {
+    return m_hid.getTouchpadFingerAvailable(touchpad, finger);
+  }
+
+  /**
+   * Get the touchpad finger data.
+   *
+   * @param touchpad The touchpad to read.
+   * @param finger The finger to read.
+   * @return The touchpad finger data.
+   */
+  public TouchpadFinger getTouchpadFinger(int touchpad, int finger) {
+    return m_hid.getTouchpadFinger(touchpad, finger);
   }
 
   private double getAxisForSendable(Axis axis) {
-    return DriverStationBackend.getStickAxisIfAvailable(getPort(), axis.value).orElse(0.0);
+    return DriverStationBackend.getStickAxisIfAvailable(m_hid.getPort(), axis.value).orElse(0.0);
   }
 
   private boolean getButtonForSendable(Button button) {
-    return DriverStationBackend.getStickButtonIfAvailable(getPort(), button.value).orElse(false);
+    return DriverStationBackend.getStickButtonIfAvailable(m_hid.getPort(), button.value)
+        .orElse(false);
   }
 
   @Override

wpilibj/src/main/java/org/wpilib/driverstation/GenericHID.java

@@ -20,7 +20,7 @@ import org.wpilib.math.util.Pair;
  * requested the most recent value is returned. There is a single class instance for each device and
  * the mapping of ports to hardware buttons depends on the code in the Driver Station.
  */
-public class GenericHID {
+public final class GenericHID implements HIDDevice {
   /** Represents a rumble output on the Joystick. */
   public enum RumbleType {
     /** Left rumble motor. */
@@ -132,10 +132,20 @@ public class GenericHID {
    *
    * @param port The port index on the Driver Station that the device is plugged into.
    */
-  public GenericHID(int port) {
+  GenericHID(int port) {
     m_port = port;
   }
 
+  /**
+   * Get this GenericHID object.
+   *
+   * @return this GenericHID object
+   */
+  @Override
+  public GenericHID getHID() {
+    return this;
+  }
+
   /**
    * Get the button value (starting at button 1).
    *

wpilibj/src/main/java/org/wpilib/driverstation/HIDDevice.java

@@ -0,0 +1,16 @@
+// Copyright (c) FIRST and other WPILib contributors.
+// Open Source Software; you can modify and/or share it under the terms of
+// the WPILib BSD license file in the root directory of this project.
+
+package org.wpilib.driverstation;
+
+/** Interface for device wrappers backed by a GenericHID. */
+@SuppressWarnings("PMD.ImplicitFunctionalInterface")
+public interface HIDDevice {
+  /**
+   * Get the underlying GenericHID object.
+   *
+   * @return the wrapped GenericHID object
+   */
+  GenericHID getHID();
+}

wpilibj/src/main/java/org/wpilib/driverstation/Joystick.java

@@ -4,6 +4,7 @@
 
 package org.wpilib.driverstation;
 
+import java.util.Objects;
 import org.wpilib.event.BooleanEvent;
 import org.wpilib.event.EventLoop;
 import org.wpilib.hardware.hal.HAL;
@@ -15,7 +16,7 @@ import org.wpilib.hardware.hal.HAL;
  * requested the most recent value is returned. There is a single class instance for each joystick
  * and the mapping of ports to hardware buttons depends on the code in the Driver Station.
  */
-public class Joystick extends GenericHID {
+public class Joystick implements HIDDevice {
   /** Default X axis channel. */
   public static final byte kDefaultXChannel = 0;
 
@@ -69,21 +70,41 @@ public class Joystick extends GenericHID {
 
   private final byte[] m_axes = new byte[AxisType.values().length];
 
+  private final GenericHID m_hid;
+
+  /**
+   * Get the underlying GenericHID object.
+   *
+   * @return the wrapped GenericHID object
+   */
+  @Override
+  public GenericHID getHID() {
+    return m_hid;
+  }
+
   /**
    * Construct an instance of a joystick.
    *
    * @param port The port index on the Driver Station that the joystick is plugged into.
    */
   public Joystick(final int port) {
-    super(port);
+    this(DriverStation.getGenericHID(port));
+  }
 
+  /**
+   * Construct an instance of a joystick with a GenericHID object.
+   *
+   * @param hid The GenericHID object to use for this joystick.
+   */
+  public Joystick(final GenericHID hid) {
+    m_hid = Objects.requireNonNull(hid, "Provided HID object cannot be null");
     m_axes[AxisType.kX.value] = kDefaultXChannel;
     m_axes[AxisType.kY.value] = kDefaultYChannel;
     m_axes[AxisType.kZ.value] = kDefaultZChannel;
     m_axes[AxisType.kTwist.value] = kDefaultTwistChannel;
     m_axes[AxisType.kThrottle.value] = kDefaultThrottleChannel;
 
-    HAL.reportUsage("HID", port, "Joystick");
+    HAL.reportUsage("HID", hid.getPort(), "Joystick");
   }
 
   /**
@@ -176,6 +197,74 @@ public class Joystick extends GenericHID {
     return m_axes[AxisType.kThrottle.value];
   }
 
+  /**
+   * Get the button value (starting at button 1).
+   *
+   * <p>The buttons are returned in a single 16 bit value with one bit representing the state of
+   * each button. The appropriate button is returned as a boolean value.
+   *
+   * @param button The button number to be read (starting at 1)
+   * @return The state of the button
+   */
+  public boolean getRawButton(int button) {
+    return m_hid.getRawButton(button);
+  }
+
+  /**
+   * Whether the button was pressed since the last check. Button indexes begin at 1.
+   *
+   * @param button The button index, beginning at 1.
+   * @return Whether the button was pressed since the last check.
+   */
+  public boolean getRawButtonPressed(int button) {
+    return m_hid.getRawButtonPressed(button);
+  }
+
+  /**
+   * Whether the button was released since the last check. Button indexes begin at 1.
+   *
+   * @param button The button index, beginning at 1.
+   * @return Whether the button was released since the last check.
+   */
+  public boolean getRawButtonReleased(int button) {
+    return m_hid.getRawButtonReleased(button);
+  }
+
+  /**
+   * Get the value of the axis.
+   *
+   * @param axis The axis to read, starting at 0.
+   * @return The value of the axis.
+   */
+  public double getRawAxis(int axis) {
+    return m_hid.getRawAxis(axis);
+  }
+
+  /**
+   * Get the angle in degrees of a POV on the HID.
+   *
+   * <p>The POV angles start at 0 in the up direction, and increase clockwise (e.g. right is 90,
+   * upper-left is 315).
+   *
+   * @param pov The index of the POV to read, starting at 0.
+   * @return the angle of the POV
+   */
+  public POVDirection getPOV(int pov) {
+    return m_hid.getPOV(pov);
+  }
+
+  /**
+   * Get the angle in degrees of the default POV on the HID.
+   *
+   * <p>The POV angles start at 0 in the up direction, and increase clockwise (e.g. right is 90,
+   * upper-left is 315).
+   *
+   * @return the angle of the POV
+   */
+  public POVDirection getPOV() {
+    return m_hid.getPOV();
+  }
+
   /**
    * Get the X value of the joystick. This depends on the mapping of the joystick connected to the
    * current port. On most joysticks, positive is to the right.
@@ -183,7 +272,7 @@ public class Joystick extends GenericHID {
    * @return The X value of the joystick.
    */
   public final double getX() {
-    return getRawAxis(m_axes[AxisType.kX.value]);
+    return m_hid.getRawAxis(m_axes[AxisType.kX.value]);
   }
 
   /**
@@ -193,7 +282,7 @@ public class Joystick extends GenericHID {
    * @return The Y value of the joystick.
    */
   public final double getY() {
-    return getRawAxis(m_axes[AxisType.kY.value]);
+    return m_hid.getRawAxis(m_axes[AxisType.kY.value]);
   }
 
   /**
@@ -202,7 +291,7 @@ public class Joystick extends GenericHID {
    * @return the z position
    */
   public final double getZ() {
-    return getRawAxis(m_axes[AxisType.kZ.value]);
+    return m_hid.getRawAxis(m_axes[AxisType.kZ.value]);
   }
 
   /**
@@ -212,7 +301,7 @@ public class Joystick extends GenericHID {
    * @return The Twist value of the joystick.
    */
   public final double getTwist() {
-    return getRawAxis(m_axes[AxisType.kTwist.value]);
+    return m_hid.getRawAxis(m_axes[AxisType.kTwist.value]);
   }
 
   /**
@@ -222,7 +311,7 @@ public class Joystick extends GenericHID {
    * @return The Throttle value of the joystick.
    */
   public final double getThrottle() {
-    return getRawAxis(m_axes[AxisType.kThrottle.value]);
+    return m_hid.getRawAxis(m_axes[AxisType.kThrottle.value]);
   }
 
   /**
@@ -231,7 +320,7 @@ public class Joystick extends GenericHID {
    * @return The state of the trigger.
    */
   public boolean getTrigger() {
-    return getRawButton(ButtonType.kTrigger.value);
+    return m_hid.getRawButton(ButtonType.kTrigger.value);
   }
 
   /**
@@ -240,7 +329,7 @@ public class Joystick extends GenericHID {
    * @return Whether the button was pressed since the last check.
    */
   public boolean getTriggerPressed() {
-    return getRawButtonPressed(ButtonType.kTrigger.value);
+    return m_hid.getRawButtonPressed(ButtonType.kTrigger.value);
   }
 
   /**
@@ -249,7 +338,7 @@ public class Joystick extends GenericHID {
    * @return Whether the button was released since the last check.
    */
   public boolean getTriggerReleased() {
-    return getRawButtonReleased(ButtonType.kTrigger.value);
+    return m_hid.getRawButtonReleased(ButtonType.kTrigger.value);
   }
 
   /**
@@ -260,7 +349,7 @@ public class Joystick extends GenericHID {
    *     given loop.
    */
   public BooleanEvent trigger(EventLoop loop) {
-    return button(ButtonType.kTrigger.value, loop);
+    return m_hid.button(ButtonType.kTrigger.value, loop);
   }
 
   /**
@@ -269,7 +358,7 @@ public class Joystick extends GenericHID {
    * @return The state of the top button.
    */
   public boolean getTop() {
-    return getRawButton(ButtonType.kTop.value);
+    return m_hid.getRawButton(ButtonType.kTop.value);
   }
 
   /**
@@ -278,7 +367,7 @@ public class Joystick extends GenericHID {
    * @return Whether the button was pressed since the last check.
    */
   public boolean getTopPressed() {
-    return getRawButtonPressed(ButtonType.kTop.value);
+    return m_hid.getRawButtonPressed(ButtonType.kTop.value);
   }
 
   /**
@@ -287,7 +376,7 @@ public class Joystick extends GenericHID {
    * @return Whether the button was released since the last check.
    */
   public boolean getTopReleased() {
-    return getRawButtonReleased(ButtonType.kTop.value);
+    return m_hid.getRawButtonReleased(ButtonType.kTop.value);
   }
 
   /**
@@ -298,7 +387,7 @@ public class Joystick extends GenericHID {
    *     loop.
    */
   public BooleanEvent top(EventLoop loop) {
-    return button(ButtonType.kTop.value, loop);
+    return m_hid.button(ButtonType.kTop.value, loop);
   }
 
   /**