kodeOS internals

Overview

How kodeOS works inside: its boot, console, screens, tests and releases. For people working on kodeOS itself, not for writing an app.

What it is

This section is the inside of kodeOS: how it boots, the console and its commands, how each screen is built, its memory, tests and releases. It is for people who work on kodeOS itself or want to know how it is made. To learn what kodeOS is and how to use it, read ecosystem/kodeos. To write an app, start at build/setup: none of this is needed for that.

kodeOS is the firmware a Kode Dot runs when you switch it on. It draws the face with the clock, lists the installed apps, shows the settings, rests the board when nobody uses it, runs entries on a clock, answers text commands from a computer and installs and starts apps. It is the one firmware every Kode Dot ships with.

kodeOS is built from the SDK (sdk/overview) the same way your app is. Its main/main.c is two calls. kode_init() starts the drivers, the Active Objects that own every chip and the console. kgui_start() starts the screens. The SDK supplies everything those calls start. The screens, the bootloader override and the way the flash is used live in the kodeOS repository, kodediy/KodeOS.

An app is a whole firmware. kodeOS writes the app's .bin into a region of the flash and the bootloader starts it in place. While it runs, kodeOS does not. Any reset brings the board back to kodeOS, because the app never writes the record that says which kodeOS slot starts. The one exception is a sketch uploaded from the Arduino IDE, which restarts after the resets its own host causes (internals/boot-model).

To build an app, start at build/setup, build/first-build and build/flash. To build kodeOS itself, read internals/building-and-flashing.

How it is connected

flowchart LR
person["buttons and touch"] --> kgui["kgui_start(): face, Apps, Settings"]
host["computer: USB-C, Bluetooth, charging base"] --> console["AO_Console"]
main["main/main.c"] --> init["kode_init()"]
main --> kgui
init --> console
init --> owners["owner Active Objects"]
kgui --> owners
console --> owners
bl["bootloader override"] --> app["app in the apps region"]
class person,host ext
class console,owners ao
class app app
class bl chip

A person reaches kodeOS through the screen and the six buttons under it.

A computer reaches it through the console, a text command line. The console runs on:

• the USB-C cable (the native USB-Serial/JTAG port);
• Bluetooth;
• with CONFIG_KHAL_CONSOLE_DOCK=y, the magnetic pads of the charging base.

A computer can also write the flash directly with esptool.

Every chip has one owner, an Active Object. The screens, the console and your own code ask the owner by event and never touch the chip. sdk/kaos/overview has the owners and sdk/design-rules the reason.

The flash holds three copies of kodeOS (factory, ota_0, ota_1), the apps region, the app_pending mailbox and a 2 MB FAT volume (internals/boot-model has the table). The bootloader is the standard ESP-IDF one plus a few steps of kodeOS's own that start an app when a boot request names one.

Opening the console port reboots the board. The USB-Serial/JTAG peripheral resets the P4 on attach, so a script that needs a Wi-Fi join or an MQTT session does the whole sequence inside one open session.

Specifications

The parts

Every page of the kodeOS section, in sidebar order, in groups.

How kodeOS starts and what it holds

Apps

The console

The screens

Building, testing and releasing

In the SDK

• main/main.c: the two calls that start kodeOS.
• components/kgui: the screens, above the SDK.
• components/kode: the facade whose kode_init() starts the system.