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; generated sdkconfig differences are called out where they affect runtime behavior. 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
3	CONFIG_TQ_SCREEN_RESET_PIN	Output	LCD	ST7789 panel reset	Set high after GPIO init; -1 disables hardware reset
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
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

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.

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
GPIO4	Unassigned	Not used
GPIO5	Unassigned	Not used
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
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

Current Generated sdkconfig Difference

sdkconfig.defaults enables the key input task:

CONFIG_TQ_KEY_INPUT_ENABLE=y

The current generated sdkconfig has it disabled:

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