#!/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 (just before the first copy goes out) driver prints FIRE (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()