# Firmware Pin Usage

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 | 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 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 / Pin | Value / Status | Meaning |
| --- | --- | --- |
| `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 / 充满检测 | Input | `CONFIG_TQ_BATTERY_FULL_GPIO=8`, low-active TP4056 STDBY# via Q8 |
| 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 |

Mechanical switches use pull-up only. PTT and charger active levels are retained
from the previous configuration and require actual idle/active measurements.
Battery charge/full state uses GPIO18/GPIO8 with 100ms polling and 1s sampled
stability confirmation. Both active means fault; both inactive means not charging.
Full prompts require a confirmed charging-to-full transition; no voltage inference. ADC divider gain/offset remain unchanged pending VBAT measurements.

## Boot Calibration And Sleep

`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.

Charge inputs are polled without GPIO interrupts. Low-active deep-sleep wake follows
`CONFIG_TQ_BATTERY_CHARGE_GPIO=18`; the full input is not a wake source. Verify charger insertion/removal and wake
behavior after changing the board.

## System Interfaces

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.

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

- `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`

## 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.