# 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:v6.1 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-wasm sim-pack 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-wasm build the browser drivers: led-driver (C++) to WebAssembly, with Emscripten in Docker" @echo " make sim-web build all of it and run one program: the controller on http://localhost:8080/ with the" @echo " simulated rig (rooms, every bar a driver) on /sim/ and the pattern gallery on /sim/gallery" @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 and serves the simulated rig itself at # /sim/ (sim-controller/components/sim/sim_rig.c): every bar is led-driver's C++ firmware built to WebAssembly # (sim-driver/, `make sim-wasm`), laid out in a room, and gets the controller's ESP-NOW frames over the page's # WebSocket (the "browser" bridge). bridge_sim.py is the older headless rig over UDP, whose drivers ran the # MicroPython led-driver/src (since removed). 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 # The rig's page and drivers for the host builds to embed (www_dist/sim.pack; empty without `make sim-wasm`) sim-pack: tools/build_sim_web.sh sim-build: web sim-pack $(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) # Emscripten in Docker (sim-driver/build.sh): led_driver (one strip) and led_fx (the pattern gallery) EMSDK_IMAGE ?= emscripten/emsdk:4.0.12 sim-wasm: EMSDK_IMAGE=$(EMSDK_IMAGE) sim-driver/build.sh sim-web: sim-wasm sim-build mkdir -p $(SIM_DB) && LED_SIM_DB=$(SIM_DB) LED_SIM_BRIDGE=browser sim-controller/build/led_controller_sim.elf test-sim: python3 -m pytest test/api -q --host localhost:8080 # --- desktop image (no hardware): the sim controller in Docker, web UI on localhost:8080 ---- # DOCKER_PULL=--pull=false (default) uses the local espressif/idf:v6.1 and debian:trixie images; set DOCKER_PULL= to refresh them DOCKER_PULL ?= --pull=false docker-sim: DOCKER_BUILDKIT=0 docker build $(DOCKER_PULL) -f Dockerfile.sim -t led-controller-sim . docker-sim-run: docker run --rm -p 8080:8080 -v led-sim-data:/data led-controller-sim # --- USB ESP-NOW bridge board (bridge/): ESP-NOW for a computer with no radio ------------------ # Two chips: ESP32-S3 (bridge-*-s3, with the I2S microphone) and ESP32-C3 (bridge-*-c3, no mic). Each has its own # build dir (bridge/build-s3, bridge/build-c3). Flash with BRIDGE=, e.g. make bridge-flash-s3 BRIDGE=/dev/ttyACM2. # BRIDGE=/dev/ttyACM1 is the default for `make rig`, which runs the sim-controller build against it (no simulator). BRIDGE ?= /dev/ttyACM1 define BRIDGE_BUILD $(DOCKER_RUN) $(IDF_IMAGE) bash -c 'cd bridge; if [ ! -f build-$(1)/CMakeCache.txt ]; then idf.py -B build-$(1) -D SDKCONFIG=build-$(1)/sdkconfig set-target $(2); fi; idf.py -B build-$(1) -D SDKCONFIG=build-$(1)/sdkconfig build; rc=$$?; $(FIX_OWNER); exit $$rc' endef bridge-build-s3: $(call BRIDGE_BUILD,s3,esp32s3) bridge-build-c3: $(call BRIDGE_BUILD,c3,esp32c3) bridge-build: bridge-build-s3 bridge-build-c3 bridge-flash-s3: bridge-build-s3 $(DOCKER_RUN) --device=$(BRIDGE) $(IDF_IMAGE) bash -c 'cd bridge && idf.py -B build-s3 -D SDKCONFIG=build-s3/sdkconfig -p $(BRIDGE) flash; rc=$$?; $(FIX_OWNER); exit $$rc' bridge-flash-c3: bridge-build-c3 $(DOCKER_RUN) --device=$(BRIDGE) $(IDF_IMAGE) bash -c 'cd bridge && idf.py -B build-c3 -D SDKCONFIG=build-c3/sdkconfig -p $(BRIDGE) flash; rc=$$?; $(FIX_OWNER); exit $$rc' rig: sim-build @test -n "$(BRIDGE)" || { echo "usage: make rig BRIDGE=/dev/ttyACM1"; exit 1; } mkdir -p $(SIM_DB) && LED_SIM_DB=$(SIM_DB) LED_SIM_BRIDGE=$(BRIDGE) sim-controller/build/led_controller_sim.elf # --- desktop: led-controller as a program, no ESP-IDF (desktop/); make deb for a headless install --- DESKTOP_BUILD ?= build-desktop DESKTOP_DATA ?= $(CURDIR)/desktop-data DESKTOP_PORT ?= 8080 # Rebuilt when any web source changes WEB_SRC := $(wildcard web/static/* web/templates/* web/*.html) tools/build_web.sh www_dist/www.pack: $(WEB_SRC) tools/build_web.sh desktop: www_dist/www.pack sim-pack cmake -S desktop -B $(DESKTOP_BUILD) -DCMAKE_BUILD_TYPE=Release cmake --build $(DESKTOP_BUILD) -j$(shell nproc) # The web UI is on http://localhost:$(DESKTOP_PORT)/; the bridges are set there (Settings > Network > Bridges), not here desktop-run: desktop $(DESKTOP_BUILD)/led-controller --db $(DESKTOP_DATA) --port $(DESKTOP_PORT) test-desktop: desktop mkdir -p $(DESKTOP_DATA)-test $(DESKTOP_BUILD)/led-controller --db $(DESKTOP_DATA)-test --port 8081 > $(DESKTOP_DATA)-test/server.log 2>&1 & pid=$$!; sleep 2; python3 -m pytest test/api -q --host localhost:8081 --ignore=test/api/test_rig_sim.py; rc=$$?; kill $$pid 2>/dev/null; wait $$pid 2>/dev/null; exit $$rc # led-cli (led-tool/) and the driver firmware image (led-driver/, built by its ESP-IDF v6.1 image) go into the .deb LED_CLI_BIN := led-tool/dist/led-cli LED_DRIVER_BIN := led-driver/build-v61/led_driver.bin LED_TOOL_SRC := $(wildcard led-tool/*.py led-tool/lib/*.py) led-cli: $(LED_CLI_BIN) $(LED_CLI_BIN): $(LED_TOOL_SRC) led-tool/led-cli.spec cd led-tool && pipenv run pyinstaller --clean --onefile --name led-cli --paths lib cli.py deb: www_dist/www.pack $(LED_CLI_BIN) @test -f $(LED_DRIVER_BIN) || { echo "missing $(LED_DRIVER_BIN): build led-driver with the espressif/idf:v6.1 image first"; exit 1; } cmake -S desktop -B $(DESKTOP_BUILD) -DCMAKE_BUILD_TYPE=Release -DLED_BUNDLE_TOOLS=ON cmake --build $(DESKTOP_BUILD) -j$(shell nproc) cd $(DESKTOP_BUILD) && cpack -G DEB .PHONY: desktop desktop-run test-desktop deb led-cli bridge-build bridge-build-s3 bridge-build-c3 bridge-flash-s3 bridge-flash-c3 rig