SDK

Apps region and containers

How a Kode Dot stores installed apps and kodeOS updates in flash: the A/B directory, the boot request, the mailbox, .kfw containers and the app manifest.

What it is

An app on a Kode Dot is a whole firmware, not a plugin. kodeOS writes its .bin into the flash region apps, and a small bootloader override jumps to it in place. Any reset brings the board back to kodeOS, because the app never touches the partition that says which kodeOS to start.

The module kdrv/apps is everything that handles those images:

Two Active Objects use it. AO_AppMgr owns the directory, the images, the mailbox and the write to the free kodeOS slot (sdk/kaos/appmgr). AO_Boot owns the boot request and otadata (sdk/kaos/boot). The design of the region and the boot model are on internals/apps-region and internals/boot-model.

How it is connected

flowchart LR
subgraph aos["Active Objects"]
  am["AO_AppMgr"]
  boot["AO_Boot"]
end
subgraph drv["kdrv/apps"]
  kfw["kdrv_kfw<br/>decoder"]
end
subgraph flash["Flash destinations"]
  apps["kdrv_apps<br/>apps region"]
  slot["kdrv_slot<br/>free OTA slot"]
  mb["kdrv_apps<br/>app_pending"]
end
am --> kfw
kfw --> apps
kfw --> slot
kfw --> mb
boot --> apps
boot --> slot
apps -- "kapps_fmt.h" --> bl["bootloader override"]
class am ao
class boot ao
class apps store
class slot store
class mb store

kapps_fmt.h is the one header the driver and the bootloader share, word for word, so it includes nothing from ESP-IDF. It holds the magic numbers, the layout, the boot request and the rules both sides apply to them, as static inline functions. The bootloader and kodeOS are updated apart, so that layout never moves.

Why the directory has two copies

Flash only clears bits. An erase sets every bit of a 4 KB sector to 1, and a write can only change a 1 to a 0. Two designs follow:

• The directory is kept twice, because a power cut in the middle of one sector write must leave a whole copy.
• The boot request moves from one state to the next with a single 4-byte write and no erase, because each new state only clears more bits.

The directory has two copies, A and B. kdrv_apps_dir_commit() never touches the copy believed valid. It writes the other one with gen one higher and a fresh CRC, waits for the write, and only then swaps its RAM copy. Inside a copy, the magic word is written last, so a cut leaves a sector that reads blank or corrupt and never one that looks whole. The commit refuses (KODE_DENIED) a directory that kapps_dir_sane() rejects, so the driver never seals a bad directory with a good CRC.

Init sorts each copy into one of four kinds. kdrv_apps_init() is idempotent: AO_Boot and AO_AppMgr both call it and whoever runs first pays the read. It also starts the category table first, so overrides are visible from the first manifest read.

If either copy is foreign, the driver uses neither and formats nothing. It logs apps region directory unreadable or of another format, returns KODE_ERROR and leaves the region shut: every call that needs the partition refuses. A later init looks again. Otherwise the ok copy with the highest gen wins (A wins a tie). When neither is ok, the region is formatted: an empty directory with gen 1 goes to A and B is erased so it cannot pass for newer.

Placing and writing an image

The allocator is log-structured and next-fit. kdrv_apps_plan() touches no flash and keeps no state, so the host tests run it without a board.

1. Round the image size up to 64 KB. An image that cannot fit in an empty region is refused (KODE_ERROR).
2. Collect the live entries and sort them by offset.
3. Start the search right after the newest install (highest seq), rounded up to 64 KB.
4. Take the first gap that fits, looking from the search start to the end of the region, then from KAPPS_DATA_OFF up to the search start.
5. If nothing fits, evict the entry named by replacing first, then the oldest live entry (lowest seq), add its extent to the search and go again. The order of evict[] is the order apps are freed in.

The eviction is first in, first out by install order. kodeOS has no notion of use to rank by. The one exception is replacing, the entry of the app the image is a new version of (KAPPS_NO_VICTIM for a new app): its old copy goes before any other app, because the install replaces it anyway. When evict[] holds it, replaced names it, and the caller does not count it as lost.

The plan also predicts one more victim, slot_victim: when all 64 directory slots would still be live after the evictions, AO_AppMgr removes the oldest remaining entry after the write. With replacing live there is none, because the new version takes its old copy's slot. Without it the plan is a prediction: an image with the same name as an installed app still replaces that app in its own slot, and only the written image tells. Replacing by name is AO_AppMgr's job. The driver's directory calls are generic: read, plan, commit.

A write session erases as it goes. kdrv_apps_write_begin(offset, size) opens a session. kdrv_apps_write() erases a 64 KB block only when the write reaches it, so the GUI keeps running between AO_AppMgr's 32 KB chunks.

The bytes reach flash through 2 KB of internal RAM (KDRV_BOUNCE_BYTES, borrowed per call from the heap). esp_flash_write() takes its fast path only from internal memory, and from PSRAM it programs 32 bytes at a time with the cache off.

Every image arrives in PSRAM. A 1.5 MB app from the card installs in about 8 s this way, against about 14 s straight from PSRAM, measured on a Kode Dot. If the heap has no 2 KB to lend, the write goes straight from the caller's buffer, slower and still correct. The mailbox and the kodeOS slot use the same helper (kdrv_bounce.h).

kdrv_apps_write_end() closes the session and runs kdrv_apps_verify() over exactly the bytes written, a plain esp_image_verify(). kdrv_apps_write_abort() only closes the session. The partial bytes stay in flash, unchecked and never entered in the directory.

Launching an app

The boot request says what the bootloader runs next. kdrv_apps_req_set() accepts only the states NEW and ALWAYS. It checks kapps_req_bounds_ok() first, so the refusal happens while there is still a console to explain it, then erases the request sector and writes the 20-byte record.

sequenceDiagram
autonumber
box "kodeOS"
  participant AM as AO_AppMgr
  participant B0 as AO_Boot
end
participant R as apps region
participant BL as bootloader
AM->>B0: BOOT_APP_RUN_SIG offset size mode
B0->>R: req_set: erase, write KRUN NEW or ALWAYS
B0->>B0: reset the chip
BL->>R: read request, check CRC and bounds
BL->>R: NEW becomes TRIED, ALWAYS becomes ARMED
BL->>BL: jump to the app image
Note over B0,R: next kodeOS boot: req_tried() yes, then req_clear()

NEW means one boot. ALWAYS is the sticky request that only mailbox adoption writes, so an uploaded sketch survives the Serial Monitor and the debugger. The bootloader marks it ARMED on the first boot, and from then on keeps it only across the resets in the table under Specifications. Back in kodeOS, kdrv_apps_req_tried() is how AO_Boot knows it is "back from the user app". kdrv_apps_req_armed() asks the same about the sticky state.

Adopting a mailbox image

The mailbox is checked in two phases. app_pending (6 MB at 0x1A00000, subtype 0x41) is non-executable, holds one image or one container at offset 0 and has no directory. A host tool writes the image with esptool, and a separate word at 0x5FF000 says what it is for (see Specifications).

1. At boot, kdrv_apps_pending_present() reads one byte. 0xE9 means a bare image, and pending_walk_len() walks its header chain with esp_partition_read() to find its length. This is a length check only: it catches a torn or garbage upload, not a wrong hash. A walk that does not hold together consumes the mailbox at once, so a broken upload is not re-checked on every boot.
2. Any other first byte may start a .kfw container, whose header states its own length. A container claiming more payload than the mailbox holds is discarded.
3. When an install must evict an app, kdrv_apps_pending_verify() runs the full esp_image_verify() on the mailbox in place, so a corrupt upload cannot cost anyone an installed app. A container is not verified here.
4. AO_AppMgr copies the image into the region, and kdrv_apps_write_end() runs the full check on the copy.

The walk does not trust the length a segment header states. It bounds the inputs of each addition, not its result, so a value near UINT32_MAX cannot wrap the offset around the partition.

The in-place check and the check on the copy need the 32-bit flash cache mapping (CONFIG_BOOTLOADER_CACHE_32BIT_ADDR_QUAD_FLASH), because both app_pending and the upper half of the region lie above 16 MB. Nothing boots on the strength of the length check alone.

kdrv_apps_pending_present() reports two lengths. img_len is what the mailbox holds, which is what a copy reads. decoded_len is what the image occupies once decoded, which is what an eviction plan is made for. They are equal for a bare image. A deflated container holds fewer bytes than it places.

The mailbox sink keeps a container verbatim, header and compression included, so reading it back checks it again. This is the one place where the decoder is not in the path, and kdrv_apps_pending_write_end() checks only the byte count. kdrv_apps_pending_consume() erases the first sector and the intent sector every time, so an intent flag never outlives its image.

Decoding a container

A container is decoded as a stream. kdrv_kfw.c holds the format, a decoder and the contract of a sink, the destination of a decoded image:

Four sinks exist: kdrv_slot_sink() (with a size pre-check), kdrv_apps_sink() for the region, kdrv_apps_pending_sink() for the mailbox and kfw_buf_sink(), which fills a buffer the caller owns. The ESP32-C5 update uses the buffer sink, because a synchronous sink would block AO_Radio for a round trip per chunk.

The decoder is one static session with five states.

stateDiagram-v2
direction LR
[*] --> IDLE
IDLE --> SNIFF: kfw_begin
SNIFF --> RAW: first byte 0xE9
SNIFF --> BODY: 72 header bytes accepted
SNIFF --> DEAD: bad header, wrong target, wrong chip
RAW --> DEAD: sink error
BODY --> DEAD: overrun, bad deflate, sink error
RAW --> IDLE: kfw_end or kfw_abort
BODY --> IDLE: kfw_end or kfw_abort
DEAD --> IDLE: kfw_end or kfw_abort

• SNIFF. One byte settles the raw case, since a raw image has no length to wait for. A raw image names its chip at byte 12 of its header, and one built for another chip than the target needs is refused before anything is placed. The P4 is the chip for the OS and app targets, the C5 for the C5 target. Any other first byte accumulates until 72 bytes are in, then kfw_hdr_parse() runs. A container that declares a different target than the caller asked for is refused: the command decides where an image goes and the file only agrees or not.
• Deflate. For a deflated payload the decoder takes a decompressor and a 32 KB dictionary from PSRAM. The inflater is tinfl_decompress in the P4's ROM, so compression costs the image no flash. A failed allocation frees whatever half succeeded and returns KODE_NO_RESOURCES.
• Digest. A SHA-256 (PSA Crypto) runs over the decoded output. At kfw_end() the count must equal image_len and the digest must match, both checked before sink->end(), so a bad image is abandoned and never committed. A raw image has no digest, and its sink's own check is the only one.
• Header callback. The callback fires with the image length and the container's name before the sink opens, so a caller that must place the image first, like the region's allocator, can.
• One session. kfw_begin() while one is open returns KODE_DENIED. AO_AppMgr and AO_Radio share the decoder, and each ends its own session with kfw_abort_owned(ctx).

kodeOS slots and the app guard

The kodeOS slots. kdrv_slot.c is the only file that calls the esp_ota_* functions. "The slot" means whichever of ota_0 and ota_1 kodeOS is not running (from factory it is ota_0).

kdrv_slot_begin() opens the write with OTA_WITH_SEQUENTIAL_WRITES, so the erase is spread over the writes and the console does not freeze for seconds. kdrv_slot_confirm_self() must run at the top of every boot from an OTA slot: an unconfirmed image keeps esp_ota_begin() refusing, and no later update can start. The slot sink refuses an image bigger than the slot before the first byte, when the length is known.

An app is built with a flash guard. In a firmware built with CONFIG_KODEOS_BOOT_ROLE_APP, an app runs in place from a data partition, and ESP-IDF's write guard finds no running app partition and aborts every persistent write. kdrv_slot.c then wraps esp_ota_get_running_partition() to answer with a synthetic app partition covering the running image (subtype APP_TEST, so kdrv_running_is_factory() stays false) and esp_ota_get_next_update_partition() to answer NULL. The --wrap flags sit under the same role guard in the layer's CMakeLists.txt. kodeOS itself is built without them.

Manifest, categories and app folder

The manifest and categories. An app may declare a display name and up to four categories in a kapp_desc_t placed at image offset 0x120: IDF's own esp_app_desc_t starts at 0x20 and is 256 bytes, and a section placed right behind it lands at a fixed, computable address. kdrv_apps_desc() reads the first KAPP_PREFIX_LEN bytes of an image with one flash read and extracts both descriptors. A missing manifest is the common case: the launcher then shows the app as a loose row at the root, in no folder.

After every parse, kapp_cat_resolve() looks for a category the board set for the app, and an override beats the image, silence included. The board's table is one NVS blob in PSRAM, written only by AO_AppMgr.

The app folder. An app can carry an app.json and a 64 by 64 icon in a folder next to its image, under .kode/appsdata/<project> on either medium. kapp_data_parse() reads the file into fixed-size fields, allocates nothing and refuses the whole file on any fault, so a caller never draws half a folder. How an app gets its icon is on internals/app-icon.

Specifications

The region

Offsets inside the region, counted from its start:

The directory

kapps_dir_t is 1044 bytes in each copy. The CRC32 covers every byte before it. The valid copy with the highest gen wins.

Each entry (kapps_entry_t):

The boot request

kapps_req_t is 20 bytes (KAPPS_REQ_LEN), frozen by a _Static_assert. The CRC32 covers magic to size only. The field state sits after the CRC, so the bootloader can advance it with a 4-byte write and keep the record valid.

Every step only clears bits: NEW to TRIED, ALWAYS to ARMED to TRIED. kapps_req_bounds_ok(offset, size, region_size) accepts an image only when it is at or past KAPPS_DATA_OFF, on a 64 KB boundary, not empty, not past the end of the region and fully inside it. The writer refuses a request that fails it, and the bootloader checks again, since flash is not safe only because a trusted writer wrote it once. The design is incompatible with flash encryption, which is not enabled.

An ARMED request survives these resets (kapps_req_cause_keeps(), a closed list, ROM numbering) while the mailbox is empty:

Power-on (which BOT+LEFT is), the watchdogs, a brownout, a full mailbox and any other cause retire it to TRIED, and kodeOS boots.

The mailbox

The word KAPPS_OS_INTENT_MAGIC (0x41544F4B, "KOTA") there means "adopt this as a kodeOS update, into the free OTA slot". Anything else, erased flash included, means "adopt this as an app", the default. A host tool writes the word separately, before the image. Nothing infers intent from the image's bytes. The constant is the contract with host tools that do not read the partition table, and a host test pins it to partitions.csv.

The container

A .kfw file is a 72-byte header and a payload. Everything in the header describes the decompressed image: the region allocator needs its length before the first byte is written, and the digest has to vouch for the image, since a digest of the payload would pass a correct transfer of a corrupt file.

kfw_hdr_parse() checks the magic (a mismatch is a quiet KODE_ERROR: not a container), the CRC, the version and length, the target and compression ranges, flags == 0, both lengths non-zero, payload_len == image_len when uncompressed, and a terminated name. It fills its output only on KODE_OK. KAPPS_KFW_MAGIC in kapps_fmt.h is a second copy of KFW_MAGIC, held equal by a _Static_assert, so the bootloader can tell a parked container from erased flash without the decoder. The host-side producer is tools/mkkfw.py in the kodeOS repository.

The manifest

kapp_desc_t is 136 bytes at image offset 0x120 (KAPP_DESC_OFF), checked at compile time against KAPP_IDF_DESC_OFF plus sizeof(esp_app_desc_t). Its offsets below count from the manifest's start.

An app declares it once, at file scope: KODE_APP_MANIFEST("Kode Runner", "game,demo");. Static asserts refuse a name or list that is too long. The magic is the only thing that tells a manifest from whatever else the linker put at 0x120 in an app that declared none.

kapp_desc_parse() is pure and trusts nothing, since every byte may have come off a card. Bad magic or an unterminated string is KODE_ERROR, which means "unmanifested" and is never a failure to report. A version 1 manifest (88 bytes, KAPP_DESC_V1_SIZE, one 16-byte category) is read by its own bound and never by sizeof(kapp_desc_t). Any other version is KODE_ERROR. Three more readers work on an image prefix: kapp_project_name(), kapp_idf_desc() (project, version, build date and time) and kapp_image_chip(), which reads the chip id at byte 12 of the image header and keeps a P4 image out of the C5.

The list has one form everywhere: lowercase words separated by commas. kapp_cat_normalise() lowercases, trims spaces, drops duplicates, caps the list at 4 and logs anything it drops. kapp_cat_has() matches a whole item, so game does not match games.

The override table is one NVS blob, namespace kode, key app_cats:

kapp_cat_deserialise() accepts a table only if all of it is valid. Magic, version, count and length must agree, and every project[] and category[] must carry a NUL inside its array. Each row's category is normalised on the way in. The rows live in PSRAM, taken once by kapp_cat_init(). A change is made in RAM first and persisted after, so a failed NVS write leaves the new table in RAM until the next boot, and the caller hears the failure.

The app folder

app.json is one flat JSON object of string values, at most 1024 bytes (KAPP_DATA_JSON_MAX). Escapes are limited to \" and \\. No numbers, arrays or nesting.

A key the reader does not know is ignored whatever its length, so a newer tool's file still works on an older board. kapp_data_parse() returns KAPP_JSON_OK, _NONE (no file), _SIZE (over 1024 bytes), _SYNTAX (outside the subset or a field over its limit) or _REVISION (kode missing or not "1"), and zeroes its output on anything but OK. The icon file icon.k64 is 12288 bytes (KAPP_ICON_BYTES): 64 by 64 pixels of RGB565 (8192 bytes) followed by 64 by 64 of alpha (4096 bytes).

The calls

The partitions behind the slot driver:

The files

Gotchas

Example code

An app that declares its name and category, which is the part of this layer an app author writes. Install it, and the launcher shows "Hello" in the folder examples.

/*
 * manifest.c - 2026-10-28 - from Kode with love
 *
 * Declares a display name and a category in the app's image, at offset
 * 0x120, then logs a line. After the install the launcher lists the app as
 * "Hello" in the folder "examples", and the log shows: hello from the apps
 * region.
 */
#include "kode.h"
 
#define TAG  "hello"
 
/* What the launcher shows, and the category it files this app under. */
KODE_APP_MANIFEST("Hello", "example");
 
/* Bring the system up, say hello, then idle so the console stays up. */
void app_main(void)
{
    kode_init();
    KLOG_N(TAG, "hello from the apps region");
 
    while (1) {
        kode_delay_ms(1000);
    }
}

Compiled against the SDK with ESP-IDF v6.1 on 2026-10-28. TBD: a run on a Kode Dot.

In the SDK

• components/kdrv/apps: the region, slot, container, manifest, category and app-folder code.
• kapps_fmt.h: the on-flash format, shared with the bootloader.
• bootloader_start.c: the other reader of kapps_fmt.h, in the kodeOS repository.