Skip to content

Faults & error codes ​

There are two different things here:

  • Robot faults are latched conditions that put the robot into faulted (or emergency_stopped) and disable the drives. They appear in telemetry's fault field.
  • Error codes are returned when a single request is refused. The robot's state doesn't change.

Robot faults ​

CodeDetected byCauseResponse
communication_lostMCU watchdog or engineMCU heard nothing from the host for watchdog_ms (e.g. USB unplugged, host hung); or the engine heard nothing from the MCU for 1 s, or the stream closedDrives disabled, queue flushed. The engine attempts to reconnect
queue_underrunMCUThe segment queue ran dry in the middle of a moveDrives disabled
segment_lateMCUA segment started too late, or the step tick stalled during motionDrives disabled; no catch-up steps
limit_hitMCUEndstop triggered while moving toward the switchNo further step; drives disabled. Reset is refused while the axis is still on the switch with no known safe direction — move it off by hand
soft_limitengine (planning) and MCU (per step)Motion would leave [min, max]Request rejected by the engine; if the MCU catches it, drives disabled
homing_failedMCUNo endstop trigger within max_travelDrives disabled
mcu_faultMCUOther firmware fault, e.g. StepRateExceeded on RP2040 when PIO output falls behind or a window's steps don't fit the pulse timingDrives disabled
plugin_failedplugin runtimeA plugin the robot requires failedPlugin and its dependents marked failed
emergency_stopengine + MCUSoftware E-stop, or on RP2040 the GP27 interlock openedLatched emergency_stopped, drives disabled

Clearing a fault ​

  1. Remove the cause: reconnect the cable, close the interlock, move off the switch by hand with drives off, and so on.
  2. reset-fault (CLI), POST /api/commands/reset_fault, or ResetFault (gRPC).
  3. The robot lands in disabled (or disconnected if the MCU link is down). It never resumes the interrupted motion.
  4. enable and re-home every axis; faults clear the homed flag.

Every fault latched by the MCU disables all drives. Only the first fault is recorded; later faults don't overwrite it.

The MCU refuses a reset until the hazard is verifiably gone: it is refused while any drive is enabled or moving, while an endstop that caused limit_hit is still pressed, and on RP2040 while the GP27 interlock is open.

HTTP error codes ​

Through the ratavyr gateway, these codes are returned as HTTP statuses with a JSON error envelope. See ratavyr: error codes.

gRPC error codes ​

The engine returns gRPC status codes, with the precise code in the trailer motioncore-error-code:

CodegRPC status
bad_request, validation_failedINVALID_ARGUMENT
unknown_axis, not_foundNOT_FOUND
not_homed, invalid_stateFAILED_PRECONDITION
mcu_errorUNAVAILABLE
internalINTERNAL

MCU NACK reasons ​

Inside the MCU protocol, the firmware refuses individual frames with a NACK. These surface to clients as mcu_error or as a fault.

ReasonMeaning
UnknownAxisChannel not configured
QueueFullSegment queue full
InvalidStateNot allowed in the MCU's current state
InvalidParamsParameters failed validation
SoftLimitWould leave the soft limits
FaultedA fault is latched
BusyAxis is moving

Apache-2.0 OR MIT. Not a certified safety system — always use an independent hardware E-stop.