diff --git a/src/beat_sync.py b/src/beat_sync.py new file mode 100644 index 0000000..7d521d0 --- /dev/null +++ b/src/beat_sync.py @@ -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("= 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 diff --git a/src/board.py b/src/board.py new file mode 100644 index 0000000..40aa76d --- /dev/null +++ b/src/board.py @@ -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) diff --git a/src/controller_messages.py b/src/controller_messages.py index 3790408..bb95482 100644 --- a/src/controller_messages.py +++ b/src/controller_messages.py @@ -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 diff --git a/src/espnow_rx.py b/src/espnow_rx.py new file mode 100644 index 0000000..925aaba --- /dev/null +++ b/src/espnow_rx.py @@ -0,0 +1,174 @@ +"""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 +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 = 16 +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(" 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(" 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(" " 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) while True: wdt.feed() @@ -61,10 +80,28 @@ while True: 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) + link.on_packet(host, msg, utime.ticks_ms()) except Exception as e: print("espnow rx error:", e) + 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) presets.tick() + if fire_log is not None: + print("FIRE", fire_log[0], fire_log[1]) + fire_log = None diff --git a/src/presets.py b/src/presets.py index 9c1011b..d87ea05 100644 --- a/src/presets.py +++ b/src/presets.py @@ -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": } 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): diff --git a/tests/test_beat_sync.py b/tests/test_beat_sync.py new file mode 100644 index 0000000..34afa82 --- /dev/null +++ b/tests/test_beat_sync.py @@ -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("