Flashing
Our program replaces the Core’s stock remote-control program; the firmware stays as it is (ADR 0002).
First run
Section titled “First run”scripts/setup.sh # guided first-run: plug in the Core, back up, flash, join the Wi-Fi, calibrate, install hooks + the noggin servicejust wifi # add a Wi-Fi network to the Core on USB (the wizard's Join the Wi-Fi step alone)just flash # install the eye program on the Core and reboot it: Wi-Fi while it beacons or no Core is on USB, else USB (just flash-usb forces it)just restore-stock # put the stock remote-control program back on the CoreTalking to the Core
Section titled “Talking to the Core”- The eyes Core reports
3.4.0; MicroPython 2e7b6351 on 2026-03-25(read 2026-11-01; an earlier note hade7cd27f2 on 2025-06-09); stock RC program 01.00.00.13. Its filesystem is LittleFS (thevfspartition starts withlittlefs: 978944 bytes, 239 blocks of 4096), so thelink.seqwrites are wear-levelled; about 66 KB of heap is free at an idle REPL.esp32.Partitionis cut down tofind,infoand block reads and writes, and only thevfspartition is visible. - The eyes Core’s USB-C carries data one way round only: flipped, it powers and boots but the Mac sees no device
(inferred from one plug each way). If
/dev/cu.usbmodem*does not appear, turn the plug over. - Held KEY at plug-in (the vendor’s download mode, LED off) shows no USB device on the Mac, in the orientation that
enumerates when it boots normally, so
esptool get-security-infocould not be run (2026-11-01). Flash encryption is community evidence only (docs/research/2026-11-01-stack-alternatives.md); firmware updates go through the vendor’s app over Bluetooth (ADR 0012), thenjust flash-usbover the cable. - The vendor’s phone app names the eyes Core
<vendor>-Eyesand reports its firmware as 1.1.4.13, “the latest” (2026-11-01). The vendor wiki’s firmware release notes stop at 01.00.03.02 (2025-11-26), so the wiki lags the app; how 1.1.4.13 maps to the3.4.0insys.versionis unknown. - mpremote’s own Ctrl-C does not interrupt the stock RC app, and
mpremote soft-resetwaits for a raw REPL the eye program never gives.eyes/interrupt.pyhandles both; every board recipe in the justfile goes through it, then usesmpremote resume. - ESP32-C3 running the vendor’s MicroPython build. USB-C is the REPL at 115200,
enumerating on macOS as
/dev/cu.usbmodem*. - Its MicroPython is 1.23.0 preview (
sys.implementation._mpy774: .mpy version 6.3, no native arch), pinned once as[tool.noggin] micropythonin pyproject.toml. pyright checks the Core’s files againstmicropython-esp32-esp32_generic_c3-stubs1.23 as the standard library (eyes/test_micropython.py; the stubs still take a tuple instr.startswith, soeyes/test_wifi.pykeeps its own check), andmpy-cross1.23 compiles them. Bytecode-only .mpy files load on any 6.x (mpyfiles). The setup wizard warns when the board reports another version. - Upload files with
just flash: over the Wi-Fi Link while the Core beacons or when no Core is on USB (the noggin service then waits up to 22 s for its beacon), elsempremoteover USB (just flash-usbforces the cable; boot.py only ever goes that way). Both send the eye program, the files boot.py imports (just mpy-list), as .mpy (just mpy, into eyes/build): less RAM to import than the .py. boot.py stays .py (the Core runs boot.py only). A .py shadows its .mpy (import looks for the .py first), soflash-usbremoves them and Wi-Fi takes only .mpy; a Core still on .py files refuses .mpy over Wi-Fi, so the first .mpy install goes over USB. just mpystamps the program with the repo’s version and commit (eyes/build/stamp.py, never in git), which its beacon reports;noggin statusshows them beside the noggin service’s own (read when it started:just startafter a pull) and warns when the Core runs an older release (just flash). The version is git’s for the checkout (v0.2.6, orv0.2.6-3-gabc1234three commits past it), and the warning compares the releases alone, so a Core flashed from an older commit since the same release shows it but no warning; on USB alone there is no beacon, so no version. A program from before the stamp (#357) beacons without them and the noggin service ignores it, so that Core is flashed over USB once (just flash-usb, the plug the right way round).- The stock program’s
boot.pyruns the remote-control app forever, so a custom program must provide its ownboot.py.
Stock program on the Core (from its rc_mpy manifest)
Section titled “Stock program on the Core (from its rc_mpy manifest)”The stock RC program’s manifest lists what it expects on the Core: boot.py, app/rc_main.py, compiled app/control.mpy,
app/devices.mpy, app/parser.mpy, and bbl/{__init__,buzzer,executor,leds, motors,servos,sleepModule}.py. So bbl lives on the filesystem, not frozen,
and the file list matches the GitHub repo’s src/app_rc/. Local copy with
md5s: docs/references/stock-program-manifest.json. Still verify on the real
board with mpremote ls before replacing anything.
noggin v0.2.26-6-g09bf9b7 · 09bf9b7