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>
This commit is contained in:
1 parent
71bd320661
commit
1c222771a5
66 files changed
+30
-31
No files matched your search
Executable
+97
@@ -0,0 +1,97 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Beat latency from a logic analyzer capture.
|
||||
|
||||
Reads a CSV with a time column and two digital channels: the controller beat
|
||||
marker (CONFIG_BEAT_TEST_GPIO, toggles when the first copy of a beat goes out)
|
||||
and the driver beat marker (`beat_pin`, toggles when the driver fires). For
|
||||
every controller edge it finds the next driver edge and reports the delay minus
|
||||
the deliberate lead (CONFIG_BEAT_LEAD_MS, default 30 ms).
|
||||
|
||||
Works with Saleae ("Time [s],Channel 0,Channel 1") and sigrok CSV exports, or
|
||||
any CSV whose first column is time and whose other columns are 0/1 levels.
|
||||
|
||||
analyze_edges.py capture.csv --ctrl 0 --drv 1
|
||||
"""
|
||||
import argparse
|
||||
import csv
|
||||
import statistics
|
||||
import sys
|
||||
|
||||
|
||||
def read(path, time_scale):
|
||||
times, rows = [], []
|
||||
with open(path, newline="") as f:
|
||||
for row in csv.reader(f):
|
||||
if not row or row[0].lstrip().startswith((";", "#")):
|
||||
continue
|
||||
try:
|
||||
t = float(row[0]) * time_scale
|
||||
levels = [int(float(c)) for c in row[1:]]
|
||||
except ValueError:
|
||||
continue # header line
|
||||
times.append(t)
|
||||
rows.append(levels)
|
||||
return times, rows
|
||||
|
||||
|
||||
def edges(times, rows, ch):
|
||||
out, prev = [], None
|
||||
for t, r in zip(times, rows):
|
||||
v = r[ch]
|
||||
if prev is not None and v != prev:
|
||||
out.append(t)
|
||||
prev = v
|
||||
return out
|
||||
|
||||
|
||||
def analyze(ctrl, drv, lead_s, window_s):
|
||||
deltas, missed, j = [], 0, 0
|
||||
for i, t in enumerate(ctrl):
|
||||
nxt = ctrl[i + 1] if i + 1 < len(ctrl) else float("inf")
|
||||
while j < len(drv) and drv[j] < t:
|
||||
j += 1
|
||||
if j < len(drv) and drv[j] - t <= min(window_s, nxt - t):
|
||||
deltas.append(drv[j] - t - lead_s)
|
||||
j += 1
|
||||
else:
|
||||
missed += 1
|
||||
return deltas, missed
|
||||
|
||||
|
||||
def pct(sorted_vals, p):
|
||||
if not sorted_vals:
|
||||
return float("nan")
|
||||
k = min(len(sorted_vals) - 1, int(round(p / 100 * (len(sorted_vals) - 1))))
|
||||
return sorted_vals[k]
|
||||
|
||||
|
||||
def main(argv=None):
|
||||
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
ap.add_argument("csv")
|
||||
ap.add_argument("--ctrl", type=int, default=0, help="column index of the controller marker (0 = first channel)")
|
||||
ap.add_argument("--drv", type=int, default=1, help="column index of the driver marker")
|
||||
ap.add_argument("--lead-ms", type=float, default=30.0, help="deliberate lead to subtract (CONFIG_BEAT_LEAD_MS)")
|
||||
ap.add_argument("--window-ms", type=float, default=200.0, help="longest delay still counted as the same beat")
|
||||
ap.add_argument("--time-unit", choices=("s", "ms", "us", "ns"), default="s", help="unit of the time column")
|
||||
a = ap.parse_args(argv)
|
||||
|
||||
scale = {"s": 1.0, "ms": 1e-3, "us": 1e-6, "ns": 1e-9}[a.time_unit]
|
||||
times, rows = read(a.csv, scale)
|
||||
if not times:
|
||||
sys.exit("no samples read")
|
||||
ctrl, drv = edges(times, rows, a.ctrl), edges(times, rows, a.drv)
|
||||
deltas, missed = analyze(ctrl, drv, a.lead_ms / 1000, a.window_ms / 1000)
|
||||
ms = sorted(d * 1000 for d in deltas)
|
||||
print(f"controller edges: {len(ctrl)} driver edges: {len(drv)} matched: {len(ms)} unmatched: {missed}")
|
||||
if not ms:
|
||||
sys.exit("no matched edges: check channel numbers and --time-unit")
|
||||
print(f"delay beyond the {a.lead_ms:g} ms lead (ms): min {ms[0]:.2f} mean {statistics.mean(ms):.2f} "
|
||||
f"median {pct(ms, 50):.2f} p95 {pct(ms, 95):.2f} max {ms[-1]:.2f}")
|
||||
if len(ms) > 1:
|
||||
print(f"jitter (std dev): {statistics.stdev(ms):.2f} ms")
|
||||
if a.lead_ms and ms[0] < -1:
|
||||
print("note: negative delays mean the lead is larger than the real one; check --lead-ms", file=sys.stderr)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Executable
+55
@@ -0,0 +1,55 @@
|
||||
#!/usr/bin/env bash
|
||||
# Minify and gzip the web UI into www_dist and pack it into www_dist/www.pack, which the
|
||||
# firmware embeds (main/CMakeLists.txt). Usage: tools/build_web.sh (needs node/npx; WWW_MAX = size limit in bytes)
|
||||
set -euo pipefail
|
||||
cd "$(dirname "$0")/.."
|
||||
SRC=web
|
||||
OUT=www_dist
|
||||
MAX=${WWW_MAX:-524288}
|
||||
rm -rf "$OUT"; mkdir -p "$OUT/static"
|
||||
|
||||
for f in "$SRC"/static/*; do
|
||||
[[ -f $f ]] || continue
|
||||
b=$(basename "$f")
|
||||
case $b in
|
||||
*.min.js) cp "$f" "$OUT/static/$b" ;;
|
||||
*.js|*.css) npx --yes esbuild@0.25.0 "$f" --minify --target=es2019 --legal-comments=none \
|
||||
--outfile="$OUT/static/$b" --log-level=warning ;;
|
||||
*) cp "$f" "$OUT/static/$b" ;;
|
||||
esac
|
||||
done
|
||||
for p in index settings; do
|
||||
npx --yes html-minifier-terser@7.2.0 --collapse-whitespace --remove-comments \
|
||||
--minify-css true --minify-js true -o "$OUT/$p.html" "$SRC/templates/$p.html"
|
||||
done
|
||||
|
||||
# Live audio and beat page (served at /audio)
|
||||
npx --yes html-minifier-terser@7.2.0 --collapse-whitespace --remove-comments \
|
||||
--minify-css true --minify-js true -o "$OUT/audio.html" web/audio.html
|
||||
|
||||
# Ship only the .gz copies; the server sends Content-Encoding: gzip
|
||||
find "$OUT" -type f -exec gzip -9 -n -f {} \;
|
||||
find "$OUT" -name '*.gz' -exec gzip -t {} \;
|
||||
|
||||
total=$(find "$OUT" -name '*.gz' -printf '%s\n' | paste -sd+ | bc)
|
||||
echo "www_dist: $(find "$OUT" -name '*.gz' | wc -l) files, $total bytes (limit $MAX)"
|
||||
(( total <= MAX )) || { echo "ERROR: web UI exceeds the size limit" >&2; exit 1; }
|
||||
|
||||
# One blob for the firmware: "WWW1", then per file u16 name length, u32 data length, name (no .gz),
|
||||
# data; a zero name length ends it. Little-endian, read by main/web.c.
|
||||
python3 - "$OUT" <<'PY'
|
||||
import os, struct, sys
|
||||
root = sys.argv[1]
|
||||
out = bytearray(b"WWW1")
|
||||
for dirpath, _, names in sorted(os.walk(root)):
|
||||
for n in sorted(names):
|
||||
if not n.endswith(".gz"):
|
||||
continue
|
||||
full = os.path.join(dirpath, n)
|
||||
name = os.path.relpath(full, root)[:-3].encode()
|
||||
data = open(full, "rb").read()
|
||||
out += struct.pack("<HI", len(name), len(data)) + name + data
|
||||
out += struct.pack("<H", 0)
|
||||
open(os.path.join(root, "www.pack"), "wb").write(out)
|
||||
print("www.pack: %d bytes" % len(out))
|
||||
PY
|
||||
@@ -0,0 +1,55 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Upload the firmware (which includes the web UI) to the controller over Ethernet.
|
||||
|
||||
ota.py <host> [firmware.bin]
|
||||
|
||||
Default is build/led_controller.bin next to this script. The board reboots into the new image.
|
||||
"""
|
||||
import http.client
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import time
|
||||
|
||||
host = sys.argv[1] if len(sys.argv) > 1 else sys.exit(__doc__)
|
||||
build = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "build")
|
||||
fw = sys.argv[2] if len(sys.argv) > 2 else os.path.join(build, "led_controller.bin")
|
||||
|
||||
|
||||
def info():
|
||||
try:
|
||||
c = http.client.HTTPConnection(host, 80, timeout=5)
|
||||
c.request("GET", "/ota")
|
||||
r = c.getresponse()
|
||||
return json.loads(r.read().decode()) if r.status == 200 else None
|
||||
except (OSError, ValueError):
|
||||
return None
|
||||
|
||||
|
||||
def upload(path, url):
|
||||
size = os.path.getsize(path)
|
||||
print(f"uploading {path} ({size} bytes) to {url}")
|
||||
c = http.client.HTTPConnection(host, 80, timeout=120)
|
||||
with open(path, "rb") as f:
|
||||
c.request("POST", url, body=f, headers={"Content-Length": str(size),
|
||||
"Content-Type": "application/octet-stream"})
|
||||
r = c.getresponse()
|
||||
body = r.read().decode()
|
||||
print(r.status, body)
|
||||
if r.status != 200:
|
||||
sys.exit(1)
|
||||
time.sleep(3)
|
||||
for _ in range(30):
|
||||
i = info()
|
||||
if i:
|
||||
print("back up on", i["partition"])
|
||||
return
|
||||
time.sleep(1)
|
||||
sys.exit("controller did not come back within 30 s")
|
||||
|
||||
|
||||
before = info()
|
||||
print("running:", before)
|
||||
if before is None:
|
||||
sys.exit("no OTA endpoint (is this the LED controller?)")
|
||||
upload(fw, "/ota")
|
||||
@@ -0,0 +1,18 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Run the led-driver link and beat tests on the host (they are plain Python)."""
|
||||
import os
|
||||
import sys
|
||||
|
||||
root = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "led-driver")
|
||||
sys.path[:0] = [os.path.join(root, "src"), os.path.join(root, "tests")]
|
||||
|
||||
import test_beat_sync # noqa: E402
|
||||
import test_espnow_rx # noqa: E402
|
||||
|
||||
n = 0
|
||||
for mod in (test_espnow_rx, test_beat_sync):
|
||||
for name, fn in vars(mod).items():
|
||||
if name.startswith("test_") and callable(fn):
|
||||
fn()
|
||||
n += 1
|
||||
print(f"{n} driver tests passed")
|
||||
@@ -0,0 +1,19 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Reset the board on PORT and print its console for SECS seconds (no terminal needed)."""
|
||||
import sys
|
||||
import time
|
||||
|
||||
import serial
|
||||
|
||||
port = sys.argv[1] if len(sys.argv) > 1 else "/dev/ttyACM0"
|
||||
secs = float(sys.argv[2]) if len(sys.argv) > 2 else 10
|
||||
s = serial.Serial(port, 115200, timeout=0.3)
|
||||
s.dtr, s.rts = False, True # pulse reset through the USB serial lines
|
||||
time.sleep(0.1)
|
||||
s.rts = False
|
||||
end = time.time() + secs
|
||||
while time.time() < end:
|
||||
data = s.read(4096)
|
||||
if data:
|
||||
sys.stdout.write(data.decode(errors="replace"))
|
||||
sys.stdout.flush()
|
||||
Executable
+152
@@ -0,0 +1,152 @@
|
||||
#!/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()
|
||||
Reference in new issue
Block a user