Before you can load your firmware, you'll need to install esptool. Follow the instructions found here.

Next up you need to determine the Serial Port the board is connected to.

  • For ESP32 boards, just plug it into your computer.
  • For ESP32-S2/S3/C3 boards, plug in and then launch 'bootloader' mode by holding down BOOT or B0 button while clicking reset. Then release both buttons.

If you're on something like a Mac or Linux, run ls /dev/tty.* to find all serial devices, it will be called something like /dev/tty.usbserial or /dev/ttyUSB0 or /dev/ttyACM0 or /dev/tty.SLABtoUSB or similar!

It will probably not be a shorter name /dev/tty23.

If you're using Windows, the port will be something like COM2 (check the Device Manager to determine your port)

If you are having difficulty determining which port is the board, try the "ls /dev/tty.*" or Device Manager listing WITHOUT the board plugged in, then plug in the board and look again - what name is new that wasn't there before?

Once you have esptool installed, you will first want to erase the flash on your ESP32 board, it's also a great way to determine that you are able to connect. You can do so by running something similar to the following command. Make sure you update the port to match the serial port to which your board is connected, i.e. change /dev/tty.usbserial-1144440 to match your connection.

esptool.py --chip esp32 --port /dev/tty.usbserial-1144440 erase_flash

or - if you're not 100% sure which ESP32 chip you have, you can just specify the port

esptool.py --port COM13 erase_flash

Once the flash is successfully erased, you can load your firmware .bin file by running something similar to the command below. Make sure you update the following:

  • The port to match the serial port to which your board is connected, i.e. change /dev/tty.usbserial-1144440 to match your connection.
  • The firmware.bin file name to match the firmware you downloaded, i.e. change firmware.bin to something like esp32spiram-20220117-v1.18.bin or adafruit-circuitpython-esp32-8.0.bin
  • This command assumes you will be loading it to address 0x0, as we do for circuitpython. This may not be true for your firmware! check the documentation for the offset if necessary

Load the firmware using something similar to the following command, with the above changes:

esptool.py --port /dev/tty.usbserial-1144440 write_flash -z 0x0 firmware.bin

To keep things simple we don't specify the chip or a faster upload speed - you can always add those options if you need to upload to many chips quickly

It's always a good idea to power cycle by unplugging-replugging, or pressing the reset button, to make sure the new firmware is running.

This guide was first published on Aug 18, 2022. It was last updated on Mar 08, 2024.

This page (Command line ESPTool) was last updated on Mar 08, 2024.

Text editor powered by tinymce.