Burn New Bootloader Esp32 Flash Download Tool Mac

Posted on by

Looking for the best ISO to USB burner for Mac? It's possible, but ISO is not native file type in Mac OS X or macOS environment, so you need to use workaround methods or employ a third-party ISO burning utility for Mac to get this done. This article covers three ways to burn ISO to USB stick on a Mac computer, powered by macOS Catalina, Mojave, High Serria and earier Mac OS X systems.

The first thing you need to know is that you can't use an ISO disk image file on a Mac, since Apple primarily uses the DMG format. However, if you merely want to burn ISO to a USB stick, that's definitely possible. The only thing you can't do is run an ISO file on an Apple computer. Let's look at the various ways to burn ISO to USB on a Mac machine.

Esptool.py is a python script that retrieves information about your ESP8266 module and flashes its firmware. In the previous article we used ESPFlasher to install a NodeMCU firmware on an ESP8266-based board (and even install a custom firmware through nodemcu-build), but ESPFlasher is only available for Windows (32 or 64 Bits) while esptool can run on all platforms that can run Python. To actually upload our test program, we need to format it for the ESP32 and then store it in the SPI Flash chip connected to the actual ESP32 within the module. We can do that with Espressif’s esptool utility. It should be part of the ESP-IDF download, but you can find more detailed instructions in the project’s GitHub repository.

  1. Aug 14, 2018 Esptool.py is a python script that retrieves information about your ESP8266 module and flashes its firmware. In the previous article we used ESPFlasher to install a NodeMCU firmware on an ESP8266-based board (and even install a custom firmware through nodemcu-build), but ESPFlasher is only available for Windows (32 or 64 Bits) while esptool can run on all platforms that can run Python.
  2. Programming ESP32 with Arduino IDE: STEP 1: Connect your ESP32 board to your computer through the micro-USB cable. Make sure the red LED goes high on the module to ensure power supply. STEP 2: Start the Arduino IDE and navigate to Tools - Boards and select ESP32Dev board as shown below.

Edit: If you have any question during ISO burning process, please check out the FAQ Part at the end of this article.

Part 1: How to Burn ISO to USB With Mac Terminal Software

Terminal is Apple's command line equivalent of Command Prompt in Windows and Terminal in Linux. Using this command line utility, you can burn an ISO file to an external DVD or USB disk. If you did not t have any experience with text command, then this is not recommended because it is too risky to damage the local disk with wrong input. Terminal allows you to do several system-level operations, so don't input anything other than the commands specified in the process outline shown below:

Step 1: Click Terminal icon from the Dock. Or Go to the Applications folder on Mac and find the Terminal app in Utilities folder.

Step 2: Copy the ISO file in a convenient location so your command doesn't have to be too long. Saving it to desktop or downloads folder is usually a good idea. Make sure you remember the name of the ISO file because it will be used in the command.

Step 3: If your ISO file is in your Desktop, then run the following command (press Enter after typing the command): cd desktop

Step 4: Now run the following command (hit Enter after typing): hdiutil burn filename.iso

Step 5: Once you run the command, your ISO file will be burned to the USB drive in your default optical drive. If you haven't inserted a disk, you will be prompted to do so. There is no need to run the command again after inserting the USB.


  • Dangerous and not safe for beginners .
  • Sharp learning curve.
  • Bad support for USB 2.0 device.
  • Lower success rate.

If you want to avoid any kind of command line work and if you're running one of the newer versions of macOS, then it's better to use a third-party software like the one described in Part 2 below.

Part 2: Easily Burn ISO to USB on Mac via UUByte Software (Bootable USB Creator)

Sofware being powered by a graphics user interface are always welcomed because of user friendly operation. So the second suggestion in here is UUByte ISO burner software called ISO Editor for Mac. It is popularly regarded as the best ISO burning software for Mac. It allows you to burn, extract, edit, copy and create ISO almost as if it was a native file format on Mac. The utility has been fully tested on a wide range of storage media brands as well as all versions of macOS and Mac OS X.

The biggest advantage is that you do not need any technical expertise whatsoever to use this software. It is highly intuitive, and in a matter of minutes you can burn your ISO to USB or DVD. More importantly, the USB is bootable in default. This flexibility makes it the most user-friendly Mac app for handling ISO disk images in a number of ways. The next section shows you how to easily and quickly burn any ISO file to a disk or drive to create bootable USB on your Mac.

Key Features of ISO Editor for Mac

  • Designed by great UI.
  • Powerful Burning options.
  • Able to make bootable USB or DVD.
  • Support the latest macOS Mojave and High Serria.
  • Include other useful ISO tools such as edit, extract and create.

Step 1: Download UUByte ISO Burner for Mac

Download and install ISO Editor for Mac to your computer and launch the program. Click on the Burn module on the first page, which will take you to the ISO burning utility.

Step 2: Insert USB Drive on Mac and Import ISO Image

Insert a USB flash drive into your Mac. Select the ISO file to be burned to the media. If you want a different partition style or file system, make those changes on this page. If you don't know what they mean, leave them in default mode.

Step 3: Start Burning ISO to USB on Mac

Click Burn and the ISO file will be burned to USB drive in around 5 minutes. Please wait and be patient. Make sure the computer not going into sleep mode during the burning process. Flash player offline download installer for mac windows 10.

UUByte ISO Editor for Mac boasts a 95% burn success rate, so no wasted disks or wasted time when you use this software. The software's reliability, flexibility and speed have made this the go-to Mac application for handling ISO disk image files.


Part 3: Disk Utility - The Default ISO to USB Buner (Solid for Old Macs)

Disk Utility is a built-in tool that comes with Mac OS X and macOS. Using this function, you can easily burn your ISO to a disk after mounting it. Disk Utility is primarily meant to view and repair hard drives and other drives, but also has added functionality. Follow the process below to get your ISO burned to a writable DVD or CD.

Step 1: Go to the Applications folder using Finder or by clicking the shortcut on the bottom right of your screen. From there, go into the Utilities folder and click on Disk Utility to launch the app.

Step 2: Open your ISO file and mount it as a virtual drive. This is done automatically when you click on File >Open Disk Image… in the top menu.

Step 3: When you see your ISO file in the left panel, that means it was mounted properly. You can now insert an USB and click on the Burn option to burn the target ISO file to the USB drive.

This method is only meant for OS X 10.10 and earlier versions. With Mac OS X 10.11 El Capitan, Apple removed the ability to burn ISO to a USB. If you have one of these higher versions, you can try the above methods.

Part 4: Frequently Asked Questions

Q: Why my USB drive is not bootable by using hdiutil command?

It is a common case for Windows ISO image because this command does not write Windows bootloader to USB drive. You have to format the drive to FAT32 first in Disk Utility.

Q: Can not select USB drive in UUByte ISO Editor?

If the USB drive could be recognized by Mac but not in UUByte ISO Editor, then it is highly possible that your Mac is in Dark Mode. To fix this, please switch to Light mode instead.

Q: Should I format USB stick to NTFS?

No. Mac can only see USB drive formatted with exFAT or MS-FAT. NTFS is not supported by Mac in default. So you can not write ISO image to NTFS USB on Mac. FAT32 is more recommended!

Q: How much time it takes for burning ISO to USB?

For high-speed USB drive (3.0 or 3.1), it can be done within 10 minutes. For low-speed USB drive, it takes much longers (more than 20 minutes).

Q: Can I use UNetbootin for burning Windows 10 ISO?

No. USB will not be bootable if you are using UNetbootin to burn ISO to USB on Mac.

Q: Can I use Etcher for burning Windows ISO?

No. You will receive 'Partition table missing' error when importing Windows ISO into Etcher app on Mac.


To be honest, Burning ISO to USB was not challenging at all on Mac in the past. But the situation was changed since the release of macOS. Many apps was not supported or updated to Catalina, Mojave or High Serria. So for the new Mac computer, UUByte ISO Editor is the best option out there in 2020.

A Python-based, open source, platform independent, utility to communicate with the ROM bootloader in Espressif ESP8266 & ESP32 chips.

Burn New Bootloader Esp32 Flash Download Tool Mac Data Recovery

esptool.py was started by Fredrik Ahlberg (@themadinventor) as an unofficial community project. It is now also supported by Espressif. Current primary maintainer is Angus Gratton (@projectgus).

esptool.py is Free Software under a GPLv2 license.

Installation / dependencies¶

Easy Installation¶

You will need either Python 2.7 or Python 3.4 or newer installed on your system.

The latest stable esptool.py release can be installed from pypi via pip:

With some Python installations this may not work and you’ll receive an error, try python-mpipinstallesptool or pip2installesptool.

After installing, you will have esptool.py installed into the default Python executables directory and you should be able to run it with the command esptool.py.

Manual Installation¶

Manual installation allows you to run the latest development version from this repository.

esptool.py depends on pySerial version 3.0 or newer for serial communication with the target device.

If you choose to install esptool.py system-wide by running pythonsetup.pyinstall, then this will be taken care of automatically.

If not using setup.py, then you’ll have to install pySerial manually by running something like pipinstallpyserial, easy_installpyserial or apt-getinstallpython-serial, depending on your platform. (The official pySerial installation instructions are here).

esptool.py also bundles the pyaes & ecdsa Python modules as “vendored” libraries. These modules are required when using the ESP32-only espsecure.py and espefuse.py tools. If you install esptool.py via pip or setup.py as shown above, then versions of these libraries will be installed from pypi. If you run esptool.py from the repository directory directly, it will use the “vendored” versions.


Use esptool.py-h to see a summary of all available commands and command line options.

To see all options for a particular command, append -h to the command name. ie esptool.pywrite_flash-h.

Common Options¶

Serial Port¶

  • The serial port is selected using the -p option, like -p/dev/ttyUSB0 (Linux and macOS) or -pCOM1 (Windows).
  • A default serial port can be specified by setting the ESPTOOL_PORT environment variable.
  • If no -p option or ESPTOOL_PORT value is specified, esptool.py will enumerate all connected serial ports and try each one until it finds an Espressif device connected (new behaviour in v2.4.0).

Note: Windows and macOS may require drivers to be installed for a particular USB/serial adapter, before a serial port is available. Consult the documentation for your particular device. On macOS, you can also consult System Information’s list of USB devices to identify the manufacturer or device ID when the adapter is plugged in. On Windows, you can use Windows Update or Device Manager to find a driver.

If using Cygwin or WSL on Windows, you have to convert the Windows-style name into an Unix-style path (COM1 -> /dev/ttyS0, and so on). (This is not necessary if using esp-idf for ESP32 with the supplied Windows MSYS2 environment, this environment uses a native Windows Python which accepts COM ports as-is.)

In Linux, the current user may not have access to serial ports and a “Permission Denied” error will appear. On most Linux distributions, the solution is to add the user to the dialout group with a command like sudousermod-a-Gdialout<USERNAME>. Check your Linux distribution’s documentation for more information.

Baud rate¶

The default esptool.py baud rate is 115200bps. Different rates may be set using -b921600 (or another baudrate of your choice). A default baud rate can also be specified using the ESPTOOL_BAUD environment variable. This can speed up write_flash and read_flash operations.

The baud rate is limited to 115200 when esptool.py establishes the initial connection, higher speeds are only used for data transfers.

Most hardware configurations will work with -b230400, some with -b460800, -b921600 and/or -b1500000 or higher.

If you have connectivity problems then you can also set baud rates below 115200. You can also choose 74880, which is the usual baud rate used by the ESP8266 to output boot log information.


Write binary data to flash: write_flash¶

Binary data can be written to the ESP’s flash chip via the serial write_flash command:

Multiple flash addresses and file names can be given on the same command line:

The --chip argument is optional when writing to flash, esptool will detect the type of chip when it connects to the serial port.

The --port argument is documented under Serial Port.

The next arguments to write_flash are one or more pairs of offset (address) and file name. When generating ESP8266 “version 1” images, the file names created by elf2image include the flash offsets as part of the file name. For other types of images, consult your SDK documentation to determine the files to flash at which offsets.

Numeric values passed to write_flash (and other commands) can be specified either in hex (ie 0x1000), or in decimal (ie 4096).

See the Troubleshooting section if the write_flash command is failing, or the flashed module fails to boot.

Setting flash mode and size¶

You may also need to specify arguments for flash mode and flash size, if you wish to override the defaults. For example:

Since esptool v2.0, these options are not often needed as the default is to keep the flash mode and size from the .bin image file, and to detect the flash size. See the Flash Modes section for more details.


Esp32 Firmware Update

By default, the serial transfer data is compressed for better performance. The -u/--no-compress option disables this behaviour.

Read Flash Contents: read_flash¶

The read_flash command allows reading back the contents of flash. The arguments to the command are an address, a size, and a filename to dump the output to. For example, to read a full 2MB of attached flash:

(Note that if write_flash updated the boot image’s flash mode and flash size during flashing then these bytes may be different when read back.)

Erase Flash: erase_flash & erase region¶

To erase the entire flash chip (all data replaced with 0xFF bytes):

To erase a region of the flash, starting at address 0x20000 with length 0x4000 bytes (16KB):

The address and length must both be multiples of the SPI flash erase sector size. This is 0x1000 (4096) bytes for supported flash chips.

Read built-in MAC address: read_mac¶

Read SPI flash id: flash_id¶

Example output:

Refer to flashrom source code for flash chip manufacturer name and part number.

Convert ELF to Binary: elf2image¶

The elf2image command converts an ELF file (from compiler/linker output) into the binary executable images which can be flashed and then booted into:

This command does not require a serial connection.

elf2image also accepts the Flash Modes arguments --flash_freq and --flash_mode, which can be used to set the default values in the image header. This is important when generating any image which will be booted directly by the chip. These values can also be overwritten via the write_flash command, see the write_flash command for details.

elf2image for ESP8266¶

The default command output is two binary files: my_app.elf-0x00000.bin and my_app.elf-0x40000.bin. You can alter the firmware file name prefix using the --output/-o option.

elf2image can also produce a “version 2” image file suitable for use with a software bootloader stub such as rboot or the Espressif bootloader program. You can’t flash a “version 2” image without also flashing a suitable bootloader.

elf2image for ESP32¶

For esp32, elf2image produces a single output binary “image file”. By default this has the same name as the .elf file, with a .bin extension. ie:

In the above example, the output image file would be called my_esp32_app.bin.

Output .bin image details: image_info¶

The image_info command outputs some information (load addresses, sizes, etc) about a .bin file created by elf2image.

Note that --chipesp32 is required when reading ESP32 images. Otherwise the default is --chipesp8266 and the image will be interpreted as an invalid ESP8266 image.

Advanced Commands¶

The following commands are less commonly used, or only of interest to advanced users. They are documented on the wiki:

Additional ESP32 Tools¶

The following tools for ESP32, bundled with esptool.py, are documented on the wiki:

Serial Connections¶

The ESP8266 & ESP32 ROM serial bootloader uses a 3.3V UART serial connection. Many development boards make the serial connections for you onboard.

However, if you are wiring the chip yourself to a USB/Serial adapter or similar then the following connections must be made:

ESP32/ESP8266 PinSerial Port Pin
TX (aka GPIO1)RX (receive)
RX (aka GPIO3)TX (transmit)

Note that TX (transmit) on the ESP8266 is connected to RX (receive) on the serial port connection, and vice versa.

Do not connect the chip to 5V TTL serial adapters, and especially not to “standard” RS-232 adapters! 3.3V serial only!

Entering the Bootloader¶

Both ESP8266 and ESP32 have to be reset in a certain way in order to launch the serial bootloader.

On some development boards (including NodeMCU, WeMOS, HUZZAH Feather, Core Board, ESP32-WROVER-KIT), esptool.py can automatically trigger a reset into the serial bootloader - in which case you don’t need to read this section.

For everyone else, three things must happen to enter the serial bootloader - a reset, required pins set correctly, and GPIO0 pulled low:

Boot Mode¶

Both ESP8266 and ESP32 chooses the boot mode each time it resets. A reset event can happen in one of several ways:

  • Power applied to chip.
  • The nRESET pin was low and is pulled high (on ESP8266 only).
  • The CH_PD/EN pin (“enable”) pin was low and is pulled high.

On ESP8266, both the nRESET and CH_PD pins must be pulled high for the chip to start operating.

For more details on selecting the boot mode, see the following Wiki pages:

Flash Modes¶

write_flash and some other comands accept command line arguments to set bootloader flash mode, flash size and flash clock frequency. The chip needs correct mode, frequency and size settings in order to run correctly - although there is some flexibility. A header at the beginning of a bootable image contains these values.

To override these values, the options --flash_mode, --flash_size and/or --flash_freq must appear after write_flash on the command line, for example:

These options are only consulted when flashing a bootable image to an ESP8266 at offset 0x0, or an ESP32 at offset 0x1000. These are addresses used by the ROM bootloader to load from flash. When flashing at all other offsets, these arguments are not used.

Flash Mode (–flash_mode, -fm)¶

These set Quad Flash I/O or Dual Flash I/O modes. Valid values are keep, qio, qout, dio, dout. The default is keep, which keeps whatever value is already in the image file. This parameter can also be specified using the environment variable ESPTOOL_FM.

Most boards use qio mode. Some ESP8266 modules, including the ESP-12E modules on some (not all) NodeMCU boards, are dual I/O and the firmware will only boot when flashed with --flash_modedio. Most ESP32 modules are also dual I/O.

In qio mode, two additional GPIOs (9 and 10) are used for SPI flash communications. If flash mode is set to dio then these pins are available for other purposes.

Burn New Bootloader Esp32 Flash Download Tool Mac Os

For a full explanation of these modes, see the SPI Flash Modes wiki page.

Flash Frequency (–flash_freq, -ff)¶

Clock frequency for SPI flash interactions. Valid values are keep, 40m, 26m, 20m, 80m (MHz). The default is keep, which keeps whatever value is already in the image file. This parameter can also be specified using the environment variable ESPTOOL_FF.

The flash chip connected to most chips works with 40MHz clock speeds, but you can try lower values if the device won’t boot. The highest 80MHz flash clock speed will give best performance, but may cause crashing if the flash or board designis not capable of this speed.

Flash Size (–flash_size, -fs)¶

Size of the SPI flash, given in megabytes. Valid values vary by chip type:

Chipflash_size values
ESP32detect, 1MB, 2MB, 4MB, 8MB, 16MB
ESP8266detect, 256KB, 512KB, 1MB, 2MB, 4MB, 2MB-c1, 4MB-c1, 8MB, 16MB

For ESP8266, some additional sizes & layouts for OTA “firmware slots” are available.

The default --flash_size parameter is detect, which tries to autodetect size based on SPI flash ID. If detection fails, a warning is printed and a default value of of 4MB (4 megabytes) is used.

If flash size is not successfully detected, you can find the flash size by using the flash_id command and then looking up the ID from the output (see Read SPI flash id). Alternatively, read off the silkscreen labelling of the flash chip and search for its datasheet.

Esp32 Flash Download Tool V3.6.4

The default flash_size parameter can also be overriden using the environment variable ESPTOOL_FS.

ESP8266 and Flash Size¶

The ESP8266 SDK stores WiFi configuration at the “end” of flash, and it finds the end using this size. However there is no downside to specifying a smaller flash size than you really have, as long as you don’t need to write an image larger than this size.

ESP-12, ESP-12E and ESP-12F modules (and boards that use them such as NodeMCU, HUZZAH, etc.) usually have at least 4 megabyte / 4MB (sometimes labelled 32 megabit) flash.

If using OTA, some additional sizes & layouts for OTA “firmware slots” are available. If not using OTA updates then you can ignore these extra sizes:

flash_size argNumber of OTA slotsOTA Slot SizeNon-OTA Space
256KB1 (no OTA)256KBN/A
512KB1 (no OTA)512KBN/A
8MB [^]21024KB6144KB
16MB [^]21024KB14336KB
  • [^] Support for 8MB & 16MB flash size is not present in all ESP8266 SDKs. If your SDK doesn’t support these flash sizes, use --flash_size4MB.

ESP32 and Flash Size¶

The ESP32 esp-idf flashes a partition table to the flash at offset 0x8000. All of the partitions in this table must fit inside the configured flash size, otherwise the ESP32 will not work correctly.

Advanced Options¶

See the Advanced Options wiki page for some of the more unusual esptool.py command line options.

Remote Serial Ports¶

It is possible to connect to any networked remote serial port that supports RFC2217 (Telnet) protocol, or a plain TCP socket. See the Remote Serial Ports wiki page for details.


Esp32 Erase Flash

Flashing problems can be fiddly to troubleshoot. Try the suggestions here if you’re having problems:

Bootloader won’t respond¶

If you see errors like “Failed to connect” then your chip is probably not entering the bootloader properly:

  • Check you are passing the correct serial port on the command line.
  • Check you have permissions to access the serial port, and other software (such as modem-manager on Linux) is not trying to interact with it. A common pitfall is leaving a serial terminal accessing this port open in another window and forgetting about it.
  • Check the chip is receiving 3.3V from a stable power source (see Insufficient Power for more details.)
  • Check that all pins are connected as described in Entering the bootloader. Check the voltages at each pin with a multimeter, “high” pins should be close to 3.3V and “low” pins should be close to 0V.
  • If you have connected other devices to GPIO pins mentioned above section, try removing them and see if esptool.py starts working.
  • Try using a slower baud rate (-b9600 is a very slow value that you can use to verify it’s not a baud rate problem.)

write_flash operation fails part way through¶

If flashing fails with random errors part way through, retry with a lower baud rate.

Power stability problems may also cause this (see Insufficient Power.)

write_flash succeeds but program doesn’t run¶

If esptool.py can flash your module with write_flash but your program doesn’t run, try the following:

Wrong Flash Mode¶

Some devices only support the dio flash mode. Writing to flash with qio mode will succeed but the chip can’t read the flash back to run - so nothing happens on boot. Try passing the -fmdio option to write_flash.

See the SPI Flash Modes wiki page for a full description of the flash modes and how to determine which ones are supported on your device.

Insufficient Power¶

The 3.3V power supply for the ESP8266 and ESP32 has to supply large amounts of current (up to 70mA continuous, 200-300mA peak, slightly higher for ESP32). You also need sufficient capacitance on the power circuit to meet large spikes of power demand.

Insufficient Capacitance¶

If you’re using a pre-made development board or module then the built-in power regulator & capacitors are usually good enough, provided the input power supply is adequate.

This is not true for some very simple pin breakout modules - `similar to this <https://user-images.githubusercontent.com/205573/30140831-9da417a6-93ba-11e7-95c3-f422744967de.jpg>`_. These breakouts do not integrate enough capacitance to work reliably without additional components.. Surface mount OEM modules like ESP-WROOM02 and ESP-WROOM32 require an external bulk capacitor on the PCB to be reliable, consult the module datasheet.

Power Supply Rating¶

It is possible to have a power supply that supplies enough current for the serial bootloader stage with esptool.py, but not enough for normal firmware operation. You may see the 3.3V VCC voltage droop down if you measure it with a multimeter, but you can have problems even if this isn’t happening.

Try swapping in a 3.3V supply with a higher current rating, add capacitors to the power line, and/or shorten any 3.3V power wires.

The 3.3V output from FTDI FT232R chips/adapters or Arduino boards do not supply sufficient current to power an ESP8266 or ESP32 (it may seem to work sometimes, but it won’t work reliably). Other USB TTL/serial adapters may also be marginal.

Missing bootloader¶

Recent ESP8266 SDKs and the ESP32 esp-idf both use a small firmware bootloader program. The hardware bootloader in ROM loads this firmware bootloader from flash, and then it runs the program. On ESP8266. firmware bootloader image (with a filename like boot_v1.x.bin) has to be flashed at offset 0. If the firmware bootloader is missing then the ESP8266 will not boot. On ESP32, the bootloader image should be flashed by esp-idf at offset 0x1000.

Refer to SDK or esp-idf documentation for details regarding which binaries need to be flashed at which offsets.

SPI Pins which must be disconnected¶

Compared to the ROM bootloader that esptool.py talks to, a running firmware uses more of the chip’s pins to access the SPI flash.

If you set “Quad I/O” mode (-fmqio, the esptool.py default) then GPIOs 7, 8, 9 & 10 are used for reading the SPI flash and must be otherwise disconnected.

If you set “Dual I/O” mode (-fmdio) then GPIOs 7 & 8 are used for reading the SPI flash and must be otherwise disconnected.

Try disconnecting anything from those pins (and/or swap to Dual I/O mode if you were previously using Quad I/O mode but want to attach things to GPIOs 9 & 10). Note that if GPIOs 9 & 10 are also connected to input pins on the SPI flash chip, they may still be unsuitable for use as general purpose I/O.

In addition to these pins, GPIOs 6 & 11 are also used to access the SPI flash (in all modes). However flashing will usually fail completely if these pins are connected incorrectly.

Early stage crash¶

Use a serial terminal program to view the boot log. (ESP8266 baud rate is 74880bps, ESP32 is 115200bps). See if the program is crashing during early startup or outputting an error message.

Serial Terminal Programs¶

There are many serial terminal programs suitable for debugging & serial interaction. The pyserial module (which is required for esptool.py) includes one such command line terminal program - miniterm.py. For more details see this page or run miniterm-h.

Note that not every serial program supports the unusual ESP8266 74880bps “boot log” baud rate. Support is especially sparse on Linux. miniterm.py supports this baud rate on all platforms. ESP32 uses the more common 115200bps.

Tracing esptool.py interactions¶

Running esptool.py--trace will dump all serial interactions to the standard output (this is a lot of output). This can be helpful when debugging issues with the serial connection, or when providing information for bug reports.

Using esptool.py from Python¶

esptool.py can easily be integrated into Python applications or called from other Python scripts.

While it currently does have a poor Python API, something which #208 will address, it allows for passing CLIarguments to esptool.main(). This workaround makes integration very straightforward as you can pass exactly thesame arguments as you would on the CLI.

Internal Technical Documentation¶

The repository wiki contains some technical documentation regarding the serial protocol and file format used by the ROM bootloader. This may be useful if you’re developing esptool.py or hacking system internals:


esptool.py was initially created by Fredrik Ahlberg (@themadinventor, @kongo), and is currently maintained by Angus Gratton (@projectgus). It has also received improvements from many members of the ESP8266 community - including @rojer, @jimparis, @jms19, @pfalcon, @tommie, @0ff, @george-hopkins and others.

This document and the attached source code are released under GNU General Public License Version 2. See the accompanying file LICENSE for a copy.