Add a board variant
Most boards need no variant: pick the upstream board that matches the chip and
give --flash its flash size (Build for a board). Make
a variant only for settings that really are one board’s, such as the LCD-7’s
cache sizes and tick.
An esp32 board
On esp32, build.py appends our ESP-IDF settings after the board’s, so ours
win. They come from files it finds by name, each used only if it exists, in
this order:
variants/esp32/sdkconfig, thenvariants/esp32/sdkconfig.<chip>(esp32s3,esp32p4): what every build, or every build for that chip, wants. The S3’s PSRAM, Wi-Fi and lwIP tuning and the P4’s BLE-over-C6 settings are here.The same two names at the root of each module you selected: what that module needs. usbhost’s USB host settings and cameraif’s OV5647 driver live in their own module directories.
variants/esp32/<BOARD>/<VARIANT>/sdkconfig: what’s left that is one board’s alone.
A variant directory of ours also holds an mpconfigvariant.cmake that includes
the upstream variant it builds on, which is how LCD_7 and T_EMBED become
variants of ESP32_GENERIC_S3, and WIFI6_DEV_KIT one of ESP32_GENERIC_P4.
It may also hold:
An
mpconfigboard.h, included before the board’s own, for C defines the port’s ESP-IDF components must see too.WIFI6_DEV_KIT’s setsMICROPY_HW_USB_HS (0), which moves the USB device to the P4’s full-speed controller, so other P4 boards keep theirs on the high-speed one.C sources, through
MICROPY_SOURCE_BOARDin itsmpconfigvariant.cmake, the way upstream’sESP32_GENERIC_C2does.WIFI6_DEV_KIT_H2builds onWIFI6_DEV_KITand adds a board startup hook that swaps the P4’s two full-speed PHYs, so the USB device comes out on the kit’s USB-C marked “USB”.
The partition table is found the same way, the most specific partitions.csv
winning (variants/esp32/partitions.esp32s3.csv
adds a coredump partition on the S3, which a standard build leaves unused).
Without one, the board’s own is used. Either way, autosize grows the app
partition when the image doesn’t fit, unless the build keeps a board’s
filesystem with --keep-fs.
Run the CPU, flash and PSRAM at the fastest clocks the board’s chips are
rated for. The CPU’s rating is the chip’s: 240 MHz for an ESP32, S2, S3 or C5,
160 for a C3 or C6, 400 for a P4 of revision 3 or later and 360 before that.
Every S3 build already runs at 240
(variants/esp32/sdkconfig.esp32s3),
and a P4 build runs at its revision’s rating by default. A classic ESP32
board sets 240 in the variant’s sdkconfig, as
AUDIO_KIT’s
does: upstream’s default is 160 MHz, and at 160 a 48 kHz synth with a reverb
runs out of time and clicks. The ESP32-S0WD and ESP32-D2WD are the exceptions,
rated for 160.
Flash and PSRAM are usually rated for 80 MHz, which the variant’s sdkconfig
sets in two lines
(QTPY_PICO’s).
Upstream’s generic boards run them at 40 MHz, and at that clock a classic
ESP32 can fall behind in Bluetooth audio. Read the flash’s JEDEC ID with
esptool.py flash-id and check its datasheet first. The flash clock lives in
the bootloader, so write the bootloader with the app. A P4 image for chips
before revision 3 keeps its flash at 40 MHz, the most ESP-IDF offers there.
A build with the CPU below its chip’s rating, or flash or PSRAM below 80 MHz, says so when it finishes, with the lines to set.
An rp2 board
An rp2 board of ours is a variant of one of upstream’s, in
variants/rp2/<BOARD>/<VARIANT>/. The port only knows variants that sit in the
board’s own folder, so build.py makes a folder of its own for every rp2
build, builds/rp2/<BOARD>/<VARIANT>/<BOARD>/, links upstream’s board into it
unchanged, adds
variants/rp2/board.cmake
after the board’s own settings, and adds what the variant holds:
mpconfigvariant.cmake(required): cmake settings, included after the board’s own default variant. The board’sPICO_BOARD, the number of GPIOs, PSRAM and the size of the filesystem go here.mpconfigboard.h: C defines, included after the board’s own header, so it can#undefwhat the board sets, such as its name.pins.csv: the pin names, in place of the board’s.
PIMORONI_PICO_PLUS2_W is the one rp2 variant of ours. It builds the Pico 2 W for the
Pimoroni board’s 16 MB flash, 8 MB PSRAM, 48 GPIOs and its own pin names, and
its files say why each setting is there.
Every rp2 build runs the CPU at its chip’s rated clock: 200 MHz on an RP2040,
which board.cmake sets where the SDK’s default is still 125, and 150 on an
RP2350. At 200 MHz the SDK raises the RP2040’s core voltage to the 1.15 V the
rating needs. Flash and PSRAM follow the CPU through a divider and stay inside
their rating, so a variant has nothing to set for them. A build whose CPU
runs below its chip’s rating says so when it finishes.
An stm32 board
An stm32 variant of ours works the same way, in
variants/stm32/<BOARD>/<VARIANT>/, with make files instead of cmake ones.
build.py makes builds/stm32/<BOARD>/<VARIANT>/<BOARD>/ from upstream’s
board, unchanged, and adds:
mpconfigvariant.mk(required): make settings, included after the board’smpconfigboard.mk, so it can change what the board sets.A header named like one of the board’s (
mpconfigboard.h,stm32h7xx_hal_conf.h): included after the board’s own.Any other file, such as a linker script fragment: put beside the board’s files, where the variant’s settings reach it as
$(BOARD_DIR)/<name>.
ARDUINO_GIGA’s DISPLAY_SHIELD is the one stm32 variant of ours. It moves
the Wi-Fi chip’s firmware into QSPI flash with a linker script fragment and
turns on the HAL’s DSI driver for displayif’s mipidsi. Its manifest.py
freezes no Python: it hands its modules to build.py, which compiles them
into romfs.img for the board’s ROMFS partition. Its
mpconfigboard.h also switches USB to TinyUSB, which is one line:
#define MICROPY_HW_TINYUSB_STACK (1).
On ARDUINO_GIGA, with a variant or without one, a firmware too big for its
1,280 KB grows over the M4 core’s flash instead of failing, and the build adds
the settings for that to the variant file it generates. A variant doesn’t need
to make room itself; see
fit firmware on a small flash.
Desktop variants
The unix and windows ports take our omnipython and vst3-engine variants, and
webassembly takes omnipython. The variants table
lists them.