# 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

```mermaid
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.

```mermaid
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.

```mermaid
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*

```mermaid
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`).

```mermaid
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.

```mermaid
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.

```mermaid
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 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

> **NOTE**
>
> **The call returned `true` and the LED has not changed.** `true` means AO_LedMgr's queue took the event. The chip is written when the owner's turn comes. Do not use the return value as proof that the colour shows.

> **WARNING**
>
> **A `kode.h` call made from an Active Object fails.** The log says `was called from an Active Object`, and so does `kode_error()`. The calls of `kode.h` may wait, and an Active Object must never wait. From an Active Object, use the `kode_sys_*` call of the same part: its answer arrives as an event.

## 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.

```c
/*
 * 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`](https://github.com/kodediy/kode-sdk/tree/main/components/kode): `kode.h` and the code behind its calls, `kode_led.c` for the LED.
- [`components/kaos/led`](https://github.com/kodediy/kode-sdk/tree/main/components/kaos/led): `led_mgr.c`, the Active Object that owns the LED.
- [`components/kdrv/led`](https://github.com/kodediy/kode-sdk/tree/main/components/kdrv/led): `kdrv_led.c`, the driver of the KTD2026.
