Skip to content
noggin

Links are Wi-Fi first, USB second; every Core is addressed directly

Amended 2026-11-02 (#547): commands now just, ADR 0016.

The Mech should sit on the desk untethered: pack-powered, with no cable to the Mac. Both Cores join the home Wi-Fi as stations (the vendor’s MicroPython build has network.WLAN and espnow; Bluetooth and WebREPL are removed, see docs/research/2026-10-31-radio.md). The noggin service talks to each Core directly, so no relay firmware exists. Each Core sends a UDP beacon every 2 s (<tag> noggin <name> <ip> <uptime s> <version> <commit>, the last two its program’s, stamped by just flash: #357); the service listens on one port and learns the Cores from it, taking a beacon only when its tag checks out, it comes from the ip it claims (so a captured beacon replayed by another host is not a Core) and it carries an X.Y.Z version. Commands are the existing newline command lines, one per UDP datagram, as <tag> <seq> <line>: the tag is HMAC-SHA256 of <name> <seq> <line> under the shared token, truncated to 128 bits (RFC 2104 section 5), from the standard hmac module on both sides: stdlib on the Mac, micropython-lib’s on the Core (just flash-usb installs it with mpremote mip, from micropython-lib’s tag of the Core’s MicroPython, so it only changes over USB); tags are compared in constant time (hmac.compare_digest, or an XOR-accumulate on the Core, whose hmac lacks it). The token itself never travels, and a datagram for one Core is worthless to another. Everything the Core sends, beacon and replies, is <tag> <body> with the tag over <name> <body>, and the service drops anything untagged, so no LAN host can pose as a Core, fake an ack or fake a flash result; the sequence is milliseconds since the epoch and must never go backwards (replays are dropped; the Core keeps a ceiling in link.seq on its flash, at or above every seq it has run: when a line’s seq passes it, the Core writes seq + 10 s before the line runs, so it writes at most once per 10 s of the Mac’s clock, and before a reboot it writes that exact seq, so the Mac’s next line runs at once; a datagram captured before a reboot or a power cut is still dead after it); the Core answers with a one-line tagged ack from its own address and command port on receipt, before it runs the line (a gesture takes about a second, longer than the ack window), and the service tries each line up to four times, waiting 0.2, 0.4, 0.8 and 1.6 s for the ack, with the same seq (the Core re-acks its highest seq without running it again). The Core keeps its radio out of power save (wlan.config(pm=wlan.PM_NONE)): in power save the access point holds its datagrams for a DTIM or more. Wi-Fi credentials and the token are written once over USB by the setup wizard (wifi.json beside calibration.json). The eye program is flashed over the same Link (just flash while the beacon is fresh, issue #108): put <file> <offset> <base64> lines of 120 bytes each (the datagram stays inside the Core’s 256-byte read) append to <file>.new, and commit <file> <sha256> swaps it in only if the hash matches, keeping the old file as <file>.bak and listing it in flash.trial; both are answered once they ran, ok or err, not on receipt. Then reboot; boot.py gives the new program 10 s to reach noggin ready and otherwise puts the .bak files back and reboots, and the service, once the beacon is back, sends the same commits again: ok only while the Core runs the new files. boot.py itself never goes over Wi-Fi. So USB-C is recovery only: boot.py and the first install (mpremote, just flash-usb), whatever Wi-Fi cannot fix, and the automatic fallback Link when the radio is down or a line goes unacked over Wi-Fi. Offline Cores make hooks silent no-ops; the service reconnects on its own and noggin status shows wifi / usb / offline per Core. Each Core reports its uptime since power-on, the only battery signal available (the shield has no voltage sense); one pack per shield, the spare swapped in.

Accepted as-is: send blocks the service loop up to 3 s per unacked line (four tries), so a Core that vanished while its beacon is still fresh (up to 22 s: the window #196 sized for a Core whose loop, and so its beacon, stopped while it played a gesture, bored about 16 s; since #205 the Core beacons through its gestures, so the window could shrink) stalls a batch 3 s a line; a datagram that never reached the Core could be replayed by a third party until the Core sees a higher seq; after a power cut (or just flash-usb, or any reset but the reboot line) the Core drops the Mac’s lines up to the saved ceiling, at most 10 s of them, so they go over USB or are dropped; the Core’s filesystem is littlefs, which wear-levels the link.seq writes (read off the eyes Core 2026-11-01, docs/build/flashing.md); a Mac clock set back leaves its lines unacked over Wi-Fi (so they go over USB) until it passes the saved seq, a reboot no longer clears it (just flash-usb does not either: delete link.seq over mpremote); an ack means received, not run: a parser exception follows as a second reply, err <seq> <reason>, which the service does not wait for (an unknown command is a silent ok); a line that arrives while a gesture plays is acked at once (the gesture’s waits serve the Link, #205) but runs only after that gesture and any line before it, as it did when the Core’s loop stopped for the gesture, and a line acked just before the Wi-Fi drops runs only once it is back; off the network the Core scans only between gestures; an unacked line does not stop its batch: the rest still goes over Wi-Fi, and the unacked lines follow over USB when the cable is in (after the batch, so out of order), else are logged as dropped; a lost ack sends that line over USB too, so it can run twice, and a socket error on Wi-Fi resends the whole batch over USB, lines already acked included; a tagged beacon replayed from the Core’s own address keeps a Core that went away looking fresh until the beacon goes stale (its lines then go unacked, so over USB); the USB fallback assumes the eyes Core (USB_CORE in noggin/service.py); a flash blocks the service loop until it is done (up to a minute, plus up to 22 s waiting for a beacon); a commit that fails after earlier files were swapped in leaves a mix until the next flash (the hash checks make it unlikely); the fallback catches a program that raises or hangs in Python before noggin ready, not one that crashes after it or hangs inside C; a Core still running a wifi.py from before #108 acks every put on receipt, one from before #135 sends untagged beacons and acks, and one from before #357 beacons without its program’s version and commit, which the service ignores, so the first flash with any of them goes over USB (just flash picks USB on its own: the Core is not on Wi-Fi).

  • Core 1 relays to Core 2 by ESP-NOW: rejected once both Cores can be on the LAN; one more protocol for nothing.
  • Bluetooth LE from the Mac: rejected, the vendor’s build has no bluetooth module.
  • ESP-NOW through a third Core as USB dongle: rejected, it keeps a cable and adds a part.
  • mDNS names: unverified on the vendor’s build; the beacon needs nothing from the network.
  • TCP: rejected for now; datagrams plus retries cover one-line commands with less reconnection logic.
  • Two packs in series for runtime: impossible, 14.8 V exceeds the shield’s 12.6 V input.

Update 2026-11-01: MQTT over mutual TLS evaluated and rejected (#157, #158)

Section titled “Update 2026-11-01: MQTT over mutual TLS evaluated and rejected (#157, #158)”

The standard alternative, Mosquitto with mutual TLS and the Cores as umqtt clients, was tried on the eyes Core. The Core’s MicroPython build leaves about 19 KB of system heap, and mbedTLS needs about 35 KiB per connection, so the handshake starves (docs/research/2026-10-31-core-tls.md). The Link stays signed UDP: stdlib hmac, signed beacons and replies, seq with link.seq (#135). The Mosquitto and PKI code from #159 and #160 was parked for a Core firmware that can hold TLS, which ADR 0002 rules out, so it was deleted on 2026-11-01 (#334, docs/research/2026-11-01-stack-alternatives.md); git history keeps it.

Update 2026-11-01: several known networks (#195)

Section titled “Update 2026-11-01: several known networks (#195)”

The Mech moves between places, so wifi.json holds a list, {"networks": [{"ssid", "password"}, ...], "token"}; the one-network shape from before still loads. While off the network the Core, every 10 s, stops the driver’s own retries (disconnect(), else ESP-IDF refuses to scan), scans and joins the known network it hears loudest; none in range, it scans again 10 s later. A drop first gets 10 s of the driver’s own reconnect. The setup wizard’s “Join the Wi-Fi” stage adds a network or updates its password, keeping the others and the token (add_network in noggin/wifi.py). Nothing else in the Link changes. Known limits: the scan blocks the Core’s loop (eyes and USB) a second or two each 10 s while it is off the network; a hidden network (no SSID in the scan) is never joined; a known network with a wrong password is retried as long as it is the loudest; a join gets about 8 s (the 10 s window less the scan) before the next scan.

byYellow PineYellow Pine

noggin v0.2.26-6-g09bf9b7 · 09bf9b7