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
The seven steps, with the layer each one happens in:
- Your task calls
kode_led_set_rgb(), declared inkode.h. Thekodelayer checks who is calling: a task goes on, an Active Object is refused. The firstkode.hcall of an app also starts the system. kodecallskode_sys_led_set_rgb(), the door an Active Object of your own would use. Underkode.hthere is always akode_sys.hcall.kode_sysposts an event to the owner. It takes aLedRgbEvtfrom the event pool, copies the three levels into it and puts it in AO_LedMgr's queue with the signalLED_RGB_SIG.- 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 returnsfalse. - 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. kdrv_ledturns the colour into registers of the KTD2026: one current register per channel, then the register that switches the channels on. It writes each one withkhal_i2c_write_reg().khal_i2csends the bytes on the bus every I2C driver shares, to address0x30. The address is a constant ofkbsp,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
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
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
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 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
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
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 layer | In the LED's path | Page |
|---|---|---|
Call, kode | kode_led_set_rgb() | sdk/kode |
Door, kode_sys | kode_sys_led_set_rgb() | sdk/kode |
Event, kqp | LED_RGB_SIG, carrying a LedRgbEvt | sdk/events |
Owner, kaos | AO_LedMgr, priority 7 | sdk/kaos/led |
Driver, kdrv | kdrv_led_rgb() | sdk/kdrv/ktd2026 |
Bus, khal | khal_i2c_write_reg() | sdk/khal |
Address, kbsp | KBSP_I2C_ADDR_LED, 0x30 | sdk/kbsp |
| Chip | KTD2026 | device/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.
| Part | Pages, from the owner down |
|---|---|
| Status LED | sdk/kaos/led, sdk/kdrv/ktd2026, device/led |
| Vibration | sdk/kaos/haptic, sdk/kdrv/aw86233, device/haptic |
| Touch | sdk/kaos/touch, sdk/kdrv/cst820, device/display |
| NFC | sdk/kaos/nfc, sdk/kdrv/st25r3916, device/nfc |
| Battery and power | sdk/kaos/power, sdk/kdrv/bq25896, sdk/kdrv/cw2217, device/power |
| Motion | sdk/kaos/imu, sdk/kdrv/qmi8658a, sdk/kdrv/qmc5883p, device/motion/overview |
| Buttons | sdk/kaos/buttons, sdk/kaos/ioexp, sdk/kdrv/buttons, sdk/kdrv/tca6408a, device/input |
| Audio | sdk/kaos/audio, sdk/kdrv/es8311, device/audio/overview |
| Files | sdk/kaos/storage, sdk/kdrv/storage, device/storage |
| RFID | sdk/kaos/rfid, sdk/kdrv/rfid, device/rfid |
| Wi-Fi and Bluetooth | sdk/kaos/radio, sdk/kdrv/c5, sdk/kdrv/radio, device/soc |
| Network | sdk/kaos/net, sdk/kdrv/radio |
| Infrared | sdk/kaos/ir, sdk/kdrv/ir, device/infrared |
| Screen | sdk/kscreen, sdk/kui, sdk/kaos/display, sdk/kdrv/co5300, device/display |
| J3 header | sdk/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
components/kode:kode.hand the code behind its calls,kode_led.cfor the LED.components/kaos/led:led_mgr.c, the Active Object that owns the LED.components/kdrv/led:kdrv_led.c, the driver of the KTD2026.