SDK

khal

The hardware services the Kode Dot's drivers share: I2C, console, time, GPIO, PWM, expansion header, SD card, NVS, PSRAM and identity, behind kode_status_t.

What it is

khal is the hardware abstraction layer of the SDK. It holds the services that several drivers share, and it is where ESP-IDF stops: above kdrv, no file includes esp_*, driver/*, freertos/*, soc/* or hal/*. The public headers speak kode_status_t for a result and opaque handles for an object. None uses esp_err_t.

Two kinds of code live in khal and nothing else:

• Code that the system creates exactly once and several drivers use: the I2C bus, the console transport, the LEDC, the heap.
• Code that could be done another way later while the layers above keep the same calls. The console is USB-Serial/JTAG today and could be a UART, and NVS could keep its values in a file.

A module is a header and a backend. A call goes from the caller to the header, to the backend file khal_<module>_esp.c, and then to ESP-IDF. A chip driver calls khal_i2c_write_reg(), and the ESP-IDF call that does the work happens inside khal_i2c_esp.c.

How it is connected

flowchart TB
subgraph above["Layers that call khal"]
  kdrv["kdrv<br/>chip drivers"]
  kaos["kaos<br/>Active Objects"]
  kqp["kqp<br/>QP tick, workers"]
end
khal["khal<br/>16 modules"]
subgraph below["What khal uses"]
  kbsp["kbsp<br/>pins, addresses"]
  klog["klog<br/>the log"]
  kdefs["kdefs<br/>kode_status_t"]
  idf["ESP-IDF drivers"]
end
kdrv --> khal
kaos --> khal
kqp --> khal
khal --> kbsp
khal --> klog
khal --> kdefs
khal --> idf
class kaos ao

khal requires kdefs, klog and kbsp, and all three are public, so an app that requires kode also sees the khal headers and kbsp.

The ESP-IDF drivers are private requirements: esp_adc, esp_driver_gpio, esp_driver_i2c, esp_driver_ledc, esp_driver_sdmmc, esp_driver_tsens, esp_driver_uart, esp_driver_usb_serial_jtag, esp_hw_support, esp_psram, esp_system, spi_flash, esp_timer, fatfs, nvs_flash, sdmmc and vfs.

A module that drives a device is not thread-safe. It has no lock, and two tasks must not call it at the same time. That is safe because each device has one owner, and only the owner calls the module (sdk/design-rules). The one exception is PWM, whose LEDC serves two owners, so khal_pwm has a lock.

A header never includes an ESP-IDF header. khal_i2c.h forward-declares ESP-IDF's two handle structures and hands out pointers to them, so a compiler can read every khal header without ESP-IDF and the host tests run on a computer. One vendor library, the codec component, needs the raw bus, and khal_i2c_bus() gives it out.

kode_init() brings khal up in a fixed order:

1. kode_log_init()
2. khal_heap_watch()
3. khal_identity_init()
4. khal_pwm_init()
5. khal_exp_init()

The I2C bus is created by the first driver that needs it, in the initial transition of its Active Object. khal_nvs_init() runs on first use.

Two build details live in the component's CMakeLists.txt:

• With esp-hosted compiled in, the linker wraps sdmmc_host_deinit, so tearing down the radio link releases only the radio's SDMMC slot and the microSD card keeps working.
• On a two-core build, the linker keeps port_start_app_hook, a hook that ESP-IDF references only weakly.

Specifications

The modules

One row per module, with the files that make it.

The component also carries Kconfig, idf_component.yml and CMakeLists.txt. idf_component.yml pins espressif/esp_tinyusb ==2.2.0, fetched only with the dock console.

i2c

I2C0 on SDA GPIO4 and SCL GPIO5 at 400 kHz, with the internal pull-ups on and a glitch filter of 7 clock cycles. Every transaction times out after 100 ms.

The ESP-IDF driver serialises transactions, so two owners that talk to two chips need no coordination. A run of several transactions with one chip stays safe because its owner does the whole run inside one step.

console

The console is the native USB-Serial/JTAG of the USB-C port. With CONFIG_KHAL_CONSOLE_DOCK it is also a TinyUSB CDC-ACM device on the magnetic pads (GPIO26 and GPIO27), and nothing above khal tells the two ports apart. The backend also builds for a plain UART.

Writes go through stdout and share newlib's stream lock. Reads never go through stdin: a select() on a VFS descriptor walks the file-system table that unmounting a FAT volume frees. The reader asks the transport driver for its bytes.

The calls of the console module:

The sizes and times the console module is built with:

Raw mode streams a firmware image in over the port that carried the command. One event per byte could not do it: a 500 KB image would be half a million events. The steps run in order:

1. A caller requests raw mode.
2. At its next pass the reader drains the pending input, promotes the request and calls on_armed.
3. Only then does the board tell the host to start the payload.
4. The reader calls pump, which reads chunks and ends the mode itself.

With the dock option, raw mode reads the one port that spoke last. The reader does the drain and the caller does not, because two readers of the driver's single-consumer ring would hang the console for good.

time

The board keeps UTC and no time zone. The constant lives in the header of klog because klog needs it for the timestamp and khal already depends on klog.

sync

A lock marks something that no Active Object owns, since an Active Object handles one event at a time. The mutex protects the few shared places:

• the internal FAT mount
• the BLE console ring
• the LEDC table in khal_pwm
• the answer slots of the C5's services
• the ring of the Kode channel's replies
• the busy flags of the blocking facade calls

The semaphore serves the screen flush and the waits of the blocking facade calls.

gpio

A pin that does not exist answers KODE_DENIED, and a configuration the driver refuses answers KODE_ERROR.

The interrupt service is installed without the IRAM flag. While the cache is off, for example during an image write, ESP-IDF masks the interrupt, which arrives late and not lost: a level is still there and an edge is latched.

pwm

The LEDC has 8 channels (KHAL_PWM_CHANNELS) and 4 timers (KHAL_PWM_TIMERS). A timer sets frequency and resolution, a channel sets duty and drives one pin.

Two users need it, the expansion header and the 125 kHz RFID carrier, and one table hands out both. All four timers run from PLL_F80M (80 MHz), because ESP-IDF refuses a timer whose source differs from one in use.

The duty is in tenths of a percent, 0 to KHAL_PWM_DUTY_MAX (1000). KHAL_PWM_BITS_WIDEST asks for the widest resolution at the frequency: the largest n with the frequency times 2^n at most 80 MHz, so 1000 Hz gets 16 bits and 125 kHz gets 9.

A refusal is one of three statuses:

• KODE_DENIED for a NULL pointer, a handle that is not open, a zero frequency, a duty over 1000 or an unreachable resolution.
• KODE_NO_RESOURCES for no channel or no timer.
• KODE_ERROR when the LEDC refused.

Each logs its reason at debug level on the tag khal.pwm.

exp

The expansion header by position, 1 to 14 (KHAL_EXP_POS_MIN to KHAL_EXP_POS_MAX), never by GPIO number. What each position can become is in KBSP_EXP[] (sdk/kbsp). A position is in exactly one mode.

The six modes:

The calls of the exp module:

Eight positions can be PWM at once, and four distinct frequencies, because the LEDC has eight channels and four timers. While the RFID field is up, its carrier holds one channel and one timer of its own, which leaves seven and three.

Every refusal logs its reason once at debug level on the tag khal.exp. khal_exp cannot tell who calls it. KBSP_RES_EXP is claimed by the console or by the facade, and that claim stops two owners from using one table.

clk

The module has no call that asks whether the 32 kHz crystal is enabled. ESP-IDF's version reads a bit of a power domain, so it returns true with the crystal desoldered.

If the crystal does not start at boot, ESP-IDF tries three times, then switches to the internal RC with one warning before the console exists and no flag. The mux read and the measurement together show it. Everything is counted against the main crystal, so an error in that crystal cannot be seen from the board (sdk/kdrv/clocks).

sdmmc

The P4 has one SDMMC controller with two slots. Slot 0 is the microSD card and slot 1 is the link to the ESP32-C5.

The volume keeps at most 5 files open and is made with 64 KB clusters.

khal_sdmmc_card_t is a copy of the card's CID, CSD, SCR and SSR registers and of the link as negotiated, taken once per mount, because ESP-IDF's sdmmc_card_t is a live handle and giving it out would put driver/sdmmc_host.h above khal.

The card's own supply is a pin that kdrv_storage switches before every mount (KBSP_PIN_SD_PWR). This module powers only the IO domain.

system

khal has no allocator that tries internal RAM first. The 640 KB of internal RAM are shared with every DMA buffer, interrupt and task stack, and an allocator that took it when it happened to fit would leave the board with none for the radio's HCI commands. A build that does not carry the board's memory policy stops with an #error in khal_system_esp.c (sdk/kbsp).

The start hook. The hook port_start_app_hook() stalls core 1 while core 0 starts the scheduler, then a one-shot task core1_go releases it.

Without it, core 1's wait loop races the stack fills of the new tasks and can raise a store fault on core 0 before app_main. A boot that faults never confirms a new OS slot. On one build 25 of 80 boots faulted without the hook and none of 97 with it.

worker

This is the task half. The Active Object half, KqpWorker, is in sdk/kqp. A worker knows nothing about events and decides nothing.

nvs

Small values in the nvs partition, behind one interface: strings, one byte, 64-bit values and blobs. Namespaces and keys have at most 15 characters. Every setter commits before it returns, and set_blob exists for records whose fields must agree, because one commit either lands or does not.

identity

The serial is computed and never stored. It comes from the base MAC of the ESP32-C5, because the identity key and the certificate live on that chip. A C5 replaced in a repair gives the board a new serial. The MAC is cached in NVS (namespace kident, key c5mac) because the C5 is not always reachable.

The encoding: the 6 MAC bytes, most significant first, are left-padded to 50 bits and read 5 bits at a time as 10 symbols of Crockford Base32 (no I, L, O or U), so the first symbol is always 0 to 7. One check symbol follows, Luhn mod 32 over the ten. It catches every single-symbol error and every swap of neighbours except 0 with Z.

KHAL_ID_LEN is 16 and KHAL_ID_PRETTY_LEN is 19, both with the terminator, and both pinned by _Static_assert to the length of KBSP_ID_PREFIX.

The C5 firmware builds the same serial from the same bytes for its certificate request, so the two encoders must stay identical. The serial identifies a board and proves nothing: it is advertised and printed, so anyone can claim it.

temp, crc32 and zlib

The decoder runs with HAS_MORE_INPUT, so a stream cut short stops and does not decode zeros. AO_AppMgr, AO_Radio and AO_Storage checksum their transfers with khal_crc32(). kdrv_apps.c calls the ROM routine itself with the seed UINT32_MAX, and the ROM inverts the seed, so its values differ from this module's for the same bytes.

Gotchas

Example code

Log the CRC-32 of the standard test text, then the free PSRAM and the state of the internal pool. The CRC reads 0xCBF43926, the known check value of CRC-32.

/*
 * khal_probe.c - 2026-10-28 - from Kode with love
 *
 * Calls three khal services from an app: the CRC-32 of "123456789", the free
 * PSRAM, and the internal RAM pool. On a Kode Dot the log shows the check
 * value 0xCBF43926 of CRC-32, then two lines of byte counts for the PSRAM
 * and the internal pool.
 */
#include "kode.h"
#include "khal_crc32.h"
#include "khal_system.h"
 
#define PROBE_TAG "probe"
 
/* Bring the system up, then log what khal reports. */
void app_main(void)
{
    static const char sample[] = "123456789";
 
    kode_init();
 
    uint32_t crc = khal_crc32(KHAL_CRC32_INIT, sample, sizeof(sample) - 1U);
    KLOG_N(PROBE_TAG, "crc32 of %s is 0x%08X", sample, (unsigned)crc);
 
    KLOG_N(PROBE_TAG, "free PSRAM %u bytes, largest block %u bytes",
           (unsigned)khal_psram_free(), (unsigned)khal_psram_largest());
    KLOG_N(PROBE_TAG, "internal pool: %u free, %u at its lowest",
           (unsigned)khal_heap_internal_free(), (unsigned)khal_heap_internal_low());
}

Compiled against the SDK with ESP-IDF v6.1 on 2026-10-28. TBD: a run on a Kode Dot.

In the SDK

• components/khal: one folder per module, each with include/ and src/.
• khal_exp.h: the expansion header by position.
• khal_system_esp.c: the heap, tasks, supervisor and start hook.