Development

The models are plain Python scripts for cadgen (build123d). Each part script declares its outputs (STEP and 3MF); all dimensions live in src/lib/params.py.

Environment

cadgen runs through uv. On NixOS its wheel needs native libraries, which scripts/env.sh provides; sourcing it also sets PYTHONPATH=src and the CADGEN command array.

source scripts/env.sh
"${CADGEN[@]}" python src/deck.py

Snapshots render in a headless browser that needs the Wayland variables unset:

env -u WAYLAND_DISPLAY -u DISPLAY -u XDG_SESSION_TYPE \
  uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.26 \
  cadgen step snapshot STEP/deck.step scratch/deck.png --camera=60:45

Build and check

scripts/build.sh regenerates every part, the assembly and the print plates (STEP/, 3MF/, 3MF/plates/), then runs scripts/mesh_repair.py on every 3MF: the tessellator occasionally leaves T-junctions (an edge split on one face only) that slicers report as non-manifold edges, and the script splits those triangles so each mesh is closed. The interference check then confirms that nothing collides over the pan/tilt range:

scripts/build.sh
(source scripts/env.sh && "${CADGEN[@]}" python checks/interference.py)

STEP/assembly.step carries the pan and tilt joints, so the CAD viewer can pose the head.

Interactive 3D viewer

scripts/view.sh starts the cadgen CAD viewer in the background (or reuses a running one) and prints browser links. Without arguments it lists every group; one or more group names select a subset; any STEP or 3MF path opens that file. The step images in the wiring and assembly guides link to their scenes, so a render opens in the viewer when clicked.

scripts/view.sh                   # all groups
scripts/view.sh wiring            # wiring diagrams (2D) and scenes (3D)
scripts/view.sh assembly          # mechanical assembly scenes (m01..m11)
scripts/view.sh STEP/deck.step    # a specific file
scripts/view.sh stop              # viewer

STEP/assembly.step carries the kinematics declared in src/assembly.py: the pan joint (−180° … 180°) coupled to the servo gear at −½, and the tilt joint (−60° … +60°), plus two saved poses. The viewer shows them as sliders. It refreshes when a file is rebuilt, so a link stays valid across builds.

Slicing

scripts/slice.sh [tank|deck|head|turntable|coupler ...] slices the named plates, or all five without an argument, with OrcaSlicer and the presets in print/presets/. Output goes to gcode/plate_<name>.gcode.3mf. The per-plate overrides are listed in Printing. OrcaSlicer’s command line leaves the project’s different_settings_to_system list empty, so the GUI would reopen the file with the plain system preset; scripts/mark_overrides.py writes the preset’s overrides (supports, brim, bed type) and the plate’s into that list, each in the slot of the preset that holds it (process, filament or printer). A setting added to process.json must also be in that key list in slice.sh; a plate’s own arguments are added to it automatically.

A plate with a src/plates/<plate>_support.py model gets a support enforcer: slice.sh runs scripts/add_enforcer.py, which joins the plate and the enforcer mesh into one OrcaSlicer project 3MF (the enforcer as a second volume of the part, the presets embedded as project settings) before slicing. With a manual support type, the slicer supports only what lies inside the enforcer, and the enforcer stays in the sliced file, so the GUI shows it and re-slices the same way.

Wiring and assembly guides

The harness is a model too: src/guide/harness.py defines every wire (endpoints, route, colour, gauge), the board jumpers, rails, bridges and landing holes; a wire with cut set is drawn as two pieces with a part spliced between them (W14 around the relay driver, whose position is DRIVER). The guide scenes src/guide/g1_*.py … g7_*.py stack the deck parts stage by stage, src/guide/board_map.py draws the perfboard hole maps and prints the wire cut list, src/guide/pinouts.py draws the glossary’s module pinouts, and src/guide/relay_driver.py draws the relay driver schematic with schemdraw (scripts/guide.sh runs it next to cadgen with --with schemdraw --with matplotlib). The assembly scenes src/guide/m01_*.py … m11_*.py come from src/guide/mech.py: each stage greys the parts of earlier steps, and explode() moves the step’s parts out along their insertion direction and adds an arrow back to their place. The glossary figures share one scene, src/guide/glossary.py: each figure sits at its own spot along X, paints the features of one part in colour (cut out of the part by intersecting it with simple regions) and carries its own camera in SCENES.

scripts/guide.sh builds the scenes and renders them into docs/img/; GUIDE_SKIP_BUILD=1 re-renders the images only:

scripts/guide.sh
(source scripts/env.sh && "${CADGEN[@]}" python src/guide/board_map.py)  # cut list on stdout

scripts/guide.sh also redraws the README’s coverage diagram (docs/img/coverage.png) with scripts/coverage.py. The script uses the model’s parameters and two unmeasured ranges, SENSE_R and REACH, which are set at its top.

A camera object frames on its target only inside a snapshot job with output.tightFrame: false; orthographicHalfHeight is then half the image height in millimetres. scripts/guide.sh writes such a job.

Firmware

firmware/ is a PlatformIO project for the ESP32 DevKitC (Arduino framework, ESP32Servo; the IMU is read over I²C with Wire). include/config.h holds the pins, geometry and tuning constants; src/ splits the program by concern:

File Concern
main.cpp setup() and loop()
actuators.cpp pan and tilt servos, pump relay with its cooldown and safety cut-off
sensors.cpp flame sensor sampling, ambient calibration, fire direction
imu.cpp MPU-6050 tilt filter, stored level, levelled aiming; re-probes a missing IMU every 10 s
control.cpp automatic mode: detection, aiming, sweep and pump decisions
remote.cpp WiFi, HTTP routes, serial commands, status JSON

The WiFi credentials go in include/secrets.h, which git ignores; without it the build warns and uses the placeholders in include/secrets.example.h. The dev shell provides pio.

The following commands create the credentials file, build, flash over USB and open the serial monitor (115200 baud). The ESP32 goes on USB only out of the perfboard: on the board, its USB 5 V back-feeds the buck through the 5V rail.

cp firmware/include/secrets.example.h firmware/include/secrets.h  # fill in WIFI_SSID and WIFI_PASS
nix develop path:. --command pio run -d firmware
nix develop path:. --command pio run -d firmware -t upload
nix develop path:. --command pio device monitor -d firmware

The binary lands in firmware/.pio/build/esp32dev/firmware.bin.

Documentation

The docs compile with tern into docs-html/. Two installs of the pandoc template run side by side: pandoc/all compiles the top-level README.md, pandoc/readme compiles docs/ and copies docs/img. Both are configured in .tern/config.toml.

nix develop path:. --command tern