[wpilib] Deprecate Accelerometer and Gyro interfaces (#5445)

Accelerometer is hyper-specific to ADXL accelerometers, and Gyro is
less useful now that 3D IMUs are prevalent, and if those IMUs want to
support the Gyro interface, they also need to provide a way to set the
axis used for the Gyro interface, which is confusing. Higher-order
functions (e.g., lambdas) are a more flexible interface boundary than
interfaces, but they didn't exist when these interfaces were
created.

wpilibc/src/main/native/include/frc/ADXL345_I2C.h

@@ -9,7 +9,6 @@
 #include <wpi/sendable/SendableHelper.h>
 
 #include "frc/I2C.h"
-#include "frc/interfaces/Accelerometer.h"
 
 namespace frc {
 
@@ -24,10 +23,11 @@ namespace frc {
  * href="https://docs.wpilib.org/en/stable/docs/yearly-overview/known-issues.html#onboard-i2c-causing-system-lockups">
  * WPILib Known Issues</a> page for details.
  */
-class ADXL345_I2C : public Accelerometer,
-                    public nt::NTSendable,
+class ADXL345_I2C : public nt::NTSendable,
                     public wpi::SendableHelper<ADXL345_I2C> {
  public:
+  enum Range { kRange_2G = 0, kRange_4G = 1, kRange_8G = 2, kRange_16G = 3 };
+
   enum Axes { kAxis_X = 0x00, kAxis_Y = 0x02, kAxis_Z = 0x04 };
 
   struct AllAxes {
@@ -53,11 +53,34 @@ class ADXL345_I2C : public Accelerometer,
   I2C::Port GetI2CPort() const;
   int GetI2CDeviceAddress() const;
 
-  // Accelerometer interface
-  void SetRange(Range range) final;
-  double GetX() override;
-  double GetY() override;
-  double GetZ() override;
+  /**
+   * Set the measuring range of the accelerometer.
+   *
+   * @param range The maximum acceleration, positive or negative, that the
+   *     accelerometer will measure.
+   */
+  void SetRange(Range range);
+
+  /**
+   * Returns the acceleration along the X axis in g-forces.
+   *
+   * @return The acceleration along the X axis in g-forces.
+   */
+  double GetX();
+
+  /**
+   * Returns the acceleration along the Y axis in g-forces.
+   *
+   * @return The acceleration along the Y axis in g-forces.
+   */
+  double GetY();
+
+  /**
+   * Returns the acceleration along the Z axis in g-forces.
+   *
+   * @return The acceleration along the Z axis in g-forces.
+   */
+  double GetZ();
 
   /**
    * Get the acceleration of one axis in Gs.

wpilibc/src/main/native/include/frc/ADXL345_SPI.h

@@ -9,7 +9,6 @@
 #include <wpi/sendable/SendableHelper.h>
 
 #include "frc/SPI.h"
-#include "frc/interfaces/Accelerometer.h"
 
 namespace frc {
 
@@ -19,10 +18,11 @@ namespace frc {
  * This class allows access to an Analog Devices ADXL345 3-axis accelerometer
  * via SPI. This class assumes the sensor is wired in 4-wire SPI mode.
  */
-class ADXL345_SPI : public Accelerometer,
-                    public nt::NTSendable,
+class ADXL345_SPI : public nt::NTSendable,
                     public wpi::SendableHelper<ADXL345_SPI> {
  public:
+  enum Range { kRange_2G = 0, kRange_4G = 1, kRange_8G = 2, kRange_16G = 3 };
+
   enum Axes { kAxis_X = 0x00, kAxis_Y = 0x02, kAxis_Z = 0x04 };
 
   struct AllAxes {
@@ -46,11 +46,34 @@ class ADXL345_SPI : public Accelerometer,
 
   SPI::Port GetSpiPort() const;
 
-  // Accelerometer interface
-  void SetRange(Range range) final;
-  double GetX() override;
-  double GetY() override;
-  double GetZ() override;
+  /**
+   * Set the measuring range of the accelerometer.
+   *
+   * @param range The maximum acceleration, positive or negative, that the
+   *     accelerometer will measure.
+   */
+  void SetRange(Range range);
+
+  /**
+   * Returns the acceleration along the X axis in g-forces.
+   *
+   * @return The acceleration along the X axis in g-forces.
+   */
+  double GetX();
+
+  /**
+   * Returns the acceleration along the Y axis in g-forces.
+   *
+   * @return The acceleration along the Y axis in g-forces.
+   */
+  double GetY();
+
+  /**
+   * Returns the acceleration along the Z axis in g-forces.
+   *
+   * @return The acceleration along the Z axis in g-forces.
+   */
+  double GetZ();
 
   /**
    * Get the acceleration of one axis in Gs.

wpilibc/src/main/native/include/frc/ADXL362.h

@@ -9,7 +9,6 @@
 #include <wpi/sendable/SendableHelper.h>
 
 #include "frc/SPI.h"
-#include "frc/interfaces/Accelerometer.h"
 
 namespace frc {
 
@@ -18,10 +17,10 @@ namespace frc {
  *
  * This class allows access to an Analog Devices ADXL362 3-axis accelerometer.
  */
-class ADXL362 : public Accelerometer,
-                public nt::NTSendable,
-                public wpi::SendableHelper<ADXL362> {
+class ADXL362 : public nt::NTSendable, public wpi::SendableHelper<ADXL362> {
  public:
+  enum Range { kRange_2G = 0, kRange_4G = 1, kRange_8G = 2 };
+
   enum Axes { kAxis_X = 0x00, kAxis_Y = 0x02, kAxis_Z = 0x04 };
   struct AllAxes {
     double XAxis;
@@ -52,11 +51,34 @@ class ADXL362 : public Accelerometer,
 
   SPI::Port GetSpiPort() const;
 
-  // Accelerometer interface
-  void SetRange(Range range) final;
-  double GetX() override;
-  double GetY() override;
-  double GetZ() override;
+  /**
+   * Set the measuring range of the accelerometer.
+   *
+   * @param range The maximum acceleration, positive or negative, that the
+   *     accelerometer will measure.
+   */
+  void SetRange(Range range);
+
+  /**
+   * Returns the acceleration along the X axis in g-forces.
+   *
+   * @return The acceleration along the X axis in g-forces.
+   */
+  double GetX();
+
+  /**
+   * Returns the acceleration along the Y axis in g-forces.
+   *
+   * @return The acceleration along the Y axis in g-forces.
+   */
+  double GetY();
+
+  /**
+   * Returns the acceleration along the Z axis in g-forces.
+   *
+   * @return The acceleration along the Z axis in g-forces.
+   */
+  double GetZ();
 
   /**
    * Get the acceleration of one axis in Gs.

wpilibc/src/main/native/include/frc/ADXRS450_Gyro.h

@@ -11,7 +11,7 @@
 #include <wpi/sendable/SendableHelper.h>
 
 #include "frc/SPI.h"
-#include "frc/interfaces/Gyro.h"
+#include "frc/geometry/Rotation2d.h"
 
 namespace frc {
 
@@ -28,8 +28,7 @@ namespace frc {
  * This class is for the digital ADXRS450 gyro sensor that connects via SPI.
  * Only one instance of an ADXRS %Gyro is supported.
  */
-class ADXRS450_Gyro : public Gyro,
-                      public wpi::Sendable,
+class ADXRS450_Gyro : public wpi::Sendable,
                       public wpi::SendableHelper<ADXRS450_Gyro> {
  public:
   /**
@@ -61,7 +60,7 @@ class ADXRS450_Gyro : public Gyro,
    *
    * @return the current heading of the robot in degrees.
    */
-  double GetAngle() const override;
+  double GetAngle() const;
 
   /**
    * Return the rate of rotation of the gyro
@@ -70,7 +69,7 @@ class ADXRS450_Gyro : public Gyro,
    *
    * @return the current rate in degrees per second
    */
-  double GetRate() const override;
+  double GetRate() const;
 
   /**
    * Reset the gyro.
@@ -79,11 +78,9 @@ class ADXRS450_Gyro : public Gyro,
    * significant drift in the gyro and it needs to be recalibrated after it has
    * been running.
    */
-  void Reset() override;
+  void Reset();
 
   /**
-   * Initialize the gyro.
-   *
    * Calibrate the gyro by running for a number of samples and computing the
    * center value. Then use the center value as the Accumulator center value for
    * subsequent measurements.
@@ -93,7 +90,22 @@ class ADXRS450_Gyro : public Gyro,
    * robot is first turned on while it's sitting at rest before the competition
    * starts.
    */
-  void Calibrate() final;
+  void Calibrate();
+
+  /**
+   * Return the heading of the robot as a Rotation2d.
+   *
+   * The angle is continuous, that is it will continue from 360 to 361 degrees.
+   * This allows algorithms that wouldn't want to see a discontinuity in the
+   * gyro output as it sweeps past from 360 to 0 on the second time around.
+   *
+   * The angle is expected to increase as the gyro turns counterclockwise when
+   * looked at from the top. It needs to follow the NWU axis convention.
+   *
+   * @return the current heading of the robot as a Rotation2d. This heading is
+   *         based on integration of the returned rate from the gyro.
+   */
+  Rotation2d GetRotation2d() const;
 
   /**
    * Get the SPI port number.

wpilibc/src/main/native/include/frc/AnalogGyro.h

@@ -10,7 +10,7 @@
 #include <wpi/sendable/Sendable.h>
 #include <wpi/sendable/SendableHelper.h>
 
-#include "frc/interfaces/Gyro.h"
+#include "frc/geometry/Rotation2d.h"
 
 namespace frc {
 
@@ -29,8 +29,7 @@ class AnalogInput;
  *
  * This class is for gyro sensors that connect to an analog input.
  */
-class AnalogGyro : public Gyro,
-                   public wpi::Sendable,
+class AnalogGyro : public wpi::Sendable,
                    public wpi::SendableHelper<AnalogGyro> {
  public:
   static constexpr int kOversampleBits = 10;
@@ -118,7 +117,7 @@ class AnalogGyro : public Gyro,
    * @return The current heading of the robot in degrees. This heading is based
    *         on integration of the returned rate from the gyro.
    */
-  double GetAngle() const override;
+  double GetAngle() const;
 
   /**
    * Return the rate of rotation of the gyro
@@ -127,7 +126,7 @@ class AnalogGyro : public Gyro,
    *
    * @return the current rate in degrees per second
    */
-  double GetRate() const override;
+  double GetRate() const;
 
   /**
    * Return the gyro center value. If run after calibration,
@@ -174,7 +173,7 @@ class AnalogGyro : public Gyro,
    * significant drift in the gyro and it needs to be recalibrated after it has
    * been running.
    */
-  void Reset() final;
+  void Reset();
 
   /**
    * Initialize the gyro.
@@ -183,7 +182,32 @@ class AnalogGyro : public Gyro,
    */
   void InitGyro();
 
-  void Calibrate() final;
+  /**
+   * Calibrate the gyro by running for a number of samples and computing the
+   * center value. Then use the center value as the Accumulator center value for
+   * subsequent measurements.
+   *
+   * It's important to make sure that the robot is not moving while the
+   * centering calculations are in progress, this is typically done when the
+   * robot is first turned on while it's sitting at rest before the competition
+   * starts.
+   */
+  void Calibrate();
+
+  /**
+   * Return the heading of the robot as a Rotation2d.
+   *
+   * The angle is continuous, that is it will continue from 360 to 361 degrees.
+   * This allows algorithms that wouldn't want to see a discontinuity in the
+   * gyro output as it sweeps past from 360 to 0 on the second time around.
+   *
+   * The angle is expected to increase as the gyro turns counterclockwise when
+   * looked at from the top. It needs to follow the NWU axis convention.
+   *
+   * @return the current heading of the robot as a Rotation2d. This heading is
+   *         based on integration of the returned rate from the gyro.
+   */
+  Rotation2d GetRotation2d() const;
 
   /**
    * Gets the analog input for the gyro.

wpilibc/src/main/native/include/frc/BuiltInAccelerometer.h

@@ -7,8 +7,6 @@
 #include <wpi/sendable/Sendable.h>
 #include <wpi/sendable/SendableHelper.h>
 
-#include "frc/interfaces/Accelerometer.h"
-
 namespace frc {
 
 /**
@@ -16,10 +14,11 @@ namespace frc {
  *
  * This class allows access to the roboRIO's internal accelerometer.
  */
-class BuiltInAccelerometer : public Accelerometer,
-                             public wpi::Sendable,
+class BuiltInAccelerometer : public wpi::Sendable,
                              public wpi::SendableHelper<BuiltInAccelerometer> {
  public:
+  enum Range { kRange_2G = 0, kRange_4G = 1, kRange_8G = 2 };
+
   /**
    * Constructor.
    *
@@ -30,30 +29,28 @@ class BuiltInAccelerometer : public Accelerometer,
   BuiltInAccelerometer(BuiltInAccelerometer&&) = default;
   BuiltInAccelerometer& operator=(BuiltInAccelerometer&&) = default;
 
-  // Accelerometer interface
   /**
    * Set the measuring range of the accelerometer.
    *
    * @param range The maximum acceleration, positive or negative, that the
-   *              accelerometer will measure. Not all accelerometers support all
-   *              ranges.
+   *     accelerometer will measure.
    */
-  void SetRange(Range range) final;
+  void SetRange(Range range);
 
   /**
    * @return The acceleration of the roboRIO along the X axis in g-forces
    */
-  double GetX() override;
+  double GetX();
 
   /**
    * @return The acceleration of the roboRIO along the Y axis in g-forces
    */
-  double GetY() override;
+  double GetY();
 
   /**
    * @return The acceleration of the roboRIO along the Z axis in g-forces
    */
-  double GetZ() override;
+  double GetZ();
 
   void InitSendable(wpi::SendableBuilder& builder) override;
 };

wpilibc/src/main/native/include/frc/interfaces/Accelerometer.h

@@ -8,8 +8,11 @@ namespace frc {
 
 /**
  * Interface for 3-axis accelerometers.
+ *
+ * @deprecated This interface is being removed with no replacement.
  */
-class Accelerometer {
+class [[deprecated(
+    "This interface is being removed with no replacement.")]] Accelerometer {
  public:
   Accelerometer() = default;
   virtual ~Accelerometer() = default;

wpilibc/src/main/native/include/frc/interfaces/Gyro.h

@@ -12,8 +12,11 @@ namespace frc {
 
 /**
  * Interface for yaw rate gyros.
+ *
+ * @deprecated This interface is being removed with no replacement.
  */
-class Gyro {
+class [[deprecated(
+    "This interface is being removed with no replacement.")]] Gyro {
  public:
   Gyro() = default;
   virtual ~Gyro() = default;