SDK

kbsp

The Kode Dot as constants: pins, I2C addresses, screen, battery and owners, plus the sdkconfig.board and partitions.csv every firmware builds with.

What it is

kbsp is the board support package, and it describes the Kode Dot. It holds:

• every GPIO number and I2C address
• the size and shape of the screen
• the supply rails
• the numbers of the battery
• the name of the product
• the table of who owns which device

It also carries two files that every firmware reads when it is built: sdkconfig.board, the build options that state the chip and wiring facts, and partitions.csv, the map of the 32 MB flash.

kbsp sits at the bottom of the layers and depends on nothing. It describes and never acts: no code in it touches hardware. khal starts the buses with its numbers, the drivers address their chips with its constants, and each Active Object registers in its ownership table.

That gives it a placement test. A file that knows a pin belongs here. A file that knows a part number belongs in kdrv.

A pin number or an I2C address is defined only here. Layer check 3 of tools/check_layers.sh fails when a KBSP_PIN_*, KBSP_I2C_ADDR_* or KBSP_IOEXP_* is defined anywhere else (sdk/design-rules).

How it is connected

flowchart LR
subgraph readers["Who reads kbsp"]
  khal["khal<br/>I2C bus, GPIO, expansion header"]
  kdrv["kdrv<br/>chip drivers"]
  kaos["kaos<br/>kaos_claim()"]
end
subgraph kbsp["kbsp"]
  consts["Pins, addresses,<br/>owners"]
  build["sdkconfig.board<br/>partitions.csv"]
end
khal --> consts
kdrv --> consts
kaos -- "kbsp_claim()" --> consts
build --> fw["Every firmware build"]
class kaos ao
class build store
class fw app

The component has two sources in C and everything else is #defines. The expansion header tables KBSP_EXP[] and KBSP_EXP_CTRL[] live in kbsp_exp.c, because a table in a header would be copied into every file that includes it. The ownership table lives in kbsp_owners.c for the same reason.

Ownership takes no lock

Ownership is a record. Each owner claims its resources in its initial transition, through kaos_claim(). That wrapper calls kbsp_claim(), and when a second owner asks for the same resource it prints kodeOS: <resource> claimed by both <first> and <second> and stops the boot.

Each slot is an atomic pointer changed by compare-and-swap, so two Active Objects on two cores cannot both win. The table does not stand between an owner and its device. The Active Object keeps the device safe by handling one event at a time.

An owner owns a whole device. The TCA6408A expander serves four parts, but it has one input register and one interrupt line, so AO_IoExp owns the chip and everyone else asks it by event.

The build files follow the board

Every project reads <sdk>/components/kbsp/sdkconfig.board first, then its own sdkconfig.defaults, through SDKCONFIG_DEFAULTS. A later file wins, so a project can restate an option, with no warning.

A project spells out two board facts itself, because both are needed before the shared file can be fetched:

• set(IDF_TARGET esp32p4) before project().
• CONFIG_PARTITION_TABLE_CUSTOM_FILENAME. An app beside the SDK fetched as a component points it at managed_components/kodediy__kbsp/partitions.csv.

Specifications

The board

The facts about the chip, the glass and the rails.

The controllers kodeOS owns

The chip routes most controllers to any pin, so which controller drives a device is a board choice. The numbers are ESP-IDF's own: for SPI and the ADC that is one less than the chip's name, so SPI2 is SPI2_HOST, 1. Each driver turns its number into the IDF type beside a _Static_assert that the chip has it.

KBSP_EXP_CTRL_COUNT is 7 on the board: I2C1, SPI3 and five UARTs. The LP controllers reach only the LP pins and are not offered. The chip has one continuous ADC engine for both units and the RFID driver opens it for each read window, so J3's analog positions are read one sample at a time.

The I2C bus

One shared bus: SDA on KBSP_PIN_I2C_SDA GPIO4, SCL on KBSP_PIN_I2C_SCL GPIO5, at KBSP_I2C_FREQ_HZ 400000. The chips on it:

kbsp has no axis map for the IMU or the magnetometer. The drivers return each part's own axes.

The expander

The eight pins of the TCA6408A serve the buttons, the motion sensor, the touch controller and the supply of the panel.

• Its interrupt line is KBSP_PIN_IOEXP_INT GPIO6, active low, pulled up by R24 (10 kΩ).
• Its RESET is tied high through R117, so a reset of the P4 never resets the expander.
• KBSP_IOEXP_DIR_INPUTS is 0x7F: P0 to P6 are inputs, P7 is an output.

The eight pins:

All six buttons are SKRMAAE010 and active low. The sixth, KBSP_PIN_BUTTON_TOP GPIO35, is the only one on a P4 pin, and the driver also turns on the internal pull-up.

If P7 becomes an input the screen turns off, so AO_IoExp never writes P7 unless AO_Display asks.

TBD: the pull-up of BUTTON_BOT and BUTTON_TOP. The validation pin map lists external 10 kΩ resistors R38 to R42 on the five expander buttons, while a read of the schematics puts R38 on BUTTON_TOP and leaves BUTTON_BOT to the 200 kΩ internal pull-up of the charger's QON pin. A measurement on the board would settle it.

Other pins

The rest of the pins, by part.

The RFID input is on ADC2 because GPIO23 is also ADC1 channel 7, and a read on ADC1 there would reconfigure the enable line of the C5 and stop the radio.

The expansion header

J3 is a 2 by 10 header. It brings out GPIO8 to GPIO21 as KBSP_PIN_EXP_1 to KBSP_PIN_EXP_14, each through 68 Ω, with the 3.3 V and 5 V rails and ground.

KBSP_EXP[] has KBSP_EXP_COUNT 14 entries, indexed by position minus one. Each is a kbsp_exp_t: gpio, adc_chan (or KBSP_EXP_NO_ADC, 0xFF) and lp.

Every position is digital and matrix-routed. The ADC channel is the GPIO minus 16, and the LP pins are the GPIOs at or below 15. No position is both.

The 14 positions:

The table has no bit for the touch-sensing inputs of the chip, because kbsp has no trusted list of which GPIO each channel uses.

The battery

The cell is a 1S Li-ion pouch cell, type 603048 at 1000 mAh, on connector J7 with the shunt R75 in series. These numbers belong to the cell and the shunt, so none of them sits in a driver. AO_Power writes the charge profile into the BQ25896 at every boot.

The constants, in kbsp_cell.h:

All the charge values sit on the grid of the BQ25896's registers, so nothing is rounded on the way in (sdk/kdrv/bq25896).

The owners

kbsp_res_t lists 25 resources. The column on the right is who claims it in the SDK.

Some pairs are one resource on purpose. The infrared emitters and the receiver share a housing and the receiver hears the emitter. The IMU and the magnetometer share one owner because the test rows and the haptic row's witness go through one place. The audio amplifier's enable pin belongs to the C5 and is not in the audio resource.

KBSP_RES_JPEG and KBSP_RES_PPA are claimed only in a build with the screen mirror, KBSP_RES_C5 only with the radio, and the three AppMgr resources only with AO_AppMgr. The LEDC channels of the RFID carrier are not part of its resource: the driver takes them from khal_pwm while the field is up.

The calls

The four calls of the ownership table.

The build file sdkconfig.board

Each option is a fact about the chip or the wiring. A comment on every option names the component that declares it. A project can restate an option in its own sdkconfig.defaults.

The options come in five groups, one table each. The first group holds flash, cache and the partition table.

sdkconfig.board: memory

PSRAM and where the big buffers go.

sdkconfig.board: the radio link and Bluetooth

The wiring of the C5 and the BLE host.

sdkconfig.board: console, clock, tick and logging

The console, the CPU and RTC clocks, the scheduler tick and the log levels.

sdkconfig.board: LVGL

The graphics library's allocator, timing, draw threads and colour format.

sdkconfig.board: what it leaves out

CONFIG_ESP_HOSTED_ENABLED is absent on purpose. The component installs a constructor that claims the SDMMC controller before app_main, so a firmware that read this file would lose the microSD slot without asking for a radio. KODEOS_RADIO selects it. CONFIG_XTAL_FREQ_40 is absent because the chip forces it.

Two lines are commented out for a die older than v3.0: ESP32P4_SELECTS_REV_LESS_V3 and ESP32P4_REV_MIN_100. Turning them on also makes SPIRAM_SPEED_250M stop existing, and moves the CPU default to 360 MHz.

The partition table

The bootloader is at 0x2000 and the table at 0x8000. The table fits in one 4 KB sector, and nvs starts at 0xB000 so a table that grows never moves it. Executable code is not confined below 16 MB, because the cache maps 32-bit addresses, so the apps region runs from the last OS slot up to the FAT.

The ten partitions of partitions.csv:

The regions end where the next begins: apps ends at 0x1800000, storage at 0x1A00000 and app_pending at 0x2000000, the end of the 32 MB. The offset of apps is fixed, so installed images keep their addresses across a table change.

The files

The files of the component.

Gotchas

Example code

Read the board facts from kbsp, then ask the ownership table who holds the LED and the battery charger. After kode_init() returns, the log shows the screen size and the two owners, AO_LedMgr and AO_Power.

/*
 * board_facts.c - 2026-10-28 - from Kode with love
 *
 * Logs the screen size and the I2C address of the charger from kbsp, then asks
 * the ownership table who owns the status LED and the BQ25896. On a Kode Dot
 * the log reads "screen 410 x 502", "charger at 0x6B", "LED owner: AO_LedMgr"
 * and "charger owner: AO_Power".
 */
#include "kode.h"
#include "kbsp.h"
#include "kbsp_owners.h"
 
#define BOARD_TAG "board"
 
/* Bring the system up, then log what kbsp says about the board. */
void app_main(void)
{
    kode_init();
 
    KLOG_N(BOARD_TAG, "screen %u x %u", (unsigned)KBSP_LCD_H_RES, (unsigned)KBSP_LCD_V_RES);
    KLOG_N(BOARD_TAG, "charger at 0x%02X", (unsigned)KBSP_I2C_ADDR_CHARGER);
 
    /* A resource nobody claimed has no owner and answers NULL. */
    const char *led_owner = kbsp_owner_name(KBSP_RES_LED);
    const char *charger_owner = kbsp_owner_name(KBSP_RES_PMIC);
 
    if (led_owner != NULL) {
        KLOG_N(BOARD_TAG, "LED owner: %s", led_owner);
    }
    if (charger_owner != NULL) {
        KLOG_N(BOARD_TAG, "charger owner: %s", charger_owner);
    }
}

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

In the SDK

• components/kbsp: the whole layer, with sdkconfig.board and partitions.csv at its root.
• kbsp_pins.h: every pin and address.
• kbsp_owners.c: the ownership table.