kodeOS internals

Boot model

How a Kode Dot picks the firmware to start after a reset: the partition table, otadata, the boot request, the mailbox and the bootloader override.

What it is

After every reset the Kode Dot has to decide which firmware to run: a kodeOS image, or an app. Three records in the flash decide, and each has exactly one owner.

An app never writes otadata. That is why any reset brings the board back to kodeOS: the next boot finds no request that still stands and falls to the slot otadata names. A sketch uploaded through the mailbox is the exception, and only for the resets listed under Specifications.

kodeOS keeps three slots for itself: factory, ota_0 and ota_1. factory is the rescue copy, written only over the cable. The other two take updates in turn. The apps region is not a slot, but it also holds firmware, and the bootloader starts an app from it in place, without copying it.

How it is connected

flowchart TD
rom["ROM bootloader"] --> bl["Bootloader override"]
bl --> q{"Boot request stands?<br/>NEW, ALWAYS or ARMED"}
q -- "yes" --> app["App in the<br/>apps region"]
q -- "no" --> od{"otadata names<br/>a slot?"}
od -- "yes" --> slot["ota_0 or ota_1"]
od -- "no" --> factory["factory"]
class rom chip
class app app
class slot,factory store

The bootloader is the standard ESP-IDF one with four additions, in bootloader_components/main/bootloader_start.c. Three run at every boot:

• The IO_MUX clock goes back to the crystal.
• Every GPIO interrupt a previous firmware left armed is disarmed.
• The panel's reset line is pulsed low for 2 ms.

The fourth is the question in the diagram. If no request stands, the standard path runs.

The request changes before the jump

The bootloader moves NEW to TRIED and ALWAYS to ARMED with one 4-byte write, then jumps. A one-shot app that crashes or resets finds TRIED at the next boot, so the standard path starts kodeOS. The same order means a failed write blocks the jump: a request that cannot advance would otherwise jump on every reset.

An ARMED request is judged on every reset

It stands only if the reset cause is one a working app or its host produces (the list under Specifications) and the mailbox is empty. If it does not stand, the bootloader writes TRIED and starts kodeOS without verifying the app. The first boot of an ALWAYS request never consults the list, because kodeOS launches an app with a software reset and that reset must not cancel its own launch.

sequenceDiagram
autonumber
participant OS as kodeOS<br/>AO_Boot
participant BL as Bootloader<br/>override
participant App as App
OS->>OS: write the request: NEW, or ALWAYS from the mailbox
OS->>BL: reset, after the leave
BL->>BL: check magic, CRC, bounds and esp_image_verify
BL->>BL: NEW becomes TRIED, ALWAYS becomes ARMED
BL->>App: jump in place
App->>BL: any reset
Note over BL: TRIED, so otadata names kodeOS
BL->>OS: start kodeOS
OS->>OS: req_tried() gives boot reason app, then req_clear()

AO_Boot decides what kodeOS does about it

Its behaviour depends on the firmware's role, a Kconfig choice (CONFIG_KODEOS_BOOT_ROLE_OS or _APP). In an app (the default) it claims otadata and the request sector and writes neither, so a firmware that crashes on its first line still returns to kodeOS. In kodeOS it runs three steps at every boot:

1. If the running image is still PENDING_VERIFY, kdrv_slot_confirm_self() clears the mark. This is mandatory: an unconfirmed image is rolled back at the next boot, and esp_ota_begin() refuses to open an update while the running slot is unconfirmed.
2. It calls kdrv_apps_init() and then kdrv_apps_req_tried(). A TRIED request proves the bootloader jumped, so the reason is app and the request is cleared. Any other request still present is cleared with a warning, because the bootloader's retire write did not stick, and the reason is cold.
3. If kodeOS runs from factory while otadata is not blank, a kodeOS update died before it confirmed. The reason is unexpected and AO_Boot clears otadata, so the board stays on factory.

The reset reason of the chip, read after those steps, classes how the app before it ended: panic, watchdog, brownout, or clean for everything else. An unknown reset reason never reads as a crash.

A restart leaves in an order

Every deliberate restart (an app launch, a kodeOS update, kode_exit_to_os(), the bottom button held) goes through the same short leave in AO_Boot:

1. AO_Net stops the Kode channel cleanly (at most 200 ms).
2. AO_Radio hangs up Bluetooth and parks the ESP32-C5 so the Wi-Fi link survives the jump (at most 250 ms).
3. The console drains for 150 ms.
4. The chip resets.

Each step ends on its owner's answer or on its bound, so a silent neighbour never holds the jump. A second restart request during the leave is dropped.

The C5 across the jump

The C5 has its own reset line, so a P4 restart does not reset it. The firmware that leaves writes a handover note into a register of the low-power domain, only after the C5 confirmed it parked. The firmware that starts reads the note at its first link, takes the Wi-Fi association over and erases the note. After a panic, a watchdog or a power cut there is no note, and the C5 is reset to a fresh start.

Specifications

The partition table

The bootloader is at 0x2000 and the table at 0x8000 (CONFIG_PARTITION_TABLE_OFFSET, where the Arduino core also looks for it). The file is components/kbsp/partitions.csv. nvs starts at 0xB000, so the two sectors after the table stay free and a table that grows never moves it.

From factory to the end of the flash each area starts where the one before ends, up to app_pending at 28 MB. The flash is 32 MB.

The coredump= field of info says whether a dump waits. owner=kodeos means the dump's ELF SHA-256 matches the running image. owner=other is any other dump: a sketch's, another build's, or one this build cannot decode (the Arduino core's libraries checksum with CRC32 and kodeOS checks SHA-256 only, so it prints task=- pc=-). Read a dump with idf.py coredump-info.

The boot request

kapps_req_t is 20 bytes: magic ("KRUN", 0x4E55524B), offset, size, crc, then state. The CRC covers magic to size. state sits after it so the bootloader can advance it with a 4-byte write that only clears bits. The byte formats are on sdk/kdrv/apps.

The bootloader reads the request and checks, in order, the magic, the CRC (esp_rom_crc32_le), a state of NEW, ALWAYS or ARMED, and the geometry (kapps_req_bounds_ok()). A request that fails the first three is ignored without a write. A request that fails the geometry check is ignored too and stays where it is, so AO_Boot clears it when kodeOS starts. Then one of five things happens:

If the write that advances the state fails, the bootloader does not jump. If the array of images it may load is full, it returns to the standard path. The standard loader falls back to the earlier images (ota_1, ota_0, factory) when the jump itself fails.

Resets that keep an ARMED request

The list is closed (reset_keeps_request() is a switch whose default answers no). The numbers are the ROM's soc_reset_reason_t, not the esp_reset_reason_t that kodeOS logs at boot. The request also needs an empty mailbox: the bootloader reads the first word of app_pending and counts a bare image (0xE9) or a .kfw container (0x3157464B) as full, and a failed read counts as full.

Any other cause retires the request: power-on (0x01, which BOT and LEFT held together produce), every hardware watchdog, the hardware brownout reset 0x0F, the glitch detectors, a CPU lockup, and a number nobody named. A full mailbox retires it as well, so a second upload works without touching the board.

kodeOS's own OFF state ends in deep sleep too, and its wake is the row of the deep-sleep wake with no request standing: a normal boot. Before AO_Log starts, kode_boot_gate() sends the board back to deep sleep when a button other than BOT woke it (sdk/kaos/lowpower).

AO_Boot

boot_info answers one record: running=<slot> addr=0x... size_kb=<n> otadata=blank|slot reason=cold|app|unexpected app_end=none|clean|panic|watchdog|brownout. After a clean install, running=factory, otadata=blank and app_list answers nothing.

Flash addresses a host tool uses

A host tool contains these as constants and never computes them.

Four ways to put firmware on the board use these addresses:

Nothing infers the intent from the image's bytes, because the author of an image controls its name field. Every consume of the mailbox erases both sectors, so an old word never describes a later upload.

Gotchas

Example code

Push a sketch or an app through the mailbox and come back to kodeOS. Each step ends in something you can see.

1. Write the image to the mailbox: python -m esptool --chip esp32p4 -p <port> write-flash 0x1A00000 app.bin. The board resets, kodeOS adopts the image and the app starts. The glass shows the app.
2. Open a serial monitor on the port. The port opening resets the board, and the same app starts again, with its console answering.
3. Hold BOT and LEFT together for about one second. The board resets as a power-on and the request is retired.
4. kodeOS counts the boot as the return from an app, so Apps is on the glass with the app in focus, listed first (internals/gui/launcher).

TBD: these steps have not been run on a Kode Dot from this page.

In the SDK

• bootloader_components/main/bootloader_start.c: the bootloader override, about 300 lines.
• components/kaos/boot/src/boot_ao.c: AO_Boot, the owner of otadata and the boot request.
• components/kbsp/partitions.csv: the partition table.