Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

One image for two dials: detect the board at boot

0xdiego25b6f151fa84f0
diff --git a/cli/src/cable/cableSession.spec.ts b/cli/src/cable/cableSession.spec.ts
index b5fae8673..deab531c9 100644
--- a/cli/src/cable/cableSession.spec.ts
+++ b/cli/src/cable/cableSession.spec.ts
@@ -918,6 +918,21 @@ describe('cable session', () => {
await session.stop()
})
+ it('names the board a dial greets with, and lives without it', async () => {
+ // Two dials ship on one image; the firmware says which it is in `hw`. A firmware from before the
+ // field greets without it, and that is not an error — only a shorter line.
+ const lines: string[] = []
+ const seen: unknown[] = []
+ const { session, port } = await connect(makeHost({ log: (l) => lines.push(l), onDialStatus: (s) => seen.push(s) }))
+ port.say({ t: 'hello', product: 'harness', mac: 'aa:bb', fw: '0.0.68', proto: 3, hw: 'cst816s' })
+ await vi.waitFor(() => expect(lines.some((l) => l.includes('on fw 0.0.68 proto 3 hw cst816s'))).toBe(true))
+ expect(seen).toEqual([{ attached: true, fw: '0.0.68', hw: 'cst816s' }])
+ port.say({ t: 'hello', product: 'harness', mac: 'cc:dd', fw: '0.0.67', proto: 3 })
+ await vi.waitFor(() => expect(lines.some((l) => l.includes('dial cc:dd on fw 0.0.67 proto 3'))).toBe(true))
+ expect(seen.at(-1)).toEqual({ attached: true, fw: '0.0.67' })
+ await session.stop()
+ })
+
it('files framed device logs instead of losing them', async () => {
// The dial has ONE USB port, shared by its console and this protocol. While the daemon holds it,
// these frames are the only copy of that console which exists anywhere — `idf.py monitor` cannot open
diff --git a/cli/src/cable/cableSession.ts b/cli/src/cable/cableSession.ts
index 7b547d8fa..d220c9cfc 100644
--- a/cli/src/cable/cableSession.ts
+++ b/cli/src/cable/cableSession.ts
@@ -298,6 +298,9 @@ export interface CableHost {
export interface DialStatus {
attached: boolean
fw?: string
+ /** Which of the two dials this is — `cst9217+axp2101`, `cst816s`, … — as the firmware detected itself
+ * at boot (device: board.h). Absent from a firmware that predates the field. Informational. */
+ hw?: string
updating?: string
}
@@ -706,13 +709,14 @@ export class CableSession {
// "it came back, and on which version". Losing it left a successful 0.0.37 install unverifiable
// from the log on 2026-08-24.
const fw = str('fw') ?? '?'
+ const hw = str('hw')
if (mac !== this.greetedMac || fw !== this.greetedFw) {
const returning = mac === this.greetedMac
this.greetedMac = mac
this.greetedFw = fw
- this.log(`cable: dial ${mac} ${returning ? 'back ' : ''}on fw ${fw} proto ${msg.proto}`)
+ this.log(`cable: dial ${mac} ${returning ? 'back ' : ''}on fw ${fw} proto ${msg.proto}${hw ? ` hw ${hw}` : ''}`)
this.dialLog.greeted()
- this.host.onDialStatus?.({ attached: true, fw })
+ this.host.onDialStatus?.({ attached: true, fw, ...(hw ? { hw } : {}) })
// BEFORE the state push, not after: the push reads the selected machine, and for a remote one
// that means an RPC over a lane this is what re-opens.
this.host.onDialAttached?.()
diff --git a/desktop/lib/state/dial_status.dart b/desktop/lib/state/dial_status.dart
index d9ddca689..4c431772b 100644
--- a/desktop/lib/state/dial_status.dart
+++ b/desktop/lib/state/dial_status.dart
@@ -9,7 +9,7 @@ import '../core/local_key_value_store.dart';
/// once more the moment this window connects, so a window opened after the dial was plugged in is not
/// left believing there is none.
class DialStatus {
- const DialStatus({required this.attached, this.fw, this.updating});
+ const DialStatus({required this.attached, this.fw, this.hw, this.updating});
static const none = DialStatus(attached: false);
@@ -19,6 +19,11 @@ class DialStatus {
/// has said which image it runs.
final String? fw;
+ /// Which of the two dials it is — `cst9217+axp2101` or `cst816s` — as the firmware detected itself
+ /// at boot. Null from a firmware that predates the field. Shown only in the row's detail: a person
+ /// does not choose it, support reads it.
+ final String? hw;
+
/// The version on its way over the cable, or null. The one state that deserves its own word in the
/// window, because it is the minute in which people unplug the thing.
final String? updating;
@@ -29,6 +34,9 @@ class DialStatus {
fw: json['fw'] is String && (json['fw'] as String).isNotEmpty
? json['fw'] as String
: null,
+ hw: json['hw'] is String && (json['hw'] as String).isNotEmpty
+ ? json['hw'] as String
+ : null,
updating:
json['updating'] is String && (json['updating'] as String).isNotEmpty
? json['updating'] as String
diff --git a/desktop/lib/widgets/device_row.dart b/desktop/lib/widgets/device_row.dart
index 4a277fd7b..05b7bcc83 100644
--- a/desktop/lib/widgets/device_row.dart
+++ b/desktop/lib/widgets/device_row.dart
@@ -285,6 +285,9 @@ class _DeviceStatusCard extends StatelessWidget {
),
),
],
+ if (status.hw != null) ...[
+ TextSpan(text: ' · ${status.hw}'),
+ ],
if (updating != null) ...[
const TextSpan(text: ' · '),
TextSpan(
diff --git a/device/esp32-circle/.gitignore b/device/esp32-circle/.gitignore
index 7859775e4..1b1fe6085 100644
--- a/device/esp32-circle/.gitignore
+++ b/device/esp32-circle/.gitignore
@@ -23,3 +23,4 @@ build-prod/
# Design mockups: HTML frames used to agree on a layout BEFORE writing LVGL code. They are a
# conversation, not a build input — nothing here compiles or ships.
mockup/
+build-probe/
diff --git a/device/esp32-circle/main/CMakeLists.txt b/device/esp32-circle/main/CMakeLists.txt
index 975fed5d1..08a7be5de 100644
--- a/device/esp32-circle/main/CMakeLists.txt
+++ b/device/esp32-circle/main/CMakeLists.txt
@@ -16,6 +16,8 @@ idf_component_register(
"audio_client.c"
"ptt.c"
"board/board_i2c.c"
+ "board/board.c"
+ "board/board_table.c"
"board/power.c"
"ui/display.c"
"ui/touch.c"
@@ -84,3 +86,11 @@ endif()
if(DEVICE_BACKEND_URL)
target_compile_definitions(${COMPONENT_LIB} PRIVATE DEVICE_PROD_BACKEND_URL="${DEVICE_BACKEND_URL}")
endif()
+
+# BRING-UP PROBE: `idf.py -DBOARD_PROBE=1 build` (separate build dir recommended). app_main runs
+# board/board_probe.c before the display comes up and prints what is on the I2C bus, which reset pins
+# do what, and what each touch driver reads idle. Never set for a release image.
+if(BOARD_PROBE)
+ target_compile_definitions(${COMPONENT_LIB} PRIVATE BOARD_PROBE=1)
+ target_sources(${COMPONENT_LIB} PRIVATE "board/board_probe.c")
+endif()
diff --git a/device/esp32-circle/main/app_main.c b/device/esp32-circle/main/app_main.c
index 4e1f4eb70..226abd77a 100644
--- a/device/esp32-circle/main/app_main.c
+++ b/device/esp32-circle/main/app_main.c
@@ -23,6 +23,8 @@
#include "config_store.h"
#include "fw_update.h"
#include "last_words.h"
+#include "board/board.h"
+#include "board/board_probe.h"
#include "driver/gpio.h"
#include "esp_heap_caps.h"
#include "esp_log.h"
@@ -175,6 +177,7 @@ void app_main(void)
{
ram_telemetry_checkpoint("boot");
last_words_boot(); // before the first log line, so the previous boot's ring is read, not overwritten
+ board_detect(); // which dial this is — the panel's reset pin comes from here, so before display_init
config_store_init();
if (boot_button_held()) {
@@ -182,6 +185,9 @@ void app_main(void)
config_clear_all();
}
+#ifdef BOARD_PROBE
+ board_probe_run(); // bring-up only — see board/board_probe.c
+#endif
display_init();
ui_init();
ui_set_brightness(config_load_brightness());
diff --git a/device/esp32-circle/main/board/board.c b/device/esp32-circle/main/board/board.c
new file mode 100644
index 000000000..a8cb2515a
--- /dev/null
+++ b/device/esp32-circle/main/board/board.c
@@ -0,0 +1,78 @@
+#include "board.h"
+
+#include <stdio.h>
+
+#include "board_i2c.h"
+#include "driver/gpio.h"
+#include "driver/i2c_master.h"
+#include "esp_log.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+static const char *TAG = "board";
+
+// Until board_detect() runs: the dial this code grew up on.
+static board_t s_board = {
+ .name = "cst9217+axp2101", .lcd_rst = 39, .touch_rst = 40,
+ .touch = TOUCH_CST9217, .touch_mirror = true, .has_pmic = true,
+};
+static bool s_detected;
+static char s_describe[64];
+
+const board_t *board(void) { return &s_board; }
+
+static int scan(uint8_t *acks, int cap)
+{
+ i2c_master_bus_handle_t bus = board_i2c_get();
+ if (!bus) return -1;
+ int n = 0;
+ // Only the addresses the decision reads, not the whole range: 3 probes at 20ms is a boot-time
+ // cost nobody sees; 112 of them is not.
+ static const uint8_t WANT[] = { 0x34, 0x5A, 0x15 };
+ for (unsigned i = 0; i < sizeof WANT && n < cap; i++)
+ if (i2c_master_probe(bus, WANT[i], 20) == ESP_OK) acks[n++] = WANT[i];
+ return n;
+}
+
+// The two touch controllers' reset lines, as a pair. Measured harmless on the board that does not use
+// a pair (its two pins are no-connects); the driver pulses the right one again at init anyway.
+static void pulse(int pin)
+{
+ gpio_config_t io = { .pin_bit_mask = 1ULL << pin, .mode = GPIO_MODE_OUTPUT };
+ gpio_config(&io);
+ gpio_set_level(pin, 0); vTaskDelay(pdMS_TO_TICKS(10));
+ gpio_set_level(pin, 1); vTaskDelay(pdMS_TO_TICKS(50));
+}
+
+void board_detect(void)
+{
+ if (s_detected) return;
+ s_detected = true;
+ uint8_t acks[4];
+ int n = scan(acks, 4);
+ if (n < 0) { ESP_LOGE(TAG, "no i2c bus — assuming %s", s_board.name); return; }
+ // Nothing that names a touch chip answered. Both are out of reset at power-on in practice (the
+ // CST816S measured so; the CST9217 has always come up on the driver's own pulse), but a chip held
+ // in reset by a floating line would look exactly like "no touch" — so pulse both pairs once and ask
+ // again before settling for that.
+ bool touch_seen = false;
+ for (int i = 0; i < n; i++) touch_seen |= (acks[i] == 0x5A || acks[i] == 0x15);
+ if (!touch_seen) {
+ pulse(39); pulse(40); pulse(1); pulse(2);
+ n = scan(acks, 4);
+ if (n < 0) n = 0;
+ }
+ board_from_acks(acks, n, &s_board);
+ char list[24]; int p = 0;
+ for (int i = 0; i < n; i++) p += snprintf(list + p, sizeof list - p, "%s%02X", i ? "," : "", acks[i]);
+ ESP_LOGI(TAG, "%s (ack %s)", board_describe(), n ? list : "none");
+}
+
+const char *board_describe(void)
+{
+ const board_t *b = &s_board;
+ snprintf(s_describe, sizeof s_describe, "board %s: touch=%s pmic=%s rst=%d/%d", b->name,
+ b->touch == TOUCH_CST9217 ? "cst9217" : b->touch == TOUCH_CST816S ? "cst816s" : "none",
+ b->has_pmic ? "yes" : "no", b->lcd_rst, b->touch_rst);
+ return s_describe;
+}
diff --git a/device/esp32-circle/main/board/board.h b/device/esp32-circle/main/board/board.h
new file mode 100644
index 000000000..f2b0007d5
--- /dev/null
+++ b/device/esp32-circle/main/board/board.h
@@ -0,0 +1,42 @@
+// The board this image is running on — decided at boot, not at build.
+//
+// Two dials ship at once. Same panel, audio, pins and firmware; they differ only in the touch
+// controller, the reset pins and whether there is a PMIC (docs/plans/2026-09-15-004-two-boards-plan.md):
+//
+// touch lcd/touch reset PMIC (AXP2101 @0x34) sleep key
+// "cst9217+axp2101" CST9217 @0x5A GPIO39 / GPIO40 yes: battery, PWR key PWR tap, BOOT hold
+// "cst816s" CST816S @0x15 GPIO1 / GPIO2 no BOOT hold
+//
+// Every one of those is a fact the I2C bus answers, so one image asks and configures itself — no SKU
+// burned at the factory, no second OTA manifest, no image that can be flashed onto the wrong dial.
+// Read per FEATURE, not per SKU: a batch that mixes them (CST816S with a PMIC, say) is right too.
+#pragma once
+
+#include <stdbool.h>
+#include <stdint.h>
+
+typedef enum { TOUCH_NONE = 0, TOUCH_CST9217, TOUCH_CST816S } touch_chip_t;
+
+typedef struct {
+ const char *name; // goes up the cable in `hello.hw`, and into the boot log
+ int lcd_rst; // CO5300 reset GPIO
+ int touch_rst; // touch controller reset GPIO
+ touch_chip_t touch;
+ bool touch_mirror; // CST9217 is mounted 180° to the panel; CST816S reports panel-aligned
+ bool has_pmic; // AXP2101 answered: battery figures + the PWR key exist
+} board_t;
+
+// Probe the bus and fill in the board. Call FIRST in app_main, before display_init() — the panel
+// reset pin comes from here. Safe to call once; later calls return the same answer.
+void board_detect(void);
+
+// What board_detect found. Before it runs, the table for "cst9217+axp2101" (what the code assumed
+// for its whole life until this file), so nothing dereferences a NULL.
+const board_t *board(void);
+
+// The decision itself, from the list of 7-bit addresses that ACKed. Pure — host-tested in
+// test/test_board.c — so the table can be proved without a bus.
+void board_from_acks(const uint8_t *acks, int n, board_t *out);
+
+// One line, for the boot log and the daemon: "touch=cst816s pmic=no rst=1/2".
+const char *board_describe(void);
diff --git a/device/esp32-circle/main/board/board_pins.h b/device/esp32-circle/main/board/board_pins.h
index 3c0149ae4..499a58026 100644
--- a/device/esp32-circle/main/board/board_pins.h
+++ b/device/esp32-circle/main/board/board_pins.h
@@ -17,7 +17,7 @@
#define BSP_LCD_QSPI_D1 5
#define BSP_LCD_QSPI_D2 6
#define BSP_LCD_QSPI_D3 7
-#define BSP_LCD_RST 39
+// LCD reset: per board — board()->lcd_rst (board.h). GPIO39 on the CST9217 dial, GPIO1 on the CST816S one.
// ---- I2C bus (touch + PMIC share it) ----
#define BSP_I2C_SDA 15
@@ -25,12 +25,11 @@
#define BSP_I2C_FREQ_HZ 400000
// ---- Capacitive touch: CST9217 (I2C) — wired for future use, not required in v1 ----
-#define BSP_TOUCH_I2C_ADDR 0x5A
+// Touch controller address and reset: per board — board()->touch / ->touch_rst (board.h).
#define BSP_TOUCH_INT 11
-#define BSP_TOUCH_RST 40
// ---- Power management: AXP2101 (I2C) ----
-#define BSP_AXP2101_I2C_ADDR 0x34
+#define BSP_AXP2101_I2C_ADDR 0x34 // present only when board()->has_pmic
// ---- Audio: dual-mic → ES7210 ADC (capture) + ES8311 codec, on the shared I2C; I2S bus ----
// Pins from the Waveshare BSP (bsp/esp32_s3_touch_amoled_1_75). Mic capture (ES7210) only in v1.
diff --git a/device/esp32-circle/main/board/board_probe.c b/device/esp32-circle/main/board/board_probe.c
new file mode 100644
index 000000000..d114311e5
--- /dev/null
+++ b/device/esp32-circle/main/board/board_probe.c
@@ -0,0 +1,89 @@
+// Bring-up probe for a board the firmware has not met yet. Built only with `idf.py -DBOARD_PROBE=1`,
+// never in a release image: it walks the shared I2C bus, pulses every candidate reset pin, walks the
+// bus again, and reads the touch controllers raw — the facts board_detect() is built on, measured
+// rather than assumed. Output goes to the console; read it with a serial monitor, not the daemon.
+#include "board_probe.h"
+
+#include "board_i2c.h"
+#include "board_pins.h"
+#include "driver/gpio.h"
+#include "esp_lcd_panel_io.h"
+#include "esp_lcd_touch_cst816s.h"
+#include "esp_lcd_touch_cst9217.h"
+#include "esp_log.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+static const char *TAG = "probe";
+
+static void scan(const char *when)
+{
+ i2c_master_bus_handle_t bus = board_i2c_get();
+ if (!bus) { ESP_LOGE(TAG, "%s: no bus", when); return; }
+ char line[128]; int n = 0;
+ for (int a = 0x08; a <= 0x77; a++) {
+ if (i2c_master_probe(bus, (uint16_t)a, 20) == ESP_OK) n += snprintf(line + n, sizeof line - n, " %02X", a);
+ }
+ ESP_LOGI(TAG, "%s: ack%s", when, n ? line : " (none)");
+}
+
+static void pulse(int pin)
+{
+ gpio_config_t io = { .pin_bit_mask = 1ULL << pin, .mode = GPIO_MODE_OUTPUT };
+ gpio_config(&io);
+ gpio_set_level(pin, 0); vTaskDelay(pdMS_TO_TICKS(10));
+ gpio_set_level(pin, 1); vTaskDelay(pdMS_TO_TICKS(50));
+ ESP_LOGI(TAG, "pulsed reset on GPIO%d", pin);
+}
+
+// Open one touch driver on one reset pin and sample it a few times, idle. Says whether the chip answers,
+// what its id is, and — the part touch.c cares about — what read_data returns with no finger down.
+static void try_touch(const char *name, int rst, bool cst816s)
+{
+ i2c_master_bus_handle_t bus = board_i2c_get();
+ esp_lcd_panel_io_handle_t io = NULL;
+ esp_lcd_panel_io_i2c_config_t io_cfg = cst816s ? (esp_lcd_panel_io_i2c_config_t)ESP_LCD_TOUCH_IO_I2C_CST816S_CONFIG()
+ : (esp_lcd_panel_io_i2c_config_t)ESP_LCD_TOUCH_IO_I2C_CST9217_CONFIG();
+ io_cfg.scl_speed_hz = BSP_I2C_FREQ_HZ;
+ if (esp_lcd_new_panel_io_i2c(bus, &io_cfg, &io) != ESP_OK) { ESP_LOGW(TAG, "%s: panel io failed", name); return; }
+ esp_lcd_touch_config_t cfg = {
+ .x_max = 466, .y_max = 466, .rst_gpio_num = rst, .int_gpio_num = BSP_TOUCH_INT,
+ .flags = { .swap_xy = 0, .mirror_x = 0, .mirror_y = 0 },
+ };
+ esp_lcd_touch_handle_t tp = NULL;
+ esp_err_t err = cst816s ? esp_lcd_touch_new_i2c_cst816s(io, &cfg, &tp) : esp_lcd_touch_new_i2c_cst9217(io, &cfg, &tp);
+ if (err != ESP_OK || !tp) { ESP_LOGW(TAG, "%s (rst GPIO%d): init %s", name, rst, esp_err_to_name(err)); esp_lcd_panel_io_del(io); return; }
+ ESP_LOGI(TAG, "%s (rst GPIO%d): init OK", name, rst);
+ int ok = 0, inv = 0, fail = 0;
+ for (int i = 0; i < 30; i++) {
+ esp_err_t rc = esp_lcd_touch_read_data(tp);
+ if (rc == ESP_OK) ok++; else if (rc == ESP_ERR_INVALID_RESPONSE) inv++; else fail++;
+ uint16_t x, y, s; uint8_t cnt = 0;
+ bool pressed = esp_lcd_touch_get_coordinates(tp, &x, &y, &s, &cnt, 1) && cnt > 0;
+ if (i < 3 || pressed) ESP_LOGI(TAG, " read %d: rc=%s pressed=%d (%u,%u)", i, esp_err_to_name(rc), pressed, x, y);
+ vTaskDelay(pdMS_TO_TICKS(33));
+ }
+ ESP_LOGI(TAG, "%s idle reads: ok=%d invalid_response=%d fail=%d", name, ok, inv, fail);
+ esp_lcd_touch_del(tp);
+ esp_lcd_panel_io_del(io);
+}
+
+void board_probe_run(void)
+{
+ ESP_LOGW(TAG, "=== BOARD PROBE (not a release image) ===");
+ scan("before any reset");
+ pulse(39); pulse(40); // board A's LCD / touch reset
+ scan("after 39/40");
+ pulse(1); pulse(2); // board B's LCD / touch reset
+ scan("after 1/2");
+ try_touch("CST9217", 40, false);
+ try_touch("CST9217", 2, false);
+ try_touch("CST816S", 2, true);
+ try_touch("CST816S", 40, true);
+ scan("after touch probes");
+ ESP_LOGW(TAG, "=== PROBE DONE — touch these 10s: ===");
+ // One more pass with a finger, on whichever driver answered, to see a press.
+ try_touch("CST816S", 2, true);
+ try_touch("CST9217", 40, false);
+ ESP_LOGW(TAG, "=== END ===");
+}
diff --git a/device/esp32-circle/main/board/board_probe.h b/device/esp32-circle/main/board/board_probe.h
new file mode 100644
index 000000000..d448c26f6
--- /dev/null
+++ b/device/esp32-circle/main/board/board_probe.h
@@ -0,0 +1,3 @@
+// See board_probe.c. Only compiled with -DBOARD_PROBE=1; app_main calls it before display_init().
+#pragma once
+void board_probe_run(void);
diff --git a/device/esp32-circle/main/board/board_table.c b/device/esp32-circle/main/board/board_table.c
new file mode 100644
index 000000000..7ff510e21
--- /dev/null
+++ b/device/esp32-circle/main/board/board_table.c
@@ -0,0 +1,42 @@
+// The decision table behind board_detect(): from "who answered on the bus" to pins and drivers.
+// No ESP-IDF here on purpose — test/test_board.c compiles this file with a plain cc.
+#include "board.h"
+
+#include <stdbool.h>
+#include <stdio.h>
+
+// Measured, not assumed (2026-09-15, both units on the desk):
+// board A ack 34 5A 18 40 (AXP2101, CST9217, ES8311, ES7210)
+// board B ack 15 18 40 (CST816S, ES8311, ES7210) — same before and after any reset pulse
+#define ADDR_AXP2101 0x34
+#define ADDR_CST9217 0x5A
+#define ADDR_CST816S 0x15
+
+static bool acked(const uint8_t *acks, int n, uint8_t addr)
+{
+ for (int i = 0; i < n; i++) if (acks[i] == addr) return true;
+ return false;
+}
+
+void board_from_acks(const uint8_t *acks, int n, board_t *out)
+{
+ const bool pmic = acked(acks, n, ADDR_AXP2101);
+ const bool cst9217 = acked(acks, n, ADDR_CST9217);
+ const bool cst816s = acked(acks, n, ADDR_CST816S);
+
+ // The reset pins follow the TOUCH CHIP: the CST816S module (DXQ0175Y003) is the one wired to
+ // GPIO1/2, whatever else is on the board. A dial with no touch answering at all is treated as
+ // board A — the shape this code was written for, and the PMIC (if any) says so too.
+ if (cst816s && !cst9217) {
+ out->lcd_rst = 1; out->touch_rst = 2;
+ out->touch = TOUCH_CST816S; out->touch_mirror = false;
+ } else {
+ out->lcd_rst = 39; out->touch_rst = 40;
+ out->touch = cst9217 ? TOUCH_CST9217 : TOUCH_NONE;
+ out->touch_mirror = true;
+ }
+ out->has_pmic = pmic;
+ out->name = out->touch == TOUCH_CST816S ? (pmic ? "cst816s+axp2101" : "cst816s")
+ : out->touch == TOUCH_CST9217 ? (pmic ? "cst9217+axp2101" : "cst9217")
+ : (pmic ? "notouch+axp2101" : "notouch");
+}
diff --git a/device/esp32-circle/main/board/power.c b/device/esp32-circle/main/board/power.c
index 8b40548bd..8993b527d 100644
--- a/device/esp32-circle/main/board/power.c
+++ b/device/esp32-circle/main/board/power.c
@@ -1,6 +1,7 @@
#include "power.h"
#include "board_pins.h"
#include "board_i2c.h"
+#include "board.h"
#include "driver/i2c_master.h"
#include "freertos/FreeRTOS.h"
#include "esp_log.h"
@@ -40,6 +41,10 @@ static void axp_pwrkey_setup(void)
bool power_init(void)
{
if (s_dev) return true;
+ // No PMIC on this dial (board.h): nothing to attach, and — the part that matters — nothing to poll.
+ // Attaching anyway cost a failed I2C transaction with a 50ms timeout on every read, ten times a
+ // second, for the whole life of the device.
+ if (!board()->has_pmic) return false;
i2c_master_bus_handle_t bus = board_i2c_get();
if (!bus) { ESP_LOGW(TAG, "shared i2c bus unavailable"); return false; }
i2c_device_config_t cfg = {
diff --git a/device/esp32-circle/main/cable_client.c b/device/esp32-circle/main/cable_client.c
index c6e0b27f2..1d2389f22 100644
--- a/device/esp32-circle/main/cable_client.c
+++ b/device/esp32-circle/main/cable_client.c
@@ -13,6 +13,7 @@
#include "esp_timer.h"
#include "fw_update.h"
#include "last_words.h"
+#include "board/board.h"
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
#include "freertos/task.h"
@@ -105,6 +106,9 @@ static void send_hello(void)
// Named before anything else about this dial is believed. See CABLE_PRODUCT.
cJSON_AddStringToObject(root, "product", CABLE_PRODUCT);
cJSON_AddNumberToObject(root, "proto", CABLE_PROTO_VERSION);
+ // Which of the two dials this is (board.h) — informational, so a log or a bug report can say. A
+ // daemon that predates the field ignores it.
+ cJSON_AddStringToObject(root, "hw", board()->name);
// Also the device's USB serial number, so the daemon can tell one dial from another before a byte is
// exchanged — and can tell a keepalive greeting from a new board.
char mac[24] = "";
diff --git a/device/esp32-circle/main/idf_component.yml b/device/esp32-circle/main/idf_component.yml
index a6fce2a19..2aa7ddc95 100644
--- a/device/esp32-circle/main/idf_component.yml
+++ b/device/esp32-circle/main/idf_component.yml
@@ -6,8 +6,11 @@ dependencies:
lvgl/lvgl: "^9.2.0"
# Official CO5300 AMOLED panel driver (the controller on this board).
espressif/esp_lcd_co5300: "*"
- # CST9217 capacitive touch (Waveshare) → LVGL pointer indev for swipe. Pulls esp_lcd_touch.
+ # Capacitive touch → LVGL pointer indev for swipe. BOTH controllers are linked in: the two dials
+ # that ship differ here (CST9217 on one, CST816S on the other) and one image serves both — the
+ # board is detected at boot (board/board.c) and the matching driver is opened. Pulls esp_lcd_touch.
waveshare/esp_lcd_touch_cst9217: "*"
+ espressif/esp_lcd_touch_cst816s: "^1.1.2"
# Audio codec abstraction + ES7210 (ADC/mic) + ES8311 drivers for mic capture.
espressif/esp_codec_dev: "*"
# WebSocket client used by commander_client.c. Pinned below 1.3.0: newer
diff --git a/device/esp32-circle/main/ptt.c b/device/esp32-circle/main/ptt.c
index 83c51d76a..c203ef70a 100644
--- a/device/esp32-circle/main/ptt.c
+++ b/device/esp32-circle/main/ptt.c
@@ -3,6 +3,7 @@
#include "ui/display.h"
#include "board/power.h"
#include "board/board_pins.h"
+#include "board/board.h"
#include "audio_client.h"
#include "driver/gpio.h"
#include "freertos/FreeRTOS.h"
@@ -11,14 +12,30 @@
#include "esp_log.h"
static const char *TAG = "ptt";
-#define POLL_MS 100 // AXP2101 PWR-key poll cadence (latency only — the key event latches)
+#define POLL_MS 100 // key poll cadence (latency only — the PMIC key event latches; BOOT is level-read)
+
+// Two keys, two dials (board.h):
+// • BOOT (GPIO0, both dials): a tap interrupts the running turn — fires on the press edge, so it is as
+// quick as it ever was. Held ≥ BOOT_LONG_PRESS_MS it also toggles the screen on/off — the same
+// gesture on both dials, so there is one thing to teach and one path to maintain.
+// • Button A (the PWR key, wired to the AXP2101 PWRON pin — read over I2C, not a GPIO): a tap toggles
+// the screen. Only where there is an AXP2101; a long press restarts the device in PMIC hardware and
+// never reaches us.
+// Voice is gesture-driven (touch.c); neither key touches it.
+#define BOOT_LONG_PRESS_MS 800
+
+static void screen_toggle(const char *why)
+{
+ // Hold the LVGL lock: display_sleep/wake touch LVGL timers + the panel, and normally run on the LVGL
+ // task; the recursive mutex serialises this ptt-task call with it.
+ display_lock();
+ if (display_is_asleep()) { ESP_LOGI(TAG, "%s → screen ON", why); display_wake(); }
+ else { ESP_LOGI(TAG, "%s → screen OFF", why); display_sleep(); }
+ display_unlock();
+}
-// Button A (the PWR key, wired to the AXP2101 PWRON pin — read over I2C, not a GPIO) toggles the SCREEN
-// on/off. Voice is gesture-driven now (double-tap starts, a tap stops — see touch.c), so this key no
-// longer touches voice. A LONG press restarts the device in AXP2101 hardware and never reaches us.
static void ptt_task(void *arg)
{
- // BOOT button (GPIO0, active-low) → interrupt the running turn (replaces the on-screen STOP).
gpio_config_t bcfg = {
.pin_bit_mask = 1ULL << BSP_BOOT_BUTTON,
.mode = GPIO_MODE_INPUT,
@@ -26,23 +43,24 @@ static void ptt_task(void *arg)
};
gpio_config(&bcfg);
int boot_prev = 1; // released (active-low: 1 = up, 0 = pressed)
+ int64_t press_start_us = 0;
+ bool long_fired = false;
+ const bool pwr_key = board()->has_pmic;
while (1) {
- if (power_take_pwrkey_tap()) { // one short press of button A (PWR) → toggle screen
- // Hold the LVGL lock: display_sleep/wake touch LVGL timers + the panel, and normally run on
- // the LVGL task; the recursive mutex serialises this ptt-task call with it.
- display_lock();
- if (display_is_asleep()) { ESP_LOGI(TAG, "PWR tap → screen ON"); display_wake(); }
- else { ESP_LOGI(TAG, "PWR tap → screen OFF"); display_sleep(); }
- display_unlock();
- }
+ if (pwr_key && power_take_pwrkey_tap()) screen_toggle("PWR tap");
- // BOOT button: on a fresh press (falling edge), interrupt the visible project's running turn.
int boot_now = gpio_get_level(BSP_BOOT_BUTTON);
- if (boot_prev == 1 && boot_now == 0) {
+ if (boot_prev == 1 && boot_now == 0) { // fresh press
if (display_is_asleep()) { display_lock(); display_wake(); display_unlock(); }
ESP_LOGI(TAG, "BOOT press → back / stop turn");
ui_boot_pressed();
+ press_start_us = esp_timer_get_time();
+ long_fired = false;
+ } else if (boot_now == 0 && !long_fired
+ && esp_timer_get_time() - press_start_us >= (int64_t)BOOT_LONG_PRESS_MS * 1000) {
+ long_fired = true; // once per press
+ screen_toggle("BOOT hold");
}
boot_prev = boot_now;
diff --git a/device/esp32-circle/main/ui/display.c b/device/esp32-circle/main/ui/display.c
index 94ed3421c..0c1204a73 100644
--- a/device/esp32-circle/main/ui/display.c
+++ b/device/esp32-circle/main/ui/display.c
@@ -3,6 +3,7 @@
#include "touch.h"
#include "ui_screens.h"
#include "board_pins.h"
+#include "board.h"
#include "ram_telemetry.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
@@ -167,7 +168,7 @@ static void panel_bringup(void)
.flags = { .use_qspi_interface = 1 },
};
esp_lcd_panel_dev_config_t pcfg = {
- .reset_gpio_num = BSP_LCD_RST,
+ .reset_gpio_num = board()->lcd_rst, // differs between the two dials — see board.h
.rgb_ele_order = LCD_RGB_ELEMENT_ORDER_RGB,
.bits_per_pixel = BSP_LCD_BIT_PER_PIXEL,
.vendor_config = &vendor,
diff --git a/device/esp32-circle/main/ui/touch.c b/device/esp32-circle/main/ui/touch.c
index 4dd091e89..c69668a4c 100644
--- a/device/esp32-circle/main/ui/touch.c
+++ b/device/esp32-circle/main/ui/touch.c
@@ -3,10 +3,12 @@
#include "cable_client.h"
#include "board_pins.h"
#include "board_i2c.h"
+#include "board.h"
#include "display.h"
#include "ui_screens.h" // ui_swipe_begin/end for the circular edge-swipe
#include "driver/i2c_master.h"
#include "esp_lcd_panel_io.h"
+#include "esp_lcd_touch_cst816s.h"
#include "esp_lcd_touch_cst9217.h"
#include "esp_log.h"
#include "lvgl.h"
@@ -293,6 +295,10 @@ static void swipe_track(bool pressed, uint16_t x, uint16_t y)
// CST9217 over I2C from here is fine (LVGL task holds no conflicting lock).
static bool touch_open(void);
static void touch_reinit(void);
+static const char *touch_chip_name(void)
+{
+ return board()->touch == TOUCH_CST816S ? "CST816S" : board()->touch == TOUCH_CST9217 ? "CST9217" : "no-touch";
+}
static void touch_read(lv_indev_t *indev, lv_indev_data_t *data)
{
@@ -316,7 +322,11 @@ static void touch_read(lv_indev_t *indev, lv_indev_data_t *data)
s_noack_run = 0;
pressed = esp_lcd_touch_get_coordinates(s_tp, &x, &y, &strength, &cnt, 1) && cnt > 0;
if (pressed) ok_reads++;
- } else if (rc == ESP_ERR_INVALID_RESPONSE) {
+ } else if (rc == ESP_ERR_INVALID_RESPONSE && board()->touch == TOUCH_CST9217) {
+ // CST9217 ONLY. The CST816S driver answers ESP_OK on every idle read (measured on that board, 30/30)
+ // and clears its own point table, so this rule would have nothing to do there — and must not run
+ // there, since an unexpected INVALID_RESPONSE from it would not mean "no finger".
+ //
// The chip's report has no ACK byte. MEASURED, not assumed (2026-09-15, this log): every idle
// read answers this way (~30/s with no finger near the glass), and NOT ONE read does while a
// finger is down — a still 2.9s hold read `acked=84 stale=0`. So no ACK is no finger.
@@ -346,10 +356,10 @@ static void touch_read(lv_indev_t *indev, lv_indev_data_t *data)
s_read_fail_total++;
s_read_fail_run++;
if (s_read_fail_run == 1 || s_read_fail_total % READ_FAIL_LOG_EVERY == 0)
- ESP_LOGW(TAG, "cst9217 read failed: %s (run=%u total=%u)", esp_err_to_name(rc),
+ ESP_LOGW(TAG, "%s read failed: %s (run=%u total=%u)", touch_chip_name(), esp_err_to_name(rc),
(unsigned)s_read_fail_run, (unsigned)s_read_fail_total);
if (s_read_fail_run >= READ_FAIL_REINIT) {
- ESP_LOGW(TAG, "cst9217 dead after %u failed reads — reinit", (unsigned)s_read_fail_run);
+ ESP_LOGW(TAG, "%s dead after %u failed reads — reinit", touch_chip_name(), (unsigned)s_read_fail_run);
s_read_fail_run = 0;
reinit_at = lv_tick_get();
touch_reinit();
@@ -511,7 +521,8 @@ static void touch_read(lv_indev_t *indev, lv_indev_data_t *data)
}
}
-// Bring the CST9217 up on the shared bus. Everything that can fail, logs and leaves s_tp NULL.
+// Bring the touch controller up on the shared bus — whichever one this dial has (board.h). Everything
+// that can fail, logs and leaves s_tp NULL.
static bool touch_open(void)
{
i2c_master_bus_handle_t bus = board_i2c_get();
@@ -519,8 +530,15 @@ static bool touch_open(void)
ESP_LOGW(TAG, "shared i2c bus unavailable — touch disabled");
return false;
}
+ const board_t *b = board();
+ if (b->touch == TOUCH_NONE) {
+ ESP_LOGW(TAG, "no touch controller answered on the bus — touch disabled");
+ return false;
+ }
- esp_lcd_panel_io_i2c_config_t io_cfg = ESP_LCD_TOUCH_IO_I2C_CST9217_CONFIG();
+ esp_lcd_panel_io_i2c_config_t io_cfg = b->touch == TOUCH_CST816S
+ ? (esp_lcd_panel_io_i2c_config_t)ESP_LCD_TOUCH_IO_I2C_CST816S_CONFIG()
+ : (esp_lcd_panel_io_i2c_config_t)ESP_LCD_TOUCH_IO_I2C_CST9217_CONFIG();
io_cfg.scl_speed_hz = BSP_I2C_FREQ_HZ;
if (esp_lcd_new_panel_io_i2c(bus, &io_cfg, &s_tp_io) != ESP_OK) {
ESP_LOGW(TAG, "touch panel io failed — touch disabled");
@@ -531,14 +549,18 @@ static bool touch_open(void)
esp_lcd_touch_config_t tp_cfg = {
.x_max = 466,
.y_max = 466,
- .rst_gpio_num = BSP_TOUCH_RST,
+ .rst_gpio_num = b->touch_rst,
.int_gpio_num = BSP_TOUCH_INT,
- // The CST9217 is mounted 180° relative to the CO5300 on this board, so BOTH axes are
- // reversed vs the display (horizontal swipe and vertical scroll/taps). Mirror X and Y.
- .flags = { .swap_xy = 0, .mirror_x = 1, .mirror_y = 1 },
+ // The CST9217 is mounted 180° relative to the CO5300 on its board, so BOTH axes are reversed vs
+ // the display (horizontal swipe and vertical scroll/taps). The CST816S reports panel-aligned
+ // coordinates — measured: mirrored, a touch landed 180° from the finger.
+ .flags = { .swap_xy = 0, .mirror_x = b->touch_mirror, .mirror_y = b->touch_mirror },
};
- if (esp_lcd_touch_new_i2c_cst9217(s_tp_io, &tp_cfg, &s_tp) != ESP_OK) {
- ESP_LOGW(TAG, "CST9217 init failed — touch disabled");
+ esp_err_t err = b->touch == TOUCH_CST816S
+ ? esp_lcd_touch_new_i2c_cst816s(s_tp_io, &tp_cfg, &s_tp)
+ : esp_lcd_touch_new_i2c_cst9217(s_tp_io, &tp_cfg, &s_tp);
+ if (err != ESP_OK) {
+ ESP_LOGW(TAG, "%s init failed (%s) — touch disabled", touch_chip_name(), esp_err_to_name(err));
s_tp = NULL;
esp_lcd_panel_io_del(s_tp_io);
s_tp_io = NULL;
@@ -555,8 +577,8 @@ static void touch_reinit(void)
{
if (s_tp) { esp_lcd_touch_del(s_tp); s_tp = NULL; }
if (s_tp_io) { esp_lcd_panel_io_del(s_tp_io); s_tp_io = NULL; }
- if (touch_open()) ESP_LOGI(TAG, "CST9217 back after reinit");
- else ESP_LOGW(TAG, "CST9217 reinit failed — retrying in %ds", REINIT_RETRY_MS / 1000);
+ if (touch_open()) ESP_LOGI(TAG, "%s back after reinit", touch_chip_name());
+ else ESP_LOGW(TAG, "%s reinit failed — retrying in %ds", touch_chip_name(), REINIT_RETRY_MS / 1000);
}
void touch_stats(touch_stats_t *out)
@@ -576,5 +598,5 @@ void touch_init(void)
lv_indev_t *indev = lv_indev_create();
lv_indev_set_type(indev, LV_INDEV_TYPE_POINTER);
lv_indev_set_read_cb(indev, touch_read);
- ESP_LOGI(TAG, "CST9217 touch ready");
+ ESP_LOGI(TAG, "%s touch ready", touch_chip_name());
}
diff --git a/device/esp32-circle/test/run.sh b/device/esp32-circle/test/run.sh
index 7f9d69c7e..81f21dcc5 100755
--- a/device/esp32-circle/test/run.sh
+++ b/device/esp32-circle/test/run.sh
@@ -30,3 +30,9 @@ cc -std=c11 -Wall -Wextra -Werror -O1 \
cc -std=c11 -Wall -Wextra -Werror -O1 \
-o "$out/test_carousel_ring" "$here/test_carousel_ring.c" "$here/../main/ui/carousel_ring.c"
"$out/test_carousel_ring"
+
+# Which dial this image is on, decided from who answered on the I2C bus. Two boards ship on one image;
+# the table that tells them apart is arithmetic on a list of addresses, so it is proved here.
+cc -std=c11 -Wall -Wextra -Werror -O1 \
+ -o "$out/test_board" "$here/test_board.c" "$here/../main/board/board_table.c"
+"$out/test_board"
diff --git a/device/esp32-circle/test/test_board.c b/device/esp32-circle/test/test_board.c
new file mode 100644
index 000000000..2ae1a5a82
--- /dev/null
+++ b/device/esp32-circle/test/test_board.c
@@ -0,0 +1,39 @@
+// The board decision table, proved without a bus. See main/board/board_table.c.
+#include <stdio.h>
+#include <string.h>
+#include "../main/board/board.h"
+
+static int fails;
+#define CHECK(cond) do { if (!(cond)) { fails++; printf("FAIL %s:%d %s\n", __FILE__, __LINE__, #cond); } } while (0)
+
+static board_t decide(const uint8_t *acks, int n) { board_t b; memset(&b, 0, sizeof b); board_from_acks(acks, n, &b); return b; }
+
+int main(void)
+{
+ // Board A, as measured: AXP2101 + CST9217 (+ the codecs, which the decision ignores).
+ board_t a = decide((const uint8_t[]){ 0x34, 0x5A, 0x18, 0x40 }, 4);
+ CHECK(a.touch == TOUCH_CST9217); CHECK(a.touch_mirror); CHECK(a.has_pmic);
+ CHECK(a.lcd_rst == 39 && a.touch_rst == 40); CHECK(!strcmp(a.name, "cst9217+axp2101"));
+
+ // Board B, as measured: CST816S alone.
+ board_t b = decide((const uint8_t[]){ 0x15, 0x18, 0x40 }, 3);
+ CHECK(b.touch == TOUCH_CST816S); CHECK(!b.touch_mirror); CHECK(!b.has_pmic);
+ CHECK(b.lcd_rst == 1 && b.touch_rst == 2); CHECK(!strcmp(b.name, "cst816s"));
+
+ // A batch that mixes them: the reset pins follow the touch chip, the PMIC is its own fact.
+ board_t mix = decide((const uint8_t[]){ 0x15, 0x34 }, 2);
+ CHECK(mix.touch == TOUCH_CST816S && mix.has_pmic && mix.lcd_rst == 1);
+ CHECK(!strcmp(mix.name, "cst816s+axp2101"));
+
+ // Nothing answered: board A's shape, no touch, no PMIC — the UI still has to come up.
+ board_t none = decide(NULL, 0);
+ CHECK(none.touch == TOUCH_NONE && !none.has_pmic && none.lcd_rst == 39);
+ CHECK(!strcmp(none.name, "notouch"));
+
+ // Both touch chips answering is not a board that exists; CST9217's pins win (board A's shape).
+ board_t both = decide((const uint8_t[]){ 0x5A, 0x15 }, 2);
+ CHECK(both.touch == TOUCH_CST9217 && both.lcd_rst == 39);
+
+ printf("board: %s\n", fails ? "FAILED" : "ok");
+ return fails ? 1 : 0;
+}
diff --git a/docs/plans/2026-09-15-004-two-boards-plan.md b/docs/plans/2026-09-15-004-two-boards-plan.md
new file mode 100644
index 000000000..3e08e278a
--- /dev/null
+++ b/docs/plans/2026-09-15-004-two-boards-plan.md
@@ -0,0 +1,120 @@
+# One firmware for two dials: runtime board detection
+
+Status: implemented · 2026-09-15
+
+## Context
+
+Two physical dials will ship at once. Same panel (CO5300 466×466 over QSPI), same audio (ES7210 @0x40 /
+ES8311 @0x18), same I2C/I2S/QSPI pins, same UI, cable protocol and OTA. They differ only under
+`board/`, `touch.c` and `ptt.c` (`~/Downloads/TOUCH_AND_BUTTON_PORT.md`, measured on two units):
+
+| | Board A (what the repo targets today) | Board B (the port doc) |
+|---|---|---|
+| Touch controller | CST9217 @ `0x5A`, `mirror_x/y = 1` | CST816S @ `0x15`, no mirror |
+| LCD reset / touch reset | GPIO39 / GPIO40 | GPIO1 / GPIO2 |
+| PMIC AXP2101 @ `0x34` | present: battery %, charging, PWR key | **absent** |
+| Screen sleep/wake key | PWR key via PMIC (`power_take_pwrkey_tap`) | BOOT held ≥ 800 ms |
+| Touch driver component | `waveshare/esp_lcd_touch_cst9217` | `espressif/esp_lcd_touch_cst816s ^1.1.2` |
+
+Today every one of those is a compile-time constant (`main/board/board_pins.h`) and there is one
+binary, one OTA manifest, one `make upload-circle`. Two build targets would mean two manifests, a
+dial that has to know its own SKU (eFuse/NVS at the factory), two release paths and the failure
+"wrong image flashed → no touch". None of that is needed: **every difference is a fact the bus can
+answer at boot**, so one image detects the board and configures itself. The daemon, `harness flash`,
+OTA and CI stay exactly as they are.
+
+Not per SKU — per **feature**: `has_pmic`, `touch chip`, `reset pins` are read independently, so a
+future batch mixing them (CST816S + AXP2101, say) is right without a "board C".
+
+## Detection (the whole design in one function)
+
+`main/board/board.c` — `board_detect()`, run first thing in `app_main`, before `display_init()`:
+
+1. `board_i2c_get()` (bus is common to both boards).
+2. **PMIC**: `i2c_master_probe(bus, 0x34, 50)` — ACK ⇒ `has_pmic`. No reset involved; the AXP2101
+ is always live on the bus. This is the most reliable fact, taken first.
+3. **Reset both candidate pairs**: pulse GPIO39/40 then GPIO1/2 (low 10 ms, high, wait 50 ms —
+ what both touch drivers do internally). Per `board_pins.h` GPIO1/2 are unused on A and
+ GPIO39/40 unused on B, so the "other" pair is a no-connect on each board. ⚠️ This is the one
+ assumption the code cannot verify itself — **step 0 below measures it on both units before anything
+ is written**.
+4. **Touch**: probe `0x5A` ⇒ CST9217 (mirror XY, rst 39/40); else probe `0x15` ⇒ CST816S (no
+ mirror, rst 1/2); else `TOUCH_NONE` (UI still boots, as it does today when touch init fails).
+5. Result: `const board_t *board(void)` — `{ lcd_rst, touch_rst, touch (enum), touch_mirror,
+ has_pmic, name }`; one INFO line `board: touch=cst816s pmic=no rst=1/2 acks=15,18,40` that goes
+ up the cable into `dial-*.log`.
+6. Pure decision table `board_from_acks(const uint8_t *acks, int n, board_t *out)` — host-testable.
+
+Fallback if step 0 shows the cross-pulse is NOT harmless: order the reset by the PMIC answer
+(PMIC ⇒ pulse 39/40 and probe `0x5A`; none ⇒ pulse 1/2 and probe `0x15`), and only on a miss pulse
+the other pair and probe again. Same result, one more branch.
+
+## Changes
+
+### Firmware `device/esp32-circle/main/`
+- **`board/board.{c,h}`** (new): `board_detect()`, `board()`, `board_from_acks()`, the two pin
+ tables. `board_pins.h` keeps only what is common (QSPI, I2C, I2S, BOOT, INT=11); `BSP_LCD_RST`,
+ `BSP_TOUCH_RST`, `BSP_TOUCH_I2C_ADDR`, `BSP_AXP2101_I2C_ADDR` move into the tables.
+- **`ui/display.c`** `panel_bringup()`: `.reset_gpio_num = board()->lcd_rst`.
+- **`ui/touch.c`** `touch_open()`: both drivers compiled in; `switch (board()->touch)` picks
+ `esp_lcd_touch_new_i2c_cst9217` or `..._cst816s`, io config macro per chip, `.rst_gpio_num =
+ board()->touch_rst`, `.flags.mirror_* = board()->touch_mirror`. `touch_reinit()` unchanged (both
+ drivers are `esp_lcd_touch_handle_t`). The `ESP_ERR_INVALID_RESPONSE` = "no finger" rule
+ (2026-09-15) is a CST9217 fact — keep it under `if (board()->touch == TOUCH_CST9217)` and measure
+ what CST816S returns idle (step 3) before deciding its branch. Log `CST816S: IC id` / `Chip Type`
+ after init as the second confirmation.
+- **`board/power.{c,h}`**: `power_init()` returns false without touching the bus when
+ `!board()->has_pmic`; getters already answer -1/false when `s_dev == NULL`. Drop the doc's stub
+ approach — one file serves both.
+- **`ptt.c`**: BOOT long-press ≥ 800 ms toggles `display_sleep/wake` **on both boards** (one UX to
+ teach, one code path; the doc's snippet). PWR-key tap stays on A (`if (board()->has_pmic)`),
+ polled as today. Short BOOT tap = interrupt turn, unchanged.
+- **`ui/ui_screens.c`**: nothing — the charge bolt already keys off `power_is_on_external()`; a
+ Settings battery row, if any is added later, gates on `board()->has_pmic`.
+- **`cable_client.c`** `send_hello()`: add `"hw": board()->name` (`"cst9217+axp2101"`,
+ `"cst816s"`, …). Additive JSON, proto version unchanged.
+- **`idf_component.yml`**: add `espressif/esp_lcd_touch_cst816s: "^1.1.2"`, keep the cst9217 one.
+- **`sdkconfig.defaults`**: nothing expected; verify both drivers link without Kconfig.
+
+### Daemon `cli/src/cable/`
+- `cableSession.ts` hello: read `hw` (optional), include it in the `cable: dial … on fw … proto …`
+ line and in `DialStatus` (`hw?: string`) → `dialStatus` push. `dialLog.greeted()` unchanged.
+- `docs/specs/cable-protocol.md` §hello: document `hw` as optional, informational.
+- Tests: `cableSession.spec.ts` — hello with/without `hw` both greet; the log line carries it.
+
+### App `desktop/`
+- `dial_status` already reaches the app; show `hw` beside fw where the dial's firmware is shown
+ (Settings ▸ About / the flash dialog). Small, optional; skip if no such surface exists today.
+
+### Host tests `device/esp32-circle/test/`
+- `test_board.c` + a line in `run.sh`: `board_from_acks` table — `{34,5A,18,40}`→A,
+ `{15,18,40}`→B, `{15,34,…}`→cst816s+pmic, `{}`→none. Also that `board.c` compiles on the host
+ (isolate the decision from `driver/gpio.h` via a thin `board_detect.c`/`board_table.c` split).
+
+### Docs
+- `device/esp32-circle/README` (or `RELEASE.md`): "Two boards, one image" section with the table,
+ the detect order, and the verification recipe from the port doc (I2C ACK list, `IC id: 183`).
+
+## Order, and which dial to plug in
+
+| step | what | plug in |
+|---|---|---|
+| 0 | **Measure before writing.** Throwaway probe in `app_main` (behind `#if 0`-style flag, never committed): scan 0x08–0x77, print ACKs; then pulse 39/40 *and* 1/2 and scan again. Confirms (a) the ACK table, (b) the cross-pulse is harmless, (c) CST816S's idle `read_data` return code. | **B first**, then A |
+| 1 | `board.{c,h}` + host test + `board_pins.h` split. `make device-test`. | none |
+| 2 | `display.c`, `touch.c`, `power.c`, `ptt.c`, `idf_component.yml` on the new tables. Build. Flash → boot log `board: …`, `CST9217 touch ready`, tap lands where the finger is, PWR tap sleeps, BOOT long-press sleeps. | **A** (regression) |
+| 3 | Same image, no rebuild. Boot log `board: touch=cst816s pmic=no`, `CST816S: IC id: 183`, taps not mirrored, BOOT long-press sleeps/wakes, no `i2c transaction failed` spam, `alive` heartbeat every 60 s, `read-fails` absent in it. | **B** |
+| 4 | `hello.hw` + daemon + spec + spec tests. `make install-cli`; dial log shows `on fw … hw cst816s`. | B, then A |
+| 5 | Voice on both (mic path is shared — a sanity check, not expected to differ). Notification tap, swipe, question close. | both, one after the other |
+| 6 | Publish: `make release-cli`, `make upload-circle` (one image) → both dials OTA to it; watch `boot: reset reason` + `board:` lines in each dial's log after the update. | both, cabled in turn |
+
+## Verification
+- `make device-test` green (new `test_board`).
+- `idf.py build` clean; `cli`: `tsc`, `vitest run src/cable`.
+- Board A: no behaviour change except BOOT long-press now also sleeps the screen.
+- Board B: touch, sleep/wake, no PMIC noise in the log, OTA works from the same manifest.
+- `~/.harness/logs/dial-*.log` for each board contains `board:` at boot and `hw` in the greeting.
+
+## Out of scope
+- Battery UI for B (there is no battery).
+- A second OTA manifest or SKU eFuse — explicitly rejected above.
+- Any UI/LVGL change.
diff --git a/docs/specs/cable-protocol.md b/docs/specs/cable-protocol.md
index e7e5cf9b6..1409364fc 100644
--- a/docs/specs/cable-protocol.md
+++ b/docs/specs/cable-protocol.md
@@ -100,7 +100,7 @@ needs no machine component and events for a machine that is not selected are dro
| `t` | Fields | Meaning |
|---|---|---|
-| `hello` | `fw`, `proto`, `mac` | First thing after boot, and repeated (below). `mac` is also the USB serial number, so the daemon can tell one dial from another before a byte is exchanged. |
+| `hello` | `fw`, `proto`, `mac`, `hw` | First thing after boot, and repeated (below). `mac` is also the USB serial number, so the daemon can tell one dial from another before a byte is exchanged. `hw` (since fw 0.0.68, optional) names the board the firmware detected itself on at boot — `cst9217+axp2101` or `cst816s` — two dials ship on one image (device `board/board.h`); informational, the daemon logs it and passes it to the app in `dial_status`. |
| `pong` | — | The answer to `ping`. Empty: the arrival is the content. |
| `agents.list` | — | Send me the tiles. |
| `machines.list` | — | Send me the machine wheel. |