Appendix A - GPIO Reference Tables
Appendix A – GPIO Reference Tables
Version: 0.1 (Draft)
Written for: ESPixelStick Version 4.x
Last Updated: July 2026
Author: Ernest Horning
Research & Technical Editing: ChatGPT
Appendix Summary
Purpose
This appendix provides quick-reference GPIO information for ESP8266 and ESP32-family controllers used with ESPixelStick.
The tables identify:
- Generally usable GPIO
- Boot-strapping pins
- Flash and PSRAM connections
- Input-only pins
- USB and serial-interface conflicts
- Board-specific restrictions
- Pins requiring further ESPixelStick verification
These tables are intended to help users choose GPIO assignments without preventing the controller from booting or interfering with onboard hardware.
Related Chapters
- Chapter 3 – ESP8266 Hardware Guide
- Chapter 4 – ESP32 Hardware Guide
- Chapter 8 – Configuration
- Chapter 9 – Pixel Outputs and Wiring
A.1 Important GPIO Principles
A GPIO number identifies the processor pin used by the firmware.
It does not necessarily match:
- The physical connector position
- The development-board pin number
- A printed D number
- The location of the pin on another ESP board
Always configure ESPixelStick using the actual GPIO number.
For example:
| Board Label | GPIO Number |
|---|---|
| D1 | GPIO5 |
| D2 | GPIO4 |
| D4 | GPIO2 |
This distinction is especially important on ESP8266 development boards.
Status Key
| Status | Meaning |
|---|---|
| 🟩 | Generally suitable for the stated purpose |
| 🟨 | Usable with restrictions or additional verification |
| 🟦 | Community experience or board-dependent |
| 🟥 | Do not use for that purpose |
Engineering Note
A processor may technically allow a pin to be used as GPIO while the development board uses that same pin for:
- Flash memory
- PSRAM
- Ethernet
- USB
- Status LEDs
- Serial programming
- Boot selection
- SD cards
The processor datasheet and the development-board schematic must both be considered.
A.2 Boot-Strapping Pins
Boot-strapping pins are sampled when the processor starts or resets.
External circuitry connected to these pins can change the boot mode or prevent startup.
After booting, many strapping pins may operate as ordinary GPIO, but attached devices must not force them to an incorrect level during reset.
Why This Matters
A pixel string, level shifter, relay board, pull-up resistor, or pull-down resistor connected to a strapping pin can prevent the controller from starting even though the GPIO assignment is otherwise valid.
A.3 ESP8266 GPIO Reference
The ESP8266 has fewer available GPIO than the ESP32 and requires careful pin selection.
GPIO0, GPIO2, and GPIO15 participate in boot-mode selection. GPIO6 through GPIO11 are normally used by the external flash interface and should not be reassigned.
A.3.1 ESP8266 General GPIO Table
| GPIO | Common Board Label | Output Use | Important Notes |
|---|---|---|---|
| GPIO0 | D3 | 🟨 | Boot-strapping pin; normally pulled high |
| GPIO1 | TX | 🟨 | Serial transmit; produces boot and diagnostic data |
| GPIO2 | D4 | 🟨 | Boot-strapping pin; normally pulled high; often connected to onboard LED |
| GPIO3 | RX | 🟨 | Serial receive; may be usable after startup |
| GPIO4 | D2 | 🟩 | Generally suitable GPIO |
| GPIO5 | D1 | 🟩 | Generally suitable GPIO |
| GPIO6 | — | 🟥 | Connected to flash memory |
| GPIO7 | — | 🟥 | Connected to flash memory |
| GPIO8 | — | 🟥 | Connected to flash memory |
| GPIO9 | SD2 | 🟥 | Normally connected to flash memory |
| GPIO10 | SD3 | 🟥 | Normally connected to flash memory |
| GPIO11 | — | 🟥 | Connected to flash memory |
| GPIO12 | D6 | 🟩 | Generally suitable GPIO |
| GPIO13 | D7 | 🟩 | Generally suitable GPIO |
| GPIO14 | D5 | 🟩 | Generally suitable GPIO |
| GPIO15 | D8 | 🟨 | Boot-strapping pin; normally held low |
| GPIO16 | D0 | 🟨 | Restricted peripheral support; board dependent |
A.3.2 ESP8266 Preferred Output Pins
For generic ESP8266 development boards, the following pins are normally the least troublesome starting choices:
| Preference | GPIO | Notes |
|---|---|---|
| 1 | GPIO4 | Commonly labeled D2 |
| 2 | GPIO5 | Commonly labeled D1 |
| 3 | GPIO12 | Commonly labeled D6 |
| 4 | GPIO13 | Commonly labeled D7 |
| 5 | GPIO14 | Commonly labeled D5 |
These recommendations describe general hardware behavior and do not guarantee that every pin is enabled for every ESPixelStick output type.
A.3.3 ESP8266 Pins Requiring Caution
| GPIO | Reason for Caution |
|---|---|
| GPIO0 | Must be high for normal boot |
| GPIO1 | Used for UART transmit and boot messages |
| GPIO2 | Must be high for normal boot |
| GPIO3 | Used for UART receive |
| GPIO15 | Must be low for normal boot |
| GPIO16 | Does not support every peripheral function available through the normal GPIO matrix |
Engineering Note
GPIO2 may briefly carry bootloader-related activity during startup. Espressif specifically warns against connecting GPIO2 directly to VCC or to circuitry that cannot tolerate its startup behavior.
A.4 ESPixelStick ESP8266 Board Assignments
The original ESPixelStick hardware was designed around the ESP8266 and assigns GPIO internally according to the board design.
Users of complete ESPixelStick hardware should normally select the appropriate board profile rather than manually assigning every pin.
A.4.1 Board-Level Reference
| Function | GPIO | Status |
|---|---|---|
| Pixel data output | 🟨 Verify by board revision | 🟨 |
| Serial output | 🟨 Verify by board revision | 🟨 |
| Status LED | 🟨 Verify by board revision | 🟨 |
| Programming UART | GPIO1 and GPIO3 | 🟩 |
| Boot control | GPIO0 | 🟩 |
Research Note
The exact assignments for each official ESPixelStick hardware revision should be confirmed against the matching schematic before Version 1.0.
A.5 Original ESP32 GPIO Reference
The original ESP32 provides substantially more GPIO than the ESP8266.
However, several pins are reserved, input-only, or involved in boot configuration.
Espressif identifies GPIO0, GPIO2, GPIO5, GPIO12, and GPIO15 as strapping pins. GPIO6 through GPIO11 are normally connected to SPI flash. GPIO34 through GPIO39 are input-only and do not provide software-controlled internal pull-up or pull-down resistors.
A.5.1 Original ESP32 General GPIO Table
| GPIO | Output Use | Important Notes |
|---|---|---|
| GPIO0 | 🟨 | Boot-strapping and download-mode pin |
| GPIO1 | 🟨 | UART0 transmit; programming and boot messages |
| GPIO2 | 🟨 | Strapping pin; board dependent |
| GPIO3 | 🟨 | UART0 receive |
| GPIO4 | 🟩 | Generally suitable |
| GPIO5 | 🟨 | Strapping pin; often used for SPI chip select |
| GPIO6 | 🟥 | Flash interface |
| GPIO7 | 🟥 | Flash interface |
| GPIO8 | 🟥 | Flash interface |
| GPIO9 | 🟥 | Flash interface |
| GPIO10 | 🟥 | Flash interface |
| GPIO11 | 🟥 | Flash interface |
| GPIO12 | 🟨 | Strapping pin; flash-voltage selection risk |
| GPIO13 | 🟩 | Generally suitable |
| GPIO14 | 🟩 | Generally suitable |
| GPIO15 | 🟨 | Strapping pin |
| GPIO16 | 🟨 | May be used by PSRAM on some modules |
| GPIO17 | 🟨 | May be used by PSRAM on some modules |
| GPIO18 | 🟩 | Generally suitable |
| GPIO19 | 🟩 | Generally suitable |
| GPIO20 | 🟨 | Not exposed or implemented on many original ESP32 modules |
| GPIO21 | 🟩 | Generally suitable |
| GPIO22 | 🟩 | Generally suitable |
| GPIO23 | 🟩 | Generally suitable |
| GPIO24 | 🟥 | Not normally implemented |
| GPIO25 | 🟩 | Generally suitable |
| GPIO26 | 🟩 | Generally suitable |
| GPIO27 | 🟩 | Generally suitable |
| GPIO28 | 🟥 | Not normally implemented |
| GPIO29 | 🟥 | Not normally implemented |
| GPIO30 | 🟥 | Not normally implemented |
| GPIO31 | 🟥 | Not normally implemented |
| GPIO32 | 🟩 | Generally suitable |
| GPIO33 | 🟩 | Generally suitable |
| GPIO34 | 🟥 | Input only |
| GPIO35 | 🟥 | Input only |
| GPIO36 | 🟥 | Input only; often labeled VP |
| GPIO37 | 🟥 | Input only; not exposed on many boards |
| GPIO38 | 🟥 | Input only; not exposed on many boards |
| GPIO39 | 🟥 | Input only; often labeled VN |
A.6 Recommended Original ESP32 Output Pins
The following pins are generally good starting choices for pixel or serial outputs on common ESP32-WROOM development boards:
| Preference Group | GPIO |
|---|---|
| Preferred | 4, 13, 14, 18, 19, 21, 22, 23 |
| Also commonly usable | 25, 26, 27, 32, 33 |
| Usable with caution | 0, 2, 5, 12, 15 |
| Serial conflict possible | 1, 3 |
| Module dependent | 16, 17 |
| Input only | 34–39 |
| Reserved for flash | 6–11 |
Community Experience
On a generic 30-pin ESP-WROOM-32 development board, Ernest Horning successfully tested ESPixelStick/WLED-style pixel outputs on many exposed GPIO, including:
- GPIO4
- GPIO5
- GPIO12
- GPIO13
- GPIO18
- GPIO19
- GPIO21
- GPIO22
- GPIO23
- GPIO25
- GPIO27
- GPIO1
- GPIO3
GPIO26 did not operate on the particular tested board and firmware configuration.
This should be treated as a board-specific test rather than a universal ESP32 limitation.
Contributor: Ernest Horning
Source: Bench testing
A.7 ESP32 Strapping-Pin Cautions
A.7.1 GPIO0
GPIO0 is used to select serial download mode.
Holding it low during reset can place the processor into the bootloader rather than starting ESPixelStick.
A.7.2 GPIO2
GPIO2 is a strapping pin and may have startup-state requirements depending on the module and flash configuration.
A.7.3 GPIO5
GPIO5 is a strapping pin but is frequently used successfully after boot.
A.7.4 GPIO12
GPIO12 requires particular caution because its startup level can influence flash-memory voltage configuration on some original ESP32 modules.
A peripheral that pulls GPIO12 high during reset may prevent the processor from reading its flash memory correctly.
A.7.5 GPIO15
GPIO15 is a strapping pin and may also be associated with debug or peripheral functions.
Why This Matters
A pin may work perfectly after the controller starts but still prevent startup because the attached circuit forces the wrong state during the first milliseconds after reset.
A.8 ESP32 Input-Only Pins
Original ESP32 GPIO34 through GPIO39 are input-only.
They cannot drive:
- Pixel data
- Serial output
- Relay control
- Clock signals
- Status LEDs
They also lack software-controlled internal pull-up and pull-down resistors.
| GPIO | Input Capability | Output Capability |
|---|---|---|
| GPIO34 | Yes | No |
| GPIO35 | Yes | No |
| GPIO36 | Yes | No |
| GPIO37 | Yes | No |
| GPIO38 | Yes | No |
| GPIO39 | Yes | No |
A.9 ESP32 Flash and PSRAM Pins
A.9.1 Flash Pins
On typical ESP32 modules, GPIO6 through GPIO11 are connected internally to flash memory.
They should not be used for ESPixelStick outputs.
A.9.2 PSRAM Pins
On ESP32 modules containing PSRAM, GPIO16 and GPIO17 may be assigned internally to the PSRAM interface.
Their availability depends on the exact module.
| Module Type | GPIO16 and GPIO17 |
|---|---|
| ESP32-WROOM without PSRAM | Often available |
| ESP32-WROVER with PSRAM | Frequently reserved |
| Unknown module | 🟨 Verify before use |
A.10 WT32-ETH01 GPIO Reference
The WT32-ETH01 combines an ESP32 with an onboard Ethernet PHY.
Ethernet consumes several GPIO that might otherwise be available on a generic ESP32 development board.
The exact board schematic and ESPixelStick board profile should be treated as authoritative.
A.10.1 WT32-ETH01 General Guidance
| GPIO Category | Recommendation |
|---|---|
| Ethernet PHY pins | 🟥 Do not reassign |
| Serial programming pins | 🟨 Use with caution |
| Boot-strapping pins | 🟨 Use only when startup state is controlled |
| Exposed unused GPIO | 🟩 May be assigned where supported |
| GPIO34–39 | 🟥 Input only |
Research Note
A verified WT32-ETH01 pin-by-pin ESPixelStick table remains required.
The final table should identify:
- Ethernet MDC
- Ethernet MDIO
- Ethernet clock
- PHY power or enable
- UART programming pins
- Default pixel output
- Available auxiliary outputs
A.11 ESP32-S2 GPIO Reference
The ESP32-S2 differs from the original ESP32.
Pin availability depends heavily on:
- Module type
- Native USB use
- Flash configuration
- PSRAM configuration
- Development-board routing
A.11.1 ESP32-S2 Status
| Item | Status |
|---|---|
| Processor-level GPIO documented by Espressif | 🟩 |
| ESPixelStick production support | 🟨 |
| Verified default ESPixelStick output assignments | 🟨 |
| Board-specific reference tables | 🟨 |
Research Note
Do not apply the original ESP32 GPIO table directly to an ESP32-S2.
A.12 ESP32-S3 GPIO Reference
The ESP32-S3 uses a different pin arrangement from the original ESP32.
Espressif identifies GPIO0, GPIO3, GPIO45, and GPIO46 as strapping pins. GPIO26 through GPIO32 are generally associated with flash or PSRAM. On modules using octal flash or octal PSRAM, GPIO33 through GPIO37 may also be consumed internally.
A.12.1 ESP32-S3 Restricted GPIO
| GPIO | Status | Reason |
|---|---|---|
| GPIO0 | 🟨 | Boot-strapping pin |
| GPIO3 | 🟨 | Strapping pin |
| GPIO19 | 🟨 | Native USB function on many boards |
| GPIO20 | 🟨 | Native USB function on many boards |
| GPIO26–32 | 🟥 | Commonly flash or PSRAM |
| GPIO33–37 | 🟨/🟥 | Reserved on octal-memory modules |
| GPIO45 | 🟨 | Strapping pin; input restrictions may apply |
| GPIO46 | 🟨 | Strapping pin; input restrictions may apply |
A.12.2 ESP32-S3 USB Considerations
Many ESP32-S3 development boards use native USB on GPIO19 and GPIO20.
Reassigning these pins may disable:
- USB programming
- USB serial communication
- USB JTAG
- Firmware recovery through the native USB connector
Research Note
ESP32-S3 ESPixelStick support and tested output combinations remain under active verification.
A.13 ESP32-C3 GPIO Reference
Espressif identifies GPIO2, GPIO8, and GPIO9 as strapping pins on the ESP32-C3. GPIO12 through GPIO17 are commonly used for flash and PSRAM and are not recommended for general reassignment. GPIO18 and GPIO19 are used by USB-JTAG by default on applicable designs.
A.13.1 ESP32-C3 General Table
| GPIO | Status | Important Notes |
|---|---|---|
| GPIO0 | 🟩 | Generally usable; board dependent |
| GPIO1 | 🟩 | Generally usable; board dependent |
| GPIO2 | 🟨 | Strapping pin |
| GPIO3 | 🟩 | Generally usable |
| GPIO4 | 🟩 | Generally usable |
| GPIO5 | 🟩 | Generally usable |
| GPIO6 | 🟩 | Generally usable on many modules |
| GPIO7 | 🟩 | Generally usable on many modules |
| GPIO8 | 🟨 | Strapping pin; often onboard LED |
| GPIO9 | 🟨 | Strapping and boot-mode pin |
| GPIO10 | 🟨 | Module and board dependent |
| GPIO11 | 🟨 | Module and board dependent |
| GPIO12–17 | 🟥 | Commonly flash or PSRAM |
| GPIO18 | 🟨 | USB-JTAG or USB serial function |
| GPIO19 | 🟨 | USB-JTAG or USB serial function |
| GPIO20 | 🟨 | UART function; board dependent |
| GPIO21 | 🟨 | UART function; board dependent |
Engineering Note
Small ESP32-C3 boards often expose only a subset of the processor GPIO.
The pin printed on the board must be checked against that board's schematic.
A.14 ESP32-C6 GPIO Reference
Espressif identifies GPIO4, GPIO5, GPIO8, GPIO9, and GPIO15 as strapping pins on the ESP32-C6. GPIO24 through GPIO30 are generally associated with flash. GPIO12 and GPIO13 may be used by USB-JTAG.
A.14.1 ESP32-C6 Restricted GPIO
| GPIO | Status | Reason |
|---|---|---|
| GPIO4 | 🟨 | Strapping pin |
| GPIO5 | 🟨 | Strapping pin |
| GPIO8 | 🟨 | Strapping pin |
| GPIO9 | 🟨 | Strapping and boot-mode pin |
| GPIO12 | 🟨 | USB-JTAG |
| GPIO13 | 🟨 | USB-JTAG |
| GPIO15 | 🟨 | Strapping pin |
| GPIO24–30 | 🟥 | Flash interface |
Research Note
ESP32-C6 ESPixelStick support has not yet been established as production-ready for this guide.
A.15 GPIO Selection by Function
A.15.1 Pixel Data Output
A pixel-data GPIO must:
- Support digital output
- Remain stable after startup
- Not be reserved for flash
- Not be input-only
- Not be forced to an incorrect boot state
- Be supported by the selected ESPixelStick output driver
A.15.2 Clocked Pixel Output
Clocked pixels require two GPIO:
- Data
- Clock
Both pins must support digital output and the required peripheral assignment.
A.15.3 Serial Output
Serial protocols may use:
- Hardware UART
- Firmware-generated serial output
- Differential line-driver hardware
UART0 pins are commonly shared with programming and diagnostic messages.
A.15.4 Input Functions
Inputs may include:
- Buttons
- Triggers
- Sensors
- Serial receive
- DMX receive
Input-only pins may be useful for these functions even though they cannot drive pixels.
A.16 Quick Selection Tables
A.16.1 ESP8266 Quick Selection
| Category | GPIO |
|---|---|
| Preferred starting choices | 4, 5, 12, 13, 14 |
| Boot-sensitive | 0, 2, 15 |
| Serial programming | 1, 3 |
| Flash reserved | 6–11 |
| Special restrictions | 16 |
A.16.2 Original ESP32 Quick Selection
| Category | GPIO |
|---|---|
| Preferred starting choices | 4, 13, 14, 18, 19, 21, 22, 23, 25, 26, 27, 32, 33 |
| Boot-sensitive | 0, 2, 5, 12, 15 |
| Serial programming | 1, 3 |
| Flash reserved | 6–11 |
| Possible PSRAM use | 16, 17 |
| Input only | 34–39 |
A.16.3 ESP32-C3 Quick Selection
| Category | GPIO |
|---|---|
| Potential general GPIO | 0, 1, 3, 4, 5, 6, 7 |
| Boot-sensitive | 2, 8, 9 |
| Flash or PSRAM | 12–17 |
| USB conflict possible | 18, 19 |
| Board dependent | 10, 11, 20, 21 |
A.16.4 ESP32-S3 Quick Selection
| Category | GPIO |
|---|---|
| Boot-sensitive | 0, 3, 45, 46 |
| USB conflict possible | 19, 20 |
| Flash or PSRAM | 26–32 |
| Octal-memory dependent | 33–37 |
| All others | Verify against module and board schematic |
A.17 ESPixelStick Advanced Mode
ESPixelStick Version 4 exposes GPIO assignments through Advanced Mode.
According to ESPixelStick project guidance:
- Open the Admin page.
- Enable Advanced Mode.
- Open the device-configuration page.
- Review the GPIO assigned to each selected input and output.
The interface prevents or limits some incompatible combinations, but the user must still account for board-level electrical restrictions.
Engineering Note
Advanced Mode exposes flexibility.
It does not make every GPIO electrically safe.
A.18 GPIO Troubleshooting Table
| Symptom | Possible GPIO Cause |
|---|---|
| Controller will not boot | Incorrect level on a strapping pin |
| Controller enters programming mode | GPIO0 or equivalent boot pin held low |
| Output works only after manual reset | Startup conflict |
| Random pixels appear during boot | UART or boot activity on output pin |
| No output on GPIO34–39 | Original ESP32 pins are input-only |
| Controller crashes when output enabled | Flash or PSRAM pin reassigned |
| USB connection disappears | Native USB pins reassigned |
| Ethernet stops working | Ethernet PHY GPIO reassigned |
| Onboard LED flashes with pixel data | Output shares the LED GPIO |
| Firmware cannot be reflashed | Boot, UART, or USB pins are occupied |
A.19 Engineering Recommendations
✔ Begin with a preferred GPIO before using a restricted pin.
✔ Verify the processor family.
✔ Verify the module.
✔ Verify the development-board schematic.
✔ Verify the ESPixelStick board profile.
✔ Avoid flash and PSRAM pins.
✔ Avoid input-only pins for outputs.
✔ Treat strapping pins as conditional choices.
✔ Test startup with pixels and peripherals connected.
✔ Power-cycle the complete assembly several times before installation.
✔ Record every GPIO assignment in the project documentation.
A.20 Open Research Items
| Status | Item |
|---|---|
| 🟨 | Official ESPixelStick V1 GPIO assignments |
| 🟨 | Official ESPixelStick V2 GPIO assignments |
| 🟨 | Official ESPixelStick V3 GPIO assignments |
| 🟨 | WT32-ETH01 complete pin table |
| 🟨 | QuinLED and other community-board profiles |
| 🟨 | ESP32-S2 ESPixelStick support |
| 🟨 | ESP32-S3 tested output table |
| 🟨 | ESP32-C3 tested output table |
| 🟨 | ESP32-C6 firmware support |
| 🟨 | PSRAM use by ESPixelStick |
| 🟨 | Maximum simultaneous outputs by processor |
| 🟨 | Output-driver-specific GPIO restrictions |
| 🟨 | SD-card interface assignments |
| 🟨 | Ethernet interface assignments |
| 🟨 | I²C PWM-module pin assignments |
References
This appendix is based upon:
- ESPixelStick project documentation and firmware discussions
- Espressif ESP8266 boot-mode documentation
- Espressif ESP32 GPIO documentation
- Espressif ESP32-S3 GPIO documentation
- Espressif ESP32-C3 GPIO documentation
- Espressif ESP32-C6 GPIO documentation
- Espressif hardware-design guidance
- Community bench testing
Revision History
| Version | Date | Description |
|---|---|---|
| 0.1 | July 2026 | Initial GPIO reference draft |