Bringing up a board

From a board with nothing on it to one drawing on its own panel. Everything here was done rather than recalled — it comes out of a full bring-up of a Waveshare ESP32-S3-Touch-LCD-4.3 — and where something is untested it says so.

For installing OmniPython anywhere else, including desktop, see Install. This page is the board.

Read §1 and §2 before you install anything. Between them they are most of the time a first bring-up costs: half of what you might install is already in the firmware, and installing over serial when the board has Wi-Fi turns minutes into an afternoon.


1. What the firmware already has, and what it does not

Check before installing anything. On an image built with the OmniPython C modules (omnipython-builds’ build.py --modules displayif,lvgl,usbhost,pygraphics,audiodsp,ulab, say) the following are frozen or built in — installing them is wasted effort:

  • lvgl (from omnipython-lvgl)

  • dotclockframebuffer (from displayif) — the RGB panel interface

  • _usbhost, the USB host’s C module (usbhost). The USB packages that use it (usb.core, usb.host.*, usb.device.*, from this repository’s usb-* directories) are installed with mip, except on a board variant that freezes them (the WIFI6 DEV-KIT’s)

  • ulab, pygraphics, and audiodsp’s modules

and the following are not, and must be installed:

  • displaydev, appdev, multimer, audiodev, boarddev, events, keys and display_driver, LVGL’s coordinator (OmniPython). An image built with --modules all freezes these too, and .frozen comes before /lib on sys.path, so there a mip-installed copy never runs: rebuild to update them.

  • board_config and board_peripherals for the specific board

  • the board’s Python drivers (ch422g, gt911, …)

for m in ("lvgl", "display_driver", "dotclockframebuffer", "mipidsi",
          "displaydev", "board_config", "_usbhost", "appdev", "multimer"):
    try:
        __import__(m); print("OK  ", m)
    except Exception as e:
        print("MISS", m, type(e).__name__, e)

(mipidsi is the panel interface on the ESP32-P4 boards, dotclockframebuffer on the RGB-panel S3 boards; whichever is not yours will simply be missing.)

Trap. A frozen module can fail with ImportError on a bare board even though it is there — because it imports events, and it is that import failing (no module named 'events'). The probe prints the exception text so you can see which module is really absent; a frozen module that reports MISS with somebody else’s name in the message is present and fine. Install omnipython (which carries events, appdev and display_driver), then re-probe. Firmware built before display_driver moved to OmniPython froze it from the LVGL module, where it showed the same trap with appdev.

2. Installing, over Wi-Fi

Serial file transfer is slow. On a Wi-Fi board, let the board fetch everything itself with omip: one file that gets the board online, then installs a package and what it needs. If import omip works on the freshly flashed board, your firmware already has it. Otherwise copy it on from the computer:

mpremote connect <port> mip install github:PyDevices/omnipython/lib/omip.py

Then, on the board:

import omip
omip.install("omnipython")
omip.install("github:PyDevices/omnipython/board_configs/fbdisplay/esp32-s3-touch-lcd-4_3")

If the board is offline, omip joins the network in secrets.py, and with no secrets.py it asks at the REPL and only saves what you type if you say so. To skip the question, put secrets.py on the board first, as two plain assignments. It holds credentials and is per-user, so it’s not in any package:

WIFI_SSID = "..."
WIFI_PASSWORD = "..."

The same file is all mcuctl wifi enable needs to set the board up for reaching it over Wi-Fi later: it writes /webrepl_cfg.py and a boot.py block on MicroPython, and the web workflow settings in settings.toml on CircuitPython. Stock firmware works, with or without wifi_manager. Reaching the board over Wi-Fi has the steps.

The board installer pulls its own drivers and depends on omnipython, so the second call alone is usually enough. A program with no one at the REPL calls omip.install(name, prompt=False), so it never waits for an answer.

Apps for Home install the same way, each into its own folder under /apps while what it needs goes in /lib: install an app. A package does that by naming its folder under target in its JSON, as in "target": "apps/home"; the folder sits beside the library folder.

omip.install takes the arguments of mip.install. The difference is what happens with no index: it looks on the OmniPython index and then on micropython-lib, and it brings what a package needs from micropython-lib, such as the sdcard driver. Plain mip uses one index for a whole install, so with mip you install those first, from its default index. If an install fails, omip raises OSError; mip prints a message and returns.

omip also skips a package the firmware already has frozen in, and says so: Skipping aioble: it's frozen into this firmware. A frozen module runs ahead of /lib, so a copy there would only take up space. It skips even when the index has a newer version, because that copy still wouldn’t run. To use a newer one, rebuild the firmware, or put /lib ahead of .frozen on sys.path, which omip notices and then installs as usual. force=True installs everything regardless.

Take both halves from the same place. The pair above mixes the released omnipython (the index) with the board config from main (github:). That is fine when the two agree, and wrong the moment main’s board configs pass something the release’s library does not know: once, the release was one step behind the audio pump, so a board built exactly this way came up with a working panel and touch and no audio — pcm_out() raised TypeError: unexpected keyword argument 'wire' (#50). To install a specific version of the board config, add version=:

omip.install("github:PyDevices/omnipython/board_configs/fbdisplay/esp32-s3-touch-lcd-4_3",
             version="v0.7.0")

Note that this does not replace files a release already put in /lib with different names — an install adds and overwrites, it never removes — and that a .py beside a .mpy is the one that loads, so a source install over a bytecode one takes effect without deleting anything first.

When it finishes, reset the board (machine.reset(), or the button) before you import board_config. On a panel like this one the display will not start while Wi-Fi is connected — §10 has the numbers — and in your own programs the display comes up first.

Without Wi-Fi: a ROMFS image

A board with no network, the XIAO nRF52840 on stock MicroPython among them, has no mip to fetch with, so you copy files from the computer. Its filesystem fills sooner than the byte count suggests: littlefs gives every file at least one 4 KB block, and the XIAO’s is 64 blocks, so OmniPython plus pygraphics as separate .mpy files didn’t fit.

Where the firmware has a ROMFS partition (the stock XIAO nRF52840 build has 256 KB), put the libraries there instead, as one image:

# stage/lib holds the libraries, laid out as they would be in /lib
mpremote romfs deploy stage

mpremote compiles .py files to .mpy on the way (--no-mpy keeps sources, or .mpy files you compiled yourself).

It mounts at /rom with /rom/lib on sys.path. Modules there run in place from flash, so importing them costs less RAM than importing the same modules from /flash. Keep board_config.py and your own program on the writable filesystem, where you can edit them; a new image replaces the whole partition.

On the nRF52, a driver must send from RAM. A b"..." literal in a ROMFS or frozen module stays in flash, and the nRF52’s SPI and I2C peripherals read only RAM. MicroPython’s nrf port then sends nothing and raises nothing: sdcard.py timed out initialising a card from /rom until its filler byte became a bytearray. If a driver works from /flash and fails from /rom, look for literals passed to write().

3. Choosing what to install, and from where

omip.install("omnipython") and omip.install("github:PyDevices/omnipython/board_configs/...") both work and give you different things. The difference is invisible until you wonder why your edit did not take.

What you get

When you want it

omip.install("name")

the released version, as .mpy bytecode

running a release, which is the normal case

omip.install("github:owner/repo/path")

whatever is on that branch, as .py source

developing against current main

Two separate axes hide in there. The index serves a release — the tag pinned in the MIP index’s lockfile — while github: serves the branch as it stands this minute. Separately, the index serves bytecode by default and source on request:

omip.install("omnipython", mpy=False)   # released, but as .py source

Bytecode is smaller and loads faster; source is what you can read on the board and what a CircuitPython or CPython tree needs. mpremote mip and micropython -m mip spell the same thing --no-mpy.

Single files from GitHub

github: installs one file just as happily as a package, which is the escape hatch when a repository has no package.json:

mip.install("github:PyDevices/audiocomponents/lib/audioeffects/reverb.py",
            target="/lib/audioeffects")

audiocomponents has no manifest by choice, and that is the reason rather than an oversight: the normal workflow is to install the released version from the index, and not shipping a manifest is what keeps people on releases. If you want current source from it, you install file by file and you are meant to notice that you are doing something unusual.

4. An erase-flash wipes /lib

Firmware and installed Python have separate lifetimes, and only one of them survives an erase. After esptool erase_flash — or any partition-table change, which forces one — the board comes back with boot.py and nothing else, and everything in §2 has to run again.

Worth knowing before you reflash rather than after: if the board is on Wi-Fi, keep wifi.py and secrets.py somewhere you can push back in two mpremote commands, because they are the two files that let the board fetch the rest for itself. Keep secrets.py outside any repository, somewhere only you can read.

5. Iterating without installing

mpremote mount serves a local directory as the board’s filesystem, so a whole staged tree can be exercised with no transfer step. Invaluable while a board_config or an example is still changing:

mpremote connect <port> mount /path/to/staged run /path/to/staged/example.py

Trap. Connecting to the board interrupts whatever it is running. There is no way to “peek” at a running program over the same serial port — a second mpremote ... exec to check on it is what kills it.

6. The two drawing idioms

Both start from board_config. They are not mixed.

Without LVGL

from board_config import display_drv
import board_config
import appdev

app = appdev.App(board_config)

appdev.App is the scheduler and the lifecycle. It keeps the program alive past the end of the script (no app.run() needed), dispatches input events, and gives everything else on the board its turn.

  • Event-driven work goes in handlers: app.on(app.events.MOUSEBUTTONDOWN, fn). See paint.py.

  • Periodic work of your own goes in app.every(period, fn). See bouncing_balls.py. Do not reach for app.every merely to keep the program alive — appdev already does that.

  • A bare while True: loop works and is the wrong shape: it owns the interpreter and starves input, the REPL and everything else.

With LVGL

import display_driver  # wires LVGL flush + input + event loop to board_config
import lvgl as lv
from display_driver import app

Then use LVGL widgets normally. display_driver builds the App for you from board_config when one does not already exist. See lv_test_timer.py.

7. Presenting the frame, and when you must ask for it

Short answer: if your program is built on appdev.App, you never call show(). If it is not, you do, once per frame.

On a MicroPython dotclockframebuffer panel, drawing is not showing until the back buffer is promoted: the panel is double-buffered with auto_refresh=False, and display_drv.show() is what promotes it. Miss that and every blit succeeds, nothing raises, and the screen never changes.

Under LVGL it is wired for you — display_driver hands LVGL’s refresh_cb to show(), and disables App’s own refresh so nothing presents twice.

Without LVGL it is wired for you too, since omnipython 0.4.0. appdev.App drives periodic show() for any display whose needs_refresh is True, and FBDisplay.needs_refresh is a computed property rather than a fixed attribute: it reports True when the underlying display does not auto-refresh, False when it does. One class has to serve two runtimes that need opposite answers — CircuitPython’s framebufferio.FramebufferDisplay(fb, auto_refresh=True) composites at the panel rate and tears if presented again, while MicroPython’s DotClockFramebuffer shows nothing until refresh(). The driver already made exactly this test inside show(); the property just asks it once instead of leaving it to the caller.

Older non-LVGL code that calls show() itself per frame — paint.py does this in each handler — is still correct and costs nothing; show() is idempotent against the auto-refresh case.

On an older install the class inherited needs_refresh = False, so a non-LVGL program that did not call show() drew nothing, silently. If you meet that, this is it — and the fix is to update omnipython rather than to sprinkle show() calls.

8. blit_rect byteswaps in place

display_drv.blit_rect(buf, x, y, w, h)   # RGB565, native byte order

When the panel needs byte-swapped pixels, blit_rect swaps the caller’s buffer, in place. Blitting the same buffer twice therefore swaps it back and draws it wrong the second time.

This bites specifically when repeating a row to upscale. Build a block of n rows and blit it once rather than blitting one row n times.

The driver handles the swap itself, so produce plain native-order RGB565 and do not pre-swap.

9. IO expanders: what construction alone can change

The single most expensive failure of this bring-up, and the reason this section exists at all.

On a board with an IO expander, constructing the expander driver writes to every pin. CH422G.__init__ wrote 0xFF — all outputs high — before any board config had said what it wanted. Those pins are not decorative: they drive resets, chip selects, backlights, and on some boards an analog multiplexer that decides what a connector is physically wired to.

On the Waveshare ESP32-S3-Touch-LCD-4.3, EXIO5 drives an FSUSB42UMX that routes the second USB-C connector either to the ESP32-S3’s native USB (low) or to the CAN transceiver (high). So import board_config silently disconnected the board’s USB.

What made it expensive is worth stating plainly, because the same shape will recur on other boards:

  • No error anywhere. The USB host started fine, registered a client, and reported attaches = 0 forever. Every layer said “working”.

  • It survived resets. The expander is a separate chip on I2C; it only clears on power loss. So “have you power cycled it” did not help, and the fault looked like hardware.

  • It was invisible in the obvious place. board_peripherals.py documents the pin (_CAN_SEL_EXIO = 5  # CH422G: high = CAN mode), but only can() sets it, and can() is lazy. Nothing ever set it deliberately in either direction; the board arrived in CAN mode by accident.

The fix, and the pattern to copy: pass the board’s intended state to the constructor rather than correcting it afterwards.

_USB_SEL = 5
_IO_INITIAL = 0xFF & ~(1 << _USB_SEL)      # USB, not CAN
io_expander = CH422G(i2c, initial=_IO_INITIAL)

Correcting after construction leaves a window in which the pin is wrong, which matters when it controls something already running.

Recovering a board already stuck in the wrong mode needs the ordering, not just the value: setting the pin is not enough once the USB controller has initialised against a disconnected bus. Set the pin, then reset, then start the host.

When a peripheral on a board is inexplicably absent, board_peripherals.py is the first file to read — it is where the board’s pins are named, even when nothing is calling the function that uses them.

10. Odds and ends worth knowing

  • pdMS_TO_TICKS(n) for n < 10 is zero ticks at this port’s CONFIG_FREERTOS_HZ=100, and vTaskDelay(0) does not block. This is a C concern, not Python, but it has produced “waits” that never waited in this tree more than once.

  • A display_drv reports width, height and color_depth; write examples against those rather than hard-coding the panel size. The Waveshare 4.3” and 7” boards are both 800x480, which makes a wrong assumption easy to miss.

  • Memory headroom on the Waveshare ESP32-S3-Touch-LCD-4.3 (8 MB PSRAM, MicroPython 1.30 preview): about 8.3 MB free at the REPL, and about 6.7 MB with the 800x480 panel and LVGL up.

  • PSRAM is not the scarce thing on an S3; contiguous internal RAM is. On the same board, esp32.idf_heap_info(esp32.HEAP_DATA) shows a largest internal block of about 100 KB at boot. The RGB panel’s bounce buffers take 32 KB of it in one piece (BOUNCE_ROWS = 10 in its board_config.py; 20 rows take 64 KB), a connected Wi-Fi radio leaves 92 KB, and the panel and Wi-Fi together leave 62 KB. If import board_config raises OSError: ESP-IDF error 257 (ESP_ERR_NO_MEM), lower BOUNCE_ROWS or bring the display up before Wi-Fi.

  • MicroPython’s namedtuple has no _replace(). CPython’s does, so a pure-Python module can pass a full desktop test suite and still raise AttributeError on the first board it meets. Anything destined for a board wants at least a smoke run on one.