nina-fw CircuitPython installer

[mikeysklar]

Currently the nina-fw install process involves pasthrough code written in Arduino. @b-blake proposed a CircuitPython installer and came up with some code that gets pretty close, but is not quite usable to push up a stub.

This is a request for enhancement. Making this functional as a convenient way for the CircuitPython crowd to manage ESP32 Airlift updates. It is a an elegant approach leaving the CircuitPython installation and libraries intact. Rather than the sledgehammer UF2 pass through image which wipes everything.

We have been testing with a mix of Feather RP2040 + Airlift (breakout or FeatherWing).

import time
import board
import busio
import digitalio
import usb_cdc
import supervisor
# 3 seconds to get here from fresh load
time.sleep(10)

# Define your pins (example for Feather RP2040)
TX = board.TX
RX = board.RX
ESP32_CS    = digitalio.DigitalInOut(board.D13)  # B Chip Select pin, LED
ESP32_RST   = digitalio.DigitalInOut(board.D12)  # G Reset pin
ESP32_GPIO0 = digitalio.DigitalInOut(board.D10)  # W GPIO0 pin (force bootloader mode)

ESP32_CS.direction    = digitalio.Direction.OUTPUT
ESP32_RST.direction   = digitalio.Direction.OUTPUT
ESP32_GPIO0.direction = digitalio.Direction.OUTPUT

# Create UART for ESP32 communication
uart = busio.UART(TX, RX, baudrate=115_200, timeout=0)

# Wait for USB connection (if needed)
while not supervisor.runtime.usb_connected:
    time.sleep(0.1)

# --- Reset ESP32 Sequence ---
# Force ESP32 into bootloader mode
time.sleep(0.1)           # Short delay
ESP32_GPIO0.value = False # Pull GPIO0 low
time.sleep(0.1)           # Short delay
ESP32_RST.value   = False # Assert reset
time.sleep(0.1)           # Short delay
ESP32_RST.value   = True  # Release reset
# Minimal delay to let bootloader initialize but not too long so we don't miss its handshake
time.sleep(0.1)

# --- Main Passthrough Loop ---
while True:
    # Forward data from ESP32 (UART) to USB console
    data = uart.read(32)  # Read up to 32 bytes
    if data:
        try:
            usb_cdc.console.write(data)
        except Exception as e:
            # In case of a transient error, you could log it here
            pass

    # Forward data from USB console to ESP32 (UART)
    if usb_cdc.console.in_waiting:
        incoming = usb_cdc.console.read(usb_cdc.console.in_waiting)
        if incoming:
            uart.write(incoming)

    # A short sleep to prevent hogging the CPU; adjust as needed
    time.sleep(0.001)

This is how far the code gets:

% esptool.py --port /dev/cu.usbmodem142101 --before no_reset --baud 115200 write_flash 0 NINA_W102-1.7.7.bin
esptool.py v4.8.1
Serial port /dev/cu.usbmodem142101
WARNING: Pre-connection option "no_reset" was selected. Connection may fail if the chip is not in bootloader or flasher stub mode.
Connecting....
Detecting chip type... Unsupported detection protocol, switching and trying again...
Connecting...
Detecting chip type... ESP32
Chip is ESP32-U4WDH (revision v3.1)
Features: WiFi, BT, Dual Core, 240MHz, Embedded Flash, VRef calibration in efuse, Coding Scheme None
Crystal is 40MHz
MAC: 30:c9:22:7b:41:a4
Uploading stub...

A fatal error occurred: Invalid head of packet (0x54): Possible serial noise or corruption.

Longer forum thread for reference.

[b-blake]

@mikeysklar,

Thank you Mikey for your help.

@et al,

The goal is to make ESP32 firmware update code platform independent.

[dhalbert]

There is a Python library that helps out doing this: https://github.com/adafruit/Adafruit_CircuitPython_miniesptool

See an example of its use here. I recently tried this while debugging updating the Metro M7. It works for me.
https://learn.adafruit.com/adafruit-metro-m7-with-airlift/upgrade-esp32-airlift-firmware-with-python. That page was private, but I've added some minimal help for now and made it public. The page content could be improved.

[b-blake]

I think I have bidirectional communication between the PC/Chrome and the Feather RP2040 running CircuitPython 9.2.7.

This is what I see on the Chrome screen:

esptool.js
Serial port WebSerial VendorID 0x239a ProductID 0x80f2
Connecting... Detecting chip type... ESP32
Chip is ESP32-D0WD-V3 (revision 3)
Features: Wi-Fi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
Crystal is 40MHz
MAC: 34:ab:95:49:1b:0c
Uploading stub...```

This is what I get on the control and UART lines:
`After board reset
TX High
RX High
CS High

After Chrome Connect
Much LED action
TX High
RX Low
CS High
`
This is the code that is executing:
`# --- Reset ESP32 Sequence ---
# Force ESP32 into bootloader mode
neopixel_write.neopixel_write(pin, pixel_red)
time.sleep(0.1)           # Short delay
ESP32_GPIO0.value = False # Pull GPIO0 low
time.sleep(0.1)           # Short delay
ESP32_RST.value   = False # Assert reset
time.sleep(0.1)           # Short delay
ESP32_RST.value   = True  # Release reset
time.sleep(0.1)           # Short delay
ESP32_GPIO0.value = True  # Pull GPIO0 High
# Minimal delay to let bootloader initialize but not too long so we don't miss its handshake
time.sleep(0.1)           # Short delay
neopixel_write.neopixel_write(pin, pixel_green)

# --- Main Passthrough Loop ---
while True:
    # Forward data from ESP32 (UART) to USB console
    data = uart.read(32)  # Read up to 32 bytes
    if data:
        neopixel_write.neopixel_write(pin, pixel_red)
        try:
            usb_cdc.console.write(data)
        except Exception as e:
            # In case of a transient error, you could log it here
            pass
    neopixel_write.neopixel_write(pin, pixel_blue)

    # Forward data from USB console to ESP32 (UART)
    if usb_cdc.console.in_waiting:
        neopixel_write.neopixel_write(pin, pixel_green)
        incoming = usb_cdc.console.read(usb_cdc.console.in_waiting)
        if incoming:
            uart.write(incoming)
    neopixel_write.neopixel_write(pin, pixel_off)

    # A short sleep to prevent hogging the CPU; adjust as needed
    time.sleep(0.001)
`

What do I need to do to get to the next step?

[b-blake]

Also, The neopixel is flickering showing that the Main Passthrough Loop is executing waiting for some data from Chrome or the UART.

[b-blake]

@dhalbert,

After a third look I got your recommended code to work. Thank you!
Your code does not reference Chip Select. Can I assume it is unnecessary?
It does not like the MD5sum numbers. Where do I find them?
Apparently it does not require Chrome.

Bruce

[dhalbert]

Chip Select is used to toggle the co-processor between WiFi and BLE mode. See for instance what's in https://github.com/adafruit/Adafruit_CircuitPython_AirLift. But in this case we're forcing the co-processor into bootloader mode, so it's not used.

I don't know what you mean about MD5sum values.

[b-blake]

@dhalbert ,

Part 1, Thank you. Understandable.

Part 2, MD5sum looks like MD5 is a checksum. Checksum is not explicitly stated.

Bruce

def md5(self, offset, size):

    """On ESP32 we can ask the ROM bootloader to calculate an MD5 on the
    SPI flash memory, from a location over a size in bytes. Returns a
    string with the MD5 in lowercase"""
    if self._chipfamily == ESP8266:
        raise NotImplementedError("MD5 only supported on ESP32")
    self.check_command(ESP_SPI_ATTACH, bytes([0] * 8))
    buffer = struct.pack("<IIII", offset, size, 0, 0)
    md5 = self.check_command(ESP_SPI_FLASH_MD5, buffer, timeout=2)[1]
    return "".join([chr(i) for i in md5])

[b-blake]

P.S. I have taken to copying the MD5 result into the CircuitPython code. It stops the error message.

[dhalbert]

The MD5 check is just a double-check that the write worked. You could just remove that code.