Note: This is a draft, with decisions still to be made. To participate in the discussion, see the Discord server or Forum, both linked above.
More background information is available at the original video: “Vlog #66: Let’s define a standard ESP8266/ESP32 programming header“
Alternative version here: ESProg
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.
- 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)
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 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. This format works well on the edge of a PCB.
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.
1×6 Header Format
The 1×6 header format is an extension of the 4-pin header commonly used on Sonoff boards. The Sonoff programming header includes the first 4 pins of this format.
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.
|1||GND||Common ground between programmer and target board.|
|2||ESP_TXD||Tx pin on target board. Rx on programmer.|
|3||ESP_RXD||Rx pin on target board. Tx on programmer.|
|4||3.3V||3.3V supplied to target board by programmer. 600mA minimum.|
|5||ESP_EN||Enable (reset) pin on target board.|
|6||ESP_IO0||GPIO0 on target board.|
2×3 Header Format
The 2×3 header format is used by the Espressif programmer / debugger reference design, which stipulates a shrouded 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.
|1||ESP_EN||Enable (reset) pin on target board.|
|2||3.3V||3.3V supplied to target board by programmer. 600mA minimum.|
|3||ESP_TXD||Tx pin on target board. Rx on programmer.|
|4||GND||Common ground between programmer and target board.|
|5||ESP_RXD||Rx pin on target board. Tx on programmer.|
|6||ESP_IO0||GPIO0 on target board.|
This header convention is still under active discussion. This page will continue to be updated based on the discussion.