Why this is larger than another demo

The scarce part is not a smarter chat. It is a body other people can join without rewriting the OS.

This is public so you can walk in

The protocol is on this page. Pick a door. You do not need to be a customer.

The OS, and how other nodes connect

Body OS sits in the middle. Everything else is a node on a named interface. New hardware does not fork the kernel. A new model does not rewrite the organs.

What each link carries

Kernel framework on the C6 host

The host tree is brain/. The kernel is a bus plus a vital snapshot. It does not include a cloud vendor, and it does not plan.

Two clocks

• Body fast loop: UART milliseconds. Heartbeat, streams, halt_event pauses only the current wait
• Soul slow loop: one consult at a time. Empty steps = silence. The kernel does not fill the gap
• A failed or halted step is not retried and does not invent new steps. Later steps already listed still forward

Three roles inside the OS. Do not mix them.

What is running in the lab

Not a product SKU. Protocol V3 on a C6 kernel, an LED organ, and a speaker organ.

• Kernel host ESP32-C6, firmware tag 20260902-C6-SPK42. Organs: LED C6-LED17, I2S speaker C6-SPK20 (MAX98357 class)
• Organ bus: point-to-point UART, 115200 8N1, crossed TX / RX, shared ground. Boards powered separately — do not parallel 5 V
• An organ powers on, sends a descriptor, then a heartbeat. The kernel ACKs. An unknown action returns fail, not a guessed alias
• USB vitals is a local snapshot. It does not call the cloud. Speak text is written by the brain; the speaker plays it
• A 1 s breath keeps the body alive when nobody is typing. That loop does not write motors

Protocol V3 — the public frame

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

Rules the OS must not break

• The body reports a contract: named abilities, min / max, named returns, max steps in one reply
• The brain slot decides steps. If the menu is missing an ability, can_execute is false — not a silent skip
• The kernel is a post office: register, forward, copy vitals by field name. It does not remap user speech, and it does not write speak text
• The name is the contract: strcmp byte-exact. No trim, no case-fold. Breaking change = a new name, not a kernel remap
• min / max are hard. The brain should clamp; the organ must clamp again
• Empty steps means silence. If the brain wants to talk and speak is on the menu, speak must be a step
• Additive descriptor trailer only. Order frozen: halt_event, then cap_version. Old slaves still register
• No JSON organ bus replacing UART 0xAA…0x55. No capability-graph auto-compose. No rollback inventing reverse actions

Four frozen contracts

• Descriptor 0x91: self-report. Unknown names still enter the menu
• Capability schema: the execute key is name. On and off are two abilities. cap_version is for the brain only
• Step: forward in order. needs_completion_ack waits for task_completed / task_failed. halt_event pauses only the current wait
• Body state: vitals keyed by return_params names. No guessing values[0]=front. Event ring 16, priority overwrite

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)
• Kernel ACKs with an 8-byte empty frame. After ACK the organ heartbeats every 1 s and resends the descriptor every 5 s
• If the kernel reboots, the menu in RAM is empty — it sends DISCOVER; the organ must report again
• Execute: brain outputs steps[].action = capability name. Kernel 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 brain (≤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
• needs_completion_ack: wait for task_completed / task_failed before the next waiting step
• return_params: named feedback fields. 0x93 values are copied by these names, never by C struct layout
• Optional trailer, order frozen: halt_event string, then cap_version string. Old organs that omit it still register
• Same resource_group is exclusive on the kernel. 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 kernel 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 kernel 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 0x92 and streams 0x93 are not stuffed into COMMAND_RESP. Completion and samples use those types

Kernel ↔ brain slot (organs do not implement this)

The kernel turns online organs into a JSON menu, plus a vital snapshot and a notebook. The brain must answer with steps whose action names exist on that menu:

{
  "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": [],
  "memory": { "items": [], "digest": "" },
  "response": "user-facing line"
}

• Consult input is menu + vitals + events + notebook + source (user or self). Snapshot is copy, not semantics
• action is a capability name, never LED_001.led_blink as the action
• If the menu cannot do the job: can_execute=false, missing names the gap, steps stay within max_steps (16 in one reply)
• The kernel does not score abilities or pick the nearest name. Thinking stays in the slot
• Self-turn empty steps must stay silent. Do not speak from response

Still open. Come argue

A living OS has unfinished edges. If you care, these are the fights worth having.

• What organ should plug in next — so long as it speaks the UART contract, not a walk invented in the kernel
• Stay on UART, or change topology when a third high-speed UART runs out on C6?
• When should the local brain driver leave the reserved slot?
• How small can the kernel stay if every organ is truly hot-pluggable?