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.