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

feat(platform): adapt GPIO configuration to new board

Browse Source
This commit is contained in:
chenjintao
2026-10-23 15:37:22 +08:00
parent 6d103938ab
commit aede687dc9
10 changed files with 801 additions and 421 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/firmware-pin-usage.md
+76 -90
View File
@@ -1,115 +1,101 @@
# Firmware Pin Usage
This document summarizes the GPIOs used by the current firmware configuration.
The primary source of truth is `sdkconfig.defaults`. Signal direction is from
the ESP32-S3 MCU perspective.
The current profile targets the new board in `schematic/电机-马达方案.pdf`
(upper board 2026-10-19; lower board 2026-10-12). Defaults are declared in
`sdkconfig.defaults` and `main/Kconfig.projbuild`; saved local settings in
`sdkconfig` must match. Directions below are from the ESP32-S3 perspective.
Existing GPIOs, active levels, pull resistors, and backlight polarity are on one
`menuconfig` page: `TQ Cat Configuration -> Board Hardware Configuration (GPIO)`.
Feature switches and behavior parameters remain in their original menus.
No new GPIO option has been added for full-charge sensing or the rocker motor.
## Configured Firmware Pins
| GPIO | Signal / Config | Direction | Subsystem | Runtime use | Electrical / logic notes |
| ---: | --- | --- | --- | --- | --- |
| 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 |
| 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 |
| 6 | `CONFIG_TQ_SLOT_SWITCH_GPIO` | Input | Slot / key input | Rocker microswitch / original SW2 function | Uses the unconnected `TP_SCL` contact; active-low with internal pull-up |
| 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_BATTERY_ADC_GPIO` | Analog input | Battery | Battery voltage through 100 kOhm / 100 kOhm divider | ADC1 input; do not configure as a power-hold output |
| 10 | `CONFIG_TQ_BATTERY_CHARGE_GPIO` | Input | Battery charger | TP4057 charge status | Active-low, internal pull-up enabled |
| 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 | Button 1 / SW1 direction calibration | Active-low, external and internal pull-up |
| 13 | `CONFIG_MULTIMODAL_PTT_BUTTON_GPIO` | Input | Keys / multimodal | Button 2 / K2 push-to-talk | Active-low, external and internal pull-up |
| 14 | `CONFIG_TQ_RESET_BUTTON_GPIO` | Input when enabled | Optional reset key | Hold to clear saved Wi-Fi credentials and restart | Disabled by default; active-low with internal pull-up when enabled |
| 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_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 |
| GPIO | Config | Direction | Function / Notes |
| ---: | --- | --- | --- |
| 1 | `CONFIG_MULTIMODAL_AUDIO_I2C_SDA_GPIO` | Bidirectional | ES8311 control SDA |
| 2 | `CONFIG_MULTIMODAL_AUDIO_I2C_SCL_GPIO` | Output | ES8311 control SCL |
| 4 | `CONFIG_TQ_SCREEN_BACKLIGHT_GPIO` | Output | LCD BLK, active high; initial brightness 100%, validate dimming separately |
| 5 | `CONFIG_TQ_SCREEN_SPI_CS_GPIO` | Output | LCD CS |
| 6 | `CONFIG_TQ_SCREEN_DC_GPIO` | Output | LCD data/command; no old switch flying wire |
| 7 | `CONFIG_TQ_SCREEN_RESET_PIN` | Output | LCD reset, active low |
| 9 | `CONFIG_MULTIMODAL_AUDIO_PA_GPIO` | Output | Audio amplifier enable |
| 11 | `CONFIG_TQ_CALIBRATION_SWITCH_GPIO` | Input | Switch 1 / calibration, active low with pull-up |
| 12 | `CONFIG_TQ_SLOT_SWITCH_GPIO` | Input | Switch 2 / slot trigger, active low with pull-up |
| 13 | `CONFIG_MULTIMODAL_PTT_BUTTON_GPIO` | Input | TTP223 touch output / PTT; previous active-low/pull-up settings retained pending measured polarity |
| 14 | `CONFIG_TQ_STEPPER_IN1_GPIO` | Output | ULN2003 IN1; must not also be configured as Wi-Fi reset |
| 15 | `CONFIG_TQ_SCREEN_SPI_MOSI_GPIO` | Output | LCD SDA is SPI MOSI, not I2C |
| 16 | `CONFIG_TQ_SCREEN_SPI_CLK_GPIO` | Output | LCD SCL is SPI SCK; saved defaults use 40 MHz, not a measured performance guarantee |
| 17 | `CONFIG_TQ_BATTERY_ADC_GPIO` | Analog input | ADC2 channel 6; divider via Q5/Q6; R6/R11=100 kOhm each |
| 18 | `CONFIG_TQ_BATTERY_CHARGE_GPIO` | Input | TP4056 CHRG# via Q7; retain active low, verify on hardware |
| 21 | `CONFIG_TQ_STEPPER_IN2_GPIO` | Output | ULN2003 IN2 |
| 38 | `CONFIG_MULTIMODAL_AUDIO_I2S_MCLK_GPIO` | Output | ES8311 MCLK |
| 39 | `CONFIG_MULTIMODAL_AUDIO_I2S_BCLK_GPIO` | Output | ES8311 SCLK |
| 40 | `CONFIG_MULTIMODAL_AUDIO_I2S_DOUT_GPIO` | Output | ES8311 DSDIN |
| 41 | `CONFIG_MULTIMODAL_AUDIO_I2S_WS_GPIO` | Output | ES8311 LRCK |
| 42 | `CONFIG_MULTIMODAL_AUDIO_I2S_DIN_GPIO` | Input | ES8311 ASDOUT |
| 47 | `CONFIG_TQ_STEPPER_IN3_GPIO` | Output | ULN2003 IN3 |
| 48 | `CONFIG_TQ_STEPPER_IN4_GPIO` | Output | ULN2003 IN4 |
The rocker microswitch wiring is `CN2 pin 3 (TP_SCL/GPIO6) -> normally-open
switch -> GND` (`CN2 pin 11` is a local ground option). The switch must not be
connected to 3.3 V. GPIO6 cannot be used as a touch I2C clock while this wiring
is installed.
The old `platform_io_effects_init()` startup call has been removed: its GPIO4
RMT and GPIO5 pulse workers conflict with new LCD BLK/CS. The old implementation
is retained as source, but no startup path calls it. GPIO10 motor control has
not been enabled as a replacement.
## 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_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 | Button 2 uses pull-up only. |
| `CONFIG_TQ_POWER_HOLD_GPIO` | `-1` | Legacy board power-hold output is disabled because GPIO9 is the battery ADC input. |
## 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
The factory CLI uses `UART_NUM_0` through the ESP-IDF UART driver without
project-specific GPIO remapping. The board reference map routes the debug UART
to the `RXD0` / `TXD0` nets on connector `J2`.
| Interface | Direction | Use |
| Config / Pin | Value / Status | Meaning |
| --- | --- | --- |
| UART0 RX | Input | Factory CLI input and serial monitor input |
| UART0 TX | Output | ESP log output, factory CLI replies, serial monitor output |
| `CONFIG_TQ_SCREEN_SPI_MISO_GPIO` | -1 | LCD readback is not connected |
| `CONFIG_TQ_POWER_HOLD_GPIO` | -1 | No MCU power-hold net on the new board |
| `CONFIG_TQ_RESET_BUTTON_ENABLE` | Disabled | The old optional reset default GPIO14 now belongs to stepper IN1; configure separate physical wiring before enabling |
| `CONFIG_TQ_BATTERY_SHUTDOWN_WAKE_BUTTON_GPIO` | -1 | No additional deep-sleep wake button |
| GPIO8 / 充满检测 | Not consumed | Full-charge input exists on hardware; no option/driver added |
| GPIO10 / 马达控制 | Not consumed | Rocker-motor gate held off by external R30 pull-down; no new option/driver added |
| GPIO3 / 35 / 36 / 37 / 45 / 46 | NC on schematic | Do not infer arbitrary availability from NC |
## External Memory Pins
Mechanical switches use pull-up only. PTT and charger active levels are retained
from the previous configuration and require actual idle/active measurements.
Battery full-charge prompts still use voltage/percentage/time inference rather
than GPIO8. ADC divider gain/offset remain unchanged pending VBAT measurements.
The project enables external PSRAM in octal mode. These are generated ESP-IDF
memory-interface settings in `sdkconfig`, not normal application GPIOs.
## Boot Calibration And Sleep
| GPIO | Config | Direction | Use | Notes |
| ---: | --- | --- | --- | --- |
| 26 | `CONFIG_SPIRAM_CS_IO` / `CONFIG_DEFAULT_PSRAM_CS_IO` | Memory bus | PSRAM CS | Reserved by ESP32-S3 memory interface |
| 30 | `CONFIG_SPIRAM_CLK_IO` / `CONFIG_DEFAULT_PSRAM_CLK_IO` | Memory bus | PSRAM clock | Reserved by ESP32-S3 memory interface |
`CONFIG_TQ_BOOT_TURNTABLE_CALIBRATION_ENABLE` remains enabled. Boot searches for
switch 1 on GPIO11 with IN1/IN2/IN3/IN4 = 14/21/47/48. Verify motor direction,
mechanical limits and bounded stop on hardware.
Flash pins are controlled by the ESP32-S3 flash interface and are not assigned
by project GPIO configuration.
Charge-state edge interrupts and low-active deep-sleep wake both follow
`CONFIG_TQ_BATTERY_CHARGE_GPIO=18`. Verify charger insertion/removal and wake
behavior after changing the board.
## Board Nets Present But Not Used By Current Firmware
## System Interfaces
These nets exist in `docs/gpio-map.md`, but the current firmware does not assign
them to an active project feature.
USB D-/D+ remain GPIO19/20. UART0 uses default RXD0/TXD0 without application
remapping; connector CN5 labels are TX/RX from the opposite endpoint's
perspective. BOOT remains GPIO0 and is not an application input.
| GPIO / Net | Board function | Firmware status |
| --- | --- | --- |
| GPIO0 / K1 | Switch to GND, commonly boot/download related | Not consumed by application code |
| GPIO3 / `touch` | TTP223 touch output | Present on the board but not consumed by the current input policy |
| GPIO14 | Unassigned | Not used |
| GPIO35 | Unassigned | Not used |
| GPIO36 | Unassigned | Not used |
| GPIO37 | Unassigned | Not used |
| GPIO46 | Unassigned | Not used |
| GPIO19 / USB D- | USB | Board/system function; not configured by application code |
| GPIO20 / USB D+ | USB | Board/system function; not configured by application code |
The octal PSRAM/Flash interfaces remain owned by ESP-IDF and the module.
Generated memory settings such as PSRAM CS=26 and CLK=30 are not application
GPIO assignments. Do not repurpose memory pins from this table.
## Source Files
- `sdkconfig.defaults`
- `sdkconfig`
- `main/Kconfig.projbuild`
- `docs/gpio-map.md`
- `main/Kconfig.projbuild`, `sdkconfig.defaults`, local `sdkconfig`
- `docs/gpio-map.md`, `docs/gpio-board-adaptation.zh-CN.md`
- `components/platform/src/runtime/platform_core_runtime.c`
- `components/platform/src/lcd_direct.c`
- `components/platform/src/platform_stepper_driver.c`
- `components/platform/src/platform_battery_driver.c`
- `components/platform/src/multimodal/audio_pipeline/audio_pipeline_codec_impl.c`
- `components/control_plane/src/runtime/control_plane_key_input.c`
- `components/platform/src/platform_console_driver.c`
## Validation (2026-10-23)
ESP-IDF 5.5.4 build and all five LCD regression scripts passed. The production
battery initializer passed host tests for ADC2/ADC1 propagation, idempotence,
bounded lock failure, cleanup and retry (`tools/test_battery_adc_init.py`).
Config/default consistency and enabled-pin uniqueness checks passed.
No device was flashed; touch polarity, ADC2 sampling with Wi-Fi, charger/wake,
motor direction and concurrent operation still require hardware validation.