kodeOS internals

Settings

Every setting a Kode Dot stores across restarts, which Active Object owns it, its values and default, and how the console verb config reads and changes it.

What it is

kodeOS keeps some settings across a restart and a power cycle: the brightness, whether Wi-Fi and Bluetooth are wanted, the volume, the time zone and a few more. They all live in the nvs partition, the flash store ESP-IDF uses for small values. You read and change every one of them with one console verb, config.

Each setting is read and written by the one Active Object that applies it, and no other code touches it. So each stored value has one owner and the store needs no lock. The console never touches the store either. It sends a request for one key at a time, and the owner reads, applies, stores and answers.

Nothing in the store is a secret. Wi-Fi passwords and Bluetooth bonds live on the ESP32-C5. Every value here sits in plain flash, and any console and any app on the board can read it.

How it is connected

sequenceDiagram
autonumber
participant Host as kcli.py
box "On the Kode Dot"
  participant Con as AO_Console
  participant Own as owner AO
  participant Nvs as khal_nvs
end
Host->>Con: config key="bright" value=40
Con->>Own: CONFIG_REQ_SIG (key, value)
Own->>Own: apply
Own->>Nvs: store
Own->>Con: kode_config_answer()
Con->>Host: >|config key="bright" value=40 stored=yes

Each setting is a row of type kode_config_t in a registry (kode_config.h). Each Active Object registers the rows it owns as it starts, and kgui registers its six when AO_Gui has a queue. A table with one bad row is refused whole, with a log line naming the row.

An app can add rows of its own with KODE_CONFIG_ADD() and answer them from its own Active Object. They join the same listing. The registry holds at most KODE_CONFIG_MAX = 32 rows in KODE_CONFIG_TABLES = 4 tables. A key is lowercase letters, digits and _, at most 15 characters.

The console reads and sets in three forms:

• config lists every row, one record each.
• config key="bright" reads one.
• config key="bright" value=40 sets one and answers with what the owner kept.

A record reads >|config key="bright" value=40 stored=yes. stored=no means the key is not in the store and the value shown is the default. Setting a value back to its default erases the key for log, for scene set to auto, for kody_sleep set to lock and for mag_cal set to "".

A value is typed like a function argument: a string is quoted and every other kind is bare, and the console refuses the wrong form with >err code=3 msg=value. A boolean is on or off. An integer outside its range, a word not in an enum, or a wrong form gets the same refusal. Strings hold at most 32 characters, and an enum lists at most six words (KODE_VALUE_ENUMS_MAX).

Specifications

The twenty-four settings

A row exists only in a build that has its feature. config prints the keys in the order their owners registered them. Each owner registers its table as it starts, so the order is the order of the start: in kodeOS log, zone, off_after, bright, lock, scene, clock, kody_sleep, haptic_ui, usb_awake, wifi, ble, wifi_join, wifi_ps, chan, chan_keep, vol, mic_db, mute, mag_cal, haptic, led_activity, charge, charge_ma. A build with Wi-Fi, Bluetooth, the Kode channel and low power lists 24 rows. An app built with CONFIG_KODE_LOWPOWER_IDLE also has sleep_after; kodeOS builds without it, because its Rest decides when the board rests. The tables below group them by what they control.

Settings: display, log, audio and haptic

The panel, the console's log level, the codec, the compass and the motor.

Settings: radio and network

Wi-Fi, Bluetooth and the Kode channel. The rest of the board has its own table below.

Settings: the rest

When the board rests (sdk/kaos/lowpower).

Settings: power

The LED and the charger.

Settings: the clock

The time zone belongs to AO_Boot, which applies it at boot before an app runs.

Settings: the face

Four of the six rows kgui owns: the clock's format, the lock and Kody.

Settings: the interface

The other three rows of kgui. Each applies at once and is stored on every set, even when the value is the stored one. A byte the setting does not have reads as the default, with a warning.

How each one is stored

All keys are in the NVS namespace kset, except kgui's six (lock, scene, clock, kody_sleep, haptic_ui, usb_awake), which are in kgui. Namespaces and keys are at most 15 characters, NVS's own limit.

Other things in the same partition

These have no row in config.

The nvs partition is 64 KB at 0xB000. khal_nvs_init() erases it and starts again when ESP-IDF reports no free pages or a newer version. A reader returns KODE_DENIED for an absent key and for a namespace never written, and that is not an error: the caller applies its default.

What survives a restart: the settings above, the last launched row, the wall clock (marked approximate), the entries of cron, the summary of the last rest, the category overrides, the kapp keys and the bonds.

What does not: the C5 link, the Wi-Fi connection and address, any MQTT session, the commands that wait in the queue of the Kode channel (RAM, already acknowledged by the broker), the scan tables and the selection in the launcher.

Gotchas

Example code

List every setting, set the brightness to 40 and read it back. The second command prints a record with value=40 and stored=yes. The last command writes all settings to settings.json, and config-import writes back only the keys that differ.

# settings.sh - 2026-10-28 - from Kode with love
#
# Lists every stored setting of a Kode Dot, dims the screen to 40 per cent,
# reads the value back, and saves all settings to a JSON file. The second
# command prints a record with value=40 and stored=yes. Opening the port
# resets the board, so the three config commands share one session.
python3 tools/kcli.py -p /dev/cu.usbmodem101 --settle 5 cmd 'config' 'config key="bright" value=40' 'config key="bright"'
python3 tools/kcli.py -p /dev/cu.usbmodem101 --settle 5 config-export -o settings.json

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

In the SDK

• components/kaos/core/src/kset.h: the names of the kset keys and their limits.
• components/kaos/core/include/kode_config.h: the registry and KODE_CONFIG_ADD().
• components/kgui/kgui_ao.c: the six kgui rows and their owner.