Files
led-controller/v2/tools/usb_latency.py
T
jimmyandClaude Sonnet 5.5 a94d6a7de5 feat(v2): ESP32-S3 controller with Ethernet, I2S mic beat detection and ESP-NOW
New ESP-IDF project in v2/ that replaces the Pi and the UART bridge:

- W5500 Ethernet, INMP441 beat/tempo detector (from esp32-eth), ESP-NOW master
- LittleFS data store and a JSON API over the Pi's db/*.json collections,
  with /db import and export; web UI minified and gzipped at build time
- Zone play/stop as 0x4C GROUP_CMD, preset push/send as CMD (binary v2
  envelope, byte-identical to src/util/binary_envelope.py), sequencer and
  scenes, driver registration from the boot hello
- Reliable bulk link: acks with retransmit, fragments, state-version digest
  and resync; beat frames sent twice with a lead so drivers fire together
- Bench tooling: lossy-link mode, synthetic beats with echo measurement,
  USB and logic-analyzer latency scripts, and docs/BENCH_TEST.md

Needs the matching led-driver changes (p2p branch) to receive the link and
beat frames.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-27 17:15:28 +13:00

150 lines
6.1 KiB
Python
Executable File

#!/usr/bin/env python3
"""Beat latency over USB, no logic analyzer.
Starts the controller's synthetic beat generator, reads one timestamped line
from each board's USB serial port, and works out how long the driver took to
fire after the controller sent each beat.
controller prints BT <beat_idx> <esp_timer_us> (just before the first copy goes out)
driver prints FIRE <beat_idx> <ticks_us> (when the beat triggers a pattern step)
The two boards have unrelated clocks and USB adds a variable delay of its own.
Each board's clock is mapped onto the PC clock with the *fastest* USB deliveries
(lower envelope of host-time minus board-time, fitted per 5 s window, so crystal
drift is removed). Differences between the two mapped clocks are then the latency.
What remains is the gap between the two USB paths' minimum delays (about a
millisecond at worst) plus noise; the report prints the residual USB jitter so
you can judge it. The driver needs "usb_log": true in settings.json.
usb_latency.py --ctrl-port /dev/ttyACM0 --drv-port /dev/ttyACM1 --url http://10.1.1.180
"""
import argparse
import json
import re
import statistics
import threading
import time
import urllib.request
import serial
TICKS_PERIOD_US = 1 << 30 # MicroPython ticks_us wraps here
class Reader(threading.Thread):
def __init__(self, port, pattern):
super().__init__(daemon=True)
self.ser = serial.Serial(port, 115200, timeout=0.05)
self.pattern = re.compile(pattern)
self.events = [] # (idx, device_us, host_s)
self.running = True
self.buf = b""
def run(self):
while self.running:
try:
chunk = self.ser.read(4096)
except serial.SerialException:
break
if not chunk:
continue
now = time.perf_counter() # one stamp per USB chunk
self.buf += chunk
*lines, self.buf = self.buf.split(b"\n")
for ln in lines:
m = self.pattern.search(ln.decode(errors="replace"))
if m:
self.events.append((int(m.group(1)), int(m.group(2)), now))
def unwrap(events, period=None):
"""Make device timestamps monotonic (handles the driver's wrapping tick counter)."""
out, add, prev = [], 0, None
for idx, us, host in events:
if period and prev is not None and us + add < prev - period // 2:
add += period
out.append((idx, (us + add) / 1e6, host))
prev = us + add
return out
def fit_clock(events, window_s=5.0):
"""Map device seconds to host seconds using the fastest deliveries. Returns (a, b, residuals)."""
pts = [(d, h - d) for _, d, h in events] # (device time, host minus device)
t0 = pts[0][0]
mins = {}
for d, off in pts:
k = int((d - t0) // window_s)
if k not in mins or off < mins[k][1]:
mins[k] = (d, off)
xs, ys = zip(*mins.values()) if len(mins) > 1 else (zip(*mins.values()))
xs, ys = list(xs), list(ys)
if len(xs) < 2:
b, a = 0.0, ys[0]
else:
mx, my = statistics.mean(xs), statistics.mean(ys)
den = sum((x - mx) ** 2 for x in xs) or 1.0
b = sum((x - mx) * (y - my) for x, y in zip(xs, ys)) / den
a = my - b * mx
lowest = min(off - (a + b * d) for d, off in pts)
a += lowest # shift so the fastest delivery sits exactly on the line
resid = sorted((off - (a + b * d)) * 1000 for d, off in pts)
return a, b, resid
def pct(vals, p):
return vals[min(len(vals) - 1, int(round(p / 100 * (len(vals) - 1))))]
def main():
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--ctrl-port", default="/dev/ttyACM0")
ap.add_argument("--drv-port", default="/dev/ttyACM1")
ap.add_argument("--url", default="http://10.1.1.180")
ap.add_argument("--bpm", type=float, default=120)
ap.add_argument("--beats", type=int, default=200)
ap.add_argument("--lead-ms", type=float, default=30.0, help="CONFIG_BEAT_LEAD_MS")
ap.add_argument("--no-start", action="store_true", help="do not start the generator (it is already running)")
a = ap.parse_args()
rc = Reader(a.ctrl_port, r"\bBT (\d+) (\d+)")
rd = Reader(a.drv_port, r"\bFIRE (\d+) (\d+)")
rc.start(); rd.start()
time.sleep(0.5)
if not a.no_start:
req = urllib.request.Request(a.url + "/test/beats", data=json.dumps({"bpm": a.bpm, "count": a.beats}).encode(),
method="POST")
urllib.request.urlopen(req, timeout=10).read()
wait = a.beats * 60.0 / a.bpm + 4
print(f"running {a.beats} beats at {a.bpm:g} BPM, about {wait:.0f} s ...")
time.sleep(wait)
rc.running = rd.running = False
time.sleep(0.2)
ctrl, drv = unwrap(rc.events), unwrap(rd.events, TICKS_PERIOD_US)
if len(ctrl) < 5 or len(drv) < 5:
raise SystemExit(f"too few events: controller {len(ctrl)}, driver {len(drv)} "
"(driver needs usb_log:true; check ports)")
ca, cb, cres = fit_clock(ctrl)
da, db, dres = fit_clock(drv)
c_host = {i: d + ca + cb * d for i, d, _ in ctrl}
lat = []
for i, d, _ in drv:
if i in c_host:
lat.append((d + da + db * d - c_host[i]) * 1000 - a.lead_ms)
lat.sort()
print(f"controller events {len(ctrl)}, driver events {len(drv)}, matched {len(lat)}")
print(f"clock drift: controller {cb*1e6:+.1f} ppm, driver {db*1e6:+.1f} ppm (relative to the PC)")
print(f"USB delivery jitter above the fastest (ms), p50/p95/max: controller {pct(cres,50):.2f}/{pct(cres,95):.2f}/{cres[-1]:.2f} "
f"driver {pct(dres,50):.2f}/{pct(dres,95):.2f}/{dres[-1]:.2f}")
if not lat:
raise SystemExit("no beat index matched on both ports")
print(f"delay beyond the {a.lead_ms:g} ms lead (ms): min {lat[0]:.2f} mean {statistics.mean(lat):.2f} "
f"median {pct(lat,50):.2f} p95 {pct(lat,95):.2f} max {lat[-1]:.2f} std {statistics.pstdev(lat):.2f}")
print("accuracy: systematic error about +/-1 ms (difference of the two USB paths' fastest delivery); "
"use the logic analyzer if you need better")
if __name__ == "__main__":
main()