Package com.ctre.phoenix6.mechanisms

Class SimpleDifferentialMechanism<MotorT extends CommonTalon>

java.lang.Object
com.ctre.phoenix6.mechanisms.SimpleDifferentialMechanism<MotorT>
public class SimpleDifferentialMechanism<MotorT extends CommonTalon> extends Object
Manages control of a simple two-axis differential mechanism.

This mechanism provides limited differential functionality. Pro users on a CAN FD bus can use the DifferentialMechanism instead for full functionality.

A differential mechanism has two axes of motion, where the position along each axis is determined by two motors in separate gearboxes:

  • Driving both motors in a common direction causes the mechanism to move forward/reverse, up/down, etc.
    • This is the Average axis: position is determined by the average of the two motors' positions.
  • Driving the motors in opposing directions causes the mechanism to twist or rotate left/right.
    • This is the Difference axis: rotation is determined by half the difference of the two motors' positions.

  • Constructor Details

    • SimpleDifferentialMechanism

      public SimpleDifferentialMechanism(SimpleDifferentialMechanism.DeviceConstructor<MotorT> motorConstructor, DifferentialMotorConstants<?> constants)
      Creates a new simple differential mechanism using two CommonTalon devices. The mechanism will use the average of the two Talon FX sensors on the primary axis, and half of the difference between the two Talon FX sensors on the differential axis.

      This mechanism provides limited differential functionality. Pro users on a CAN FD bus can use the DifferentialMechanism class instead for full functionality.

      Parameters:
      motorConstructor - Constructor for the motors, such as TalonFX::new
      constants - Constants used to construct the mechanism

    • SimpleDifferentialMechanism

      public SimpleDifferentialMechanism(SimpleDifferentialMechanism.DeviceConstructor<MotorT> motorConstructor, DifferentialMotorConstants<?> constants, Pigeon2 pigeon2, DifferentialMotorConstants.DifferentialPigeon2Source pigeonSource)
      Creates a new simple differential mechanism using two CommonTalon devices and a Pigeon2. The mechanism will use the average of the two Talon FX sensors on the primary axis, and the selected Pigeon 2 sensor source on the differential axis.

      This mechanism provides limited differential functionality. Pro users on a CAN FD bus can use the DifferentialMechanism class instead for full functionality.

      Parameters:
      motorConstructor - Constructor for the motors, such as TalonFX::new
      constants - Constants used to construct the mechanism
      pigeon2 - The Pigeon 2 to use for the differential axis
      pigeonSource - The sensor source to use for the Pigeon 2 (Yaw, Pitch, or Roll)

    • SimpleDifferentialMechanism

      public SimpleDifferentialMechanism(SimpleDifferentialMechanism.DeviceConstructor<MotorT> motorConstructor, DifferentialMotorConstants<?> constants, CANcoder cancoder)
      Creates a new simple differential mechanism using two CommonTalon devices and a CANcoder. The mechanism will use the average of the two Talon FX sensors on the primary axis, and the CANcoder position/velocity on the differential axis.

      This mechanism provides limited differential functionality. Pro users on a CAN FD bus can use the DifferentialMechanism class instead for full functionality.

      Parameters:
      motorConstructor - Constructor for the motors, such as TalonFX::new
      constants - Constants used to construct the mechanism
      cancoder - The CANcoder to use for the differential axis

    • SimpleDifferentialMechanism

      public SimpleDifferentialMechanism(SimpleDifferentialMechanism.DeviceConstructor<MotorT> motorConstructor, DifferentialMotorConstants<?> constants, CANdi candi, DifferentialMotorConstants.DifferentialCANdiSource candiSource)
      Creates a new simple differential mechanism using two hardware#traits#CommonTalon devices and a CANdi. The mechanism will use the average of the two Talon FX sensors on the primary axis, and the selected CTR Electronics' CANdi™ branded sensor source on the differential axis.

      This mechanism provides limited differential functionality. Pro users on a CAN FD bus can use the DifferentialMechanism class instead for full functionality.

      Parameters:
      motorConstructor - Constructor for the motors, such as TalonFX::new
      constants - Constants used to construct the mechanism
      candi - The CTR Electronics' CANdi™ branded device to use for the differential axis
      candiSource - The sensor source to use for the CTR Electronics' CANdi™ branded device

  • Method Details

    • configNeutralMode

      public final StatusCode configNeutralMode(NeutralModeValue neutralMode)
      Configures the neutral mode to use for both motors in the mechanism.

      This will wait up to 0.100 seconds (100ms) by default.

      Parameters:
      neutralMode - The state of the motor controller bridge when output is neutral or disabled
      Returns:
      Status code of the first failed config call, or OK if all succeeded

    • configNeutralMode

      public final StatusCode configNeutralMode(NeutralModeValue neutralMode, double timeoutSeconds)
      Configures the neutral mode to use for both motors in the mechanism.
      Parameters:
      neutralMode - The state of the motor controller bridge when output is neutral or disabled
      timeoutSeconds - Maximum amount of time to wait when performing each configuration
      Returns:
      Status code of the first failed config call, or OK if all succeeded

    • periodic

      public final void periodic()
      Call this method periodically to automatically protect against dangerous fault conditions and keep getMechanismState() updated.

    • isDisabled

      public final boolean isDisabled()
      Get whether the mechanism is currently disabled due to an issue.
      Returns:
      true if the mechanism is temporarily disabled

    • requiresUserAction

      public final boolean requiresUserAction()
      Get whether the mechanism is currently disabled and requires user action to re-enable mechanism control.
      Returns:
      true if the mechanism is disabled and the user must manually perform an action

    • getMechanismState

      public final MechanismState getMechanismState()
      Gets the state of the mechanism.
      Returns:
      MechanismState representing the state of the mechanism

    • clearUserRequirement

      public final void clearUserRequirement()
      Indicate to the mechanism that the user has performed the required action to resume mechanism control.

    • getDisabledReason

      public final SimpleDifferentialMechanism.DisabledReasonValue getDisabledReason()
      Returns:
      The reason for the mechanism being disabled

    • getRequiresUserReason

      public final SimpleDifferentialMechanism.RequiresUserReasonValue getRequiresUserReason()
      Returns:
      The reason for the mechanism requiring user action to resume control

    • getAveragePosition

      public final StatusSignal<Angle> getAveragePosition()
      Average component of the mechanism position.
      • Minimum Value: -16384.0
      • Maximum Value: 16383.999755859375
      • Default Value: 0
      • Units: rotations

      This refreshes and returns a cached StatusSignal object.

      Returns:
      DifferentialAveragePosition Status Signal Object

    • getAveragePosition

      public final StatusSignal<Angle> getAveragePosition(boolean refresh)
      Average component of the mechanism position.
      • Minimum Value: -16384.0
      • Maximum Value: 16383.999755859375
      • Default Value: 0
      • Units: rotations

      This refreshes and returns a cached StatusSignal object.

      Parameters:
      refresh - Whether to refresh the StatusSignal before returning it; defaults to true
      Returns:
      DifferentialAveragePosition Status Signal Object

    • getAverageVelocity

      public final StatusSignal<AngularVelocity> getAverageVelocity()
      Average component of the mechanism velocity.
      • Minimum Value: -512.0
      • Maximum Value: 511.998046875
      • Default Value: 0
      • Units: rotations per second

      This refreshes and returns a cached StatusSignal object.

      Returns:
      DifferentialAverageVelocity Status Signal Object

    • getAverageVelocity

      public final StatusSignal<AngularVelocity> getAverageVelocity(boolean refresh)
      Average component of the mechanism velocity.
      • Minimum Value: -512.0
      • Maximum Value: 511.998046875
      • Default Value: 0
      • Units: rotations per second

      This refreshes and returns a cached StatusSignal object.

      Parameters:
      refresh - Whether to refresh the StatusSignal before returning it; defaults to true
      Returns:
      DifferentialAverageVelocity Status Signal Object

    • getDifferentialPosition

      public final StatusSignal<Angle> getDifferentialPosition()
      Differential component of the mechanism position.
      • Minimum Value: -16384.0
      • Maximum Value: 16383.999755859375
      • Default Value: 0
      • Units: rotations

      This refreshes and returns a cached StatusSignal object.

      Returns:
      DifferentialDifferencePosition Status Signal Object

    • getDifferentialPosition

      public final StatusSignal<Angle> getDifferentialPosition(boolean refresh)
      Differential component of the mechanism position.
      • Minimum Value: -16384.0
      • Maximum Value: 16383.999755859375
      • Default Value: 0
      • Units: rotations

      This refreshes and returns a cached StatusSignal object.

      Parameters:
      refresh - Whether to refresh the StatusSignal before returning it; defaults to true
      Returns:
      DifferentialDifferencePosition Status Signal Object

    • getDifferentialVelocity

      public final StatusSignal<AngularVelocity> getDifferentialVelocity()
      Differential component of the mechanism velocity.
      • Minimum Value: -512.0
      • Maximum Value: 511.998046875
      • Default Value: 0
      • Units: rotations per second

      This refreshes and returns a cached StatusSignal object.

      Returns:
      DifferentialDifferenceVelocity Status Signal Object

    • getDifferentialVelocity

      public final StatusSignal<AngularVelocity> getDifferentialVelocity(boolean refresh)
      Differential component of the mechanism velocity.
      • Minimum Value: -512.0
      • Maximum Value: 511.998046875
      • Default Value: 0
      • Units: rotations per second

      This refreshes and returns a cached StatusSignal object.

      Parameters:
      refresh - Whether to refresh the StatusSignal before returning it; defaults to true
      Returns:
      DifferentialDifferenceVelocity Status Signal Object

    • getAverageClosedLoopReference

      public final StatusSignal<Double> getAverageClosedLoopReference()
      Value that the average closed loop is targeting.

      This is the value that the closed loop PID controller targets.

      This refreshes and returns a cached StatusSignal object.

      Returns:
      ClosedLoopReference Status Signal object

    • getAverageClosedLoopReference

      public final StatusSignal<Double> getAverageClosedLoopReference(boolean refresh)
      Value that the average closed loop is targeting.

      This is the value that the closed loop PID controller targets.

      This refreshes and returns a cached StatusSignal object.

      Parameters:
      refresh - Whether to refresh the StatusSignal before returning it; defaults to true
      Returns:
      ClosedLoopReference Status Signal object

    • getAverageClosedLoopReferenceSlope

      public final StatusSignal<Double> getAverageClosedLoopReferenceSlope()
      Derivative of the target that the average closed loop is targeting.

      This is the change in the closed loop reference. This may be used in the feed-forward calculation, the derivative-error, or in application of the signage for kS. Typically, this represents the target velocity during Motion Magic®.

      This refreshes and returns a cached StatusSignal object.

      Returns:
      ClosedLoopReferenceSlope Status Signal object

    • getAverageClosedLoopReferenceSlope

      public final StatusSignal<Double> getAverageClosedLoopReferenceSlope(boolean refresh)
      Derivative of the target that the average closed loop is targeting.

      This is the change in the closed loop reference. This may be used in the feed-forward calculation, the derivative-error, or in application of the signage for kS. Typically, this represents the target velocity during Motion Magic®.

      This refreshes and returns a cached StatusSignal object.

      Parameters:
      refresh - Whether to refresh the StatusSignal before returning it; defaults to true
      Returns:
      ClosedLoopReferenceSlope Status Signal object

    • getAverageClosedLoopError

      public final StatusSignal<Double> getAverageClosedLoopError()
      The difference between target average reference and current measurement.

      This is the value that is treated as the error in the PID loop.

      This refreshes and returns a cached StatusSignal object.

      Returns:
      ClosedLoopError Status Signal object

    • getAverageClosedLoopError

      public final StatusSignal<Double> getAverageClosedLoopError(boolean refresh)
      The difference between target average reference and current measurement.

      This is the value that is treated as the error in the PID loop.

      This refreshes and returns a cached StatusSignal object.

      Parameters:
      refresh - Whether to refresh the StatusSignal before returning it; defaults to true
      Returns:
      ClosedLoopError Status Signal object

    • getDifferentialClosedLoopReference

      public final StatusSignal<Double> getDifferentialClosedLoopReference()
      Value that the differential closed loop is targeting.

      This is the value that the differential closed loop PID controller targets (on the difference axis).

      This refreshes and returns a cached StatusSignal object.

      Returns:
      DifferentialClosedLoopReference Status Signal object

    • getDifferentialClosedLoopReference

      public final StatusSignal<Double> getDifferentialClosedLoopReference(boolean refresh)
      Value that the differential closed loop is targeting.

      This is the value that the differential closed loop PID controller targets (on the difference axis).

      This refreshes and returns a cached StatusSignal object.

      Parameters:
      refresh - Whether to refresh the StatusSignal before returning it; defaults to true
      Returns:
      DifferentialClosedLoopReference Status Signal object

    • getDifferentialClosedLoopReferenceSlope

      public final StatusSignal<Double> getDifferentialClosedLoopReferenceSlope()
      Derivative of the target that the differential closed loop is targeting.

      This is the change in the closed loop reference (on the difference axis). This may be used in the feed-forward calculation, the derivative-error, or in application of the signage for kS. Typically, this represents the target velocity during Motion Magic®.

      This refreshes and returns a cached StatusSignal object.

      Returns:
      DifferentialClosedLoopReferenceSlope Status Signal object

    • getDifferentialClosedLoopReferenceSlope

      public final StatusSignal<Double> getDifferentialClosedLoopReferenceSlope(boolean refresh)
      Derivative of the target that the differential closed loop is targeting.

      This is the change in the closed loop reference (on the difference axis). This may be used in the feed-forward calculation, the derivative-error, or in application of the signage for kS. Typically, this represents the target velocity during Motion Magic®.

      This refreshes and returns a cached StatusSignal object.

      Parameters:
      refresh - Whether to refresh the StatusSignal before returning it; defaults to true
      Returns:
      DifferentialClosedLoopReferenceSlope Status Signal object

    • getDifferentialClosedLoopError

      public final StatusSignal<Double> getDifferentialClosedLoopError()
      The difference between target differential reference and current measurement.

      This is the value that is treated as the error in the differential PID loop (on the difference axis).

      This refreshes and returns a cached StatusSignal object.

      Returns:
      DifferentialClosedLoopError Status Signal object

    • getDifferentialClosedLoopError

      public final StatusSignal<Double> getDifferentialClosedLoopError(boolean refresh)
      The difference between target differential reference and current measurement.

      This is the value that is treated as the error in the differential PID loop (on the difference axis).

      This refreshes and returns a cached StatusSignal object.

      Parameters:
      refresh - Whether to refresh the StatusSignal before returning it; defaults to true
      Returns:
      DifferentialClosedLoopError Status Signal object

    • setPosition

      public final StatusCode setPosition(double avgPosition)
      Sets the position of the mechanism in rotations, assuming a differential position of 0 rotations.

      This will wait up to 0.100 seconds (100ms) by default.

      Parameters:
      avgPosition - The average position of the mechanism, in rotations
      Returns:
      StatusCode of the set command

    • setPosition

      public final StatusCode setPosition(double avgPosition, double diffPosition)
      Sets the position of the mechanism in rotations.

      This will wait up to 0.100 seconds (100ms) by default.

      Parameters:
      avgPosition - The average position of the mechanism, in rotations
      diffPosition - The differential position of the mechanism, in rotations
      Returns:
      StatusCode of the set command

    • setPosition

      public final StatusCode setPosition(double avgPosition, double diffPosition, double timeoutSeconds)
      Sets the position of the mechanism in rotations.
      Parameters:
      avgPosition - The average position of the mechanism, in rotations
      diffPosition - The differential position of the mechanism, in rotations
      timeoutSeconds - Maximum time to wait up to in seconds
      Returns:
      StatusCode of the set command

    • setPosition

      public final StatusCode setPosition(Angle avgPosition)
      Sets the position of the mechanism, assuming a differential position of 0 rotations.

      This will wait up to 0.100 seconds (100ms) by default.

      Parameters:
      avgPosition - The average position of the mechanism
      Returns:
      StatusCode of the set command

    • setPosition

      public final StatusCode setPosition(Angle avgPosition, Angle diffPosition)
      Sets the position of the mechanism.

      This will wait up to 0.100 seconds (100ms) by default.

      Parameters:
      avgPosition - The average position of the mechanism
      diffPosition - The differential position of the mechanism
      Returns:
      StatusCode of the set command

    • setPosition

      public final StatusCode setPosition(Angle avgPosition, Angle diffPosition, double timeoutSeconds)
      Sets the position of the mechanism.
      Parameters:
      avgPosition - The average position of the mechanism
      diffPosition - The differential position of the mechanism
      timeoutSeconds - Maximum time to wait up to in seconds
      Returns:
      StatusCode of the set command

    • getLeader

      public final MotorT getLeader()
      Get the Talon FX that is differential leader. The differential leader calculates the output for the differential follower. The differential leader is also useful for fault detection, and it reports status signals for the differential controller.
      Returns:
      Differential leader Talon FX

    • getFollower

      public final MotorT getFollower()
      Get the Talon FX that is differential follower. The differential follower's position and velocity are used by the differential leader for the differential controller.
      Returns:
      Differential follower Talon FX

    • setNeutralOut

      public final StatusCode setNeutralOut()
      Request neutral output of mechanism. The applied brake type is determined by the NeutralMode configuration of each device.

      Since the NeutralMode configuration of devices may not align, users may prefer to use the setCoastOut() or setStaticBrake() method.

      Returns:
      Status Code of the request.

    • setCoastOut

      public final StatusCode setCoastOut()
      Request coast neutral output of mechanism. The bridge is disabled and the rotor is allowed to coast.
      Returns:
      Status Code of the request.

    • setStaticBrake

      public final StatusCode setStaticBrake()
      Applies full neutral-brake on the mechanism by shorting motor leads together.
      Returns:
      Status Code of the request.

    • setControl

      public final StatusCode setControl(DifferentialDutyCycle diffLeaderFXRequest)
      Sets the control request for this mechanism.
      Parameters:
      diffLeaderFXRequest - Request a specified motor duty cycle with a differential position closed-loop.
      Returns:
      Status Code of the request.

    • setControl

      public final StatusCode setControl(DifferentialVoltage diffLeaderFXRequest)
      Sets the control request for this mechanism.
      Parameters:
      diffLeaderFXRequest - Request a specified voltage with a differential position closed-loop.
      Returns:
      Status Code of the request.

    • setControl

      public final StatusCode setControl(DifferentialPositionDutyCycle diffLeaderFXRequest)
      Sets the control request for this mechanism.
      Parameters:
      diffLeaderFXRequest - Request PID to target position with a differential position setpoint.
      Returns:
      Status Code of the request.

    • setControl

      public final StatusCode setControl(DifferentialPositionVoltage diffLeaderFXRequest)
      Sets the control request for this mechanism.
      Parameters:
      diffLeaderFXRequest - Request PID to target position with a differential position setpoint
      Returns:
      Status Code of the request.

    • setControl

      public final StatusCode setControl(DifferentialVelocityDutyCycle diffLeaderFXRequest)
      Sets the control request for this mechanism.
      Parameters:
      diffLeaderFXRequest - Request PID to target velocity with a differential position setpoint.
      Returns:
      Status Code of the request.

    • setControl

      public final StatusCode setControl(DifferentialVelocityVoltage diffLeaderFXRequest)
      Sets the control request for this mechanism.
      Parameters:
      diffLeaderFXRequest - Request PID to target velocity with a differential position setpoint.
      Returns:
      Status Code of the request.

    • setControl

      public final StatusCode setControl(DifferentialMotionMagicDutyCycle diffLeaderFXRequest)
      Sets the control request for this mechanism.
      Parameters:
      diffLeaderFXRequest - Requests Motion Magic® to target a final position using a motion profile, and PID to a differential position setpoint.
      Returns:
      Status Code of the request.

    • setControl

      public final StatusCode setControl(DifferentialMotionMagicVoltage diffLeaderFXRequest)
      Sets the control request for this mechanism.
      Parameters:
      diffLeaderFXRequest - Requests Motion Magic® to target a final position using a motion profile, and PID to a differential position setpoint.
      Returns:
      Status Code of the request.

    • setControl

      public final StatusCode setControl(DifferentialMotionMagicExpoDutyCycle diffLeaderFXRequest)
      Sets the control request for this mechanism.
      Parameters:
      diffLeaderFXRequest - Requests Motion Magic® to target a final position using an exponential motion profile, and PID to a differential position setpoint.
      Returns:
      Status Code of the request.

    • setControl

      public final StatusCode setControl(DifferentialMotionMagicExpoVoltage diffLeaderFXRequest)
      Sets the control request for this mechanism.
      Parameters:
      diffLeaderFXRequest - Requests Motion Magic® to target a final position using an exponential motion profile, and PID to a differential position setpoint.
      Returns:
      Status Code of the request.

    • setControl

      public final StatusCode setControl(DifferentialMotionMagicVelocityDutyCycle diffLeaderFXRequest)
      Sets the control request for this mechanism.
      Parameters:
      diffLeaderFXRequest - Requests Motion Magic® to target a final velocity using a motion profile, and PID to a differential position setpoint. This allows smooth transitions between velocity set points.
      Returns:
      Status Code of the request.

    • setControl

      public final StatusCode setControl(DifferentialMotionMagicVelocityVoltage diffLeaderFXRequest)
      Sets the control request for this mechanism.
      Parameters:
      diffLeaderFXRequest - Requests Motion Magic® to target a final velocity using a motion profile, and PID to a differential position setpoint. This allows smooth transitions between velocity set points.
      Returns:
      Status Code of the request.