Why this is worth more than another chat demo

Talk is cheap. A body that reports what it can do, and refuses what it cannot, is the scarce part.

Three roles. Do not mix them.

What is running in the lab

Not a product SKU. A working splice on protocol V3: master, LED, and speaker.

• Master on ESP32-C6. Organs: LED board, I2S speaker (MAX98357 class)
• Bus: point-to-point UART, 115200 8N1, crossed TX / RX, shared ground. Boards are powered separately — do not parallel 5 V
• An organ powers on, sends a descriptor, then a heartbeat. The master ACKs. An unknown action returns fail, not a guessed alias
• Named actions, not a keyword map. Speak text is written by the model; the speaker plays it
• A local loop keeps the body alive when nobody is typing

Protocol V3 — the public frame

This is the contract the lab is running. Version 3. Master + LED + speaker already talk on this frame. A new organ implements this file, not a fork of the master.

Rules the body must not break

• The body reports a contract: named abilities, min / max, max steps in one reply
• The cloud model decides steps. If the menu is missing an ability, can_execute is false — not a silent skip
• The master is a bus: register, forward, clamp string length. It does not remap user speech, and it does not write speak text
• The name is the contract: model action, UART capability, organ strcmp — one ASCII string
• min / max are hard. The model should clamp; the organ must clamp again
• Empty steps means silence. If the model wants to talk and speak is on the menu, speak must be a step

Physical layer

• Point-to-point UART, no hardware flow control, 115200 8N1
• Crossed TX / RX. Shared ground is mandatory. Each board has its own supply — do not parallel 5 V
• UART on the body bus is UTF-8 only. Do not put GBK on the wire
• On ESP32-C6 DevKitC-1 leave GPIO 4/5 (JTAG), 8/9, and 12/13 (USB) alone. Console stays on USB serial
• C6 has two high-speed UARTs. A third organ needs a new topology, not a stolen console pin

Frame (every message)

SOF 0xAA | version 3 | msg_type | payload_len (u16 big-endian, 0–512) | payload | CRC16 | EOF 0x55
CRC covers version + type + length + payload. Init 0xFFFF, poly 0xA001.
Shortest frame is 8 bytes (ACK, DISCOVER, heartbeat).
RX must reassemble: split frames, stuck frames, and junk before SOF are normal. Do not assume one uart_read is one frame.

Message types

How it stays alive

• Organ boots, waits 1 s, then sends DESCRIPTOR every 2 s until ACK (or until it sees a COMMAND)
• Master ACKs with an 8-byte empty frame. After ACK the organ heartbeats every 1 s and resends the descriptor every 5 s
• If the master reboots, the menu in RAM is empty — it sends DISCOVER; the organ must report again
• Execute: model outputs steps[].action = capability name. Master finds the UART, sends COMMAND. Organ clamps min/max, runs, returns COMMAND_RESP
• Unknown name: organ returns fail. It must not alias to another ability
• 15 s with no legal frame: that organ is offline and dropped from the menu

Descriptor — the organ’s only function contract

• Module header: module_id, module_type, hw/fw version, capability_count (1–8)
• Each ability: ASCII name (≤23), human description for the model (≤63 UTF-8 bytes), params, exec_type, resource_group, max_duration_ms
• exec_type: 0 immediate (reply at once), 1 continuous (reply when started), 2 periodic, 3 event-driven
• Same resource_group is exclusive on the master. speak and announce share audio — only one at a time
• Param: name, type (int / float / string / bool), min_val, max_val, unit. The organ enforces min/max. The master does not rewrite numbers
• On and off are two abilities. Do not ship one led that flips on a parameter

Naming

• Lower-case ASCII and underscore: led_on, led_off, led_blink, speak, announce
• Do not repeat a capability name on one body. The master forwards to the first organ that registered that name

LED contract (on the wire now)

Speaker contract (on the wire now)

Command payload

• COMMAND: capability name, then float params in descriptor order, then optional one string named text (≤240 bytes)
• COMMAND_RESP: one status byte. 0 started or done; 1 bad payload, unknown name, or hardware refused
• Events and data streams are not stuffed into COMMAND_RESP. Those types are reserved for sensors and completion

Master ↔ model (organs do not implement this)

The master turns online organs into a JSON menu. The model must answer with steps whose action names exist on that menu. This is what a cloud model should emit:

{
  "heard_req": 0,
  "steps": [
    { "task_id": "t1", "action": "led_on", "params": {}, "priority": 5, "depends_on": [] },
    { "task_id": "t2", "action": "speak", "params": { "text": "Light is on." }, "priority": 5, "depends_on": ["t1"] }
  ],
  "can_execute": true,
  "missing": [],
  "response": "user-facing line"
}

• action is a capability name, never LED_001.led_blink as the action (the last segment may be stripped as a compatibility mop, not a new ability)
• If the menu cannot do the job: can_execute=false, missing names the gap, steps stay within max_steps (16 in one reply on this body)
• The master does not score abilities or pick the nearest name. Thinking stays in the model

Open, and worth arguing

This page exists so engineers and other models can cite one URL, then disagree in the open.

• What organ should plug in next — IMU, camera, microphone, or a motor?
• Stay on UART, or change topology when a third high-speed UART runs out on C6?
• How should a model mark that it cannot execute, so a human sees the gap?
• How small can the master stay if every organ is truly hot-pluggable?