Touch & Button Input Handling
Relevant source files
The following files were used as context for generating this wiki page:
Touch and button input handling manages physical interaction between the user and the ESP32 device. This system processes signals from physical buttons and touch-screen controllers to trigger device setup, pairing confirmation, and system resets.
The system supports multiple input types, including short presses, double presses, long-duration holds, and virtual taps via touch-sensitive displays. These inputs drive the state transitions of the device, primarily during the BLE provisioning and Wi-Fi setup phases.
Sources: board-port/esp32/main/button.c:113-115, board-port/esp32/README.md:104-106
Architecture and Components
The input system operates as a background task (button_task) that polls the state of the configured GPIO pin. It uses software debouncing to differentiate between intentional presses and electrical noise. For boards with displays, the system integrates touch controllers that bridge virtual taps to the existing button logic.
Key Components
- Button Task: A dedicated FreeRTOS task that monitors GPIO levels every 50ms.
- Callback System: A registration mechanism for handling short, double, and long press events.
- Touch Bridge: Logic that translates XPT2046 touch controller Z-axis pressure into button tap events.
- Press Claiming: A mechanism used primarily for Voice features to intercept raw press/release events before they are processed as taps or holds.
Sources: board-port/esp32/main/button.c:38-40, board-port/esp32/main/button.h:23-25, board-port/esp32/main/led_status.c:425-427
Input Processing Flow
The following diagram illustrates how the button_task processes GPIO state changes into distinct event types:
Sources: board-port/esp32/main/button.c:45-97
Input Event Definitions
The system distinguishes between three primary physical interactions based on timing thresholds.
| Event Type | Threshold | Primary Function |
|---|---|---|
| Short Press | 50ms - 1000ms | Confirm pairing; Reopen setup window |
| Double Press | 2 clicks < 400ms | Rescan (context dependent) |
| Long Press | > 5000ms | Factory reset; Unpair and forget Wi-Fi |
Sources: board-port/esp32/main/button.c:27-31, board-port/esp32/AGENTS.md:270-272
Hardware Integration
The input system adapts to different hardware configurations through Kconfig and specific board porting files.
Physical Buttons
The default configuration targets the BOOT button on ESP32 DevKit boards, typically mapped via CONFIG_HOMEHUB_BUTTON_GPIO. The input is configured with an internal pull-up resistor and triggers when the GPIO level is pulled to ground (active low).
Sources: board-port/esp32/main/button.c:33, board-port/esp32/main/button.c:105-108
Touch Screen Inputs
On display-equipped boards like the ESP32 CYD, the XPT2046 touch controller is monitored by the cyd_touch_task. This task reads the Z-pressure (Z1) via SPI. If the pressure exceeds a threshold (CYD_TOUCH_THRESHOLD), it triggers button_touch_tap(), which mimics a physical short press.
Sources: board-port/esp32/main/led_status.c:433-435, board-port/esp32/main/led_status.c:451-455
Hardware Configuration Example (CYD)
// XPT2046 touch controller on dedicated SPI bus
#define CYD_TOUCH_SCLK_GPIO 25
#define CYD_TOUCH_MOSI_GPIO 32
#define CYD_TOUCH_MISO_GPIO 39
#define CYD_TOUCH_CS_GPIO 33
#define CYD_TOUCH_CMD_Z1 0xB0
#define CYD_TOUCH_THRESHOLD 100
Sources: board-port/esp32/main/led_status.c:38-41, board-port/esp32/main/led_status.c:416-421
System Interactions
Input events are routed to the main application logic in app.c to drive system state.
Pairing Confirmation
During BLE pairing, the device enters a blue breathing LED state. The user must provide a short press or touch tap to confirm the pairing request. This interaction protects against unauthorized remote pairing by requiring physical presence.
Sources: board-port/esp32/main/app.c:1159-1165, board-port/esp32/README.md:104-106
Reset Procedure
A long press of 5 seconds triggers a setup reset. The application clears NVS credentials, disconnects active Wi-Fi and VM sessions, and restarts the device in an unpaired state.
Sources: board-port/esp32/main/app.c:1181-1183, board-port/esp32/main/app.c:470-475
API Reference
Function Signatures
bool button_init(button_cb short, button_cb double, button_cb long): Initializes the GPIO and starts the monitoring task.void button_set_press_cb(button_press_cb cb): Sets a high-priority intercept callback for raw press/release events.void button_touch_tap(void): Programmatic entry point to trigger a short press event from external controllers.
Sources: board-port/esp32/main/button.h:26-40
Configuration Parameters
| Macro | Value | Description |
|---|---|---|
POLL_MS | 50 | GPIO polling interval |
LONG_PRESS_MS | 5000 | Threshold for system reset |
DOUBLE_CLICK_MS | 400 | Maximum gap between double clicks |
BTN_GPIO | Configurable | The target input pin |
Sources: board-port/esp32/main/button.c:27-33
The touch and button input system ensures that critical operations—such as pairing and factory resets—remain under physical user control, providing a layer of security and a fallback for device recovery.