feat: add AXS15231B touch driver with coordinate parsing tests

8 files changed, 476 insertions, 1 deletions

diff --git a/TOUCH_WIFI_SETUP_PLAN.md b/TOUCH_WIFI_SETUP_PLAN.md
new file mode 100644
index 0000000..afbc0b3
--- /dev/null
+++ b/TOUCH_WIFI_SETUP_PLAN.md
@@ -0,0 +1,92 @@
+# Touchscreen WiFi Setup Plan
+
+## Overview
+Add touchscreen WiFi configuration to the TollGate display so users can select a gateway network and enter a password directly on the device.
+
+## Hardware
+
+### Touch Controller
+- **IC:** AXS15231B built-in touch (same chip as display, separate I2C interface)
+- **Bus:** I2C, address `0x3B`
+- **Pins:** SDA=GPIO4, SCL=GPIO8, RST=GPIO12, INT=GPIO11
+- **Protocol:** Write 11 bytes `[0xb5,0xab,0xa5,0x5a,0x00,0x00,0x00,0x08,0x00,0x00,0x00]`, read 8 bytes
+- **Coordinates:** X/Y from data bytes [2..5], 12-bit
+- **RST sequence:** LOW 200ms -> HIGH 200ms
+
+### No Pin Conflicts
+| Pin | Display | Touch | Conflict? |
+|-----|---------|-------|-----------|
+| 4   | --      | SDA   | No |
+| 8   | --      | SCL   | No |
+| 11  | --      | INT   | No |
+| 12  | --      | RST   | No |
+| 1,21,39,40,45,47,48 | Display QSPI | -- | No |
+
+## Trigger Points (all three)
+
+| Trigger | How | When |
+|---------|-----|------|
+| A) Tap on ERROR screen | "Setup WiFi" button | Any time upstream is down |
+| B) Auto-show on first boot | Check wifi_networks empty | Fresh device with no credentials |
+| C) Setup button on READY/ERROR | Small gear icon in corner | Always accessible |
+
+## UI Screens
+
+### 1. Scanning
+Title + "Scanning..." spinner
+
+### 2. Network List
+Top 8 by RSSI, sorted strongest first, scrollable. Lock icon for secured networks.
+
+### 3. Password Entry
+SSID name, masked password field with eye reveal toggle, QWERTY keyboard.
+
+### 4. Connecting
+"Connecting to SSID..." spinner
+
+### 5. Result
+Green "Connected!" with IP, or red "Failed" with retry options.
+
+## New Files
+
+| File | Purpose | Testable Logic |
+|------|---------|----------------|
+| `main/touch.h/c` | AXS15231B I2C touch driver | Coordinate parsing |
+| `main/keyboard.h/c` | On-screen keyboard rendering + hit detection | Layout, key lookup |
+| `main/wifi_setup.h/c` | WiFi scan/select/connect flow | State machine |
+| `tests/unit/test_touch.c` | Touch coordinate decode | Pure math |
+| `tests/unit/test_keyboard.c` | Key layout + hit detection | Pure logic |
+| `tests/unit/test_wifi_setup.c` | Setup state machine | State transitions |
+
+## Config Extension
+Add `tollgate_config_add_wifi(const char *ssid, const char *password)` to `config.c` - rewrites `/spiffs/config.json`.
+
+## Display Extension
+Add `DISPLAY_WIFI_SETUP` to `display_state_t`.
+
+## Implementation Checklist
+
+### Phase 1: Touch Driver
+- [ ] Create `main/touch.h` with API
+- [ ] Create `main/touch.c` with ESP-IDF I2C v5 implementation
+- [ ] Create `tests/unit/test_touch.c` with coordinate parsing tests
+- [ ] Run `make test-unit`, verify all pass
+
+### Phase 2: On-Screen Keyboard
+- [ ] Create `main/keyboard.h` with API
+- [ ] Create `main/keyboard.c` with QWERTY layout + hit detection
+- [ ] Create `tests/unit/test_keyboard.c` with layout + key lookup tests
+- [ ] Run `make test-unit`, verify all pass
+
+### Phase 3: WiFi Setup Flow
+- [ ] Create `main/wifi_setup.h` with API
+- [ ] Create `main/wifi_setup.c` with scan/list/connect state machine
+- [ ] Add `tollgate_config_add_wifi()` to config.c + config.h
+- [ ] Create `tests/unit/test_wifi_setup.c` with state machine tests
+- [ ] Run `make test-unit`, verify all pass
+
+### Phase 4: Integration
+- [ ] Add `DISPLAY_WIFI_SETUP` to display.h
+- [ ] Update display.c with WiFi setup rendering + touch input
+- [ ] Update `main/CMakeLists.txt` with new source files
+- [ ] Build, flash to Board C, verify full flow
diff --git a/main/touch.c b/main/touch.c
new file mode 100644
index 0000000..5a1eec9
--- /dev/null
+++ b/main/touch.c
@@ -0,0 +1,131 @@
+#include "touch.h"
+#include "esp_log.h"
+#include "driver/i2c_master.h"
+#include "driver/gpio.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include <string.h>
+
+static const char *TAG = "touch";
+
+static i2c_master_bus_handle_t s_bus = NULL;
+static i2c_master_dev_handle_t s_dev = NULL;
+static bool s_initialized = false;
+
+static const uint8_t s_read_cmd[11] = {
+    0xb5, 0xab, 0xa5, 0x5a, 0x00, 0x00, 0x00, 0x08, 0x00, 0x00, 0x00
+};
+
+void touch_parse_raw(const uint8_t *data, touch_point_t *pt) {
+    memset(pt, 0, sizeof(*pt));
+
+    if (!data || data[0] != 0 || data[1] == 0 || data[1] > 1) {
+        pt->touched = false;
+        return;
+    }
+
+    uint16_t raw_x = ((data[2] & 0x0F) << 8) | data[3];
+    uint16_t raw_y = ((data[4] & 0x0F) << 8) | data[5];
+
+    if (raw_x > TOUCH_MAX_X) raw_x = TOUCH_MAX_X;
+    if (raw_y > TOUCH_MAX_Y) raw_y = TOUCH_MAX_Y;
+
+    pt->x = raw_x;
+    pt->y = raw_y;
+    pt->touched = true;
+}
+
+esp_err_t touch_init(void) {
+    if (s_initialized) return ESP_OK;
+
+    gpio_config_t rst_conf = {
+        .pin_bit_mask = (1ULL << TOUCH_RST_PIN),
+        .mode = GPIO_MODE_OUTPUT,
+        .pull_up_en = GPIO_PULLUP_DISABLE,
+        .pull_down_en = GPIO_PULLDOWN_DISABLE,
+        .intr_type = GPIO_INTR_DISABLE,
+    };
+    gpio_config(&rst_conf);
+
+    gpio_set_level(TOUCH_RST_PIN, 0);
+    vTaskDelay(pdMS_TO_TICKS(200));
+    gpio_set_level(TOUCH_RST_PIN, 1);
+    vTaskDelay(pdMS_TO_TICKS(200));
+
+    i2c_master_bus_config_t bus_cfg = {
+        .i2c_port = I2C_NUM_0,
+        .sda_io_num = TOUCH_SDA_PIN,
+        .scl_io_num = TOUCH_SCL_PIN,
+        .clk_source = I2C_CLK_SRC_DEFAULT,
+        .glitch_ignore_cnt = 7,
+        .intr_priority = 0,
+        .trans_queue_depth = 0,
+        .flags = {
+            .enable_internal_pullup = 1,
+            .allow_pd = 0,
+        },
+    };
+
+    esp_err_t ret = i2c_new_master_bus(&bus_cfg, &s_bus);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to create I2C bus: %s", esp_err_to_name(ret));
+        return ret;
+    }
+
+    i2c_device_config_t dev_cfg = {
+        .dev_addr_length = I2C_ADDR_BIT_LEN_7,
+        .device_address = TOUCH_I2C_ADDR,
+        .scl_speed_hz = 400000,
+        .scl_wait_us = 0,
+        .flags = {
+            .disable_ack_check = 0,
+        },
+    };
+
+    ret = i2c_master_bus_add_device(s_bus, &dev_cfg, &s_dev);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to add I2C device: %s", esp_err_to_name(ret));
+        i2c_del_master_bus(s_bus);
+        s_bus = NULL;
+        return ret;
+    }
+
+    s_initialized = true;
+    ESP_LOGI(TAG, "Touch initialized (I2C addr 0x%02X)", TOUCH_I2C_ADDR);
+    return ESP_OK;
+}
+
+bool touch_read(touch_point_t *pt) {
+    if (!s_initialized || !s_dev || !pt) {
+        if (pt) pt->touched = false;
+        return false;
+    }
+
+    esp_err_t ret = i2c_master_transmit(s_dev, s_read_cmd, sizeof(s_read_cmd), 100);
+    if (ret != ESP_OK) {
+        pt->touched = false;
+        return false;
+    }
+
+    uint8_t data[8] = {0};
+    ret = i2c_master_receive(s_dev, data, sizeof(data), 100);
+    if (ret != ESP_OK) {
+        pt->touched = false;
+        return false;
+    }
+
+    touch_parse_raw(data, pt);
+    return pt->touched;
+}
+
+void touch_deinit(void) {
+    if (s_dev) {
+        i2c_master_bus_rm_device(s_dev);
+        s_dev = NULL;
+    }
+    if (s_bus) {
+        i2c_del_master_bus(s_bus);
+        s_bus = NULL;
+    }
+    s_initialized = false;
+}
diff --git a/main/touch.h b/main/touch.h
new file mode 100644
index 0000000..a4a5aa4
--- /dev/null
+++ b/main/touch.h
@@ -0,0 +1,28 @@
+#ifndef TOUCH_H
+#define TOUCH_H
+
+#include "esp_err.h"
+#include <stdint.h>
+#include <stdbool.h>
+
+#define TOUCH_SDA_PIN    4
+#define TOUCH_SCL_PIN    8
+#define TOUCH_RST_PIN    12
+#define TOUCH_INT_PIN    11
+#define TOUCH_I2C_ADDR   0x3B
+#define TOUCH_MAX_X      319
+#define TOUCH_MAX_Y      479
+
+typedef struct {
+    uint16_t x;
+    uint16_t y;
+    bool touched;
+} touch_point_t;
+
+esp_err_t touch_init(void);
+bool touch_read(touch_point_t *pt);
+void touch_deinit(void);
+
+void touch_parse_raw(const uint8_t *data, touch_point_t *pt);
+
+#endif
diff --git a/tests/unit/Makefile b/tests/unit/Makefile
index 7ebc3b2..5bc5eb1 100644
--- a/tests/unit/Makefile
+++ b/tests/unit/Makefile
@@ -22,7 +22,7 @@ LDFLAGS := -lmbedcrypto -lcjson -lm
 
 SECP256K1_OBJ := secp256k1.o precomputed_ecmult.o precomputed_ecmult_gen.o
 
-TESTS := test_geohash test_identity test_nostr_event test_cashu test_session test_tollgate_client test_lnurl_pay test_lightning_payout test_mcp_handler test_nip04 test_cvm_server
+TESTS := test_geohash test_identity test_nostr_event test_cashu test_session test_tollgate_client test_lnurl_pay test_lightning_payout test_mcp_handler test_nip04 test_cvm_server test_touch
 
 .PHONY: all test clean $(TESTS)
 
@@ -81,5 +81,8 @@ test_nip04: test_nip04.c $(REPO_ROOT)/main/nip04.c $(SECP256K1_OBJ)
 test_cvm_server: test_cvm_server.c
         $(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
 
+test_touch: test_touch.c $(REPO_ROOT)/main/touch.c
+        $(CC) $(CFLAGS) $< $(REPO_ROOT)/main/touch.c -o $@ $(LDFLAGS)
+
 clean:
         rm -f $(TESTS) $(SECP256K1_OBJ)
diff --git a/tests/unit/stubs/driver/gpio.h b/tests/unit/stubs/driver/gpio.h
new file mode 100644
index 0000000..d8dda0a
--- /dev/null
+++ b/tests/unit/stubs/driver/gpio.h
@@ -0,0 +1,44 @@
+#ifndef STUBS_DRIVER_GPIO_H
+#define STUBS_DRIVER_GPIO_H
+
+#include <stdint.h>
+
+typedef enum {
+    GPIO_MODE_DISABLE = 0,
+    GPIO_MODE_INPUT,
+    GPIO_MODE_OUTPUT,
+    GPIO_MODE_OUTPUT_OD,
+    GPIO_MODE_INPUT_OUTPUT_OD,
+    GPIO_MODE_INPUT_OUTPUT,
+} gpio_mode_t;
+
+typedef enum {
+    GPIO_INTR_DISABLE = 0,
+} gpio_int_type_t;
+
+typedef enum {
+    GPIO_PULLUP_DISABLE = 0,
+    GPIO_PULLUP_ENABLE,
+} gpio_pullup_t;
+
+typedef enum {
+    GPIO_PULLDOWN_DISABLE = 0,
+    GPIO_PULLDOWN_ENABLE,
+} gpio_pulldown_t;
+
+typedef struct {
+    uint64_t pin_bit_mask;
+    gpio_mode_t mode;
+    gpio_pullup_t pull_up_en;
+    gpio_pulldown_t pull_down_en;
+    gpio_int_type_t intr_type;
+} gpio_config_t;
+
+static inline int gpio_config(const gpio_config_t *cfg) { (void)cfg; return 0; }
+static inline int gpio_set_level(uint32_t gpio_num, uint32_t level) { (void)gpio_num; (void)level; return 0; }
+
+#define GPIO_INTR_DISABLE 0
+#define GPIO_PULLUP_DISABLE 0
+#define GPIO_PULLDOWN_DISABLE 0
+
+#endif
diff --git a/tests/unit/stubs/driver/i2c_master.h b/tests/unit/stubs/driver/i2c_master.h
new file mode 100644
index 0000000..f49eaad
--- /dev/null
+++ b/tests/unit/stubs/driver/i2c_master.h
@@ -0,0 +1,39 @@
+#ifndef STUBS_DRIVER_I2C_MASTER_H
+#define STUBS_DRIVER_I2C_MASTER_H
+
+#include "driver/i2c_types.h"
+#include "esp_err.h"
+#include <stdint.h>
+#include <stddef.h>
+
+static inline esp_err_t i2c_new_master_bus(const i2c_master_bus_config_t *cfg, i2c_master_bus_handle_t *ret) {
+    (void)cfg; (void)ret;
+    return ESP_OK;
+}
+
+static inline esp_err_t i2c_master_bus_add_device(i2c_master_bus_handle_t bus, const i2c_device_config_t *cfg, i2c_master_dev_handle_t *ret) {
+    (void)bus; (void)cfg; (void)ret;
+    return ESP_OK;
+}
+
+static inline esp_err_t i2c_master_transmit(i2c_master_dev_handle_t dev, const uint8_t *buf, size_t len, int timeout_ms) {
+    (void)dev; (void)buf; (void)len; (void)timeout_ms;
+    return ESP_OK;
+}
+
+static inline esp_err_t i2c_master_receive(i2c_master_dev_handle_t dev, uint8_t *buf, size_t len, int timeout_ms) {
+    (void)dev; (void)buf; (void)len; (void)timeout_ms;
+    return ESP_OK;
+}
+
+static inline esp_err_t i2c_master_bus_rm_device(i2c_master_dev_handle_t dev) {
+    (void)dev;
+    return ESP_OK;
+}
+
+static inline esp_err_t i2c_del_master_bus(i2c_master_bus_handle_t bus) {
+    (void)bus;
+    return ESP_OK;
+}
+
+#endif
diff --git a/tests/unit/stubs/driver/i2c_types.h b/tests/unit/stubs/driver/i2c_types.h
new file mode 100644
index 0000000..3590a8b
--- /dev/null
+++ b/tests/unit/stubs/driver/i2c_types.h
@@ -0,0 +1,45 @@
+#ifndef STUBS_DRIVER_I2C_TYPES_H
+#define STUBS_DRIVER_I2C_TYPES_H
+
+#include <stdint.h>
+#include <stddef.h>
+
+typedef int i2c_port_num_t;
+#define I2C_NUM_0 0
+
+typedef enum {
+    I2C_ADDR_BIT_LEN_7 = 0,
+} i2c_addr_bit_len_t;
+
+typedef enum {
+    I2C_CLK_SRC_DEFAULT = 0,
+} i2c_clock_source_t;
+
+typedef struct i2c_master_bus_t *i2c_master_bus_handle_t;
+typedef struct i2c_master_dev_t *i2c_master_dev_handle_t;
+
+typedef struct {
+    i2c_port_num_t i2c_port;
+    int sda_io_num;
+    int scl_io_num;
+    i2c_clock_source_t clk_source;
+    uint8_t glitch_ignore_cnt;
+    int intr_priority;
+    size_t trans_queue_depth;
+    struct {
+        uint32_t enable_internal_pullup : 1;
+        uint32_t allow_pd : 1;
+    } flags;
+} i2c_master_bus_config_t;
+
+typedef struct {
+    i2c_addr_bit_len_t dev_addr_length;
+    uint16_t device_address;
+    uint32_t scl_speed_hz;
+    uint32_t scl_wait_us;
+    struct {
+        uint32_t disable_ack_check : 1;
+    } flags;
+} i2c_device_config_t;
+
+#endif
diff --git a/tests/unit/test_touch.c b/tests/unit/test_touch.c
new file mode 100644
index 0000000..13f04b5
--- /dev/null
+++ b/tests/unit/test_touch.c
@@ -0,0 +1,93 @@
+#include "test_framework.h"
+#include "../../main/touch.h"
+#include <string.h>
+
+int main(void)
+{
+    touch_point_t pt;
+    uint8_t data[8];
+
+    printf("=== test_touch ===\n");
+
+    memset(data, 0, sizeof(data));
+    touch_parse_raw(data, &pt);
+    ASSERT(!pt.touched, "All-zero data = no touch");
+
+    data[0] = 1;
+    data[1] = 1;
+    data[2] = 0;
+    data[3] = 0;
+    touch_parse_raw(data, &pt);
+    ASSERT(!pt.touched, "data[0]=1 = no touch (gesture byte nonzero)");
+
+    data[0] = 0;
+    data[1] = 0;
+    touch_parse_raw(data, &pt);
+    ASSERT(!pt.touched, "data[1]=0 = no touch (touch count zero)");
+
+    data[0] = 0;
+    data[1] = 1;
+    data[2] = 0x00;
+    data[3] = 0x64;
+    data[4] = 0x00;
+    data[5] = 0xC8;
+    data[6] = 0;
+    data[7] = 0;
+    touch_parse_raw(data, &pt);
+    ASSERT(pt.touched, "Valid touch: touched=true");
+    ASSERT_EQ_INT(100, (int)pt.x, "Valid touch: x=100");
+    ASSERT_EQ_INT(200, (int)pt.y, "Valid touch: y=200");
+
+    data[0] = 0;
+    data[1] = 1;
+    data[2] = 0x0F;
+    data[3] = 0xFF;
+    data[4] = 0x0F;
+    data[5] = 0xFF;
+    touch_parse_raw(data, &pt);
+    ASSERT(pt.touched, "Max raw coords: touched=true");
+    ASSERT_EQ_INT(TOUCH_MAX_X, (int)pt.x, "Max raw coords clamped to 319");
+    ASSERT_EQ_INT(TOUCH_MAX_Y, (int)pt.y, "Max raw coords clamped to 479");
+
+    data[0] = 0;
+    data[1] = 1;
+    data[2] = 0x05;
+    data[3] = 0x00;
+    data[4] = 0x08;
+    data[5] = 0x00;
+    touch_parse_raw(data, &pt);
+    ASSERT(pt.touched, "12-bit coords: touched=true");
+    ASSERT_EQ_INT(TOUCH_MAX_X, (int)pt.x, "12-bit x: (0x05 << 8) | 0x00 = 1280, clamped to 319");
+
+    data[0] = 0;
+    data[1] = 2;
+    touch_parse_raw(data, &pt);
+    ASSERT(!pt.touched, "data[1]=2 = too many touches, reject");
+
+    touch_parse_raw(NULL, &pt);
+    ASSERT(!pt.touched, "NULL data = no touch");
+
+    data[0] = 0;
+    data[1] = 1;
+    data[2] = 0x00;
+    data[3] = 0x00;
+    data[4] = 0x00;
+    data[5] = 0x00;
+    touch_parse_raw(data, &pt);
+    ASSERT(pt.touched, "Origin (0,0): touched=true");
+    ASSERT_EQ_INT(0, (int)pt.x, "Origin: x=0");
+    ASSERT_EQ_INT(0, (int)pt.y, "Origin: y=0");
+
+    data[0] = 0;
+    data[1] = 1;
+    data[2] = 0x01;
+    data[3] = 0x3F;
+    data[4] = 0x01;
+    data[5] = 0xDF;
+    touch_parse_raw(data, &pt);
+    ASSERT(pt.touched, "Mid-screen: touched=true");
+    ASSERT_EQ_INT(319, (int)pt.x, "Mid-screen: x=0x13F=319");
+    ASSERT_EQ_INT(479, (int)pt.y, "Mid-screen: y=0x1DF=479");
+
+    TEST_SUMMARY();
+}