From 899d4f24180ba09703e21c4a08aca32ff751c1dd Mon Sep 17 00:00:00 2001 From: jimmy Date: Tue, 27 Oct 2026 22:30:26 +1300 Subject: [PATCH] build(v2): root Makefile for build, flash and monitor make build / flash / monitor / flash-monitor / log / size / menuconfig / erase / clean / test run ESP-IDF in Docker and handle rootless ownership. Adds the helper scripts behind log and test, and a --settle option for usb_latency.py (an ESP32-C3 driver resets when its port is opened). Co-Authored-By: Claude Sonnet 5.5 --- Makefile | 93 ++++++++++++++++++++++++++++++++++++ v2/tools/run_driver_tests.py | 18 +++++++ v2/tools/serial_log.py | 19 ++++++++ v2/tools/usb_latency.py | 5 +- 4 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 Makefile create mode 100644 v2/tools/run_driver_tests.py create mode 100644 v2/tools/serial_log.py diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..1bb7b50 --- /dev/null +++ b/Makefile @@ -0,0 +1,93 @@ +# Build, flash and monitor the v2 ESP32-S3 controller (ESP-IDF in Docker). +# +# make list the targets +# make build minify the web UI, then build the firmware +# make flash build if needed and flash the S3 +# make monitor serial console (Ctrl-] to quit) +# make flash-monitor +# +# Override on the command line, e.g. make flash PORT=/dev/ttyACM1 + +PORT ?= /dev/ttyACM0 +IDF_IMAGE ?= espressif/idf:v5.5.5 +SECS ?= 10 +V2 := v2 + +DOCKER_RUN = docker run --rm -v "$(CURDIR)/$(V2)":/project -w /project +DEVICE = --device=$(PORT) +# Interactive terminal only when there is one (monitor needs it, CI does not have it) +TTY := $(shell [ -t 0 ] && echo -it) + +# Rootless Docker maps container root to you, so files must end up owned by uid 0 inside; with a +# normal daemon they must be owned by you. +OWNER := $(shell docker info --format '{{.SecurityOptions}}' 2>/dev/null | grep -q rootless && echo 0:0 || echo $$(id -u):$$(id -g)) +FIX_OWNER = chown -R $(OWNER) /project + +.PHONY: help web build flash monitor flash-monitor log size menuconfig clean fullclean erase test test-driver test-envelope + +help: + @echo "v2 controller (ESP32-S3):" + @echo " make build minify + gzip the web UI, then build the firmware" + @echo " make flash flash firmware and web UI to PORT ($(PORT))" + @echo " make monitor serial console on PORT (Ctrl-] to quit)" + @echo " make flash-monitor flash, then open the console" + @echo " make log [SECS=10] print the console for SECS seconds and exit (no terminal needed)" + @echo " make web only rebuild the web UI (needs node/npx)" + @echo " make size memory use of the last build" + @echo " make menuconfig change the ESP-NOW channel, marker pin, W5500 pins, ..." + @echo " make erase erase the whole flash (loses the stored data)" + @echo " make clean remove the build directory (keeps sdkconfig)" + @echo " make fullclean also remove sdkconfig and the web UI output" + @echo " make test driver unit tests + C/Python envelope cross-check" + @echo "variables: PORT=$(PORT) IDF_IMAGE=$(IDF_IMAGE)" + +# --- web UI --------------------------------------------------------------- +web: + cd $(V2) && tools/build_web.sh + +# --- firmware ------------------------------------------------------------- +build: web + $(DOCKER_RUN) $(IDF_IMAGE) bash -c 'idf.py build; rc=$$?; $(FIX_OWNER); exit $$rc' + +flash: build + $(DOCKER_RUN) $(DEVICE) $(IDF_IMAGE) bash -c 'idf.py -p $(PORT) flash; rc=$$?; $(FIX_OWNER); exit $$rc' + +monitor: + $(DOCKER_RUN) $(TTY) $(DEVICE) $(IDF_IMAGE) idf.py -p $(PORT) monitor + +flash-monitor: flash monitor + +# Non-interactive: reset the board and print what it says for SECS seconds +log: + python3 $(V2)/tools/serial_log.py $(PORT) $(SECS) + +size: + $(DOCKER_RUN) $(IDF_IMAGE) bash -c 'idf.py size; rc=$$?; $(FIX_OWNER); exit $$rc' + +menuconfig: + $(DOCKER_RUN) -it $(IDF_IMAGE) bash -c 'idf.py menuconfig; rc=$$?; $(FIX_OWNER); exit $$rc' + +erase: + $(DOCKER_RUN) $(DEVICE) $(IDF_IMAGE) idf.py -p $(PORT) erase-flash + +clean: + rm -rf $(V2)/build + +fullclean: clean + rm -rf $(V2)/sdkconfig $(V2)/sdkconfig.old $(V2)/www_dist + +# --- tests ---------------------------------------------------------------- +test: test-driver test-envelope + +# Host-side unit tests for the driver's link layer and beat sync (pure Python) +test-driver: + python3 $(V2)/tools/run_driver_tests.py + +# The C envelope packer must produce the same bytes as src/util/binary_envelope.py +test-envelope: + @tmp=$$(mktemp -d); \ + (cd $(V2)/test && python3 env_check.py) > $$tmp/py.txt; \ + docker run --rm -v "$(CURDIR)/$(V2)":/project -w /project/test $(IDF_IMAGE) bash -c \ + 'gcc -Wall -I/opt/esp/idf/components/json/cJSON env_host.c ../main/envelope.c /opt/esp/idf/components/json/cJSON/cJSON.c -o /tmp/t -lm && /tmp/t' 2>&1 | tail -2 > $$tmp/c.txt; \ + if diff -q $$tmp/py.txt $$tmp/c.txt >/dev/null; then echo "envelope: C and Python agree"; rm -rf $$tmp; \ + else echo "envelope: MISMATCH"; diff $$tmp/py.txt $$tmp/c.txt; rm -rf $$tmp; exit 1; fi diff --git a/v2/tools/run_driver_tests.py b/v2/tools/run_driver_tests.py new file mode 100644 index 0000000..7cc424f --- /dev/null +++ b/v2/tools/run_driver_tests.py @@ -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") diff --git a/v2/tools/serial_log.py b/v2/tools/serial_log.py new file mode 100644 index 0000000..7fe883b --- /dev/null +++ b/v2/tools/serial_log.py @@ -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() diff --git a/v2/tools/usb_latency.py b/v2/tools/usb_latency.py index 91da81c..ba61d64 100755 --- a/v2/tools/usb_latency.py +++ b/v2/tools/usb_latency.py @@ -105,12 +105,15 @@ def main(): 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(0.5) + 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")