[wpimath] Replace Speeds with Velocities (#8479)

I left "free speed" alone since that's the technical term for it. In
general, velocity is a vector quantity, and speed is a magnitude (i.e.,
a strictly positive value).

This PR also replaces the speed verbiage in MotorController with duty
cycle.

Fixes #8423.

wpilibc/src/main/native/include/wpi/hardware/expansionhub/ExpansionHubMotor.hpp

@@ -29,14 +29,16 @@ class ExpansionHubMotor {
    * @param channel The motor channel
    */
   ExpansionHubMotor(int usbId, int channel);
+
   ~ExpansionHubMotor() noexcept;
 
   /**
-   * Sets the percentage power to run the motor at, between -1 and 1.
+   * Sets the duty cycle.
    *
-   * @param power The power to drive the motor at
+   * @param dutyCycle The duty cycle between -1 and 1 (sign indicates
+   *     direction).
    */
-  void SetPercentagePower(double power);
+  void SetDutyCycle(double dutyCycle);
 
   /**
    * Sets the voltage to run the motor at. This value will be continously scaled

wpilibc/src/main/native/include/wpi/hardware/led/LEDPattern.hpp

@@ -121,7 +121,7 @@ class LEDPattern {
    * long (assuming equal LED density on both segments).
    */
   [[nodiscard]]
-  LEDPattern ScrollAtRelativeSpeed(wpi::units::hertz_t velocity);
+  LEDPattern ScrollAtRelativeVelocity(wpi::units::hertz_t velocity);
 
   /**
    * Creates a pattern that plays this one scrolling up an LED strip. A negative
@@ -136,9 +136,8 @@ class LEDPattern {
    * wpi::units::meter_t{1 /60.0};
    *
    *   wpi::LEDPattern rainbow = wpi::LEDPattern::Rainbow();
-   *   wpi::LEDPattern scrollingRainbow =
-   *     rainbow.ScrollAtAbsoluteSpeed(wpi::units::feet_per_second_t{1 / 3.0},
-   * LED_SPACING);
+   *   wpi::LEDPattern scrollingRainbow = rainbow.ScrollAtAbsoluteVelocity(
+   *     wpi::units::feet_per_second_t{1 / 3.0}, LED_SPACING);
    * </pre>
    *
    * <p>Note that this pattern will scroll <i>faster</i> if applied to a less
@@ -147,12 +146,12 @@ class LEDPattern {
    *
    * @param velocity how fast the pattern should move along a physical LED strip
    * @param ledSpacing the distance between adjacent LEDs on the physical LED
-   * strip
+   *     strip
    * @return the scrolling pattern
    */
   [[nodiscard]]
-  LEDPattern ScrollAtAbsoluteSpeed(wpi::units::meters_per_second_t velocity,
-                                   wpi::units::meter_t ledSpacing);
+  LEDPattern ScrollAtAbsoluteVelocity(wpi::units::meters_per_second_t velocity,
+                                      wpi::units::meter_t ledSpacing);
 
   /**
    * Creates a pattern that switches between playing this pattern and turning
@@ -170,7 +169,7 @@ class LEDPattern {
    * "off" time is exactly equal to the "on" time.
    *
    * @param onTime how long the pattern should play for (and be turned off for),
-   * per cycle
+   *     per cycle
    * @return the blinking pattern
    */
   [[nodiscard]]
@@ -264,7 +263,7 @@ class LEDPattern {
    * </pre>
    *
    * @param relativeBrightness the multiplier to apply to all channels to modify
-   * brightness
+   *     brightness
    * @return the input pattern, displayed at
    */
   [[nodiscard]]
@@ -305,8 +304,8 @@ class LEDPattern {
    * </pre>
    *
    * @param progressFunction the function to call to determine the progress.
-   * This should return values in the range [0, 1]; any values outside that
-   * range will be clamped.
+   *     This should return values in the range [0, 1]; any values outside that
+   *     range will be clamped.
    * @return the mask pattern
    */
   static LEDPattern ProgressMaskLayer(std::function<double()> progressFunction);
@@ -320,7 +319,7 @@ class LEDPattern {
    * there's a 0 -> black step by default).
    *
    * @param steps a map of progress to the color to start displaying at that
-   * position along the LED strip
+   *     position along the LED strip
    * @return a motionless step pattern
    */
   static LEDPattern Steps(
@@ -335,7 +334,7 @@ class LEDPattern {
    * there's a 0 -> black step by default).
    *
    * @param steps a map of progress to the color to start displaying at that
-   * position along the LED strip
+   *     position along the LED strip
    * @return a motionless step pattern
    */
   static LEDPattern Steps(

wpilibc/src/main/native/include/wpi/hardware/motor/MotorController.hpp

@@ -16,49 +16,52 @@ class MotorController {
   virtual ~MotorController() = default;
 
   /**
-   * Common interface for setting the speed of a motor controller.
+   * Sets the duty cycle of the motor controller.
    *
-   * @param speed The speed to set.  Value should be between -1.0 and 1.0.
+   * @param dutyCycle The duty cycle between -1 and 1 (sign indicates
+   *     direction).
    */
-  virtual void Set(double speed) = 0;
+  virtual void SetDutyCycle(double dutyCycle) = 0;
 
   /**
-   * Sets the voltage output of the MotorController.  Compensates for
-   * the current bus voltage to ensure that the desired voltage is output even
-   * if the battery voltage is below 12V - highly useful when the voltage
-   * outputs are "meaningful" (e.g. they come from a feedforward calculation).
+   * Sets the voltage output of the motor controller.
    *
-   * <p>NOTE: This function *must* be called regularly in order for voltage
+   * Compensates for the current bus voltage to ensure that the desired voltage
+   * is output even if the battery voltage is below 12V - highly useful when the
+   * voltage outputs are "meaningful" (e.g. they come from a feedforward
+   * calculation).
+   *
+   * NOTE: This function *must* be called regularly in order for voltage
    * compensation to work properly - unlike the ordinary set function, it is not
    * "set it and forget it."
    *
-   * @param output The voltage to output.
+   * @param voltage The voltage.
    */
-  virtual void SetVoltage(wpi::units::volt_t output);
+  virtual void SetVoltage(wpi::units::volt_t voltage);
 
   /**
-   * Common interface for getting the current set speed of a motor controller.
+   * Gets the duty cycle of the motor controller.
    *
-   * @return The current set speed.  Value is between -1.0 and 1.0.
+   * @return The duty cycle between -1 and 1 (sign indicates direction).
    */
-  virtual double Get() const = 0;
+  virtual double GetDutyCycle() const = 0;
 
   /**
-   * Common interface for inverting direction of a motor controller.
+   * Sets the inversion state of the motor controller.
    *
-   * @param isInverted The state of inversion, true is inverted.
+   * @param isInverted The inversion state.
    */
   virtual void SetInverted(bool isInverted) = 0;
 
   /**
-   * Common interface for returning the inversion state of a motor controller.
+   * Gets the inversion state of the motor controller.
    *
-   * @return isInverted The state of inversion, true is inverted.
+   * @return The inversion state.
    */
   virtual bool GetInverted() const = 0;
 
   /**
-   * Common interface for disabling a motor.
+   * Disables the motor controller.
    */
   virtual void Disable() = 0;
 };

wpilibc/src/main/native/include/wpi/hardware/motor/PWMMotorController.hpp

@@ -37,45 +37,16 @@ class PWMMotorController
   PWMMotorController(PWMMotorController&&) = default;
   PWMMotorController& operator=(PWMMotorController&&) = default;
 
-  /**
-   * Set the PWM value.
-   *
-   * The PWM value is set using a range of -1.0 to 1.0, appropriately scaling
-   * the value for the FPGA.
-   *
-   * @param value The speed value between -1.0 and 1.0 to set.
-   */
-  void Set(double value) override;
+  void SetDutyCycle(double dutyCycle) override;
 
-  /**
-   * Sets the voltage output of the PWMMotorController. Compensates for
-   * the current bus voltage to ensure that the desired voltage is output even
-   * if the battery voltage is below 12V - highly useful when the voltage
-   * outputs are "meaningful" (e.g. they come from a feedforward calculation).
-   *
-   * <p>NOTE: This function *must* be called regularly in order for voltage
-   * compensation to work properly - unlike the ordinary set function, it is not
-   * "set it and forget it."
-   *
-   * @param output The voltage to output.
-   */
-  void SetVoltage(wpi::units::volt_t output) override;
-
-  /**
-   * Get the recently set value of the PWM. This value is affected by the
-   * inversion property. If you want the value that is sent directly to the
-   * MotorController, use PWM::GetSpeed() instead.
-   *
-   * @return The most recently set value for the PWM between -1.0 and 1.0.
-   */
-  double Get() const override;
+  double GetDutyCycle() const override;
 
   /**
    * Gets the voltage output of the motor controller, nominally between -12 V
    * and 12 V.
    *
    * @return The voltage of the motor controller, nominally between -12 V and 12
-   *   V.
+   *     V.
    */
   virtual wpi::units::volt_t GetVoltage() const;
 
@@ -134,8 +105,8 @@ class PWMMotorController
   /// PWM instances for motor controller.
   PWM m_pwm;
 
-  void SetSpeed(double speed);
-  double GetSpeed() const;
+  void SetDutyCycleInternal(double dutyCycle);
+  double GetDutyCycleInternal() const;
 
   void SetBounds(wpi::units::microsecond_t maxPwm,
                  wpi::units::microsecond_t deadbandMaxPwm,
@@ -149,7 +120,7 @@ class PWMMotorController
   std::vector<std::unique_ptr<PWMMotorController>> m_owningFollowers;
 
   wpi::hal::SimDevice m_simDevice;
-  wpi::hal::SimDouble m_simSpeed;
+  wpi::hal::SimDouble m_simDutyCycle;
 
   bool m_eliminateDeadband{0};
   wpi::units::microsecond_t m_minPwm{0};