ROM loader for ESP chips, works with ESP8266 or ESP32. This is a ‘no-stub’ loader, so you can’t read MD5 or firmware back on ESP8266.

See this document for protocol we’re implementing:

See this for the ‘original’ code we’re miniaturizing:

There’s a very basic Arduino ROM loader here for ESP32:

  • Author(s): ladyada

Implementation Notes


Software and Dependencies:

class adafruit_miniesptool.miniesptool(uart, gpio0_pin, reset_pin, *, flashsize, baudrate=115200)

A miniature version of esptool, a programming command line tool for ESP8266 and ESP32 chips. This version is minimized to work on CircuitPython boards, so you can burn ESP firmware direct from the CPy disk drive. Handy when you have an ESP module wired to a board and need to upload new AT firmware. Its slow! Expect a few minutes when programming 1 MB flash.

property baudrate

The baudrate of the UART connection. On ESP8266 we cannot change this once we’ve started syncing. On ESP32 we must start at 115200 and then manually change to higher speeds if desired

check_command(opcode, buffer, checksum=0, timeout=0.1)

Send a command packet, check that the command succeeded and return a tuple with the value and data. See the ESP Serial Protocol for more details on what value/data are

static checksum(data, state=239)

Calculate checksum of a blob, as it is defined by the ROM

property chip_name

The specific name of the chip, e.g. ESP8266EX, to the best of our ability to determine without a stub bootloader.

property chip_type

ESP32 or ESP8266 based on which chip type we’re talking to

property debug

Print out all sent/received UART data plus some debugging output

flash_begin(*, size=0, offset=0)

Prepare for flashing by attaching SPI chip and erasing the number of blocks requred.

flash_block(data, seq, timeout=0.1)

Send one block of data to program into SPI Flash memory

flash_file(filename, offset=0, md5=None)

Program a full, uncompressed binary file into SPI Flash at a given offset. If an ESP32 and md5 string is passed in, will also verify memory. ESP8266 does not have checksum memory verification in ROM

get_erase_size(offset, size)

Calculate an erase size given a specific size in bytes. Provides a workaround for the bootloader erase bug on ESP8266.

get_response(opcode, timeout=0.1)

Read response data and decodes the slip packet, then parses out the value/data and returns as a tuple of (value, data) where each is a list of bytes

property mac_addr

The MAC address burned into the OTP memory of the ESP chip

md5(offset, size)

On ESP32 we can ask the ROM bootloader to calculate an MD5 on the SPI flash memory, from a location over a size in bytes. Returns a string with the MD5 in lowercase


Read a register within the ESP chip RAM, returns a 4-element list


Perform a hard-reset into ROM bootloader using gpio0 and reset

send_command(opcode, buffer)

Send a slip-encoded, checksummed command over the UART, does not check response

static slip_encode(buffer)

Take a bytearray buffer and return back a new bytearray where 0xdb is replaced with 0xdb 0xdd and 0xc0 is replaced with 0xdb 0xdc


Put into ROM bootload mode & attempt to synchronize with the ESP ROM bootloader, we will retry a few times