Skip to content

Robot configuration ​

A robot is described by one TOML file: its MCU, its axes, and how each axis is wired. The engine loads it at start (motioncore start --config FILE), and the firmware builder uses the same file to generate firmware.

For every key and its constraints, see the configuration schema reference. This page walks through writing one.

A minimal profile ​

This is the shipped robot-profiles/single-axis-virtual.toml: one revolute axis on the virtual MCU.

toml
schema = 1

[robot]
name = "single-axis-bench"
profile = "org.motioncore.robot.single_axis"

[mcu.main]
board = "virtual"
transport = "virtual"
watchdog_ms = 500

[[axis]]
id = "j1"
name = "Base"
kind = "revolute"
unit = "deg"
mcu = "main"
channel = 0
# 200 steps/rev * 8 microsteps * 10:1 gearbox / 360 deg
steps_per_unit = 44.444444
min = -170.0
max = 170.0
max_velocity = 90.0
max_acceleration = 360.0

[axis.driver]
actuator = "org.motioncore.actuator.step_dir"
step_pin = "STEP0"
dir_pin = "DIR0"
enable_pin = "EN0"

[axis.endstop]
pin = "ENDSTOP0"

[axis.homing]
direction = "negative"
speed = 30.0
position = -170.0
max_travel = 360.0

Step by step ​

1. Robot and profile plugin ​

robot.profile names a robot-profile plugin, which must be active. For now, use the builtin org.motioncore.robot.single_axis. Each axis's driver.actuator names an actuator plugin; use org.motioncore.actuator.step_dir. See Plugins.

2. The MCU ​

Pick a board and a transport:

boardtransport examples
virtual"virtual" (in-process) or "tcp://127.0.0.1:7700" (out-of-process simulator)
stm32f411-blackpill"serial:///dev/ttyACM0"
rp2040-pico"serial:///dev/ttyACM0" (COMx on Windows)

watchdog_ms is how long the MCU waits without hearing from the host before it disables every drive. The default of 500 ms is a good start.

v0.2 supports exactly one MCU per robot.

3. Axes: units and steps ​

Each [[axis]] is one motor. kind = "revolute" uses degrees; kind = "prismatic" uses millimetres. All positions, velocities and accelerations are in that unit.

steps_per_unit converts units to motor steps:

text
steps_per_unit = full steps per rev × microsteps × gear ratio / units per output rev
ExampleCalculationResult
Revolute joint, 1.8° motor, 8× microstepping, 10:1 gearbox200 × 8 × 10 / 36044.444444 steps/°
Lead screw, 1.8° motor, 16× microstepping, 8 mm lead200 × 16 / 8400 steps/mm

4. Limits ​

  • min / max are soft limits, enforced by both the planner and the MCU.
  • max_velocity × steps_per_unit must not exceed the board's maximum step rate (motioncore firmware targets lists it). For example, on RP2040 (50 000 steps/s advertised), 44.44 steps/° allows up to 1125 °/s.
  • stop_deceleration defaults to twice max_acceleration. It is used by stop and by a controlled stop on disable.

5. Wiring ​

channel selects the MCU's step output, and the pin names must match the board's fixed firmware pin map. The resolver rejects a mismatch with a specific message, for example:

text
board 'rp2040-pico' firmware wires channel 1 driver.step_pin to GP2

Pin maps: STM32F411, RP2040. The virtual board has no fixed pin map, so any names work there; the shipped profiles use STEPn, DIRn, ENn, ENDSTOPn by convention. Pins must still be unique.

Add [axis.endstop] with the switch's pin, and invert = true for a normally-closed switch. With an endstop, [axis.homing] tells the axis to search in direction at speed until the switch triggers, then to set its position to position. Homing fails if the switch is not found within max_travel.

Without homing, an axis can only be jogged relatively, at 25 % speed. See Moving axes.

Validation ​

The configuration is validated by the device graph when the engine starts and when you build firmware:

  • schema must be 1; unknown keys are errors (so typos don't silently fall back to defaults).
  • All problems are reported at once, each with a path such as axis[0](j1).driver.dir_pin.
  • Axis ids must be unique; channels and pins must be unique per MCU; channels must exist on the board.
  • Pins must match the board's firmware pin map.
  • Homing requires an endstop, a speed ≤ max_velocity, and a position within [min, max].

To check a file without starting the engine, run the firmware configure step, which resolves the configuration and prints the lockfile:

bash
motioncore firmware configure --config my-robot.toml

Shipped profiles ​

FileBoardAxes
robot-profiles/single-axis-virtual.tomlvirtual1
robot-profiles/single-axis-stm32f411.tomlstm32f411-blackpill1
robot-profiles/six-axis-rp2040-pico.tomlrp2040-pico6, with endstops and homing

Changing the configuration ​

The engine reads the file only at start. There is no configuration-editing API yet: edit the TOML and restart the engine. The UI's Robot Composer is read-only for the same reason. If you change pins, channels or boards, rebuild and reflash the firmware too.

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