3 Commits
Author SHA1 Message Date
jimmyandClaude Opus 5.5 495da4e366 feat(espnow): app-file OTA over the reliable link
New espnow_ota module, loaded on the first OTA packet (types 0x07-0x0C,
status reply 0x26). Files are written by chunk index to <path>.new,
checked against their sha256, and moved into place together on commit,
followed by a reset. Unchanged files are skipped, and a repeated commit
after the reset still gets OK.

- receive ESP-NOW frames from esp.irq() so frames are not lost while
  presets.tick() runs; polling remains as a fallback
- raise rxbuf to 2048 and the link inbox to 24 frames
- file_hashes: MicroPython's sha256 has no hexdigest()
- bench stats line includes esp.stats()

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 23:41:17 +13:00
jimmyandClaude Sonnet 5.5 940d1d0a77 fix(espnow): start ESP-NOW before the pattern library on boot
On the ESP32-C3 the radio tasks failed to start (Wifi Unknown Error 0x0101)
on about every other cold boot once the link and beat modules were loaded.
Bringing ESP-NOW up before the pattern library and the LED driver claim
memory made 6 of 6 cold boots start cleanly.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-27 22:30:26 +13:00
jimmyandClaude Sonnet 5.5 20d1af7177 feat(espnow): reliable link and beat trigger on the 0x4C protocol
Adds the driver half of the v2 controller link as extra 0x4C message types:
DATA with fragment reassembly, de-duplication and acks, a state-version
digest with jittered resync requests, a bench echo, and a BEAT frame handled
by BeatSync (accepts one of the two copies, free-runs on the last period
when a beat is missed). Presets.beat() steps the selected pattern without a
message. Optional settings: espnow_loss, bench, beat_pin, usb_log.

The working tree also carries the files already running on the bench device,
which were ahead of origin/p2p: board.py (per-chip LED pin and CPU speed),
the reversed device_config flag in controller_messages.py, and the
apply_cpu_freq call in main.py.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-27 17:15:28 +13:00
13 changed files with 1218 additions and 22 deletions

No files matched your search

+76
View File
@@ -0,0 +1,76 @@
import struct
WIRE_MAGIC = 0x4C
MSG_BEAT = 0x25
FRAME_LEN = 8 # [4C][25][flags][idx u16][period u16][fire_in]
MIN_GUARD_MS = 30
FREERUN_MISS_MAX = 4
def _diff(a, b):
return (a - b) & 0xFFFF
class BeatSync:
"""Turns beat frames from the controller into step triggers.
The controller sends every beat twice with the same index; only the first
copy that arrives is acted on. Between frames the driver free-runs on the
last period so a lost beat is not noticed.
"""
def __init__(self):
self.last_idx = None
self.period = 0
self.last_fire = 0
self.fire_at = None
self.downbeat = False
self.bar = 0
self.missed = 0
self.freerun_fire = False # True when the last fire was invented, not triggered by a frame
# fires: beats acted on; dups: second copies dropped; late: too-soon or old frames;
# freerun: beats the driver made up because no frame arrived
self.stats = {"fires": 0, "dups": 0, "late": 0, "freerun": 0}
def on_frame(self, data, now):
"""Handle one received frame. Call from the ESP-NOW irq: no allocation beyond unpack."""
if len(data) != FRAME_LEN or data[0] != WIRE_MAGIC or data[1] != MSG_BEAT:
return False
flags, idx, period, fire_in = struct.unpack_from("<BHHB", data, 2)
if self.last_idx is not None:
if idx == self.last_idx:
self.stats["dups"] += 1
return False # second copy of a beat we already took
guard = max(MIN_GUARD_MS, self.period // 2)
if _diff(idx, self.last_idx) >= 0x8000 or (
self.fire_at is None and now - self.last_fire < guard and self.period
):
self.stats["late"] += 1
return False # late copy of an older beat, or too soon after the last one
self.last_idx = idx
self.period = period
self.downbeat = bool(flags & 1)
self.bar = (flags >> 1) & 7
self.fire_at = now + fire_in
self.missed = 0
return True
def poll(self, now):
"""True when a beat should step the pattern now. Call every tick."""
if self.fire_at is not None:
if now - self.fire_at >= 0:
self.fire_at = None
self.last_fire = now
self.freerun_fire = False
self.stats["fires"] += 1
return True
return False
if self.period and self.last_idx is not None and self.missed < FREERUN_MISS_MAX:
if now - (self.last_fire + self.period + self.period // 4) >= 0:
self.last_fire += self.period
self.missed += 1
self.freerun_fire = True
self.stats["fires"] += 1
self.stats["freerun"] += 1
return True
return False
+41
View File
@@ -0,0 +1,41 @@
"""ESP32-C3 and ESP32-S3 differences for the LED driver.
Seeed XIAO silk-screen D10 is GPIO 10 on the C3 and GPIO 9 on the S3.
Fresh settings use that pad. A saved ``led_pin`` is left unchanged.
"""
try:
import uos as os
except ImportError:
import os
import machine
_LED_PIN_C3 = 10
_LED_PIN_S3 = 9
_CPU_HZ_C3 = 160000000
_CPU_HZ_S3 = 240000000
def mcu():
"""Return ``s3``, ``c3``, or ``""`` when the chip is neither."""
name = os.uname().machine.upper().replace("-", "")
if "ESP32S3" in name:
return "s3"
if "ESP32C3" in name:
return "c3"
return ""
def default_led_pin():
if mcu() == "s3":
return _LED_PIN_S3
return _LED_PIN_C3
def apply_cpu_freq():
"""C3 maximum is 160 MHz. S3 (XIAO firmware) runs at 240 MHz."""
if mcu() == "s3":
machine.freq(_CPU_HZ_S3)
else:
machine.freq(_CPU_HZ_C3)
+41 -3
View File
@@ -125,6 +125,21 @@ def apply_startup_pattern(settings, presets):
print("Startup preset failed (invalid pattern?):", dp)
def _config_flag(value):
"""Parse a device_config boolean. None if the value is not a flag."""
if isinstance(value, bool):
return value
if isinstance(value, int) and not isinstance(value, bool):
return value != 0
if isinstance(value, str):
s = value.strip().lower()
if s in ("1", "true", "yes", "on"):
return True
if s in ("0", "false", "no", "off"):
return False
return None
def apply_device_config(data, settings, presets):
"""Apply fields from v1 ``device_config``; reload presets when strip length or colour order changes."""
dc = data.get("device_config")
@@ -157,6 +172,12 @@ def apply_device_config(data, settings, presets):
if sm in _STARTUP_MODES:
settings["startup_mode"] = sm
meta_changed = True
if "reversed" in dc:
flag = _config_flag(dc["reversed"])
if flag is not None:
settings["reversed"] = flag
presets.reversed = flag
meta_changed = True
if not strip_changed and not meta_changed:
return
if strip_changed:
@@ -181,10 +202,27 @@ def record_last_preset(settings, preset_name):
def apply_brightness(data, settings, presets):
try:
presets.b = max(0, min(255, int(data["b"])))
settings["brightness"] = presets.b
new_b = max(0, min(255, int(data["b"])))
except (TypeError, ValueError):
pass
return
changed = int(presets.b) != new_b
presets.b = new_b
settings["brightness"] = new_b
# A finished manual chase frame keeps the colours scaled at the last beat.
# Skip when this message also selects: that select redraws after ``b`` is set.
if not changed or presets.generator is not None:
return
if "select" in data or "s" in data:
return
name = presets.selected
preset = presets.presets.get(name) if name else None
if preset is None or getattr(preset, "p", None) != "chase":
return
presets.redraw = True
try:
presets.select(name)
finally:
presets.redraw = False
_pending_select = None
+293
View File
@@ -0,0 +1,293 @@
"""App-file OTA over ESP-NOW (driver side). Imported on the first OTA packet only.
Inner packets, carried in reliable-link DATA frames (unicast acked, or broadcast):
0x07 BEGIN [4C][07][sess u16][size u32][sha256 32B][plen][path]
0x08 DATA [4C][08][sess u16][chunk u16] + up to CHUNK bytes at chunk * CHUNK
0x09 END [4C][09][sess u16] hash the staged file
0x0A COMMIT [4C][0A][sess u16] move every staged file into place, then reset
0x0B ABORT [4C][0B][sess u16] delete the staged files
0x0C MISSING [4C][0C][sess u16] report which chunks of the current file are missing
Reply, sent straight back (not through the link):
0x26 STATUS [4C][26][sess u16][op][code] + arg
arg: [cnt u16] + missing bitmap for MISSING, else received bytes u32
Files are written to <path>.new; a new session discards whatever an older one staged.
The committed session is kept in ota_last: the reset can beat a lost reply, and the
controller then asks again.
"""
import struct
import file_hashes
WIRE_MAGIC = 0x4C
OP_BEGIN = 0x07
OP_DATA = 0x08
OP_END = 0x09
OP_COMMIT = 0x0A
OP_ABORT = 0x0B
OP_MISSING = 0x0C
MSG_STATUS = 0x26
OK = 0
READY = 1
SAME = 2
BADHASH = 3
INCOMPLETE = 4
BADPATH = 5
IOERR = 6
NOSESS = 7
TOOBIG = 8
CHUNK = 944 # 4 link fragments of 238 bytes minus this packet's 8-byte header
MAX_SIZE = 65536
STAGED_SUFFIX = ".new"
LAST_FILE = "ota_last" # session last committed, so a repeated COMMIT after the reset still gets OK
try:
import uos as os
except ImportError:
import os
def safe_path(path):
"""Relative path to a root file, patterns/... or lib/..., never the hash manifest."""
if not path or path.startswith("/") or "\\" in path or path == file_hashes.MANIFEST_FILENAME:
return False
parts = path.split("/")
if any(p in ("", ".", "..") for p in parts):
return False
return len(parts) == 1 or parts[0] in ("patterns", "lib")
def _makedirs(path):
parts = path.split("/")[:-1]
for i in range(1, len(parts) + 1):
try:
os.mkdir("/".join(parts[:i]))
except OSError:
pass
def _remove(path):
try:
os.remove(path)
except OSError:
pass
class Ota:
def __init__(self, send, reset=None):
self.send = send # send(mac, frame)
self.reset = reset # called after a commit; defaults to machine.reset
self.sess = 0
self.staged = {} # path -> sha hex of a verified .new file
self.cur = None # [path, size, sha hex, file, have bitmap (bytearray), received bytes]
try:
with open(LAST_FILE) as f:
self.committed = int(f.read())
except (OSError, ValueError):
self.committed = 0
def handle(self, mac, pkt):
if len(pkt) < 4:
return
op = pkt[1]
sess = pkt[2] | (pkt[3] << 8)
if sess == 0:
return
if op == OP_COMMIT and sess == self.committed:
self._reply(mac, sess, op, OK, struct.pack("<I", 0))
elif op == OP_BEGIN:
self._begin(mac, sess, pkt)
elif sess != self.sess:
if op != OP_DATA: # data for a session we never started: stay quiet, it may be broadcast
self._reply(mac, sess, op, NOSESS)
elif op == OP_DATA:
self._data(pkt)
elif op == OP_END:
self._end(mac)
elif op == OP_COMMIT:
self._commit(mac)
elif op == OP_ABORT:
self._abort()
self._reply(mac, sess, op, OK)
elif op == OP_MISSING:
self._missing(mac)
def _reply(self, mac, sess, op, code, arg=None):
if arg is None:
arg = struct.pack("<I", self.cur[5] if self.cur else 0)
self.send(mac, struct.pack("<BBHBB", WIRE_MAGIC, MSG_STATUS, sess, op, code) + arg)
def _close_cur(self, delete):
if self.cur is None:
return
try:
self.cur[3].close()
except OSError:
pass
if delete:
_remove(self.cur[0] + STAGED_SUFFIX)
self.cur = None
def _abort(self):
self._close_cur(True)
for path in self.staged:
_remove(path + STAGED_SUFFIX)
self.staged = {}
def _begin(self, mac, sess, pkt):
if len(pkt) < 43:
return
size = struct.unpack_from("<I", pkt, 4)[0]
sha = "".join("%02x" % b for b in pkt[8:40])
plen = pkt[40]
path = bytes(pkt[41 : 41 + plen]).decode()
if sess != self.sess:
self._abort()
self.sess = sess
if not safe_path(path):
self._reply(mac, sess, OP_BEGIN, BADPATH)
return
if size > MAX_SIZE:
self._reply(mac, sess, OP_BEGIN, TOOBIG)
return
if self.cur is not None:
if self.cur[0] == path and self.cur[2] == sha:
self._reply(mac, sess, OP_BEGIN, READY) # our earlier reply was lost
return
self._close_cur(True)
if self.staged.get(path) == sha:
self._reply(mac, sess, OP_BEGIN, READY)
return
try:
if file_hashes._hash_file(path) == sha:
self._reply(mac, sess, OP_BEGIN, SAME)
return
except OSError:
pass # no such file yet
try:
_makedirs(path)
f = open(path + STAGED_SUFFIX, "w+b")
except OSError:
self._reply(mac, sess, OP_BEGIN, IOERR)
return
cnt = (size + CHUNK - 1) // CHUNK
self.staged.pop(path, None)
self.cur = [path, size, sha, f, bytearray((cnt + 7) // 8), 0]
self._reply(mac, sess, OP_BEGIN, READY)
def _data(self, pkt):
cur = self.cur
if cur is None or len(pkt) < 6:
return
idx = pkt[4] | (pkt[5] << 8)
body = pkt[6:]
off = idx * CHUNK
have = cur[4]
if off >= cur[1] or have[idx >> 3] & (1 << (idx & 7)):
return # past the end, or a copy we already wrote
if len(body) != min(CHUNK, cur[1] - off):
return
f = cur[3]
try:
end = f.seek(0, 2)
if end < off:
f.write(bytes(off - end)) # a chunk before this one is still missing
f.seek(off)
f.write(body)
except OSError:
self._close_cur(True)
return
have[idx >> 3] |= 1 << (idx & 7)
cur[5] += len(body)
def _missing_bitmap(self):
cur = self.cur
cnt = (cur[1] + CHUNK - 1) // CHUNK
miss = bytearray(len(cur[4]))
for i in range(cnt):
if not cur[4][i >> 3] & (1 << (i & 7)):
miss[i >> 3] |= 1 << (i & 7)
return cnt, miss
def _missing(self, mac):
if self.cur is None:
self._reply(mac, self.sess, OP_MISSING, OK, struct.pack("<H", 0))
return
cnt, miss = self._missing_bitmap()
self._reply(mac, self.sess, OP_MISSING, OK, struct.pack("<H", cnt) + miss)
def _end(self, mac):
cur = self.cur
if cur is None:
# already verified: our OK was lost and the controller asks again
self._reply(mac, self.sess, OP_END, OK if self.staged else NOSESS)
return
if cur[5] < cur[1]:
self._reply(mac, self.sess, OP_END, INCOMPLETE)
return
path, sha = cur[0], cur[2]
self._close_cur(False)
try:
ok = file_hashes._hash_file(path + STAGED_SUFFIX) == sha
except OSError:
ok = False
if not ok:
_remove(path + STAGED_SUFFIX)
self._reply(mac, self.sess, OP_END, BADHASH)
return
self.staged[path] = sha
self._reply(mac, self.sess, OP_END, OK)
def _commit(self, mac):
self._close_cur(True)
manifest = file_hashes.load()
failed = False
for path, sha in self.staged.items():
try:
try:
os.rename(path + STAGED_SUFFIX, path)
except OSError:
_remove(path)
os.rename(path + STAGED_SUFFIX, path)
manifest[path] = sha
except OSError:
failed = True
moved = len(self.staged)
self.staged = {}
try:
file_hashes.save(manifest)
with open(LAST_FILE, "w") as f:
f.write(str(self.sess))
except OSError:
failed = True
self.committed = self.sess
self._reply(mac, self.sess, OP_COMMIT, IOERR if failed else OK, struct.pack("<I", moved))
print("ota: committed", moved, "files" + (" with errors" if failed else ""))
if moved:
self._schedule_reset()
def _schedule_reset(self):
if self.reset is not None:
self.reset()
return
import machine
try:
t = machine.Timer(0)
t.init(mode=machine.Timer.ONE_SHOT, period=300, callback=lambda _: machine.reset())
except Exception:
import utime
utime.sleep_ms(300)
machine.reset()
_ota = None
def handle(mac, pkt, send):
global _ota
if _ota is None:
_ota = Ota(send)
_ota.handle(bytes(mac), pkt)
+175
View File
@@ -0,0 +1,175 @@
"""Reliable-link extension of the 0x4C ESP-NOW protocol (driver side).
Extra message types, all inside the existing wire magic 0x4C:
0x20 DATA [4C][20][flags][seq u16][ver u16][idx][cnt] + fragment of an inner packet
flags: 1 = ack wanted, 2 = commit (record ver once complete)
The inner packet is any normal packet (4C 03 CMD, 4C 04 GROUP_CMD, 4C 02 GROUPS, or JSON).
0x21 ACK [4C][21][0][seq u16][cnt][mask u32] driver -> controller
0x22 DIGEST [4C][22][ver u16] controller broadcast
0x23 RESYNC [4C][23][ver u16] driver -> controller
0x24 ECHO [4C][24][beat_idx u16] driver -> controller, bench only
0x25 BEAT [4C][25][flags][idx u16][period u16][fire_in] handled by BeatSync
0x26 OTA [4C][26][sess u16][op][code] + arg driver -> controller, see espnow_ota.py
Everything else (announce, groups, cmd, group cmd, plain JSON) goes straight to the handler.
"""
import struct
WIRE_MAGIC = 0x4C
MSG_DATA = 0x20
MSG_ACK = 0x21
MSG_DIGEST = 0x22
MSG_RESYNC = 0x23
MSG_ECHO = 0x24
MSG_BEAT = 0x25
LINK_TYPES = (MSG_DATA, MSG_DIGEST)
F_ACK = 1
F_COMMIT = 2
HDR = 9
INBOX_MAX = 24
DONE_MAX = 16
ASM_TIMEOUT_MS = 3000
RESYNC_MIN_GAP_MS = 3000
def _due(now, t):
return (now - t) & 0x7FFFFFFF < 0x40000000
class LinkRx:
def __init__(self, handler, beat, send=None, jitter_ms=0, rand=None):
self.handler = handler # handler(mac, packet_bytes)
self.beat = beat # BeatSync
self.send = send # send(mac, frame)
self.jitter_ms = jitter_ms # spreads resync requests across drivers
self.ver = 0
self.master = None
self.inbox = []
self.asm = {}
self.done = []
self.resync_at = None
self.last_resync = None
self.loss_pct = 0 # lossy-link test: drop this percentage of received frames
self.loss_beats = True
self.rand = rand # rand() -> 0..99; defaults to the random module
self.stats = {"msgs": 0, "dups": 0, "acks": 0, "resyncs": 0, "dropped": 0, "sim_lost": 0}
def on_packet(self, mac, data, now):
"""Call for every received frame (irq or main loop). Beats are handled here; the rest is queued."""
if not data:
return
is_beat = len(data) > 1 and data[0] == WIRE_MAGIC and data[1] == MSG_BEAT
if self.loss_pct and (self.loss_beats or not is_beat) and self._rand() < self.loss_pct:
self.stats["sim_lost"] += 1
return
if is_beat:
self.beat.on_frame(data, now)
elif len(self.inbox) < INBOX_MAX:
self.inbox.append((bytes(mac), bytes(data)))
else:
self.stats["dropped"] += 1
def _rand(self):
if self.rand is None:
import random
self.rand = lambda: random.getrandbits(16) % 100
return self.rand()
def echo(self, idx):
"""Tell the controller we just fired beat idx (bench measurement only)."""
if self.send and self.master:
self.send(self.master, struct.pack("<BBH", WIRE_MAGIC, MSG_ECHO, idx))
def poll(self, now):
"""Process queued frames. Call from the main loop."""
while self.inbox:
mac, data = self.inbox.pop(0)
if len(data) > 1 and data[0] == WIRE_MAGIC and data[1] == MSG_DATA:
self._data(mac, data, now)
elif len(data) > 1 and data[0] == WIRE_MAGIC and data[1] == MSG_DIGEST:
self._digest(mac, data, now)
else:
self.handler(mac, data)
if self.resync_at is not None and _due(now, self.resync_at):
self.resync_at = None
self._send_resync(now)
if self.asm:
for k in [k for k, e in self.asm.items() if now - e[3] > ASM_TIMEOUT_MS]:
del self.asm[k]
def _ack(self, mac, seq, cnt, mask):
if self.send:
self.send(mac, struct.pack("<BBBHBI", WIRE_MAGIC, MSG_ACK, 0, seq, cnt, mask))
self.stats["acks"] += 1
def _data(self, mac, data, now):
if len(data) <= HDR:
return
_, _, flags, seq, ver, idx, cnt = struct.unpack("<BBBHHBB", data[:HDR])
if cnt == 0 or cnt > 32 or idx >= cnt:
return
self.master = mac
key = (mac, seq)
full = (1 << cnt) - 1 if cnt < 32 else 0xFFFFFFFF
if key in self.done:
self.stats["dups"] += 1
if flags & F_ACK:
self._ack(mac, seq, cnt, full) # our earlier ack was lost
return
e = self.asm.get(key)
if e is None:
e = self.asm[key] = [cnt, 0, [None] * cnt, now, flags, ver]
e[1] |= 1 << idx
e[2][idx] = data[HDR:]
e[3] = now
if flags & F_ACK:
self._ack(mac, seq, cnt, e[1])
if e[1] != full:
return
del self.asm[key]
self.done.append(key)
if len(self.done) > DONE_MAX:
self.done.pop(0)
msg = e[2][0] if cnt == 1 else b"".join(e[2])
self.stats["msgs"] += 1
self.handler(mac, msg)
if flags & F_COMMIT and ver:
self.ver = ver
self.resync_at = None
def _digest(self, mac, data, now):
if len(data) < 4:
return
self.master = mac
ver = struct.unpack("<H", data[2:4])[0]
if ver == 0 or ver == self.ver or self.resync_at is not None:
return
if self.last_resync is not None and now - self.last_resync < RESYNC_MIN_GAP_MS:
return
self.resync_at = now + self.jitter_ms
def _send_resync(self, now):
if self.send and self.master:
self.last_resync = now
self.stats["resyncs"] += 1
self.send(self.master, struct.pack("<BBH", WIRE_MAGIC, MSG_RESYNC, self.ver))
def make_sender(esp):
"""send(mac, frame) for an espnow.ESPNow instance, adding the peer on first use."""
peers = set()
def send(mac, frame):
if mac not in peers:
try:
esp.add_peer(mac)
except OSError:
pass
peers.add(mac)
try:
esp.send(mac, frame, False)
except OSError:
pass
return send
+18 -1
View File
@@ -14,6 +14,8 @@ from espnow_wire import (
MSG_CMD,
MSG_GROUP_CMD,
MSG_GROUPS,
MSG_OTA_FIRST,
MSG_OTA_LAST,
MSG_PING_REQ,
cmd_envelope,
pack_announce,
@@ -31,6 +33,7 @@ _PING_DELAY_MS_MIN = 50
_PING_DELAY_MS_MAX = 500
_esp = None
_ota_send = None
_groups_received = False
_debug = False
@@ -56,6 +59,11 @@ def init_espnow(settings):
except Exception as e:
print("espnow sta channel set failed:", e)
_esp = espnow.ESPNow()
try:
# The default 526 bytes holds two full frames; an OTA chunk is four
_esp.config(rxbuf=int(settings.get("espnow_rxbuf", 2048)))
except Exception as e:
print("espnow rxbuf set failed:", e)
_esp.active(True)
try:
_esp.add_peer(BROADCAST_MAC)
@@ -125,8 +133,17 @@ def send_boot_announce(settings):
def _handle_packet(host, pkt, settings, presets):
global _groups_received
global _groups_received, _ota_send
mt = wire_msg_type(pkt)
if mt is not None and MSG_OTA_FIRST <= mt <= MSG_OTA_LAST:
import espnow_ota
if _ota_send is None:
from espnow_rx import make_sender
_ota_send = make_sender(_esp)
espnow_ota.handle(host, pkt, _ota_send)
return
if mt == MSG_GROUPS:
ids = parse_groups(pkt)
if ids is not None:
+2
View File
@@ -11,6 +11,8 @@ MSG_CMD = 0x03
MSG_GROUP_CMD = 0x04
MSG_PING_REQ = 0x05
MSG_PING_RSP = 0x06
MSG_OTA_FIRST = 0x07 # 0x07..0x0C app-file OTA, see espnow_ota.py
MSG_OTA_LAST = 0x0C
BROADCAST_MAC = b"\xff\xff\xff\xff\xff\xff"
+3 -2
View File
@@ -47,16 +47,17 @@ def save(files):
def _hash_file(path):
import binascii
import hashlib
h = hashlib.sha256()
with open(path, "rb") as f:
while True:
chunk = f.read(256)
chunk = f.read(1024)
if not chunk:
break
h.update(chunk)
return h.hexdigest()
return binascii.hexlify(h.digest()).decode() # MicroPython's sha256 has no hexdigest()
def _walk_dir(base, prefix, out):
+69 -12
View File
@@ -7,21 +7,29 @@ import json
import network
import espnow
import device_groups as dg
from board import apply_cpu_freq
from presets import Presets
from controller_messages import apply_startup_pattern, process_data
from espnow_transport import _handle_packet, init_espnow
from espnow_wire import BROADCAST_MAC, WIRE_MAGIC
import utime
from beat_sync import BeatSync
from espnow_rx import LinkRx, make_sender
wdt = machine.WDT(timeout=10000)
wdt.feed()
machine.freq(160000000)
apply_cpu_freq()
settings = Settings()
dg.load_from_settings(settings)
print(settings)
gc.collect()
# Bring Wi-Fi up before the pattern library and the LED driver claim memory: on the ESP32-C3 the radio
# tasks otherwise fail to start on about every other cold boot (Wifi Unknown Error 0x0101)
esp = init_espnow(settings)
presets = Presets(settings["led_pin"], settings["num_leds"])
presets.load(settings)
presets.b = settings.get("brightness", 255)
@@ -30,7 +38,6 @@ gc.collect()
apply_startup_pattern(settings, presets)
esp = init_espnow(settings)
print(network.WLAN(network.STA_IF).config("channel"))
hello = json.dumps({
@@ -54,17 +61,67 @@ def _on_espnow_message(host, msg):
process_data(msg, settings, presets)
beat_sync = BeatSync()
link = LinkRx(
_on_espnow_message,
beat_sync,
make_sender(esp),
jitter_ms=int.from_bytes(network.WLAN(network.STA_IF).config("mac")[-2:], "big") % 1000,
)
link.loss_pct = int(settings.get("espnow_loss", 0))
bench = bool(settings.get("bench", False)) # echo each fired beat to the controller, print stats
usb_log = bool(settings.get("usb_log", False)) # print "FIRE <idx> <ticks_us>" per real beat for tools/usb_latency.py
fire_log = None
last_stat = utime.ticks_ms()
beat_pin = None
if settings.get("beat_pin") is not None:
beat_pin = machine.Pin(int(settings["beat_pin"]), machine.Pin.OUT)
def _drain(e):
# Runs scheduled between bytecodes, so frames are taken while presets.tick() is still busy.
# irecv reuses its buffers: on_packet handles beats in place and copies everything else.
while True:
try:
host, msg = e.irecv(0)
except OSError:
return
if not host:
return
if msg:
try:
link.on_packet(host, msg, utime.ticks_ms())
except Exception as ex:
print("espnow rx error:", ex)
try:
esp.irq(_drain)
use_irq = True
except AttributeError: # firmware built without ESP-NOW irq support: poll as before
use_irq = False
while True:
wdt.feed()
while esp.any():
host, msg = esp.recv(0)
if not host or not msg:
continue
print(host, len(msg), "B")
try:
_on_espnow_message(host, msg)
print(msg)
except Exception as e:
print("espnow rx error:", e)
if not use_irq:
_drain(esp)
now = utime.ticks_ms()
try:
link.poll(now)
except Exception as e:
print("espnow rx error:", e)
if beat_sync.poll(now):
fire_us = utime.ticks_us()
presets.beat()
if beat_pin is not None:
beat_pin.value(not beat_pin.value()) # edge for the latency measurement
if usb_log and not beat_sync.freerun_fire:
fire_log = (beat_sync.last_idx, fire_us) # printed after the LED update so it never delays it
if bench and not beat_sync.freerun_fire:
link.echo(beat_sync.last_idx) # only real triggers: an invented beat has no send time to compare
if bench and utime.ticks_diff(now, last_stat) >= 5000:
last_stat = now
print("beat", beat_sync.stats, "link", link.stats, "radio", esp.stats()) # radio: tx, tx_resp, tx_fail, rx, rx_dropped
presets.tick()
if fire_log is not None:
print("FIRE", fire_log[0], fire_log[1])
fire_log = None
+22 -4
View File
@@ -12,6 +12,9 @@ except ImportError:
MAX_PRESETS = 32
# Tests set this so pattern import can feed the 10s watchdog.
load_wdt = None
class Presets:
def __init__(self, pin, num_leds):
@@ -20,6 +23,7 @@ class Presets:
self.step = 0
# Global brightness (0–255), controlled via ESPNow {"b": <value>}
self.b = 255
self.reversed = False
self.generator = None
self.presets = {}
@@ -44,6 +48,8 @@ class Presets:
return loaded
for filename in files:
if load_wdt is not None:
load_wdt.feed()
if not filename.endswith(".py") or filename in ("__init__.py", "main.py"):
continue
module_basename = filename[:-3]
@@ -184,6 +190,14 @@ class Presets:
print(f"Error in tick: {e}")
self.generator = None
def beat(self):
"""Step the selected pattern once; same effect as re-selecting it, without the message."""
name = self.selected
if name in self.presets:
preset = self.presets[name]
if preset.p in self.patterns:
self.generator = self.patterns[preset.p](preset)
def select(self, preset_name, step=None):
# Auto-create simple built-in presets for common names on first use
if preset_name not in self.presets and preset_name in ("on", "off"):
@@ -230,17 +244,22 @@ class Presets:
def is_reversed(self, preset):
from patterns.pattern_direction import is_reversed as _is_reversed
return _is_reversed(preset)
return _is_reversed(preset, self)
def led_i(self, preset, logical_index):
from patterns.pattern_direction import led_i as _led_i
return _led_i(self, preset, logical_index)
def set(self, preset, logical_index, color):
from patterns.pattern_direction import set_led
set_led(self, preset, logical_index, color)
def signed(self, preset, value):
from patterns.pattern_direction import signed as _signed
return _signed(preset, value)
return _signed(preset, value, self)
def apply_brightness(self, color, brightness_override=None):
# Combine per-preset brightness (override) with global brightness self.b
@@ -261,9 +280,8 @@ class Presets:
def on(self, preset):
colors = preset.c
color = colors[0] if colors else (255, 255, 255)
lit = self.apply_brightness(color, preset.b)
while True:
self.fill(lit)
self.fill(self.apply_brightness(color, preset.b))
yield
def blink(self, preset):
+91
View File
@@ -0,0 +1,91 @@
#!/usr/bin/env python3
"""BeatSync accepts exactly one of the two copies of each beat - runs on MicroPython."""
import struct
from beat_sync import BeatSync
def frame(idx, period=500, fire_in=30, flags=0):
return struct.pack("<BBBHHB", 0x4C, 0x25, flags, idx, period, fire_in)
def run(events, tick=1):
"""events: (time_ms, frame_bytes). Returns the number of fires."""
b = BeatSync()
fires = 0
t = 0
end = events[-1][0] + 200
ev = list(events)
while t < end:
while ev and ev[0][0] <= t:
b.on_frame(ev.pop(0)[1], t)
if b.poll(t):
fires += 1
t += tick
return fires
def test_both_copies():
assert run([(0, frame(1)), (2, frame(1, fire_in=28))]) == 1
def test_only_first():
assert run([(0, frame(1))]) == 1
def test_only_second():
assert run([(2, frame(1, fire_in=28))]) == 1
def test_wraparound():
b = BeatSync()
assert b.on_frame(frame(0xFFFF), 0)
assert not b.on_frame(frame(0xFFFF), 2)
assert b.on_frame(frame(0), 500)
def test_late_old_copy_ignored():
b = BeatSync()
assert b.on_frame(frame(5), 0)
assert b.on_frame(frame(6), 500)
assert not b.on_frame(frame(5), 502)
def test_two_beats_two_fires():
ev = [(0, frame(1)), (2, frame(1)), (500, frame(2)), (502, frame(2))]
assert run(ev) == 2
def test_free_run_covers_missed_beat():
# beat 3 lost entirely: the driver still fires about once per period
ev = [(0, frame(1)), (2, frame(1)), (500, frame(2)), (502, frame(2)), (1500, frame(4)), (1502, frame(4))]
assert run(ev) == 4
def test_bad_frames():
b = BeatSync()
assert not b.on_frame(b"\x00" * 8, 0)
assert not b.on_frame(b"\xb1\x00", 0)
def test_freerun_flag_marks_invented_beats():
b = BeatSync()
b.on_frame(frame(1), 0)
assert b.poll(40) is True and b.freerun_fire is False
assert b.poll(700) is True and b.freerun_fire is True
def test_stats_count_dups_and_freerun():
b = BeatSync()
b.on_frame(frame(1), 0)
b.on_frame(frame(1), 2)
b.poll(40)
assert b.stats["fires"] == 1 and b.stats["dups"] == 1
b.poll(700)
assert b.stats["freerun"] == 1 and b.stats["fires"] == 2
if __name__ == "__main__":
for name, fn in list(globals().items()):
if name.startswith("test_"):
fn()
print("ok", name)
+231
View File
@@ -0,0 +1,231 @@
#!/usr/bin/env python3
"""Ota: staging, chunk bitmap, hash checks, commit and sessions. Runs in a temp directory."""
import hashlib
import json
import os
import struct
import tempfile
import espnow_ota as o
import file_hashes
M = b"\x01\x02\x03\x04\x05\x06"
def begin(sess, path, body):
p = path.encode()
return struct.pack("<BBHI", 0x4C, o.OP_BEGIN, sess, len(body)) + hashlib.sha256(body).digest() + bytes([len(p)]) + p
def chunk(sess, body, idx):
return struct.pack("<BBHH", 0x4C, o.OP_DATA, sess, idx) + body[idx * o.CHUNK : (idx + 1) * o.CHUNK]
def cmd(op, sess):
return struct.pack("<BBH", 0x4C, op, sess)
def nchunks(body):
return (len(body) + o.CHUNK - 1) // o.CHUNK
class Rig:
def __init__(self):
self.sent, self.resets = [], 0
self.ota = o.Ota(lambda mac, f: self.sent.append(f), self._reset)
def _reset(self):
self.resets += 1
def __call__(self, pkt):
self.ota.handle(M, pkt)
if self.sent:
f = self.sent.pop()
_, t, sess, op, code = struct.unpack_from("<BBHBB", f)
assert t == o.MSG_STATUS
return op, code, f[6:]
return None
def send_file(self, sess, path, body, skip=()):
assert self(begin(sess, path, body))[1] == o.READY
for i in range(nchunks(body)):
if i not in skip:
assert self(chunk(sess, body, i)) is None # data is acked by the link, not here
return self(cmd(o.OP_END, sess))[1]
def in_tmp(fn):
def run():
old = os.getcwd()
with tempfile.TemporaryDirectory() as d:
os.chdir(d)
try:
fn()
finally:
os.chdir(old)
run.__name__ = fn.__name__
return run
BODY = bytes(range(256)) * 10 # 2560 bytes, 3 chunks
@in_tmp
def test_write_commit_and_manifest():
r = Rig()
assert r.send_file(5, "patterns/wave.py", BODY) == o.OK
assert not os.path.exists("patterns/wave.py") # staged only
op, code, arg = r(cmd(o.OP_COMMIT, 5))
assert (op, code, struct.unpack("<I", arg)[0]) == (o.OP_COMMIT, o.OK, 1)
assert open("patterns/wave.py", "rb").read() == BODY and not os.path.exists("patterns/wave.py.new")
assert file_hashes.load()["patterns/wave.py"] == hashlib.sha256(BODY).hexdigest()
assert r.resets == 1
@in_tmp
def test_same_file_is_skipped():
with open("main.py", "wb") as f:
f.write(BODY)
r = Rig()
assert r(begin(1, "main.py", BODY))[1] == o.SAME
op, code, _ = r(cmd(o.OP_COMMIT, 1))
assert code == o.OK and r.resets == 0 # nothing moved, no reset
@in_tmp
def test_out_of_order_and_duplicate_chunks():
r = Rig()
assert r(begin(2, "a.py", BODY))[1] == o.READY
for i in (2, 0, 2, 1, 0):
r(chunk(2, BODY, i))
assert r(cmd(o.OP_END, 2))[1] == o.OK
r(cmd(o.OP_COMMIT, 2))
assert open("a.py", "rb").read() == BODY
@in_tmp
def test_incomplete_then_missing_then_repair():
r = Rig()
assert r.send_file(3, "a.py", BODY, skip=(0, 2)) == o.INCOMPLETE
op, code, arg = r(cmd(o.OP_MISSING, 3))
cnt = struct.unpack_from("<H", arg)[0]
assert (op, cnt, arg[2]) == (o.OP_MISSING, 3, 0b101)
r(chunk(3, BODY, 0))
r(chunk(3, BODY, 2))
assert r(cmd(o.OP_MISSING, 3))[2][2] == 0
assert r(cmd(o.OP_END, 3))[1] == o.OK
@in_tmp
def test_bad_hash_is_not_staged():
r = Rig()
bad = bytearray(begin(4, "a.py", BODY))
bad[8] ^= 0xFF
assert r(bytes(bad))[1] == o.READY
for i in range(nchunks(BODY)):
r(chunk(4, BODY, i))
assert r(cmd(o.OP_END, 4))[1] == o.BADHASH
r(cmd(o.OP_COMMIT, 4))
assert not os.path.exists("a.py") and not os.path.exists("a.py.new") and r.resets == 0
@in_tmp
def test_bad_paths():
r = Rig()
for p in ("../x.py", "/main.py", "a/b.py", "lib//x.py", "file_hashes.json", "patterns\\x.py", "lib/../main.py"):
assert r(begin(6, p, b"x"))[1] == o.BADPATH, p
for p in ("main.py", "patterns/x.py", "lib/microdot/websocket.py"):
assert r(begin(6, p, b"x"))[1] == o.READY, p
@in_tmp
def test_new_session_discards_staged():
r = Rig()
assert r.send_file(7, "a.py", BODY) == o.OK
assert os.path.exists("a.py.new")
assert r(begin(8, "b.py", b"bb"))[1] == o.READY
assert not os.path.exists("a.py.new")
assert r(cmd(o.OP_COMMIT, 7))[1] == o.NOSESS # old session is gone
@in_tmp
def test_repeated_begin_and_end_are_idempotent():
r = Rig()
assert r(begin(9, "a.py", BODY))[1] == o.READY
r(chunk(9, BODY, 0))
assert r(begin(9, "a.py", BODY))[1] == o.READY # reply was lost, controller asks again
r(chunk(9, BODY, 1))
r(chunk(9, BODY, 2))
assert r(cmd(o.OP_END, 9))[1] == o.OK
assert r(cmd(o.OP_END, 9))[1] == o.OK
assert r(begin(9, "a.py", BODY))[1] == o.READY # already staged with that hash
@in_tmp
def test_abort_removes_staged():
r = Rig()
r.send_file(10, "a.py", BODY)
assert r(cmd(o.OP_ABORT, 10))[1] == o.OK
assert not os.path.exists("a.py.new")
assert r(cmd(o.OP_COMMIT, 10))[2] == struct.pack("<I", 0)
@in_tmp
def test_broadcast_with_loss_recovers():
# three drivers share one broadcast; each drops different chunks, then gets repaired by unicast
body = os.urandom(o.CHUNK * 7 + 100)
rigs = [Rig() for _ in range(3)]
for k, r in enumerate(rigs):
os.makedirs(str(k))
old = os.getcwd()
for k, r in enumerate(rigs):
os.chdir(str(k))
assert r(begin(11, "lib/x.py", body))[1] == o.READY
for i in range(nchunks(body)):
if (i + k) % 3:
r(chunk(11, body, i))
assert r(cmd(o.OP_END, 11))[1] == o.INCOMPLETE
arg = r(cmd(o.OP_MISSING, 11))[2]
cnt = struct.unpack_from("<H", arg)[0]
for i in range(cnt):
if arg[2 + (i >> 3)] & (1 << (i & 7)):
r(chunk(11, body, i))
assert r(cmd(o.OP_END, 11))[1] == o.OK
r(cmd(o.OP_COMMIT, 11))
assert open("lib/x.py", "rb").read() == body
os.chdir(old)
@in_tmp
def test_commit_repeated_after_reset():
r = Rig()
r.send_file(14, "a.py", BODY)
assert r(cmd(o.OP_COMMIT, 14))[1] == o.OK
fresh = Rig() # the driver reset before its reply arrived
op, code, arg = fresh(cmd(o.OP_COMMIT, 14))
assert code == o.OK and fresh.resets == 0
assert fresh(cmd(o.OP_COMMIT, 15))[1] == o.NOSESS
@in_tmp
def test_empty_file():
r = Rig()
assert r.send_file(13, "lib/pkg/__init__.py", b"") == o.OK
r(cmd(o.OP_COMMIT, 13))
assert open("lib/pkg/__init__.py", "rb").read() == b""
@in_tmp
def test_too_big_rejected():
r = Rig()
pkt = bytearray(begin(12, "a.py", b"x"))
struct.pack_into("<I", pkt, 4, o.MAX_SIZE + 1)
assert r(bytes(pkt))[1] == o.TOOBIG
if __name__ == "__main__":
for name, fn in list(globals().items()):
if name.startswith("test_"):
fn()
print("ok")
+156
View File
@@ -0,0 +1,156 @@
#!/usr/bin/env python3
"""LinkRx: reassembly, dedupe, acks, commit and digest resync."""
import struct
from espnow_rx import LinkRx, MSG_DATA, MSG_ACK, MSG_DIGEST, MSG_RESYNC, F_ACK, F_COMMIT, INBOX_MAX
from beat_sync import BeatSync
M = b"\x01\x02\x03\x04\x05\x06"
def data(seq, payload, idx=0, cnt=1, flags=F_ACK, ver=0):
return struct.pack("<BBBHHBB", 0x4C, MSG_DATA, flags, seq, ver, idx, cnt) + payload
def make(jitter=0):
got, sent = [], []
link = LinkRx(lambda mac, m: got.append(m), BeatSync(), lambda mac, f: sent.append((mac, f)), jitter)
return link, got, sent
def feed(link, frame, now=0, mac=M):
link.on_packet(mac, frame, now)
link.poll(now)
def test_single():
link, got, sent = make()
feed(link, data(1, b"hello"))
assert got == [b"hello"]
_, t, _, seq, cnt, mask = struct.unpack("<BBBHBI", sent[0][1])
assert (t, seq, cnt, mask) == (MSG_ACK, 1, 1, 1)
def test_duplicate_acks_again_but_delivers_once():
link, got, sent = make()
feed(link, data(1, b"x"))
feed(link, data(1, b"x"), now=60)
assert got == [b"x"] and len(sent) == 2 and link.stats["dups"] == 1
def test_fragments_out_of_order_and_partial_mask():
link, got, sent = make()
feed(link, data(7, b"CC", 2, 3))
assert got == [] and struct.unpack("<BBBHBI", sent[-1][1])[5] == 0b100
feed(link, data(7, b"AA", 0, 3))
assert struct.unpack("<BBBHBI", sent[-1][1])[5] == 0b101
feed(link, data(7, b"BB", 1, 3))
assert got == [b"AABBCC"] and struct.unpack("<BBBHBI", sent[-1][1])[5] == 0b111
def test_stale_fragments_dropped():
link, got, _ = make()
feed(link, data(3, b"A", 0, 2), now=0)
feed(link, data(9, b"x"), now=4000) # triggers cleanup
feed(link, data(3, b"B", 1, 2), now=4001)
assert got == [b"x"]
def test_no_ack_when_not_requested():
link, got, sent = make()
feed(link, data(2, b"b", flags=0))
assert got == [b"b"] and sent == []
def test_commit_sets_version_only_when_complete():
link, got, _ = make()
feed(link, data(1, b"A", 0, 2, F_ACK | F_COMMIT, ver=5))
assert link.ver == 0
feed(link, data(1, b"B", 1, 2, F_ACK | F_COMMIT, ver=5))
assert link.ver == 5
feed(link, data(2, b"p", flags=0, ver=6)) # no commit flag: version unchanged
assert link.ver == 5
def digest(ver):
return struct.pack("<BBH", 0x4C, MSG_DIGEST, ver)
def test_digest_match_no_resync():
link, _, sent = make()
feed(link, data(1, b"a", flags=F_COMMIT, ver=4))
feed(link, digest(4), now=100)
link.poll(5000)
assert not [s for s in sent if s[1][1] == MSG_RESYNC]
def test_digest_mismatch_requests_resync_after_jitter_and_rate_limits():
link, _, sent = make(jitter=300)
feed(link, digest(9), now=1000)
link.poll(1100)
assert sent == [] # jitter not elapsed
link.poll(1300)
assert sent[-1] == (M, struct.pack("<BBH", 0x4C, MSG_RESYNC, 0))
feed(link, digest(9), now=2000)
link.poll(2400)
assert len(sent) == 1 # within the 3 s gap
feed(link, digest(9), now=4500)
link.poll(4900)
assert len(sent) == 2
def test_resync_cancelled_when_state_arrives():
link, _, sent = make(jitter=500)
feed(link, digest(9), now=0)
feed(link, data(1, b"s", flags=F_COMMIT, ver=9), now=100)
link.poll(600)
assert sent == []
def test_digest_zero_ignored():
link, _, sent = make()
feed(link, digest(0), now=0)
link.poll(5000)
assert sent == []
def test_legacy_and_beat_frames():
link, got, _ = make()
feed(link, b"\x4c\x03\x02\xff\x00\x00\x00") # plain CMD passes straight to the handler
feed(link, b'{"v":"1"}')
assert len(got) == 2
link.on_packet(M, struct.pack("<BBBHHB", 0x4C, 0x25, 0, 1, 500, 0), 0)
assert link.beat.poll(0) is True
def test_inbox_overflow_counted():
link, _, _ = make()
for i in range(INBOX_MAX + 4):
link.on_packet(M, data(i, b"x"), 0)
assert link.stats["dropped"] == 4
def test_loss_drops_frames_and_can_spare_beats():
seq = iter([5, 90, 5, 90])
link, got, _ = make()
link.rand = lambda: next(seq)
link.loss_pct = 50
feed(link, data(1, b"a")) # 5 < 50: lost
feed(link, data(2, b"b")) # 90: kept
assert got == [b"b"] and link.stats["sim_lost"] == 1
link.loss_beats = False
link.on_packet(M, struct.pack("<BBBHHB", 0x4C, 0x25, 0, 1, 500, 0), 0) # beats exempt, rand not consulted
assert link.beat.poll(0) is True
def test_echo_goes_to_master():
link, _, sent = make()
feed(link, data(1, b"a"))
link.echo(0x1234)
assert sent[-1] == (M, struct.pack("<BBH", 0x4C, 0x24, 0x1234))
if __name__ == "__main__":
for name, fn in list(globals().items()):
if name.startswith("test_"):
fn()
print("ok", name)