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’susb-*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,keysanddisplay_driver, LVGL’s coordinator (OmniPython). An image built with--modules allfreezes these too, and.frozencomes before/libonsys.path, so there a mip-installed copy never runs: rebuild to update them.board_configandboard_peripheralsfor the specific boardthe 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 |
|
|---|---|---|
|
the released version, as |
running a release, which is the normal case |
|
whatever is on that branch, as |
developing against current |
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). Seepaint.py.Periodic work of your own goes in
app.every(period, fn). Seebouncing_balls.py. Do not reach forapp.everymerely 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 = 0forever. 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.pydocuments the pin (_CAN_SEL_EXIO = 5 # CH422G: high = CAN mode), but onlycan()sets it, andcan()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)forn < 10is zero ticks at this port’sCONFIG_FREERTOS_HZ=100, andvTaskDelay(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_drvreportswidth,heightandcolor_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 = 10in itsboard_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. Ifimport board_configraisesOSError: ESP-IDF error 257 (ESP_ERR_NO_MEM), lowerBOUNCE_ROWSor bring the display up before Wi-Fi.MicroPython’s
namedtuplehas no_replace(). CPython’s does, so a pure-Python module can pass a full desktop test suite and still raiseAttributeErroron the first board it meets. Anything destined for a board wants at least a smoke run on one.