SDK

kdrv

The chip drivers of the Kode Dot: one per part, what each one hides, how the register tables work, and which page documents each chip.

What it is

kdrv is the layer that knows the chips. Each driver speaks to one part: it knows its address, its registers and its traps, and nothing about when the part should be used. That decision belongs to the part's owner, an Active Object in kaos. A driver is the only place in the SDK where a part number appears, so swapping a chip touches one file and the board description.

A driver page in this section is the whole story of a part: what the chip is, how the Kode Dot wires it, its registers, and how the driver is built over them. The Kode Dot pages (device/overview) say what a part does for your app; these pages say how it works underneath.

How it is connected

flowchart TB
ao["kaos<br/>the owner AO"] -- "function call" --> drv["kdrv<br/>the driver"]
subgraph below["Below the driver"]
  khal["khal"]
  kbsp["kbsp"]
  idf["ESP-IDF components"]
end
drv -- "khal_i2c, khal_gpio, ..." --> khal
drv -. "addresses, pins" .-> kbsp
drv -- "esp_lcd, esp_hosted, ..." --> idf
class ao ao

Calls in and out

A driver is called by exactly one Active Object, the part's owner, and calls down into khal for the shared services: the I2C bus, GPIO, time. Its address and pins come from kbsp as named constants; a driver never writes a pin number itself. Where Espressif or the chip vendor publishes a component, kdrv wraps it instead of rewriting it: the CO5300 panel through esp_lcd_co5300, the ES8311 codec through esp_codec_dev, the radio link through esp_hosted. Those versions are pinned exactly in the layer's idf_component.yml, because the numbers the drivers check were measured against them.

Public headers speak kode_status_t. No esp_err_t, no ESP-IDF type crosses a kdrv header, which is what keeps ESP-IDF out of every layer above.

Register maps

Register maps are tables. For the parts with a register map worth reading (the BQ25896, the CW2217, the TCA6408A, the CST820, the ES8311, the AW86233, the ST25R3916B, the ESP32-C5's status and the microSD card), every field the datasheet names is one row: register, bit position, width, scale, range, and whether it is writable.

• Two calls, get and set, read and write any field in its own unit, millivolts or milliamps rather than raw codes.
• A set writes only the field's bits. The charger, gauge, expander, touch and codec tables then read the register back, so a write the chip did not keep fails at once.
• The ESP32-C5 table is read-only. The microSD table reads the card, and its two writable rows set the bus width and clock the next mount asks for.
• The console prints the same tables, so pmic, ioexp, tp, audio and haptic show every field of their chip.
• What a table cannot say, a burst read or a register that clears when read, gets a typed call of its own.

Layout

Each module has include/ for its public header and src/ for its code. Every include/ is on the include path, so code writes #include "kdrv_bq25896.h" and never names the folder.

The parts

Every module of the layer, the chip or job it covers, and the page that documents it.

In the SDK

• components/kdrv: one folder per module.
• components/kdrv/idf_component.yml: the pinned components the drivers wrap.