feat: support ESP32-S3 new board bring-up

components/control_plane/src/runtime/control_plane_key_input.c

@@ -74,10 +74,26 @@
 #define CONFIG_MULTIMODAL_PTT_BUTTON_PULLDOWN 0
 #endif
 
+#ifndef CONFIG_MULTIMODAL_PTT_BUTTON_PULLUP
+#define CONFIG_MULTIMODAL_PTT_BUTTON_PULLUP 0
+#endif
+
+#ifndef CONFIG_TQ_SLOT_SWITCH_PULLUP
+#define CONFIG_TQ_SLOT_SWITCH_PULLUP 0
+#endif
+
 #ifndef CONFIG_TQ_SLOT_SWITCH_PULLDOWN
 #define CONFIG_TQ_SLOT_SWITCH_PULLDOWN 0
 #endif
 
+#ifndef CONFIG_TQ_CALIBRATION_SWITCH_PULLUP
+#define CONFIG_TQ_CALIBRATION_SWITCH_PULLUP 0
+#endif
+
+#ifndef CONFIG_TQ_CALIBRATION_SWITCH_PULLDOWN
+#define CONFIG_TQ_CALIBRATION_SWITCH_PULLDOWN 0
+#endif
+
 static const char *TAG = "cp_key_input";
 
 typedef struct {
@@ -137,6 +153,20 @@ static const control_plane_key_config_t s_key_configs[] = {
         .enable_double_click = false,
 #endif
     },
+    {
+        .key_id = CONTROL_PLANE_KEY_ID_SW1,
+        .gpio_num = CONFIG_TQ_CALIBRATION_SWITCH_GPIO,
+        .active_level = CONFIG_TQ_CALIBRATION_SWITCH_ACTIVE_LEVEL,
+        .pullup_enabled = CONFIG_TQ_CALIBRATION_SWITCH_PULLUP,
+        .pulldown_enabled = CONFIG_TQ_CALIBRATION_SWITCH_PULLDOWN,
+        .debounce_ms = CONFIG_TQ_KEY_DEBOUNCE_INTERVAL_MS,
+        .long_press_ms = CONFIG_TQ_KEY_LONG_PRESS_MS,
+        .double_click_ms = CONFIG_TQ_KEY_DOUBLE_CLICK_MS,
+        .emit_press_release = true,
+        .enable_short_press = true,
+        .enable_long_press = true,
+        .enable_double_click = true,
+    },
     {
         .key_id = CONTROL_PLANE_KEY_ID_SW2,
         .gpio_num = CONFIG_TQ_SLOT_SWITCH_GPIO,

components/domain/src/calibration/domain_calibration_service.c

@@ -18,6 +18,7 @@ static const char *TAG = "domain_cal";
 #define DOMAIN_CALIBRATION_STEP_TIMEOUT_MS 1500
 #define DOMAIN_TURNTABLE_LIMIT_SEARCH_MAX_DEG 330.0f
 #define DOMAIN_TURNTABLE_LIMIT_TO_HOME_DEG    180.0f
+#define DOMAIN_TURNTABLE_RETURN_CHUNK_DEG     90.0f
 #define DOMAIN_TURNTABLE_HOME_ANGLE_DEG       0.0f
 
 static float clamp_positive_default(float value, float default_value)
@@ -110,6 +111,32 @@ static esp_err_t calibration_rotate_and_track(float delta, int rotate_speed_us,
     return domain_apply_rotation_delta(delta);
 }
 
+static esp_err_t calibration_return_from_limit(float search_direction,
+                                               int rotate_speed_us,
+                                               TickType_t start_tick,
+                                               TickType_t timeout_ticks)
+{
+    float remaining_deg = DOMAIN_TURNTABLE_LIMIT_TO_HOME_DEG;
+    while (remaining_deg > 0.0f) {
+        float chunk_deg = remaining_deg < DOMAIN_TURNTABLE_RETURN_CHUNK_DEG ?
+                          remaining_deg :
+                          DOMAIN_TURNTABLE_RETURN_CHUNK_DEG;
+        int remaining_timeout_ms = calibration_remaining_timeout_ms(start_tick, timeout_ticks);
+        if (remaining_timeout_ms <= 0) {
+            return ESP_ERR_TIMEOUT;
+        }
+
+        esp_err_t err = calibration_rotate_and_track(-search_direction * chunk_deg,
+                                                     rotate_speed_us,
+                                                     remaining_timeout_ms);
+        if (err != ESP_OK) {
+            return err;
+        }
+        remaining_deg -= chunk_deg;
+    }
+    return ESP_OK;
+}
+
 esp_err_t domain_calibrate_with_timeout(const domain_direction_calibration_t *config, int timeout_ms)
 {
     int effective_timeout_ms = timeout_ms > 0 ? timeout_ms : DOMAIN_CALIBRATION_TIMEOUT_MS;
@@ -157,17 +184,17 @@ esp_err_t domain_calibrate_with_timeout(const domain_direction_calibration_t *co
     int rotate_speed_us = domain_get_rotate_speed_us();
 
     ESP_LOGI(TAG,
-             "Limit calibration start step=%.1f sweep=%.1f search=%s",
+             "Boot motor test start: KEY1/SW1 search step=%.1f sweep=%.1f direction=%s",
              step_angle,
              max_sweep,
              calibration.search_clockwise ? "clockwise" : "counterclockwise");
 
     if (is_calibration_switch_active(&calibration)) {
-        ESP_LOGI(TAG, "Limit switch active at start; treating current position as 6 o'clock");
+        ESP_LOGI(TAG, "KEY1/SW1 pressed at motor-test start; treating current position as 6 o'clock");
-        int return_timeout_ms = calibration_step_timeout_ms(start_tick, timeout_ticks);
+        err = calibration_return_from_limit(direction,
-        err = calibration_rotate_and_track(-direction * DOMAIN_TURNTABLE_LIMIT_TO_HOME_DEG,
                                             rotate_speed_us,
-                                           return_timeout_ms);
+                                            start_tick,
+                                            timeout_ticks);
         if (err != ESP_OK) {
             domain_runtime_stepper_power_off();
             domain_direction_unlock_state();
@@ -206,11 +233,13 @@ esp_err_t domain_calibrate_with_timeout(const domain_direction_calibration_t *co
         }
 
         if (is_calibration_switch_active(&calibration)) {
-            ESP_LOGI(TAG, "Limit switch detected after %.1f deg; current position is 6 o'clock", total_sweep);
+            ESP_LOGI(TAG,
-            int return_timeout_ms = calibration_step_timeout_ms(start_tick, timeout_ticks);
+                     "KEY1/SW1 press detected after %.1f deg; current position is 6 o'clock",
-            err = calibration_rotate_and_track(-direction * DOMAIN_TURNTABLE_LIMIT_TO_HOME_DEG,
+                     total_sweep);
+            err = calibration_return_from_limit(direction,
                                                 rotate_speed_us,
-                                               return_timeout_ms);
+                                                start_tick,
+                                                timeout_ticks);
             if (err != ESP_OK) {
                 domain_runtime_stepper_power_off();
                 domain_direction_unlock_state();
@@ -226,6 +255,6 @@ esp_err_t domain_calibrate_with_timeout(const domain_direction_calibration_t *co
 
     domain_runtime_stepper_power_off();
     domain_direction_unlock_state();
-    ESP_LOGW(TAG, "Limit switch not found after %.1f deg search", total_sweep);
+    ESP_LOGW(TAG, "KEY1/SW1 not pressed during %.1f deg motor test", total_sweep);
     return ESP_ERR_TIMEOUT;
 }

components/domain/src/runtime/domain_runtime_adapters.c

@@ -761,7 +761,14 @@ esp_err_t domain_runtime_calibration_switch_init(void)
              config.active_level,
              config.pullup_enabled,
              config.pulldown_enabled);
-    return domain_runtime_digital_input_configure(&config);
+    esp_err_t err = domain_runtime_digital_input_configure(&config);
+    if (err == ESP_OK) {
+        ESP_LOGI(TAG,
+                 "KEY1/SW1 ready gpio=%d initial_state=%s",
+                 config.gpio_num,
+                 domain_runtime_digital_input_is_active(&config) ? "pressed" : "released");
+    }
+    return err;
 }
 
 bool domain_runtime_calibration_switch_is_active(void)

components/platform/src/lcd_direct.c

@@ -1,5 +1,5 @@
 /*
- * Direct ST7789 LCD backend.
+ * Direct ST7789P3 LCD backend.
  *
  * This backend owns the low-level panel initialization, a serialized render
  * loop, and a minimal presentation queue.
@@ -18,6 +18,7 @@
 
 #include "driver/gpio.h"
 #include "driver/spi_master.h"
+#include "esp_attr.h"
 #include "esp_check.h"
 #include "esp_lcd_panel_io.h"
 #include "esp_lcd_panel_ops.h"
@@ -29,11 +30,19 @@
 #include "sdkconfig.h"
 
 #define LCD_DIRECT_SPI_HOST SPI2_HOST
-#define LCD_DIRECT_WIDTH 320U
+#define LCD_DIRECT_NATIVE_WIDTH 240U
-#define LCD_DIRECT_HEIGHT 240U
+#define LCD_DIRECT_NATIVE_HEIGHT 320U
+#if CONFIG_TQ_SCREEN_SWAP_XY
+#define LCD_DIRECT_WIDTH LCD_DIRECT_NATIVE_HEIGHT
+#define LCD_DIRECT_HEIGHT LCD_DIRECT_NATIVE_WIDTH
+#else
+#define LCD_DIRECT_WIDTH LCD_DIRECT_NATIVE_WIDTH
+#define LCD_DIRECT_HEIGHT LCD_DIRECT_NATIVE_HEIGHT
+#endif
 #define LCD_DIRECT_ROWS_PER_TRANSFER 8U
 #define LCD_DIRECT_PIXELS_PER_TRANSFER (LCD_DIRECT_WIDTH * LCD_DIRECT_ROWS_PER_TRANSFER)
 #define LCD_DIRECT_PRESENTATION_WAIT_POLL_MS 20U
+#define LCD_DIRECT_TRANSFER_TIMEOUT_MS 100U
 
 #define LCD_CMD_MADCTL  0x36
 #define LCD_CMD_RAMCTRL 0xB0
@@ -88,6 +97,7 @@ static esp_lcd_panel_io_handle_t s_panel_io;
 static esp_lcd_panel_handle_t s_panel;
 static SemaphoreHandle_t s_lock;
 static SemaphoreHandle_t s_completion_sem;
+static SemaphoreHandle_t s_transfer_done_sem;
 static TaskHandle_t s_render_task;
 static bool s_initialized;
 static bool s_render_loop_running;
@@ -101,6 +111,21 @@ static lcd_direct_rle_run_t s_rle_file_chunk[128];
 
 static void lcd_direct_signal_completion(void);
 
+static bool IRAM_ATTR lcd_direct_on_color_trans_done(esp_lcd_panel_io_handle_t panel_io,
+                                                      esp_lcd_panel_io_event_data_t *event_data,
+                                                      void *user_ctx)
+{
+    (void)panel_io;
+    (void)event_data;
+    (void)user_ctx;
+
+    BaseType_t higher_priority_task_woken = pdFALSE;
+    if (s_transfer_done_sem != NULL) {
+        (void)xSemaphoreGiveFromISR(s_transfer_done_sem, &higher_priority_task_woken);
+    }
+    return higher_priority_task_woken == pdTRUE;
+}
+
 static uint16_t lcd_direct_swap_color(uint16_t color)
 {
 #if CONFIG_TQ_SCREEN_SWAP_COLOR_BYTES
@@ -113,12 +138,26 @@ static uint16_t lcd_direct_swap_color(uint16_t color)
 static esp_err_t lcd_direct_draw_rows(uint16_t row_start, uint16_t row_count)
 {
     ESP_RETURN_ON_FALSE(s_panel != NULL, ESP_ERR_INVALID_STATE, TAG, "panel is not ready");
-    return esp_lcd_panel_draw_bitmap(s_panel,
+    ESP_RETURN_ON_FALSE(s_transfer_done_sem != NULL,
+                        ESP_ERR_INVALID_STATE,
+                        TAG,
+                        "transfer semaphore is not ready");
+
+    (void)xSemaphoreTake(s_transfer_done_sem, 0);
+    ESP_RETURN_ON_ERROR(esp_lcd_panel_draw_bitmap(s_panel,
                                                   0,
                                                   row_start,
                                                   LCD_DIRECT_WIDTH,
                                                   row_start + row_count,
-                                     s_line_buffer);
+                                                  s_line_buffer),
+                        TAG,
+                        "panel draw failed");
+    ESP_RETURN_ON_FALSE(xSemaphoreTake(s_transfer_done_sem,
+                                       pdMS_TO_TICKS(LCD_DIRECT_TRANSFER_TIMEOUT_MS)) == pdTRUE,
+                        ESP_ERR_TIMEOUT,
+                        TAG,
+                        "panel transfer timed out");
+    return ESP_OK;
 }
 
 static esp_err_t lcd_direct_gpio_init(void)
@@ -168,7 +207,8 @@ static esp_err_t lcd_direct_panel_init(void)
         .lcd_cmd_bits = 8,
         .lcd_param_bits = 8,
         .spi_mode = 0,
-        .trans_queue_depth = 10,
+        .trans_queue_depth = 1,
+        .on_color_trans_done = lcd_direct_on_color_trans_done,
     };
     ESP_RETURN_ON_ERROR(esp_lcd_new_panel_io_spi((esp_lcd_spi_bus_handle_t)LCD_DIRECT_SPI_HOST,
                                                  &io_config,
@@ -871,13 +911,22 @@ esp_err_t lcd_direct_init_device(void)
     ESP_RETURN_ON_FALSE(s_lock != NULL, ESP_ERR_NO_MEM, TAG, "lock create failed");
     s_completion_sem = xSemaphoreCreateBinary();
     ESP_RETURN_ON_FALSE(s_completion_sem != NULL, ESP_ERR_NO_MEM, TAG, "completion sem create failed");
+    s_transfer_done_sem = xSemaphoreCreateBinary();
+    ESP_RETURN_ON_FALSE(s_transfer_done_sem != NULL,
+                        ESP_ERR_NO_MEM,
+                        TAG,
+                        "transfer sem create failed");
 
     ESP_RETURN_ON_ERROR(lcd_direct_gpio_init(), TAG, "gpio init failed");
     ESP_RETURN_ON_ERROR(lcd_direct_panel_init(), TAG, "esp_lcd panel init failed");
 
     s_initialized = true;
     ESP_LOGI(TAG,
-             "Direct LCD initialized (MOSI=%d SCLK=%d CS=%d DC=%d RST=%d BL=%d clock=%d)",
+             "Direct ST7789P3 LCD initialized (native=%ux%u logical=%ux%u MOSI=%d SCLK=%d CS=%d DC=%d RST=%d BL=%d clock=%d)",
+             (unsigned)LCD_DIRECT_NATIVE_WIDTH,
+             (unsigned)LCD_DIRECT_NATIVE_HEIGHT,
+             (unsigned)LCD_DIRECT_WIDTH,
+             (unsigned)LCD_DIRECT_HEIGHT,
              CONFIG_TQ_SCREEN_SPI_MOSI_GPIO,
              CONFIG_TQ_SCREEN_SPI_CLK_GPIO,
              CONFIG_TQ_SCREEN_SPI_CS_GPIO,

components/platform/src/lcd_direct_assets.c

@@ -12,15 +12,15 @@ static const lcd_direct_image_t s_default_image = {
 static const lcd_direct_image_t s_basic_face_frames[] = {
     {
         .path = LCD_ASSET_BASE_PATH "jichubiaoqing0.rle",
-        .run_count = 5893U,
+        .run_count = 5411U,
     },
     {
         .path = LCD_ASSET_BASE_PATH "jichubiaoqing1.rle",
-        .run_count = 4581U,
+        .run_count = 4099U,
     },
     {
         .path = LCD_ASSET_BASE_PATH "jichubiaoqing2.rle",
-        .run_count = 3651U,
+        .run_count = 3169U,
     },
 };
 

components/platform/src/platform_stepper_driver.c

@@ -324,7 +324,16 @@ esp_err_t platform_stepper_driver_init(void)
         .intr_type = GPIO_INTR_DISABLE
     };
 
-    return gpio_config(&io_conf);
+    esp_err_t err = gpio_config(&io_conf);
+    if (err == ESP_OK) {
+        ESP_LOGI(TAG,
+                 "Stepper ready IN1=%d IN2=%d IN3=%d IN4=%d",
+                 PLATFORM_STEPPER_IN1_PIN,
+                 PLATFORM_STEPPER_IN2_PIN,
+                 PLATFORM_STEPPER_IN3_PIN,
+                 PLATFORM_STEPPER_IN4_PIN);
+    }
+    return err;
 }
 
 esp_err_t platform_stepper_driver_rotate_angle_with_accel(float angle,

components/platform/src/wifi_portal_bridge.cpp

@@ -15,7 +15,12 @@
 #include "sdkconfig.h"
 #include "ssid_manager.h"
 #include "wifi_manager.h"
+#if __has_include("wifi_storage_hooks.h")
 #include "wifi_storage_hooks.h"
+#define WIFI_PORTAL_HAS_STORAGE_HOOKS 1
+#else
+#define WIFI_PORTAL_HAS_STORAGE_HOOKS 0
+#endif
 
 static const char *TAG = "wifi_portal";
 
@@ -49,6 +54,7 @@ static void install_wifi_storage_hooks(void)
         return;
     }
 
+#if WIFI_PORTAL_HAS_STORAGE_HOOKS
     const wifi_storage_hooks_t hooks = {
         .set_string = platform_storage_set_string,
         .get_string = platform_storage_get_string,
@@ -59,6 +65,9 @@ static void install_wifi_storage_hooks(void)
         .erase = platform_storage_erase,
     };
     wifi_storage_set_hooks(&hooks);
+#else
+    ESP_LOGW(TAG, "Wi-Fi storage hook API unavailable; using component default storage");
+#endif
     s_installed = true;
 }
 
@@ -198,6 +207,21 @@ static void seed_default_credentials(const char *ssid, const char *password)
         return;
     }
 
+    bool configured_ssid_saved = false;
+    for (const auto &item : manager.GetSsidList()) {
+        if (item.ssid == ssid) {
+            configured_ssid_saved = true;
+            break;
+        }
+    }
+    if (saved_count > 0U && !configured_ssid_saved) {
+        ESP_LOGI(TAG,
+                 "Configured seed SSID changed to \"%s\"; replacing %u stale credential candidate(s)",
+                 ssid,
+                 (unsigned)saved_count);
+        manager.Clear();
+    }
+
     manager.AddSsid(ssid, password != NULL ? password : "");
     ESP_LOGI(TAG,
              "Ensured configured Wi-Fi credentials for SSID \"%s\" with %u previous candidate(s)",

docs/architecture-and-flow-mermaid.md

@@ -205,7 +205,7 @@ flowchart LR
 
 ```mermaid
 flowchart TD
-    GPIO["GPIO edge interrupt\nPTT GPIO15 / SW2 GPIO45"]
+    GPIO["GPIO edge interrupt\nPTT GPIO3 / SW2 GPIO13"]
     IsrQueue["key IRQ queue"]
     KeyTask["cp_key_input\ndebounce and click state machine"]
     SystemQueue["system event queue"]

docs/firmware-pin-usage.md

@@ -1,9 +1,8 @@
 # Firmware Pin Usage
 
 This document summarizes the GPIOs used by the current firmware configuration.
-The primary source of truth is `sdkconfig.defaults`; generated `sdkconfig`
+The primary source of truth is `sdkconfig.defaults`. Signal direction is from
-differences are called out where they affect runtime behavior. Signal direction
+the ESP32-S3 MCU perspective.
-is from the ESP32-S3 MCU perspective.
 
 ## Configured Firmware Pins
 
@@ -11,37 +10,48 @@ is from the ESP32-S3 MCU perspective.
 | ---: | --- | --- | --- | --- | --- |
 | 1 | `CONFIG_MULTIMODAL_AUDIO_I2C_SDA_GPIO` | Bidirectional | Audio codec | ES8311 I2C SDA | I2C port 0, codec control bus |
 | 2 | `CONFIG_MULTIMODAL_AUDIO_I2C_SCL_GPIO` | Output | Audio codec | ES8311 I2C SCL | I2C port 0, codec control bus |
-| 3 | `CONFIG_TQ_SCREEN_RESET_PIN` | Output | LCD | ST7789 panel reset | Set high after GPIO init; `-1` disables hardware reset |
+| 3 | `CONFIG_MULTIMODAL_PTT_BUTTON_GPIO` | Input | Keys / multimodal | TTP223 touch output / PTT | Active-high, externally driven, no internal pull |
-| 4 | IO4 RMT control | Output | RMT control | RMT output control | Driven by platform IO effects RMT task |
+| 4 | IO4 RMT control | Output | RMT control | RMT output control | Reuses unconnected `TP_INT` on the 8-wire LCD setup |
-| 5 | IO5 PWM control | Output | PWM control | PWM output control | Driven by platform IO effects pulse task |
+| 5 | IO5 PWM control | Output | PWM control | PWM output control | Reuses unconnected `TP_SDA` on the 8-wire LCD setup |
-| 6 | `CONFIG_TQ_SCREEN_SPI_CS_GPIO` | Output | LCD | ST7789 SPI chip select | SPI2 host |
+| 7 | `CONFIG_TQ_SCREEN_BACKLIGHT_GPIO` | Output | LCD | LCD adapter backlight control | Active-high by default |
-| 7 | `CONFIG_TQ_SCREEN_DC_GPIO` | Output | LCD | ST7789 data/command select | Initialized low |
+| 8 | `CONFIG_TQ_SCREEN_SPI_CLK_GPIO` | Output | LCD | ST7789P3 SPI clock / SCK | SPI2 host, 20 MHz default |
-| 9 | `CONFIG_TQ_SCREEN_BACKLIGHT_GPIO` | Output | LCD | LCD backlight enable | Active-high by default |
+| 9 | `CONFIG_TQ_POWER_HOLD_GPIO` | Output | Power | Board power hold | Active-high by default |
-| 12 | `CONFIG_MULTIMODAL_AUDIO_PA_GPIO` | Output | Audio amplifier | PA enable / NS4150B control | Managed by codec GPIO interface |
+| 11 | `CONFIG_MULTIMODAL_AUDIO_PA_GPIO` | Output | Audio amplifier | PA enable | Managed by codec GPIO interface |
-| 13 | `CONFIG_TQ_STEPPER_IN1_GPIO` | Output | Turntable | ULN2003 stepper IN1 | Batched GPIO phase updates |
+| 12 | `CONFIG_TQ_CALIBRATION_SWITCH_GPIO` | Input | Turntable calibration | SW1 direction calibration microswitch | Active-low, external and internal pull-up |
-| 14 | `CONFIG_TQ_STEPPER_IN2_GPIO` | Output | Turntable | ULN2003 stepper IN2 | Batched GPIO phase updates |
+| 13 | `CONFIG_TQ_SLOT_SWITCH_GPIO` | Input | Slot / key input | SW2 slot-machine feature switch | Active-low, external and internal pull-up |
-| 15 | `CONFIG_MULTIMODAL_PTT_BUTTON_GPIO` | Input | Keys / multimodal | Push-to-talk button K2 | Active-low, internal pull-up enabled |
+| 15 | `CONFIG_TQ_SCREEN_SPI_CS_GPIO` | Output | LCD | ST7789P3 SPI chip select | SPI2 host |
-| 17 | `CONFIG_TQ_SCREEN_SPI_MOSI_GPIO` | Output | LCD | ST7789 SPI MOSI / SDA | SPI2 host |
+| 16 | `CONFIG_TQ_SCREEN_DC_GPIO` | Output | LCD | ST7789P3 data/command select | Initialized low |
-| 18 | `CONFIG_TQ_SCREEN_SPI_CLK_GPIO` | Output | LCD | ST7789 SPI clock / SCK | SPI2 host, 20 MHz default |
+| 17 | `CONFIG_TQ_SCREEN_RESET_PIN` | Output | LCD | ST7789P3 panel reset | Active-low reset; `-1` disables hardware reset |
-| 21 | `CONFIG_TQ_STEPPER_IN3_GPIO` | Output | Turntable | ULN2003 stepper IN3 | Batched GPIO phase updates |
+| 18 | `CONFIG_TQ_SCREEN_SPI_MOSI_GPIO` | Output | LCD | ST7789P3 SPI MOSI / SDA | SPI2 host |
+| 21 | `CONFIG_TQ_STEPPER_IN4_GPIO` | Output | Turntable | ULN2003 stepper IN4 | Batched GPIO phase updates |
 | 38 | `CONFIG_MULTIMODAL_AUDIO_I2S_MCLK_GPIO` | Output | Audio codec | ES8311 I2S MCLK | Enabled by `CONFIG_MULTIMODAL_AUDIO_USE_MCLK=y` |
 | 39 | `CONFIG_MULTIMODAL_AUDIO_I2S_BCLK_GPIO` | Output | Audio codec | ES8311 I2S BCLK / SCLK | I2S port 0 |
 | 40 | `CONFIG_MULTIMODAL_AUDIO_I2S_DOUT_GPIO` | Output | Audio codec | MCU PCM output to ES8311 DSDIN | I2S port 0 |
 | 41 | `CONFIG_MULTIMODAL_AUDIO_I2S_WS_GPIO` | Output | Audio codec | ES8311 I2S WS / LRCK | I2S port 0 |
 | 42 | `CONFIG_MULTIMODAL_AUDIO_I2S_DIN_GPIO` | Input | Audio codec | MCU PCM input from ES8311 ASDOUT | I2S port 0 |
-| 45 | `CONFIG_TQ_SLOT_SWITCH_GPIO` | Input | Slot / key input | SW2 slot-machine feature switch | Active-low, internal pull-up enabled |
+| 45 | `CONFIG_TQ_STEPPER_IN1_GPIO` | Output | Turntable | ULN2003 stepper IN1 | Batched GPIO phase updates |
-| 47 | `CONFIG_TQ_STEPPER_IN4_GPIO` | Output | Turntable | ULN2003 stepper IN4 | Batched GPIO phase updates |
+| 47 | `CONFIG_TQ_STEPPER_IN3_GPIO` | Output | Turntable | ULN2003 stepper IN3 | Batched GPIO phase updates |
-| 48 | `CONFIG_TQ_CALIBRATION_SWITCH_GPIO` | Input | Turntable calibration | SW1 direction calibration microswitch | Active-low, internal pull-up enabled |
+| 48 | `CONFIG_TQ_STEPPER_IN2_GPIO` | Output | Turntable | ULN2003 stepper IN2 | Batched GPIO phase updates |
 
 ## Disabled Or Not Connected In Defaults
 
 | Config | Value | Meaning |
 | --- | ---: | --- |
 | `CONFIG_TQ_SCREEN_SPI_MISO_GPIO` | `-1` | LCD MISO is not connected or not used. |
-| `CONFIG_TQ_POWER_HOLD_GPIO` | `-1` | Power-hold output is disabled. |
 | `CONFIG_TQ_SLOT_SWITCH_PULLDOWN` | unset | SW2 uses pull-up only. |
 | `CONFIG_TQ_CALIBRATION_SWITCH_PULLDOWN` | unset | Calibration switch uses pull-up only. |
-| `CONFIG_MULTIMODAL_PTT_BUTTON_PULLDOWN` | unset | PTT button uses pull-up only. |
+| `CONFIG_MULTIMODAL_PTT_BUTTON_PULLUP` | unset | TTP223 drives both levels. |
+| `CONFIG_MULTIMODAL_PTT_BUTTON_PULLDOWN` | unset | TTP223 drives both levels. |
+
+## Boot Hardware Test Profile
+
+The current board profile enables `CONFIG_TQ_BOOT_TURNTABLE_CALIBRATION_ENABLE`.
+After platform initialization, the stepper performs a bounded search for the
+active-low KEY1/SW1 input on GPIO12. Serial logs report the configured motor
+pins, the initial KEY1/SW1 state, switch detection, and the bounded no-switch
+result before Wi-Fi bootstrap continues. After boot, the managed key-input task
+keeps monitoring SW1 and logs its pressed, released, short-press, long-press,
+and double-click events.
 
 ## Console / Factory CLI
 
@@ -75,10 +85,9 @@ them to an active project feature.
 | GPIO / Net | Board function | Firmware status |
 | --- | --- | --- |
 | GPIO0 / K1 | Switch to GND, commonly boot/download related | Not consumed by application code |
-| GPIO8 | Unassigned | Not used |
+| GPIO6 / `TP_SCL` | Optional touch clock / reusable IO | Not connected by the current 8-wire LCD adapter |
-| GPIO10 / `SWING_PWM` | Swing coil control interface | No current firmware driver/config found |
+| GPIO10 / `Charge` | Charger status | No current firmware consumer found |
-| GPIO11 | Unassigned | Not used |
+| GPIO14 | Unassigned | Not used |
-| GPIO16 | Unassigned | Not used |
 | GPIO35 | Unassigned | Not used |
 | GPIO36 | Unassigned | Not used |
 | GPIO37 | Unassigned | Not used |
@@ -86,24 +95,6 @@ them to an active project feature.
 | GPIO19 / USB D- | USB | Board/system function; not configured by application code |
 | GPIO20 / USB D+ | USB | Board/system function; not configured by application code |
 
-## Current Generated `sdkconfig` Difference
-
-`sdkconfig.defaults` enables the key input task:
-
-```text
-CONFIG_TQ_KEY_INPUT_ENABLE=y
-```
-
-The current generated `sdkconfig` has it disabled:
-
-```text
-# CONFIG_TQ_KEY_INPUT_ENABLE is not set
-```
-
-This means the defaults describe the intended project pin usage, while the
-current generated build configuration may not actively start the interrupt key
-input task unless `sdkconfig` is regenerated or updated.
-
 ## Source Files
 
 - `sdkconfig.defaults`

docs/gpio-map.md

@@ -1,40 +1,40 @@
 # ESP32-S3 GPIO Map
 
-This document defines the reference GPIO assignments for the ESP32-S3 board,
+This document defines the reference GPIO assignments for the ESP32-S3 board
-current as of April 8, 2026. Signal direction is described from the MCU's
+from `SCH_招财猫0.3&商界0.2_2026-07-24.pdf`. Signal direction is described from
-perspective.
+the MCU's perspective.
 
 ## GPIO Table
 
-| U4 Pin | GPIO | Net | Direction | Connection / Function | Notes |
+| U5 Pin | GPIO | Net | Direction | Connection / Function | Notes |
 | --- | --- | --- | --- | --- | --- |
 | 1 | GND | GND | N/A | Ground reference | Ground reference |
 | 2 | 3V3 | 3V3 | Power | 3.3 V supply rail | Power rail |
 | 3 | EN/RST | EN | Input | Chip enable and reset input | Reset and enable |
-| 4 | GPIO4 | IO4_RMT | Output | RMT control | RMT output control |
+| 4 | GPIO4 | TP_INT | Bidirectional | Optional touch interrupt / reusable IO | Not connected by the 8-wire LCD adapter |
-| 5 | GPIO5 | IO5_PWM | Output | PWM control | PWM output control |
+| 5 | GPIO5 | TP_SDA | Bidirectional | Optional touch I2C SDA / reusable IO | Not connected by the 8-wire LCD adapter |
-| 6 | GPIO6 | ESP_IO6 | Output | Display interface CS | U9 |
+| 6 | GPIO6 | TP_SCL | Bidirectional | Optional touch I2C SCL / reusable IO | Not connected by the 8-wire LCD adapter |
-| 7 | GPIO7 | ESP_IO7 | Output | Display interface A0 (RS) | U9 |
+| 7 | GPIO7 | BLK | Output | LCD adapter backlight control | Active-high firmware default |
-| 8 | GPIO15 | ESP_IO15 | Input | Function key K2 | 10 kOhm pull-up to 3V3; pulled to GND when pressed |
+| 8 | GPIO15 | CS | Output | ST7789P3 SPI chip select | Active low |
-| 9 | GPIO16 | UNASSIGNED | N/A | No connection assigned | Reserved; no signal assigned |
+| 9 | GPIO16 | DC | Output | ST7789P3 data/command select | Also named A0 by the panel specification |
-| 10 | GPIO17 | ESP_IO17 | Output | Display interface SDA | U9 |
+| 10 | GPIO17 | RES | Output | ST7789P3 hardware reset | Active low |
-| 11 | GPIO18 | ESP_IO18 | Output | Display interface SCK | U9 |
+| 11 | GPIO18 | MOSI | Output | ST7789P3 SPI data / SDA | 4-line SPI write data |
-| 12 | GPIO8 | UNASSIGNED | N/A | No connection assigned | Reserved; no signal assigned |
+| 12 | GPIO8 | CLK / Swing | Output | ST7789P3 SPI clock | Do not drive the Swing function while the LCD is connected |
 | 13 | GPIO19 | ESP_D_N | Bidirectional | USB D- | Type-C |
 | 14 | GPIO20 | ESP_D_P | Bidirectional | USB D+ | Type-C |
-| 15 | GPIO3 | ESP_IO3 | Output | Display interface RST | U9 JLX240-00302 |
+| 15 | GPIO3 | touch | Input | TTP223 touch-button output / PTT | Active high |
 | 16 | GPIO46 | UNASSIGNED | N/A | No connection assigned | Reserved; no signal assigned |
-| 17 | GPIO9 | ESP_IO9 | Output | Display interface LEDA | U9 |
+| 17 | GPIO9 | Power | Output | Board power hold | Active high |
-| 18 | GPIO10 | SWING_PWM | Output | Swing coil control interface | J3 |
+| 18 | GPIO10 | Charge | Input | Charger status | Not consumed by current firmware |
-| 19 | GPIO11 | UNASSIGNED | N/A | No connection assigned | Reserved; no signal assigned |
+| 19 | GPIO11 | PA_CTRL | Output | Audio power-amplifier enable | Amplifier control |
-| 20 | GPIO12 | PA_CTRL | Output | NS4150B CTRL | Amplifier control |
+| 20 | GPIO12 | SW1 | Input | Turntable calibration microswitch | External 10 kOhm pull-up; active low |
-| 21 | GPIO13 | IN1 | Output | ULN2003 IN1 | Stepper motor phase control |
+| 21 | GPIO13 | SW2 | Input | Slot-machine feature switch | External 10 kOhm pull-up; active low |
-| 22 | GPIO14 | IN2 | Output | ULN2003 IN2 | Stepper motor phase control |
+| 22 | GPIO14 | UNASSIGNED | N/A | No connection assigned | Reserved; no signal assigned |
-| 23 | GPIO21 | IN3 | Output | ULN2003 IN3 | Stepper motor phase control |
+| 23 | GPIO21 | IN4 | Output | ULN2003 IN4 | Stepper motor phase control |
-| 24 | GPIO47 | IN4 | Output | ULN2003 IN4 | Stepper motor phase control |
+| 24 | GPIO47 | IN3 | Output | ULN2003 IN3 | Stepper motor phase control |
-| 25 | GPIO48 | SW_1 | Input | Microswitch interface for turntable calibration | External connector J7 |
+| 25 | GPIO48 | IN2 | Output | ULN2003 IN2 | Stepper motor phase control |
-| 26 | GPIO45 | SW_2 | Input | Microswitch interface for slot-machine feature | External connector J? |
+| 26 | GPIO45 | IN1 | Output | ULN2003 IN1 | Stepper motor phase control |
-| 27 | GPIO0 | UNLABELED | Input | K1 switch to GND | Purpose not annotated; commonly used for boot or download strapping |
+| 27 | GPIO0 | BOOT | Input | Boot/download switch | 10 kOhm pull-up to 3V3 |
 | 28 | GPIO35 | UNASSIGNED | N/A | No connection assigned | Reserved; no signal assigned |
 | 29 | GPIO36 | UNASSIGNED | N/A | No connection assigned | Reserved; no signal assigned |
 | 30 | GPIO37 | UNASSIGNED | N/A | No connection assigned | Reserved; no signal assigned |

docs/lcd-expressions.md

@@ -26,9 +26,12 @@ not expose domain expression IDs.
 ## Current Backend State
 
 The current LCD backend is `components/platform/src/lcd_direct.c`. It initializes
-the ST7789 panel directly through SPI using the `CONFIG_TQ_SCREEN_*` pin and
+the 240x320 ST7789P3 panel directly through SPI using the
-orientation settings, starts one render task, and accepts the existing platform
+`CONFIG_TQ_SCREEN_*` pin and orientation settings, starts one render task, and
-presentation requests.
+accepts the existing platform presentation requests. The 2026-07-24 board uses
+MOSI GPIO18, clock GPIO8, CS GPIO15, D/C GPIO16, reset GPIO17, and backlight
+GPIO7. The default X/Y swap exposes a 320x240 landscape drawing surface so the
+existing LCD assets retain their current geometry.
 
 The direct backend currently draws deterministic full-screen test patterns for
 presentation requests. Real image/resource playback is the next migration step.

main/Kconfig.projbuild

@@ -357,11 +357,11 @@ menu "Example Configuration"
 
         config TQ_SCREEN_RESET_PIN
             int "Panel reset GPIO (-1 to disable hardware reset)"
-            default 3
+            default 17
             range -1 48
             help
-                This board maps LCD_RST to IO3. Use -1 only when panel reset pin
+                The 2026-07-24 board maps the ST7789P3 RES signal to IO17.
-                is physically not connected.
+                Use -1 only when panel reset is physically not connected.
 
         config TQ_SCREEN_SPI_MISO_GPIO
             int "LCD SPI MISO GPIO (-1 to disable)"
@@ -372,35 +372,35 @@ menu "Example Configuration"
 
         config TQ_SCREEN_SPI_MOSI_GPIO
             int "LCD SPI MOSI GPIO"
-            default 17
+            default 18
             range 0 48
             help
                 LCD SPI MOSI GPIO.
 
         config TQ_SCREEN_SPI_CLK_GPIO
             int "LCD SPI clock GPIO"
-            default 18
+            default 8
             range 0 48
             help
                 LCD SPI clock GPIO.
 
         config TQ_SCREEN_SPI_CS_GPIO
             int "LCD SPI CS GPIO"
-            default 6
+            default 15
             range 0 48
             help
                 LCD SPI chip-select GPIO.
 
         config TQ_SCREEN_DC_GPIO
             int "LCD D/C GPIO"
-            default 7
+            default 16
             range 0 48
             help
                 LCD data/command GPIO.
 
         config TQ_SCREEN_BACKLIGHT_GPIO
             int "LCD backlight GPIO"
-            default 9
+            default 7
             range 0 48
             help
                 LCD backlight control GPIO.
@@ -435,11 +435,11 @@ menu "Example Configuration"
 
         config TQ_SLOT_SWITCH_GPIO
             int "Slot feature switch GPIO"
-            default 45
+            default 13
             range 0 48
             help
                 GPIO used for the slot machine feature switch.
-                Default from docs/gpio-map.md (SW_2 on IO45).
+                Default from docs/gpio-map.md (SW2 on IO13).
 
         config TQ_SLOT_SWITCH_ACTIVE_LEVEL
             int "Slot feature switch active level"
@@ -480,43 +480,43 @@ menu "Example Configuration"
 
         config TQ_BOOT_TURNTABLE_CALIBRATION_ENABLE
             bool "Run turntable calibration at boot"
-            default n
+            default y
             help
-                Keep disabled for staged module verification. The calibration
+                Run a bounded motor and KEY1/SW1 test before Wi-Fi bootstrap.
-                API remains available for key, voice, console, or system-event
+                The motor searches for the active-low switch and stops after
-                triggers after boot.
+                the configured calibration sweep if the switch is not pressed.
 
         config TQ_STEPPER_IN1_GPIO
             int "Turntable stepper IN1 GPIO"
-            default 13
+            default 45
             range 0 48
             help
                 GPIO connected to the turntable stepper driver IN1 input.
 
         config TQ_STEPPER_IN2_GPIO
             int "Turntable stepper IN2 GPIO"
-            default 14
+            default 48
             range 0 48
             help
                 GPIO connected to the turntable stepper driver IN2 input.
 
         config TQ_STEPPER_IN3_GPIO
             int "Turntable stepper IN3 GPIO"
-            default 21
+            default 47
             range 0 48
             help
                 GPIO connected to the turntable stepper driver IN3 input.
 
         config TQ_STEPPER_IN4_GPIO
             int "Turntable stepper IN4 GPIO"
-            default 47
+            default 21
             range 0 48
             help
                 GPIO connected to the turntable stepper driver IN4 input.
 
         config TQ_CALIBRATION_SWITCH_GPIO
             int "Direction calibration switch GPIO"
-            default 48
+            default 12
             range 0 48
             help
                 GPIO used for the turntable direction calibration switch.
@@ -546,10 +546,11 @@ menu "Example Configuration"
 
         config TQ_POWER_HOLD_GPIO
             int "Power hold GPIO (-1 to disable)"
-            default -1
+            default 9
             range -1 48
             help
-                GPIO used to keep board power enabled after boot. Set to -1
+                GPIO used to keep board power enabled after boot. The
+                2026-07-24 board maps the Power net to IO9. Set to -1 only
                 when no external power-hold circuit is connected.
 
         config TQ_POWER_HOLD_ACTIVE_LEVEL
@@ -840,31 +841,33 @@ menu "Example Configuration"
 
         config MULTIMODAL_PTT_BUTTON_GPIO
             int "Push-to-talk button GPIO"
-            default 15
+            default 3
             range 0 48
             help
                 GPIO used for the push-to-talk button.
-                Default from docs/gpio-map.md (function key K2 on GPIO15).
+                Default from docs/gpio-map.md (TTP223 touch output on IO3).
 
         config MULTIMODAL_PTT_BUTTON_ACTIVE_LEVEL
             int "Push-to-talk button active level"
-            default 0
+            default 1
             range 0 1
             help
                 Logic level that means the push-to-talk button is pressed.
-                Default from docs/gpio-map.md (function key K2 is active-low).
+                Default from docs/gpio-map.md (TTP223 output is active-high).
 
         config MULTIMODAL_PTT_BUTTON_PULLUP
             bool "Enable push-to-talk button pull-up"
-            default y
+            default n
             help
-                Enable the internal pull-up for the active-low push-to-talk button.
+                The TTP223 provides a driven digital output, so no internal
+                pull-up is required on the default board.
 
         config MULTIMODAL_PTT_BUTTON_PULLDOWN
             bool "Enable push-to-talk button pull-down"
             default n
             help
-                Leave disabled for the default active-low push-to-talk wiring.
+                The TTP223 provides a driven digital output, so no internal
+                pull-down is required on the default board.
 
         config MULTIMODAL_HEARTBEAT_INTERVAL_MS
             int "Heartbeat interval (ms)"
@@ -1177,9 +1180,9 @@ menu "Example Configuration"
 
             config MULTIMODAL_AUDIO_PA_GPIO
                 int "PA enable GPIO (-1 to disable)"
-                default 12
+                default 11
                 help
-                    Default from docs/gpio-map.md (PA_CTRL on IO12).
+                    Default from docs/gpio-map.md (PA_CTRL on IO11).
 
             config MULTIMODAL_AUDIO_I2S_DMA_DESC_NUM
                 int "I2S DMA descriptor count"

sdkconfig.defaults

@@ -104,8 +104,8 @@ CONFIG_MDNS_MEMORY_ALLOC_SPIRAM=y
 
 CONFIG_MULTIMODAL_DEVICE_ID=""
 CONFIG_MULTIMODAL_SERIAL_NUMBER=""
-CONFIG_MULTIMODAL_WIFI_SSID="csy2"
+CONFIG_MULTIMODAL_WIFI_SSID="TalkingQ_Guest"
-CONFIG_MULTIMODAL_WIFI_PASSWORD="csy19881023"
+CONFIG_MULTIMODAL_WIFI_PASSWORD="66668888"
 CONFIG_ESPTOOLPY_MONITOR_BAUD=921600
 CONFIG_ESP_CONSOLE_UART_BAUDRATE=921600
 CONFIG_MULTIMODAL_DEVICE_TOKEN_URL="https://gz.api.talkingq.com/token/api/device/token"
@@ -122,9 +122,9 @@ CONFIG_ENABLE_MULTIMODAL_INTERACTION=y
 # CONFIG_MULTIMODAL_AUTH_BYPASS_TOKEN_SERVICE is not set
 CONFIG_AUTH_V2_ENABLE=y
 CONFIG_MULTIMODAL_UPSTREAM_MODE="push2talk"
-CONFIG_MULTIMODAL_PTT_BUTTON_GPIO=15
+CONFIG_MULTIMODAL_PTT_BUTTON_GPIO=3
-CONFIG_MULTIMODAL_PTT_BUTTON_ACTIVE_LEVEL=0
+CONFIG_MULTIMODAL_PTT_BUTTON_ACTIVE_LEVEL=1
-CONFIG_MULTIMODAL_PTT_BUTTON_PULLUP=y
+# CONFIG_MULTIMODAL_PTT_BUTTON_PULLUP is not set
 # CONFIG_MULTIMODAL_PTT_BUTTON_PULLDOWN is not set
 # CONFIG_MULTIMODAL_AUDIO_CHANNEL_PROBE_ON_INIT is not set
 CONFIG_MULTIMODAL_HEARTBEAT_INTERVAL_MS=50000
@@ -202,7 +202,7 @@ CONFIG_MBEDTLS_SSL_PROTO_TLS1_2=y
 # CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE is not set
 CONFIG_MBEDTLS_CERTIFICATE_BUNDLE=y
 CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_FULL=y
-# Screen parameters aligned with validated reference project
+# ZJY200-2432KHWIG25DCT ST7789P3 panel on the 2026-07-24 board
 # CONFIG_TQ_SCREEN_COLOR_ORDER_BGR is not set
 CONFIG_TQ_SCREEN_INVERT_COLOR=y
 CONFIG_TQ_SCREEN_SWAP_COLOR_BYTES=y
@@ -211,27 +211,29 @@ CONFIG_TQ_SCREEN_MIRROR_X=y
 CONFIG_TQ_SCREEN_SWAP_XY=y
 CONFIG_TQ_SCREEN_X_GAP=0
 CONFIG_TQ_SCREEN_Y_GAP=0
-CONFIG_TQ_SCREEN_RESET_PIN=3
+CONFIG_TQ_SCREEN_RESET_PIN=17
 CONFIG_TQ_SCREEN_SPI_MISO_GPIO=-1
-CONFIG_TQ_SCREEN_SPI_MOSI_GPIO=17
+CONFIG_TQ_SCREEN_SPI_MOSI_GPIO=18
-CONFIG_TQ_SCREEN_SPI_CLK_GPIO=18
+CONFIG_TQ_SCREEN_SPI_CLK_GPIO=8
-CONFIG_TQ_SCREEN_SPI_CS_GPIO=6
+CONFIG_TQ_SCREEN_SPI_CS_GPIO=15
-CONFIG_TQ_SCREEN_DC_GPIO=7
+CONFIG_TQ_SCREEN_DC_GPIO=16
-CONFIG_TQ_SCREEN_BACKLIGHT_GPIO=9
+CONFIG_TQ_SCREEN_BACKLIGHT_GPIO=7
 CONFIG_TQ_SCREEN_SPI_PIXEL_CLOCK_HZ=20000000
-CONFIG_TQ_SLOT_SWITCH_GPIO=45
+CONFIG_TQ_SLOT_SWITCH_GPIO=13
 CONFIG_TQ_SLOT_SWITCH_ACTIVE_LEVEL=0
 CONFIG_TQ_SLOT_SWITCH_PULLUP=y
 # CONFIG_TQ_SLOT_SWITCH_PULLDOWN is not set
-CONFIG_TQ_BOOT_TURNTABLE_CALIBRATION_ENABLE=n
+CONFIG_TQ_BOOT_TURNTABLE_CALIBRATION_ENABLE=y
-CONFIG_TQ_STEPPER_IN1_GPIO=13
+CONFIG_TQ_STEPPER_IN1_GPIO=45
-CONFIG_TQ_STEPPER_IN2_GPIO=14
+CONFIG_TQ_STEPPER_IN2_GPIO=48
-CONFIG_TQ_STEPPER_IN3_GPIO=21
+CONFIG_TQ_STEPPER_IN3_GPIO=47
-CONFIG_TQ_STEPPER_IN4_GPIO=47
+CONFIG_TQ_STEPPER_IN4_GPIO=21
-CONFIG_TQ_CALIBRATION_SWITCH_GPIO=48
+CONFIG_TQ_CALIBRATION_SWITCH_GPIO=12
 CONFIG_TQ_CALIBRATION_SWITCH_ACTIVE_LEVEL=0
 CONFIG_TQ_CALIBRATION_SWITCH_PULLUP=y
 # CONFIG_TQ_CALIBRATION_SWITCH_PULLDOWN is not set
 # CONFIG_TQ_SCREEN_COLOR_AUTOTEST is not set
 CONFIG_TQ_SCREEN_COLOR_AUTOTEST_INTERVAL_MS=3000
-CONFIG_MULTIMODAL_AUDIO_PA_GPIO=12
+CONFIG_TQ_POWER_HOLD_GPIO=9
+CONFIG_TQ_POWER_HOLD_ACTIVE_LEVEL=1
+CONFIG_MULTIMODAL_AUDIO_PA_GPIO=11