Upgrading ESP32 Firmware
2019-11-22 | By Adafruit Industries
License: See Original Project
Courtesy of Adafruit
Guide by Brent Rubell
Overview
If you want to keep the firmware on your ESP32 WiFi co-processor up-to-date, you'll need to update the firmware on the ESP32.
You're going 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!
Why would I update my ESP32's firmware?
Using an ESP32 as a WiFi 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 and debug a SSL library.
Adafruit ships a variety of products which use the ESP32 as a WiFi co-processor with a variant of the Arduino nina-fw core. 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.
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 AirLift – ESP32 WiFi Co-Processor Breakout Board
- Adafruit AirLift FeatherWing – ESP32 WiFi Co-Processor
- Adafruit AirLift Shield - ESP32 WiFi Co-Processor
- Adafruit AirLift Bitsy Add-On – ESP32 WiFi Co-Processor
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.
- Adafruit PyPortal - CircuitPython Powered Internet Display
- Adafruit Metro M4 Express AirLift (WiFi) - Lite
Materials
- 1 x USB Cable
Upgrade All-in-One ESP32 AirLift Firmware
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 anyway.
Download the UF2 for your board to your Desktop.
Metro_M4_WiFi_ESP32_Passthru.UF2
PyBadge_M4_with_AirLift_Wing_Passthru.UF2
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.
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.
Uploading nina-fw with esptool
This section assumes you know how to use 'esptool' to upload firmware to your ESP! If you're not sure, check https://github.com/espressif/esptool and look for tutorials.
Click the link below to download the latest nina-fw .bin file. Unzip it and save the .bin file to your desktop.
If you're using macOS or Linux - run the following command, replacing /dev/ttys6 with the serial port of your board and NINA_W102-1.3.0 with the binary file you're flashing to the ESP32.
esptool.py --port /dev/ttyS6 --before no_reset --baud 115200 write_flash 0 NINA_W102-1.3.0.bin
If you're using Windows - run the following command, replacing COM7 with the serial port of your board and NINA_W102-1.3.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.3.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.
If you were previously using your ESP32 with Arduino, you should load up an Arduino sketch to verify everything is working properly and the version of the nina-fw correlates with the version the sketch reads.
Open up File->Examples->WiFiNINA->ScanNetworks and upload the sketch. Then, open the Serial Monitor. You should see the firmware version printed out to the serial monitor.
CircuitPython
If you were previously using your ESP32 with CircuitPython, you'll need to first reinstall CircuitPython firmware (UF2) for your board. The QSPI flash should have retained its contents. If you don't see anything on the CIRCUITPY volume, copy files from the backup you made earlier over to CIRCUITPY.
To verify the new ESP32 WiFi firmware version is correct, follow the Connect to WiFi step in this guide and come back here when you've successfully ran the code. The REPL output should display the firmware version you uploaded.
Upgrade External ESP32 Airlift Firmware
Bridging the ESP32's Optional Control Pins
External AirLift boards have three optional ESP32 control pins which are not connected by default:
- ESPGPIO0
- ESPRX
- ESPTX
Before continuing the steps on this page - you will need to add solder to connect the ESPTX, EXPRX and GPIO0 pads on the bottom of breakout.
Make sure you solder all three of these pads together. You will not be able to upload firmware to your ESP32 if they are not connected.
Code
With the ESP32's optional control pins soldered together, you'll be turning your airlift breakout, shield, or wing into a USB to Serial converter. To do this, you'll need a special Arduino sketch named SerialESPPassthrough.ino.
Click Download: Project ZIP to download the code below.
Download: Project Zip or SerialESPPassthrough.ino | View on Github
/*
SerialNINAPassthrough - Use esptool to flash the ESP32 module
For use with PyPortal, Metro M4 WiFi...
Copyright (c) 2018 Arduino SA. All rights reserved.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
#include <Adafruit_NeoPixel.h>
unsigned long baud = 115200;
#if defined(ADAFRUIT_FEATHER_M4_EXPRESS) || \
defined(ADAFRUIT_FEATHER_M0_EXPRESS) || \
defined(ARDUINO_AVR_FEATHER32U4) || \
defined(ARDUINO_NRF52840_FEATHER) || \
defined(ADAFRUIT_ITSYBITSY_M0_EXPRESS) || \
defined(ADAFRUIT_ITSYBITSY_M4_EXPRESS) || \
defined(ARDUINO_AVR_ITSYBITSY32U4_3V)
// Configure the pins used for the ESP32 connection
#define SerialESP32 Serial1
#define SPIWIFI SPI // The SPI port
#define SPIWIFI_SS 13 // Chip select pin
#define ESP32_RESETN 12 // Reset pin
#define SPIWIFI_ACK 11 // a.k.a BUSY or READY pin
#define ESP32_GPIO0 10
#define NEOPIXEL_PIN 8
#elif defined(ARDUINO_AVR_FEATHER328P)
#define SerialESP32 Serial1
#define SPIWIFI SPI // The SPI port
#define SPIWIFI_SS 4 // Chip select pin
#define ESP32_RESETN 3 // Reset pin
#define SPIWIFI_ACK 2 // a.k.a BUSY or READY pin
#define ESP32_GPIO0 -1
#define NEOPIXEL_PIN 8
#elif defined(TEENSYDUINO)
#define SerialESP32 Serial1
#define SPIWIFI SPI // The SPI port
#define SPIWIFI_SS 5 // Chip select pin
#define ESP32_RESETN 6 // Reset pin
#define SPIWIFI_ACK 9 // a.k.a BUSY or READY pin
#define ESP32_GPIO0 -1
#define NEOPIXEL_PIN 8
#elif defined(ARDUINO_NRF52832_FEATHER )
#define SerialESP32 Serial1
#define SPIWIFI SPI // The SPI port
#define SPIWIFI_SS 16 // Chip select pin
#define ESP32_RESETN 15 // Reset pin
#define SPIWIFI_ACK 7 // a.k.a BUSY or READY pin
#define ESP32_GPIO0 -1
#define NEOPIXEL_PIN 8
#elif !defined(SPIWIFI_SS) // if the wifi definition isnt in the board variant
// Don't change the names of these #define's! they match the variant ones
#define SerialESP32 Serial1
#define SPIWIFI SPI
#define SPIWIFI_SS 10 // Chip select pin
#define SPIWIFI_ACK 7 // a.k.a BUSY or READY pin
#define ESP32_RESETN 5 // Reset pin
#define ESP32_GPIO0 -1 // Not connected
#define NEOPIXEL_PIN 8
#endif
Adafruit_NeoPixel pixel = Adafruit_NeoPixel(1, NEOPIXEL_PIN, NEO_GRB + NEO_KHZ800);
void setup() {
Serial.begin(baud);
pixel.begin();
pixel.setPixelColor(0, 10, 10, 10); pixel.show();
while (!Serial);
pixel.setPixelColor(0, 50, 50, 50); pixel.show();
delay(100);
SerialESP32.begin(baud);
pinMode(SPIWIFI_SS, OUTPUT);
pinMode(ESP32_GPIO0, OUTPUT);
pinMode(ESP32_RESETN, OUTPUT);
// manually put the ESP32 in upload mode
digitalWrite(ESP32_GPIO0, LOW);
digitalWrite(ESP32_RESETN, LOW);
delay(100);
digitalWrite(ESP32_RESETN, HIGH);
pixel.setPixelColor(0, 20, 20, 0); pixel.show();
delay(100);
}
void loop() {
while (Serial.available()) {
pixel.setPixelColor(0, 10, 0, 0); pixel.show();
SerialESP32.write(Serial.read());
}
while (SerialESP32.available()) {
pixel.setPixelColor(0, 0, 0, 10); pixel.show();
Serial.write(SerialESP32.read());
}
}
Code Usage
Unzip the file and open the SerialESPPassthrough.ino file in the Arduino IDE.
If you're using the AirLift FeatherWing, AirLift Shield or AirLift Bitsy Add-On, you do not need to make any modifications to the code.
If you have an AirLift Breakout (or are manually wiring up any of the boards above), change the following pin definitions in the sketch to match your wiring:
Download: file
#elif !defined(SPIWIFI_SS) // if the wifi definition isnt in the board variant
// Don't change the names of these #define's! they match the variant ones
#define SerialESP32 Serial1
#define SPIWIFI SPI
#define SPIWIFI_SS 10 // Chip select pin
#define SPIWIFI_ACK 7 // a.k.a BUSY or READY pin
#define ESP32_RESETN 5 // Reset pin
#define ESP32_GPIO0 -1 // Not connected
#define NEOPIXEL_PIN 8
#endif
Using the Arduino IDE, upload the code to your board (Sketch->Upload).
After uploading, the board should 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 in ls /dev/cu* or /dev/tty* (Mac or Linux) in a terminal
Burning 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.
This section assumes you know how to use 'esptool' to upload firmware to your ESP! If you're not sure, check https://github.com/espressif/esptool and look for tutorials.
If you're using macOS or Linux - run the following command, replacing /dev/ttys6 with the serial port of your board and NINA_W102-1.3.0 with the binary file you're flashing to the ESP32.
esptool.py --port /dev/ttyS6 --before no_reset --baud 115200 write_flash 0 NINA_W102-1.3.0.bin
If you're using Windows - run the following command, replacing COM7 with the serial port of your board and NINA_W102-1.3.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.3.0.bin
The command should detect the ESP32 and will take a minute or two to upload the firmware.
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.
Verifying the Upgraded Firmware Version
To verify everything is working correctly, we'll load up either an Arduino sketch or CircuitPython code. At this point, you may also want desolder the connections between the Optional ESP32 control pins you made earlier using a solder sucker or a bit of solder wick.
Arduino
If you were previously using your ESP32 with Arduino, you should load up an Arduino sketch to verify everything is working properly and the version of the nina-fw correlates with the version the sketch reads.
Open up File->Examples->WiFiNINA->ScanNetworks and upload the sketch. Then, open the Serial Monitor. You should see the firmware version printed out to the serial monitor.
CircuitPython
If you were previously using your ESP32 project with CircuitPython, you'll need to first reinstall CircuitPython firmware (UF2) for your board. The QSPI flash should have retained its contents. If you don't see anything on the CIRCUITPY volume, copy files from the backup you made earlier to CIRCUITPY.
To verify the new ESP32 WiFi firmware version is correct, follow the Connect to WiFi step in this guide and come back here when you've successfully ran the code. The REPL output should display the firmware version you flashed.
Have questions or comments? Continue the conversation on TechForum, DigiKey's online community and technical resource.
Visit TechForum