How to upload a compiled ESP32 sketch from command line to devices using esptool (Windows/Mac)

(この記事には日本語版があります)

I am using the Arduino IDE for developing ESP32 and uploading my sketch. Arduino IDE always executes compilation before uploading sketches to devices. This is so annoying when I have to upload my sketch with the same contents to dozens of boards. So I thought it's good that I keep a compiled binary then use it repeatedly for uploading. In this article, I will explain how I did that.

Environment

  • ESP32 board
  • Arduino IDE: v1.8.9
  • Host OS
    • Mac: OSX 10.14.6
    • Windows: Windows 10 Home ver. 1809

Preparations

Complete setting up the Arduino IDE and ESP32 SDK. It means you should be able to compile ESP32 sketches and write them to actual devices. Details of preparation are not covered in this article.

Procedure

Step 1.

Launch Arduino IDE and open the sketch you want to use.

Step 2.

Open the preferences window, check "Show verbose output during: upload". click the OK button and close the window.

Windows

Mac

Step 3.

Connect an ESP32 board to PC or Mac then compile and upload your sketch once. The detailed information will be displayed at the output area of the Arduino IDE's editor window.

Step 4.

Find the line that is running the esptool command in the output area. Copy the line entirely and save it in a text file to use later.

Step 5.

There are two places in the command line where the path of the file with the extension .bin that contains the name of your sketch is specified in the argument of theesptool command. Copy the two .bin files and store them somewhere.

For example, when the ESP32 WatchdogTimer sample was compiled and uploaded, the following two .bin files that contain the sketch name(WatchdogTimer) were obtained.

  • WatchdogTimer.ino.bin
  • WatchdogTimer.ino.partitions.bin

After compiling & uploading(Windows)

C:\Users\hogehoge\Documents\ArduinoData\packages\esp32\tools\esptool_py\2.6.1/esptool.exe --chip esp32 --port COM7 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 80m --flash_size detect 0xe000 C:\Users\hogehoge\Documents\ArduinoData\packages\esp32\hardware\esp32\1.0.4/tools/partitions/boot_app0.bin 0x1000 C:\Users\hogehoge\Documents\ArduinoData\packages\esp32\hardware\esp32\1.0.4/tools/sdk/bin/bootloader_qio_80m.bin 0x10000 C:\Users\hogehoge\AppData\Local\Temp\arduino_build_425707/WatchdogTimer.ino.bin 0x8000 C:\Users\hogehoge\AppData\Local\Temp\arduino_build_425707/WatchdogTimer.ino.partitions.bin
esptool.py v2.6
After compiling & uploading(Mac)

/Users/hogehoge/Library/Arduino15/packages/esp32/tools/esptool_py/2.6.1/esptool --chip esp32 --port /dev/cu.usbserial-XXXXXXXX --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 80m --flash_size detect 0xe000 /Users/hogehoge/Library/Arduino15/packages/esp32/hardware/esp32/1.0.3/tools/partitions/boot_app0.bin 0x1000 /Users/hogehoge/Library/Arduino15/packages/esp32/hardware/esp32/1.0.3/tools/sdk/bin/bootloader_qio_80m.bin 0x10000 /var/folders/8q/zz5yryg10bs8h6n8rktc_mtw0000gq/T/arduino_build_834564/WatchdogTimer.ino.bin 0x8000 /var/folders/8q/zz5yryg10bs8h6n8rktc_mtw0000gq/T/arduino_build_834564/WatchdogTimer.ino.partitions.bin

Final Step

If you are using Mac, open Terminal.app or similar, or if you are using Windows, open cmd.exe and navigate to the folder/directory where you saved the .bin files. Open the text file you saved the esptool command line, change the path of <your sketch name>.ino.bin and <your sketch name>.ino.partitions.bin. Copy the command line and paste it to the Terminal.app or cmd.exe. And hit the enter key. This will start uploading the compiled firmware to an ESP32 device.

Result of uploading(Windows)

F:\tmp>C:\Users\hogehoge\Documents\ArduinoData\packages\esp32\tools\esptool_py\2.6.1/esptool.exe --chip esp32 --port COM7 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 80m --flash_size detect 0xe000 C:\Users\hogehoge\Documents\ArduinoData\packages\esp32\hardware\esp32\1.0.4/tools/partitions/boot_app0.bin 0x1000 C:\Users\hogehoge\Documents\ArduinoData\packages\esp32\hardware\esp32\1.0.4/tools/sdk/bin/bootloader_qio_80m.bin 0x10000 .\WatchdogTimer.ino.bin 0x8000 .\WatchdogTimer.ino.partitions.bin
esptool.py v2.6
Serial port COM7
Connecting....
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core, Coding Scheme None
MAC: XX:XX:XX:XX:XX:XX
Uploading stub...
~ ~ ~ snip ~ ~ ~
Hash of data verified.
Compressed 3072 bytes to 128...
Wrote 3072 bytes (128 compressed) at 0x00008000 in 0.0 seconds (effective 1638.4 kbit/s)...
Hash of data verified.

Leaving...
Hard resetting via RTS pin...

F:\tmp>

Result of uploading(Mac)

$ /Users/hogehoge/Library/Arduino15/packages/esp32/tools/esptool_py/2.6.1/esptool --chip esp32 --port /dev/cu.usbserial-XXXXXXXX --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 80m --flash_size detect 0xe000 /Users/hogehoge/Library/Arduino15/packages/esp32/hardware/esp32/1.0.3/tools/partitions/boot_app0.bin 0x1000 /Users/hogehoge/Library/Arduino15/packages/esp32/hardware/esp32/1.0.3/tools/sdk/bin/bootloader_qio_80m.bin 0x10000 ./WatchdogTimer.ino.bin 0x8000 ./WatchdogTimer.ino.partitions.bin
esptool.py v2.6
Serial port /dev/cu.usbserial-XXXXXXXX
Connecting....
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core, Coding Scheme None
MAC: XX:XX:XX:XX:XX:XX
Uploading stub...
~ ~ ~ snip ~ ~ ~
Hash of data verified.
Compressed 3072 bytes to 128...
Wrote 3072 bytes (128 compressed) at 0x00008000 in 0.0 seconds (effective 1528.7 kbit/s)...
Hash of data verified.

Leaving...
Hard resetting via RTS pin...
$

Additional notes

  • When you execute "Export Compiled Binary" from the Arduino IDE menu, a .bin file is created in the same location as your sketch. the contents of this .bin file is as same as the <your sketch name>.ino.bin.

  • Depending on the ESP32 board, the serial port number may change if you connect a physically different board to your PC/Mac. When uploading firmware from a command line, it is necessary to specify the serial port number of the board currently connected to your PC with the --port option.

Conclusion

How to write a compiled ESP32 firmware image from the command line using the esptool command has been explained. You can reduce annoying GUI operations and save your time a little bit by using this method. If you know a smarter way, I'd love to hear from you!

References