Files
led-controller/tools/usb_latency.py
jimmyandClaude Opus 5.5 1c222771a5 refactor: move the v2 controller to the repository root
The ESP-IDF project, docs, tools, tests and web UI move from v2/ to the
root, and the Makefile, README, build scripts and test runner drop the
v2/ prefix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 23:44:58 +13:00

153 lines
6.4 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)")
ap.add_argument("--settle", type=float, default=0.5,
help="seconds to wait after opening the ports; use about 14 for an ESP32-C3 driver, which "
"resets when its USB port is opened")
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(a.settle)
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()