adafruit learning system ESP32 User manual

Upgrading ESP32 Firmware
Created by Brent Rubell
Last updated on 2021-03-29 01:04:43 PM EDT

2
3
3
3
3
5
7
8
8
9
10
10
10
11
12
12
13
14
14
15
15
16
16
16
18
18
19
19
20
22
23
23
Guide Contents
Guide Contents
Overview
Why would I update my ESP32's firmware?
Parts
External ESP32 Co-Processors
ESP32 Co-Processor All-in-One Boards
Materials
Upgrade All-in-One ESP32 AirLift Firmware
Uploading Serial Passthrough Code
Install esptool.py
Uploading nina-fw with esptool
Verifying the Upgraded Firmware Version
Arduino
CircuitPython
Upgrade External ESP32 Airlift Firmware
External AirLift FeatherWing, Shield, or ItsyWing
Upload Serial Passthrough code for Feather or ItsyBitsy
External AirLift Breakout
Code Usage
Install esptool.py
Burning nina-fw with esptool
Verifying the Upgraded Firmware Version
Arduino
CircuitPython
Upgrade RP2040 AirLift Firmware
Upload Serial Passthrough Code
Download NINA Firmware
Flash AirLift using Web Serial ESPTool
Enable Chrome's Web Serial API
Flash AirLift using esptool.py
Burning nina-fw with esptool
Verifying the Upgraded Firmware Version
© Adafruit Industries https://learn.adafruit.com/upgrading-esp32-firmware Page 2 of 25

Overview
If you want to keep the firmware on your ESP32 WiFi-BLE co-processor up-to-date, you'll need to update
the firmware on the ESP32.
You're going to to turn your board into a USB-to-Serial converter to flash new firmware to your ESP32 -
no extra hardware required !
This process is mostly setup and should take from 10 to 20 minutes.
 This guide is not for when you are running Arduino/MicroPython/FreeRTOS/etc *directly* on the
ESP32, this is only for using the ESP32 as an AirLift/WiFi co-processor!
 To support BLE on the ESP32 AirLift, you'll need NINA_W102-1.7.1.bin or later.
Why would I update my ESP32's firmware?
Using an ESP32 as a WiFi-BLE co-processor is a way to connect your CircuitPython and Arduino projects
to the internet. Having WiFi managed by a separate chip means your code is simpler, you don't have to
cache socket data, or compile in & debug an SSL library.
Adafruit ships a variety of products which use the ESP32 as a WiFi-BLE co-processor with a variant of the
Arduino nina-fw core (https://adafru.it/FWj). This firmware is programmed to the ESP32 at the Adafruit
factory. If you wish to update to a newer version of nina-fw, you'll need to program it to the ESP32.
BLE is supported on the ESP32 co-processor only with version NINA_W102-1.7.1.bin or later of the
firmware (released in October 2020). If you want BLE support, it is quite likely you'll need to upgrade
Parts
External ESP32 Co-Processors
If you already have a project which uses a popular microcontroller (like the ATMega328 or ATSAMD51),
you can easily add WiFi by using an externally connected ESP32 module.
© Adafruit Industries https://learn.adafruit.com/upgrading-esp32-firmware Page 3 of 25

Adafruit AirLift – ESP32 WiFi Co-Processor Breakout Board
Give your plain ol' microcontroller project a lift with the Adafruit AirLift - a breakout board that lets you use
the powerful ESP32 as a WiFi co-processor. You probably...
$9.95
In Stock
Add to Cart
© Adafruit Industries https://learn.adafruit.com/upgrading-esp32-firmware Page 4 of 25

Adafruit AirLift FeatherWing – ESP32 WiFi Co-Processor
Give your Feather project a lift with the Adafruit AirLift FeatherWing - a FeatherWing that lets you use the
powerful ESP32 as a WiFi co-processor. You probably have your...
$12.95
In Stock
Adafruit AirLift Shield - ESP32 WiFi Co-Processor
Give your Arduino project a lift with the Adafruit AirLift Shield - a shield that lets you use the powerful
ESP32 as a WiFi co-processor. You probably have your favorite...
$14.95
In Stock
Your browser does not support the video tag.
Adafruit AirLift Bitsy Add-On – ESP32 WiFi Co-Processor
Give your ItsyBitsy project a lift with the Adafruit AirLift Bitsy Add-On - a daughterboard that lets you use
the powerful ESP32 as a WiFi co-processor. You probably have your...
Out of Stock
ESP32 Co-Processor All-in-One Boards
Don't want to add extra hardware to your project? Consider grabbing a board which has an ESP32 WiFi
co-processor built-in.
Add to Cart
Add to Cart
Out of
Stock
© Adafruit Industries https://learn.adafruit.com/upgrading-esp32-firmware Page 5 of 25

Adafruit PyPortal - CircuitPython Powered Internet Display
PyPortal, our easy-to-use IoT device that allows you to create all the things for the “Internet of Things” in
minutes. Make custom touch screen interface...
Out of Stock
Adafruit Metro M4 Express AirLift (WiFi) - Lite
Out of
Stock
© Adafruit Industries https://learn.adafruit.com/upgrading-esp32-firmware Page 6 of 25

Give your next project a lift with AirLift - our witty name for the ESP32 co-processor that graces this Metro
M4. You already know about the Adafruit Metro...
$34.95
In Stock
Materials
1 x USB Cable
USB cable - USB A to Micro-B - 3 foot long
Add to Cart
Add to Cart
© Adafruit Industries https://learn.adafruit.com/upgrading-esp32-firmware Page 7 of 25

Upgrade All-in-One ESP32 AirLift Firmware
 To support BLE on the ESP32 AirLift, you'll need NINA_W102-1.7.1.bin or later.
Uploading Serial Passthrough Code
First, back up any code and files you have on your CIRCUITPY drive . It will be overwritten by the code
you're going to upload to your board. You should not end up losing any files on the QSPI flash, but it's a
good idea to back them up anyways.
Download the UF2 for your board to your Desktop.
https://adafru.it/Ep1
https://adafru.it/END
https://adafru.it/Obx
https://adafru.it/F98
Find the reset button on your board. It's a small, black button, and on most of the boards, it will be the only
button available.
Tap this button twice to enter the bootloader. If it doesn't work on the first try, don't be discouraged. The
rhythm of the taps needs to be correct and sometimes it takes a few tries.
Once successful, the RGB LED on the board will flash red and then stay green. A new drive will show up
on your computer. The drive will be called boardnameBOOT where boardname is a reference to your
specific board. For example, a Feather will have FEATHERBOOT and a Trinket will
have TRINKETBOOT etc. Going forward we'll just call the boot drive BOOT
https://adafru.it/Ep1
https://adafru.it/END
https://adafru.it/Obx
https://adafru.it/F98
© Adafruit Industries https://learn.adafruit.com/upgrading-esp32-firmware Page 8 of 25

The board is now in bootloader mode. Now find the UF2 file you downloaded. Drag that file to
the BOOT drive on your computer.
The lights should flash again, BOOT will disappear. It should re-enumerate USB and appear as a COM or
Serial port on your computer. Make a note of the serial port by checking the Device Manager (windows) or
typing ls /dev/cu* or /dev/tty* (Mac or Linux) in a terminal.
If you see your board listed in the terminal: Proceed to the Uploading nina-fw with esptool section of this
page.
 This guide assumes you have Python3 installed. If you have not installed it, navigate to the Python
downloads page (https://www.python.org/downloads) and install the latest release.
Install esptool.py
Esptool is an application which can communicate with the ROM bootloader (https://adafru.it/LKe) in
Espressif chips.
To install esptool, run the following in your terminal :
pip3 install esptool
© Adafruit Industries https://learn.adafruit.com/upgrading-esp32-firmware Page 9 of 25

Uploading nina-fw with esptool
Click the link below to download the latest nina-fw .bin file. Unzip it and save the .bin file to your desktop .
https://adafru.it/G3D
If you're using macOS or Linux - run the following command, replacing /dev/ttyACM0 with the serial port of
your board and NINA_W102-1.6.0 with the binary file you're flashing to the ESP32.
esptool.py --port /dev/ttyACM0 --before no_reset --baud 115200 write_flash 0 NINA_W102-1.6.0.bin
If you're using Windows - run the following command, replacing COM7 with the serial port of your board
and NINA_W102-1.6.0 with the binary file you're flashing to the ESP32
esptool.py --port COM7 --before no_reset --baud 115200 write_flash 0 NINA_W102-1.6.0.bin
The command should detect the ESP32 and will take a minute or two to upload the firmware. The NeoPixel
on your board will flicker and flash as the firmware uploads.
If ESPTool doesn't detect the ESP32 , make sure you've uploaded the correct .UF2 file to the bootloader.
Once the firmware is fully uploaded, the ESP32 will reset and the NeoPixel will glow blue.
Verifying the Upgraded Firmware Version
Arduino
To verify everything is working correctly, we'll load up either an Arduino sketch or CircuitPython code.
https://adafru.it/G3D
© Adafruit Industries https://learn.adafruit.com/upgrading-esp32-firmware Page 10 of 25