SDK

Wi-Fi, BLE and network

The Wi-Fi station, the Bluetooth LE host with its console service, and the network stack with HTTP, MQTT and ping, all over the ESP32-C5's radio.

What it is

A Kode Dot has no radio on the ESP32-P4, so three drivers turn the radio of the ESP32-C5 into things an app can use:

• kdrv_wifi is the Wi-Fi station. It scans both bands, joins a network, leaves it and reports where the connection stands.
• kdrv_ble is Bluetooth LE. It advertises, scans, pairs and bonds, and carries the console as a Bluetooth service.
• kdrv_net is the network above an address: DNS, ping, HTTP and HTTPS, UDP, an MQTT client and the time.

The first two drive the C5 with remote calls over the link described in sdk/kdrv/c5. The third never touches the link. lwIP runs on the P4, and the C5 only carries frames.

How it is connected

flowchart LR
subgraph p4["ESP32-P4"]
  ao["AO_Radio<br/>radio_worker"] --> run["kdrv_radio_run()"]
  run --> wifi["kdrv_wifi"]
  run --> ble["kdrv_ble<br/>NimBLE"]
  net["AO_Net<br/>net_worker"] --> knet["kdrv_net<br/>lwIP"]
end
wifi -- "RPC" --> c5["ESP32-C5"]
ble -- "HCI over SDIO" --> c5
knet -- "frames" --> c5
class ao,net ao
class c5 chip

The two owners

AO_Radio (sdk/kaos/radio) owns Wi-Fi and Bluetooth. It hands each call to its radio worker as a job of kdrv_radio_run(), one at a time, and the driver functions run only there. Nothing in them takes a lock: correctness rests on that one worker, and on the C5's RPC channel serving one request at a time. A call from another task brings back the failure the design avoids, an intermittent "0 networks".

AO_Net (sdk/kaos/net) owns the network. It runs kdrv_net_run() from its own worker, net_worker, at the lowest Active Object priority (2), so network I/O only ever delays itself. lwIP can serve several requests at once, so its one-job-at-a-time rule protects only the driver's result tables.

Build options

Three Kconfig options gate the build: KODEOS_WIFI compiles kdrv_wifi, KODEOS_BLE compiles kdrv_ble and kdrv_ble_tokens, and KODEOS_NET (which needs Wi-Fi) compiles kdrv_net. KODEOS_MQTT gates the MQTT client inside kdrv_net. With it off the public MQTT calls still link and refuse with KODE_DENIED.

Wi-Fi

The driver stores no credentials. It takes a name and a password as arguments and remembers only the network it has joined. Saved networks live in the C5's vault.

The station netif is created late, on purpose. The default station netif sends its own RPCs when it starts. During a blocking scan those RPCs time out and the channel loses its order. So kdrv_wifi_start() starts a station with no netif, which is enough to scan, and the first join creates the netif with the stack stopped and restarted around it. That costs two extra RPCs, once.

The netif must exist before the station starts, because it sets itself up from WIFI_EVENT_STA_START. One created afterwards never gets an input path.

A scan sweeps the channels in seven steps, each its own non-blocking start and wait: three for 2.4 GHz and four for the 28 slots of 5 GHz, with the country deciding which slots the stack keeps. The scan is active, shows hidden networks and dwells 200 to 500 ms per channel.

Each answer from the C5 causes cache invalidations on the P4, and under heavy SDIO traffic they can fault the tick interrupt with an illegal instruction. Seven steps cut those invalidations by a factor of six, and the first results still arrive within seconds. A sweep takes about 38 s on a Kode Dot.

Results travel two ways:

• Everything found goes through a hand-over ring of 96 entries that AO_Radio drains as the sweep runs, so a crowded street lists all its networks.
• A table keeps the strongest 24 for autojoin and the production test.

The sweep does not stop when the table is full, because a crowded lower band would otherwise hide the whole upper one.

A join waits for the lease. It returns when DHCP has given an address, which comes after the association. The driver has no reconnect policy, because only AO_Radio knows whether anyone still wants the network.

Bluetooth LE

Bluetooth is split across the two chips. NimBLE, the host, runs on the P4. The controller and the radio run on the C5. HCI messages cross the SDIO link through esp-hosted. The C5 supports LE only.

kdrv_ble_start() runs four steps in order:

1. Initialise and enable the controller over RPC.
2. Call nimble_port_init().
3. Configure NimBLE: callbacks, pairing policy, the GAP and GATT services, the device name, the console service table, the output rings and the bond store.
4. Call nimble_port_freertos_init() and wait up to 5 s for the host and controller to synchronise.

The configuration is rebuilt on every start, because a deinit frees what the previous one registered. The device name is the serial number of the board, or KODE-DOT if it does not know it.

The console service carries the same text the USB-C cable carries. Kode's own UUIDs name it, so a client can filter for Kode Dots alone. The characteristics behave like the Nordic UART service, a write pipe and a notify pipe. With pairing built in, both require an encrypted and authenticated link.

In kodeOS a new peer sees a six-digit code on the screen and types it on the phone. An app has no card for the code and refuses new pairings, serving only phones already bonded in kodeOS. internals/ble-console covers the user's side.

The output side is built around one fact: ble_gatts_notify_custom() waits with no limit, and AO_Log, the only writer of both consoles, must never wait on it. So kdrv_ble_console_write() copies a line into a ring of 2048 bytes under a mutex and posts one NimBLE event, whole or not at all, and the drain runs on the NimBLE task. The ring's bytes are in PSRAM, taken once when the service is set up and kept for the boot. Only tasks touch them, never an interrupt.

An entry that meets an empty buffer pool stays pending and the drain returns on a timed callout, never by posting to itself.

When screen mirroring is built in, the service gets a third characteristic of its own with a second ring of 8192 bytes, also in PSRAM, so pictures and console lines never take each other's room.

The keys of a bond live on the C5. NimBLE's store on the P4 keeps a 16-byte token in place of each key, and the C5 swaps the token for the key on the HCI path into its controller. The wrapped store callbacks send the key to the C5 (BTKEYS_PUT) before they store the token, and the pairing fails if the C5 refuses.

kdrv_ble_tokens.c makes and tests the tokens with no NimBLE in it. A bond written before tokens existed is moved to the C5 when the host synchronises.

Network

kdrv_net has three parts. The one-shots (lookup, ping, HTTP GET, UDP send) are reentrant: each opens its own socket or client, keeps nothing between calls and blocks for seconds, so they never run on an Active Object. The jobs run one at a time on AO_Net's worker and leave their results in tables the owner reads between the done event and the next job. The MQTT client exists once, with one connection and subscriptions that outlast any call, so AO_Net owns it.

No job touches internal flash, which is what lets both stacks live in PSRAM.

TLS buffers are in PSRAM as well (CONFIG_MBEDTLS_EXTERNAL_MEM_ALLOC), and kdrv_net.c stops the build with an #error if that option is off. The certificate bundle also accepts a cross-signed chain, because servers hosted by Google, api.kode.diy among them, send a root that the stock bundle does not hold.

A ping waits for the whole session with a limit of count × 2000 ms + 5000 ms. If the limit expires, the driver abandons the session's context and does not free it, because esp_ping_delete_session() does not wait for the ping task. About 50 bytes leak on a path that normally never runs, in exchange for no use-after-free.

An HTTP client reads to the end of the body even past your buffer, counting the bytes it drops, so body_len is the true length and truncated is not a guess. A zero-length read does not end the body. Only esp_http_client_is_complete_data_received() does.

The files

The files of the component:

The link, the status table, the KODE services and the handover note are in sdk/kdrv/c5.

Specifications

The Wi-Fi station

Bluetooth LE

The key tokens are 16 bytes: the 4-byte magic KBTL (a long-term key) or KBTI (an identity resolving key), the peer's identity address (6 bytes), its type (1), whose key it is (1, KBT_ROLE_OUR or KBT_ROLE_PEER), then zeros. The board's long-term key and the peer's get different tokens, because with legacy pairing they are different keys.

kbt_forget_on_enc_fail() is true for a disconnect reason of "PIN or key missing" or a MIC failure on a bonded peer, and the driver then asks the C5 whether it holds the key (BTKEYS_HAS). kbt_c5_lost_key() is true only for a clear "not found" answer. A spoofer can end a link with either reason, and cannot make the C5 lose a key it holds.

The network

Gotchas

Example code

An app can check that a Kode Dot is online by pinging a public address. Join a network once from the console first, with wifi_up and then wifi_join ssid="<network>" pass="<password>"; both are stored. This example retries every five seconds until the name resolves, then logs how many echoes came back and the average time.

/*
 * ping_check.c - 2026-10-28 - from Kode with love
 *
 * Pings 1.1.1.1 four times and logs the result. Join a Wi-Fi network from
 * the console first. The log shows a line like "4 of 4 replies, average
 * 23 ms" when the Kode Dot is online.
 */
#include "kode.h"
 
#define TAG "ping_check"
 
/* Bring the system up, then ping until the network answers. */
void app_main(void)
{
    kode_ping_stats_t stats;
 
    kode_init();
 
    /* A failed lookup means no address yet, so wait and ask again. */
    while (kode_net_ping("1.1.1.1", 4, &stats) != KODE_OK) {
        KLOG_I(TAG, "no network yet");
        kode_delay_ms(5000);
    }
 
    KLOG_I(TAG, "%u of %u replies, average %u ms", (unsigned)stats.rx,
           (unsigned)stats.tx, (unsigned)stats.avg_ms);
 
    while (1) {
        kode_delay_ms(1000);
    }
}

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

In the SDK

• components/kdrv/radio: the three drivers beside the link.
• kdrv_net.h: the one-shots, the jobs, the MQTT session.
• components/kaos/net: AO_Net, which owns the network (sdk/kaos/net).