# Build, flash and monitor the ESP32-S3 controller (ESP-IDF in Docker). # # make build, flash, then monitor (same as: make all) # make help list the targets # make build minify the web UI, then build the firmware # make flash flash the last build to the S3 (does not build) # 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 DOCKER_RUN = docker run --rm -v "$(CURDIR)":/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: all help web build flash ota monitor flash-monitor log size menuconfig clean fullclean erase test test-driver test-envelope test-api test-browser sim-build sim sim-web test-sim # Default target: build, flash, then open the console (run in order, so not with make -j) all: build flash monitor help: @echo "LED controller (ESP32-S3):" @echo " make [all] build, flash, then open the console" @echo " make build minify + gzip the web UI, then build the firmware" @echo " make flash flash the last build (firmware and web UI) to PORT ($(PORT)); does not build" @echo " make ota [HOST=ip] build, then upload the firmware (web UI included) over Ethernet (no USB);" @echo " HOST defaults to led-controller.local" @echo " make monitor serial console on PORT (Ctrl-] to quit)" @echo " make flash-monitor flash the last build, 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 " make test-api HOST=ip HTTP API tests against a running controller (data restored afterwards)" @echo " make test-browser HOST=ip Selenium UI tests against a running controller (needs selenium + chromedriver)" @echo "Simulated rig (no hardware): the controller built for linux + led-simulator's 16 drivers over a UDP bridge" @echo " make sim-build build the controller for the host (sim-controller/build/led_controller_sim.elf)" @echo " make sim build, then run the headless rig and the controller (http://localhost:8080/)" @echo " make sim-web build, then run the browser rig (http://localhost:8765/) and the controller" @echo " make test-sim rig tests (groups, field patterns, sequences) + the API tests against make sim" @echo "variables: PORT=$(PORT) IDF_IMAGE=$(IDF_IMAGE)" # --- web UI --------------------------------------------------------------- web: tools/build_web.sh # --- firmware ------------------------------------------------------------- # The build time in the image comes from esp_app_desc.c, which nothing else recompiles (a web-only # change just relinks), so drop its object and every build gets the current time. APP_DESC_OBJ = build/esp-idf/esp_app_format/CMakeFiles/__idf_esp_app_format.dir/esp_app_desc.c.obj build: web $(DOCKER_RUN) $(IDF_IMAGE) bash -c 'rm -f $(APP_DESC_OBJ); idf.py build; rc=$$?; $(FIX_OWNER); exit $$rc' flash: $(DOCKER_RUN) $(DEVICE) $(IDF_IMAGE) bash -c 'idf.py -p $(PORT) flash; rc=$$?; $(FIX_OWNER); exit $$rc' ota: HOST ?= led-controller.local ota: build python3 tools/ota.py $(HOST) 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 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 build fullclean: clean rm -rf sdkconfig sdkconfig.old 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 tools/run_driver_tests.py # HTTP API tests (ported from v1) against a running controller; v1 features v2 lacks are xfail test-api: @test -n "$(HOST)" || { echo "usage: make test-api HOST="; exit 1; } python3 -m pytest test/api -q --host $(HOST) # Selenium UI tests (ported from v1); they change the controller's data and do not restore it test-browser: @test -n "$(HOST)" || { echo "usage: make test-browser HOST="; exit 1; } LED_CONTROLLER_RUN_BROWSER_TESTS=1 LED_HOST=$(HOST) python3 -m pytest test/browser -q # The C envelope packer must produce the same bytes as test/binary_envelope.py test-envelope: @tmp=$$(mktemp -d); \ (cd test && python3 env_check.py) > $$tmp/py.txt; \ docker run --rm -v "$(CURDIR)":/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 -4 | head -3 > $$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 # --- simulated rig -------------------------------------------------------- # The firmware built for ESP-IDF's linux target runs on this computer; its ESP-NOW frames go over UDP to # led-simulator (bridge_sim.py headless, or server.py in the browser), whose drivers run led-driver/src. SIM_DB ?= $(CURDIR)/sim-controller/data SIM_RUN = mkdir -p $(SIM_DB) && LED_SIM_DB=$(SIM_DB) LED_SIM_BRIDGE=127.0.0.1:8766 sim-controller/build/led_controller_sim.elf sim-build: web $(DOCKER_RUN) $(IDF_IMAGE) bash -c 'cd sim-controller && idf.py build; rc=$$?; $(FIX_OWNER); exit $$rc' sim: sim-build @trap 'kill 0' INT TERM EXIT; python3 led-simulator/bridge_sim.py & $(SIM_RUN) sim-web: sim-build @trap 'kill 0' INT TERM EXIT; python3 led-simulator/server.py & $(SIM_RUN) test-sim: python3 -m pytest test/api -q --host localhost:8080