Skip to content

Engine gRPC API ​

The engine's control API is gRPC package motioncore.engine.v1. ratavyr and the motioncore CLI are clients of it; you can write your own in any language with gRPC support.

Connecting ​

PlatformDefault address
Linuxunix:///run/motioncore/engine.sock
Windows, macOS127.0.0.1:7600 (plain TCP)

There is no authentication at this layer: filesystem permissions or loopback are the boundary. Never expose the engine on a network; put ratavyr in front.

Clients should call GetInfo first and refuse to continue unless api_version has major version 1.

Errors ​

Errors are gRPC status codes. The precise MotionCore code is in the trailing metadata key motioncore-error-code:

motioncore-error-codegRPC status
bad_requestINVALID_ARGUMENT
validation_failedINVALID_ARGUMENT
unknown_axisNOT_FOUND
not_foundNOT_FOUND
not_homedFAILED_PRECONDITION
invalid_stateFAILED_PRECONDITION
mcu_errorUNAVAILABLE
internalINTERNAL

Positions, deltas and velocities are in the axis display unit (deg or mm).

EngineService ​

RPCRequestResponseNotes
GetInfo–EngineInfoHandshake. Check api_version
GetStatus–TelemetryCurrent snapshot
GetRobotConfig–RobotConfigLoaded configuration
ListPlugins–ListPluginsResponse
StreamEvents–stream of EventTelemetry (~20 Hz) and log entries. The first event is always a telemetry snapshot
Enable–CommandResponse
Disable–CommandResponseControlled stop if moving, then drive disable
Jogaxis, delta, optional velocityCommandResponseDefault velocity: axis maximum (25 % when unhomed)
MoveToaxis, position, optional velocityCommandResponseAxis must be homed
HomeaxisCommandResponse
Stop–CommandResponseControlled stop
EmergencyStop–CommandResponseLatches emergency_stopped
ResetFault–CommandResponseNever resumes motion; drives stay disabled; re-home required
DebugDisconnectMcu–CommandResponseOnly with --enable-fault-injection; otherwise FAILED_PRECONDITION
DebugFailPluginidCommandResponseSame

Command RPCs return when the engine has accepted the command. Follow progress through StreamEvents.

FirmwareService ​

Firmware build and flash, delegated to the restricted Rust builder. Builds always use the robot configuration the engine loaded; clients cannot supply paths, scripts or toolchains.

RPCRequestResponseNotes
ListTargets–ListTargetsResponseSupported boards
StartBuildmcuFirmwareJobmcu may be empty when the robot has one MCU
StartFlashbuild_job_id, confirmFirmwareJobRequires confirm = true and drives not energised
GetJobidFirmwareJob
ListJobs–ListJobsResponse

Messages ​

EngineInfo ​

FieldTypeMeaning
api_versionstringSemantic version of this contract, e.g. 1.0.0
engine_versionstring
mcu_protocol_versionuint32MCU wire protocol version
plugin_api_versionstringHost plugin API version
fault_injection_enabledbool

Telemetry ​

FieldTypeMeaning
sequint64Monotonic per engine process; gaps mean dropped samples
time_msuint64Milliseconds since engine start
stateRobotState
faultoptional FaultUnset when no fault is latched
mcuMcuTelemetry
axesrepeated AxisTelemetry

Fault: code (FaultCode), message, axis (empty when not axis-specific).

McuTelemetry ​

FieldTypeMeaning
connectedbool
transportstringvirtual, tcp or serial
target, board, firmware_version, build_hashstringEmpty until the MCU identifies itself
protocol_versionuint32
capabilitiesrepeated stringe.g. stepper.step_dir, endstop, watchdog
queue_capacity, queue_depthuint32MCU segment queue
clock_offset_usint64MCU clock vs. host clock
rtt_usuint32Round-trip time
tx_frames, rx_frames, crc_errorsuint64Link counters
last_heartbeat_ms_agooptional uint64Unset while no link exists

AxisTelemetry ​

id, homed, enabled, commanded_position, measured_position (from the MCU step counter; no encoder feedback in v1.0), velocity, endstop.

RobotConfig, McuConfig, AxisConfig ​

RobotConfig: name, profile, axes, mcus. McuConfig: name, board, transport, watchdog_ms. AxisConfig: id, name, kind (JointKind), unit, min, max, max_velocity, max_acceleration, optional home_position, steps_per_unit, mcu, mcu_channel, actuator, step_pin, dir_pin, enable_pin, endstop_pin (empty when there is no endstop).

Plugin ​

id, version, api_version, kind (builtin or wasm), description, provides, requires, permissions, state (PluginState), error (empty unless failed).

Event ​

A oneof: telemetry (Telemetry) or log (LogEntry: time_ms, level, message).

FirmwareTarget ​

board, description, firmware_target (empty for virtual), rust_target, step_channels, max_step_rate, provisional, is_virtual.

FirmwareJob ​

id, kind (JobKind), state (JobState), mcu, created_unix, finished_unix, message (summary of the outcome), log (tail of the build/flash log), optional artifact.

FirmwareArtifact: board, firmware_version, build_hash, image_sha256, toolchain, required_capabilities.

Enums ​

EnumValues (after the UNSPECIFIED = 0 entry)
RobotStateDISCONNECTED, INITIALIZING, DISABLED, READY, HOMING, RUNNING, FAULTED, EMERGENCY_STOPPED
FaultCodeCOMMUNICATION_LOST, QUEUE_UNDERRUN, SEGMENT_LATE, LIMIT_HIT, SOFT_LIMIT, HOMING_FAILED, MCU_FAULT, PLUGIN_FAILED, EMERGENCY_STOP
JointKindREVOLUTE, PRISMATIC
PluginStateDISCOVERED, VALIDATED, RESOLVED, INITIALIZED, ACTIVE, FAILED, DEACTIVATED
LogLevelDEBUG, INFO, WARN, ERROR
JobKindBUILD, FLASH
JobStateQUEUED, RUNNING, SUCCEEDED, FAILED

Each value is prefixed with the enum name in the proto, e.g. ROBOT_STATE_READY. A newer 1.x engine may add values; clients must handle unknown ones.

Compatibility rules for v1 ​

  • Only additive changes: new fields, messages, RPCs and enum values.
  • Field numbers are never reused; removed fields are reserved.
  • Breaking changes require a new package, motioncore.engine.v2.

See Contracts & versioning.

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