ESP-Prog: Programming header format for ESP8266, ESP8285, and ESP32

Note: This is a draft, with decisions still to be made. The main outstanding question is whether the 1×6 pinout should match the pin assignments of the 2×3 (which results in a very ugly and strange pin order) or use a more logical order such as the wESP32 or ESProg pinouts.

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.

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 is an extension of the 4-pin header commonly used on Sonoff boards, and matches the pinout of the wESP32 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.

PinPurposeNotes
1ESP_IO0
2ES_EN
3GND
4ESP_TXDTx pin on target board. Rx on programmer.
5ESP_RXDRx pin on target board. Tx on programmer.
6VDD3.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.

PinPurposeNotes
1ESP_EN
2VDD3.3V supplied to target board by programmer. 600mA minimum.
3ESP_TXDTx pin on target board. Rx on programmer.
4GND
5ESP_RXDRx pin on target board. Tx on programmer.
6ESP_IO0

This header convention is still under active discussion. This page will continue to be updated based on the discussion.