• Pinout
  • Beginner
  • 5 min
  • Wiring

Recipe · Beginner · Pinout

How to choose the right GPIO pinout before wiring

Different boards expose different pins. The pinout wiki summarizes mappings for boards such as Cardputer, M5Stick, StampS3, AtomS3, T-Embed and Xiao ESP32-S3.

GPIO pinout diagram for wiring checks.
Correct pin selection avoids most “the protocol is broken” false starts.
Step 1

Commands

Most protocol modes have a config command. Select pins after checking the board-specific pinout.

Result

What success looks like

The selected pins match physical exposed pins on your board and the target can be wired without guessing.

Troubleshooting

  • A GPIO exists on the chip but is not exposed on the board.
  • The selected pin is already used by screen, SD card or another onboard peripheral.
  • TX/RX direction is reversed.
  • You copied a pinout from another board variant.

Next steps

  • Save working pin sets with the profile shell.
  • Document the pinout in your project notes.
  • Use DIO pins or a quick scan to verify basic signal presence.

GPIO pinout selection FAQ

Why choose pins per board instead of only per ESP32 chip?

Board layout matters because some GPIOs are already routed to displays, SD cards, buttons, radios or boot functions. A board-aware pinout avoids conflicts that a chip-only pin list will miss.

Should I choose pins in the firmware or wire first?

Choose and configure the pins first, then wire the target to match that configuration. This reduces crossed signals and makes the recipe easier to repeat.

What should I document after a working pinout?

Record the board variant, physical header pins, GPIO numbers, protocol role and target voltage. That makes saved profiles and future troubleshooting much more reliable.

Go deeper