Official firmware downloads

firmware_download.py builds the download catalog the way micropython.org builds its own download pages, so nothing in between has to be kept up to date. The browser interface’s Firmware dialog and the firmware download-* commands share this code.

The board list

The board list is https://micropython.org/resources/boards/index.json. MicroPython’s tools/autobuild/build-downloads.py writes it from every ports/<port>/boards/<BOARD>/board.json, and the site’s board pages are rendered from it. Each entry has id (the board, ESP32_GENERIC_S3), port, mcu, vendor, product, variants (name to description) and, for ESP boards, deploy_options.flash_offset. The catalog keeps the ports mcuctl can flash from a download: esp32 (esptool) and rp2, samd, nrf and mimxrt (UF2).

The files

The files have no listing of their own: https://micropython.org/resources/firmware/ answers 403. A board’s page, https://micropython.org/download/<BOARD>/, links every file it has, and the names follow the autobuild’s contract (tools/autobuild/autobuild.sh):

<BOARD>[-<VARIANT>]-<YYYYMMDD>-v<version>.<ext>
ESP32_GENERIC_P4-C6_WIFI-20260406-v1.28.0.bin
RPI_PICO-20260929-v1.30.0-preview.95.g5b5f06cb48.uf2

A variant name starts with a letter, so it can’t be mistaken for the date. A version with -preview. in it is a nightly; the server keeps the last few of those and every release. ESP boards have .bin (the combined image, written at the board’s flash_offset), .uf2, .app-bin, .elf, .map and .meta.zip; rp2 and samd have .uf2; stm32 has .dfu and .hex.

The index is cached for a day and each page for an hour in ~/.mcuctl/firmware-cache/, along with the downloaded images. firmware_fetch downloads only a URL the board’s page listed.

OmniPython’s releases

The second source, --source omnipython, reads PyDevices/omnipython-builds the way its releases are made. GET /repos/PyDevices/omnipython-builds/releases lists them; each firmware release has a firmware.json asset with a builds list. A build has an id (mp-s3-octal, which is the board name here), a chip, a flash_offset and app_offset, and files: a role (flash is the whole-flash image, app the app-only image, uf2 for RP2), a name, a size and a sha256. The manifest’s preview flag decides whether a build is a release or a preview, and the release’s tag is its version.

A draft release’s public URL answers 404, so its files are fetched through the API’s asset URL with a token from GH_TOKEN or GITHUB_TOKEN. The token goes to api.github.com only, and is dropped when GitHub redirects the download to its storage. The release list and each manifest are cached for an hour, the same as a micropython.org page. A release with no manifest is skipped; if none has one, or a file the manifest lists isn’t on the release, or a download doesn’t match its sha256, the command stops and says which.

Check it still holds

curl -s https://micropython.org/resources/boards/index.json | python -m json.tool | head
curl -s https://micropython.org/download/RPI_PICO/ | grep -o '/resources/firmware/[^"]*' | head
mcuctl firmware download-list --board ESP32_GENERIC_S3 --force
gh release list -R PyDevices/omnipython-builds
mcuctl firmware download-list --board mp-s3-octal --source omnipython --force