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 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.
wireless_adafruit_products_jumpers.jpg
AirLift BitsyWing with ESP32 Optional Control Pins highlighted.

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.

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

This guide was first published on Sep 30, 2019. It was last updated on Sep 30, 2019. This page (Upgrade External ESP32 Airlift Firmware) was last updated on Oct 14, 2019.