kodeOS internals

BLE console

Reach the kodeOS console over Bluetooth from a computer: the GATT service, the pairing code on the glass, flow control and the kble.py client.

What it is

The console of a Kode Dot also answers over Bluetooth Low Energy. The commands, the grammar and the answers are the ones of the USB-C cable. A line a central writes is a command. A line the board notifies is a record, a terminator or a ! log line. internals/console-protocol describes the lines, and this page describes what is different on the Bluetooth port.

A cable keeps the console to whoever holds it. Any Bluetooth radio in range hears the board advertise, so this port requires a pairing before it sends a line. With the default build, the first pairing shows six digits on the glass and you type them on the computer. The bond is stored on both sides, and every later attach is silent. Once a device is bonded the board hides from everyone else, and Pair new device on its Bluetooth page shows it again for a new one.

tools/kble.py is the client for macOS. It holds the Bluetooth link between commands, so the first command takes about 2.3 s to attach and each later command about 0.18 s, measured on a Kode Dot.

How it is connected

sequenceDiagram
autonumber
participant C as Central<br/>kble.py
box "kodeOS"
  participant D as kdrv_ble<br/>NimBLE task
  participant L as AO_Log
  participant K as AO_Console
end
C->>D: GATT write on RX
D->>D: console_feed assembles a line
D->>L: log_on_ble_line
L-->>K: CONSOLE_LINE_SIG, src BLE
K->>L: kode_log_reply, records and terminator
Note over D,L: AO_Log owns both console ports
L->>D: kdrv_ble_console_write, into the ring
D-->>C: notify on TX, at most MTU minus 3 bytes

AO_Log owns both console ports

The driver only carries bytes. AO_Log installs the callbacks in its initial transition, before Bluetooth starts, so the radio never advertises while nobody listens to the port. A finished line becomes a ConsoleLineEvt tagged KODE_CONSOLE_SRC_BLE and is published.

AO_Console receives every CONSOLE_LINE_SIG and keeps the tag, which only install, file_put and a few verbs that need the cable look at. AO_Log calls kdrv_ble_console_write() from one place only, right after the same line went out on the cable. So a log line, a record and a terminator reach both ports, whoever asked.

AO_Radio starts the stack and keeps the board advertising

When the ble flag is on, the worker is free and the driver is idle, AO_Radio submits an advert job. The board stops advertising when a central connects, when it leaves or while a scan uses the radio, and the same rule restarts it. The same rule picks a visible or a hidden advert (see Advertising below). The driver cannot do this alone: restarting an advert is a chain of RPCs to the C5, and only the worker task of kdrv_radio makes them.

Build options and files

The NimBLE host runs on the P4 and reaches the controller on the C5 over esp-hosted. Three options shape the port:

• CONFIG_KODEOS_BLE_CONSOLE builds the port. It depends on KODEOS_BLE and KODEOS_CONSOLE, and defaults to on.
• CONFIG_KODEOS_BLE_CONSOLE_PAIRING (default on) requires pairing.
• CONFIG_KODEOS_BLE_PAIRING_PASSKEY (default on) makes the pairing authenticated with the six digits.

These files hold the port:

Specifications

The GATT service

The service and its characteristics have Kode's own 128-bit UUIDs. The first group spells KODE in ASCII and the second is the index. The characteristics behave like the Nordic UART Service (one pipe in, one pipe out), so a generic BLE terminal can drive the board once you enter these UUIDs by hand. A terminal that knows only the Nordic UUIDs does not find it.

With the passkey option on, RX and the TX and mirror notifications demand encryption and authentication (WRITE_ENC and WRITE_AUTHEN, and the matching notify flags). With only pairing on, they demand encryption. With pairing off, the permission masks are empty and the service is open, and the log line "console attached" ends with (no pairing).

• Neither characteristic is readable. A read answers BLE_ATT_ERR_READ_NOT_PERMITTED.
• One write can carry part of a line, a whole line or several lines. console_feed() assembles whole lines, ends one at CR or LF and ignores empty lines.
• A line of 240 bytes or more (BLE_LINE_MAX) is dropped whole, with a warning in the log and no terminator. A command that is cut and then run would not be the command the client sent.
• There is no echo, no prompt and no line editor, and a backspace is an ordinary byte. The parser of a Bluetooth client is the parser of the console protocol without the prompt and the erase sequence.
• The board counts a central as attached when it subscribes to TX. It still runs the lines written to RX before that, but the answers go nowhere.
• The CCCD of a characteristic does not inherit its permissions, so the driver gives TX the NOTIFY_INDICATE encryption flags too. Without them an unpaired stranger could subscribe and read the console in clear text.
• NimBLE destroys the service table when it stops, so the driver registers it again on every start.

Advertising

Pairing

The board asks for security from the GAP connect handler (ble_gap_security_initiate()). It does not wait for a protected access, because NimBLE drops a write without response that fails a permission check, silently, and a client would wait forever for a pairing nobody started.

The digits never appear in a log line or a verb answer, because every line reaches every attached central and a bonded peer would read the code of the next one. Without the passkey option the pairing is Just Works and the characteristics ask for encryption alone.

A hidden board serves its bonded devices and pairs nobody new. A pairing that reaches it is refused the way an app refuses one, below, and the log says the board is hidden; Pair new device makes it visible. Pair new device opens pairing until the first device pairs, so one press pairs one device.

An app serves bonded phones and never pairs a new one. The same BLE is in every SDK app. A phone bonded in kodeOS works in the app with no new pairing, since both the C5 and the P4 keep the bond across the jump. In an app built with CONFIG_KODEOS_BOOT_ROLE_APP, a new pairing is refused: the passkey action picks no digits and hangs up, a repeat pairing keeps the old bond, an encrypted but unauthenticated link has its bond deleted and a full store answers BLE_HS_ENOMEM. Pair a new phone in kodeOS.

Reconnecting

A computer pairs once. After that it reconnects the way headphones do: no code on the glass, and no need to forget the Kode Dot in the Bluetooth settings. Every reset of the P4 drops the link, because NimBLE runs on the P4 and the controller on the C5. The board advertises again as soon as kodeOS is up, and the computer attaches with the bond it already has.

A bond has two halves on the board. The P4 keeps one record per peer in its NVS, and that record holds tokens, not keys. The long-term key and the identity key of the peer sit in the vault of the C5. A delete goes through both: the store callbacks of kdrv_ble.c tell the C5 to forget the keys, and the P4 drops its record. Because the record is in NVS and the keys are in the C5, the bond does not depend on the image that created it.

These four were run on one Kode Dot on 2026-10-29 with a Mac that held the bond. ble_info read bonds=1 before and after each one, and no pairing card appeared. TBD: the board log of a reconnect, and a run of the two updates with the install verb itself.

If a computer asks to pair while the board still holds a bond for it, NimBLE raises a repeat-pairing event. In kodeOS the board deletes the old bond, keys included, and lets the pairing run again. With the passkey option on, that puts the pairing card on the glass and asks for six digits. An app keeps the bond, as described under Pairing. TBD: this path has no host test and no bench run.

Flow control

The link is far slower than the console can produce. The numbers below keep a producer from outrunning it.

A producer cannot ask the ring how full it is: AO_Log has a lower priority than the producer, so the ring still reads empty when a slice is posted. The check runs on the queue of AO_Log and on the backlog once AO_Log has run, for each record. Without that limit, a frame of 2,542 records loses 765 of them as tx_drop.

ble_info is the single record that reports all of this:

log_dropped=0 in ps and tx_drop=0 in ble_info are the direct proof that a screenshot or a file arrived intact.

Payloads over Bluetooth

install src="terminal" runs the same stop-and-wait conversation as on the cable: ready chunk=4096, then one chunk per ack. The destination c5 is refused with msg=cable, since the reboot of the C5 takes the link with it.

On Bluetooth there is no reader task to divert. The driver stops assembling lines, gathers the GATT writes into 4 KB chunks on the NimBLE task and posts them to the receiver. The board holds the byte count, so a host that keeps sending finds the line assembler again. If the pool is empty mid-image, the driver logs an error and the transfer fails on the CRC instead of installing a wrong image.

screenshot and file_get work because their answer is base64 text in ordinary records. A frame takes about 22 s over Bluetooth.

kble.py

With several Kode Dots in range, the first one scanned is not always the one that holds your bond. A connection to the wrong board fails with Insufficient Authentication, which looks like a broken bond and is not. Give kble.py the serial of the board, which info prints as serial=:

python3 tools/kble.py --serial KODE1R8JZ0FSJM5 cmd "ping"

The environment variable KODE_SERIAL does the same when --serial is absent. The scan skips every advert whose name is a different serial. A hidden board's advert carries no name, so the scan reads the name the computer kept from the board's visible advert, which every computer that paired has. A bridge that already holds another board is refused with a message that names both. Without either, kble.py takes the first Kode Dot it finds. The serial has to be the one the running kodeOS advertises, since the advert name is that serial.

The bridge

The script runs as two halves joined by a Unix socket at ~/Library/Caches/kode-kble/bridge.sock. The half inside a macOS app bundle holds the Bluetooth link and is a plain byte pipe. The other half runs your command and knows the protocol. A command connects, says kble 1 attach, and bytes cross verbatim until it hangs up.

The bridge serves one client at a time and answers a second one busy. A command waits 1 s before believing busy, because the bridge frees its slot a moment after the previous command exits. A bridge that hears another version in the hello answers stale, drops the link and exits, and the command starts a current one. The link stays open until kble.py detach, until the board drops it (ble_down, a reset, out of range) or until Bluetooth goes away. It never closes on idle.

Writes and the first attach

Writes are cut into pieces of MTU minus 3 bytes and sent as write without response. The first attach scans for the service UUID, connects and subscribes to TX. If the subscription is refused for want of encryption, the client writes one empty line to RX with response and retries up to six times, a second apart. On a Mac that write is what makes CoreBluetooth start the pairing, while a subscription alone does not. The client waits for payloads with an idle deadline that restarts at every line, matching the watchdog of the board.

The macOS app bundle

The macOS scaffolding is needed because CoreBluetooth aborts any process whose Info.plist has no NSBluetoothAlwaysUsageDescription, with no message. kble.py builds a small signed KodeBle.app under ~/Library/Caches/kode-kble, launches itself inside it with open -a so the bundle has its own Bluetooth permission, and creates a Python environment with bleak there. These files live in the cache because a bundle started by launchd cannot read ~/Documents.

Gotchas

Example code

Send a command over Bluetooth from a Mac.

1. Turn Bluetooth on at the computer and make sure the Kode Dot is advertising. ble_up over the cable starts it, and a stored ble setting of on starts it at boot. A board that already has a bond is hidden: press Pair new device on its Bluetooth page, or run ble_pair on the cable.
2. Run python3 tools/kble.py cmd "ping". The first run builds the app bundle, scans, connects and asks for the pairing.
3. Read the six digits on the glass of the Kode Dot and type them in the dialog of the computer.
4. The terminal prints attached, then pong and ok. Run it again: the second run attaches in under a second.
5. Run python3 tools/kble.py screenshot -o shot.png and wait about 20 s for the picture of the glass.
6. Run python3 tools/kble.py detach to let go of the board.

In the SDK

• components/kdrv/radio: kdrv_ble.c holds the service, the assembler, the ring and the pairing policy.
• log_ao.c: the callbacks, raw mode and console_congested().
• tools/kble.py: the client and the bridge.