The Grafito CAN Stepper Protocol v1 is the contract between hosts and boards. The Python reference codec is canstepper/protocol.py; the firmware implements the same tables.

Physical layer

• CAN 2.0A, standard 11-bit identifiers, 1 Mbps.
• Daisy-chain, 120 Ω termination at both physical ends, up to 31 nodes.

Addressing

CAN ID (11 bit) = (node_id << 6) | msg_id

• All multi-byte values are little-endian.
• A remote frame (RTR) with a telemetry msg_id polls that telemetry.
• Nodes broadcast telemetry periodically: the fast group (POSITION, MOTION, PID_STATUS) at fast_rate_hz (default 10 Hz), the slow group (STATUS, DRIVER, ENV, FOLLOW_STATUS, CAN_HEALTH) at slow_rate_hz (default 1 Hz). Rate 0 disables a group.

Serial bridge

Any node bridges its USB CDC port (115200 baud) to the bus; one text line per frame in each direction:

<CAN_ID hex> <RTR 0|1> <payload hex>\n

Example — move node 1 to 180°: 44 0 0000000000C06640 (0x44 = (1 shl 6) or 4 = MOVE_ABS; payload is f64 180.0).

• Payload length = hex digits / 2 (0–8 bytes). RTR lines carry no payload.
• Lines starting with # are debug output — skip them.
• The bridging node executes frames addressed to it (or broadcast) and re-transmits them on CAN; everything it sees on the bus, plus its own telemetry, is printed to the port.

Commands (msg_id 0–31)

Closed-loop motion profile (firmware ≥1.2)

When closed_loop = 1 and the node receives MOVE_ABS / MOVE_REL:

1. Plan a rest-to-rest trapezoid (or triangle if short) from the encoder angle to the target using vmax = min(max_speed, cl_max_speed) and amax = cl_max_accel.
2. Each 5 ms: reference position r(t) and feedforward velocity v_ff(t).
3. Track: v_cmd = v_ff + Kp·(r − encoder) + Ki·∫ − Kd·v_meas.
4. Settle when the plan is finished, |target − encoder| ≤ pid_tolerance, and speed is low → MOVE_DONE (event 7).

Open-loop position uses FastAccelStepper’s trapezoid on step counts. MOVE_VEL is open-loop continuous velocity. FOLLOW with encoder correction uses a continuous braking-law chase (not a full re-planned trap each frame).

Tuning, measured RPM, and soak data: Closed-loop speed tuning.

Parameters

4-byte values, u32 or f32. Ranges are hardware-sanity checks only — motion limits are configurable defaults, never firmware clamps. Persisted by SAVE_CONFIG, loaded at power-on.

Telemetry (msg_id 32–63)

STATUS flag bits

Enumerations

• mode: 0 idle, 1 position, 2 velocity, 3 homing, 4 following
• fault: 0 none, 1 encoder invalid, 2 no progress, 3 homing timeout
• event: 1 boot, 2 endstop hit, 3 endstop released, 4 stall, 5 homing done, 6 homing failed, 7 move done, 8 e-stop, 9 fault (data is usually the position in degrees at the event)

Leader / follower

FOLLOW makes a node track another node's POSITION broadcasts entirely on-bus. The first leader frame after enable (or FOLLOW_SYNC) captures both zero references, so engagement never jumps:

follower = local_ref + (leader − leader_ref) × ratio × (invert ? −1 : 1)

With flags bit1 the follower closes its own encoder loop on the mapped target (recommended); otherwise it steps open-loop. A 0.15° hysteresis deadband rejects stationary leader-encoder noise without adding lag.

Bus load

A 1 Mbps standard frame with 8-byte payload is roughly 111–135 bits with stuffing. At default rates (about 35 frames/s per node), 31 nodes produce about 1085 frames/s — roughly 15 % bus load. Budget accordingly when raising fast_rate_hz.