AI_Printer/docs/gpio-map.md

ESP32-S3 GPIO Mapping

本文件按当前固件实现校对（代码 + 当前 sdkconfig），审计日期：2026-03-02。

GPIO Table (Current Build)

Board Pin	GPIO	Signal	Direction (Current Build)	Notes
1	GND	GND	-	Ground
2	3V3	3V3	-	3.3V Power
3	EN/RST	EN	Input	Chip enable/reset
4	IO4	PRINT_STB5_6	Output	Printer strobe 5/6
5	IO5	PRINT_STB3_4	Output	Printer strobe 3/4
6	IO6	ES8311_I2C_SDA	Bidirectional	Voice codec I2C SDA
7	IO7	ES8311_I2C_SCL	Output	Voice codec I2C SCL
8	IO15	BATTERY_ADC	Input	Battery voltage ADC detect
9	IO16	PRINT_STB1_2	Output	Printer strobe 1/2
10	IO17	PRINT_PAPER	Input	Paper-present level is controlled by CONFIG_TQ_PRINTER_PAPER_PRESENT_LEVEL (current: 0, low means paper present)
11	IO18	NTC_ADC	Input	NTC ADC
12	IO8	PRINT_OUTA_P	Output	Printer OUTA+
13	IO19	PRINT_OUTA_N	Output	Printer OUTA-
14	IO20	ES8311_PA	Output	PA control
15	IO3	PRINT_OUTB_P	Output	Printer OUTB+
16	IO46	PRINT_OUTB_N	Output	Printer OUTB-
17	IO9	SPI_SHARED_MOSI	Output	Printer/Screen shared MOSI
18	IO10	PRINTER_MISO	Input	Shared SPI MISO used by current screen driver config
19	IO11	SPI_SHARED_CLK	Output	Printer/Screen shared CLK
20	IO12	SCREEN_DC	Output	ST7789 DC
21	IO13	SCREEN_CS (SCREEN_CS1)	Output	ST7789 CS
22	IO14	MIC_KEY	Input	Mic key (supports ADC-mux extension path)
23	IO21	LED_G	Output	Green LED
24	IO47	POWER_KEY	Input	Active-low power key, long press 2s triggers lifecycle stop and power-off hold release
25	IO48	SCREEN_BACKLIGHT	Output	Backlight active level by CONFIG_TQ_SCREEN_BACKLIGHT_ACTIVE_HIGH (current: y, high = on)
26	IO45	PRINT_LAT	Output	Printer LAT
27	IO0	KEY_PRINT / BOOST_CTRL	Output (current) / Input (optional)	Current build uses boost mode at boot (CONFIG_TQ_KEY_PRINT_BOOST_ENABLE_ON_BOOT=y), so this pin is driven as boost control
28	IO35	N/A	-	Not available
29	IO36	N/A	-	Not available
30	IO37	N/A	-	Not available
31	IO38	I2S_MCLK	Output	Voice I2S MCLK
32	IO39	I2S_BCLK	Output	Voice I2S BCLK
33	IO40	I2S_DI	Input	Voice I2S data in
34	IO41	I2S_WS	Output	Voice I2S WS
35	IO42	I2S_DO	Output	Voice I2S data out
36	TXD0	UART0_TX	Output	Serial log/program
37	RXD0	UART0_RX	Input	Serial log/program
38	IO2	LED_R	Output	Red LED
39	IO1	POWER_HOLD	Output	Must drive high at boot to keep board powered
40	GND	GND	-	Ground
41	GND	GND	-	Ground

Additional Runtime Pin Behavior

Logical Signal	Config	Current Value	Behavior
SCREEN_RESET	CONFIG_TQ_SCREEN_RESET_PIN	-1	No dedicated reset pin. Runtime falls back to CONFIG_TQ_SCREEN_BACKLIGHT_PIN (IO48) as reset pin.

Firmware Mapping Notes (Current Implementation)

• Board pin mapping is configured through main/Kconfig.projbuild (CONFIG_TQ_*) and resolved from sdkconfig at build time.
• GPIO usage is config-driven. Current code path does not rely on GPIO_NUM_xx hardcoded pin numbers.
• components/platform/src/platform_bootstrap.c initializes critical GPIO on startup:
  • POWER_HOLD is asserted high early.
  • LED_R and LED_G default low.
  • SCREEN_CS/DC/BACKLIGHT are initialized with configured defaults.
  • KEY_PRINT is output boost control when CONFIG_TQ_KEY_PRINT_BOOST_ENABLE_ON_BOOT=y, otherwise input with pull-up.
  • POWER_KEY, MIC_KEY, PRINT_PAPER default to input with pull-up.
• Physical power-key handling uses managed_components/espressif__button:
  • Platform layer (platform_power_key.c) reports long-press events (2s, active-low).
  • Control-plane consumes the shutdown request and performs graceful stop, then calls platform_power_hold_set(false) through system_runtime_power_off().
• Thermal printer runtime behavior (components/platform/src/thermal_printer.c):
  • STB lines are active-high.
  • LAT idles high and is pulsed low-high.
  • Shared MOSI/CLK are temporarily switched to GPIO bit-bang for printing.
  • Paper detect compares GPIO level against runtime_policy_printer_paper_present_level().
• Display stack is:
  • platform_display_* (display_st7789.c) -> lcd_module_* (display_lcd_module.c) -> st7789p3_* (display_st7789p3.c).
  • Current implementation no longer describes panel setup in display_st7789.c directly.
  • LCD path includes shared-SPI recovery after printer takes over shared pins.
• Voice path (components/platform/src/voice_audio.c):
  • I2C defaults to SDA=6, SCL=7, with internal pull-up enabled in both I2C code paths.
  • I2S defaults to MCLK=38, BCLK=39, WS=41, DOUT=42, DIN=40.
  • PA control defaults to IO20 and polarity can be flipped by CONFIG_TQ_VOICE_CODEC_PA_PIN_REVERSED.

Condition-Driven Behavior (Important)

Config	Current	Impact
CONFIG_TQ_KEY_PRINT_BOOST_ENABLE_ON_BOOT	y	KEY_PRINT/BOOST_CTRL works as output boost-control at boot/runtime instead of key input
CONFIG_TQ_KEY_PRINT_BOOST_ACTIVE_HIGH	y	Boost enable level is high
CONFIG_TQ_SCREEN_BACKLIGHT_ACTIVE_HIGH	y	Backlight ON level is high
CONFIG_TQ_SCREEN_RESET_PIN	-1	Screen reset falls back to backlight pin
CONFIG_TQ_SCREEN_ENABLE	y	Screen driver and its GPIO paths are compiled in
CONFIG_TQ_PRINTER_PAPER_PRESENT_LEVEL	0	Paper detect treats GPIO low as paper present