SDK

Active Objects

The Active Objects of the Kode Dot: how they talk, their priorities, the start order and the page of each one.

What it is

kaos is the layer where every device of the Kode Dot gets an owner. The owner is an Active Object, or AO: a FreeRTOS task with its own queue of events and a state machine that handles one event at a time. The name is k + AOs. An AO decides when its device is used, and the driver below it in sdk/kdrv/overview knows how.

Your code never calls a driver. It sends the owner an event, or calls a function of the facade (sdk/kode) that sends it for you. The owner finishes one event before it starts the next, so two requests cannot interleave their writes to a chip and the code needs no lock.

kode_init() starts twenty-two AOs when every option is built in, and a twenty-third, AO_TestDot, with the E5 test. Device owners are never optional. What a firmware may leave out is policy: the console, the app installer, the self-test sequencer, the radio, the network, the rest of the board (AO_LowPower), the cron scheduler (AO_Scheduler) and the E5 final test (AO_TestDot). AO_LowPower decides whether the Kode Dot is awake, asleep or off, and AO_Scheduler runs entries on a clock. AO_Gui, the renderer of kodeOS, is not in kaos. It lives in kgui, above the SDK, and starts after kode_init() returns.

How it is connected

sequenceDiagram
autonumber
participant Host as Computer
box kodeOS
  participant Log as AO_Log
  participant Con as AO_Console
  participant Led as AO_LedMgr
end
participant Chip as KTD2026
Host->>Log: bytes of "led_rgb rgb=0,0,200"
Log->>Con: CONSOLE_LINE_SIG, published
Con->>Led: LED_RGB_SIG, published
Con->>Log: LOG_LINE_SIG, ">ok"
Led->>Chip: four registers over I2C
Log->>Host: ">ok"

Two ways to send

To post is to leave an event in the queue of one AO. To publish is to leave it for every AO that subscribed to the signal. A signal below MAX_PUB_SIG travels by publish, and one at or above it by post (sdk/kqp). AO_Log publishes the finished command line and does not know who listens. AO_Console subscribes, and so can an AO of yours.

One event at a time

An AO takes an event from its queue, handles it from start to end and takes the next. A step never waits for a network answer, a delay or a chip. A queue has a fixed size, and one more event than it holds stops the system with a QP assertion and a reset.

The worker rule

Work that has to wait leaves the AO for a worker, a task that belongs to that AO. The AO calls kqp_worker_submit() with a function and its argument, and carries on. The worker runs the job and posts one KqpWorkerDoneEvt back, with a sequence number, a status and one value.

A worker decides nothing. The state machine, the timeouts, the retries and the order of jobs stay in the AO, and the sequence number is how the AO tells a late answer from the one it waits for. Six AOs have workers: AO_Storage, AO_Radio, AO_Net, AO_Ir, AO_Audio and AO_Rfid. The list of workers is in sdk/kqp, and the rule is number 9 in sdk/design-rules.

Ownership is claimed at boot

In its initial transition each AO calls kaos_claim() for the resources it owns. A second claim on the same resource prints kodeOS: <resource> claimed by both <first> and <second> and stops the boot through Q_ERROR(), so the same mistake fails the same way at every boot.

The table of owners is a record. It takes no lock, and a driver called from another task is not stopped by it. The queue keeps the device safe.

Events carry copies

A list travels as one event per entry and an end marker. A page is posted to the AO that asked for it, never published, so a fast asker cannot fill the queue of a slow subscriber.

Specifications

The priorities

A higher number is a higher priority. The QP priority is the FreeRTOS priority of the task, so the console command ps prints this map live. The full table with the macros is in sdk/kqp.

The order of levels 18 to 23 ranks no urgency. They are the levels left above the first owners, and each AO is allowed there because its own step is short: the infrared AO queues a frame and returns, the NFC AO advances a state machine one step, the audio AO runs everything that blocks on its worker. Level 24 is the highest FreeRTOS gives a task on this port, and AO_LowPower holds it, so no level is left above the map. An AO that needs a level must not copy 18: its step has to be short, or the map is renumbered.

The startup order

kode_init() is the one place that knows the order. It starts the AOs on the main task, and QP runs each initial transition inside QACTIVE_START, so an AO has claimed its resources by the time the next one starts.

Before AO_Log starts, with KODE_LOWPOWER, kode_init() calls kode_boot_gate(), which sends a board woken from OFF by any button but BOT back to deep sleep (sdk/kaos/lowpower). After the twenty-second AO, kode_init() registers the SDK's settings (kaos_config_add()), starts the console reader task (log_start_reader()), calls sched_system_up() when the scheduler is built and calls QF_run(), which returns at once because the scheduler is already running. Posting to an AO that has no queue yet is a FreeRTOS assertion, xQueueGenericSend queue.c:936, and a boot loop.

With KODE_TEST_DOT, kode_init() also starts AO_TestDot, after the console and before AO_Power, in either boot role. It is dormant until the cable asks (sdk/kaos/test-dot).

A consumer such as kgui starts its own AOs after kode_init() returns and asks for state (display_state_request()) instead of waiting for an announcement it missed.

Who claims what

KBSP_RES_EXP, the expansion header, has no owner at boot. The console claims it on the first exp write, and the facade claims it on the first kode_exp_*() call. Both claims are late and each is refused by the same table: the console answers >err code=5 msg=owned, and the facade returns KODE_EXISTS. sdk/kbsp lists the 25 resources and the pins behind them.

The options

The radio, Bluetooth, MQTT and Kode channel options are on the pages of sdk/kaos/radio and sdk/kaos/net.

The files of core

Gotchas

The parts

In the SDK

• components/kaos: one folder per Active Object, plus core/.
• components/kaos/core: kaos.h, the claim, and the registry of settings.
• components/kbsp/owners: the table of owners kaos_claim() writes to.