com.qualcomm.robotcore.hardware

## Interface DcMotorEx

- All Superinterfaces:
    DcMotor, DcMotorSimple, HardwareDevice
  All Known Implementing Classes:
    DcMotorImplEx

      public interface DcMotorEx
      extends DcMotor

  The DcMotorEx interface provides enhanced motor functionality which is available with some hardware devices. The DcMotorEx interface is typically used as a second interface on an object whose primary interface is DcMotor. To access it, cast your DcMotor object to DcMotorEx. However, it is perhaps prudent to first test whether the cast will succeed by testing using 'instanceof'.
  See Also:
    `PwmControl`

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface com.qualcomm.robotcore.hardware.DcMotor

      `DcMotor.RunMode, DcMotor.ZeroPowerBehavior`

    - ### Nested classes/interfaces inherited from interface com.qualcomm.robotcore.hardware.DcMotorSimple

      `DcMotorSimple.Direction`

    - ### Nested classes/interfaces inherited from interface com.qualcomm.robotcore.hardware.HardwareDevice

      `HardwareDevice.Manufacturer`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `PIDCoefficients` | `getPIDCoefficients(DcMotor.RunMode mode)` Deprecated. Use `#getPIDFCoefficients(RunMode)` instead
    `PIDFCoefficients` | `getPIDFCoefficients(DcMotor.RunMode mode)` Returns the PIDF control coefficients used when running in the indicated mode on this motor.
    `int` | `getTargetPositionTolerance()` Returns the current target positioning tolerance of this motor
    `double` | `getVelocity()` Returns the current velocity of the motor, in ticks per second
    `double` | `getVelocity(AngleUnit unit)` Returns the current velocity of the motor, in angular units per second
    `boolean` | `isMotorEnabled()` Returns whether this motor is energized
    `void` | `setMotorDisable()` Individually de-energizes this particular motor
    `void` | `setMotorEnable()` Individually energizes this particular motor
    `void` | `setPIDCoefficients(DcMotor.RunMode mode, PIDCoefficients pidCoefficients)` Deprecated. Use `#setPIDFCoefficients(RunMode, PIDFCoefficients)` instead
    `void` | `setPIDFCoefficients(DcMotor.RunMode mode, PIDFCoefficients pidfCoefficients)` `setPIDFCoefficients(com.qualcomm.robotcore.hardware.DcMotor.RunMode, com.qualcomm.robotcore.hardware.PIDFCoefficients)` is a superset enhancement to `setPIDCoefficients(com.qualcomm.robotcore.hardware.DcMotor.RunMode, com.qualcomm.robotcore.hardware.PIDCoefficients)`.
    `void` | `setPositionPIDFCoefficients(double p)` A shorthand for setting the PIDF coefficients for the `DcMotor.RunMode.RUN_TO_POSITION` mode.
    `void` | `setTargetPositionTolerance(int tolerance)` Sets the target positioning tolerance of this motor
    `void` | `setVelocity(double angularRate)` Sets the velocity of the motor
    `void` | `setVelocity(double angularRate, AngleUnit unit)` Sets the velocity of the motor
    `void` | `setVelocityPIDFCoefficients(double p, double i, double d, double f)` A shorthand for setting the PIDF coefficients for the `DcMotor.RunMode.RUN_USING_ENCODER` mode.

    - ### Methods inherited from interface com.qualcomm.robotcore.hardware.DcMotor

      `getController, getCurrentPosition, getMode, getMotorType, getPortNumber, getPowerFloat, getTargetPosition, getZeroPowerBehavior, isBusy, setMode, setMotorType, setPowerFloat, setTargetPosition, setZeroPowerBehavior`

    - ### Methods inherited from interface com.qualcomm.robotcore.hardware.DcMotorSimple

      `getDirection, getPower, setDirection, setPower`

    - ### Methods inherited from interface com.qualcomm.robotcore.hardware.HardwareDevice

      `close, getConnectionInfo, getDeviceName, getManufacturer, getVersion, resetDeviceConfigurationForOpMode`

- - ### Method Detail

    - #### setMotorEnable

          void setMotorEnable()

      Individually energizes this particular motor
      See Also:
        `setMotorDisable()`, `isMotorEnabled()`

    - #### setMotorDisable

          void setMotorDisable()

      Individually de-energizes this particular motor
      See Also:
        `setMotorEnable()`, `isMotorEnabled()`

    - #### isMotorEnabled

          boolean isMotorEnabled()

      Returns whether this motor is energized
      See Also:
        `setMotorEnable()`, `setMotorDisable()`

    - #### setVelocity

          void setVelocity(double angularRate)

      Sets the velocity of the motor
      Parameters:
        `angularRate` - the desired ticks per second

    - #### setVelocity

          void setVelocity(double angularRate,
                           AngleUnit unit)

      Sets the velocity of the motor
      Parameters:
        `angularRate` - the desired angular rate, in units per second
        `unit` - the units in which angularRate is expressed
      See Also:
        `getVelocity(AngleUnit)`

    - #### getVelocity

          double getVelocity()

      Returns the current velocity of the motor, in ticks per second
      Returns:
        the current velocity of the motor

    - #### getVelocity

          double getVelocity(AngleUnit unit)

      Returns the current velocity of the motor, in angular units per second
      Parameters:
        `unit` - the units in which the angular rate is desired
      Returns:
        the current velocity of the motor
      See Also:
        `setVelocity(double, AngleUnit)`

    - #### setPIDCoefficients

          @Deprecated
          void setPIDCoefficients(DcMotor.RunMode mode,
                                              PIDCoefficients pidCoefficients)

      Deprecated. Use `#setPIDFCoefficients(RunMode, PIDFCoefficients)` instead
      Sets the PID control coefficients for one of the PID modes of this motor. Note that in some controller implementations, setting the PID coefficients for one mode on a motor might affect other modes on that motor, or might affect the PID coefficients used by other motors on the same controller (this is not true on the REV Expansion Hub).
      Parameters:
        `mode` - either `RunMode#RUN_USING_ENCODER` or `RunMode#RUN_TO_POSITION`
        `pidCoefficients` - the new coefficients to use when in that mode on this motor
      See Also:
        `#getPIDCoefficients(RunMode)`

    - #### setPIDFCoefficients

          void setPIDFCoefficients(DcMotor.RunMode mode,
                                   PIDFCoefficients pidfCoefficients)
                            throws java.lang.UnsupportedOperationException

      `setPIDFCoefficients(com.qualcomm.robotcore.hardware.DcMotor.RunMode, com.qualcomm.robotcore.hardware.PIDFCoefficients)` is a superset enhancement to `setPIDCoefficients(com.qualcomm.robotcore.hardware.DcMotor.RunMode, com.qualcomm.robotcore.hardware.PIDCoefficients)`. In addition to the proportional, integral, and derivative coefficients previously supported, a feed-forward coefficient may also be specified. Further, a selection of motor control algorithms is offered: the originally-shipped Legacy PID algorithm, and a PIDF algorithm which avails itself of the feed-forward coefficient. Note that the feed-forward coefficient is not used by the Legacy PID algorithm; thus, the feed-forward coefficient must be indicated as zero if the Legacy PID algorithm is used. Also: the internal implementation of these algorithms may be different: it is not the case that the use of PIDF with the F term as zero necessarily exhibits exactly the same behavior as the use of the LegacyPID algorithm, though in practice they will be quite close. Readers are reminded that `DcMotor.RunMode.RUN_TO_POSITION` mode makes use of both the coefficients set for RUN_TO_POSITION and the coefficients set for RUN_WITH_ENCODER, due to the fact that internally the RUN_TO_POSITION logic calculates an on-the-fly velocity goal on each control cycle, then (logically) runs the RUN_WITH_ENCODER logic. Because of that double- layering, only the proportional ('p') coefficient makes logical sense for use in the RUN_TO_POSITION coefficients.
      Throws:
        `java.lang.UnsupportedOperationException`
      See Also:
        `setVelocityPIDFCoefficients(double, double, double, double)`, `setPositionPIDFCoefficients(double)`, `#getPIDFCoefficients(RunMode)`

    - #### setVelocityPIDFCoefficients

          void setVelocityPIDFCoefficients(double p,
                                           double i,
                                           double d,
                                           double f)

      A shorthand for setting the PIDF coefficients for the `DcMotor.RunMode.RUN_USING_ENCODER` mode. `MotorControlAlgorithm.PIDF` is used.
      See Also:
        `#setPIDFCoefficients(RunMode, PIDFCoefficients)`

    - #### setPositionPIDFCoefficients

          void setPositionPIDFCoefficients(double p)

      A shorthand for setting the PIDF coefficients for the `DcMotor.RunMode.RUN_TO_POSITION` mode. `MotorControlAlgorithm.PIDF` is used. Readers are reminded that `DcMotor.RunMode.RUN_TO_POSITION` mode makes use of both the coefficients set for RUN_TO_POSITION and the coefficients set for RUN_WITH_ENCODER, due to the fact that internally the RUN_TO_POSITION logic calculates an on-the-fly velocity goal on each control cycle, then (logically) runs the RUN_WITH_ENCODER logic. Because of that double- layering, only the proportional ('p') coefficient makes logical sense for use in the RUN_TO_POSITION coefficients.
      See Also:
        `setVelocityPIDFCoefficients(double, double, double, double)`, `#setPIDFCoefficients(RunMode, PIDFCoefficients)`

    - #### getPIDCoefficients

          @Deprecated
          PIDCoefficients getPIDCoefficients(DcMotor.RunMode mode)

      Deprecated. Use `#getPIDFCoefficients(RunMode)` instead
      Returns the PID control coefficients used when running in the indicated mode on this motor.
      Parameters:
        `mode` - either `RunMode#RUN_USING_ENCODER` or `RunMode#RUN_TO_POSITION`
      Returns:
        the PID control coefficients used when running in the indicated mode on this motor

    - #### getPIDFCoefficients

          PIDFCoefficients getPIDFCoefficients(DcMotor.RunMode mode)

      Returns the PIDF control coefficients used when running in the indicated mode on this motor.
      Parameters:
        `mode` - either `RunMode#RUN_USING_ENCODER` or `RunMode#RUN_TO_POSITION`
      Returns:
        the PIDF control coefficients used when running in the indicated mode on this motor
      See Also:
        `#setPIDFCoefficients(RunMode, PIDFCoefficients)`

    - #### setTargetPositionTolerance

          void setTargetPositionTolerance(int tolerance)

      Sets the target positioning tolerance of this motor
      Parameters:
        `tolerance` - the desired tolerance, in encoder ticks
      See Also:
        `DcMotor.setTargetPosition(int)`

    - #### getTargetPositionTolerance

          int getTargetPositionTolerance()

      Returns the current target positioning tolerance of this motor
      Returns:
        the current target positioning tolerance of this motor