SDK

AO_Boot

The Active Object that decides which firmware starts after a reset: otadata, the boot request, the short leave before every reset, and the bottom-button hold.

What it is

After every reset the bootloader picks a firmware. Two small records in the flash hold that choice. otadata names the kodeOS slot that starts when nothing else is asked. The boot request, a sector of the apps region, names one app to start instead. AO_Boot owns both records and is the only code that writes them. Which images the flash holds is AO_AppMgr's business (sdk/kaos/appmgr). Which one starts is AO_Boot's.

It runs in kodeOS and inside every app, and the build role decides what it writes. In an app it claims the records and writes nothing, so any reset comes back to kodeOS. In kodeOS it confirms a new update, works out why the board started, and carries out four requests: switch slot, run an app, report, exit. Every restart it makes passes through a short leave first. A hold of the bottom button publishes HOME_SIG and, in an app, resets the board home even when the app is hung.

How it is connected

stateDiagram-v2
[*] --> Boot_active : claim, subscribe BUTTON_HOLD_SIG, act on the role
Boot_active --> Boot_leaving : slot switch, app run, exit, home
Boot_active --> Boot_active : info, hold, defer
Boot_leaving --> [*] : khal_restart() after 150 ms

sequenceDiagram
autonumber
box "kodeOS"
  participant B as AO_Boot
  participant N as AO_Net
  participant R as AO_Radio
end
B->>N: NET_LEAVE_REQ_SIG, 200 ms bound
N-->>B: BOOT_NET_LEFT_SIG
B->>R: RADIO_PARK_REQ_SIG, 250 ms bound
R-->>B: BOOT_RADIO_PARKED_SIG
Note over B: wait 150 ms, then khal_restart()

AO_Boot in numbers:

In both roles its initial transition also restores the wall clock from the RTC or from the last value AO_Power kept (sdk/kaos/power).

The role

KODEOS_BOOT_ROLE_APP is the default, so a firmware that forgets to say what it is behaves like an app and cannot keep the board. KODEOS_BOOT_ROLE_OS is kodeOS itself. The initial transition then does four things in order:

1. Confirm. kdrv_slot_confirm_self() clears the PENDING_VERIFY mark of a freshly updated image. This is mandatory: esp_ota_begin() refuses to open an update session from an unconfirmed partition.
2. Work out why the board started. The bootloader marks a request TRIED before it jumps to an app, so a TRIED request means the board is back from an app. AO_Boot sets the reason KBOOT_FROM_APP, remembers the app's offset and clears the request. Any other state sets KBOOT_COLD, and a request still present is cleared as stale.
3. Detect a failed update. Running from factory while otadata is not blank means an update died before it confirmed. AO_Boot sets KBOOT_UNEXPECTED and clears otadata, so the board stays on factory.
4. Classify how the app ended, from the chip's reset reason (boot_app_end()).

The leave

Every deliberate restart does its own write first (the slot, the boot request, or nothing), records the role of the firmware it goes to and enters Boot_leaving. There AO_Boot runs these steps:

1. Ask AO_Net to stop the Kode channel cleanly.
2. Ask AO_Radio to hang up Bluetooth and park the C5.
3. Wait 150 ms, so the reply to the command that caused the reset leaves the console.
4. Call khal_restart().

Each of the first two steps has its own bound on the leave timer. A silent neighbour delays the reset by its bound and no more.

In Boot_leaving every other restart request and every home gesture is logged and dropped: the first request wins and the board resets once.

The hold

With the bottom button held for KODE_BUTTON_HOLD_MS, AO_Buttons publishes BUTTON_HOLD_SIG. AO_Boot is the only owner of that gesture. It publishes HOME_SIG, which the launcher of kodeOS or an AO of yours answers.

With KODEOS_HOME_HOLD (app role) it then arms the home timer for 200 ms and resets the board home when it expires. An app that needs the time to save calls kode_home_defer() from its HOME_SIG handler, writes, and calls kode_home_now(). The wait is capped at 3 s from the hold, once.

Resting with the board

AO_Boot owns no device that sleeps, but it joins the rounds of AO_LowPower as boot (sdk/kaos/lowpower). A board that went to sleep between the write of a boot request and the reset would wake into the old firmware, so AO_Boot answers a round busy while a restart is on its way and ready otherwise:

• home pending while an app's deferral of the hold is running (kode_home_defer()), which is a restart a moment away;
• restart pending in Boot_leaving, from the write of the request to the reset;
• factory reset while a factory reset runs, so the board cannot rest in the middle of it.

AO_Boot restores nothing when the board wakes. A new kodeOS slot confirms itself in the initial transition, before any round can begin, so no confirmation is ever pending to wait for.

The time zone

AO_Boot owns the setting zone (kset/zone, internals/settings). It applies the stored zone in its initial transition, before an app runs, so the face, the FAT timestamps and an app's localtime_r() read the same local time from the first second.

A zone must be a POSIX TZ string, std offset [dst [offset] [,start[/time],end[/time]]], of at most 32 characters. config key="zone" refuses anything else with >err code=5 msg=value and stores nothing, so text the C library would read as no zone, or as an offset of days, never reaches the face. A stored zone that is not one, left by an older build, is ignored at boot: the clock runs in UTC and the log says zone: UTC0 (none stored). A zone the C library has no memory for is not stored either, and the log names the zone that stays.

Specifications

The requests

The private signals are BOOT_LEAVE_TMO_SIG, the bound of the leave step that is running, and BOOT_HOME_GRACE_SIG, the grace and then the cap. A build without KODEOS_NET or KODEOS_RADIO skips that step of the leave.

What it sends

The states of a boot

An unknown reset reason reads as clean and never as a crash.

The timings

The calls

AO_Boot has one stored setting, zone, and no console verb of its own besides boot_info. The options are KODEOS_BOOT_ROLE_APP or _OS and KODEOS_HOME_HOLD, which depends on the app role.

Gotchas

Example code

Light the LED blue for three seconds, then hand the machine back to kodeOS. With the app running the LED turns blue, and after three seconds the screen shows the launcher of kodeOS again.

/*
 * home_after_3s.c - 2026-10-28 - from Kode with love
 *
 * Lights the status LED blue, waits three seconds, then asks AO_Boot to
 * leave the app. AO_Boot runs its short leave and resets, and the bootloader
 * brings kodeOS back. On a Kode Dot the LED goes blue, then the launcher
 * returns.
 */
#include "kode.h"
 
/* Bring the system up, show a colour, wait, then go home. */
void app_main(void)
{
    kode_init();
    kode_led_rgb(0, 0, 64);
    kode_delay_ms(3000);
    kode_exit_to_os();
}

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

In the SDK

• components/kaos/boot: boot_ao.c, the state machine, the leave and the hold.
• components/kdrv/apps: kdrv_slot and kdrv_apps, the otadata and boot-request primitives AO_Boot calls.
• kode.h: kode_exit_to_os(), kode_home_defer() and kode_home_now().