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.
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.pySnapshots 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:45scripts/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.
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 # viewerSTEP/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.
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.
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 stdoutscripts/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/ 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 firmwareThe binary lands in
firmware/.pio/build/esp32dev/firmware.bin.
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