Pin Assignment Master Table
This is the single source of truth for all GPIO assignments. Every wiring and firmware document cross-references this table. Resolve any conflicts here before wiring.
Keep this open while wiring
This page is linked in the navbar for quick access.
GPIO Assignments
| GPIO | Signal Name | Component | Direction | Notes |
|---|---|---|---|---|
| GPIO2 | FRONTLIGHT_PWM | E-ink front light | Out | LEDC channel 0; duty cycle controls brightness |
| GPIO3 | EINK_BUSY | E-ink display | In | Active HIGH — wait until LOW before sending commands |
| GPIO4 | EINK_RST | E-ink display | Out | Active LOW; pulse LOW for ≥10 ms on init |
| GPIO5 | EINK_DC | E-ink display | Out | LOW = command, HIGH = data |
| GPIO6 | BTN_UP | Button 1 | In | Internal pull-up; LOW when pressed |
| GPIO7 | BTN_DOWN | Button 2 | In | Internal pull-up; LOW when pressed |
| GPIO8 | BTN_SELECT | Button 3 | In | Internal pull-up; LOW when pressed |
| GPIO9 | BTN_BACK | Button 4 | In | Internal pull-up; LOW when pressed |
| GPIO10 | SPI_CS_DISPLAY | E-ink display | Out | Active LOW; display is the only SPI device |
| GPIO11 | SPI_MOSI | SPI bus (display only) | Out | |
| GPIO12 | SPI_SCLK | SPI bus (display only) | Out | |
| GPIO13 | SPI_MISO | SPI bus (display only) | In | |
| GPIO15 | I2S_BCLK | MAX98357A | Out | Bit clock |
| GPIO16 | I2S_LRCLK | MAX98357A | Out | Frame/word select (WS) |
| GPIO17 | I2S_DIN | MAX98357A | Out | Serial audio data |
| GPIO21 | I2C_SDA | DS3231 RTC + APDS-9960 | Bidir | Pull-up resistor on DS3231 breakout board |
| GPIO18 | I2C_SCL | DS3231 RTC + APDS-9960 | Out | Pull-up resistor on DS3231 breakout board |
| GPIO35 | LED_RED | Red indicator LED | Out | Active HIGH; 220 Ω series resistor to GND |
| GPIO36 | LED_GREEN | Green indicator LED | Out | Active HIGH; 100 Ω series resistor to GND |
| GPIO37 | LED_BLUE | Blue indicator LED | Out | Active HIGH; 100 Ω series resistor to GND |
| GPIO38 | BTN_SNOOZE | Button 5 + ATtiny PB1 | In | Internal pull-up + 10 kΩ external pull-up; LOW when pressed; shared with ATtiny backup circuit |
| GPIO39 | BTN_DISMISS | Button 6 + ATtiny PB2 | In | Internal pull-up + 10 kΩ external pull-up; LOW when pressed; shared with ATtiny backup circuit |
| GPIO40 | PROXIMITY_INT | APDS-9960 | In | Active LOW when proximity count exceeds threshold; 10 kΩ pull-up to 3.3V required; interrupt-driven |
| GPIO41 | USB_PRESENT | Voltage divider (2× 100 kΩ) | In | HIGH (~2.5 V) when USB connected; LOW when USB absent |
| GPIO42 | RTC_INT | DS3231 SQW + ATtiny PB3/INT0 | In | Active LOW alarm interrupt; 10 kΩ pull-up to 3.3 V required; shared with ATtiny backup circuit |
Power Rails
| Pin | Voltage | Connected To |
|---|---|---|
| 5V (VBUS) | 5 V | USB-C VBUS → MAX98357A VIN |
| 3V3 | 3.3 V | DS3231 VCC, APDS-9960 VCC, E-ink adapter VCC |
| GND | 0 V | All component grounds (common reference) |
The system 5V rail is sourced directly from USB-C VBUS. The MAX98357A needs 5 V for its internal amplifier stage; everything else runs at 3.3 V. There is no battery-backed 5V rail — when USB power is removed, the ESP32 shuts down. The discrete AA backup circuit (ATtiny85 + piezo) operates independently from its own 3V supply.
Bus Overview
Pins to Avoid
The ESP32-S3 has several pins with special behaviour on boot. Do not use these for buttons or other general purposes:
| GPIO | Why to avoid |
|---|---|
| GPIO0 | Strapping pin — LOW at boot enters download mode |
| GPIO19 | USB D− (used for USB OTG on some boards) |
| GPIO20 | USB D+ (used for USB OTG on some boards) |
| GPIO45 | Strapping pin — controls VDD_SPI voltage |
| GPIO46 | Strapping pin — controls ROM log output |
| GPIO43 | UART0 TX (used for serial console / flashing) |
| GPIO44 | UART0 RX (used for serial console / flashing) |