SDK

From a call to the chip

How one call in your app crosses every layer of the SDK down to a chip, followed for the status LED, and the same path for every part of a Kode Dot.

What it is

Every part of a Kode Dot is reached the same way. Your app makes a call. The call becomes an event for the Active Object that owns the part. The owner calls a driver, the driver uses a bus, and the chip does the work.

sdk/overview describes the layers one at a time. This page goes the other way: it takes one call, the one that lights the status LED, and follows it down through every layer. The LED has the shortest path on the board, so nothing hides the shape.

Every other part follows that shape and adds one thing of its own, such as a worker task or a second owner. The drawings after the LED's show the path of each part, grouped by what it adds.

How it is connected

flowchart TD
task["Your task"] -- "1 · kode_led_set_rgb()" --> kode["kode<br/>kode.h"]
kode -- "2 · kode_sys_led_set_rgb()" --> sys["kode_sys<br/>kode_sys.h"]
sys -- "3 · LED_RGB_SIG, LedRgbEvt" --> ao["AO_LedMgr<br/>priority 7"]
kode -. "4 · true: the queue took it" .-> task
ao -- "5 · kdrv_led_rgb()" --> drv["kdrv_led"]
drv -- "6 · khal_i2c_write_reg()" --> bus["khal_i2c"]
bus -- "7 · I2C, address 0x30" --> chip["KTD2026"]
class task app
class ao ao
class chip chip
One colour, from the call to the LED

The seven steps, with the layer each one happens in:

  1. Your task calls kode_led_set_rgb(), declared in kode.h. The kode layer checks who is calling: a task goes on, an Active Object is refused. The first kode.h call of an app also starts the system.
  2. kode calls kode_sys_led_set_rgb(), the door an Active Object of your own would use. Under kode.h there is always a kode_sys.h call.
  3. kode_sys posts an event to the owner. It takes a LedRgbEvt from the event pool, copies the three levels into it and puts it in AO_LedMgr's queue with the signal LED_RGB_SIG.
  4. The call returns true, because the queue holds the event. The LED has not changed yet. When the queue has no room, or the event pool is empty, the call tries again every 10 ms, and after 100 ms it returns false.
  5. AO_LedMgr takes the event when its turn comes, at priority 7, and calls kdrv_led_rgb(). It claimed the chip at boot, so it is the only code that calls this driver.
  6. kdrv_led turns the colour into registers of the KTD2026: one current register per channel, then the register that switches the channels on. It writes each one with khal_i2c_write_reg().
  7. khal_i2c sends the bytes on the bus every I2C driver shares, to address 0x30. The address is a constant of kbsp, KBSP_I2C_ADDR_LED. The KTD2026 changes the current of its three outputs and the LED shows the colour.

Steps 1 to 4 know nothing about the chip, and steps 6 and 7 know nothing about who asked. AO_LedMgr, in the middle, is the one place that knows both.

One owner, one driver, one chip

Four parts have the LED's path as it is. Each column is one part, read from top to bottom: the calls in kode.h, the owner, its driver, then the chip and its bus.

flowchart TD
c_led["kode_led_*"] --> a_led["AO_LedMgr<br/>priority 7"] --> d_led["kdrv_led"] --> h_led["KTD2026<br/>I2C 0x30"]
c_hap["kode_haptic_*"] --> a_hap["AO_Haptic<br/>priority 22"] --> d_hap["kdrv_aw86233"] --> h_hap["AW86233<br/>I2C 0x5A"]
c_tch["kode_touch_read()"] --> a_tch["AO_Touch<br/>priority 14"] --> d_tch["kdrv_cst820"] --> h_tch["CST820<br/>I2C 0x15"]
c_nfc["kode_nfc_*"] --> a_nfc["AO_Nfc<br/>priority 19"] --> d_nfc["kdrv_st25r3916"] --> h_nfc["ST25R3916B<br/>SPI"]
class c_led,c_hap,c_tch,c_nfc app
class a_led,a_hap,a_tch,a_nfc ao
class h_led,h_hap,h_tch,h_nfc chip
The plain path

Two chips, or two owners

AO_Power and AO_Imu each own two chips, so each calls two drivers. The buttons have two owners. AO_IoExp owns the expander and publishes its inputs. AO_Buttons turns them, and the top button's own pin, into presses.

flowchart TD
c_pw["kode_battery_*<br/>kode_power_*"] --> a_pw["AO_Power<br/>priority 8"]
a_pw --> d_bq["kdrv_bq25896"] --> h_bq["BQ25896<br/>I2C 0x6B"]
a_pw --> d_cw["kdrv_cw2217"] --> h_cw["CW2217<br/>I2C 0x64"]
c_mo["kode_imu_*<br/>kode_mag_*"] --> a_mo["AO_Imu<br/>priority 21"]
a_mo --> d_qmi["kdrv_qmi8658"] --> h_qmi["QMI8658A<br/>I2C 0x6A"]
a_mo --> d_qmc["kdrv_qmc5883p"] --> h_qmc["QMC5883P<br/>I2C 0x2C"]
class c_pw,c_mo app
class a_pw,a_mo ao
class h_bq,h_cw,h_qmi,h_qmc chip
Two chips under one owner
flowchart TD
c_bt["kode_button_*"] --> a_bt["AO_Buttons<br/>priority 13"]
a_bt --> d_bt["kdrv_buttons"] --> h_bt["Top button<br/>GPIO35"]
a_bt -. "subscribes to<br/>IOEXP_INPUT_SIG" .-> a_io["AO_IoExp<br/>priority 17"]
a_io --> d_io["kdrv_tca6408a"] --> h_io["TCA6408A<br/>I2C 0x20"]
class c_bt app
class a_bt,a_io ao
class h_bt,h_io chip
The buttons' two owners

A worker task

An owner never waits. When the driver's work takes time, the owner hands it to a task of its own, the worker. The worker calls the driver, and the result comes back to the owner as an event (sdk/kaos/overview).

flowchart TD
c_au["kode_audio_*"] --> a_au["AO_Audio<br/>priority 20"] --> w_au["audio_worker"] --> d_au["kdrv_es8311"] --> h_au["ES8311<br/>I2C 0x18, I2S"]
c_fs["kode_file_*"] --> a_fs["AO_Storage<br/>priority 5"] --> w_fs["storage_sd"] --> d_fs["kdrv_storage"] --> h_fs["microSD<br/>SDMMC"]
c_rf["kode_rfid_*"] --> a_rf["AO_Rfid<br/>priority 23"] --> w_rf["rfid_worker"] --> d_rf["kdrv_rfid_lf"] --> h_rf["125 kHz<br/>front end"]
class c_au,c_fs,c_rf app
class a_au,a_fs,a_rf ao
class h_au,h_fs,h_rf chip
The owner decides, its worker calls the driver

The ESP32-C5

Wi-Fi, Bluetooth and infrared are hardware of the second processor. Their drivers reach it over the SDIO link, which AO_Radio owns. The network has no chip of its own: its code runs on the P4 and uses the same link. All three owners have a worker.

flowchart TD
c_ra["kode_wifi_*<br/>kode_ble_*"] --> a_ra["AO_Radio<br/>priority 4"] --> w_ra["radio_worker"] --> d_ra["kdrv_radio<br/>kdrv_ble"] --> c5["ESP32-C5<br/>SDIO"]
c_ne["kode_http_*<br/>kode_mqtt_*"] --> a_ne["AO_Net<br/>priority 2"] --> w_ne["net_worker"] --> d_ne["kdrv_net"] --> c5
c_ir["kode_ir_*"] --> a_ir["AO_Ir<br/>priority 18"] --> w_ir["ir_worker"] --> d_ir["kdrv_ir"] --> c5
class c_ra,c_ne,c_ir app
class a_ra,a_ne,a_ir ao
class c5 chip
Three paths that end on the ESP32-C5

Layers above the owner, or no owner

The screen has layers above its owner. Your calls go to kode_screen, which draws with sdk/kscreen and sdk/kui, and each finished frame is one event to AO_Display. The J3 header has no owner: it belongs to your app, and the call uses khal_exp with no Active Object in between.

flowchart TD
c_sc["kode_screen_*<br/>kode_widget_*"] --> u_sc["kscreen, kui<br/>LVGL"] --> a_sc["AO_Display<br/>priority 15"] --> d_sc["kdrv_display"] --> h_sc["CO5300<br/>MIPI-DSI"]
c_j3["kode_pin_*<br/>kode_i2c_*"] --> d_j3["khal_exp"] --> h_j3["J3 header"]
class c_sc,c_j3 app
class a_sc ao
class h_sc,h_j3 chip
The screen's path and the J3 header's

What comes back up

A call that returns data, such as kode_imu_read() or kode_file_read(), waits in your task, with a time limit, until the owner has written the answer. A part with news of its own (touch, infrared, NFC, Wi-Fi, Bluetooth) publishes an event when something happens, and the kode layer has one Active Object that hears it and keeps it for your task.

Specifications

The stops of the LED's path

One row per stop: what it is and the layer it belongs to, its name in this path, and the page that documents it.

Stop and layerIn the LED's pathPage
Call, kodekode_led_set_rgb()sdk/kode
Door, kode_syskode_sys_led_set_rgb()sdk/kode
Event, kqpLED_RGB_SIG, carrying a LedRgbEvtsdk/events
Owner, kaosAO_LedMgr, priority 7sdk/kaos/led
Driver, kdrvkdrv_led_rgb()sdk/kdrv/ktd2026
Bus, khalkhal_i2c_write_reg()sdk/khal
Address, kbspKBSP_I2C_ADDR_LED, 0x30sdk/kbsp
ChipKTD2026device/led

The pages of each path

The page of every box in the drawings, in the order of the path: the owner, the driver, then the page that describes the part on the Kode Dot. The calls of every part are on sdk/kode.

PartPages, from the owner down
Status LEDsdk/kaos/led, sdk/kdrv/ktd2026, device/led
Vibrationsdk/kaos/haptic, sdk/kdrv/aw86233, device/haptic
Touchsdk/kaos/touch, sdk/kdrv/cst820, device/display
NFCsdk/kaos/nfc, sdk/kdrv/st25r3916, device/nfc
Battery and powersdk/kaos/power, sdk/kdrv/bq25896, sdk/kdrv/cw2217, device/power
Motionsdk/kaos/imu, sdk/kdrv/qmi8658a, sdk/kdrv/qmc5883p, device/motion/overview
Buttonssdk/kaos/buttons, sdk/kaos/ioexp, sdk/kdrv/buttons, sdk/kdrv/tca6408a, device/input
Audiosdk/kaos/audio, sdk/kdrv/es8311, device/audio/overview
Filessdk/kaos/storage, sdk/kdrv/storage, device/storage
RFIDsdk/kaos/rfid, sdk/kdrv/rfid, device/rfid
Wi-Fi and Bluetoothsdk/kaos/radio, sdk/kdrv/c5, sdk/kdrv/radio, device/soc
Networksdk/kaos/net, sdk/kdrv/radio
Infraredsdk/kaos/ir, sdk/kdrv/ir, device/infrared
Screensdk/kscreen, sdk/kui, sdk/kaos/display, sdk/kdrv/co5300, device/display
J3 headersdk/khal, device/expansion

Gotchas

Example code

This asks for a dim yellow on the status LED and prints what the call answered. You see the LED turn yellow and the line led: the owner took it in the serial log.

/*
 * led_path.c - 2026-11-10 - from Kode with love
 *
 * Asks for one colour on the status LED of a Kode Dot and says whether the
 * LED's owner took the request. The call posts one event to AO_LedMgr, which
 * calls the driver, which writes to the KTD2026 over I2C. You will see the
 * LED turn a dim yellow and the line "led: the owner took it" in the serial
 * log.
 */
#include "kode.h"
 
/* Asks for a dim yellow and reports what the call answered. */
static void led_show_yellow(void)
{
    /* a quarter of Bold Yellow: at full level this LED is bright */
    bool taken = kode_led_set_rgb(64, 43, 0);
 
    if (taken) {
        kode_print("led: the owner took it");
    } else {
        /* the owner's queue stayed full for 100 ms */
        kode_print("led: refused, %s", kode_error());
    }
}
 
/* The first kode.h call starts the system: there is nothing to bring up. */
void app_main(void)
{
    led_show_yellow();
}

Compiled on the date in the header against SDK v0.1.0 with ESP-IDF v6.1. It has not been run on a Kode Dot.

In the SDK