Flash a board

ESP32

An esp32 build ends with ESP-IDF’s To flash, run: idf.py flash. That isn’t the route here: idf.py lives in the ESP-IDF environment the build sets up, not on your shell’s PATH. Write firmware.bin with esptool (pip install esptool) instead. It’s the merged image, with bootloader, partition table and app in one, so it goes where the bootloader goes: 0x2000 on the P4, 0x0 on the S3. For another chip, the build folder’s flasher_args.json has the bootloader’s offset.

esptool --chip esp32p4 --baud 460800 write-flash 0x2000 builds/esp32/ESP32_GENERIC_P4/WIFI6_DEV_KIT_H2/firmware.bin
esptool --chip esp32s3 --baud 460800 write-flash 0x0 builds/esp32/ESP32_GENERIC_S3/SPIRAM_OCT/firmware.bin

Erase the whole flash first on a board that has run something else, or an older layout of this firmware: esptool --chip esp32s3 erase-flash. The write only covers the image, so anything left from before can sit where the new filesystem starts, and MicroPython then says the filesystem looks corrupted and mounts nothing. The erase takes your files too, secrets.py among them, so copy them off first.

RP2

Hold BOOTSEL while you plug the board in, and copy firmware.uf2 to the drive it shows.

STM32 (Arduino GIGA R1 WiFi)

The DISPLAY_SHIELD build makes three images: firmware0.bin for the microcontroller’s flash, firmware1.bin, the Wi-Fi chip’s firmware, for the QSPI flash, and romfs.img for the ROMFS partition beside it. Put the board in its bootloader, by running machine.bootloader() at its REPL or double-tapping RESET, and write them with dfu-util, firmware0.bin last:

cd builds/stm32/ARDUINO_GIGA/DISPLAY_SHIELD
dfu-util -a 1 -d 2341:0366 -s 0x90F00000 -D firmware1.bin
dfu-util -a 1 -d 2341:0366 -s 0x90B00000 -D romfs.img
dfu-util -a 0 -d 2341:0366 -s 0x08040000:leave -D firmware0.bin

romfs.img holds the firmware’s own Python modules: asyncio, webrepl, mip, requests, logging and the rest. The firmware doesn’t freeze them, because its flash is needed for LVGL, so it reads them from the ROMFS, and firmware0.bin without them boots with none of them. The build also leaves them as files in romfs/.

A firmware release carries the same files with the address each is written at in its name: ...firmware1-at-0x90F00000.bin is firmware1.bin, ...romfs-at-0x90B00000.img is romfs.img and ...firmware0-at-0x08040000.bin is firmware0.bin. Use them in the commands above, and the release notes list the lines with the names filled in. Its ...romfs-files.zip is the romfs/ folder.

The DISPLAY_SHIELD firmware runs its USB-C port on TinyUSB, so a program can add USB interfaces at run time with machine.USBDevice, such as a MIDI device with micropython-lib’s usb-device-midi. The port starts as the REPL’s serial port alone, with no /flash drive, and Windows gives the serial port a new COM number the first time. To get a drive, present one from code with usb.device.msc, which the ROMFS carries:

import usb.device, vfs
from usb.device.msc import MSCInterface, RAMBlockDev

disk = RAMBlockDev(1024)  # 512 KB of RAM; any block device works
vfs.VfsFat.mkfs(disk)
usb.device.get().init(MSCInterface(disk), builtin_driver=True)

The computer then lists a drive. Don’t mount the same block device on the board while the computer has it.

machine.bootloader() still reaches the DFU bootloader.

firmware1.bin holds the radio’s firmware for Wi-Fi and for Bluetooth. firmware0.bin finds it by address, so flash the two from the same build together: with a firmware1.bin from another build, the board starts with “could not find valid firmware” and no Wi-Fi or Bluetooth. A build without the variant keeps the Wi-Fi firmware inside its one image, firmware.bin, which the last command writes in place of firmware0.bin, and freezes its Python modules as upstream does.

The OmniPython libraries don’t fit in this firmware beside LVGL, so they go in the ROMFS partition too, where MicroPython runs them in place and finds them before /flash/lib. A deploy replaces the whole partition, so put the firmware’s modules in the folder you deploy, then the libraries. From a clone of omnipython, with mpremote:

git clone --depth 1 https://github.com/PyDevices/omnipython.git
mkdir romfs
cp -r builds/stm32/ARDUINO_GIGA/DISPLAY_SHIELD/romfs/* romfs/
cp -r omnipython/lib/* romfs/
mpremote romfs deploy romfs

From a release, unzip ...romfs-files.zip -d romfs takes the place of the first cp. mpremote compiles each .py to .mpy on the way when the mpy-cross Python package is installed (pip install mpy-cross; its 1.29 release writes .mpy files this firmware reads). Without it, mpremote copies the .py files and the board compiles them as they’re imported. The board’s own drivers go in the same folder: the GIGA Display Shield’s board page has that recipe.

The H747 has a second core, a Cortex-M4, and upstream’s layout leaves it the last 512 KB of flash. A GIGA build that doesn’t fit the 1,280 KB before that takes it too, and says autosize: as it does (fit firmware on a small flash). You flash it the same way; firmware0.bin is just longer. It overwrites any M4 program on the board, and it has no openamp module, so it can’t start one.

The M4 starts on its own

When a GIGA’s BCM4 option bit is set, as it was on the one these builds were tested on, its M4 starts at reset, before MicroPython runs, from 0x08100000, the default boot address. To read the bit at the REPL (1 means set; this only reads it):

import machine
print(machine.mem32[0x5200201C] >> 22 & 1)

Any GIGA firmware longer than 768 KB covers that address, upstream’s included, so the M4 starts from whatever bytes of it are there. Usually they point nowhere it can reach, so it faults and stops. When they point at memory, the M4 can hang the board, so every GIGA build checks them and, if it must, moves the code a few bytes and links again, saying so in an m4 pad: line.

To stop the M4 starting at all, clear BCM4: ST’s STM32CubeProgrammer can change it in the option bytes. Changing option bytes is your call, since a wrong one can leave the board unable to boot until it is recovered over SWD.

With mcuctl

mcuctl writes either file for you, given the build’s port and your board’s serial port:

mcuctl firmware flash --port esp32 --artifact firmware.bin -d /dev/ttyACM0
mcuctl firmware flash --port rp2 --uf2 --artifact firmware.uf2

For a .uf2, mcuctl copies it to the board’s drive instead.

After flashing

omnipython’s Bringing up a board takes a flashed board to one drawing on its own panel.