Note: This draft is outdated and is left here for reference only. Do not use it in new designs!
The final programming header format is documented at www.superhouse.tv/espflash
ESP8266, ESP8285, and ESP32 microcontrollers are commonly designed into projects with a programming header, to allow initial flashing of firmware. Espressif produced a limited number of programmer / debugger boards, but they’re almost unknown so there has been very little standardisation on the format of programming headers. Everyone who starts their own project invents their own header format.
This document outlines the conventions that I have decided to follow for my own ESPXXxx projects, based on a review of existing header formats, discussions with many other board designers, Espressif documentation, and my own whims.
The more people who follow these conventions with their own designs, the better it will be for everyone.
Pins Required
- GND
- VDD (3.3V)
- TX (3.3V)
- RX (3.3V)
- GPIO0 (hold LOW during startup to enter bootloader mode)
- RESET (CH_EN, marked as “ESP_EN” below)
Header Options
The header can use either 2×3 or 1×6 format, in either 2.54mm (0.1″) or 1.27mm (0.05″) pitch.
Rationale for supporting 2×3 format: The Espressif reference design uses 2×3 format. This format is useful for minimising the footprint on the target board, so including this in the convention is useful. This format is also best for use with a programmer connected via an IDC cable.
Rationale for supporting 1×6 format: Most hobby projects tend to use a linear format, and popular boards such as the Sonoff often do as well.
Rationale for supporting both 2.54mm and 1.27mm pitch: The Espressif reference design specifies use of either 2.54mm or 1.27mm pitch. Hobby projects tend to use 2.54mm pitch because it’s commonly available, large enough to handle easily, and jumper wires are readily available in this size. Providing 1.27mm pitch as an option is desirable for small boards with tight space.
This effectively gives 4 possible headers that can be used:
- 1×6, 2.54mm pitch
- 1×6, 1.27mm pitch
- 2×3, 2.54mm pitch
- 2×3, 1.27mm pitch
Ideally, there should be only one standard header. Having 4 possible header formats could lead to confusion, but at least the confusion will be minimised if there is consistency of pinout. Also, size adapters are trivial to make so it doesn’t require people to own 4 different programmers. A general-purpose programmer could easily support all 4 formats, or a programmer could be optimised for one specific format.
I expect that the most common format will be 1×6 @ 2.54mm, followed by 2×3 @ 2.54mm.
1×6 Header Format
The 1×6 header format matches the pinout of the ESProg programming header.
Connector on target: 1×6 socket, in either 2.54mm or 1.27mm pitch.
Connector on programmer: 1×6 pin header, in pitch to match target.
| Pin | Purpose | Notes |
| 1 | ESP_IO0 | |
| 2 | ES_EN | |
| 3 | GND | |
| 4 | ESP_TXD | Tx pin on target board. Rx on programmer. |
| 5 | ESP_RXD | Rx pin on target board. Tx on programmer. |
| 6 | VDD | 3.3V supplied to target board by programmer. 600mA minimum. |
2×3 Header Format
The 2×3 header format is used by the Espressif programmer / debugger reference design, which stipulates a box-header to ensure correct orientation. However, normal pin headers can also be used if preferred.
Connector on target: 2×3 box header or pin header, in either 2.54mm or 1.27mm pitch.
Connector on programmer: 2×3 socket or 2×3 IDC cable, in pitch to match target.
| Pin | Purpose | Notes |
| 1 | ESP_EN | |
| 2 | VDD | 3.3V supplied to target board by programmer. 600mA minimum. |
| 3 | ESP_TXD | Tx pin on target board. Rx on programmer. |
| 4 | GND | |
| 5 | ESP_RXD | Rx pin on target board. Tx on programmer. |
| 6 | ESP_IO0 |
Note: This draft is outdated and is left here for reference only. Do not use it in new designs!
The final programming header format is documented at www.superhouse.tv/espflash
