kodeOS internals

Console protocol

How a console line is written, what comes back, how log lines and levels look, and how files and screenshots cross the wire as base64.

What it is

The console is the text command line of a Kode Dot. A host program sends one command per line. The board answers with records, one closing line and, on the side, log lines. The same lines travel over four ways in: the USB-C cable, the charging base, Bluetooth and the Kode channel on the internet.

Almost every client is a program: a bench script, tools/kcli.py or tools/kble.py. So the protocol is built for parsers. The first characters of a line say what the line is, and a host never has to guess which lines answer its command.

>|name="doom.bin" size=524288 medium=sd     a record: one line of the answer
>ok                                         the terminator: the command worked
>err code=3 msg=rgb                         the terminator: it did not
!N 2026-10-28T09:12:44.585Z kaos.power ...  a log line: nobody asked for it
kode> ping                                  the prompt and the echo, for a person

One rule governs every value: a string is always quoted, and nothing else ever is. The form of a value says what the value is, in both directions, and every value has exactly one way to be typed. What the board prints can be typed back unchanged.

How it is connected

flowchart LR
subgraph ways["Ways in"]
  cable["USB-C cable"]
  dock["charging base"]
  ble["Bluetooth<br/>kdrv_ble"]
  chan["Kode channel<br/>AO_Net"]
end
subgraph board["On the Kode Dot"]
  rd["khal reader task"]
  log["AO_Log"]
  con["AO_Console"]
  own["owning AO"]
end
cable --> rd
dock --> rd
rd --> log
ble --> log
chan --> con
log -- "CONSOLE_LINE_SIG" --> con
con -- "request event" --> own
own -- "answer event" --> con
con -- "kode_log_reply" --> log
class cable,dock,ble ext
class chan,log,con,own ao

Two Active Objects share the work.

• AO_Log owns the console device and is the only writer of it. It runs a small line editor for the cable and the base, tags each finished line with its source (cable or BLE) and publishes it as CONSOLE_LINE_SIG. A line off the Kode channel reaches AO_Console from AO_Net, and a line of the cron scheduler from AO_Scheduler, each with its own source.
• AO_Console owns the parsing. It splits the line, validates it against the command table CMDS[], runs the handler and tracks the one command in flight.

A handler never touches a device: it posts to the Active Object that owns the device, and that owner answers by event.

Every reply line leaves through kode_log_reply(), which sends it to the same queue as the log lines. Answers and log lines reach AO_Log in the order the code produced them.

A fifth source has no wire. An entry of cron runs a console line on its own at a clock time (source SCHED), so nobody types it and nothing reads its answer from a port: the reply is written to the log as a notice, sched: <reply>. A line of this source is held to the policy of the channel (internals/command-set, sdk/kaos/scheduler).

AO_Log writes each line to the cable and the base and copies it to Bluetooth. It also copies the replies of channel commands into the ring that AO_Net drains, and it never copies a ! line.

The four ways in differ in what they hand over:

Specifications

The command line

The value types decide the form. A key of type string or text refuses the bare word, and every other type refuses the quoted one. Both refusals are code 3 with the key in msg.

The answer

A command that reaches the console gets exactly one terminator, unless the board or the link goes away first. hcf resets the board and sends none. A host program always has a timeout.

>ok has three meanings, which the kind of command tells apart. A query (bat_info) sends its data in records and then >ok. An accept (sd_mount, app_erase, install from a medium) says only that the request reached its owner, and the owner tells the outcome in ! lines. A result (mkdir, cp, install src="terminal") means the work is done. app_run, install dst=os and hcf reset the board, so nothing follows their answer.

When the verb alone cannot say what failed, code 5 carries one word: volume, missing, notdir, isdir, noparent, notempty, exists, iofail, src, appendline, slots. Three words name the source of a line. cable means the command needs the USB-C cable or the base, net means it needs a wire and the channel carries only lines, and sched means a scheduled line may not run it (every payload verb, and cron itself). For screenshot dst=http the words are http (the api refused), size (the frame is over 64 KB), channel (the channel is down) and stream. internals/command-set lists the words of each verb.

Four answers leave the two-line scheme:

• nfc_emulate and nfc_emulate_off close with >ok reads=<n>.
• The NFC and RFID commands that explain a physical outcome put a quoted sentence in msg, such as msg="no tag in the window".
• When a tag is in the window but the exchange fails, nfc_read and nfc_write put the raw kode_status_t of the owner in code.
• A failed file_desc answers >err code=<n> with no msg.

Log lines

A line that starts with ! is something the host did not ask for. Panic text and the boot log are the only output that does not follow the marker rule.

The global level is the setting log of config, with the words d, i, n, w, e and off. It is stored, so it survives resets, including the reset that opening the cable port causes. log_level tag="<tag>" level=<word> sets one tag for the current boot. Replies are never filtered: every level keeps every > line, so a command still closes with >ok or >err. A script that reads !I lines on a board left at n or e sees nothing, so it sets value=i first.

The prompt and the echo

AO_Log draws kode> and echoes typed characters for a person. While only a program uses the console, every > and ! line starts at column 0. A parser handles two leftovers from a person's session:

• The echo of the command the host sent comes back before the answer, with a kode> prefix when the prompt was drawn. Discard everything up to the first line that starts with > or !.
• A record can arrive after the erase sequence \r ESC [K (ERASE_LINE in log_ao.c), on the same line. Drop everything up to and including it.

The Bluetooth port copies complete lines only: no prompt, no echo, no erase sequence.

Commands in flight and the watchdog

The slices exist because every reply line is an event from the large pool, and AO_Console outranks AO_Log. A listing sent in one step would take the whole pool (KQP_LARGE_POOL_COUNT, 48) before AO_Log wrote a line, and the tail with the terminator would be lost.

console_congested() adds back-pressure: producers wait while AO_Log has more than 24 lines queued (4 when a Bluetooth console is attached), or while the Bluetooth ring holds more than 512 bytes. The check runs for each record, not for each slice.

Payload from the host

install src="terminal" and file_put are the only commands whose payload follows the line.

sequenceDiagram
autonumber
participant H as host
participant B as board
H->>B: install src="terminal" dst=os size=N crc32=C
B->>H: >|ready chunk=4096
loop each 4096-byte chunk
  H->>B: raw bytes
  B->>H: >|ack
end
H->>B: last partial chunk, no ack
B->>H: >ok

On Bluetooth there is no reader task to divert. The driver stops assembling lines and gathers the GATT writes into 4 KB chunks on the NimBLE task. The payload follows the command down the port it arrived on.

Bulk data from the board

screenshot and file_get send the opposite way. No raw mode is used for output: the rescue path could write into the middle of it, Bluetooth carries only lines, and holding all other output for a transfer defeats the log. The board sends base64 inside ordinary >|d= records.

screenshot
>|shot w=410 h=502 fmt=bmp16 len=411768
>|d=Qk34IQYAAAAAAIAAAAAoAAAAmgEAAPYB...
...
>ok

The host reads without stopping. The board never sends faster than its writer can write, but nothing protects the serial buffer of the host, and a program that pauses to parse loses bytes the board did not drop.

screenshot dst=http is not a transfer on this wire. The board encodes a JPEG and uploads it over HTTPS. See internals/kode-channel.

The mirror stream

mirror_start uses the same base64 shape as a screenshot, but as a continuous stream with no terminator between frames.

>|m=<base64>
>|m=<base64>
>|mabort
>|mpause

The records decode to one continuous buffer: a 14-byte header, then len JPEG bytes, then the next header. Fields are little-endian.

• Only the first frame after mirror_start or a pause covers the whole panel. Later frames can be the rectangle that changed, so a viewer places each part at its own offset.
• Decode only whole groups of 4 base64 characters and never pad a short tail. Padding makes different bytes, silently. decode_whole_groups() in tools/kpayload.py keeps the 0 to 3 leftover characters for the next call, and MirrorDecoder in tools/kmirror.py is the reference.
• >|mabort means the frame in progress is abandoned and the next record starts a new header. The board sends it only when at least one byte of the frame has left.
• >|mpause means the session sleeps after 5 s with no progress. mirror_start or any mirror_ack wakes it.
• Both control records travel on the console line on every transport, the Bluetooth binary characteristic included. That characteristic carries the same header and raw JPEG bytes with no base64.

A variable followed with variable name="<row>" watch=<ms> also emits records after its command has ended, between the records of other commands. The rule for a host is the same: filter on the first key and drop what you did not ask for. See internals/variables-and-functions.

Gotchas

Example code

The script below opens the cable port, sends ping and checks the answer. It skips the echo and the erase sequence, collects records until the terminator, and ends silently when the board answers pong and >ok. Replace the port name with the one of your board. Opening the port restarts the board, so a real program waits for it to boot before the first command.

# ping.py - 2026-10-28 - from Kode with love
#
# Sends "ping" to a Kode Dot over the USB-C cable and checks that the console
# answers the record "pong" and then the terminator ">ok". It prints nothing
# when the check passes and stops with an assertion error when it does not.
import serial
 
port = serial.Serial('/dev/cu.usbmodem101', 115200, timeout=2)
 
 
# Send one command and return its terminator plus the records before it.
def command(line):
    port.write((line + '\r\n').encode())
    records = []
    while True:
        text = port.readline().decode(errors='replace').rstrip('\r\n')
        # The erase sequence can precede a line once, after the port opens.
        text = text.rsplit('\r', 1)[-1].removeprefix('\x1b[K')
        if text.startswith('>|'):
            records.append(text)
        elif text.startswith('>ok') or text.startswith('>err'):
            return text, records
        # Echo and '!' log lines fall through: they are not the answer.
 
 
terminator, records = command('ping')
assert (terminator, records) == ('>ok', ['>|pong'])

TBD: this example has not been compiled or run on a Kode Dot yet.

In the SDK

• components/kaos/console: the parser, the command table and the grammar.
• kcli_proto.h: the error codes.
• tools/kpayload.py: quote(), fields() and the base64 decoders every host tool shares.