lucky-cat/docs/firmware-pin-usage.md

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.

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

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.

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.

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
UART0 RX	Input	Factory CLI input and serial monitor input
UART0 TX	Output	ESP log output, factory CLI replies, serial monitor output

External Memory Pins

The project enables external PSRAM in octal mode. These are generated ESP-IDF memory-interface settings in sdkconfig, not normal application GPIOs.

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

Flash pins are controlled by the ESP32-S3 flash interface and are not assigned by project GPIO configuration.

Board Nets Present But Not Used By Current Firmware

These nets exist in docs/gpio-map.md, but the current firmware does not assign 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
GPIO3 / touch	TTP223 touch output	Present on the board but not consumed by the current input policy
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
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

Source Files

• sdkconfig.defaults
• sdkconfig
• main/Kconfig.projbuild
• docs/gpio-map.md
• components/platform/src/lcd_direct.c
• components/platform/src/platform_stepper_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