SDK

Buttons

The Kode Dot's D-pad and two side buttons: which pin each one is on, how a press is debounced, and the press, hold and double-press events your code receives.

What it is

The Kode Dot has six buttons: a D-pad of four (up, down, left, right) and two side buttons, top and bottom. The driver names each one by what it is for, not by where it is wired, and turns the state of all six into one number, the button mask, with one bit per button.

Your code never sees the wiring or the bounce. A press arrives as one BUTTON_EVT_SIG event that says which button changed and whether it is down, already filtered. Two gestures are timed for you as well: a hold of the top or bottom button, and a double press of the top button. If you prefer to poll, kode_buttons_read() returns the mask.

How it is connected

flowchart LR
subgraph board["On the Kode Dot"]
  pad["pad and<br/>bottom button"] --> tca["TCA6408A<br/>P0 to P4"]
  tca -- "INT, GPIO6" --> ioexp["AO_IoExp"]
  ioexp -- "IOEXP_INPUT_SIG" --> btn["AO_Buttons"]
  top["top button<br/>GPIO35"] -- "edge" --> btn
end
btn -- "BUTTON_EVT_SIG" --> app["your AO"]
class pad chip
class tca chip
class top chip
class ioexp ao
class btn ao
class app app

The wiring

Five buttons hang off the TCA6408A expander (sdk/kdrv/tca6408a) and one is on a pin of the P4. All six switches are SKRMAAE010 and all are active low: a pressed button pulls its net to ground and reads 0.

The bottom button shares its net with the QON pin of the BQ25896 (sdk/kdrv/bq25896), so it is the button that wakes the board from ship mode, and the one that wakes it from OFF. A tap does not wake it from OFF: the boot gate wants BOT held for about a second (sdk/kaos/lowpower). Two hardware behaviours act with no software. The bottom button and D-pad left held together for about a second reset the P4. The bottom button held 16 to 23 s with no USB power-cycles the board. A script that tests buttons must never hold those two together.

Owners and debounce

Two owners. The expander belongs to AO_IoExp, which reads it on its interrupt and publishes all eight pins. AO_Buttons owns the driver, claims KBSP_RES_BTN_TOP (GPIO35), runs at priority 13 and reads nothing while nobody presses. An expander publish and an edge on GPIO35 each count as one sample of the six buttons.

The driver itself holds only GPIO35: it sets the input with the pull-up, arms an any-edge interrupt, and decodes a sample. The interrupt disables itself before its callback runs, so a bouncing contact posts once per arming.

The debounce is AO_Buttons'. A change arms a one-shot of 30 ms (KODE_BUTTONS_SETTLE_MS). When it fires, AO_Buttons re-arms GPIO35 and asks AO_IoExp for a fresh reading. That reading is the only sample that can confirm a change, for all six buttons, and only when it agrees with the sample before it. Earlier samples, which arrive microseconds apart, never confirm. There are two reasons:

• GPIO35 is a strapping pin that has carried a false level across a reset.
• The bottom button, held up only by QON's 200 kΩ, rings as it is let go. Measured on a Kode Dot, with two close samples enough, one release published a release, a press nobody made and a second release within 1 ms.

A failed expander read is not a sample, since decoding a dead bus as "every button released" would publish releases nobody made.

The events

AO_Buttons publishes on change only, so a resting finger costs nothing downstream. Every confirmed edge logs one line at INFO: the button, pressed or released, and which sample confirmed it.

A press that reached hold does not start a double, and the second press of a double does not start another, so three quick taps make one double. The detector is fed only by real presses; console-injected ones are left out on purpose.

The pad follows the glass

An app that rotates its screen with kscreen_set_rotation() gets the D-pad rotated with it when CONFIG_KSCREEN_ROTATE_PAD is on, which is the default. kscreen calls buttons_rotation_request(quarter_turns), and each pad button then publishes the direction it points on the turned glass. The top and bottom buttons never turn. A turn that arrives while a pad button is down waits for its release, so a press and its release always name the same button.

The guided test

test component=buttons asks for six presses: left, bottom, down, top, right, up. A short between two D-pad tracks or a pin mapped to the wrong button shows as a wrong name.

• The first confirmed sample with a button down is the answer: exactly the asked button passes. A wrong button, or the asked button with another, is forgiven and asked again; the third wrong press on a step ends the test as a failure, and the second double fails the step. Each names what was pressed.
• Each prompt waits until every button is released, so the operator is never asked for the second half of the reset combination.
• A step times out after 20 s, a button still held 3 s after being judged is reported stuck, and the run goes on.
• The verdict is TEST_RESULT_SIG named buttons.

Specifications

The driver

The driver does no debouncing. A caller that used it directly would see every bounce.

The owner

The timings

Gotchas

Example code

Poll the buttons and show them on the LED: green while the top button is down, red for the bottom button, blue for any D-pad button. You see the colour follow your thumb.

/*
 * buttons_led.c - 2026-10-28 - from Kode with love
 *
 * Reads the Kode Dot's six buttons every 20 ms and shows them on the RGB
 * LED: green while the top button is down, red for the bottom button and
 * blue for any D-pad button. You see the colour follow your thumb. The
 * bottom button held for 600 ms returns to kodeOS, so tap it.
 */
#include "kode.h"
 
#define LEVEL    32U
#define PAD_MASK ((1UL << (uint32_t)KDRV_BTN_TOP) - 1UL)
 
/* Bring the system up, then map the button mask to a colour forever. */
void app_main(void)
{
    kode_init();
 
    while (1) {
        uint32_t const down = kode_buttons_read();
        uint8_t red = 0U;
        uint8_t green = 0U;
        uint8_t blue = 0U;
 
        if ((down & (1UL << (uint32_t)KDRV_BTN_TOP)) != 0UL) {
            green = LEVEL;
        }
        if ((down & (1UL << (uint32_t)KDRV_BTN_BOT)) != 0UL) {
            red = LEVEL;
        }
        if ((down & PAD_MASK) != 0UL) {
            blue = LEVEL;
        }
        (void)kode_led_rgb(red, green, blue);
        kode_delay_ms(20);
    }
}

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/buttons: the driver, kdrv_buttons.c.
• kdrv_buttons.h: the button enum and the decode call.
• components/kaos/buttons: AO_Buttons, the owner, with the debounce, hold, double press and guided test.