Brad, 2026-09-09, after a full board bring-up: "the tricks I showed you regarding mip from the index and git:, including single files, when .show() is required and some other things … are useful knowledge that I'm sure are documented, but scattered about. Also, the board-bringup-notes.md is written for internal use, but an example like that could be very useful, and I'm not sure the workflow docs in pydevices cover it."
He is right on both counts. Checked:
install-workflows.md does cover the board-installer pattern — mip.install("github:PyDevices/pydevices/board_configs/…", index="https://PyDevices.github.io/mip") — and explains why board installers live in the repo rather than the index.- It does not cover any of the following, which a real bring-up needs.
What is missing, specifically
- Serial is slow; Wi-Fi is not. Put two files on the board (
wifi.py, secrets.py) and let it fetch everything else itself. Installing pydevices + a board installer + 92 files of audiocomponents over Wi-Fi took minutes; the same over serial is an order of magnitude worse. This is the single highest-value trick and it is written down nowhere user-facing.
- The index ships
.mpy; github: ships source. Which you want depends on whether you are running a release or developing against current main. Neither is wrong, and the difference is invisible until you wonder why your edit did not take.
- Single-file
github: installs. mip.install("github:owner/repo/path/to/file.py", target="/lib/pkg") works and is the escape hatch when a repo has no package.json — audiocomponents has none by deliberate choice, so a user wanting current source installs file by file. Worth documenting with the reason the repo has no manifest: normal workflow is to install the released version from the index, and not shipping a manifest is what keeps users on releases.
- What the firmware already has. Installing
lvgl, display_driver, pygraphics, ulab, _usbif on a cmods-built image is wasted effort; displaydev, appdev, events, board_config and the board's drivers are what actually need installing. board-bringup-notes.md §1 has the probe snippet for this and it is excellent.
show() and when it is required — and this changed today. As of pydevices 0d6350a, FBDisplay.needs_refresh is computed from the underlying display, so a program built on appdev.App no longer calls show() at all: App presents for it. Programs without an App still must. §5 of the bring-up notes has been rewritten to match, and 81 now-redundant show() calls were removed from 35 examples (pydevices-examples 15f166ad).- An erase-flash wipes
/lib. Firmware and installed Python are separate lifetimes; after a partition-table change the board comes back with only boot.py and everything must be reinstalled. Nothing says so.
The ask
Promote the material in board-bringup-notes.md — currently marked "Status: draft, raw material" and written from one S3-Touch-LCD-4.3 bring-up — into a user-facing guide, and fold the six points above into it or into install-workflows.md. The raw notes are unusually good precisely because everything in them was done rather than recalled; the job is editing and placement, not research.
Related: the wifi.py half of this is filed separately.
Brad, 2026-09-09, after a full board bring-up: "the tricks I showed you regarding mip from the index and
git:, including single files, when.show()is required and some other things … are useful knowledge that I'm sure are documented, but scattered about. Also, theboard-bringup-notes.mdis written for internal use, but an example like that could be very useful, and I'm not sure the workflow docs in pydevices cover it."He is right on both counts. Checked:
install-workflows.mddoes cover the board-installer pattern —mip.install("github:PyDevices/pydevices/board_configs/…", index="https://PyDevices.github.io/mip")— and explains why board installers live in the repo rather than the index.What is missing, specifically
wifi.py,secrets.py) and let it fetch everything else itself. Installingpydevices+ a board installer + 92 files ofaudiocomponentsover Wi-Fi took minutes; the same over serial is an order of magnitude worse. This is the single highest-value trick and it is written down nowhere user-facing..mpy;github:ships source. Which you want depends on whether you are running a release or developing against currentmain. Neither is wrong, and the difference is invisible until you wonder why your edit did not take.github:installs.mip.install("github:owner/repo/path/to/file.py", target="/lib/pkg")works and is the escape hatch when a repo has nopackage.json—audiocomponentshas none by deliberate choice, so a user wanting current source installs file by file. Worth documenting with the reason the repo has no manifest: normal workflow is to install the released version from the index, and not shipping a manifest is what keeps users on releases.lvgl,display_driver,pygraphics,ulab,_usbifon a cmods-built image is wasted effort;displaydev,appdev,events,board_configand the board's drivers are what actually need installing.board-bringup-notes.md§1 has the probe snippet for this and it is excellent.show()and when it is required — and this changed today. As ofpydevices0d6350a,FBDisplay.needs_refreshis computed from the underlying display, so a program built onappdev.Appno longer callsshow()at all:Apppresents for it. Programs without anAppstill must. §5 of the bring-up notes has been rewritten to match, and 81 now-redundantshow()calls were removed from 35 examples (pydevices-examples15f166ad)./lib. Firmware and installed Python are separate lifetimes; after a partition-table change the board comes back with onlyboot.pyand everything must be reinstalled. Nothing says so.The ask
Promote the material in
board-bringup-notes.md— currently marked "Status: draft, raw material" and written from one S3-Touch-LCD-4.3 bring-up — into a user-facing guide, and fold the six points above into it or intoinstall-workflows.md. The raw notes are unusually good precisely because everything in them was done rather than recalled; the job is editing and placement, not research.Related: the
wifi.pyhalf of this is filed separately.