Skip to content

Moteus Debugging

Jump to bottom
Ian Lansdowne edited this page Apr 15, 2026 · 1 revision

Fault Codes

From the docs:

A fault code which will be set if the primary mode is 1 (Fault).

  • 32 - calibration fault - the encoder was not able to sense a magnet during calibration
  • 33 - motor driver fault - the most common reason for this is undervoltage, moteus attempted to draw more current than the supply could provide. Other electrical faults may also report this error, the drv8323 diagnostic tree has more information.
  • 34 - over voltage - the bus voltage exceeded servo.max_voltage. This can happen due to misconfiguration, or if the controller regenerated power with a supply that cannot sink power and no flux braking was configured.
  • 35 - encoder fault - the encoder readings are not consistent with a magnet being present.
  • 36 - motor not configured - the moteus_tool --calibrate procedure has not been run on this motor.
  • 37 - pwm cycle overrun - an internal firmware error
  • 38 - over temperature - the maximum configured temperature has been exceeded
  • 39 - outside limit - an attempt was made to start position control while outside the bounds configured by servopos.position_min and servopos.position_max.
  • 40 - under voltage - the voltage was too low
  • 41 - config changed - a configuration value was changed during operation that requires a stop
  • 42 - theta invalid - no valid commutation encoder is available
  • 43 - position invalid - no valid output encoder is available
  • 44 - driver enable fault - the MOSFET gate driver could not be enabled
  • 45 - stop position deprecated - an attempt was made to use the deprecated "stop position" feature along with velocity or acceleration limits. Prefer to instead command the desired position directly with a target velocity of 0.0, or secondarily, disable acceleration and velocity limits.
  • 46 - timing violation - internal checks are enabled, and the controller violated an internal timing constraint
  • 47 - bemf feedforward no accel - servo.bemf_feedforward is configured, but no acceleration limit was specified. If you really know what you are doing, you can disable this with servo.bemf_feedforward_override.
  • 48 - invalid limits - servopos.position_min or servopos.position_max are finite and outside the available position range

Some non-zero codes can be presented during valid control modes without a fault. These indicate which, if any, function is limiting the output power of the controller.

  • 96 - servo.max_velocity
  • 97 - servo.max_power_W
  • 98 - the maximum system voltage
  • 99 - servo.max_current_A
  • 100 - servo.fault_temperature
  • 101 - servo.motor_fault_temperature
  • 102 - the commanded maximum torque
  • 103 - servopos.position_min or servopos.position_max

Output Limit Reasons

From the docs:

As of firmware version 2025-07-21, the firmware will report if a factor is limiting the output current via the "fault" register while in position mode. The set of possible values are:

  • 96 max_velocity: Maximum velocity: If the observed velocity exceeds the configured maximum velocity, torque is limited in the direction that would cause the velocity to increase. This is configured with servo.max_velocity.
  • 97 max_power: Maximum power: The total power of the output is limited through a combination of a board power profile and servo.max_power_W. See this post for more.
  • 98 BEMF: Maximum system voltage: The supply voltage, combined with the back EMF of the motor and the phase resistance does not permit more current to be applied.
  • 99 max_current: Maximum current: There is a system wide maximum output phase current that is configured in servo.max_current_A.
  • 100 fault_temperature: Temperature: The onboard FET temperature sensor can limit the output current. This threshold is set in the current firmware with servo.fault_temperature/servo.temperature_margin.
  • 101 motor_temperature: Temperature: The motor temperature sensor can also limit the output current. This is configured in servo.motor_fault_temperature/servo.motor_temperature_margin.
  • 102 max_torque: Maximum torque: With each position mode command, the client can specify a maximum torque to use. If the combination of the onboard PID and commanded feedforward torque exceeds this, then limiting occurs.
  • 103 position_bounds: Position bounds: If the current position is outside of servopos.position_min and servopos.position_max, then torque is limited in the direction that would push the motor further outside the bounds.
  • 104 flux_braking: Flux braking: The input voltage is too high and the controller is dissipating energy in the motor windings.

Control Modes

kStopped = 0,
kFault = 1,
kEnabling = 2,
kCalibrating = 3,
kCalibrationComplete = 4,
kPwm = 5,
kVoltage = 6,
kVoltageFoc = 7,
kVoltageDq = 8,
kCurrent = 9,
kPosition = 10,
kPositionTimeout = 11,
kZeroVelocity = 12,
kStayWithin = 13,
kMeasureInd = 14,
kBrake = 15,

Clone this wiki locally