Package trclib.motor

Class TrcMotor

java.lang.Object
trclib.motor.TrcMotor
All Implemented Interfaces:
TrcMotorController, TrcExclusiveSubsystem, TrcOdometrySensor
Direct Known Subclasses:
FrcCANPhoenix5Controller, FrcCANPhoenix6Controller, FrcCANSparkMax, FrcCRServo, FrcPWMMotorController
public abstract class TrcMotor extends Object implements TrcMotorController, TrcExclusiveSubsystem, TrcOdometrySensor
This class implements a platform independent generic motor controller. Typically, this class is extended by a platform dependent motor controller class. Not all motor controllers are created equal. Some have more features than the others. This class attempts to simulate some of the features in software. If the platform dependent motor controller supports those features in hardware it should override the corresponding methods and call the hardware directly. For some features that there is no software emulation, this class will throw an UnsupportedOperationException.

  • Field Details

    • motorGetPositionElapsedTimer

      protected static TrcElapsedTimer motorGetPositionElapsedTimer

    • motorSetPowerElapsedTimer

      protected static TrcElapsedTimer motorSetPowerElapsedTimer

    • motorSetVelocityElapsedTimer

      protected static TrcElapsedTimer motorSetVelocityElapsedTimer

    • motorSetPositionElapsedTimer

      protected static TrcElapsedTimer motorSetPositionElapsedTimer

    • motorSetCurrentElapsedTimer

      protected static TrcElapsedTimer motorSetCurrentElapsedTimer

    • tracer

      public final TrcDbgTrace tracer

    • instanceName

      protected final String instanceName

  • Constructor Details

    • TrcMotor

      public TrcMotor(String instanceName, TrcMotor.ExternalSensors sensors)
      Constructor: Create an instance of the object.
      Parameters:
      instanceName - specifies the instance name.
      sensors - specifies external sensors, can be null if none.

    • TrcMotor

      public TrcMotor(String instanceName)
      Constructor: Create an instance of the object.
      Parameters:
      instanceName - specifies the instance name.

  • Method Details

    • toString

      public String toString()
      This method returns the instance name.
      Overrides:
      toString in class Object
      Returns:
      instance name.

    • setPerformanceMonitorEnabled

      public void setPerformanceMonitorEnabled(boolean enabled)
      This method enables/disables performance monitoring of the PID control task.
      Parameters:
      enabled - specifies true to enable, false to disable.

    • setTraceLevel

      public void setTraceLevel(TrcDbgTrace.MsgLevel msgLevel, boolean tracePidInfo, boolean verbosePidInfo, TrcRobotBattery battery)
      This method sets the message trace level for the tracer.
      Parameters:
      msgLevel - specifies the message level.
      tracePidInfo - specifies true to enable tracing of PID info, false otherwise.
      verbosePidInfo - specifies true to trace verbose PID info, false otherwise.
      battery - specifies the battery object to get battery info for the message.

    • setBeep

      public void setBeep(TrcTone beepDevice, double beepLowFrequency, double beepHighFrequency, double beepDuration)
      This method sets the beep device and the beep tones so that it can play beeps when motor stalled.
      Parameters:
      beepDevice - specifies the beep device object.
      beepLowFrequency - specifies the low frequency beep.
      beepHighFrequency - specifies the high frequency beep.
      beepDuration - specifies the beep duration.

    • setBeep

      public void setBeep(TrcTone beepDevice)
      This method sets the beep device so that it can play beeps at default frequencies and duration when motor stalled.
      Parameters:
      beepDevice - specifies the beep device object.

    • convertPositionToScaledUnits

      public double convertPositionToScaledUnits(double pos)
      This method converts position sensor units to scaled units.
      Parameters:
      pos - specifies position in sensor units.
      Returns:
      position in scaled units.

    • convertPositionToSensorUnits

      public double convertPositionToSensorUnits(double pos)
      This method converts position scaled units to sensor units.
      Parameters:
      pos - specifies position in scaled units.
      Returns:
      position in sensor units.

    • setVoltageCompensationEnabled

      public void setVoltageCompensationEnabled(Double batteryNominalVoltage)
      This method enables/disables voltage compensation so that it will maintain the motor output regardless of battery voltage.
      Specified by:
      setVoltageCompensationEnabled in interface TrcMotorController
      Parameters:
      batteryNominalVoltage - specifies the nominal voltage of the battery to enable, null to disable.

    • isVoltageCompensationEnabled

      public boolean isVoltageCompensationEnabled()
      This method checks if voltage compensation is enabled.
      Specified by:
      isVoltageCompensationEnabled in interface TrcMotorController
      Returns:
      true if voltage compensation is enabled, false if disabled.

    • enableMotionProfile

      public void enableMotionProfile(double velocity, double acceleration, double jerk)
      This method enables motion profile support.
      Specified by:
      enableMotionProfile in interface TrcMotorController
      Parameters:
      velocity - specifies cruise velocity in the unit of rps.
      acceleration - specifies acceleration in the unit of rot per sec square.
      jerk - specifies acceleration derivation in the unit of rot per sec cube.

    • disableMotionProfile

      public void disableMotionProfile()
      This method disables motion profile support.
      Specified by:
      disableMotionProfile in interface TrcMotorController

    • addFollower

      protected void addFollower(TrcMotor motor, double scale, boolean nativeFollower)
      This method adds the given motor to the list that will follow this motor. It should only be called by the given motor to add it to the follower list of the motor it wants to follow.
      Parameters:
      motor - specifies the motor that will follow this motor.
      scale - specifies the value scale for the follower motor, 1.0 by default.
      nativeFollower - specifies true if the motor supports following natively, false otherwise.

    • follow

      public void follow(TrcMotor motor, boolean inverted, double scale)
      This method sets this motor to follow another motor.
      Specified by:
      follow in interface TrcMotorController
      Parameters:
      motor - specifies the motor to follow.
      inverted - specifies true if this motor is inverted from the motor it is following, false otherwise.
      scale - specifies the value scale for the follower motor, 1.0 by default.

    • follow

      public void follow(TrcMotor motor, boolean inverted)
      This method sets this motor to follow another motor.
      Parameters:
      motor - specifies the motor to follow.
      inverted - specifies true if this motor is inverted from the motor it is following, false otherwise.

    • getFollower

      public TrcMotor getFollower(int index)
      This method returns the follower with the specified index.
      Specified by:
      getFollower in interface TrcMotorController
      Parameters:
      index - specifies the follower index.
      Returns:
      follower.

    • setStallProtection

      public void setStallProtection(double stallMinPower, double stallTolerance, double stallTimeout, double resetTimeout)
      This method sets stall protection. When stall protection is turned ON, it will monitor the motor movement for stalled condition. A motor is considered stalled if: - the power applied to the motor is above or equal to stallMinPower. - the motor has not moved or movement stayed within stallTolerance for at least stallTimeout. Note: By definition, holding target position doing software PID control is stalling. If you decide to enable stall protection while holding target, please make sure to set a stallMinPower much greater than the power necessary to hold position against gravity, for example. However, if you want to zero calibrate on motor stall (e.g. don't have lower limit switch), you want to make sure calPower is at least stallMinPower.
      Parameters:
      stallMinPower - specifies the minimum motor power to detect stalled condition. If the motor power is below stallMinPower, it won't consider it as a stalled condition even if the motor does not move.
      stallTolerance - specifies the movement tolerance within which is still considered stalled.
      stallTimeout - specifies the time in seconds that the motor must stopped before it is declared stalled.
      resetTimeout - specifies the time in seconds the motor must be set to zero power after it is declared stalled will the stalled condition be reset. If this is set to zero, the stalled condition won't be cleared.

    • setPidStallDetectionEnabled

      public void setPidStallDetectionEnabled(double stallDetectionDelay, double stallDetectionTimeout, double stallErrorRateThreshold)
      This method enables/disables PID stall detection.
      Parameters:
      stallDetectionDelay - specifies stall detection start delay in seconds, zero to disable stall detection.
      stallDetectionTimeout - specifies stall timeout in seconds which is the minimum elapsed time for the motor to be motionless to be considered stalled.
      stallErrorRateThreshold - specifies the error rate threshold below which it will consider stalling.

    • setPidStallDetectionEnabled

      public void setPidStallDetectionEnabled(boolean enabled)
      This method enables/disables PID stall detection.
      Parameters:
      enabled - specifies true to enable stall detection, false to disable.

    • setLimitSwitchesSwapped

      public void setLimitSwitchesSwapped(boolean swapped)
      This method swaps the forward and reverse limit switches. By default, the lower limit switch is associated with the reverse limit switch and the upper limit switch is associated with the forward limit switch. This method will swap the association. Note: if you need to configure the lower and upper limit switches, you must configure them after this call.
      Parameters:
      swapped - specifies true to swap the limit switches, false otherwise.

    • enableLowerLimitSwitch

      public void enableLowerLimitSwitch(boolean normalClose)
      This method enables the lower limit switch and configures it to the specified type.
      Parameters:
      normalClose - specifies true as the normal close switch type, false as normal open.

    • enableUpperLimitSwitch

      public void enableUpperLimitSwitch(boolean normalClose)
      This method enables the upper limit switch and configures it to the specified type.
      Parameters:
      normalClose - specifies true as the normal close switch type, false as normal open.

    • disableLowerLimitSwitch

      public void disableLowerLimitSwitch()
      This method disables the lower limit switch.

    • disableUpperLimitSwitch

      public void disableUpperLimitSwitch()
      This method disables the upper limit switch.

    • setLowerLimitSwitchInverted

      public void setLowerLimitSwitchInverted(boolean inverted)
      This method inverts the active state of the lower limit switch, typically reflecting whether the switch is wired normally open or normally close.
      Parameters:
      inverted - specifies true to invert the limit switch to normal close, false to normal open.

    • setUpperLimitSwitchInverted

      public void setUpperLimitSwitchInverted(boolean inverted)
      This method inverts the active state of the upper limit switch, typically reflecting whether the switch is wired normally open or normally close.
      Parameters:
      inverted - specifies true to invert the limit switch to normal close, false to normal open.

    • isLowerLimitSwitchEnabled

      public boolean isLowerLimitSwitchEnabled()
      This method checks if the lower limit switch is enabled.
      Returns:
      true if enabled, false if disabled.

    • isUpperLimitSwitchEnabled

      public boolean isUpperLimitSwitchEnabled()
      This method checks if the upper limit switch is enabled.
      Returns:
      true if enabled, false if disabled.

    • isLowerLimitSwitchActive

      public boolean isLowerLimitSwitchActive()
      This method returns the state of the lower limit switch.
      Returns:
      true if lower limit switch is active, false otherwise.

    • isUpperLimitSwitchActive

      public boolean isUpperLimitSwitchActive()
      This method returns the state of the upper limit switch.
      Returns:
      true if upper limit switch is active, false otherwise.

    • setSoftPositionLimits

      public void setSoftPositionLimits(Double lowerLimit, Double upperLimit, boolean swapped)
      This method sets the lower and upper soft position limits.
      Parameters:
      lowerLimit - specifies the position of the lower limit in scaled units, null to disable lower limit.
      upperLimit - specifies the position of the upper limit in scaled units, null to disable upper limit.
      swapped - specifies true to swap the direction (lowerLimit is forward and upperLimit is reverse), false otherwise. This is only applicable for motor controller soft limits.

    • setPositionSensorInverted

      public void setPositionSensorInverted(boolean inverted)
      This method inverts the position sensor direction. This may be rare but there are scenarios where the motor encoder may be mounted somewhere in the power train that it rotates opposite to the motor rotation. This will cause the encoder reading to go down when the motor is receiving positive power. This method can correct this situation.
      Parameters:
      inverted - specifies true to invert position sensor direction, false otherwise.

    • isPositionSensorInverted

      public boolean isPositionSensorInverted()
      This method returns the state of the position sensor direction.
      Returns:
      true if the motor direction is inverted, false otherwise.

    • setPositionSensorScaleAndOffset

      public void setPositionSensorScaleAndOffset(double scale, double offset, double zeroOffset)
      This method sets the position sensor scale and offset for translating sensor units to real world units.
      Parameters:
      scale - specifies scale factor to multiply the position sensor reading.
      offset - specifies offset added to the scaled sensor reading.
      zeroOffset - specifies the zero offset for absolute encoder.

    • setPositionSensorScaleAndOffset

      public void setPositionSensorScaleAndOffset(double scale, double offset)
      This method sets the position sensor scale and offset for translating sensor units to real world units.
      Parameters:
      scale - specifies scale factor to multiply the position sensor reading.
      offset - specifies offset added to the scaled sensor reading.

    • getEncoderRawPosition

      public double getEncoderRawPosition()
      This method returns the normalized raw position of the external encoder if one is provided.
      Returns:
      external encoder normalized raw position.

    • resetPosition

      public void resetPosition(boolean hardware)
      This method resets the motor position sensor if provided, typically an encoder. Otherwise, it resets the one on the motor controller if it supports one. If hardware is false, it simulates the reset by reading the current position as the zero position.
      Parameters:
      hardware - specifies true for resetting hardware position, false for resetting software position.

    • resetPosition

      public void resetPosition()
      This method resets the motor position sensor, typically an encoder. This method emulates a reset for a potentiometer by doing a soft reset.

    • setSoftwarePidEnabled

      public void setSoftwarePidEnabled(boolean enabled)
      This method enables/disable software PID as the close-loop control.
      Parameters:
      enabled - specifies true to enable software PID control, false to disable.

    • getPidTarget

      public double getPidTarget()
      This method returns the PID control target. It could be a position, velocity or current depending on the current active PID controller.
      Returns:
      PID control target, zero if no active PID controller.

    • cancel

      public void cancel()
      This method cancels a previous operation by resetting the state set by the previous operation. Note: cancel does not stop the motor and therefore it will still hold its position. If you want to stop the motor, call the stop method instead. This could be called by an external caller who may not have ownership.

    • stop

      public void stop()
      This method stops the motor regardless of the control mode and resets it to power control mode.

    • setPower

      public void setPower(String owner, double delay, double power, double duration, TrcEvent event)
      This method sets the motor power. If the motor is not in the correct control mode, it will stop the motor and set it to power control mode. Optionally, you can specify a delay before running the motor and a duration for which the motor will be turned off afterwards.
      Parameters:
      owner - specifies the ID string of the caller for checking ownership, can be null if caller is not ownership aware.
      delay - specifies the time in seconds to delay before setting the value, 0.0 if no delay.
      power - specifies the percentage power (range -1.0 to 1.0).
      duration - specifies the duration in seconds to run the motor and turns it off afterwards, 0.0 if not turning off.
      event - specifies the event to signal when the motor operation is completed

    • setPower

      public void setPower(double delay, double power, double duration, TrcEvent event)
      This method sets the motor power. If the motor is not in the correct control mode, it will stop the motor and set it to power control mode. Optionally, you can specify a delay before running the motor and a duration for which the motor will be turned off afterwards.
      Parameters:
      delay - specifies the time in seconds to delay before setting the value, 0.0 if no delay.
      power - specifies the percentage power (range -1.0 to 1.0).
      duration - specifies the duration in seconds to run the motor and turns it off afterwards, 0.0 if not turning off.
      event - specifies the event to signal when the motor operation is completed

    • setPower

      public void setPower(double delay, double power, double duration)
      This method sets the motor power. If the motor is not in the correct control mode, it will stop the motor and set it to power control mode. Optionally, you can specify a delay before running the motor and a duration for which the motor will be turned off afterwards.
      Parameters:
      delay - specifies the time in seconds to delay before setting the value, 0.0 if no delay.
      power - specifies the percentage power (range -1.0 to 1.0).
      duration - specifies the duration in seconds to run the motor and turns it off afterwards, 0.0 if not turning off.

    • setPower

      public void setPower(double power)
      This method sets the motor power. If the motor is not in the correct control mode, it will stop the motor and set it to power control mode.
      Parameters:
      power - specifies the percentage power (range -1.0 to 1.0).

    • getPower

      public double getPower()
      This method returns the motor power.
      Returns:
      current motor percentage power (range -1.0 to 1.0).

    • setVelocity

      public void setVelocity(String owner, double delay, double velocity, double duration, TrcEvent event)
      This method sets the motor velocity. If the motor is not in the correct control mode, it will stop the motor and set it to velocity control mode. Optionally, you can specify a delay before running the motor and a duration for which the motor will be turned off afterwards.
      Parameters:
      owner - specifies the ID string of the caller for checking ownership, can be null if caller is not ownership aware.
      delay - specifies the time in seconds to delay before setting the value, 0.0 if no delay.
      velocity - specifies velocity in scaled units/sec.
      duration - specifies the duration in seconds to run the motor and turns it off afterwards, 0.0 if not turning off.
      event - specifies the event to signal when the motor operation is completed

    • setVelocity

      public void setVelocity(double delay, double velocity, double duration, TrcEvent event)
      This method sets the motor velocity. If the motor is not in the correct control mode, it will stop the motor and set it to velocity control mode. Optionally, you can specify a delay before running the motor and a duration for which the motor will be turned off afterwards.
      Parameters:
      delay - specifies the time in seconds to delay before setting the value, 0.0 if no delay.
      velocity - specifies velocity in scaled units/sec.
      duration - specifies the duration in seconds to run the motor and turns it off afterwards, 0.0 if not turning off.
      event - specifies the event to signal when the motor operation is completed

    • setVelocity

      public void setVelocity(double delay, double velocity, double duration)
      This method sets the motor velocity. If the motor is not in the correct control mode, it will stop the motor and set it to power control mode. Optionally, you can specify a delay before running the motor and a duration for which the motor will be turned off afterwards.
      Parameters:
      delay - specifies the time in seconds to delay before setting the value, 0.0 if no delay.
      velocity - specifies velocity in scaled units/sec.
      duration - specifies the duration in seconds to run the motor and turns it off afterwards, 0.0 if not turning off.

    • setVelocity

      public void setVelocity(double velocity)
      This method sets the motor velocity. If the motor is not in the correct control mode, it will stop the motor and set it to power control mode.
      Parameters:
      velocity - specifies velocity in scaled units/sec.

    • getVelocity

      public double getVelocity()
      This method returns the motor velocity. Velocity could either be obtained by calling the motor hardware if it supports it or using the odometry task to monitor the position sensor value. However, accessing hardware may impact performance because it may involve initiating USB/CAN/I2C bus cycles. Therefore, it may be beneficial to enable the odometry task to calculate the velocity value.
      Returns:
      motor velocity in scaled units/sec.

    • setPosition

      public void setPosition(String owner, double delay, double position, boolean holdTarget, double powerLimit, TrcEvent completionEvent, double timeout)
      This method sets the motor position. If the motor is not in the correct control mode, it will stop the motor and set it to power control mode.
      Parameters:
      owner - specifies the ID string of the caller for checking ownership, can be null if caller is not ownership aware.
      delay - specifies the time in seconds to delay before setting the value, 0.0 if no delay.
      position - specifies the position in scaled units to be set.
      holdTarget - specifies true to hold position target, false otherwise.
      powerLimit - specifies the maximum power output limits.
      completionEvent - specifies the event to signal when the motor operation is completed.
      timeout - specifies timeout in seconds.

    • setPosition

      public void setPosition(double delay, double position, boolean holdTarget, double powerLimit, TrcEvent completionEvent, double timeout)
      This method sets the motor position. If the motor is not in the correct control mode, it will stop the motor and set it to power control mode.
      Parameters:
      delay - specifies the time in seconds to delay before setting the value, 0.0 if no delay.
      position - specifies the position in scaled units to be set.
      holdTarget - specifies true to hold position target, false otherwise.
      powerLimit - specifies the maximum power output limits.
      completionEvent - specifies the event to signal when the motor operation is completed.
      timeout - specifies timeout in seconds.

    • setPosition

      public void setPosition(double delay, double position, boolean holdTarget, double powerLimit, TrcEvent completionEvent)
      This method sets the motor position. If the motor is not in the correct control mode, it will stop the motor and set it to power control mode.
      Parameters:
      delay - specifies the time in seconds to delay before setting the value, 0.0 if no delay.
      position - specifies the position in scaled units to be set.
      holdTarget - specifies true to hold position target, false otherwise.
      powerLimit - specifies the maximum power output limits.
      completionEvent - specifies the event to signal when the motor operation is completed.

    • setPosition

      public void setPosition(double delay, double position, boolean holdTarget, double powerLimit)
      This method sets the motor position. If the motor is not in the correct control mode, it will stop the motor and set it to power control mode.
      Parameters:
      delay - specifies the time in seconds to delay before setting the value, 0.0 if no delay.
      position - specifies the position in scaled units to be set.
      holdTarget - specifies true to hold position target, false otherwise.
      powerLimit - specifies the maximum power output limits.

    • setPosition

      public void setPosition(double position, boolean holdTarget, double powerLimit)
      This method sets the motor position. If the motor is not in the correct control mode, it will stop the motor and set it to power control mode.
      Parameters:
      position - specifies the position in scaled units to be set.
      holdTarget - specifies true to hold position target, false otherwise.
      powerLimit - specifies the maximum power output limits.

    • setPosition

      public void setPosition(double position, boolean holdTarget)
      This method sets the motor position. If the motor is not in the correct control mode, it will stop the motor and set it to power control mode.
      Parameters:
      position - specifies the position in scaled units to be set.
      holdTarget - specifies true to hold position target, false otherwise.

    • setPosition

      public void setPosition(double position)
      This method sets the motor position. If the motor is not in the correct control mode, it will stop the motor and set it to power control mode.
      Parameters:
      position - specifies the position in scaled units to be set.

    • getPosition

      public double getPosition()
      This method returns the motor position by reading the position sensor. As a performance optimization, it gets the position from cached odometry if odometry is enabled.
      Returns:
      current motor position in scaled units.

    • setPidPower

      public void setPidPower(String owner, double power, double minPos, double maxPos, boolean holdTarget)
      This method sets the motor power with PID control. This is basically the same as setPosition but with dynamically changing powerLimit. The motor will be under position PID control and the power specifies the maximum limit of how fast the motor can go. The actual motor power is controlled by a PID controller with the target either set to minPos or maxPos depending on the direction of the motor. This is very useful in scenarios such as an elevator where you want to have the elevator controlled by a joystick but would like PID control to pay attention to the upper and lower limits and slow down when approaching those limits. The joystick value will specify the maximum limit of the elevator power. So if the joystick is only pushed half way, the elevator will only go half power even though it is far away from the target.
      Parameters:
      owner - specifies the owner ID to check if the caller has ownership of the motor.
      power - specifies the upper bound power of the motor.
      minPos - specifies the minimum of the position range.
      maxPos - specifies the maximum of the position range.
      holdTarget - specifies true to hold target when speed is set to 0, false otherwise.

    • setPidPower

      public void setPidPower(double power, double minPos, double maxPos, boolean holdTarget)
      This method sets the motor power with PID control. The motor will be under PID control and the power specifies the upper bound of how fast the motor will spin. The actual motor power is controlled by a PID controller with the target either set to minPos or maxPos depending on the direction of the motor. This is very useful in scenarios such as an elevator where you want to have the elevator controlled by a joystick but would like PID control to pay attention to the upper and lower limits and slow down when approaching those limits. The joystick value will specify the upper bound of the elevator power. So if the joystick is only pushed half way, the elevator will only go half power even though it is far away from the target.
      Parameters:
      power - specifies the upper bound power of the motor.
      minPos - specifies the minimum of the position range.
      maxPos - specifies the maximum of the position range.
      holdTarget - specifies true to hold target when speed is set to 0, false otherwise.

    • setCurrent

      public void setCurrent(String owner, double delay, double current, double duration, TrcEvent event)
      This method sets the motor current. If the motor is not in the correct control mode, it will stop the motor and set it to current control mode. Optionally, you can specify a delay before running the motor and a duration for which the motor will be turned off afterwards.
      Parameters:
      owner - specifies the ID string of the caller for checking ownership, can be null if caller is not ownership aware.
      delay - specifies the time in seconds to delay before setting the value, 0.0 if no delay.
      current - specifies the current in amperes.
      duration - specifies the duration in seconds to run the motor and turns it off afterwards, 0.0 if not turning off.
      event - specifies the event to signal when the motor operation is completed

    • setCurrent

      public void setCurrent(double delay, double current, double duration, TrcEvent event)
      This method sets the motor current. If the motor is not in the correct control mode, it will stop the motor and set it to current control mode. Optionally, you can specify a delay before running the motor and a duration for which the motor will be turned off afterwards.
      Parameters:
      delay - specifies the time in seconds to delay before setting the value, 0.0 if no delay.
      current - specifies the current in amperes.
      duration - specifies the duration in seconds to run the motor and turns it off afterwards, 0.0 if not turning off.
      event - specifies the event to signal when the motor operation is completed

    • setCurrent

      public void setCurrent(double delay, double current, double duration)
      This method sets the motor current. If the motor is not in the correct control mode, it will stop the motor and set it to current control mode. Optionally, you can specify a delay before running the motor and a duration for which the motor will be turned off afterwards.
      Parameters:
      delay - specifies the time in seconds to delay before setting the value, 0.0 if no delay.
      current - specifies the current in amperes.
      duration - specifies the duration in seconds to run the motor and turns it off afterwards, 0.0 if not turning off.

    • setCurrent

      public void setCurrent(double current)
      This method sets the motor current. If the motor is not in the correct control mode, it will stop the motor and set it to current control mode.
      Parameters:
      current - specifies the current in amperes.

    • getCurrent

      public double getCurrent()
      This method returns the motor current.
      Returns:
      current motor current in amperes.

    • setVelocityPidParameters

      public void setVelocityPidParameters(TrcPidController.PidCoefficients pidCoeff, double tolerance)
      This method sets the PID parameters of the motor's velocity PID controller. Note that PID coefficients are different for software PID and controller built-in PID. If you enable/disable software PID, you need to set the appropriate PID coefficients accordingly.
      Parameters:
      pidCoeff - specifies the PID coefficients to set.
      tolerance - specifies the PID tolerance.

    • setVelocityParameters

      public void setVelocityParameters(double kP, double kI, double kD, double kF, double iZone, double tolerance)
      This method sets the PID parameters of the motor's velocity PID controller. Note that PID coefficients are different for software PID and controller built-in PID. If you enable/disable software PID, you need to set the appropriate PID coefficients accordingly.
      Parameters:
      kP - specifies the Kp coefficient.
      kI - specifies the Ki coefficient.
      kD - specifies the Kd coefficient.
      kF - specifies the Kf coefficient.
      iZone - specifies IZone, can be 0.0 if not provided.
      tolerance - specifies the PID tolerance.

    • setVelocityPidParameters

      public void setVelocityPidParameters(double kP, double kI, double kD, double kF, double tolerance)
      This method sets the PID parameters of the motor's velocity PID controller. Note that PID coefficients are different for software PID and controller built-in PID. If you enable/disable software PID, you need to set the appropriate PID coefficients accordingly.
      Parameters:
      kP - specifies the Kp coefficient.
      kI - specifies the Ki coefficient.
      kD - specifies the Kd coefficient.
      kF - specifies the Kf coefficient.
      tolerance - specifies the PID tolerance.

    • setVelocityPidTolerance

      public void setVelocityPidTolerance(double tolerance)
      This method sets the velocity tolerance for PID control.
      Parameters:
      tolerance - specifies the tolerance in scaled units per second.

    • getVelocityPidCoefficients

      public TrcPidController.PidCoefficients getVelocityPidCoefficients()
      This method returns the PID coefficients of the motor's velocity PID controller.
      Returns:
      PID coefficients of the motor's velocity PID controller.

    • getVelocityOnTarget

      public boolean getVelocityOnTarget()
      This method checks if velocity PID control has reached target.
      Returns:
      true if velocity has reached target, false otherwise.

    • setVelocityPidPowerComp

      public void setVelocityPidPowerComp(TrcMotor.PowerCompensation powerComp)
      This method sets the power compensation callback of the motor's velocity PID controller.
      Parameters:
      powerComp - specifies the power compensation callback.

    • getVelocityPidController

      public TrcPidController getVelocityPidController()
      This method returns the software velocity PID controller if one was created by enabling software PID control. It does not mean software PID control is current enable. It just means software PID control was enabled at one point. This allows you to configure the software PID controller. For example, whether the target is absolute or relative, specifying noOscillation etc.
      Returns:
      software velocity PID controller.

    • setPositionPidParameters

      public void setPositionPidParameters(TrcPidController.PidCoefficients pidCoeff, double tolerance)
      This method sets the PID parameters of the motor's position PID controller. Note that PID coefficients are different for software PID and controller built-in PID. If you enable/disable software PID, you need to set the appropriate PID coefficients accordingly.
      Parameters:
      pidCoeff - specifies the PID coefficients to set.
      tolerance - specifies the PID tolerance.

    • setPositionPidParameters

      public void setPositionPidParameters(double kP, double kI, double kD, double kF, double iZone, double tolerance)
      This method sets the PID parameters of the motor's position PID controller. Note that PID coefficients are different for software PID and controller built-in PID. If you enable/disable software PID, you need to set the appropriate PID coefficients accordingly.
      Parameters:
      kP - specifies the Kp coefficient.
      kI - specifies the Ki coefficient.
      kD - specifies the Kd coefficient.
      kF - specifies the Kf coefficient.
      iZone - specifies IZone, can be 0.0 if not provided.
      tolerance - specifies the PID tolerance.

    • setPositionPidParameters

      public void setPositionPidParameters(double kP, double kI, double kD, double kF, double tolerance)
      This method sets the PID parameters of the motor's position PID controller. Note that PID coefficients are different for software PID and controller built-in PID. If you enable/disable software PID, you need to set the appropriate PID coefficients accordingly.
      Parameters:
      kP - specifies the Kp coefficient.
      kI - specifies the Ki coefficient.
      kD - specifies the Kd coefficient.
      kF - specifies the Kf coefficient.
      tolerance - specifies the PID tolerance.

    • setPositionPidTolerance

      public void setPositionPidTolerance(double tolerance)
      This method sets the position tolerance for PID control.
      Parameters:
      tolerance - specifies the tolerance in scaled units.

    • getPositionPidCoefficients

      public TrcPidController.PidCoefficients getPositionPidCoefficients()
      This method returns the PID coefficients of the motor's position PID controller.
      Returns:
      PID coefficients of the motor's position PID controller.

    • getPositionOnTarget

      public boolean getPositionOnTarget()
      This method checks if position PID control has reached target.
      Returns:
      true if position has reached target, false otherwise.

    • setPositionPidPowerComp

      public void setPositionPidPowerComp(TrcMotor.PowerCompensation powerComp)
      This method sets the power compensation callback of the motor's position PID controller.
      Parameters:
      powerComp - specifies the power compensation callback.

    • getPositionPidController

      public TrcPidController getPositionPidController()
      This method returns the software position PID controller if one was created by enabling software PID control. It does not mean software PID control is current enable. It just means software PID control was enabled at one point. This allows you to configure the software PID controller. For example, whether the target is absolute or relative, specifying noOscillation etc.
      Returns:
      software position PID controller.

    • setCurrentPidParameters

      public void setCurrentPidParameters(TrcPidController.PidCoefficients pidCoeff, double tolerance)
      This method sets the PID parameters of the motor's current PID controller. Note that PID coefficients are different for software PID and controller built-in PID. If you enable/disable software PID, you need to set the appropriate PID coefficients accordingly.
      Parameters:
      pidCoeff - specifies the PID coefficients to set.
      tolerance - specifies the PID tolerance.

    • setCurrentPidParameters

      public void setCurrentPidParameters(double kP, double kI, double kD, double kF, double iZone, double tolerance)
      This method sets the PID parameters of the motor's current PID controller. Note that PID coefficients are different for software PID and controller built-in PID. If you enable/disable software PID, you need to set the appropriate PID coefficients accordingly.
      Parameters:
      kP - specifies the Kp coefficient.
      kI - specifies the Ki coefficient.
      kD - specifies the Kd coefficient.
      kF - specifies the Kf coefficient.
      iZone - specifies IZone, can be 0.0 if not provided.
      tolerance - specifies the PID tolerance.

    • setCurrentPidParameters

      public void setCurrentPidParameters(double kP, double kI, double kD, double kF, double tolerance)
      This method sets the PID parameters of the motor's current PID controller. Note that PID coefficients are different for software PID and controller built-in PID. If you enable/disable software PID, you need to set the appropriate PID coefficients accordingly.
      Parameters:
      kP - specifies the Kp coefficient.
      kI - specifies the Ki coefficient.
      kD - specifies the Kd coefficient.
      kF - specifies the Kf coefficient.
      tolerance - specifies the PID tolerance.

    • setCurrentPidTolerance

      public void setCurrentPidTolerance(double tolerance)
      This method sets the current tolerance for PID control.
      Parameters:
      tolerance - specifies the tolerance in amperes.

    • getCurrentPidCoefficients

      public TrcPidController.PidCoefficients getCurrentPidCoefficients()
      This method returns the PID coefficients of the motor's current PID controller.
      Returns:
      PID coefficients of the motor's current PID controller.

    • getCurrentOnTarget

      public boolean getCurrentOnTarget()
      This method checks if current PID control has reached target.
      Returns:
      true if current has reached target, false otherwise.

    • setCurrentPidPowerComp

      public void setCurrentPidPowerComp(TrcMotor.PowerCompensation powerComp)
      This method sets the power compensation callback of the motor's current PID controller.
      Parameters:
      powerComp - specifies the power compensation callback.

    • getCurrentPidController

      public TrcPidController getCurrentPidController()
      This method returns the software current PID controller if one was created by enabling software PID control. It does not mean software PID control is current enable. It just means software PID control was enabled at one point. This allows you to configure the software PID controller. For example, whether the target is absolute or relative, specifying noOscillation etc.
      Returns:
      software current PID controller.

    • resetPositionOnLowerLimitSwitch

      public void resetPositionOnLowerLimitSwitch(TrcTrigger.TriggerMode triggerMode, TrcEvent.Callback triggerCallback)
      This method creates a digital trigger on the motor's lower limit switch. It resets the position sensor reading when the digital input is triggered. This is intended to be called as part of motor initialization. Therefore, it is not designed to be ownership-aware.
      Parameters:
      triggerMode - specifies the trigger mode.
      triggerCallback - specifies an event callback if the trigger occurred, null if none specified.

    • resetPositionOnLowerLimitSwitch

      public void resetPositionOnLowerLimitSwitch(TrcTrigger.TriggerMode triggerMode)
      This method creates a digital trigger on the motor's lower limit switch. It resets the position sensor reading when the digital input is triggered. This is intended to be called as part of motor initialization. Therefore, it is not designed to be ownership-aware.
      Parameters:
      triggerMode - specifies the trigger mode.

    • resetPositionOnLowerLimitSwitch

      public void resetPositionOnLowerLimitSwitch(TrcEvent.Callback triggerCallback)
      This method creates a digital trigger on the motor's lower limit switch. It resets the position sensor reading when the digital input is triggered. This is intended to be called as part of motor initialization. Therefore, it is not designed to be ownership-aware.
      Parameters:
      triggerCallback - specifies an event callback if the trigger occurred, null if none specified.

    • resetPositionOnLowerLimitSwitch

      public void resetPositionOnLowerLimitSwitch()
      This method creates a digital trigger on the motor's lower limit switch. It resets the position sensor reading when the digital input is triggered. This is intended to be called as part of motor initialization. Therefore, it is not designed to be ownership-aware.

    • isCalibrating

      public boolean isCalibrating()
      This method checks if the PID motor is in the middle of zero calibration.
      Returns:
      true if zero calibrating, false otherwise.

    • zeroCalibrate

      public void zeroCalibrate(String owner, double calPower, TrcEvent completionEvent)
      This method starts zero calibration mode by moving the motor with specified calibration power until a limit switch is hit or the motor is stalled. Generally, calibration power should be negative so that the motor will move towards the lower limit switch. However, in some scenarios such as a turret that can turn all the way around and has only one limit switch, it may be necessary to use a positive calibration power to move it towards the limit switch instead of using negative calibration power and turning the long way around that may cause wires to entangle. If this method specifies an owner and the subsystem was not owned by it, it will acquire exclusive ownership on its behalf and release ownership after the operation is completed.
      Parameters:
      owner - specifies the owner ID to check if the caller has ownership of the motor.
      calPower - specifies the motor power for the zero calibration, can be positive or negative depending on the desire direction of movement.
      completionEvent - specifies an event to signal when zero calibration is done, can be null if not provided.

    • zeroCalibrate

      public void zeroCalibrate(double calPower, TrcEvent completionEvent)
      This method starts zero calibration mode by moving the motor with specified calibration power until a limit switch is hit or the motor is stalled. Generally, calibration power should be negative so that the motor will move towards the lower limit switch. However, in some scenarios such as a turret that can turn all the way around and has only one limit switch, it may be necessary to use a positive calibration power to move it towards the limit switch instead of using negative calibration power and turning the long way around that may cause wires to entangle.
      Parameters:
      calPower - specifies the motor power for the zero calibration, can be positive or negative depending on the desire direction of movement.
      completionEvent - specifies an event to signal when zero calibration is done, can be null if not provided.

    • zeroCalibrate

      public void zeroCalibrate(String owner, double calPower, TrcEvent.Callback callback)
      This method starts zero calibration mode by moving the motor with specified calibration power until a limit switch is hit or the motor is stalled. Generally, calibration power should be negative so that the motor will move towards the lower limit switch. However, in some scenarios such as a turret that can turn all the way around and has only one limit switch, it may be necessary to use a positive calibration power to move it towards the limit switch instead of using negative calibration power and turning the long way around that may cause wires to entangle. If this method specifies an owner and the subsystem was not owned by it, it will acquire exclusive ownership on its behalf and release ownership after the operation is completed.
      Parameters:
      owner - specifies the owner ID to check if the caller has ownership of the motor.
      calPower - specifies the motor power for the zero calibration, can be positive or negative depending on the desire direction of movement.
      callback - specifies a callback handler when zero calibration is done.

    • zeroCalibrate

      public void zeroCalibrate(double calPower, TrcEvent.Callback callback)
      This method starts zero calibration mode by moving the motor with specified calibration power until a limit switch is hit or the motor is stalled. Generally, calibration power should be negative so that the motor will move towards the lower limit switch. However, in some scenarios such as a turret that can turn all the way around and has only one limit switch, it may be necessary to use a positive calibration power to move it towards the limit switch instead of using negative calibration power and turning the long way around that may cause wires to entangle.
      Parameters:
      calPower - specifies the motor power for the zero calibration, can be positive or negative depending on the desire direction of movement.
      callback - specifies a callback handler when zero calibration is done.

    • zeroCalibrate

      public void zeroCalibrate(String owner, double calPower)
      This method starts zero calibration mode by moving the motor with specified calibration power until a limit switch is hit or the motor is stalled. Generally, calibration power should be negative so that the motor will move towards the lower limit switch. However, in some scenarios such as a turret that can turn all the way around and has only one limit switch, it may be necessary to use a positive calibration power to move it towards the limit switch instead of using negative calibration power and turning the long way around that may cause wires to entangle.
      Parameters:
      owner - specifies the owner ID to check if the caller has ownership of the motor.
      calPower - specifies the motor power for the zero calibration, can be positive or negative depending on the desire direction of movement.

    • zeroCalibrate

      public void zeroCalibrate(double calPower)
      This method starts zero calibration mode by moving the motor with specified calibration power until a limit switch is hit or the motor is stalled. Generally, calibration power should be negative so that the motor will move towards the lower limit switch. However, in some scenarios such as a turret that can turn all the way around and has only one limit switch, it may be necessary to use a positive calibration power to move it towards the limit switch instead of using negative calibration power and turning the long way around that may cause wires to entangle.
      Parameters:
      calPower - specifies the motor power for the zero calibration, can be positive or negative depending on the desire direction of movement.

    • setPresets

      public void setPresets(boolean velocityPresets, double tolerance, double... presets)
      This method sets an array of presets for the motor.
      Parameters:
      velocityPresets - specifies true for velocity presets, false for position presets.
      tolerance - specifies the preset tolerance.
      presets - specifies an array of presets in scaled unit.

    • setPresetPosition

      public void setPresetPosition(String owner, double delay, int presetIndex, boolean holdTarget, double powerLimit, TrcEvent event, double timeout)
      This method sets the motor to the specified preset position.
      Parameters:
      owner - specifies the owner ID to check if the caller has ownership of the subsystem.
      delay - specifies delay time in seconds before setting position, can be zero if no delay.
      presetIndex - specifies the index to the preset position array.
      holdTarget - specifies true to hold target after PID operation is completed.
      powerLimit - specifies the maximum power limit.
      event - specifies the event to signal when target is reached, can be null if not provided.
      timeout - specifies a timeout value in seconds. If the operation is not completed without the specified timeout, the operation will be canceled and the event will be signaled. If no timeout is specified, it should be set to zero.

    • setPresetVelocity

      public void setPresetVelocity(String owner, double delay, int presetIndex, double duration, TrcEvent event)
      This method sets the motor to the specified preset velocity.
      Parameters:
      owner - specifies the owner ID to check if the caller has ownership of the subsystem.
      delay - specifies delay time in seconds before setting velocity, can be zero if no delay.
      presetIndex - specifies the index to the preset velocity array.
      duration - specifies the duration in seconds to run the motor and turns it off afterwards, 0.0 if not turning off.
      event - specifies the event to signal when target is reached, can be null if not provided.

    • presetPositionUp

      public void presetPositionUp(String owner, double powerLimit)
      This method sets the motor to the next preset position up from the current position.
      Parameters:
      owner - specifies the owner ID that will acquire ownership before setting the preset position and will automatically release ownership when the motor movement is completed, can be null if no ownership is required.
      powerLimit - specifies the maximum power limit.

    • presetPositionDown

      public void presetPositionDown(String owner, double powerLimit)
      This method sets the motor to the next preset position down from the current position.
      Parameters:
      owner - specifies the owner ID that will acquire ownership before setting the preset position and will automatically release ownership when the motor movement is completed, can be null if no ownership is required.
      powerLimit - specifies the maximum power limit.

    • presetVelocityUp

      public void presetVelocityUp(String owner)
      This method sets the motor to the next preset velocity up from the current velocity.
      Parameters:
      owner - specifies the owner ID that will acquire ownership before setting the preset position and will automatically release ownership when the motor movement is completed, can be null if no ownership is required.

    • presetVelocityDown

      public void presetVelocityDown(String owner)
      This method sets the motor to the next preset velocity down from the current velocity.
      Parameters:
      owner - specifies the owner ID that will acquire ownership before setting the preset position and will automatically release ownership when the motor movement is completed, can be null if no ownership is required.

    • clearOdometryMotorsList

      public static void clearOdometryMotorsList(boolean removeOdometryTask)
      This method clears the list of motors that register for odometry monitoring. This method should only be called by the task scheduler.
      Parameters:
      removeOdometryTask - specifies true to also remove the odometry task object, false to leave it alone. This is mainly for FTC, FRC should always set this to false.

    • getNumOdometryMotors

      public static int getNumOdometryMotors()
      This method returns the number of motors in the list registered for odometry monitoring.
      Returns:
      number of motors in the list.

    • setOdometryEnabled

      public void setOdometryEnabled(boolean enabled, boolean resetOdometry, boolean resetHardware)
      This method enables/disables the task that monitors the motor odometry. Since odometry task takes up CPU cycle, it should not be enabled if the user doesn't need motor odometry info.
      Parameters:
      enabled - specifies true to enable odometry task, disable otherwise.
      resetOdometry - specifies true to reset odometry, false otherwise.
      resetHardware - specifies true to reset odometry hardware, false otherwise. This is only applicable when enabling odometry, not used when disabling.

    • isOdometryEnabled

      public boolean isOdometryEnabled()
      This method checks if the odometry of this motor is enabled.
      Returns:
      true if odometry of this motor is enabled, false if disabled.

    • getName

      public String getName()
      This method returns the instance name.
      Specified by:
      getName in interface TrcOdometrySensor
      Returns:
      instance name.

    • resetOdometry

      public void resetOdometry(boolean resetHardware)
      This method resets the odometry data and sensor.
      Specified by:
      resetOdometry in interface TrcOdometrySensor
      Parameters:
      resetHardware - specifies true to do a hardware reset, false to do a software reset. Hardware reset may require some time to complete and will block this method from returning until finish.

    • getOdometry

      public TrcOdometrySensor.Odometry getOdometry(int axisIndex)
      This method returns a copy of the odometry data of the specified axis. It must be a copy so it won't change while the caller is accessing the data fields.
      Specified by:
      getOdometry in interface TrcOdometrySensor
      Parameters:
      axisIndex - specifies the axis index if it is a multi-axes sensor, 0 if it is a single axis sensor (not used).
      Returns:
      a copy of the odometry data of the specified axis.

    • setElapsedTimerEnabled

      public static void setElapsedTimerEnabled(boolean enabled)
      This method enables/disables the elapsed timers for performance monitoring.
      Parameters:
      enabled - specifies true to enable elapsed timers, false to disable.

    • printElapsedTime

      public static void printElapsedTime(TrcDbgTrace tracer)
      This method prints the elapsed time info using the given tracer.
      Parameters:
      tracer - specifies the tracer to be used to print the info.

    • printPidControlTaskPerformance

      public void printPidControlTaskPerformance()
      This method prints the PID control task performance info.