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.

Air_1

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.

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.

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.

PyPortal_ESP32_Passthru.UF2

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.

reset_2

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.

boot_3

The board is now in bootloader mode. Now find the UF2 file you downloaded. Drag that file to the BOOT drive on your computer.

drive_4

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.

lu_6

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.

Latest nina-fw .bin file

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.

desktop_7

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.

Alerts_8

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.

code_py_9

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.

jumpers_10

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

Copy Code

/*
  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

Copy Code

#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

port_11

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.

Latest nina-fw .bin file

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.

upload_12

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

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.

version_13

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.

Mu_14