FYI: Board name and variant changes

[jimmo]

This change is being done over the next day or so, so posting this now just in case you notice any weirdness with the downloads page. (It's done, please let us know if you see any problems)

Background:

MicroPython maintains a set of "board definitions" for each port, corresponding to actual boards that this port is known to run on. The firmware build server builds release and nightly firmware for each board, and publishes them to https://micropython.org/download

For a very long time, there has been support for "board variants", which are minor variations to a board to enable/disable features or support different SKUs of the same board. Historically for example, this was used to publish the pyboard v1.x firmware with optional support for threading, double-precision floating point, networking, etc. There is a single downloads page for PYBV11 which lists firmware for all the variants.

This was originally special-cased for the pyboard firmware, but more recently, we have made variant support available for all ports and boards. However, because it wasn't available at the time, there are a few boards in other port that exist as distinct boards rather than variants. For example, GENERIC_ESP32 vs GENERIC_ESP32_SPIRAM, or WEACTSTUDIO vs WEACTSTUDIO_4MB.

As a sort of guide for when something should be a distinct board vs a variant of an existing board, it would typically if they could share the same photo, or if they share the same pins.csv, then they should be variants. For vendors, different SKUs of the same board should typically be variants. (*)

Now that board variant support is available everywhere, we are doing a bit of a tidy-up of some boards.

Changes:

esp32

If you use the "generic" esp32 boards, they have been renamed to ESP32_GENERIC* (i.e. to add the ESP32_ prefix). This means that you need to use make BOARD=ESP32_GENERIC_S3 rather than e.g. make BOARD=GENERIC_S3. This was done because we need board names to be globally unique, and there was a GENERIC board for both esp8266 and esp32. (**)

Some of the esp32 generic boards are now "variants" of a smaller set of generic boards (one for each family). For example "GENERIC_SPIRAM" is now the "SPIRAM" variant of "ESP32_GENERIC". This was done because it avoids duplication of configuration, and simplifies the downloads page, especially as we need to start supporting generic boards with more and more combinations of flash size, octal spiram, etc. To build a variant, use the BUILD_VARIANT make option, e.g. make BOARD=ESP32_GENERIC BOARD_VARIANT=SPIRAM.

Some esp32 boards no longer need to exist. For example, we no longer provide spiram builds of esp32s2 and esp32s3, and the generic firmware will run on boards regardless of whether they have spiram. Similarly for esp32c3, there is no usb and non-usb variant, the generic c3 firmware always supports usb now. This probably should have been done like this from the start, but since the move to IDF 5.x, this has been easier to implement. (Note that a spiram variant of the OG esp32 is still required, because auto-detection is not possible).

esp8266

As for esp32, the generic esp8266 board has been renamed to ESP8266_GENERIC and now supports variants for the different flash sizes.

rp2040

For the rp2040 port, the PICO and PICO_W boards have been renamed to RPI_PICO and RPI_PICO_W. This is for the same reason as above, although there is no other board named PICO, we're trying to encourage a VENDOR_BOARDNAME convention for boards, and conceivably "PICO" could be a name used by other vendors.

nRF

The nRF boards have been renamed to be uppercase, to match the other ports. e.g. pca10059 is now PCA10059.

More information

We are in the process of renaming all the historical builds files to match the new names, and updated the downloads page, including putting redirects from the old URLs. Almost every previously-available firmware file is still available, but maybe in a different location. e.g. files previously listed on the GENERIC_SPIRAM page are now listed under a variant on the ESP32_GENERIC page. (As noted above, this is currently in-progress, pending a complete run of the firmware server's build-everything process)

See #12088 #12240 for the relevant PRs.

If you want to know the list of variants for a given board, the board.json file lists them. The downloads page uses board.json to show the list of variants too. You can see how the variant configuration is applied by looking in mpconfigboard.mk (or mpconfigboard.cmake for esp32, rp2). We have put checks in the esp32 and rp2 Makefiles to detect if you're trying to compile a generic board by its old name.

Note that there is a separate concept of "variants" which is for the unix and windows ports, "variant" takes the place of "board". i.e. a unix variant is conceptually the same as an stm32 board. Naming is hard.

Please let us know if you have questions! I hope this should be a fairly transparent and minor change assuming we get all the redirects and renames in place correctly, but please let us know if we've missed anything.

(*) We are also planning to rename+merge the various pyboard boards. e.g. by the rules above, the three PYBD SKUs should probably be variants of a single board. There are other boards that we are aware of too that should be updated.
(**) There was previously a workaround on the firmware build server and downloads page to make this work, but while we were fixing the variants it seemed like a good opportunity to remove this.

[cwalther]

we have made variant support available for all ports and boards.

I’m curious (and too lazy to look for myself), does that include the webassembly port? I once added board support there, specifically to allow out-of-tree board definitions that enable different features than the standard build, but since the project I was using that for never went anywhere, it has languished before making it into a pull request.

[jimmo]

@cwalther This does not include the webassembly port, although adding variant support (in the meaning that it's used on the unix/windows port) is something we want to do there. I think the (in progress) pyscript support will be added as a variant, for example.

On the embedded ports, board and variant support is really just a few lines in the Makefile. The main piece of work was actually the extra stuff for the build server and downloads page. Neither of which really apply to the webassembly port for now.

[Josverl]

A few comments

• overall I think this is a good move. Previous I needed to reverse engineer the logic out of code and conversations of the old forums
• I would encourage parts of this PR docs to be included as documentation in the repro, rather than just as a PR / discussion

If you want to know the list of variants for a given board, the board.json file lists them

• Is this accessible, if so on which URL?

[jimmo]

I would encourage parts of this PR docs to be included as documentation in the repro, rather than just as a PR / discussion

Definitely agree. Except I'm right in the middle of a huge docs update so I'm hesitant to make changes to the docs because it's more work for me to keep it in sync with my in-progress work. But one of the things I keep running into with the docs work is finding things that are inconsistent, so this is exactly why I'm making these sorts of changes in order to make it easier to write docs :)

Is this accessible, if so on which URL?

I meant like e.g. https://github.com/micropython/micropython/blob/master/ports/stm32/boards/PYBV11/board.json
Not sure if that's what you meant though.

[jimmo]

FWIW, The build server runs tools/autobuild/build-downloads.sh to build a single index.json of all the boards.

[Josverl]

It's that last index.json that would be good to have access to on a stable URL, or checked in to GH

[glenn20]

To potentially save time for those wondering how to select a board variant when building a micropython image, set the BOARD_VARIANT flag on the make command line or in the environment, eg:

make BOARD=ESP32_GENERIC BOARD_VARIANT=OTA

or

export BOARD_VARIANT=OTA
make BOARD=ESP32_GENERIC

[jimmo]

That is a massive oversight in my original post! Thanks @glenn20 , I have updated it :)

[robhamerling]

I wonder if there some reasoning for the 'mix' of use of underscore and hyphen in the board (variant) names, like in: ESP32_GENERIC-SPIRAM and ESP8266_GENERIC-FLASH_1M.
Reason to ask: only underscores would make it easier to split the firmware name in 'board', 'github-tag', etc. (which I do in some Python scripts to build firmware locally).

[chrisovergaauw]

Hi Jim,

I’m looking forward to v1.20!
I’ve got a lot on my plate, what would be the most efficient way to migrate an existing custom board definition? Will there be a migration guide or do you think the generic example will be easy enough to understand without having a lot context on recent changes?

regards, Chris