SDK

CST820 touch

The capacitive touch controller of a Kode Dot: its registers, how it sleeps, how a finger becomes a panel pixel, and the driver and owner over it.

What it is

The glass of a Kode Dot senses fingers. Behind the front surface a grid of thin electrodes feels the small electric change a fingertip causes, and a CST820 reads that grid. The chip is Hynitron's, from the CST816 family. It reports one finger at a time as two 12-bit coordinates, plus the last gesture it recognised: a slide, a click, a long press.

The chip counts in its own units. Two layers turn its numbers into something an app can use. The driver kdrv_cst820 reads the chip and decodes it. The owner AO_Touch clamps the point to the glass and publishes a TouchEvt in panel pixels. The controller's pixels are the panel's, and nothing is calibrated.

The CST820 sits on the panel module from supplier A. The module from supplier B carries a different controller, a CST916E at 0x5A with another register map, which kodeOS does not drive. A unit with that module boots without touch. The display driver finds a panel by asking for the CST820 at 0x15, so a module without one is also a unit without a screen: the display driver reports no panel and the board runs with its console only.

How it is connected

flowchart LR
chip["CST820"] -- "I2C 0x15" --> bus["shared I2C bus"]
chip -- "INT, DSI_TP_INT" --> p6["TCA6408A<br/>P6"]
p6 --> ioexp["AO_IoExp"]
ioexp -- "IOEXP_INPUT_SIG" --> touch["AO_Touch"]
touch -- "kdrv_cst820_read()" --> chip
gpio7["GPIO7"] -- "reset, shared<br/>with the panel" --> chip
touch -- "TOUCH_EVT_SIG" --> gui["AO_Gui or<br/>your AO"]
class chip chip
class p6 chip
class ioexp ao
class touch ao
class gui app

The chip answers at 0x15 (KBSP_I2C_ADDR_TOUCH) on the shared I2C bus, which runs at 400 kHz. The chip moves to the next register by itself after each byte, so the driver reads the six-byte frame as one transaction and the three identity bytes as another.

Shared wires

Two wires are shared with other parts:

• The reset is GPIO7, the same net as the panel's reset (DSP_&_TP_RST). The display driver pulses it while it starts the panel, so the touch controller always starts after the panel. AO_Touch subscribes to DISPLAY_STATE_SIG and calls kdrv_cst820_init() only when that event says the panel is up. No code above the driver resets the chip alone. The only software control is the soft_rst field, and nothing uses it.
• The interrupt is pin P6 of the expander. No pin of the ESP32-P4 carries it. P6 is an input and the pull-up is on the module. AO_IoExp reads the expander on the expander's own interrupt and publishes all eight pin levels as IOEXP_INPUT_SIG. See sdk/kdrv/tca6408a.

The owner

AO_Touch owns the chip (KBSP_RES_TOUCH) at priority 14. Touch_idle waits for the panel and refuses field requests. Touch_armed and Touch_tracking share a parent, Touch_up, which serves field requests and the guided test. Touch_armed reads nothing at all, so an idle board costs no I2C. When P6 falls it moves to Touch_tracking, which polls every 10 ms (KODE_TOUCH_POLL_MS) until the finger lifts.

It polls instead of following edges because some CST816-family firmwares pulse INT once per report and others once per touch-and-lift, and polling only while a finger is down is correct for both. An edge with no finger behind it gets three polls (TOUCH_EMPTY_POLLS) and then the state falls back to armed, so a glitch cannot start a poll that never ends.

AO_Touch publishes only on change: a press, a release, or movement of more than 2 px (TOUCH_MOVE_EPSILON) from the last published point, not from the last sample. That keeps a slow drag from walking its reference under the threshold and ending far from where the GUI last heard. A failed read counts as a release with the last position, so the GUI is never left pressed.

No calibration

The controller's pixels are the panel's. The point AO_Touch publishes is the one the chip reported, pinned to the 410 by 502 glass. No scale or offset is stored. The guided test, test component=tp, asks for two taps, one on each side of the glass, and judges each within 64 px (KODE_TOUCH_TEST_TOL_PX). It gives each tap 20 s (KODE_TOUCH_TEST_STEP_MS) and three tries. It proves that the panel answers where a finger lands and fits nothing.

Sleep

The chip sleeps, and the driver is written around it. After auto_sleep_time seconds without a finger the chip enters a low-power scan and stops answering the bus: every read and write gets a NAK. A finger or a reset of the panel wakes it, and a reset puts every register back to the supplier's defaults. The software draws three consequences:

• The driver reads the identity once, right after the panel's reset when the chip is known to be awake, and serves chip_id, proj_id and fw_ver from that copy. A check that read the chip at check time could fail on a unit that happens to be asleep.
• A failed read is an error. It is never a value and never a release. The driver logs the bus state on its edges only, one line when the chip stops answering and one when it answers again, because the owner polls every 10 ms while a finger is down.
• dis_auto_sleep is a bench setting and the board's rest. Only AO_Touch's rest writes it (with auto_sleep_time and irq_ctl), and it writes the values it read at bring-up back on wake (sdk/kaos/touch).

Specifications

The board

The frame and identity registers

The driver gives every register in the two register tables as a field, whole and bit by bit. [7:6] is bits 7 to 6. This table lists the registers that carry a touch and the chip's identity.

The configuration registers

The registers 0xEC to 0xFE: gestures, the interrupt, low-power scanning and sleep.

The driver

The driver takes no decisions. Whether to let the chip sleep belongs to AO_Touch.

The files

Gotchas

Example code

Log every touch sample as panel pixels. With the app running, touch the glass: each press, move and release prints a line such as x=205 y=251 pressed=1, and the release repeats the last position with pressed=0.

/*
 * touch_log.c - 2026-10-28 - from Kode with love
 *
 * An Active Object of its own subscribes to the touch samples that AO_Touch
 * publishes and logs each one on the serial console, in panel pixels. Touch
 * the glass of the Kode Dot and lines such as "x=205 y=251 pressed=1" appear.
 */
#include "kode_ao.h"
static QEvtPtr     l_queue[KQP_AO_QUEUE_LEN];
static StackType_t l_stack[KQP_AO_STACK_BYTES / sizeof(StackType_t)];
static QActive     l_ao;
 
/* The one state: log every touch sample. */
static QState touch_running(QActive * const me, QEvt const * const e)
{
    (void)me;
    if (e->sig == TOUCH_EVT_SIG) {
        TouchEvt const * const t = (TouchEvt const *)e;
        KLOG_I("touch", "x=%d y=%d pressed=%d", t->x, t->y, (int)t->pressed);
        return Q_HANDLED();
    }
    return Q_SUPER(&QHsm_top);
}
 
/* The initial transition: subscribe, then run. */
static QState touch_initial(QActive * const me, void const * const par)
{
    (void)par;
    QActive_subscribe(me, TOUCH_EVT_SIG);
    return Q_TRAN(&touch_running);
}
 
/* Bring the system up, then start the Active Object. */
void app_main(void)
{
    kode_init();
    QActive_ctor(&l_ao, Q_STATE_CAST(&touch_initial));
    QACTIVE_START(&l_ao, KODE_PRIO_USER_LOW, l_queue, Q_DIM(l_queue),
                  l_stack, sizeof(l_stack), (void *)0);
}

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/cst820: the driver and its field table.
• kdrv_cst820.h: every field and call.
• components/kaos/touch: AO_Touch, the owner.