chenjintao/lucky-cat
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: support ESP32-S3 new board bring-up

Browse Source
This commit is contained in:
wangtianyang
2026-08-03 14:06:06 +08:00
parent 404389f1ea
commit d5409ea4e3
16 changed files with 297 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture-and-flow-mermaid.md
+1 -1
View File
@@ -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
+34 -43
View File
@@ -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`
differences are called out where they affect runtime behavior. Signal direction
is from the ESP32-S3 MCU perspective.
The primary source of truth is `sdkconfig.defaults`. Signal direction 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 |
| 4 | IO4 RMT control | Output | RMT control | RMT output control | Driven by platform IO effects RMT task |
| 5 | IO5 PWM control | Output | PWM control | PWM output control | Driven by platform IO effects pulse task |
| 6 | `CONFIG_TQ_SCREEN_SPI_CS_GPIO` | Output | LCD | ST7789 SPI chip select | SPI2 host |
| 7 | `CONFIG_TQ_SCREEN_DC_GPIO` | Output | LCD | ST7789 data/command select | Initialized low |
| 9 | `CONFIG_TQ_SCREEN_BACKLIGHT_GPIO` | Output | LCD | LCD backlight enable | Active-high by default |
| 12 | `CONFIG_MULTIMODAL_AUDIO_PA_GPIO` | Output | Audio amplifier | PA enable / NS4150B control | Managed by codec GPIO interface |
| 13 | `CONFIG_TQ_STEPPER_IN1_GPIO` | Output | Turntable | ULN2003 stepper IN1 | Batched GPIO phase updates |
| 14 | `CONFIG_TQ_STEPPER_IN2_GPIO` | Output | Turntable | ULN2003 stepper IN2 | Batched GPIO phase updates |
| 15 | `CONFIG_MULTIMODAL_PTT_BUTTON_GPIO` | Input | Keys / multimodal | Push-to-talk button K2 | Active-low, internal pull-up enabled |
| 17 | `CONFIG_TQ_SCREEN_SPI_MOSI_GPIO` | Output | LCD | ST7789 SPI MOSI / SDA | SPI2 host |
| 18 | `CONFIG_TQ_SCREEN_SPI_CLK_GPIO` | Output | LCD | ST7789 SPI clock / SCK | SPI2 host, 20 MHz default |
| 21 | `CONFIG_TQ_STEPPER_IN3_GPIO` | Output | Turntable | ULN2003 stepper IN3 | Batched GPIO phase updates |
| 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 | Reuses unconnected `TP_INT` on the 8-wire LCD setup |
| 5 | IO5 PWM control | Output | PWM control | PWM output control | Reuses unconnected `TP_SDA` on the 8-wire LCD setup |
| 7 | `CONFIG_TQ_SCREEN_BACKLIGHT_GPIO` | Output | LCD | LCD adapter backlight control | Active-high by default |
| 8 | `CONFIG_TQ_SCREEN_SPI_CLK_GPIO` | Output | LCD | ST7789P3 SPI clock / SCK | SPI2 host, 20 MHz default |
| 9 | `CONFIG_TQ_POWER_HOLD_GPIO` | Output | Power | Board power hold | Active-high by default |
| 11 | `CONFIG_MULTIMODAL_AUDIO_PA_GPIO` | Output | Audio amplifier | PA enable | Managed by codec GPIO interface |
| 12 | `CONFIG_TQ_CALIBRATION_SWITCH_GPIO` | Input | Turntable calibration | SW1 direction calibration microswitch | Active-low, external and internal pull-up |
| 13 | `CONFIG_TQ_SLOT_SWITCH_GPIO` | Input | Slot / key input | SW2 slot-machine feature switch | Active-low, external and internal pull-up |
| 15 | `CONFIG_TQ_SCREEN_SPI_CS_GPIO` | Output | LCD | ST7789P3 SPI chip select | SPI2 host |
| 16 | `CONFIG_TQ_SCREEN_DC_GPIO` | Output | LCD | ST7789P3 data/command select | Initialized low |
| 17 | `CONFIG_TQ_SCREEN_RESET_PIN` | Output | LCD | ST7789P3 panel reset | Active-low reset; `-1` disables hardware reset |
| 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 |
| 47 | `CONFIG_TQ_STEPPER_IN4_GPIO` | Output | Turntable | ULN2003 stepper IN4 | Batched GPIO phase updates |
| 48 | `CONFIG_TQ_CALIBRATION_SWITCH_GPIO` | Input | Turntable calibration | SW1 direction calibration microswitch | 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_IN3_GPIO` | Output | Turntable | ULN2003 stepper IN3 | Batched GPIO phase updates |
| 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 |
| GPIO10 / `SWING_PWM` | Swing coil control interface | No current firmware driver/config found |
| GPIO11 | Unassigned | Not used |
| GPIO16 | Unassigned | Not used |
| GPIO6 / `TP_SCL` | Optional touch clock / reusable IO | Not connected by the current 8-wire LCD adapter |
| GPIO10 / `Charge` | Charger status | No current firmware consumer found |
| GPIO14 | 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
+25 -25
View File
@@ -1,40 +1,40 @@
# ESP32-S3 GPIO Map
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
perspective.
This document defines the reference GPIO assignments for the ESP32-S3 board
from `SCH_招财猫0.3&商界0.2_2026-07-24.pdf`. Signal direction is described from
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 |
| 5 | GPIO5 | IO5_PWM | Output | PWM control | PWM output control |
| 6 | GPIO6 | ESP_IO6 | Output | Display interface CS | U9 |
| 7 | GPIO7 | ESP_IO7 | Output | Display interface A0 (RS) | U9 |
| 8 | GPIO15 | ESP_IO15 | Input | Function key K2 | 10 kOhm pull-up to 3V3; pulled to GND when pressed |
| 9 | GPIO16 | UNASSIGNED | N/A | No connection assigned | Reserved; no signal assigned |
| 10 | GPIO17 | ESP_IO17 | Output | Display interface SDA | U9 |
| 11 | GPIO18 | ESP_IO18 | Output | Display interface SCK | U9 |
| 12 | GPIO8 | UNASSIGNED | N/A | No connection assigned | Reserved; no signal assigned |
| 4 | GPIO4 | TP_INT | Bidirectional | Optional touch interrupt / reusable IO | Not connected by the 8-wire LCD adapter |
| 5 | GPIO5 | TP_SDA | Bidirectional | Optional touch I2C SDA / reusable IO | Not connected by the 8-wire LCD adapter |
| 6 | GPIO6 | TP_SCL | Bidirectional | Optional touch I2C SCL / reusable IO | Not connected by the 8-wire LCD adapter |
| 7 | GPIO7 | BLK | Output | LCD adapter backlight control | Active-high firmware default |
| 8 | GPIO15 | CS | Output | ST7789P3 SPI chip select | Active low |
| 9 | GPIO16 | DC | Output | ST7789P3 data/command select | Also named A0 by the panel specification |
| 10 | GPIO17 | RES | Output | ST7789P3 hardware reset | Active low |
| 11 | GPIO18 | MOSI | Output | ST7789P3 SPI data / SDA | 4-line SPI write data |
| 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 |
| 18 | GPIO10 | SWING_PWM | Output | Swing coil control interface | J3 |
| 19 | GPIO11 | UNASSIGNED | N/A | No connection assigned | Reserved; no signal assigned |
| 20 | GPIO12 | PA_CTRL | Output | NS4150B CTRL | Amplifier control |
| 21 | GPIO13 | IN1 | Output | ULN2003 IN1 | Stepper motor phase control |
| 22 | GPIO14 | IN2 | Output | ULN2003 IN2 | Stepper motor phase control |
| 23 | GPIO21 | IN3 | Output | ULN2003 IN3 | Stepper motor phase control |
| 24 | GPIO47 | IN4 | Output | ULN2003 IN4 | Stepper motor phase control |
| 25 | GPIO48 | SW_1 | Input | Microswitch interface for turntable calibration | External connector J7 |
| 26 | GPIO45 | SW_2 | Input | Microswitch interface for slot-machine feature | External connector J? |
| 27 | GPIO0 | UNLABELED | Input | K1 switch to GND | Purpose not annotated; commonly used for boot or download strapping |
| 17 | GPIO9 | Power | Output | Board power hold | Active high |
| 18 | GPIO10 | Charge | Input | Charger status | Not consumed by current firmware |
| 19 | GPIO11 | PA_CTRL | Output | Audio power-amplifier enable | Amplifier control |
| 20 | GPIO12 | SW1 | Input | Turntable calibration microswitch | External 10 kOhm pull-up; active low |
| 21 | GPIO13 | SW2 | Input | Slot-machine feature switch | External 10 kOhm pull-up; active low |
| 22 | GPIO14 | UNASSIGNED | N/A | No connection assigned | Reserved; no signal assigned |
| 23 | GPIO21 | IN4 | Output | ULN2003 IN4 | Stepper motor phase control |
| 24 | GPIO47 | IN3 | Output | ULN2003 IN3 | Stepper motor phase control |
| 25 | GPIO48 | IN2 | Output | ULN2003 IN2 | Stepper motor phase control |
| 26 | GPIO45 | IN1 | Output | ULN2003 IN1 | Stepper motor phase control |
| 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
+6 -3
View File
@@ -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
orientation settings, starts one render task, and accepts the existing platform
presentation requests.
the 240x320 ST7789P3 panel directly through SPI using the
`CONFIG_TQ_SCREEN_*` pin and orientation settings, starts one render task, and
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.