DEV Community: Matthew Armstrong

Skipper Flipper

Matthew Armstrong — Fri, 30 Oct 2026 08:19:54 +0000

An experimental ESP32 pseudo Klipper port. (Repository and package name: esp-printhost.)

GPL-3.0 · Linux (Mint / Ubuntu) · C++17 core + Python tools · Project page

Licensed under the GNU General Public License v3.0, see LICENSE. No warranty and no liability: this is provided as is. You use it at your own risk, on your own hardware, and the author is not responsible for damage to boards, printers or anything else.

What this is

An idea for reviving old, donated 3D printers: a cheap ESP32-S3 becomes the "brain" (WiFi, web UI, text config, motion planning) and the printer's original board becomes a simple slave running a modified Klipper MCU firmware. The full plan is in docs/DESIGN.md.

Target hardware: ESP32-S3 only for the host ("master"). Status (29 October 2026): mostly working, needs tuning and proper testing. On real hardware (docs/HARDWARE_LOG.md), installed in a WEEDO Tina 2 with a BTT SKR Pico running plain Klipper v0.13.0:

the WiFi pages, console and printer.cfg editor; firmware updates over WiFi;
the Klipper link, clock sync, board configuration and recovery from board power cycles;
temperatures, heating, PID tuning and Klipper's heater safety checks;
the motor test, TMC2209 set-up, stallGuard and full homing of X, Y and Z (2026-10-27);
a whole print file, run end to end (2026-10-27): in mid-air, because the Tina 2's flexible Z gave no reliable stop to set a Z offset from;
the micro SD card, the little OLED, touch buttons through the case, the hotend fan;
the print benchmark (2026-10-29): 12 layers of a print path (9,617 lines, about a million steps) through the whole motion pipeline and the real board, drivers off, in 121.8 s, with the ESP32's printer task busy about 44 % of one core, of which about 14 % is real work and the rest mostly waiting for the board's acknowledgements (docs/BENCHMARK.md);
integer motion maths (INT32/64 test build, 2026-10-29): input shaping with pressure advance costs 10 % of one core at 100 mm/s instead of 19 %; the shaping work itself is about 3.7 times faster.

Not yet: a real printed part; input shaping, pressure advance, bed mesh and the other tuning features on a moving printer; the part-cooling fan and the third fan output (possibly a broken wire). Next test bench: a QIDI X-Smart 3 (CoreXY) with an SKR Pico; the Tina 2 is retired as the bench (no sharp Z stop, and its tiny Y motor overheats). The whole story, including every mistake: A Frankenstein Experience (PDF).

New features by date, and whether each has been on hardware, are in CHANGELOG.md.

Part	State
Klipper wire protocol (CRC16, VLQ ints, framing, resync, data dictionary)	Unit-tested; works on hardware (ESP32-S3 to SKR Pico)
ESP32-S3 firmware (`firmware/esp32s3`): WiFi access point, status page, console, `printer.cfg` editor, test bench, printer page, the Klipper host's jobs (heaters, TMC2209, moves, homing, printing from flash). Shipped ready to flash	On hardware: link, heating, PID, motor test, TMC2209, stallGuard, full homing (2026-10-27), a print file run in mid-air (2026-10-27), WiFi updates, the print and motion benchmarks (2026-10-29). Not yet: a real printed part
`skr-pico-uart` printer-board firmware (plain Klipper v0.13.0, serial on UART0; the ESP32-S3 firmware is the only bespoke part)	Works on hardware: link, heater, thermistor, steppers, TMC UART, DIAG pins (with the 2026-10-10 build, which also held the since-removed, never-used segment queue; why it went)
Motion planner + G-code engine (lookahead, junction deviation, trapezoids, pressure advance, G-code state)	On hardware for homing, a print file in mid-air and the benchmarks; checked in simulation for exact positions, speed and acceleration limits. Never yet used for a real part
Other board presets (generic RP2040, Creality 4.2.x, RAMPS mega2560, Ender-3 1.1.x, USB SKR Pico)	Compile only; never run on hardware
Flasher app (`flasher.py`): Slave tab (printer board) and Master tab (ESP32-S3)	ESP32-S3 flashing used on hardware on Linux Mint. Other paths (SD card, avrdude, Windows/macOS) tested with mocks only
Firmware build tool (CLI + Slave tab "My own build")	Works on Linux (sandbox and the author's Linux Mint laptop); Windows needs WSL
`mcu_probe`, `fake_mcu.py`, one-command setup, Tools window	Working on Linux Mint. Probe tried on an SKR Pico over USB
Real printing	A print file ran end to end on the Tina 2 (2026-10-27) but in mid-air (Z offset not found); upload, print from flash or SD card, pause / resume / cancel are simulated. No real part printed yet
Micro SD card (`firmware/esp32s3/main/sdcard.c`)	Works on hardware (2026-10-19: mount, file list, upload; printing from it not yet tried): SPI card for big G-code files, file list / print / delete on the Printer page, `SDCARD_PRINT_FILE FILENAME=`, M20/M23/M24 (the command side is unit-tested). See docs/SD_CARD.md
Buttons on the case (`firmware/esp32s3/main/panel.cpp`, `host/src/panel.cpp`)	Touch works on hardware (2026-10-26: Preheat and Home from staple pads melted into the Tina 2's case); up to four touch pads (bolts on wires) or switches: Preheat, Home and E-stop (both on a 1 s hold), Unload, and more. CAPTAIN and SKIPPER. See docs/BUTTONS.md
Tuning (`host/src/shaping.cpp`, `resonance.cpp`, `bedmesh.cpp`, `machine_pro.cpp`; Tune page)	Built and PC-tested; the shaping and pressure-advance maths timed on the ESP32 (2026-10-29), not yet used on a moving printer (2026-10-24): input shaping, pressure advance, accelerometer search and shaper calibration (matches Klipper's), bed mesh, screw tilt, arcs, G10/G11, exclude object, tuning tower. USB accelerometer: compile-only. CAPTAIN and SKIPPER only. See docs/TUNING.md
Little OLED display (`firmware/esp32s3/main/oled.cpp`, `components/ktft_oled`)	Works on hardware (2026-10-26: temperatures and the shutdown screen on a 0.96" OLED in the Tina 2); built 2026-10-23: SSD1306 / SSD1315 / SH1106, 128x64 or 128x32, on GPIO8/9: temperatures, progress bar, HEATING / HOMING / EXTRUDING / LOADING, "no board" with the WiFi name and password. See docs/OLED.md
Three builds by board memory: DECKHAND / CAPTAIN / SKIPPER (docs/TIERS.md), Flasher "Flash for my board"	CAPTAIN runs on hardware (2026-10-20: picked by the Flasher, 2 MB PSRAM found and used); WiFi firmware updates work (2026-10-20); the important-events log works (2026-10-28); not yet tried there: bigger look-ahead with PSRAM, slicer upload (OctoPrint-style), home WiFi, thumbnails, print history, event log, printer.cfg backups, crash reports
Print benchmark, motion benchmark, INT32/64 test build (docs/BENCHMARK.md)	On hardware (2026-10-28/29): both benchmarks run to the end on the Tina 2 with the SKR Pico and the drivers off; results in the important-events log. The integer build has not moved motors yet
Fans	Hotend fan confirmed on hardware; part-cooling fan and the third fan output not yet (possibly a broken wire, will update when tested)

Total checks: 1,825 C++ unit checks (run twice: with double and with integer motion maths), the OLED layout tests and 192 Python tests (including power-cycle, stallGuard and printing runs against a simulated board), all passing in the sandbox. Passing tests mean the maths and bookkeeping are right, not that a printer will behave.

Screenshots

The GUI building the tools and running the unit tests:

The GUI running the probe against the built-in fake MCU (simulated, no hardware):

Both screenshots use the simulated board, not real hardware.

Flash a board (Linux, macOS, Windows)

python3 flasher.py          (Windows: double-click Flasher.bat; macOS: Flasher.command)

You need Python 3.8+ with Tk (Linux: sudo apt install python3-tk; on Windows and macOS the installer from python.org includes Tk). No toolchain is needed: firmware for every board preset (five boards, plus a serial variant of the SKR Pico) ships in firmware/prebuilt/. Pick the Slave tab, choose your board, press Flash... and confirm. RP2040 boards: hold BOOTSEL while plugging in USB. STM32 boards such as the Creality 4.2.x: put the SD card in this computer, Browse to it, flash, then move the card to the printer and power-cycle it. AVR boards need avrdude installed. The Master tab flashes an ESP32-S3 with esptool (Install esptool, then Use shipped firmware, pick the port, Flash). The port box fills itself with the ESP32-S3's port when it can tell which one it is (otherwise pick it). The shipped image starts a WiFi network SkipperFlipper-XXXX (WPA2, default password skipperflipper, change it before real use) with a page at http://192.168.4.1/, a live log at /console and printer.cfg at /config; it talks Klipper to the printer board over UART (identify, clock sync, printer.cfg, heaters, TMC2209 drivers, motor tests at /test, homing and running a print file from the Printer page: all on hardware with the SKR Pico; a real printed part not yet). Logs appear on the chip's native USB port. ESP32-S3 only: other ESP32 chips (original, S2, C3) are not supported, and esptool refuses to write if it finds a different chip. You can also flash your own .bin. To connect the ESP32-S3 to an SKR Pico with four jumper wires, see docs/WIRING_SKR_PICO.md.

Only the skr-pico-uart firmware (SKR Pico) has run on a board, where it has done everything above; the other presets have never been flashed. Read docs/FIRMWARE.md first, and do not flash a printer you cannot recover.

Quick start (Linux Mint / Ubuntu / Debian)

git clone https://github.com/The-Dorkknight/esp-printhost
cd esp-printhost
sudo python3 printhost.py

That one command installs what is missing (build tools, cmake, zlib, python3-tk, acl), gives you access to USB serial ports without logging out, stops ModemManager and brltty from grabbing printer boards, builds mcu_probe, runs the tests, and opens the GUI as your normal user. It is safe to re-run. HOW_IT_WORKS.md lists exactly what it changes on your system.

Options: --check (report only, change nothing), --no-gui, --clean, --yes, --version.

If anything fails it prints the path of a log file in ~/esp-printhost-logs/. Attach that when you open an issue.

macOS: the C++ library and tests build (python3 host/tools/build.py), but mcu_probe is Linux-only (it uses Linux's termios2 for 250000 baud) and the one-command setup is Linux-only.

Using the GUI

Build tools compiles everything and runs the unit tests. Output is colour-coded per tool.
Fake MCU: Start runs a pretend Klipper board (no hardware). Its port appears in the Port box.
Run probe connects, reads the board's pin list into the Blink pin dropdown, and prints uptime and state. Tick Blink pin and pick a pin to also toggle it 10 times.
The output box is selectable (Ctrl+C, right-click, Copy all, Save as...). Everything is also logged to ~/esp-printhost-logs/.

Try it without hardware

python3 host/tools/fake_mcu.py            # prints /dev/pts/N
./host/build/mcu_probe /dev/pts/N 250000 --pins --blink PA5

Try it on a real board

You need a board running stock Klipper MCU firmware (the Flasher ships plain Klipper v0.13.0 builds in firmware/prebuilt/, or build your own with the Firmware tab). Stop Klipper or anything else using the port, then:

./host/build/mcu_probe /dev/serial/by-id/<your-board> 250000 --pins --blink <pin>

--pins lists the pin names the board accepts. The probe validates your pin name before touching the board, and if the board is already configured it resets it first (the USB device re-appears after about two seconds). Do not run it on a board that is in the middle of a print.

Tested so far: BTT SKR Pico (RP2040, Klipper v0.10.0-181). The probe identified it, read 31 pin names, reset it, configured gpio24 and sent 10 toggles with 0 CRC errors.

Known limitations

It has not printed a real part yet. Homing and a whole print file have run on the Tina 2, but in mid-air: first layer, Z offset, extrusion and cooling are untested in practice.
Heaters: stay with the printer. Klipper's heater safety is ported and has shut the board down correctly on hardware ("ADC out of range"), but this is experimental firmware: keep a hand near the power switch and never leave it running unattended.
The tuning features have not moved a printer: input shaping, pressure advance, accelerometer calibration, bed mesh, screw tilt, arcs, firmware retraction, exclude object and tuning tower are built and PC-tested; the shaping maths has been timed on the ESP32, nothing more.
The INT32/64 test build has passed the PC tests (within one step of the double maths everywhere) and both benchmarks on the ESP32, but has not driven motors with its integer shaper yet.
Sending waits for the board: about 30 % of one core in the print benchmark is the ESP32 waiting for the SKR Pico's acknowledgements, where Klipper keeps sending. Fine at the Tina 2's speeds; it is the next speed work.
Only the SKR Pico has run. The other board presets are compile-only, and their bootloader details are assumptions. Small 8-bit boards give Klipper a much smaller move queue than the SKR Pico's 1,024 commands; this host has not been tried with one.
Flash is nearly full on DECKHAND (about 6 KB free) and CAPTAIN (about 14 KB); new features may need something trimmed.
The part-cooling fan and the third fan output are not confirmed (possibly a broken wire). The cause of one early SKR Pico lock-up after a shutdown (2026-10-13) is still unknown.
mcu_probe is Linux-only.
The GitHub workflows in .github/workflows/ have not been checked for this release.
Presets for boards with clone chips (some Creality 4.2.x) are flagged unverified; check your chip.
Design documents describe intent, not finished work.

Project layout

printhost.py          one-command setup + launcher
flasher.py            the Flasher window (also Flasher.bat / Flasher.command)
HOW_IT_WORKS.md       what it reads, changes and never does
docs/                 DESIGN, PROTOCOL, ENGINE, FIRMWARE, TUNING, TASKS, project page
firmware/esp32s3/       ESP32-S3 firmware (ESP-IDF project) + build.sh
firmware/prebuilt-esp32s3/  shipped ESP32-S3 images (DECKHAND / CAPTAIN / SKIPPER; test-int32/ for the INT32/64 test build)
firmware/boards/      board presets (.config + .json)
firmware/prebuilt/    shipped plain-Klipper firmware per board (+ pin tables); refresh with skipper_fw.py bundle
host/                 portable C++17 core (the same code runs on the PC and, as an ESP-IDF component, on the ESP32-S3)
  include/ph/         wire, msgproto, json_mini, config_ini, gcode, motion, planner, engine
  src/  test/         implementation + 1,825 unit checks
  tools/              build.py, skipper_fw.py, printhost_gui.py (+ fw_panel, skipper_theme),
                      mcu_probe.cpp, fake_mcu.py

Roadmap

See docs/TASKS.md. Next, in order:

Make the integer input shaper the standard in every build (keeping the double planner), now that it measures about 3.7 times faster on the ESP32.
Send without waiting for each acknowledgement, the way Klipper does, to win back most of the 30 % of a core spent waiting.
Move to the QIDI X-Smart 3 test bench and print a first real part.
Try the tuning features (input shaping, pressure advance, bed mesh) on a moving printer.

The look is a 1928 black-and-white cartoon (visuals only).

Source code: The-Dorkknight/esp-printhost on GitHub

Skipper Flipper

Matthew Armstrong — Thu, 29 Oct 2026 23:30:03 +0000

An experimental ESP32 pseudo Klipper port. (Repository and package name: esp-printhost.)

GPL-3.0 · Linux (Mint / Ubuntu) · C++17 core + Python tools · Project page

What this is

Target hardware: ESP32-S3 only for the host ("master"). Status: mostly working, needs tuning and proper testing. On real hardware (see docs/HARDWARE_LOG.md), installed in a WEEDO Tina 2 with a BTT SKR Pico: the WiFi status page, console and printer.cfg editor; the Klipper link, clock sync, board configuration and recovery from board power cycles; temperatures, heating, PID tuning and Klipper's heater safety checks; the motor test; TMC2209 set-up; stallGuard triggering; the hotend fan; a micro SD card for big G-code files (docs/SD_CARD.md: mounts, lists, uploads). Not yet confirmed: the part-cooling fan and the third fan output (possibly a broken wire; will update when tested). Needs tuning: stallGuard threshold, motor current, speeds, rotation_distance. Only simulated so far: moves, full homing and probing, and printing a file. New (2026-10-20), not yet on hardware: three builds by board memory with a one-click Flasher choice (docs/TIERS.md), slicer uploads, home WiFi and crash reports. New (2026-10-23), not yet on hardware: a cheap I2C OLED shows temperatures, print progress and what the printer is doing (docs/OLED.md). New (2026-10-24), not yet on hardware: Klipper's input shaping and pressure advance, automatic input shaper calibration with an accelerometer it finds by itself, bed mesh with a coloured heightmap, screw tilt, arcs, firmware retraction, exclude object and tuning tower on CAPTAIN and SKIPPER (docs/TUNING.md). New (2026-10-27), not yet on hardware: CoreXY, Z homing on a probe, gear_ratio, a chamber thermistor on the ESP32 (docs/CHAMBER_SENSOR.md) and a QIDI X-Smart 3 test-bench config (docs/configs/qidi-xsmart3-skr-pico.md). New (2026-10-28), not yet on hardware: a print benchmark that times every stage of the motion pipeline with nothing moving, an int32/int64 motion test build for CAPTAIN, and a log of important events (docs/BENCHMARK.md). The whole story, including every mistake: A Frankenstein Experience (PDF).

Part	State
Klipper wire protocol (CRC16, VLQ ints, framing, resync, data dictionary)	Unit-tested; works on hardware (ESP32-S3 to SKR Pico)
ESP32-S3 firmware (`firmware/esp32s3`): WiFi access point, status page, console, `printer.cfg` editor, test bench, printer page, the Klipper host's jobs (heaters, TMC2209, moves, homing, printing from flash). Shipped ready to flash	On hardware (to 2026-10-14): link, heating, PID, motor test, TMC2209, stallGuard trigger. Moves, homing and printing: simulation only
`skr-pico-uart` printer-board firmware (plain Klipper v0.13.0, serial on UART0; the ESP32-S3 firmware is the only bespoke part)	Works on hardware: link, heater, thermistor, steppers, TMC UART, DIAG pins (with the 2026-10-10 build, which also held the since-removed, never-used segment queue; why it went)
Motion planner + G-code engine (lookahead, junction deviation, trapezoids, pressure advance, G-code state)	Working in simulation: output is run through the real core and checked for exact positions, speed and acceleration limits
Other board presets (generic RP2040, Creality 4.2.x, RAMPS mega2560, Ender-3 1.1.x, USB SKR Pico)	Compile only; never run on hardware
Flasher app (`flasher.py`): Slave tab (printer board) and Master tab (ESP32-S3)	ESP32-S3 flashing used on hardware on Linux Mint. Other paths (SD card, avrdude, Windows/macOS) tested with mocks only
Firmware build tool (CLI + Slave tab "My own build")	Works on Linux (sandbox and the author's Linux Mint laptop); Windows needs WSL
`mcu_probe`, `fake_mcu.py`, one-command setup, Tools window	Working on Linux Mint. Probe tried on an SKR Pico over USB
Real printing	Built and simulated only (upload, print from flash, pause / resume / cancel); not yet run on the printer
Micro SD card (`firmware/esp32s3/main/sdcard.c`)	Works on hardware (2026-10-19: mount, file list, upload; printing from it not yet tried): SPI card for big G-code files, file list / print / delete on the Printer page, `SDCARD_PRINT_FILE FILENAME=`, M20/M23/M24 (the command side is unit-tested). See docs/SD_CARD.md
Buttons on the case (`firmware/esp32s3/main/panel.cpp`, `host/src/panel.cpp`)	Touch works on hardware (2026-10-26: Preheat and Home from staple pads melted into the Tina 2's case); up to four touch pads (bolts on wires) or switches: Preheat, Home and E-stop (both on a 1 s hold), Unload, and more. CAPTAIN and SKIPPER. See docs/BUTTONS.md
Tuning (`host/src/shaping.cpp`, `resonance.cpp`, `bedmesh.cpp`, `machine_pro.cpp`; Tune page)	Built, PC-tested and run in QEMU, not yet on a printer (2026-10-24): input shaping, pressure advance, accelerometer search and shaper calibration (matches Klipper's), bed mesh, screw tilt, arcs, G10/G11, exclude object, tuning tower. USB accelerometer: compile-only. CAPTAIN and SKIPPER only. See docs/TUNING.md
Little OLED display (`firmware/esp32s3/main/oled.cpp`, `components/ktft_oled`)	Works on hardware (2026-10-26: temperatures and the shutdown screen on a 0.96" OLED in the Tina 2); built 2026-10-23: SSD1306 / SSD1315 / SH1106, 128x64 or 128x32, on GPIO8/9: temperatures, progress bar, HEATING / HOMING / EXTRUDING / LOADING, "no board" with the WiFi name and password. See docs/OLED.md
Three builds by board memory: DECKHAND / CAPTAIN / SKIPPER (docs/TIERS.md), Flasher "Flash for my board"	CAPTAIN runs on hardware (2026-10-20: picked by the Flasher, 2 MB PSRAM found and used); not yet tried there: WiFi firmware updates, bigger look-ahead with PSRAM, slicer upload (OctoPrint-style), home WiFi, thumbnails, print history, event log, printer.cfg backups, crash reports
Fans	Hotend fan confirmed on hardware; part-cooling fan and the third fan output not yet (possibly a broken wire, will update when tested)

Total checks: 1,825 C++ unit checks (run twice: with double and with integer motion maths), the OLED layout tests and 190 Python tests (including power-cycle, stallGuard and printing runs against a simulated board), all passing in the sandbox. Passing tests mean the maths and bookkeeping are right, not that a printer will behave.

Screenshots

The GUI building the tools and running the unit tests:

The GUI running the probe against the built-in fake MCU (simulated, no hardware):

Both screenshots use the simulated board, not real hardware.

Flash a board (Linux, macOS, Windows)

python3 flasher.py          (Windows: double-click Flasher.bat; macOS: Flasher.command)

You need Python 3.8+ with Tk (Linux: sudo apt install python3-tk; on Windows and macOS the installer from python.org includes Tk). No toolchain is needed: firmware for every board preset (five boards, plus a serial variant of the SKR Pico) ships in firmware/prebuilt/. Pick the Slave tab, choose your board, press Flash... and confirm. RP2040 boards: hold BOOTSEL while plugging in USB. STM32 boards such as the Creality 4.2.x: put the SD card in this computer, Browse to it, flash, then move the card to the printer and power-cycle it. AVR boards need avrdude installed. The Master tab flashes an ESP32-S3 with esptool (Install esptool, then Use shipped firmware, pick the port, Flash). The port box fills itself with the ESP32-S3's port when it can tell which one it is (otherwise pick it). The shipped image starts a WiFi network SkipperFlipper-XXXX (WPA2, default password skipperflipper, change it before real use) with a page at http://192.168.4.1/, a live log at /console and printer.cfg at /config; it talks Klipper to the printer board over UART (identify, clock sync, LEDs and thermistors from printer.cfg, confirmed on hardware; heaters, fans, TMC2209 drivers and motor tests from the test bench at /test, simulated only so far). Moves, homing and printing a file (Printer page at /printer) are built and simulated, not yet run on hardware. Logs appear on the chip's native USB port. ESP32-S3 only: other ESP32 chips (original, S2, C3) are not supported, and esptool refuses to write if it finds a different chip. You can also flash your own .bin. To connect the ESP32-S3 to an SKR Pico with four jumper wires, see docs/WIRING_SKR_PICO.md.

Only the skr-pico-uart firmware has run on a board, and only for the link and its on-board LED; the other presets have never been flashed. Read docs/FIRMWARE.md first, and do not flash a printer you cannot recover.

Quick start (Linux Mint / Ubuntu / Debian)

git clone https://github.com/The-Dorkknight/esp-printhost
cd esp-printhost
sudo python3 printhost.py

Options: --check (report only, change nothing), --no-gui, --clean, --yes, --version.

If anything fails it prints the path of a log file in ~/esp-printhost-logs/. Attach that when you open an issue.

macOS: the C++ library and tests build (python3 host/tools/build.py), but mcu_probe is Linux-only (it uses Linux's termios2 for 250000 baud) and the one-command setup is Linux-only.

Using the GUI

Build tools compiles everything and runs the unit tests. Output is colour-coded per tool.
Fake MCU: Start runs a pretend Klipper board (no hardware). Its port appears in the Port box.
Run probe connects, reads the board's pin list into the Blink pin dropdown, and prints uptime and state. Tick Blink pin and pick a pin to also toggle it 10 times.
The output box is selectable (Ctrl+C, right-click, Copy all, Save as...). Everything is also logged to ~/esp-printhost-logs/.

Try it without hardware

python3 host/tools/fake_mcu.py            # prints /dev/pts/N
./host/build/mcu_probe /dev/pts/N 250000 --pins --blink PA5

Try it on a real board

You need a board running stock Klipper MCU firmware (build it from Klipper with make menuconfig; this project does not ship firmware yet). Stop Klipper or anything else using the port, then:

./host/build/mcu_probe /dev/serial/by-id/<your-board> 250000 --pins --blink <pin>

Tested so far: BTT SKR Pico (RP2040, Klipper v0.10.0-181). The probe identified it, read 31 pin names, reset it, configured gpio24 and sent 10 toggles with 0 CRC errors.

Troubleshooting

Symptom	Likely cause and fix
`/dev/ttyUSB0` disappears when an Ender / Creality board is plugged in	brltty grabbing the CH340 chip. Re-run `sudo python3 printhost.py` and say yes to disabling it
`Permission denied` on the port	Not in `dialout` yet. `printhost.py` fixes today's session; log out and in for the long term
`Device or resource busy`	Klipper, Cura or a serial monitor has the port open. Close it
`no identify_response`	Wrong port or baud, board is not running Klipper firmware, or it needs a power cycle
`already configured`	The probe resets it automatically; if that fails, power-cycle the board
GUI will not open	`sudo apt install python3-tk`, or run `python3 printhost.py --no-gui`
Probe says OK but nothing lights up	See Known limitations

Known limitations

Only the link and the SKR Pico's LED have run on hardware (ESP32-S3 and SKR Pico); clock sync, printer.cfg and the SET_LED console also ran on it for about 41 minutes (docs/HARDWARE_LOG.md); the reset-and-reconfigure after editing printer.cfg has not been tried on hardware. Bootloader details for the other boards are assumptions that compile but are untested.
Heater, fan and motor control is new and has only run in simulation (fake_mcu.py and unit tests; see docs/TEST_BENCH.md). It follows Klipper's heater safety (board-side max_duration and ADC range checks, verify_heater, emergency stop), but has not been tried on real hardware: stay with the printer, keep a hand on the power switch, and do not rely on it unattended. Moves, homing and printing are newer still and have only run in simulation.
Pin toggle is not physically confirmed. On the SKR Pico the test used gpio24, which (as far as we can tell from BTT's pin map, not verified) is the NeoPixel/RGB header. A NeoPixel needs a timed data stream, so a plain on/off will not light one. The protocol side worked; try a pin with a visible LED or a multimeter on it.
finalize_config is sent with a fixed placeholder CRC, which is fine for stock firmware but is not a real config checksum yet.
The ESP-IDF build of the library is untested; only the PC build is exercised. The planner emits about one segment per tiny move, so link bandwidth for very fine G-code is unmeasured.
mcu_probe is Linux-only.
The GitHub workflows in .github/workflows/ have not been run yet.
Presets for boards with clone chips (some Creality 4.2.x) are flagged unverified; check your chip.
Design documents describe intent, not finished work.

Project layout

printhost.py          one-command setup + launcher
flasher.py            the Flasher window (also Flasher.bat / Flasher.command)
HOW_IT_WORKS.md       what it reads, changes and never does
docs/                 DESIGN, PROTOCOL, ENGINE, FIRMWARE, TUNING, TASKS, project page
firmware/esp32s3/       ESP32-S3 firmware (ESP-IDF project) + build.sh
firmware/prebuilt-esp32s3/  shipped ESP32-S3 image
firmware/boards/      board presets (.config + .json)
firmware/prebuilt/    shipped plain-Klipper firmware per board (+ pin tables); refresh with skipper_fw.py bundle
host/                 portable C++17 core (also an ESP-IDF component, untested)
  include/ph/         wire, msgproto, json_mini, config_ini, gcode, motion, planner, engine
  src/  test/         implementation + 480 unit tests
  tools/              build.py, skipper_fw.py, printhost_gui.py (+ fw_panel, skipper_theme),
                      mcu_probe.cpp, fake_mcu.py

Roadmap

See docs/TASKS.md. Next: real Klipper behaviour on the ESP32-S3, in stages: clock sync, configuring the board from printer.cfg, a harmless first action (LED), temperatures, then heaters with safety checks and motor tests (built, waiting for the hardware test), then real moves and homing, then printing a file. The look is a 1928 black-and-white cartoon (visuals only); a Benchy-themed pass is planned for when real building starts.

Source code: The-Dorkknight/esp-printhost on GitHub

SoloTrace

Matthew Armstrong — Thu, 29 Oct 2026 23:21:56 +0000

An easy PCB designer for single-sided, through-hole, quick-prototype boards. A small library of real full-size parts, traces up to 10 mm wide set with a slider, every corner chamfered (no pure 90° traces), an autorouter that avoids the "tangled string" look, and output for printing (toner transfer), Gerber fabs and a gantry diode laser (Elegoo Phecda) with a negative option and adjustable trace gap.

Screenshots are of the real program running on a Linux test machine with the built-in example boards.

Licence and no warranty. Copyright Matthew Armstrong. Licensed under the PolyForm Noncommercial License 1.0.0: free to use, change and share for non-commercial purposes; commercial use needs separate permission. It is source-available, not open source. GitHub shows the licence as "Other". This is not legal advice. The software is provided as is, with no warranty and no liability. Third-party parts keep their own licences (THIRD_PARTY.md).

Safety. Etching chemicals burn skin and eyes. A diode laser can blind you and start fires, and paint, resist and etchant fumes are harmful: wear laser safety glasses rated for your module, ventilate, never leave a running laser alone. The laser G-code has never been run on a real machine. Check every print against your real parts before etching.

What exists and what does not

Area	Status
Place, wire, trace, trim and jumper tools, undo/redo, pan/zoom, flip view	Works in tests and the screenshots; lightly tested by hand
Right-click menus (trim, split, tidy, width, rotate, duplicate, wire from a pin, route one net...)	Works in tests and the screenshots
Rigid wires (Shift + Wire): a direct power trunk that the rest of the net branches off	Works in tests and on the demo; first suggested from real use
Auto-route retries (best of up to 6 net orders), jumpers optional globally or per net	Works on the test boards; slower (up to about 12 s plus one try)
Cut tool: one click removes a piece of trace from joint to joint (Shift: between two points)	Works in tests
Favourites & recently placed parts; Shift + click turns a part while placing	Works in tests
Branches stay joined when a trunk is widened or tidied; DRC warns about hanging trace ends	Works in tests and on rebuilds of real boards
Board > Keep traces out from under parts	Works on the test boards; can add jumpers on cramped boards
Pin labels (B C E, G D S, K A, IN GND OUT, optocoupler and DIP layouts) and part values on the board	Works; layouts are the common ones for each shape, check your datasheet
Dragging a trace section sideways (neighbours follow, 45° rules kept)	Works in tests; lightly tested by hand
90 through-hole parts in a form-factor tree with a live preview, footprint wizard, KiCad `.kicad_mod` import	Works; some parts excluded on purpose (see below)
Trace width slider 0.4–10 mm (segment, trace or net) + current readout + "fits up to" hint	Works
Wide traces leave pads straight and end on the pad centre (auto-tidy)	Works on the test boards; may leave a trace as it was when the tidy shape does not fit
Deadbug (surface-solder, no-drill) pads, per part or per pad	Works
Chamfered corners everywhere + DRC	Works
Auto-place and auto-route with jumper fallback	Works on the three demo boards and random test boards; pure Python, can be slow on big boards
Gerber + drill zip, 1:1 PDF/SVG, BOM CSV, netlist text	Written and re-read by an independent Gerber library in tests; not opened in a fab's own viewer
Laser G-code (negative / isolation / positive, test cards, frame file)	Geometry checked in tests; never run on a real Elegoo Phecda
Windows and macOS launchers, GitHub workflows	Not run (written but untested on those systems)
Floating slider pop-up beside the cursor	Not built: the slider is in the right-hand panel
Full PathFinder-style negotiated routing, topological router, C++ speed-up	Not built (see DESIGN_NOTES.md)
Soldermask and copper-pour layers, multi-layer boards, SMD	Out of scope

Quick tour: your first board in 5 minutes

File > Open example > 555 LED flasher (or File > New board and set a size).
Place parts: pick from Favourites & recent at the top of the parts panel, or open a group in the parts panel on the left (the little arrows show the sub-types, such as Resistors standing), pick a part, check the drawing under the list, then click on the board. Or type in the search box (dip 8, to-220, standing). R or Shift + click turns the part, Esc stops placing. Star parts you use a lot with the button under the preview.
Wire: press W, click one pin, then another (or drag from pin to pin). A yellow rubber-band line shows the connection. Hold Shift for a rigid wire (see below). Click a rubber-band line to name its net or give it a class (Signal 0.8 mm, Power 2 mm, High current 5 mm; change them in Board > Board size and rules).
Auto-place, then Auto-route (toolbar). A progress bar with Cancel shows while it works. Routes use 0°, 45° and 90° moves, and a 90° turn is always built as two 45° turns (a chamfer). If a trace can't get through, a wire-link jumper (blue dashed) is added on the component side.
Label: select a part and type its Value / type (NE555, BC547, 10k...), and pick its Pin labels (B C E, G D S, IN GND OUT...).
Tweak: drag a trace section sideways to move it, use Trim (X) to cut a section out, and right-click anything for its menu.
Check, then Export.

Feature by feature

Library and parts. 90 parts, sorted by shape (form factor) rather than by maker code. Each group has an arrow that opens its sub-types:

Group	Sub-types
Chips (DIP)	Narrow (7.62 mm rows) DIP-4 to DIP-28, wide (15.24 mm rows) DIP-28 and DIP-40
Transistors & regulators	TO-92, TO-220 (2-pin, 3-pin, with heatsink outline), TO-247 / TO-3P
Resistors, diodes & inductors	Resistors lying flat (1/4 W to 5 W), resistors standing (1/4 W at 2.54 and 5.08 mm, 1/2 W and 1 W at 5.08 mm), diodes lying flat and standing, axial and radial inductors
Capacitors	Ceramic disc, film / box, electrolytic
LEDs	3 mm and 5 mm
Pots, switches & crystals	Inline pots (2.54 and 5.08 mm), triangle trimmer, 6 mm tactile switch, HC-49 crystal
Connectors	Pin headers 1-row and 2-row, screw terminals, JST-XH
Board bits	Wire links, mounting holes, solder and surface pads
My parts	Parts you made or imported

Click a part and a drawing of it (copper, holes, outline, pin numbers, pitch and drill) appears under the list, in the sidebar, with no pop-up. Names say what the part is ("Electrolytic cap, 5 mm pitch"), not an obscure model number. Left out on purpose because their sizes vary too much between makers: relay, USB-B, barrel jack, buzzer, fuse holder, panel pots with lugs, TO-126, bridge rectifiers. Make those with the wizard. Body outlines, the inductor, pot and trimmer layouts, and the standing-part pitches are generic: check them against your real part.

Your own parts. Parts > New footprint... opens the wizard: type a pad table (name, x, y, pad size, drill), or click on the canvas to drop pads, or start from a DIP or header preset, then save. Saved parts live in ~/.solotrace/parts (Parts > Open my parts folder). Parts > Import KiCad .kicad_mod... reads the text format of a KiCad footprint (through-hole pads and silkscreen lines only).

Trace width. Press T and click along the board to draw a trace (Enter, a double-click or Finish trace here on the right-click menu finishes it; corners are chamfered for you). To change a width, click a trace section on the drawing, or click a yellow rubber-band line to set the width of a whole net, then drag the slider in the right panel (0.4–10 mm; preset buttons 0.4, 0.8, 1.5, 2.5, 5, 10). Choose whether it applies to the section, the whole trace or the whole net. The panel shows roughly how many amps that width carries (IPC-2221 outer-layer formula; board settings give copper weight and temperature rise; a guide only) and how wide the trace can go where it is before it breaks the clearance rule.

Rigid wires (power trunks). A net with more than two pins is normally routed by joining the nearest pins first, so a ground net can end up as one long chain (transistor to capacitor to terminal). If you want a direct trace between two particular pins, hold Shift while wiring them (click or drag), or right-click a pin > Rigid wire from this pin, or right-click an existing rubber band > Make ... rigid. The router routes every rigid pair first, as its own pin-to-pin trace, then connects the rest of the net to the nearest point of that trunk, so a capacitor becomes a short branch. "Rigid" fixes which two pins are joined, not the path: the trunk bends round other parts like any trace, can be moved by a re-route, and you can drag or cut it. Rigid rubber bands are thicker and orange; the routed trunk is drawn in orange copper (it is ordinary copper in every export). The net panel lists the rigid pairs, each with a make normal button.

Values and pin labels. Select a part: Value / type at the top of the right panel takes anything (NE555, BC547, IRF540, 7805, 10k, 100uF 25V) and is shown next to the part name on the board; double-click a part to jump to it. Pin labels offers the common layouts for that shape, not specific part numbers:

Shape	Layouts offered
TO-92	E B C, C B E, B C E, D G S, G D S, S G D, small regulator OUT GND IN / IN GND OUT
TO-220 3-pin	power transistor B C E, MOSFET G D S, IGBT G C E, regulator IN GND OUT, adjustable regulator ADJ OUT IN, negative regulator GND IN OUT, triac MT1 MT2 G, dual diode A K A
TO-220 2-pin	diode K A / A K
TO-247	G D S, G C E, B C E
DIP-4 / DIP-6	optocoupler A K E C; optocoupler with base pin; opto-triac
DIP-8	555-style timer, dual op-amp, single op-amp, dual optocoupler
DIP-14 / 16 / 20	logic GND and VCC pins; quad op-amp (DIP-14)
Pots, connectors	1 W 3, CCW W CW; + -, - +, AC AC, IN OUT, V+ GND V-, IN GND OUT

Or type your own in pin order, separated by spaces (. skips a pin). Diodes and LEDs show K A, electrolytics + -, without asking. Pin orders differ between makers, so always check the datasheet of the part you have. Labels are shown in the editor; they are not yet written into the Gerber silkscreen.

Wide traces are tidied. When a trace is 1.2 mm or wider, SoloTrace makes it leave each pad with a straight vertical or horizontal run (about the pad radius plus the trace width) before it turns, ends it exactly on the pad centre, and makes the chamfers bigger where there is room. This happens after auto-routing and, with Auto-tidy when the width changes ticked (the default), whenever you change a width. If the tidier shape would touch other copper the trace is left as it was, and the clearance problem is marked in red. Tidy (right panel or right-click) does it on demand; Edit > Tidy all traces does the whole board.

Cutting a piece out of a trace. Press C and click a trace: the piece under the mouse goes, from the joint before it to the joint after it (a pad, a place where another trace meets it, a jumper pad). The rest of the trace and of the net stays. While you hover, the piece that would go is shown in red. Right-clicking a trace only opens its menu; rest the mouse on Cut this piece to see the piece in red, and choose it to remove it. To cut between two points of your own choosing, Shift + click the first point and Shift + click the second (or right-click > Cut between two points); Esc cancels.

Moving, trimming and splitting traces. With Select, drag a trace section sideways: it moves parallel to itself and the sections either side stretch to follow at their own angle, so no 90° corner appears. Ends on pads stay put (a 45° link is added). Trim (X, or right-click > Trim this section) cuts one section out and leaves the rest as separate pieces; Split trace here breaks a trace in two without removing copper. A trace you have moved or trimmed counts as hand-drawn, so Auto-route keeps it. Ctrl+Z undoes any of this.

Right-click menus. Right-click (without dragging) on a trace, pin, part, rubber-band line, jumper or empty board for the actions that fit: widths, trim, split, tidy, highlight or re-route the net, rotate either way, duplicate, lock, pad styles, wire or trace from a pin, disconnect, delete, and Undo/Redo. Right-drag still pans.

Small helpers. Hover over copper to light up its whole net (the net name shows in the corner). Arrow keys nudge the selected part by 1.27 mm (Shift: 2.54 mm), Ctrl+D duplicates it, Shift+R turns it back. File > Open recent lists your last boards. While a board has unsaved changes it is saved every 2 minutes to ~/.solotrace/autosave.solotrace; File > Recover autosave opens it (the file is removed when you quit normally). Hover over a toolbar button for a hint. The status bar shows the cursor position in mm and a green all routed or orange N to route badge.

Pads: through-hole or deadbug. Pick Through-hole, Deadbug or Both in the toolbar for new parts, or change it for a placed part in the right panel, or for one pad ("This pad only"). Deadbug pads have no hole and are drawn as a long oval that sticks out from the part so you can bend the lead flat and solder it on the copper side. "Both" keeps the hole and the extra copper.

Auto-place. Simulated annealing that moves, rotates and swaps unlocked parts to shorten the ratsnest and cut crossings. Tick Lock on a part to keep it where it is.

Auto-route. A grid router that remembers its heading, so it prefers straight runs and clean 45° bends instead of staircases. Wide nets are routed first, and it prefers not to run under part bodies. If a net is blocked it tears up the nets in the way and retries; as a last resort it adds a jumper, unless you unticked Jumpers in the tool bar or for that net. The whole job is tried with up to six different net orders (about 12 seconds at most, plus the try in progress) and the best result is kept; it stops early when a try routes everything without jumpers. Traces you drew by hand are kept. Board > Remove automatic routes undoes only the automatic ones.

Jumpers. Press J to add one by hand. They are plain wire links on the component side, in 2.54 mm steps from 5.08 mm. They are listed in the DRC window.

View. M flips between the component side (how you place parts) and the copper side (how the etched board looks from below). Wheel zooms, right or middle drag pans, right-click opens the menu, F fits the board.

DRC. Check lists trace ends that are not joined to anything ("dangling"), copper too close to other copper or the board edge, parts sticking out of the board, traces thinner than the minimum, turns sharper than 45°, drilled pads with too little copper ring, jumpers that are the wrong length or cross each other, and pins that are not connected yet. Click a row to jump to it on the board.

Exports (Export menu).

Output	Use
Gerber + drill (zip)	Copper (bottom), board edge, silkscreen, Excellon drill. Single layer; no soldermask layer
1:1 PDF / SVG, mirrored	Toner transfer or photo-resist film: the copper side as you will see it. Always print at 100 % and measure a known distance before etching
1:1 PDF, design view	Component-side print
Bill of materials (CSV)	Parts grouped by name and value
Netlist text	Round-trip text format for a quick board from a text editor
Laser G-code (Elegoo Phecda)	See below

Laser etching with the Elegoo Phecda (gantry diode laser)

Read this first. A diode laser cannot remove bare copper. The method is: paint the copper, let the laser burn the paint away where copper must go, etch, then clean the paint off. Nobody has run these files on a Phecda yet. Treat every default as a starting guess and use the test cards.

Finish the board and run DRC. Open Export > Laser G-code (Elegoo Phecda)...
Mode
- Negative (default): burns everything that is not copper, so paint is left only on the traces and pads. Slowest, cleanest.
- Isolation: burns only a band of gap mm around the copper. Fast; leftover paint between bands must be cleared by hand or by the etchant.
- Positive: burns the copper shapes themselves (for a negative-working resist or marking).
Adjust (all live-previewed):
- Trace adjust (mm per side): positive grows the copper, negative thins it and widens every gap between traces. Use this to correct for the laser's spot size and your etch.
- Gap (isolation band width) and Border (keep paint at the board edge).
- Line interval (default 0.08 mm; the module's spot is about 0.06–0.13 mm depending on model), feed (default 1500 mm/min), power (default 70 % of S max), passes, crosshatch (second pass at 90°), bidirectional scanning, M4 dynamic power (default) or M3 with overscan, and drill dots (a tiny burn at every hole centre as a drilling guide).
Click Save G-code.... Also use Frame file... (traces the board outline at 1 % power so you can line up the paint) and, on first use, Speed/power test... and Trace/gap test... (a grid of squares and a ladder of fine traces and gaps).
In LaserGRBL or LightBurn: jog the laser to the lower-left corner of the board as seen from the copper side, set work zero there, open the file, check the preview, run the frame, then burn. The exporter mirrors X for you because the design view is the component side.
Controller assumptions: GRBL-style, $30 equal to the S max in the dialog (default 1000) and $32=1 (laser mode). The Elegoo manual names LaserGRBL and LightBurn but does not say "GRBL"; see docs/research/phecda-laser-notes.md.

Examples to look at without installing anything: examples/ has four boards, each with its .solotrace file, Gerber zip, 1:1 copper-side SVG and PDF, BOM and laser G-code in both modes, plus test cards.

HOW_IT_WORKS.md: what it reads and writes, the coordinates, the router and the laser engine in plain English
DESIGN_NOTES.md: decisions, rejected ideas, measurements, what is untested
docs/research/: the original research and plan, and the Phecda notes
CHANGELOG.md · CONTRIBUTING.md · SECURITY.md

Project page (after you enable GitHub Pages): https://The-Dorkknight.github.io/solotrace/

Source code: The-Dorkknight/solotrace on GitHub

A POINT of contention

Matthew Armstrong — Tue, 20 Oct 2026 14:43:06 +0000

STL to STEP conversion shouldn't be that HARD: a proposed hybrid STL format that is CAD-friendly and slicer-compatible

Converting an STL back to a STEP file means guessing the original CAD faces. This paper proposes a normal binary STL that also records them, so slicers still open it and converters no longer have to guess. It is also a public, dated description of the format, and a list of the ideas that didn't work.

Matthew Armstrong · GitHub The-Dorkknight · United Kingdom\
First published 15 October 2026 · Version 1.0\
Text and figures: CC BY-SA 4.0. Code that comes with it: PolyForm Noncommercial 1.0.0.

📄 PDF · 🌐 Web page · 🔧 The FreeCAD and Fusion plug-ins · About this repository

This page is the full paper (the same text and figures as the PDF).

Contents: Abstract · Why I wrote this · The problem: what STL loses, and how slicers read it · Prior art: what I found (3–10 October 2026) · How the idea was judged · The ideas that didn't work · The format, in one picture · Does it help? · What works, and what doesn't yet · Defensive disclosure: the hardpoint STL and variations · What I'd test next (feel free to use this plan) · Working together · How this was made · Code, data and how to reproduce · Licence, and keeping it free · Disclaimers · How to cite · References · Appendix A: a real hardpoint STL

Status: nothing in this paper has been run in real FreeCAD, in Fusion, or in a slicer. The format and its reference code were tested on Linux, using test parts built with OpenCASCADE and the file-reading code that slicers use (not the slicers themselves). The FreeCAD and Fusion exporters were only tested against stand-ins for those programs. The conversion results come from one converter of mine. If you open the example files in your slicer before I do, please tell me what happened.

Not legal advice. I am not a lawyer. Where this paper talks about prior art, it says what I found, where I found it, and when. A patent attorney is the person to ask about what it means.

Plain STL: 1,103 faces	Hardpoint STL: 8 faces

The same knob, made from the same triangles, converted to STEP. Left: from a plain STL, which came out with 1,103 faces. Right: from the hardpoint version of the file, which came out with 8 faces. The original CAD model has 4.

Abstract

An STL file is just a pile of triangles. It has lost everything the CAD program knew: which triangles made up one flat face, which made up a round hole, and where the corners were. Turning an STL back into a real CAD solid means guessing all of that again, and the guesses go wrong most often on coarse meshes and curved edges.

This paper describes a way to keep that information in the file without breaking it for anyone else:

The idea: write the CAD facts into the two places a binary STL already has spare room that slicers ignore: the 80-byte header, and the 2-byte "attribute" field after every triangle.
What goes in: which face each triangle belongs to (as a small colour number, like colouring a map so that neighbouring areas differ), what kind of surface the face is, and which triangle corners are CAD vertices ("hardpoints"). A checksum in the header shows whether the mesh was edited afterwards.
What a slicer sees: the same triangles, the same file size, the same .stl extension.
How much it helps: in my tests, a converter given the labelled file turned a knob into a STEP solid with 8 faces. From the same triangles without labels it made 1,103 faces (the original CAD model has 4). On a clean, fine bracket the gain was small: 21 faces down to 17, against 16 in the original.
What didn't work: data after the last triangle, a 9-bit face number, hiding the whole STEP file inside the STL, remembering how freeform faces were cut up, and a handful of mistakes along the way.

Section 8 describes the format and its variations in enough detail to build them. It is written as prior art, so the method stays free for everyone to use.

0. Why I wrote this

How it started:

I convert STL files into STEP files. Most of the converter's effort goes on working out again what the CAD program already knew.
The CAD program could say it at the moment it writes the STL. Instead it throws the answer away.
A binary STL has two spare places that slicers ignore. I'm a hobbyist in the UK with a laptop, and I wanted to see if the answer could be kept there.

So I built the hardpoint STL, plus an exporter for FreeCAD and one for Fusion. First I researched how slicers read STL files. Then I tried to find every way a file like this could break them.

Why publish all of this, including the failures? Four reasons:

Protection. I looked, and found no earlier description of putting CAD face labels inside an STL (section 2). If that is right, a dated, detailed public description is a cheap way to keep the idea free for hobbyists. That is what a defensive publication is.
Saving you time. Every dead end here is one you don't have to walk down. The best one began as a question of mine that turned out to have a simple numerical answer (section 4.3).
Getting other people involved. The format has room for more exporters (CadQuery, Onshape, SolidWorks) and more readers than I can write.
Selfishly: by my calculations, a third paper makes me about 0.7 % more employable. The first was worth 22.7 % and the second 3.14 %, so the returns are falling. That's probably fine. Publish too many and I start to look like I have a lot of free time, and nobody wants to hire someone who looks that available.

How this was made. The ideas, the questions and the rules are mine. The code, the tests, the measurements and the first draft of this write-up were done with an AI assistant (Claude, by Anthropic), working to my design. All sources are linked so you can check them, and the code is included so you can re-run every number that can be re-run (section 12).

1. The problem: what STL loses, and how slicers read it

1.1 What gets lost

A CAD solid is made of faces: planes, cylinders, spheres, cones, tori and freeform surfaces, joined along edges and corners. Exporting it as STL cuts every face into triangles and writes only the triangles. A flat face and a rounded edge of the same bracket both end up as nothing but triangles.

A mesh-to-CAD converter has to work out again which triangles form one flat face (and how flat is flat enough?) and which form a curve. When the mesh is coarse, or a curve meets a flat face very gently, it can't always tell.

1.2 What I set myself

The design had to meet six requirements, in this order:

Recognised as an STL. The extension stays .stl and the file loads in any slicer without a plug-in.
Identical to a normal STL in a slicer. Same triangles, same file size, nothing a slicer acts on.
Makes STL-to-STEP conversion easier. It carries what a converter otherwise guesses: faces, surface types, corners.
Writable from inside CAD programs. FreeCAD's and Fusion's own Python can't be assumed to have NumPy, so the writer uses the standard library only.
Never makes a conversion worse. Labels are hints. The reader checks each one.
Runs on low-end hardware. The target machine is a 7th-generation Core i3.

1.3 What STL readers do with a file

A binary STL has an 80-byte header, a 4-byte triangle count, then 50 bytes per triangle: 12 for the normal, 36 for three corners, and 2 for an "attribute byte count" that slicers ignore. So there are exactly two places that carry no meaning to a slicer. Anything after the last triangle is a different matter.

Reader	Used by	Binary or text test	Triangle count	Extra bytes at the end	How this is known
admesh `stlinit.cpp`	OrcaSlicer; PrusaSlicer-family slicers share this code	Binary if any of the 128 bytes after offset 84 is above 127	Taken from the file size; the header count only logs a warning	Rejected unless a multiple of 50, then read as phantom triangles	Read OrcaSlicer's source (PrusaSlicer's and Bambu Studio's copies not read)
numpy-stl	Cura, through Uranium's STLReader	Automatic mode	From the header	Load fails with an error	Read Uranium's source; ran the library
trimesh	many Python tools	Binary only if the size is exactly 84 + 50 × count, otherwise tried as text	From the header	Not binary, then fails as text (0 faces)	Read trimesh's source; ran the library

Other findings that shaped the format:

The admesh text test misreads simple files. A cube at whole-millimetre coordinates with zero normals has no byte above 127 in that window, so it is read as text and imports empty. This is OrcaSlicer issue 15993, open when I checked on 3 October 2026. A probe copying the test's logic reproduced it.
The header must not start with solid. Some software then treats the file as text (Wikipedia).
Two colour conventions already use the attribute field. VisCAM and SolidView: bits 0–4 blue, 5–9 green, 10–14 red, bit 15 = 1 means the colour is valid. Materialise Magics: a COLOR= string in the header, bits 0–4 red, 5–9 green, 10–14 blue, bit 15 = 0 means the triangle has its own colour (both as described on Wikipedia).
trimesh drops the attribute field during clean-up. With process=True it survives vertex merging, but removing sliver triangles rebuilds the mesh. On one test part 5,572 triangles became 5,564 and the field was gone.

2. Prior art: what I found (3–10 October 2026)

Using the attribute bytes of an STL for something other than "nothing" is old: the two colour conventions above are the best-known uses. What I looked for was a file that keeps CAD face identity, surface types and CAD vertices inside an ordinary STL.

I found no description of that. The searches were ordinary web and code searches by me and my AI assistant, over a few days. They are not a professional prior-art search, and a miss here proves little.
Existing mesh-to-STEP tools (stlToSolid, breptile) segment the mesh and fit primitives from the triangles alone. As far as I could tell neither reads hints from the file.
The standard container for "a mesh plus the real CAD in one file" is 3MF, which is a zip. It is not an STL, and I did not test how slicers treat an extra file inside one.

Whether any of this affects anyone's rights is a question for lawyers, not me.

3. How the idea was judged

I can't build exact CAD parts by hand, so I had a CAD kernel make them:

Test parts. Two parts built with OpenCASCADE (the kernel FreeCAD uses): a bracket (rounded corners, three holes, a boss, a countersink) and a knob (cylinder, sphere, torus fillet). The bracket was meshed at two settings.
Twin files. Each mesh was written twice with identical triangles: once labelled, once as a plain STL.
The converter. Both files went through STL2STEP, an earlier converter of mine (since superseded; its code is not in this repository), default settings. I counted the faces in the STEP result, the largest distance from the mesh, and the volume against the original CAD solid.
The format itself. Round trips (write, read back, compare faces, types and hardpoints), tamper checks, and the loaders of section 1.3.

What this gets wrong (please read before quoting a number):

Three test parts, built for the tests. No real downloaded models.
One converter. Another converter may use the labels better or worse.
Linux only. The writer was timed on a cloud machine, not on a Core i3.
The FreeCAD and Fusion code ran against stand-ins with the same attribute names, filled with OpenCASCADE geometry. That checks the plug-ins' own logic and nothing about how the real programs behave.

4. The ideas that didn't work

4.1 The table

Seven ideas were built or tested and then dropped. Each row says what the evidence was, so nobody repeats the experiment blind.

Idea	What happened	Evidence
Store extra data after the last triangle	Loaders fail or read garbage	numpy-stl raised an error, trimesh loaded 0 faces, admesh's logic reads phantom triangles
A global face number in 9 bits	Replaced by colours	Capped at 511 faces; colours need 2 to 5 values for any count
Hide the STEP file itself in the STL	It doesn't fit as text, and only sometimes when compressed	Section 4.3
Remember how a freeform face was cut into patches (a second, 3-bit "patch colour")	Faster but worse, so removed	Organic part: 83 s down to 19 s, but 20 areas left as facets instead of 2 and maximum deviation 0.16 mm instead of 0.12 mm
Let the converter's normal detection handle cone and torus faces	It chopped them into cylinder and sphere pieces	Knob: 131 STEP faces and 3 failed faces, against 8 faces when treated as freeform
Label a whole-body mesh by nearest triangle centre	Mislabelled triangles beside face borders	About 1 % wrong on the knob, which turned into 11 false flats and 315 STEP faces. Point-to-triangle distance gave 100 %
Carry the attribute field through trimesh's clean-up	Lost whenever slivers are removed	5,572 triangles became 5,564 with no attribute data. Matching by position replaced it

A likely reason saved patch layouts gave a worse result (not proven): the fit of a patch depends on its border curves, and the converter smooths those borders step by step over several passes. Starting from the final layout skips the steps that made it fit.

4.2 Mistakes along the way

These are in the order they happened. Most were the AI assistant's, and they were caught by tests I had asked for.

1. A missing triangle. The knob's sphere has a pole where one triangle collapses to a line once nearby points are welded. The writer rightly dropped it (1 of 2,959). The tests then compared labels with the wrong triangles, because the output order no longer matched the input. The encoder now reports which input triangle sits at each output position.

2. About 1 % of triangles mislabelled. Fusion's fallback labels a whole-body mesh from per-face meshes. First version: nearest triangle centre. It looked fine in a picture and mislabelled about 1 % of triangles beside face borders, which a converter read as 11 flat faces and 315 STEP faces. Point-to-triangle distance fixed it.

3. A flat disc shown as rough facets. The converter's preview showed the top of the bracket's boss as dark left-as-facets. The rule that called a planar face a facet was "three edges or fewer"; a flat disc bounded by one circle qualifies. It now also requires every edge to be straight.

4. A renamed OpenCASCADE method. The test code called TopoDS.Edge_s, which doesn't exist in the OCP 8 build installed. A small compatibility helper hides the difference.

5. A changelog that claimed too much. I compared my changelog with the public repository of the converter on the day I packaged it. Five bullets under the published version had been added after it was published. They moved to the new version's section.

6. Screenshots taken at the wrong moment. Two documentation screenshots showed a job queue card and a sandbox folder name. They were retaken in a clean state.

7. A plug-in never tried in its real program. I could not install FreeCAD where this was built: its release downloads, conda-forge, the Ubuntu package source, the PPA and Flathub were all blocked, and I did not route around the block. So the workbench ran only against stand-ins. In its place, tests/freecad_selfcheck.py runs inside the real program in a few seconds. It has not been run either. I keep repeating that because it is the most useful thing a reader could check.

4.3 Could the whole STEP file be hidden in the STL?

Partway through I asked: would it be easier to hide a STEP file inside the STL as plain text? It was worth checking, because it would give the exact CAD model back with no fitting at all.

It doesn't fit. The room in an STL grows with the triangle count (2 bytes each), while the size of a STEP file grows with the number of faces:

Part	STEP file	STEP compressed	Attribute room (2 bytes × triangles)
Bracket, 1,180 triangles at 0.05 mm	48.1 KB	6.6 KB	2.3 KB
Knob, 2,958 triangles	9.3 KB	2.1 KB	5.8 KB

Simple parts with big flat faces fit worst. A text (ASCII) STL has no comment syntax; from reading OrcaSlicer's reader, extra text lines inflate its triangle count and the load fails (read, not run). A compressed STEP would also need every attribute bit, including bit 15, and would compete with the labels for the same bytes. It could be an optional extra: store it when it fits, fall back to labels when it doesn't. That is a variation in section 8.6, not a result.

5. The format, in one picture

Drawn from the specification by tools/make_illustrations.py.

Header (80 bytes of ASCII, padded with spaces):

HARDPOINT-STL 1 u=mm tol=0.05 ang=15 crc=e67609a0 by=cad-example

Field	Meaning
`HARDPOINT-STL 1`	Marker and format version
`u`	Units: `mm`, `in`, `cm` or `m`
`tol`	How far triangles may be from the true surface, in those units; 0 = unknown
`ang`	Meshing or sharp-edge angle in degrees; 0 = unknown
`crc`	CRC-32 of the 48 geometry bytes (normal and corners) of every triangle, in file order
`by`	What wrote the file

Attribute field (16 bits per triangle, little-endian):

Bits	Meaning
0–4	Face colour, 0 to 31. Faces that touch along an edge never share a colour
5–6	Reserved, 0
7	1 = this triangle is labelled
8–10	Surface type: 0 unknown, 1 plane, 2 cylinder, 3 sphere, 4 cone, 5 torus, 6 freeform, 7 keep as facets
11–13	Hardpoint flags for corner 1, 2 and 3 of the triangle
14	Reserved, 0
15	Always 0 (some viewers read bit 15 = 1 as "this field is a colour")

The bracket example (examples/bracket_hardpoint.stl): 1,180 triangles, 16 faces labelled with 3 colours, 25 hardpoints. Drawn from the file itself.

Why these choices (every one follows from section 1.3 or from a measurement):

Question	Chosen	Rejected	Why
Where the labels live	Header and attribute fields	Data after the last triangle	A trailer fails in numpy-stl and trimesh and becomes phantom triangles in admesh
How a face is identified	A 5-bit colour; a face is the edge-connected triangles sharing it	A global face number	Colours label any number of faces. Test parts needed 2 to 5 colours
Surface parameters (plane, axis, radius)	Not stored; the reader fits them	A parameter table	No room without a trailer. Fitting is cheap once the faces are known, and a reader must verify anyway
CAD vertices	3 bits per triangle, one per corner	A separate vertex list	No room. Needed where only two faces meet but a line runs into an arc
Detecting edits	CRC-32 of the triangle data in the header	No check	Stale labels on an edited mesh would mislead the converter
"Labelled" flag	Bit 7, and a labelled triangle is written first	A separate guard	Bit 7 of the first attribute byte also defeats the admesh text misread
Bit 15	Always 0	Free use	VisCAM-style viewers read bit 15 = 1 as a colour
Trust	Every label is checked against tolerance	Believe the file	A wrong or stale label must not produce a wrong solid

6. Does it help?

Labels helped most on a coarse mesh and on a part with a sphere and a rounded edge. On a clean, fine mesh of flats and cylinders they changed little.

Volume error is the STEP solid against the original CAD solid (bracket 24,490.97 mm³, knob 12,347.01 mm³). Converter: STL2STEP 0.2.0-wip, Classic engine, default settings.

Part	Triangles	Plain: STEP faces	Plain: volume error	Plain: max deviation	Hardpoint: STEP faces	Hardpoint: volume error	Hardpoint: max deviation
Bracket, 0.05 mm mesh	1,180	21	−0.013 %	0.050 mm	17	+0.001 %	0.049 mm
Same bracket, coarse 0.3 mm mesh	578	90	−0.075 %	0.109 mm	29	+0.002 %	0.086 mm
Knob, 0.05 mm mesh	2,958	1,103	−0.18 %	0.129 mm	8	+0.007 %	0.060 mm

On the coarse bracket the plain conversion found 55 "flat" faces where the CAD model has 7.
On the knob, the plain conversion took 14 s and the labelled one 2 s. The converter's second engine showed the same pattern in face counts: 21 to 17, 125 to 17 and 77 to 8.
The CAD models have 16 faces (bracket) and 4 (knob), so even with labels the converter returns slightly more than the original. Cone and torus faces are labelled but the converter fits them as freeform surfaces.

The knob in the converter's own 3D preview, from the plain STL and from its hardpoint twin (same triangles; blue = flat, green = cylinder or sphere, grey = freeform surface, dark = left as facets):

Plain STL: 1,103 faces	Hardpoint STL: 8 faces

Other measurements:

Colours needed: 2 on the knob, 3 on the bracket's 16 faces, 5 on an organic part's 69 fitted regions.
Round trip: the reference reader rebuilt exactly the faces, types and hardpoints written, on all three parts (25 of 25 and 4 of 4 CAD vertices).
Loaders: numpy-stl returned triangles identical to the plain twin; trimesh loaded each file as watertight; the admesh text test classed each as binary.
Plain inputs unchanged: five parts on the Classic engine and four on the second engine gave the same face counts, deviation and volume as before the feature was added.
Writer speed, pure Python: 4,894 triangles in 0.1 s and 15,384 in 0.2 s. The whole-body fallback added 0.4 s and 2.0 s. Measured on a cloud machine, not on a Core i3.

7. What works, and what doesn't yet

	Tested here	Simulation or stand-in only	Not tested / unknown
Format	Write, read, tamper check, `verify`, `strip`; examples pass
Loaders	numpy-stl, trimesh; admesh text test (logic copied from the source)		The slicer programs themselves
FreeCAD export		Logic against a stand-in filled with OpenCASCADE geometry	Real FreeCAD (0.20 to current); whether older versions accept the meshing call used
Fusion export		Per-face and whole-body routes against a stand-in	Real Fusion; whether per-face meshes close; winding on reversed faces
Converter	Three parts, two engines		Real downloaded models; large meshes (labels tested up to 5,120 triangles)
Systems	Linux		Windows, macOS
Colour-aware viewers			Whether a viewer using the Magics convention tints faces without `COLOR=` in the header

Known limits:

Any program that re-saves the STL writes its own header and zero attribute fields, so the labels vanish. That is also why the file falls back to a plain STL, which is the safe direction.
Text (ASCII) STL cannot carry labels.
More than 32 faces that all touch each other cannot be coloured; the writer refuses with an error. No test part has hit this.
Shapes with shared faces (FreeCAD compsolids) may give a segment count that differs from the face count; types are then written as unknown.
Fusion bodies inside occurrences are exported in their own component's coordinates, not the assembly's.

8. Defensive disclosure: the hardpoint STL and variations

This section is written to be prior art. It describes the method and its variations in enough detail for a person skilled in CAD programming and mesh file formats to build them. I dedicate the methods described in this paper to the public, and I will not seek patent protection for them. Where a variation is untested, it says so; untested variations are disclosed as possibilities, not as results.

8.1 The core method

A method of storing computer-aided-design face information in a triangle-mesh file in the binary STL format, such that the file remains a valid binary STL, comprising:

Keep the file a binary STL. Write an 80-byte header, a 4-byte little-endian triangle count, and for each triangle 50 bytes: a normal (3 × float32), three corners (9 × float32) and a 2-byte attribute word. The file size is exactly 84 + 50 × the triangle count. The geometry bytes are those a conventional export of the same mesh would give.
Put the file-level facts in the header. Begin the 80-byte header with an ASCII marker and a version number, followed by space-separated key=value fields: units, mesh tolerance, mesh angle, a checksum of the geometry bytes, and the writer's name. The header does not begin with the word solid. Readers ignore keys they do not know.
Put the per-triangle facts in the attribute word. For each triangle, store (a) a face colour in 5 bits, (b) a "labelled" flag, (c) a surface-type code in 3 bits, and (d) three bits flagging which of the triangle's three corners are CAD vertices (hardpoints). Leave remaining bits as reserved zeros, and keep the most significant bit zero.
Identify faces by colouring, not numbering. Assign each CAD face a colour so that any two faces whose triangles share an edge have different colours. A face is then recovered as a set of edge-connected triangles of equal colour. A small number of colours labels any number of faces.
Make labels checkable. The checksum covers the 48 geometry bytes of every triangle in file order, so a reader detects that the mesh was changed after labelling, and then treats the file as an unlabelled STL.
Make labels hints. A reader checks each labelled face against its own tolerance and falls back to unaided detection for any face that fails.

8.2 The reference writer (as built)

The reference writer is hstl.encode, about 100 lines of Python (standard library only), so it can run inside FreeCAD's and Fusion's own interpreters.

Round and weld. Round every coordinate to float32 (after an optional scale, e.g. ×10 for a program working in centimetres). Merge points closer than a welding tolerance, by default 2 × 10⁻⁷ of the part's bounding-box diagonal (at least 10⁻⁹). A CAD kernel gives the two faces along an edge points that differ in the last digits, so exact matching leaves the mesh open.
Drop collapsed triangles. A triangle with two corners welded together is left out, and the writer returns which input triangle each output position holds.
Check the mesh. Count edges used by one triangle (open) and edges used by more than two, or by two triangles in the same direction (bad). Report the mesh as watertight when there are none.
Colour the faces. Build a graph whose nodes are faces and whose edges join faces sharing a mesh edge. Colour it greedily in smallest-last order: repeatedly remove the node of lowest remaining degree, then assign colours in reverse removal order, each the smallest not used by a neighbour. Refuse, with an error, if 32 colours are not enough.
Flag the hardpoints. For each CAD vertex, find the welded mesh point nearest to it within 50 welding tolerances; set the flag bit of every triangle corner using that point. Report how many vertices found no point.
Put a labelled triangle first. Swap one labelled triangle into position 0. Its attribute word has bit 7 set, which makes the sniffing test of section 1.3 see a byte above 127 near the start.
Write the records. Recompute each normal from the welded corners as a unit vector. Pack the attribute word as (colour) | 0x80 | (surface type << 8) | (corner flags << 11). Triangles without a face get zero.
Checksum and header. CRC-32 over the 48 geometry bytes of every record in order; write the header with it.

8.3 The reference reader

Recognise. Read the 84-byte prefix. The file is a hardpoint STL if the header starts with the marker, the file size is 84 + 50 × count, and the version is known. Otherwise treat it as a plain STL.
Verify. Recompute the checksum. On a mismatch, ignore the labels.
Weld corners with identical float32 coordinates (a writer has already welded within tolerance, so exact matching suffices).
Group triangles that share an edge and have the same colour into faces. A triangle with the labelled flag clear belongs to no face.
Type each face by majority vote over its triangles' type codes.
Collect the corners flagged as hardpoints.

8.4 How a converter should use the labels

This is the behaviour of the converter I measured with, written as a recipe:

If the header gives units other than millimetres and the user did not choose units, use the file's.
Load and clean the mesh as usual. Skip labels if the mesh was reduced first.
Match each cleaned triangle to the file's nearest triangle centre. Require at least 98 % to match within 0.25 × the header tolerance, otherwise ignore the labels.
Handle each face by its type:

Label	Check	If it passes	If it fails
Plane	Least-squares plane; every corner within 1.5 × tolerance	A true plane	Unaided detection inside that face
Cylinder, sphere	The usual fit; if its sanity rules reject it, a least-squares fit of the labelled kind with every corner within tolerance	An analytic cylinder or sphere	Unaided detection inside that face
Cone, torus, freeform	None up front	Freeform patch fitting, without a search for primitives	The existing behaviour
Keep as facets	None	Kept as exact triangles
Unknown or unlabelled	None	Unaided detection inside that area

Map each hardpoint to the nearest mesh vertex within tolerance, and split border curves there, so a line running into an arc is fitted as a line and an arc.

The second cylinder check exists because the usual fit rejects shallow rounds, which it cannot tell from flat strips. A CAD label can.

8.5 Getting the labels out of CAD programs

	FreeCAD	Fusion
Mesh	One mesh of the whole shape with one segment per face: `MeshPart.meshFromShape(Shape, LinearDeflection, AngularDeflection, Relative=False, Segments=True)`	Each face meshed on its own through `face.meshManager.createMeshCalculator()`, with a surface tolerance (cm) and a maximum normal deviation (radians)
Triangle to face	Segment i is face i in explorer order (checked in FreeCAD's source)	Known by construction
Surface type	Class name of `face.Surface` (Plane, Cylinder, Sphere, Cone, Toroid; anything else freeform)	Last part of `face.geometry.objectType` (Plane, Cylinder, Sphere, Cone, Torus; anything else freeform)
Hardpoints	`shape.Vertexes`	`body.vertices`, each `.geometry`
Coordinates	mm; the object's global placement is applied	cm × 10; the body's own component coordinates
If something is off	Segment count differs from the face count: faces are still labelled, types are written as unknown	Per-face meshes don't close: mesh the whole body and give each triangle the face of the per-face triangle its middle point lies on

The whole-body fallback uses true point-to-triangle distance (nearest centre mislabelled about 1 %, section 4.2). It searches a uniform grid of cells, in growing shells, until the nearest triangle found is closer than the edge of the searched block.

FreeCAD's source shows that meshFromShape runs one incremental mesh over the whole shape, reads the triangulation back face by face in explorer order, flips reversed faces, and with Segments=True adds one segment per face. For Fusion, whether per-face meshes share identical points along a common edge is not stated in Autodesk's pages; the writer reports open and wrongly oriented edges and the add-in switches to the whole-body route when there are any.

8.6 Variations (disclosed; mostly untested)

Where the bits go

Use the reserved bits (5, 6 and 14) for: a "smooth border" flag for faces that meet tangentially, such as fillets; a body number for multi-body files; or a per-triangle "keep sharp normal" flag. Raise the version number.
Widen the face colour to 6 or 7 bits, or the surface type to 4 bits, by taking reserved bits. Use bit 15 only if no colour-convention viewer is a concern.
Flag edges (3 bits per triangle, one per side) instead of corners, to mark sharp or tangent edges.
Identify a face by a run of consecutive triangles in file order plus a run-length code in the attribute words, instead of by colour.

Carrying more than flags

Spread a small parameter record (a plane's normal and offset, a cylinder's axis, point and radius) across the attribute words of consecutive triangles of a face, 16 bits at a time, with the surface type saying how many triangles carry it. The reader must still verify it against the mesh.
Store a compressed STEP, IGES or other CAD file across the attribute words when it fits (section 4.3), with a header key saying so, and fall back to labels when it doesn't. The room is 2 bytes per triangle, so this suits fine meshes of simple parts least, and coarse meshes of complex parts least.
Store a second checksum over the attribute words, or a checksum of the labels only, so a program that edits colours but not geometry can be told apart.

Header

Further key=value fields: part name, source file name, body count, a flag that hardpoints include two-face vertices, a creation date. Readers ignore keys they don't know.
Another checksum (CRC-64, SHA-256 truncated) in place of CRC-32; hash the attribute words too.
A marker after the 80-byte header, such as a first record whose attribute word is the format marker, for programs that rewrite headers.

Writers

Any program that knows the CAD faces and can mesh them: CadQuery, build123d, Onshape, SolidWorks, Blender (from face groups), OpenSCAD (from its own object tree).
A STEP-to-hardpoint-STL command: mesh a STEP file with OpenCASCADE and read the triangulation back face by face. No CAD plug-in needed.
A converter that, after fitting a mesh, writes the labels back into the input's attribute words, copying the triangles byte for byte. (I built this; after converting, the labelled copy converted again to the same result. 12 faces on a bracket, 136 on an organic part.)

Readers

A viewer that colours a file by face or surface type, or checks a file against the format.
A slicer that uses the faces, for example to give round holes different perimeter settings from flat walls.
Tools that strip the labels (hstl.py strip writes a plain STL with identical triangles).

Other carriers (untested)

Per-face groups in OBJ or PLY, or per-triangle properties in 3MF, to carry the same facts. Those formats can hold groups natively; the point of this paper's method is that an unmodified STL carries them.

8.7 The reference implementation

hstl.py (about 600 lines, standard library only): pack_word, unpack_word, make_header, parse_header, geometry_crc, read, decode, colour, encode, write, transfer_faces, describe, verify, strip. Command line: python hstl.py info|verify part.stl, python hstl.py strip part.stl plain.stl.
FreeCAD workbench (HardpointSTL): hardpoint_fc.py (export logic, no GUI code) and hardpoint_stl_fc.py (the command and dialog).
Fusion add-in (HardpointSTL): hardpoint_fusion.py (no adsk imports) and HardpointSTL.py (the command).
Tests, examples and illustration scripts as in section 12.

Appendix A shows a real header and records.

9. What I'd test next (feel free to use this plan)

Slicers. Load bracket_hardpoint.stl and bracket_plain.stl into Cura, PrusaSlicer, OrcaSlicer and Bambu Studio and compare the sliced G-code. If they differ, the format has failed requirement 2 and I want to know.
FreeCAD. Run tests/freecad_selfcheck.py in FreeCAD (0.21, 1.0, 1.1) and send the output. Then export a part you actually modelled.
Fusion. Run Export hardpoint STL and note whether it took the per-face or the whole-body route.
Real models. Export real parts from CAD and compare converter results with and without labels. All my test parts were built for the tests.
Colour-aware viewers. Open a labelled file in a viewer that shows per-triangle STL colours and see whether faces get tinted.
Cone and torus. A converter that builds cone and torus faces from the labels should turn countersinks and rounded edges into one exact face each.
Big meshes. Time the writer on a 500,000-triangle export on a low-end machine, and write a native version only if it is slow.

10. Working together

Nothing here came from one person working alone:

The readers I could study: OrcaSlicer's admesh code, Uranium's STL reader and trimesh are all public, and I could read them. The person who reported OrcaSlicer issue 15993 handed me the reason bit 7 is in the format.
The colour conventions of VisCAM, SolidView and Materialise Magics decided what bit 15 must not be.
The CAD programs' own source and documentation: FreeCAD is open source and its mesher is readable. Autodesk's API pages told me what Fusion would do, and where they stay quiet.
Earlier mesh-to-STEP tools: stlToSolid and breptile showed what is possible without any hints.
What I added: putting these pieces together, building the exporters, measuring the result, and writing down every way it went wrong.

Collaboration in the open does three things a patent never will:

It's faster. One person's dead end saves everyone else the trip. Checking whether a STEP file would fit cost me an afternoon of measuring. With this paper it costs you a table.
It keeps the idea free. A published idea counts as prior art. The more of us write down what we try, with dates and enough detail to rebuild it, the harder it is for anyone to claim what hobbyists worked out together.
It gives better answers. I only tested three parts. More people exporting, converting and comparing results will tell us far more.

An open invitation:

Run the checks in section 9 and post your results, good or bad, as an issue or discussion on the repository. Photos of broken meshes are especially welcome. Failure is data.
Write an exporter for the CAD program you use. hstl.encode takes triangles, a face number per triangle, a type per face and a list of CAD vertices.
Write a reader, or make a converter that uses the labels better than mine does.
Write up your own experiments the same way: dated, public, enough detail to rebuild them. Link back here and I'll link to you.

Everyone who contributes gets credited in the next version.

11. How this was made

My part:

the idea, the six requirements in section 1.2 and the rule that a labelled file must stay a normal STL;
the instruction to research first, and the question about hiding a STEP file;
deciding what to publish, and when.

The AI assistant's part (working to that design):

the research into how readers behave, the format design, the code, the tests, the measurements and the drawings;
the first draft of this write-up;
its share of the mistakes (1 to 6 in section 4.2).

Every measurement in this paper was made by running the code in this repository, or the converter named in section 6, on a Linux cloud machine between 4 and 10 October 2026. None was made on real FreeCAD, Fusion or slicer software.

12. Code, data and how to reproduce

Two repositories:

This paper: a-point-of-contention. Its front page is this paper, generated from paper/paper.md. It also holds the reference reader and writer (code/hstl.py, Python 3, standard library only), the four example files (data/: two parts, each as a hardpoint STL and as a plain STL with the same triangles), the full research notes (notes/DESIGN_NOTES.md) and the specification (notes/HARDPOINT_STL.md).
The program: hardpoint-stl. The FreeCAD workbench and Fusion add-in (plugins/), the installers, the tests (test_hstl.py and test_install.py use the standard library only; test_hardpoint_cad.py needs cadquery-ocp, numpy, trimesh, and optionally numpy-stl; freecad_selfcheck.py runs inside real FreeCAD) and the scripts that regenerate the example files and drawings (tools/make_examples.py, tools/make_illustrations.py).
Not included in either: the converter I measured with. The numbers in section 6 can't be re-run from these repositories. The format checks, round trips and loader checks can.

13. Licence, and keeping it free

Text and figures: Creative Commons Attribution-ShareAlike 4.0. Anyone may copy, share and adapt it. Adapted versions must credit this paper and stay under the same licence.
Code: PolyForm Noncommercial 1.0.0. Free for non-commercial use. It is source-available, not open source.
The methods: dedicated to the public (section 8). A licence on text or code can't stop anyone using a method, and I don't want it to. The point of publishing is that the format stays free for everyone to implement, including commercially, in their own code: from today's date this paper is a dated public description of it.

14. Disclaimers

Untested in the real programs. Nothing here was run in real FreeCAD, Fusion or a slicer. Statements about what those programs do come from their source code or documentation, as cited, and may be wrong.
Measurements. The results in section 6 come from three test parts built for the tests and one converter. They are not a general claim about the format or about anyone else's converter.
Prior art. My search for earlier work was informal (section 2). Nothing here is a statement that the idea is new, or about the validity of anyone's rights, and nothing here is legal advice. Whether and how a defensive publication counts as prior art is a question for a patent attorney.
Other people's work. Product, company and file-format names belong to their owners and are used only to identify them. This project is not affiliated with any of them.
Your files. The exporters write a new file where you choose and don't change your CAD document. A hardpoint STL is meant to be an ordinary STL; if you find one that isn't, please say so before you print it.

15. How to cite

Armstrong, M. (2026). A POINT of contention: STL to STEP conversion shouldn't be that HARD. A proposed hybrid STL format that is CAD-friendly and slicer-compatible. A hobbyist's field notes on the hardpoint STL, including a defensive publication of the format. Version 1.0, 15 October 2026. https://github.com/The-Dorkknight/a-point-of-contention

References

OrcaSlicer, deps_src/admesh/stlinit.cpp (binary or text test, count from file size). https://raw.githubusercontent.com/OrcaSlicer/OrcaSlicer/main/deps_src/admesh/stlinit.cpp
OrcaSlicer issue 15993, small binary STLs imported as empty objects. https://github.com/OrcaSlicer/OrcaSlicer/issues/15993
Ultimaker Uranium, STLReader.py (Cura loads STL through numpy-stl). https://raw.githubusercontent.com/Ultimaker/Uranium/main/plugins/FileHandlers/STLReader/STLReader.py
trimesh, exchange/stl.py (exact-length check, attribute field kept). https://raw.githubusercontent.com/mikedh/trimesh/main/trimesh/exchange/stl.py
STL (file format), Wikipedia: binary layout, the solid rule, the two colour conventions. https://en.wikipedia.org/wiki/STL_(file_format)
FreeCAD source: src/Mod/MeshPart/App/Mesher.cpp, AppMeshPartPy.cpp; src/Mod/Part/App/TopoShape.cpp, BRepMesh.cpp, Tools.cpp; src/Mod/Mesh/App/Mesh.pyi. https://github.com/FreeCAD/FreeCAD
Autodesk Fusion API: TriangleMeshCalculator, TriangleMesh, BRepFace, BRepBody, FileDialog, selection filters.
Autodesk forum, "How can I capture facets from a surface using the API" (per-face meshing example; silent on whether neighbouring faces line up). https://forums.autodesk.com/t5/fusion-api-and-scripts-forum/how-can-i-capture-facets-from-a-surfaces-using-the-api/td-p/7070657
stlToSolid, mesh to STEP by segmentation and primitive fitting. https://github.com/Crypto69/stlToSolid
breptile, mesh to STEP. https://pypi.org/project/breptile/0.1.0/
numpy-stl. https://github.com/WoLpH/numpy-stl · trimesh. https://github.com/mikedh/trimesh · cadquery-ocp (OpenCASCADE 8.0.1). https://github.com/CadQuery/OCP

Pages and source files opened between 3 and 10 October 2026.

Appendix A: a real hardpoint STL

From examples/bracket_hardpoint.stl (59,084 bytes = 84 + 50 × 1,180).

The header, as written (80 bytes, padded with spaces):

HARDPOINT-STL 1 u=mm tol=0.05 ang=15 crc=e67609a0 by=cad-example

The first triangle's 50-byte record, in hexadecimal:

00 00 80 bf  00 00 00 00  00 00 00 00        normal  (-1, 0, 0)
00 00 f0 c1  00 00 80 c1  00 00 20 41        corner 1 (-30, -16, 10)
00 00 f0 c1  00 00 80 41  00 00 00 00        corner 2 (-30,  16,  0)
00 00 f0 c1  00 00 80 c1  00 00 00 00        corner 3 (-30, -16,  0)
80 39                                         attribute word 0x3980

Reading the attribute word 0x3980 = 0011 1001 1000 0000:

Bits	Value	Meaning
0–4	0	face colour 0
7	1	labelled
8–10	1	surface type 1: plane
11–13	7 (all three set)	all three corners are CAD vertices
15	0	as required

python src/hstl.py info examples/bracket_hardpoint.stl prints:

hardpoint STL version 1, 1180 triangles, units mm, written by cad-example
  16 faces (1 cone, 8 cylinder, 7 plane), 25 hardpoints
  meshed to 0.05 mm, 15 degrees

and python src/hstl.py verify examples/bracket_hardpoint.stl ends with RESULT: PASS.

About this repository

Path	What
`paper/paper.md`	The paper (this page is generated from it)
`paper/a-point-of-contention-v1.0.pdf`	The paper as a PDF
`paper/figures/`	Figures
`code/hstl.py`	Reference reader and writer (Python, standard library only)
`data/`	Example files, each as a hardpoint STL and a plain STL with the same triangles
`notes/`	The full research notes, the format specification, and how to archive this paper as prior art
`tools/` · `tests/`	Rebuild the PDF, web page and README; checks
`docs/`	The web version for GitHub Pages

The FreeCAD workbench and Fusion add-in live in the separate
hardpoint-stl repository.

To rebuild: python3 tools/build_paper.py (pandoc and Chromium), then python3 tools/make_readme.py.
GitHub's Cite this repository button uses CITATION.cff.

Join in: run the checks in section 9 and post results with photos as an issue or discussion, write an exporter
for another CAD program, make a converter that uses the labels better, or point out prior art I missed.
Everyone who contributes gets credited in the next version.

Licence: paper text and figures CC BY-SA 4.0; code in code/ and tools/
PolyForm Noncommercial 1.0.0 (source-available, not open source); the methods described are
dedicated to the public as a defensive publication. Not legal advice.

Fin-ally Supported

Matthew Armstrong — Tue, 20 Oct 2026 13:52:44 +0000

Shark-fin supports for long, flat, tilted overhangs: a hobbyist's field guide and a defensive publication

Matthew Armstrong (@The-Dorkknight)\
Version 1.0 · First published 19 October 2026 · Text and figures: CC BY-SA 4.0 · Code: PolyForm Noncommercial 1.0.0\
Repository: https://github.com/The-Dorkknight/fin-ally-supported · Software: https://github.com/The-Dorkknight/cura-shark-support

📄 PDF · 🌐 Web page · 🔧 The plugin · About this repository

This page is the full paper (the same text and figures as the PDF).

Contents: Why this paper exists · The problem · What already exists · Shark fins in one page · The method in detail · How it got here: the mistakes, in order · Numbers · Defensive disclosure: the method and its variations · Test plan (please print this) · Limitations and open questions · Fin-ally, a social species · Code, data and how to reproduce · How this was made · Licence, and keeping it free · Disclaimers · How to cite · References

Read this first. Every number in this paper comes from geometry code, slicer estimates or G-code. Nothing
has been printed and broken yet. Where a result is a slicer estimate or a simulation it says so. Section 8 is a
test plan for anyone with a printer and a free evening.

Abstract

Printing a long box tilted onto one of its long edges makes its walls strong along their length, but turns its base
into a long, flat overhang at 30–55°. That is near, or just past, the angle where slicers start adding support, and over 150 mm it tends to sag and
curl.
Normal slicer supports fix it by filling the space under the whole face with a forest that welds itself to the
part. This paper describes shark-fin supports: a row of thin vertical plates that run downhill under the face,
follow its slope, touch it only at small teeth, stop short of the top with a blunt flat tip, and stand on a crossbar
foot and a one-layer brim pad. They are cheap (on the test box, 1.68 m of filament and about 40 minutes for five
fins, slicer estimate) and should come off in one piece each. The method is implemented as an open Cura plugin with a
toolbar button that lets you click the face you want supported. Section 7 is a defensive disclosure: the method
and a long list of variations are published as prior art, to make it much harder for anyone to patent them and
charge hobbyists for them. They are dedicated to the public.

0. Why this paper exists

To keep it free. A published method is prior art, which makes it much harder for anyone to get a valid patent on it later. This paper puts the shark fin, its teeth, its blunt top, its feet and its many cousins on the public record with a date, so that a company filing on them later has this to get past first.
To write down the dead ends. Every version so far had a mistake in it that looked like a good idea at the time. Section 5 lists them, so nobody has to make them twice.
To bring makers together. A plugin is a tool; a paper is an invitation. Print the test plan, post the results, fork the code, prove me wrong. Everyone who contributes gets credit in the next version.
Selfish reasons. Publishing things like this tends to bring more interesting 3D printing tools and tricks back to me. It also makes me roughly 0.3 % more employable per paper, which, compounded over a few more papers, is a very efficient use of an evening.

1. The problem

1.1 Tilting for strength

FDM parts are weakest between layers. A long box printed flat is strong along its length only in the layers
themselves; printed on its end it is strong in the wrong direction and wobbly. A common compromise is to stand
the box on one long edge and tilt it, so the long walls run along the layers and the base and one side become
sloping faces (Figure 1).

Figure 1. The 35° test box (grey, see-through) and its fins (orange).

The test part used throughout is a 150 × 40 × 25 mm box rotated 35° about one long bottom edge, so its base
becomes a 55° overhang (in Cura's convention: 0° is a vertical wall, 90° a flat ceiling). It is deliberately
boring. Boring parts make honest tests.

1.2 Why "it's under the angle" is not enough

Slicers and rules of thumb treat overhangs up to about 45–55° as printable without support. That is true for a short
ledge. Over a long face several things add up:

each layer's edge sticks out a little further than the one below, and a long free edge cools unevenly and curls upwards, which the nozzle then hits;
the lowest part of the face is printed first and has nothing above it to hold it flat;
a long, thin, freshly printed edge sags under its own weight and the drag of the nozzle.

The usual result is a wavy, curled base, or a print knocked loose halfway through.

1.3 What slicers offer

Turning on normal supports fills the space under the whole base with support. It works, but it uses a lot of
plastic and time, it bonds along every layer of the face, and on a tilted part it leaves a large scarred surface.
Tree supports use less material but branch to many contact points and can be awkward to remove from a long flat
face. Neither knows that this particular overhang only needs a few stiff ribs to stop it curling.

2. What already exists

This section is an informal prior-art search, not a professional one. It is here to give credit and to be clear
about what is new.

Slicer supports. Cura, PrusaSlicer and OrcaSlicer offer grid/line supports, tree or "organic" supports, support blockers and enforcers, painted supports, and "support meshes": any shape the user loads can be marked to print as support (Prusa Knowledge Base; Printago guide).
Hand-drawn sacrificial ribs. Designers have long added thin ribs to a model in CAD to hold up an overhang and snapped them off afterwards (Hubs overview of supports). That is the same idea as a fin, made by hand, usually as a plain plate that bonds along its full edge.
Ribbed support vaults (Tricard, Claux and Lefebvre, Computer Graphics Forum, 2019) grow rib-like internal walls inside hollowed FFF prints to hold up internal overhangs (project page). They are walls that support from below, but inside the object and merging into it.
Teeth on metal supports. In metal powder-bed printing, block supports often meet the part through small teeth, whose size, shape and penetration affect the strength of the support (Materialise). The fins' teeth borrow from that habit.
US 9,469,057 (3D Systems, priority 2012). Claims a method of printing an FFF support whose upper portion contacts the part at discrete "fine points", with a retract, lift, move, lower sequence between them (Justia; Google Patents, which lists it as active until about 2034). Worth knowing: in the top layers of a fin, each tooth tip is a small separate island in the slice, and slicers usually retract and travel (and may lift) between islands. How this patent relates to Shark Support has not been assessed. If it matters to you, ask a patent professional; nothing here is legal advice.

As far as this search found, nobody describes downhill fins generated automatically under a flat tilted face,
contacting through teeth, cut short with a blunt top, braced by a crossbar foot and brim pad, with a click-to-pick
face selection. If you know of earlier work, please open an issue: the next version will credit it.

3. Shark fins in one page

For each flat face that faces downwards:

Downhill. Work out the direction a ball would roll down the face, flattened onto the bed. Fins run that way, spaced evenly across the face (30 mm by default, 4 mm in from the sides). Figure 2.
Measure. Along each fin line, cast vertical rays up from the bed every 0.5 mm to find the part's underside.
Shape each fin as a thin vertical plate (2.4 mm thick at the bed, 1.2 mm at the top) whose top edge sits 1 mm under the part, with teeth every 3 mm that reach up to 0.15 mm short of it. The first two teeth from the low end reach 0.1 mm into the part, so the start of the overhang, where curling begins, is anchored.
Stop early. The fin follows the part only to 85 % of its height; the part bridges the rest. The fin ends in a 5 mm flat top, then goes straight down.
Stand it up with a 4 mm high crossbar foot under the tip and a 4 mm wide, one-layer brim pad.
Print it as a solid little part next to the model, not as Cura "support".

Figure 10. One fin of the test box, side view, drawn from the code's output and labelled.

4. The method in detail

This section is written so that someone could rebuild the method from it.

4.1 Finding the face

Automatic mode. Triangles of the model that face downwards are grouped into flat faces: two triangles join when
they share an edge and their normals differ by less than 3°. A face qualifies when its overhang angle α (the angle
between its outward normal and the horizontal, so 0° is a wall and 90° a ceiling) lies between 20° and 70°, its area
is at least 300 mm², and it spans at least 15 mm downhill, measured in plan.

Picked mode. The user clicks the face. The slicer reports the 3D point under the mouse (in Cura, its picking
render pass). The plugin finds the triangle that contains the point (the projection of the point lies inside the
triangle within a small tolerance, and the point is within 1 mm, or 1 % of the model size, of its plane), checks
that it faces downwards and is not a flat ceiling, and uses the flat face that triangle belongs to. A picked face
ignores the automatic angle and size limits: the user has said it needs help.

4.2 Direction and layout

For a face with unit normal n, gravity g = (0, 0, −1) projected into the face's plane is
d = g − (g·n)n, the steepest descent. Its horizontal part, normalised, is the downhill direction
h; c = ẑ × h is across. Projecting the face's corners onto c gives its width; fins sit at
evenly spaced positions across it, a side margin from each edge, at most a set spacing apart (one fin in the middle
if the face is narrow). A flat ceiling has no downhill and is skipped.

4.3 Measuring the underside

Along each fin line, at steps of 0.5 mm in h, a vertical ray goes up from the bed. For a closed mesh the first
surface a ray meets from below always faces downwards, so only downward triangles are indexed, in a uniform grid in
plan. Each hit gives the height of the part above the bed and which triangle was hit. The fin keeps the longest
continuous run of samples that hit its own face and are at least the start height (4 mm) above the bed, so it
never climbs onto a neighbouring face or across a gap. Below the start height the face is short enough to print on
its own.

4.4 The top edge: relief, teeth and anchors

Let s run along the fin from its low end s₀, and z(s) be the underside height. The fin's top edge is
z(s) − relief (1 mm). Teeth are placed from the low end: the first tooth's ramp starts at s₀, then one every
pitch (3 mm), and a last one near the end. Each tooth ramps up over 1 mm, stays flat for 0.6 mm, and ramps down.
At its flat top it reaches z(s) − gap (0.15 mm) or, for the first N anchor teeth (2), z(s) + overlap
(0.1 mm, half of a 0.2 mm layer). The anchors therefore print touching the part's outer wall in the same layers
(Figure 6); the other tips stop just short.

Why teeth and not a plain edge: a plain edge 0.15 mm under a sloping face touches it along every layer. Teeth turn
that into a dotted line, so the fin snaps off with a short pull and leaves small, evenly spaced marks.

4.5 Stopping short, with a blunt top

The fin follows the part only up to a height z_cut = (1 − top cut) × the highest edge height it would otherwise
reach (top cut 15 %, so 85 %). Teeth near the cut are flattened to z_cut so nothing pokes above it. From there the
fin runs flat for 5 mm (tip length), then ends.

Why: a sharp tip means the last layers of the fin are a few millimetres long or less. The printer brakes and
accelerates for each tiny move, which is slow and prints badly. With a 5 mm flat top, no layer of the fin is shorter
than 5 mm. And the top 15 % of a long tilted face is the part closest to its own upper edge, which is already held
by the rest of the box.

4.6 The back edge

By default the fin goes straight down from the end of the flat top. Variants (Figure 9) lean the back out at a
set angle (20° from vertical) for a wider base, or make it round (a quarter ellipse) or concave. Each point of the
back is checked against the part above it and lowered if needed, and the back never goes below a 0.6 mm stub.

4.7 Thickness

The fin is a "ribbon" of columns along s. Each column has a bottom width (2.4 mm), a top width that tapers linearly
with height from 2.4 to 1.2 mm, and a top height. Neighbouring columns are joined into a closed, outward-facing
mesh. Thicker at the bed, where bending is worst; thin at the top, where the teeth are.

4.8 Crossbar foot

A bar across the fin, 2 mm thick and 4 mm high, its length ¼ of the fin's footprint (at least 10 mm), under the
middle of the flat top, where the fin is tallest. Fins with a footprint over 100 mm get a second bar halfway
between the low end and the 85 % cut.
A bar is lowered if the part comes within the relief above it, and skipped if that leaves less than 1.5 mm.

4.9 Brim pad

A rectangle one first layer thick, 4 mm wider than the fin on every side, plus one around each crossbar. Where the
part itself comes close to the bed at the low end, the pad is trimmed until the part is at least 1 mm above it, so
it never welds to the part's own edge.

4.10 Solid part, not "support"

Cura can print any mesh as support, but its support settings are global: density, walls and pattern cannot be set
per object, so a 1.2 mm fin printed as support would come out as a few sparse lines. And in the Cura releases
checked, the setting called "support brim" prints a brim inside support areas, not around them. So by default the
fins are a separate ordinary object with three per-object settings: infill 100 %, support off, and "union
overlapping volumes" on, so a fin, its crossbar and its pad print as one piece. The gaps between fin and part are
in the geometry itself. A "print as support mesh" switch is kept for comparison.

4.11 In the slicer

In Cura the method is a toolbar button under move, scale and rotate (Figure 7). Its panel has Pick face,
Auto, Remove all and Settings. Picking a face that already has fins replaces them; Auto replaces a model's
earlier fins. All of it is undoable. For other slicers a command line tool writes the fins as an STL to load next to
the part.

Figure 7. Cura (from source) with the Shark Support panel open: a mouse click on the underside, sent by the test
driver (xdotool, virtual display), made these fins.

Figure 8. The same box after Auto, from behind: five fins with their feet and pads.

4.12 All the numbers

Parameter	Default	Meaning
Overhang angle range (auto)	20–70°	Which faces Auto supports
Smallest face, shortest slope (auto)	300 mm², 15 mm	Faces smaller than this are left alone
Fin spacing, side margin	30 mm, 4 mm	Across the face
Start height	4 mm	Fins start where the face is this high
Thickness at bed / top	2.4 / 1.2 mm	Linear taper with height
Relief	1 mm	Gap under the part between teeth
Tooth pitch, tip, ramp	3, 0.6, 1 mm	Tooth shape
Tip gap	0.15 mm	Ordinary teeth stop this far under the part
Anchor teeth, overlap	2, 0.1 mm	First teeth from the low end reach into the part
Top cut	15 %	Fin stops at 85 % of its height
Tip length	5 mm	Flat blunt top
Back	vertical	Or leaning (20°), round, concave
Crossbar	¼ of footprint × 4 mm high × 2 mm	Under the tip; second one over 100 mm
Brim pad	4 mm wide, one first layer	Around fin and crossbar
Ray step	0.5 mm	Profile resolution

5. How it got here: the mistakes, in order

Most of the versions below were built, tested in code and looked at; two were design dead ends caught before the
first release. Each taught something.

Figure 3 is drawn with today's code and each version's settings, so tooth positions follow today's rule.

0.1.0: the actual shark. A round back edge, because it looked like a fin and seemed sturdier. It was neither: the crossbar already stops the fin tipping over, and the round back was a strip of plastic sticking out past the part. Measured later: 2.27 m of filament against 1.74 m without it (Figure 4).
0.1.0: teeth centred along the fin. The row of teeth was centred, so the first contact could sit up to 15 % of the way in, leaving the start of the overhang, where curling begins, unheld. Fixed in 0.1.1 by starting at the low end.
Before 0.1.0 (design): "support brim" is not a brim. The plan was to use Cura's support brim for the 4 mm pad. Reading Cura's settings showed it prints inside support, not around it. The pad became geometry.
Before 0.1.0 (design): fins as Cura support. Printed at the global support density, a fin is a few lines. Fins became solid objects (section 4.10).
0.1.1: the triangle. Straight back: 23 % less filament (27 % less fin volume). Still a sharp tip.
0.1.2: more teeth, two anchors. Pitch halved from 6 to 3 mm. The first two teeth reach 0.1 mm into the part; the rest stop 0.15 mm short (was 0.2). Almost free: 1.76 m instead of 1.74 m. With 3 mm pitch the valleys between teeth are only 0.4 mm long, so the top edge is effectively a saw blade. If it grips too hard, 4 mm pitch opens the valleys again.
0.2.0: the blunt top. Looking at a Cura preview made the problem obvious: the tip of a triangle is a column of tiny, slow layers. Cutting at 85 % with a 5 mm flat top fixed it and saved time: 1.68 m, about 40 minutes.
0.2.0: the leaning back, measured and demoted. The first sketch of the new shape had the back leaning out to the bed. Measured, it cost more than going straight down (1.97 m, about 42 minutes). It is now an option for when a wider base matters more than plastic.
Plugin plumbing, for other plugin authors:
- Uranium's signals hold weak references, so connecting a lambda silently does nothing. Connect a method.
- Cura caches "is this a support mesh" per object and only refreshes it when a setting change is announced; setting it directly leaves the cache stale.
- A plugin's first log lines can appear before Cura's log file is open; log again once the app has started.
- UM.Dialog takes only visual items as children: a Connections object in the wrong place makes the whole dialog fail to load.
- Toolbar icons are SVGs that Cura recolours by inserting a fill attribute into the <svg> tag. An icon that already has one there becomes invalid.

6. Numbers

All from PrusaSlicer 2.7.2's command line on the fins alone: 0.2 mm layers, 0.4 mm nozzle, two perimeters,
PrusaSlicer's default speeds. These are slicer estimates, not stopwatch times.

Version	Fins (5)	Filament	Time (estimate)	Volume (code)
0.1.0 round back	sharp, to the top	2.27 m	48 min	4.7 cm³
0.1.1 triangle	sharp, to the top	1.74 m	42 min	3.4 cm³
0.1.2 more teeth	sharp, to the top	1.76 m	43 min	3.5 cm³
0.2.0, leaning back	blunt, 85 %	1.97 m	42 min	4.0 cm³
0.2.0 default	blunt, 85 %	1.68 m	40 min	3.3 cm³

Volumes are without brim pads and crossbars; filament and time include them. The 0.1.0 and 0.1.1 volumes are
redrawn with today's code, so their tooth positions follow today's rule.

Does the slicer print what the code drew? Figure 5 plots every extrusion in the real G-code within 0.5 mm of the
middle fin. The fin is solid, follows the part with a stepped gap, stops below the top of the face with a flat top,
and goes straight down at the back. Figure 6 zooms in on the low end: the anchor teeth's lines run into the part's
outer wall, while further up there is a clear gap at every tooth.

Figure 5. Every extrusion in the PrusaSlicer 2.7.2 G-code within 0.5 mm of the middle fin, seen from the side.

Figure 6. The low end of the same fin, zoomed in.

Speed of the code. A 196,608-triangle version of the test box took about 2 s to process (1.6–2.3 s across
runs) on the development machine; the 12-triangle box takes 0.02 s. Not yet timed on a 7th-generation Core i3, which is the target for
everything in this project.

A box on its corner. Rolled a further 12° onto a corner, both faces next to the standing edge qualify, and the
same code makes ten fins; with the anchors switched off, the closest tooth is exactly 0.15 mm under the part
(Figure 11).

Figure 11. The box rolled 12° onto a corner: two faces, ten fins.

7. Defensive disclosure: the method and its variations

The following are disclosed as part of this publication, alone and in any combination, for FDM/FFF and for any
other layer-wise process where they make sense. They are dedicated to the public.

7.1 The core. A support structure for a downward-facing surface of an object being built layer by layer,
comprising one or more upright plates ("fins") generated from the object's geometry, each running substantially
along the downhill direction of the surface in plan, whose upper edge follows the surface at a clearance, with
contact features ("teeth") that approach or meet the surface at intervals, the plates standing on the build
surface, optionally braced by a foot and widened at the base by a pad.

7.2 Finding where fins go. Automatic detection of flat or near-flat downward faces by angle band, area and
reach; grouping by normal tolerance; user selection by clicking a point on the surface, by painting, by drawing a
line or region, or by selecting a face in CAD; selection of faces by curl risk (length of free edge, cooling time,
distance from the bed, material); faces of any size, including faces normally considered printable; curved or
faceted surfaces approximated piecewise; surfaces of multiple objects at once.

7.3 Layout. Fins along the downhill direction; at an angle to it; fanned from a point; in a grid or herringbone;
crossing pairs (X); spacing fixed, scaled with overhang length, with angle, with face width, with material, or set
so that the unsupported span between fins stays below a limit; denser near the low edge where curling starts;
offset between neighbouring faces; joined across faces into one structure.

7.4 Contact. Teeth of any profile (trapezoid, triangle, rounded, stepped); points, ridges, pins, cones, fingers;
teeth whose pitch varies along the fin (denser at the low end); anchor teeth that touch or overlap the part,
anywhere along the fin and in any number, with any overlap; teeth that stop short at a gap of any size, fixed or
proportional to the layer height; teeth printed with a different material, extruder, temperature, speed, flow or
cooling; teeth with a breakaway neck or perforation; teeth that touch only in alternate layers; an interface layer,
dissolvable or not, between teeth and part; contact made from the side rather than from below.

7.5 Profile. A top edge that follows the surface at a relief; fins that stop at any fraction of the surface's
height (the part bridging the rest), measured by height, by length along the slope or by the angle of the
remaining span; a blunt top of any length or a minimum layer length, so that no layer of the support is shorter
than a set length; a flat, rounded or stepped top; backs that are vertical, leaning at any angle, round, concave,
stepped, or shaped to the minimum stable footprint; fins that start at a set height or reach down to the bed edge.

7.6 Section and structure. Thickness constant, tapered, stepped or thickened at the base; solid, hollow,
double-walled, corrugated, perforated, lattice-filled or sparse-infilled fins; fins with stiffening ribs or a
flange along the top; fins printed as part of the model, as a separate object, as a slicer "support mesh", or
directly as toolpaths at G-code level.

7.7 Feet and pads. A crossbar of any length, height and position (under the tip, at the middle, at the low end,
several); T, X, H or gusset-shaped feet; triangular gussets between fin and bed; a pad of any width and thickness,
one or more layers, trimmed clear of the part, shared between neighbouring fins, or replaced by a raft or by mouse
ears; tie bars linking fins to each other above the bed.

7.8 Workflow. Generating fins in a slicer, a CAD program, a mesh editor, a plugin, a command line tool or a
web service; replacing earlier fins when the same face is picked again; regenerating fins when the object is moved;
removing all fins at once; previewing before adding; combining fins with tree or normal supports elsewhere on the
same part; automatically turning off the slicer's own supports under the faces that have fins.

8. Test plan (please print this)

Print the 35° test box (data/tilted_box_35deg.stl, 150 × 40 × 25 mm) four ways, same filament, same settings:

No support. Photograph the base, measure curl at the low edge and mid-face with a feeler gauge or a ruler on a flat surface.
Slicer supports (normal, then tree), touching build plate only.
Shark fins, defaults.
Shark fins, anchors off (Anchor teeth 0).

For each, record: filament and time (slicer estimate and real), whether it finished, curl or sag of the base,
time to remove the supports by hand, and the state of the base afterwards (photo). Then, if you are keen: tooth pitch
3 vs 4 vs 6 mm; top cut 0, 15 and 25 %; a 45° box. Post your results as a GitHub issue or discussion with photos.
Everyone who does gets credited in version 1.1.

10. Fin-ally, a social species

Infant sharks do, do, do support prints well.

(With apologies to a certain children's song, which is now going to be in your head until at least Thursday.)

The serious point behind the joke: this method grew one review at a time. A fin that looked right in a diagram
looked wrong in a slicer preview; a "more efficient" back edge turned out to cost more when measured. Each change
came from someone looking at the output and saying "that bit's daft". The fastest way to find the next daft bit is
more people looking. Print it, break it, measure it, and tell the rest of us. Makers, like fins, are stronger when
they are spaced sensibly and braced against each other.

11. Code, data and how to reproduce

The plugin (Cura toolbar tool, menu, installer, command line tool, 22 geometry tests): https://github.com/The-Dorkknight/cura-shark-support, version 0.2.1-wip (fin shapes as in 0.2.0).
In this repository: code/shark_core.py (the geometry, numpy only), data/ (the test boxes and their fins as STL), tools/make_figures.py (redraws Figures 1–4 and 9–11 from the code), tools/gcode_side_view.py (draws Figures 5–6 from any G-code), tools/build_paper.py (builds the web page and PDF).
Figures 5 and 6: PrusaSlicer 2.7.2, --layer-height 0.2 --first-layer-height 0.2 --nozzle-diameter 0.4 --perimeters 2 --fill-density 15%, the box and its fins merged. Figures 7 and 8: Cura from source, run by the plugin's own test driver under a virtual display.

12. How this was made

The geometry code, plugin, tests, measurements and literature search were done with an AI assistant (Claude,
by Anthropic) working to my design intent, reviewed and steered by me at each step: the shark fin, the point
contacts, the 4 mm brim, the crossbar, the triangle, the anchors, the blunt top and the toolbar button were all my
calls; the assistant did the typing, the maths and the measuring, and owned up to its own mistakes listed in
section 5. I think saying so plainly makes the work more trustworthy, not less.

13. Licence, and keeping it free

Text and figures: CC BY-SA 4.0. Share and adapt, credit me, keep it under the same licence.
Code: PolyForm Noncommercial 1.0.0 (LICENSE-CODE.md). Free for hobbyists; commercial use needs permission.
The methods in sections 3, 4 and 7 are dedicated to the public. This paper is a defensive publication: its purpose is to be prior art, to make it much harder for anyone to patent these methods and restrict their use.

14. Disclaimers

Not legal advice: what counts as prior art, and whether something infringes a patent, is decided by patent offices
and courts. Not engineering certification: printed supports can fail, and parts can detach from the bed. Use at
your own risk. Not affiliated with UltiMaker, Prusa Research, 3D Systems, Materialise or anyone else named here.

15. How to cite

Armstrong, M. (2026). Fin-ally Supported: Shark-fin supports for long, flat, tilted overhangs. A hobbyist's field
guide and a defensive publication. Version 1.0, first published 19 October 2026.
https://github.com/The-Dorkknight/fin-ally-supported

References

Prusa Research, "Support material", Prusa Knowledge Base. https://help.prusa3d.com/en/article/support-material_1698/
Printago, "How to Add Supports in PrusaSlicer (Including Organic and Custom)". https://printago.io/guides/prusaslicer-supports
Hubs, "Supports in 3D printing: a technology overview". https://www.hubs.com/knowledge-base/supports-3d-printing-technology-overview
T. Tricard, F. Claux, S. Lefebvre, "Ribbed Support Vaults for 3D Printing of Hollowed Objects", Computer Graphics Forum, 2019. https://www.unilim.fr/pages_perso/frederic.claux/blog/2019/2019-06-21_Ribbed_support_vaults.html
Materialise, "How to create optimal support structures for metal 3D printing". https://www.materialise.com/en/inspiration/articles/optimal-metal-supports
3D Systems, Inc., US 9,469,057 B2, "Support structures and deposition techniques for 3D printing", filed 17 May 2013, issued 18 October 2016. https://patents.justia.com/patent/9469057
Google Patents entry for US9469057B2 (status as listed on 19 October 2026). https://patents.google.com/patent/US9469057B2/en
Software: The-Dorkknight/cura-shark-support, version 0.2.1-wip. https://github.com/The-Dorkknight/cura-shark-support

About this repository

Path	What
`paper/paper.md`	The paper (this page is generated from it)
`paper/fin-ally-supported-v1.0.pdf`	The paper as a PDF
`paper/figures/`	All figures
`code/shark_core.py`	The fin geometry (Python, numpy only), as used by the plugin 0.2.0 and 0.2.1-wip
`data/`	The test boxes and their fins as STL
`tools/`	Redraw the figures (`make_figures.py`), plot G-code (`gcode_side_view.py`), build the PDF and web page (`build_paper.py`), write this page (`make_readme.py`)
`docs/`	The web version for GitHub Pages

To rebuild everything: python3 tools/make_figures.py (numpy, matplotlib, Pillow), then
python3 tools/build_paper.py (pandoc, Chromium), then python3 tools/make_readme.py.

GitHub's Cite this repository button uses CITATION.cff.

Join in: print the test plan (section 8), post results with photos as an issue or discussion, fork it, port it to
another slicer, or point out prior art I missed. Everyone who contributes gets credited in the next version.

Shark Support for UltiMaker Cura

Matthew Armstrong — Tue, 20 Oct 2026 13:42:30 +0000

WORK IN PROGRESS: MANY FEATURES MAY BE BROKEN (proof of concept, 0.2.1-wip)

Source-available · Non-commercial. Copyright Matthew Armstrong. Licensed under the
PolyForm Noncommercial License 1.0.0. No warranty, no liability: use at your own risk.

Shark Support adds thin shark-fin supports under big, flat, tilted faces. The typical case: you print a long
box tilted onto one long edge so it is strong along its length. Its base becomes a long 30–55° overhang that is
fine in theory but sags or curls over that length. Shark Support puts a row of fins under it:

each fin is a thin vertical plate that follows the slope of the part, stops at 85 % of its height (the part bridges the last bit), has a blunt 5 mm flat top (no tiny, slow top layers) and a straight back down to the bed
it only touches the part at small teeth, a dotted line of points every 3 mm that snaps off cleanly, starting right at the fin's low end. The first two teeth really touch (0.1 mm into the part) to hold the start of the overhang; the rest stop 0.15 mm short
a crossbar foot under the tip (¼ of the fin's length, 4 mm high) and a 4 mm one-layer brim pad keep tall fins standing
in Cura it is a button in the left toolbar: pick the face you want supported with the mouse, or press Auto for every big tilted flat face, and Remove all to clear them

Real screenshot: the plugin running inside Cura (5.15 development source, see Testing), with
fins under the 35° test box and the Shark Support panel open from its toolbar button.

Use it

Load your model and tilt it the way you will print it (Rotate tool, Lay flat, etc.).
Select it, then click the shark-fin button at the bottom of the left toolbar (under move, scale, rotate, mirror, per-model settings and support blocker). Its panel opens:

Pick face, then click the underside face that needs support. Fins appear under that one face. Pick more faces the same way; picking a face again replaces its fins (handy after changing settings). Press the button again to stop picking. Turn the view so you can see the underside (a low side view works).
Auto: fins under every big tilted flat face of the selected model(s), replacing their earlier fins.
Remove all: removes every Shark fin object.
Settings...: the numbers below.
1. A message says how many fins were made. New objects called Shark fins (your model...) appear.
2. Slice and print as usual. Normal support for that model is switched off (a per-model setting) so Cura does not add its own supports under the same face. You can change that in the settings.

The same actions are in the menu Extensions > Shark Support. If you move or rotate the model afterwards, use
Remove all and add the fins again: they are a separate object and do not follow the model.

Settings (Settings... in the panel, or Extensions > Shark Support > Settings...)

Setting	Default	What it does
Overhang angle from / to	20° / 70°	Auto puts fins under faces in this range (Cura's angles: 0° = wall, 90° = ceiling). A face you pick gets fins whatever its angle, as long as it faces down
Smallest face / Shortest slope	300 mm² / 15 mm	Auto leaves smaller faces alone (picked faces ignore this)
Fin spacing / Side margin	30 mm / 4 mm	Distance between fins across the face, and from its sides
Start height	4 mm	Fins start where the face is this high (low down it needs no help)
Thickness at bed / at top	2.4 / 1.2 mm	Fins taper; with a 0.4 mm nozzle that is 6 lines at the bed, 3 at the top
Gap between teeth	1 mm	The fin edge stays this far under the part except at the teeth
Tooth spacing / tip length	3 / 0.6 mm	The contact points. The first tooth starts at the fin's low end, the last sits at the tall end
Tip gap	0.15 mm	All teeth except the anchors stop this far under the part. Smaller = stronger contact, harder removal
Anchor teeth / overlap	2 / 0.1 mm	The first teeth from the low end reach this far into the part so they bond slightly and hold the start of the overhang. 0 turns it off
Top left free	15 %	The fin stops this far below the top of the face; the part bridges the rest. 0 runs it to the top
Blunt tip length	5 mm	The fin's flat top. No layer of the fin is shorter than this, so the printer never slows down for tiny top moves
Back lean	20°	Only with Lean the back out on
Crossbar length / height	0.25 × fin / 4 mm	The foot across the fin under its tip (a second one in the middle for fins over 100 mm)
Brim width / thickness	4 mm / first layer	One-layer pad around each fin and crossbar
Lean the back out to the bed	off	The back slopes out 20° instead of going straight down: wider base, but more plastic and time (test box: 1.97 m and 42 min instead of 1.68 m and 40 min). The command line also offers round and concave backs
Print fins as a Cura support mesh	off	Experimental: Cura then prints them with your support pattern and density

Extensions > Shark Support > Run self-check builds a test box in memory, runs the plugin's own code against it
(including face picking and the toolbar button),
and shows PASS/FAIL per check (also saved to shark_support_selfcheck.txt in your temp folder). Run it once after
installing.

Without Cura (PrusaSlicer, OrcaSlicer, anything)

The geometry code needs only numpy, so there is a command line tool:

python3 shark_cli.py part.stl                   # writes part_fins.stl
python3 shark_cli.py part.stl --spacing 25 --merged part_with_fins.stl
python3 shark_cli.py part.stl --back slope       # back leaning out instead of straight down
python3 shark_cli.py --help                     # every setting

The STL must already be oriented for printing (Z up, sitting on the bed). Import the fins STL as a second part at
the same position (PrusaSlicer: Add part; or slice the --merged file). The repository has examples in
examples/.

Real G-code: the merged test box sliced by PrusaSlicer 2.7.2 on the command line, showing every extrusion within
0.5 mm of the middle fin. The fin is solid, touches the part only at the teeth, stops below the top of the face
with a flat top, and goes straight down at the back.

What exists and what does not

Exists (0.2.1-wip)	Does not exist yet
Fins under flat tilted faces: picked with the mouse, or found automatically	Fins under curved or organic surfaces (it needs flat faces)
Fins cut at 85 %, blunt flat top, straight back, teeth every 3 mm, 2 anchor teeth, crossbar, brim pad	Painting exactly where on a face fins go
Cura toolbar button with panel, menu, settings dialog, self-check, undo	Fins that follow the model when it is moved
Installer that checks Cura's log; `.curapackage`	Live preview while editing settings
Command line tool for any slicer	PrusaSlicer / OrcaSlicer plugin (they have no Python plugin API)
Experimental "Cura support mesh" mode	A real print test (see below)

What was tested

Be aware of exactly what has and has not been tried:

Geometry: 22 automatic tests (python3 tests/test_core.py): closed outward meshes, fins never reach into the part (only the anchor teeth reach in, exactly 0.1 mm; with anchors off every tip is 0.15 mm below it), boxes tilted 35° and 45°, turned on the bed, standing on a corner, the 85 % cut and 5 mm flat top, picking a face (and refusing a top face or a miss), triangle-soup input, spacing, long fins, no fins on a plain cube. A 196,000-triangle mesh took about 2 s on the development machine (not timed on a 7th-gen Core i3).
Inside Cura: Cura could not be downloaded in the build sandbox, so it was run from Cura's and Uranium's source (5.15 development branch, plugin SDK 8.13) under a virtual display, with stand-ins only for Cura's C++ parts. There the plugin loaded, its toolbar button appeared and opened its panel, a real mouse click (sent with xdotool) on the box's underside made fins for that face, picking it again replaced them, Auto replaced those with automatic fins with the right per-object settings, the menu and dialog opened, the self-check passed, support-mesh mode and Remove all fins worked, and Cura's package manager listed it as installed, both after the installer and after Cura's own .curapackage route. Slicing in Cura was not tested (the slicing engine is one of the C++ parts that could not run).
Slicing: the fins were sliced for real with PrusaSlicer 2.7.2 (command line), picture above. For the test box the fins take 1.68 m of filament and about 40 minutes on their own (PrusaSlicer defaults, 0.2 mm layers); the 0.1.2 fins, which ran to the top with a sharp tip, took 1.74 m and about 43 minutes. The zoom below shows the anchor teeth meeting the part's outer wall in the G-code while the other teeth leave a gap.

Not tested: a real print, Cura 5.0–5.10 releases (face picking uses a different path there, written to match Cura 5.0's own support blocker but not run), Windows and Mac (launchers and installer), Flatpak Cura.

Research paper

Fin-ally Supported: Shark-fin supports for long, flat, tilted overhangs (version 1.0, first
published 19 October 2026) · PDF

Everything behind this plugin written up: the problem, what already exists (including a live patent on "fine point"
supports and how this differs), the method in enough detail to rebuild it, every mistake made on the way, the
numbers, a test plan, and a defensive disclosure of the method and its variations, dedicated to the public so
nobody can patent them. It is published on its own at
The-Dorkknight/fin-ally-supported; paper/ is a copy that
travels with the plugin. Text and figures: CC BY-SA 4.0. Infant sharks do, do, do support prints well.

How to cite: Armstrong, M. (2026). Fin-ally Supported: Shark-fin supports for long, flat, tilted overhangs. A
hobbyist's field guide and a defensive publication. Version 1.0, 19 October 2026.
https://github.com/The-Dorkknight/fin-ally-supported

HOW_IT_WORKS.md: what the plugin reads, changes and never touches
DESIGN_NOTES.md: research notes, decisions, measurements, ideas
paper/: the research paper (Markdown and PDF)
CHANGELOG.md · CONTRIBUTING.md · SECURITY.md · THIRD_PARTY.md

Not affiliated with or endorsed by UltiMaker. "Cura" and "UltiMaker" are names of their owners.

Source code: The-Dorkknight/cura-shark-support on GitHub

FREE (open) Lizard Scanner

Matthew Armstrong — Mon, 19 Oct 2026 20:45:24 +0000

Paused for a month or two. Calibration turned out to be more boring than cleaning, and after weeks of
mad science projects the cleaning has been neglected for long enough. The app works as far as described
below; the notes say exactly where it stopped. Issues and ideas are still welcome.

The paper: Down the Lizard Hole, the whole reverse-engineering
story in plain English (also in its own repository,
down-the-lizard-hole).

WORK IN PROGRESS: MANY FEATURES MAY BE BROKEN. Version 0.5.2-wip. Proof of concept.
The camera control, the light buttons and the diagnostics have run on the owner's real CR-Scan
Lizard. The first real wall test (0.4) failed because the projector throws stripes, not dots;
0.5 rebuilds depth for the stripes and was checked on that wall test's saved data and one saved
picture (walls back within 2 mm). The first live test (19 October) gave a flat wall where the
calibration was good, with wrong-stripe streaks that 0.5.1 removes; a second calibration did worse for
reasons not yet known. See the findings.

Licence: PolyForm Noncommercial 1.0.0. Source-available, non-commercial.
Free for personal and other non-commercial use; commercial use needs permission. No warranty
and no liability: it is provided as is. Not made by, or affiliated with, Creality.

A standalone app for the Creality CR-Scan Lizard 3D scanner that does not need Creality's
software: a live infrared picture, automagic buttons instead of sliders for the light, a
wall test that gives the scanner a rough depth calibration, a live depth view, point-cloud
export and recordings. It is built on the bones of
Scantastic and the Lizard engine from
Who are yoUSB?, and is laid out so the Lizard
can move into Scantastic later (INTEGRATION.md).

Screenshots are of the built-in simulated scanner, not a real Lizard.

What exists, and what does not

Works (on the simulated scanner)	Not yet
Finding the Lizard's two cameras (USB bcdc:000a / 000b) and starting them (Linux)	Tried on a real Lizard with this app
Live picture, "pattern only" view, camera A + B side by side	Full 3D scans (many views joined into a mesh): that is Scantastic's job, see INTEGRATION.md
AUTO-TUNE, three presets, Brighter / Dimmer, flash capped at 1 ms	Lens distortion correction
Diagnostics: 10 checks and a report zip
Wall test: rough depth calibration from 3 to 5 walls, saved as you go, all in one folder, one-click zip	Creality's own factory calibration (not found)
Live depth view, save points as .ply	Windows and macOS camera paths (written, never run)
Recording sessions and playing them back	Colour (the Lizard's pictures are infrared)
Light test, "What is camera B?" test

Using it

1. The picture

Plug the Lizard in. On Linux the picture starts by itself within a few seconds (the app
looks for it every 2.5 s). The green tag on the picture says how many pictures a second
arrive and how much of the view shows the projector's stripes. The projector (camera A's light)
flashes once per picture, so every picture carries its pattern; the red glow looks like flicker.

The View row switches between:

Picture: the infrared picture with the projector's stripes.
Pattern only: the stripes with the background light taken away. What the depth is made from.
Depth: needs a wall test first.
A + B: both cameras side by side.

2. The light: automagic buttons

Creality's own app only ever changes two settings, exposure and gain. Here they are a
ladder of 11 light levels instead of two sliders:

AUTO-TUNE walks the ladder until the stripes are bright but not blown out, from whatever is in front of the scanner. Press it again to stop.
Shiny / white, Normal, Dark / black: presets. Normal is what Creality's app uses (1 ms, gain 65); Shiny / white is its dimmest setting.
Dimmer / Brighter: one step of the ladder.

The ring's brightness is the flash length. The white ring is camera B's light, the infrared
projector camera A's. Both cameras start at Creality's 1 ms, never on their own automatic exposure,
and camera B follows these buttons whenever it runs. The ring and the projector flash for as
long as the camera exposes, and at Creality's 1 ms the ring is already very bright. So the
ladder never flashes longer than 1 ms; above that it adds gain (picture amplification), which
brightens the picture without touching the lights. The bar under the buttons shows the rungs.

Allow longer flashes: an advanced switch, with a warning, for dark objects. Brighter then goes up to 6 ms (the camera's own starting value, never more); those rungs show red. It switches itself off when the app closes.
Camera's own settings (long flashes): back to the camera's own automatic exposure. Only with longer flashes allowed, because the camera then picks its own (often long) flash.

Every raw setting is still there under Every camera setting (advanced); setting a flash longer
than 1 ms there asks first.

3. The wall test: rough depth calibration

The Lizard's camera A sees a fixed pattern from its projector: dense vertical stripes, each a string
of beads whose width wobbles. When the scanner moves closer to a wall, the stripes slide sideways in
the picture, by an amount that depends on the distance (and, on the real scanner, a little on where
in the picture). The beads' wobble tells one stripe from the next. Measure that slide at a few known
distances and every picture afterwards can be turned into depth. The original Kinect worked the same
way with dots.

You need a flat, plain, matt wall and a tape measure. About five minutes.

Press WALL TEST.
Point the scanner straight at the wall. Measure to the wall from one fixed point on the scanner (the front glass is easiest; any point works if you use the same one every time; depth is then counted from that point) and type the distance in millimetres.
Press RECORD THIS WALL and hold still for two seconds. (Before the first wall the app runs AUTO-TUNE by itself.)
Repeat at five distances: 18, 23, 28, 33 and 38 cm are suggested (Creality gives the Lizard's working range as 15 to 40 cm). Three is the least; spreading the walls over the whole range matters, because depth gets less certain beyond the nearest and farthest wall.
Nothing to press to save. Every wall is saved the moment it is recorded, and from the third wall on the calibration is fitted and saved by itself; the Depth view turns on. The list shows how well each wall fits, and the window warns about a wall at an angle (one that disagrees with the others is left out) or a scanner turned to the wall. FIT AND SAVE AGAIN is only needed after typing a picture width.

Everything for one scanner's calibration is in one folder, calibration/<serial>/: the fit
(calibration.json), the wall patterns and K map (reference.npz), the measured shift maps, the report,
and walls/ with three of the camera's own full-size pictures of each wall. ZIP CALIBRATION (in the
wall test, or Zip this scanner's calibration under Depth) packs it into one file next to it, with the
serial hidden when the Capture box says so. Load saved walls brings the walls back to fit again, also
from an older version of the app: a 0.4 calibration is refitted for the stripes without new walls.

Optional: tick I measured the picture's width and type how wide the picture is on the wall
at a known distance. Without it, the lens is guessed from Creality's spec (200 mm across),
which only affects sideways sizes in exported points, not depth.

4. Depth and points

The Depth view colours the scene green in the sweet spot (18 to 35 cm), through yellow to red
outside it, with shading so shapes show. Save this view as points (.ply) writes the current
depth as a point cloud in millimetres, which MeshLab, CloudCompare or Blender can open.

5. Capturing frames, recording and playing back

Every saved picture is stamped with when it arrived, which camera, the exposure, the gain, the
auto-exposure mode and every other camera setting in force, plus its brightness, fine detail, how much
of it shows the projector's pattern, its sharpness, the light-ladder rung and the stream's own picture
number. Every setting change (light buttons, AUTO-TUNE, tests) is logged as it happens, so pictures from
before and after a change never get mixed up.

Save frame now (Capture panel): one picture from each running camera.
RECORD: every picture from every running camera (camera B joins when the A + B view starts it). every saves only every Nth picture for long recordings.
Notes: type e.g. "covered camera A" and press Add note; it is stamped on the next picture and kept in the timeline. With nothing recording, it goes on the next capture.
Hide the scanner's serial (on by default) masks it in captures and in test reports.

Each capture is a folder captures/capture_<date>_<time>_<name>/: the camera's own JPEGs (no quality lost)
in frames/, frames.csv (one row per picture with all the stamps), events.jsonl (settings snapshots,
every change, notes) and session.json. Source > Play back a recording... plays one back as if it were
the scanner. The capture code is shared with Who are yoUSB? (lizard_framecap.py); see
docs/framecap-in-lizard-scanner.md.

6. Diagnostics

Diagnostics opens one window with every check. Point the scanner at a plain wall 20 to 30 cm
away and press RUN QUICK CHECKS (about 10 seconds):

Check	What it tells you
USB connection	Both cameras there, at USB 2 speed, on the right driver, not behind an extra hub (Linux)
Camera A video	Pictures a second, late pictures, whether the stripe pattern is in every picture (or the lights pulse), picture sizes
Video modes and settings	Every mode and setting both cameras offer (saved in the report)
Serial number	The scanner's serial, read the way Creality's app does
Projector and room light	How much of the view shows the stripe pattern, how strong it is, how much infrared is in the room (judged between the stripes; sunlight swamps them), anything blown out
Depth speed	How long one depth picture takes on this computer

and, one at a time:

Check	What it tells you
Sensor map	Runs camera A alone, B alone, then both, 3 s each; measures each camera's rate, stripe pattern, colour and pulse, and asks which light you saw each time. Answers "which camera does what"
What is camera B?	Streams camera B alone (at a 1 ms flash): colour or grey, does its light pulse. On the owner's Lizard it is the camera with the white ring
Flat wall check	After the wall test: how flat a wall comes out, how far away, and (with a tape-measured distance) how far off. Also spots lens bending at the edges. The best test of a calibration
Light test	Steps the flash from 0.1 ms to 1 ms while you watch the ring, then asks what you saw
Gain test	Holds the flash at 1 ms and steps the gain: if the ring changes, the firmware ties the LEDs to gain too

Save diagnostics report (.zip) puts the results, the settings dumps, sample pictures, the
calibration report and the light / gain test answers in one zip in reports/, with the serial
hidden if you like: ready to attach to a GitHub issue.

Looking for Creality's own calibration? See
docs/research/calibration-hunt.md and the read-only Windows
script tools/Find-CR-Scan-Calibration.bat (untested).

More screenshots



Scanner off: static until the Lizard is plugged in	Pattern only: what depth is made from

The plain look (`--plain`, or Look: Plain)

HOW_IT_WORKS.md: what the app reads, changes and never does; the maths.
DESIGN_NOTES.md: findings, decisions, measurements, what is untested, what next.
INTEGRATION.md: putting the Lizard into Scantastic.
docs/research: the USB research behind the camera control.
CHANGELOG.md, CONTRIBUTING.md, SECURITY.md, THIRD_PARTY.md.

Required Notice: Copyright Matthew Armstrong (https://github.com/The-Dorkknight)

Source code: The-Dorkknight/lizard-scanner on GitHub

SimpleCAD

Matthew Armstrong — Mon, 19 Oct 2026 20:33:23 +0000

Source-available · Non-commercial · Licensed under the PolyForm Noncommercial License 1.0.0 · Copyright Matthew Armstrong · No warranty, no liability: use at your own risk. Free for personal, hobby, study and other non-commercial use; commercial use needs my separate permission. Not legal advice. See THIRD_PARTY.md.

Early release (0.12.0). Tested in FreeCAD 1.1.4 on Linux. SimpleFlow's RUN button has been run for real against OpenFOAM v1912 (ESI) only; OpenFOAM Foundation 13, Windows and Mac are not tested yet; see RESEARCH.md. SimpleStress results are a quick check, not a certified analysis.

FreeCAD made simple: one pack, four workbenches.

SimpleCAD: a decluttered, Fusion 360-style sketch-and-solid workbench. FreeCAD's screen is full of tools most people never touch; SimpleCAD hides them (nothing is removed) and puts sketch → solid front and centre, with one big red button that always does the next obvious thing.
SimpleStress, SimpleFlow, SimpleSnap: foolproof, step-by-step simulations (will it break? how does air or water move? put the parts together). Each locks you into a short numbered pipeline: you can't skip a step, every refused click explains itself in plain English, and the same big red caution-tape button runs the next thing.

	Ask it	You do
SimpleStress	Will my part break?	Pick one part or several, tap a material tile for each (PLA, PETG, ABS, steel, stainless, pine, oak, plywood...), say which way up it was printed or which way the grain runs, bolt parts together with virtual M3-M6 bolts (no holes needed), paint the faces that are glued or bolted, pin holes, click where it gets pushed (a small spot, shown as a twinkling red disc, or the whole face), say how hard in N, kg or lb, tilt the push with two sliders, press RUN. You get STRONG / PROBABLY OK / RISKY / WILL BREAK and a red dot on the weakest spot.
SimpleFlow	How does air or water move round or through it?	Choose AROUND (a wind tunnel is built for you) or THROUGH A HOLE (click the rim of each opening: IN or OUT; the water inside is worked out for you), pick air / water / oil, set the speed and tilt the wind. It picks laminar or turbulent for you and builds the CfdOF case.
SimpleSnap	Put these parts together.	Like Lego: click a peg, hole or flat face; it lists what fits (pegs into matching holes, flat onto flat), you choose STUCK / SPINS / SLIDES, press SNAP IT. The peg goes all the way in and the part lands the right way up.

All screenshots are real FreeCAD 1.1.4 windows (Linux, virtual display, scripted clicks), except the deck close-ups deck.webp / swirl.webp, which are renders.

SimpleCAD

Features

Brushed-aluminium instrument panel: the deck is a screwed-on brushed-metal plate with engraved, recessed modules (MODE · CONFIRM · VIEW · SYSTEM), machined keys with indicator LEDs and a green phosphor readout; SimpleCAD's tool rows get the same metal and keys. The grain is a seamless generated tile (tools/make_brushed_alu.py), so it's all offline. Turn the tool-row styling off with ALU_TOOLBARS = False.
The big red button (in caution tape, shortcut Ctrl+Enter) does the next obvious thing:
- ✏ SKETCH: sketch on the selected face, or edit the selected sketch. With nothing selected, the three planes appear in the 3D view: click one, or press the big TOP / FRONT / SIDE buttons. No side-panel list to hunt through.
- ✔ FINISH SKETCH: close the sketch and leave it selected, so Extrude / Revolve / Loft is one click.
- ✔ OK – FINISH STEP: when a tool like Pad or Fillet is open, press its OK button.
Acid-green ACTIVE badge with rising bubbles shows whether you're in SKETCH, SOLID or TOOL mode.
🎯 SNAP TO FACE: look straight at the selected face (or the sketch you're in) and zoom to it.
⏎ ENTER button: pulses red whenever a tool (Pad, Pocket, Fillet...) is open and ready to confirm; click it, or just press Enter on the keyboard. (Enter is left alone in sketch mode, where it confirms typed dimensions.)
Whole-solid tools (Solid toolbar): New body (works from the start page too), Duplicate, Move / turn (drag arrows and rings), Combine, Subtract (first click kept, the rest cut away) and Intersect. Every result is a new body you can keep sketching on; originals are hidden, not deleted. Each says in plain English why it won't (e.g. "These solids don't touch, so they can't become one solid").
Make component: select bodies that belong together (a lid and its knob, a case and its clips) and they become one component (a folder that moves as one piece, like a Fusion 360 component). Nothing moves on screen. SimpleSnap snaps a component as one part. Select a component before New body to start a body inside it.

Light on old PCs: the deck is drawn once and reused, and the badge bubbles and ENTER pulse only animate briefly when something changes, so FreeCAD sits at about 3 % CPU when idle (0.9.3 kept a core about 40 % busy).
Sketch on a solid, snap to it: a new sketch on a solid gets that solid's edges in the sketch plane as pink reference lines (like Fusion 360), so your lines snap to them and can be made coincident. Use solid edges and Project (click any other edge) are first in the sketch tool row.

Only the everyday tools, on their own row under the deck, and the row swaps automatically between sketch tools and solid tools. On a smaller screen (e.g. a 1366 px laptop) the labels drop to icons only, so no tool falls off the end (hover for its name). Optional auto-extrude after finishing a sketch.
⋯ More tools: every Part Design / Sketcher command, plus "Show all hidden toolbars" and a jump to the full Part Design workbench.
Stays put: FreeCAD 1.x jumps to the Sketcher workbench when you open a sketch, and to Part Design whenever a Pad/Pocket/Fillet... dialog opens. SimpleCAD hops straight back without resetting anything (Declutter, deck and buttons stay as they were), and steps aside if FreeCAD ever keeps fighting it.
Tidy panels: model tree, task panel, report view and Python console become tabs on the left, and the Tasks tab comes forward when a dialog opens.
🧭 Navigation readout (the green phosphor display) cycles navigation styles (all orbit around the centre of the screen unless noted):
- Fusion Trackpad: two-finger swipe pans, Shift or Option + two-finger swipe orbits, pinch zooms, two-finger double-tap fits everything; two-finger click-drag also orbits.
- TinkerCAD: right-drag (two-finger click-drag) orbits, middle-drag pans, wheel zooms.
- FreeCAD Touchpad: FreeCAD's own touchpad style.
- Fusion Mouse and Cursor Mouse (orbit around what's under the mouse) need a mouse with a middle button, so on a Mac the button skips them; they're still in More tools → 🧭 Navigation.
- Reverse trackpad directions or restore FreeCAD's original navigation from the same menu.
🌀 Rainbow swirl: the selected face gets a smooth, see-through rainbow spiral so you can always see what's active (opacity: SWIRL_OPACITY). It animates gently (10 fps) and freezes to a static swirl by itself if the PC struggles; toggle it or make it static in More tools → 🎨 Look.
🌈 Rainbow faces: every face gets its own bright, see-through colour, updated automatically after each Pad/Pocket (toggle in More tools → 🎨 Look; transparency and colour strength at the top of SimpleCADDeck.py).
Looks: solids go even more see-through while you sketch. 🌙 Luminous (high contrast: near-black background, glowing cyan solids, neon selection) or ☀ Clean (light, soft blue-grey). Originals are backed up; More tools → 🎨 Look → Restore puts them back.
The look stays in SimpleCAD. Switch to SimpleStress, SimpleFlow, Part Design or any other workbench and your solids get their own colours back and FreeCAD its own background; the look returns when you come back. SimpleSnap is the exception: it assembles the same bodies you model, so they keep SimpleCAD's look there.
DECLUTTER key (amber LED when on): hides every remaining toolbar, panel and the status bar (never the workbench switcher). Press again to undo. Nothing it hides is remembered by FreeCAD, so a restart, with or without SimpleCAD, always brings everything back.
Opens in SimpleCAD: FreeCAD starts in SimpleCAD, and a new Part Design document (e.g. the Start page's Parametric Body) opens in SimpleCAD too. Turn off with More tools → Start FreeCAD in SimpleCAD (your previous start workbench comes back). The LUMINOUS key (green LED) switches the high-contrast 3D view.

Step by step

Start FreeCAD and pick SimpleCAD (it opens there by default).
Click the big red button (or Ctrl+Enter) with nothing selected, then click TOP / FRONT / SIDE in the 3D view.
Draw, then press the button again to finish the sketch; press Extrude (or let auto-extrude do it).
While a tool (Pad, Pocket, Fillet...) is open, press Enter or the ⏎ button.
More tools holds everything else, including Show all hidden toolbars and About.

Customise

Everything tweakable is at the top of SimpleCADDeck.py: which tools appear, icon size, colours, themes, navigation presets, trackpad speeds and the bubble animation.

The simulations

SimpleStress: PARTS > MATERIAL > DIRECTION > BOLTS > HOLD > FORCES > RUN > RESULT

The only solid in the document is picked automatically. Ctrl+click several solids to test them bolted together.
Materials are big colourful tiles (drawn in code, no image files): 3D printed (PLA, PETG, ABS, ASA, nylon, polycarbonate, resin), metal (mild steel, stainless, aluminium, brass), wood & board (pine, oak, plywood, MDF) and acrylic. Each shows its strength along and across its weak or strong direction.
DIRECTION (only when it matters): how it sat on the printer (flat, on its side, on its end, or click the face that was on the bed), which way the grain runs (or click the end grain), or which way a sheet's thickness runs. A blue arrow shows it in the 3D view. The stiffness and strength then really depend on it: a PLA bracket printed on its end can be half as strong as one printed flat, and the result tells you when "layers pulled apart" is the weak spot.
BOLTS (several parts only): pick M3, M4, M5 or M6 and stainless A2-70 or steel 8.8, press PLACE BOLTS and click where each bolt head goes. The bolt runs straight through into the part it touches; holes are optional. A bolt and nut are drawn in the 3D view; click one again to remove it. Each bolt is checked for stretching, shearing, its head or nut pulling through the part, and crushing the hole wall, and the result lists every part and every bolt. Parts touch only where bolted (cautious).
GLUE = stuck solid. PIN = a bolt through a round hole: it can turn but not slide off. A single pin on its own is refused (it would swing like a door).
Forces: SPOT (default): click exactly where it pushes; the force goes on a small circle there (set its size, e.g. a finger is about 15 mm, an M4 washer 9 mm), shown as a red twinkling disc. Click again to move it. WHOLE FACE: paint faces and the push is spread over them. Set how hard in N, kg or lb (kg/lb = the pull of that weight hanging on it; newtons always shown; your unit is remembered), PUSH IN or PULL OUT, then TILT (0 straight, 90 sideways) and SWING (which way it leans) with a live compass and a red arrow. Optional self-weight.
The part wears its material in the 3D view: layer lines the way it was printed, wood grain along the grain, brushed metal, so a wrong direction is easy to spot.
A face can't be both held and pushed. Nothing runs until something holds it and something pushes it.
The mesh is coarsened automatically so older PCs (7th-gen Core i3) cope.
CLEAN UP removes everything the study added, including FreeCAD's own result objects.

SimpleFlow: PART > KIND > FLUID > FLOW > CHECK > RUN > RESULT

AROUND builds a wind-tunnel box aligned with the wind (3 lengths upstream, 8 downstream, 3 each side), cuts your part out, and labels inlet, outlet and slip side walls.
THROUGH A HOLE: pick the part with the hole or channel in it (a drilled block, a pipe fitting, a manifold). Every opening on a flat face is found and shown as a grey disc. Tap IN or OUT next to each, or turn on IN / OUT and click the rim of the hole (or its inside wall near that end: the nearest end is used, never the whole wall). The fluid inside is worked out for you; if the channel also comes out somewhere you have not marked, it names that opening instead of letting the water leak. Unrelated holes (e.g. mounting holes) are ignored. Several inlets may face different ways.
THE PART IS THE FLUID: if you modelled the water itself (a solid shaped like the inside of the pipe), paint the faces where it enters and leaves.

CHECK shows the Reynolds number and whether it will be laminar or turbulent, and refuses air above 100 m/s (beyond what this setup can model).
RUN is one green button, like SimpleStress's: it builds the CfdOF case, meshes the part (Gmsh), runs OpenFOAM on every core, with a live progress line ("Solving, step 120 of 2000") and a red STOP that really ends the solver. When it finishes it jumps to RESULT. Nothing to open in CfdOF any more (small MESH PANEL / SOLVER PANEL buttons stay for experts). RESULT reads the solver log: SETTLED, STILL RUNNING, FINISHED BUT NOT SETTLED, or BLEW UP (with advice), plus how many cells and how long it took.

SimpleSnap: PARTS > BASE > SNAP > DONE

Tick parts to add them. Your own bodies go into the assembly, no copies are made: snapping moves the real part, so SimpleCAD and SimpleStress see it where it was snapped. Parts stay where they are; one that overlaps another is slid aside first.
Components: bodies that move together (a lid and its separate knob) can be added as one component (select them, then + ADD SELECTED AS ONE COMPONENT), or made beforehand with SimpleCAD's Make component. Each body on its own is its own component.
An assembly already in the file is picked up again when you come back (also after reopening the file).
START AGAIN puts every part back exactly where it was (same place, same folder) and splits components SimpleSnap made back into their bodies.
The base is fixed to the table (first part by default).
Click a face on the part you want to move. Matching faces on other parts are listed best-first (a perfect fit is chosen for you). Choose STUCK, SPINS, SLIDES, SPINS & SLIDES or BALL JOINT where it makes sense, then press the big red SNAP IT.
OTHER END pushes a peg in from the other side of a through-hole; FLIP LAST, UNDO LAST.
Snapping two parts that are both already attached is refused (it would jam the assembly). NEXT unlocks only when nothing is loose.

Files

Path	What
`InitGui.py`, `SimpleCAD*.py`, `icons/`	SimpleCAD itself (deck, solid tools, trackpad, swirl, metal panel)
`SimpleStress/`, `SimpleFlow/`, `SimpleSnap/`	The simulations (each: `InitGui.py`, `Boot.py`, `UI.py` screens, `Logic.py` plain-Python rules, `Backend.py` FreeCAD calls)
`simplewiz/`	The simulations' shared core: step-locking wizard, caution-tape panel, face picker, geometry, 3D overlays
`install.py` + launchers	Installer window (install, start FreeCAD, check, uninstall)
`tests/`	Unit/UI tests (no FreeCAD needed) and `tests/freecad/` scripts that run in real FreeCAD
`RESEARCH.md`	Sources, measurements, decisions, and what is not verified yet
`HOW_IT_WORKS.md`	What it reads, changes and never does

Build and test

Nothing to compile. The heavy work is done by FreeCAD, CalculiX, Gmsh, OpenFOAM and FreeCAD's assembly solver.

pip install -r requirements-dev.txt                    # PySide6, only for the tests
QT_QPA_PLATFORM=offscreen python3 -m unittest discover -s tests
# real FreeCAD (Linux, AppImage extracted to ./squashfs-root):
FREECAD=./squashfs-root/AppRun tests/freecad/run_all.sh

Version

One version for the whole pack. It is in SimpleCAD's About box, the deck's tooltip and the status bar, in every simulation panel's title and status line (e.g. SimpleStress 0.12.0 (Built 2026-10-16 00:58)), and in python3 install.py --version.

Source code: The-Dorkknight/simplecad on GitHub

Skipper Flipper

Matthew Armstrong — Wed, 14 Oct 2026 20:11:04 +0000

An experimental ESP32 pseudo Klipper port. (Repository and package name: esp-printhost.)

GPL-3.0 · Linux (Mint / Ubuntu) · C++17 core + Python tools · Project page

What this is

Part	State
Klipper wire protocol (CRC16, VLQ ints, framing, resync, data dictionary)	Unit-tested; works on hardware (ESP32-S3 to SKR Pico)
ESP32-S3 firmware (`firmware/esp32s3`): WiFi access point, status page, console, `printer.cfg` editor, test bench, printer page, the Klipper host's jobs (heaters, TMC2209, moves, homing, printing from flash). Shipped ready to flash	On hardware (to 2026-10-14): link, heating, PID, motor test, TMC2209, stallGuard trigger. Moves, homing and printing: simulation only
`skr-pico-uart` printer-board firmware (Klipper v0.13.0 + segment queue, serial on UART0)	Works on hardware: link, heater, thermistor, steppers, TMC UART, DIAG pins. The segment queue is not used by the ESP32 host
Segment-queue core (`firmware/skipper/segq_core.*`, shared by the firmware and the PC tests)	Working in simulation: exact step counts, step spacing, ring buffer, start threshold, underrun, stop
Motion planner + G-code engine (lookahead, junction deviation, trapezoids, pressure advance, G-code state)	Working in simulation: output is run through the real core and checked for exact positions, speed and acceleration limits
Other board presets (generic RP2040, Creality 4.2.x, RAMPS mega2560, Ender-3 1.1.x, USB SKR Pico)	Compile only; never run on hardware
Flasher app (`flasher.py`): Slave tab (printer board) and Master tab (ESP32-S3)	ESP32-S3 flashing used on hardware on Linux Mint. Other paths (SD card, avrdude, Windows/macOS) tested with mocks only
Firmware build tool (CLI + Slave tab "My own build")	Works on Linux (sandbox and the author's Linux Mint laptop); Windows needs WSL
`mcu_probe`, `fake_mcu.py`, one-command setup, Tools window	Working on Linux Mint. Probe tried on an SKR Pico over USB
Real printing	Built and simulated only (upload, print from flash, pause / resume / cancel); not yet run on the printer
Fans	Hotend fan confirmed on hardware; part-cooling fan and the third fan output not yet (possibly a broken wire, will update when tested)

Total checks: 1,029 C++ unit checks and 187 Python tests (including power-cycle, stallGuard and printing runs against a simulated board), all passing in the sandbox. Passing tests mean the maths and bookkeeping are right, not that a printer will behave.

Screenshots

The GUI building the tools and running the unit tests:

Both screenshots use the simulated board, not real hardware.

Flash a board (Linux, macOS, Windows)

python3 flasher.py          (Windows: double-click Flasher.bat; macOS: Flasher.command)

You need Python 3.8+ with Tk (Linux: sudo apt install python3-tk; on Windows and macOS the installer from python.org includes Tk). No toolchain is needed: firmware for every board preset (five boards, plus a serial variant of the SKR Pico) ships in firmware/prebuilt/. Pick the Slave tab, choose your board, press Flash... and confirm. RP2040 boards: hold BOOTSEL while plugging in USB. STM32 boards such as the Creality 4.2.x: put the SD card in this computer, Browse to it, flash, then move the card to the printer and power-cycle it. AVR boards need avrdude installed. The Master tab flashes an ESP32-S3 with esptool (Install esptool, then Use shipped firmware, pick the port, Flash). The port box fills itself with the ESP32-S3's port when it can tell which one it is (otherwise pick it). The shipped image starts a WiFi network SkipperFlipper-XXXX (WPA2, default password skipperflipper, change it before real use) with a page at http://192.168.4.1/, a live log at /console and printer.cfg at /config; it talks Klipper to the printer board over UART (identify, clock sync, LEDs and thermistors from printer.cfg, confirmed on hardware; heaters, fans, TMC2209 drivers and motor tests from the test bench at /test, simulated only so far). Moves, homing and printing a file (Printer page at /printer) are built and simulated, not yet run on hardware. Logs appear on the chip's native USB port. ESP32-S3 only: other ESP32 chips (original, S2, C3) are not supported, and esptool refuses to write if it finds a different chip. You can also flash your own .bin. To connect the ESP32-S3 to an SKR Pico with four jumper wires, see docs/WIRING_SKR_PICO.md.

Quick start (Linux Mint / Ubuntu / Debian)

git clone https://github.com/The-Dorkknight/esp-printhost
cd esp-printhost
sudo python3 printhost.py

Options: --check (report only, change nothing), --no-gui, --clean, --yes, --version.

If anything fails it prints the path of a log file in ~/esp-printhost-logs/. Attach that when you open an issue.

macOS: the C++ library and tests build (python3 host/tools/build.py), but mcu_probe is Linux-only (it uses Linux's termios2 for 250000 baud) and the one-command setup is Linux-only.

Using the GUI

Build tools compiles everything and runs the unit tests. Output is colour-coded per tool.
Fake MCU: Start runs a pretend Klipper board (no hardware). Its port appears in the Port box.
Run probe connects, reads the board's pin list into the Blink pin dropdown, and prints uptime and state. Tick Blink pin and pick a pin to also toggle it 10 times.
The output box is selectable (Ctrl+C, right-click, Copy all, Save as...). Everything is also logged to ~/esp-printhost-logs/.

Try it without hardware

python3 host/tools/fake_mcu.py            # prints /dev/pts/N
./host/build/mcu_probe /dev/pts/N 250000 --pins --blink PA5

Try it on a real board

You need a board running stock Klipper MCU firmware (build it from Klipper with make menuconfig; this project does not ship firmware yet). Stop Klipper or anything else using the port, then:

./host/build/mcu_probe /dev/serial/by-id/<your-board> 250000 --pins --blink <pin>

Tested so far: BTT SKR Pico (RP2040, Klipper v0.10.0-181). The probe identified it, read 31 pin names, reset it, configured gpio24 and sent 10 toggles with 0 CRC errors.

Project layout

printhost.py          one-command setup + launcher
flasher.py            the Flasher window (also Flasher.bat / Flasher.command)
HOW_IT_WORKS.md       what it reads, changes and never does
docs/                 DESIGN, PROTOCOL (draft v1), ENGINE, FIRMWARE, TASKS, project page
firmware/skipper/     segq_core (portable C core) + segq.c (Klipper glue)
firmware/esp32s3/       ESP32-S3 firmware (ESP-IDF project) + build.sh
firmware/prebuilt-esp32s3/  shipped ESP32-S3 image
firmware/boards/      board presets (.config + .json)
firmware/prebuilt/    shipped firmware per board (+ pin tables); refresh with skipper_fw.py bundle
firmware/test/        PC simulation of the Klipper glue
host/                 portable C++17 core (also an ESP-IDF component, untested)
  include/ph/         wire, msgproto, json_mini, config_ini, gcode, motion, planner, engine
  src/  test/         implementation + 480 unit tests
  tools/              build.py, skipper_fw.py, printhost_gui.py (+ fw_panel, skipper_theme),
                      mcu_probe.cpp, fake_mcu.py

Roadmap

Source code: The-Dorkknight/esp-printhost on GitHub

A Bonding Experience- The open-source new frontier of Z-delamination resistance.

Matthew Armstrong — Tue, 13 Oct 2026 15:19:35 +0000

The open-source new frontier of Z-delamination resistance

A hobbyist's field guide to Z-strength in FDM printing without tripping over patents, and a defensive publication of PinLoK (pinned infill).

By Matthew Armstrong (The-Dorkknight), United Kingdom. First published 13 October 2026.

📄 Read it: PAPER.md · PDF · web page

Every strength number for my own ideas here, including Shift-LoK, FlatLock and PinLoK, is theoretical: it comes from a 2-D computer simulation with known blind spots (paper, section 3), not from printed and tested parts. They are not product claims and say nothing about anyone else's products or patents. Real-world numbers quoted from others are linked to their sources. Not legal advice.

In one minute

Printed parts snap along their layers. The famous fix, staggering walls by half a layer ("brick layers"), is patented in the US. I went looking for every way to get stronger layers without beads of different heights, ran twelve ideas through a strength model, and wrote down what happened, failures included.

Idea	Simulated result across the layers (theoretical)	Verdict
"Loopholes" (variable first layer, smaller or multi-phase staggers)	about the same as normal; still needs different bead heights	geometry doesn't care about wording
Different layer height per wall	−1 to −11 %	weaker
FlatLock (fat/thin walls)	−4 to −17 %	weaker
Squish-LoK (over-extruded squish bead)	−8 to +1 %	nothing to fill
Squish-KeyLoK (keyed gaps)	−19 to +3 %	keys snap off
Wide inner walls (about 1.5 × nozzle)	+2 to +9 %	partial success, just a slicer setting
PinLoK pinned infill	+16 to +27 % against solid infill of the same weight	best result; costs print time

PinLoK builds on Oak Ridge National Laboratory's published Z-pinning. Every few layers the nozzle stops over half of the open gaps in Grid infill and pushes a blob of plastic down into each one; the other half get theirs next time, so the joints never line up. A potato mode keeps each push to about a second for stock printers like the Ender 3. A late discovery: pins that end half-way through a layer, not on a layer line, did far better in the simulation.

Why it's published

To keep it free. Once a method is published, nobody can validly patent it afterwards. Section 9 of the paper discloses PinLoK and its variations in buildable detail, and the methods are dedicated to the public.
To bring makers together. Open notebooks let tinkerers build on each other's work instead of repeating it. Print the test plan, post your results as an issue or discussion, fork it, improve it: everyone who contributes gets credited in the next version (paper, section 11).
To save you the dead ends. Most of the ideas here didn't work. Now you know without trying.
Selfishly: more cool 3D-printing techniques come back from the community, and I am now 22.713333…% more employable. High-efficiency synergy.

What's in here

Folder	What
`PAPER.md`, the PDF, `docs/`	The paper as Markdown, PDF and a web page
`figures/`	Every figure
`pinlok/`	The PinLoK G-code post-processor (Python 3.8+, no dependencies): `python3 pinlok/engine.py file.gcode --mode potato`
`tests/`	Its tests: `python3 -m unittest discover -s tests`
`model/`	The strength model and every result file (needs numpy, scipy, matplotlib)
`PUBLISHING.md`	How this was published, and what makes it count as published

The full app (LoK Walls: FlatLock, PinLoK and a locked brick-layer pattern, with installers for Cura, PrusaSlicer and OrcaSlicer) is in a separate repository, to be published after ADDMAN, the brick-layer patent holder, has been asked. I haven't contacted them yet; I intend to.

Cite

See CITATION.cff (GitHub shows a "Cite this repository" button). Once archived, the DOI goes here: DOI to be added.

Source code: The-Dorkknight/a-bonding-experience on GitHub

SimpleMesh

Matthew Armstrong — Sun, 11 Oct 2026 08:45:17 +0000

WORK IN PROGRESS: MANY FEATURES MAY BE BROKEN · version 0.5.0-wip · pre-release

About the screenshots: they are the real Blender 4.0.2 window with SimpleMesh loaded, captured on a virtual display (software rendering) while a script moved the mouse and pressed keys (tests/gui_session.py). No person, and no child, has used this version by hand yet, so how it feels is unproven. See what is tested.

A Blender add-on that turns Blender into a plain make-and-print workbench. No scenery, no animation timeline, no game-asset tooling. It has two levels:

Easy mode (what Blender now starts in): big picture buttons aimed at a ten-year-old. Build things out of shapes, your own drawings, words and clay, colour them in, press Print!.
The panel: big buttons across the top of the 3D view, there in every mode, for editing STL files exactly: lay flat, move, turn, size, pull a face, cut, drill, measure, mould like clay, with millimetres. It is the same idea as SimpleCAD's deck: a big red button that does the next obvious thing, a green badge that says what is active, and keys for the look.

It is the Blender sibling of SimpleCAD.

Easy mode

To make something: click a picture, move the mouse, click to put it down. A shape sits on whatever is under the mouse: the floor, or the top or side of another shape, so things stack and stick the way you expect.

Left side: things to add
Block, Ball, Tube, Cone, Pyramid, Roof, Ring, Star, Heart	Ready-made shapes.
Draw	Hold the mouse button and draw a loop on the floor. It becomes a solid shape. Wobbly lines, crossed lines and scribbles still give something solid.
Words	Type a word or your name and get 3D letters.
Clay	Squish and pull the chosen shape (or a new ball) like clay, then press Done. Turn on Mirror for faces and creatures.
Ideas	Start from a snowman, house, rocket, robot or car made of shapes, then change it.
Open	Load a model file somebody else made.

To change a shape: click it. Drag it to move it. It has six dots:

Dot	Pull it to...
white (top corner)	make it bigger or smaller
red / green / blue	make it longer / wider / taller
orange	spin it round
purple	tip it over

Along the bottom
Undo / Redo	Go back a step. Nothing can be broken.
Copy / Bin	Another one the same / throw it away.
Hole	Turns the chosen shape into a hole (it goes red). Push it into another shape; Glue or Print! cuts it out.
Glue	Sticks the shapes together into one.
Save	Keeps your project so you can carry on another day (it reopens in Easy mode).
Colours	Colour in the chosen shape. (Colours are for you; a printer prints in whatever plastic is loaded.)
Print!	Cuts out the holes, glues what touches, repairs everything, sits it on the bed, tells you if it is too big, and saves the file for the printer.

Bottom right: arrow buttons turn the view, + and − zoom, the middle one shows everything. You can also drag with the right mouse button to look around.


What Blender looks like when it starts	A ball being put on top of a block
The six dots on the chosen shape	Pulling the blue dot: taller
Draw a loop on the floor...	Ideas: ready-made starters

The Easy key on the panel turns Easy mode off and on. With it off you select models by clicking and use the panel's tools described next. To make Blender start with it off, untick Start in Easy mode in the add-on's preferences.

What "anything you can imagine" really means here: anything you can build from those shapes, your own drawn outlines, letters and clay, stuck together and with holes cut out. That covers a lot (characters, vehicles, buildings, name tags, cookie cutters, creatures) but it is not everything: no screw threads, no exact engineering fits, and very thin clay shapes may not print.

The panel (big buttons)

Part	What it does
The big red button	The next obvious thing. Normally MOULD LIKE CLAY. While a tool is on: FINISH that tool. While moulding: DONE. In one of Blender's own modes: BACK TO THE MODELS. In Blender's own Sculpt Mode before the model is ready: GET READY TO MOULD.
The green badge	What is active right now: SELECT, EASY, LAY FLAT, CLAY: PULL...
FIND MODEL	Centres the view on the model (same as F).
Tool keys	Lay flat, Move, Turn, Size, Pull face, Cut, Drill, Measure, Open, Save, Undo, Redo. The key of the tool that is on has its light lit. While moulding they become the seven brushes plus Brush +, Brush - and Mirror.
Easy	Picture buttons on or off.
Luminous	Switches between the dark, high-contrast look and the light, clean one.
Hide clutter	Hides Blender's own menu rows and status bar; press again to bring them back. The panel stays.
More tools	Exact numbers, shapes and holes, check and repair, view settings, Look (below), and Report a problem.

The panel is drawn inside the 3D view (Blender's own header rows cannot hold big buttons), ends short of the right edge so Blender's view ball stays free, and shrinks its buttons on a narrow window. Hover over a button and a line under the panel says what it does. Switch it off in More tools ▸ Big-button panel and the tools go back to the thin strip in Blender's header.


Lay flat is on: its light is lit, the red button says FINISH LAY FLAT	While moulding: DONE, and the brushes
The Clean look	Hide clutter: Blender's rows are gone

Look

More tools ▸ Look (also in the strip's View pop-up):

Luminous (near-black background, cyan models, orange outline), Clean (light background, soft blue-grey) or Blender default. The Luminous key on the panel switches between the first two.
Rainbow: every model gets a colour of its own, which shows at a glance which parts are separate.
Show the triangles: the triangles of the STL drawn on the model.
See-through, Show flipped faces (red), Show size on the model.

The tools

Open an STL. It arrives in millimetres at a sensible size (a 5200 mm monster is divided by 10 until it fits your bed), sitting on the bed, in the middle of the view. Its size and "fits the bed" are written in the top-left corner all the time.
Pick a tool on the panel, then do it on the model. The view shows what a click will do before you click. Orbit and zoom keep working. Esc or right-click leaves the tool. Ctrl+Z undoes.
Save writes a millimetre STL as <name>_edited.stl.
Lost the model? Press F (or Find).

Tool	What you do	Extras
Lay flat	Move over the model: the flat face under the mouse lights up. Click: that face sits on the bed.	No Edit Mode.
Move	Drag a model: it slides across the bed.	Shift+drag lifts it. Arrow keys 1 mm (Shift 10, Ctrl 0.1). D = drop to bed, C = centre.
Turn	Drag a model sideways: it spins in 15° steps and is put back on the bed.	X / Y / Z choose the direction. Arrow keys = 90°. Type an angle + Enter. Shift = fine.
Size	Drag away from the model = bigger, towards it = smaller. Or type the longest side in mm + Enter.	X / Y / Z stretch one direction only. Ctrl = whole millimetres. Scale stays 1.0.
Pull	Point at a flat face (it lights up) and drag it out or in: the part gets longer or shorter. Or point and type mm + Enter.	Steps of 0.5 mm; Ctrl = whole mm; Shift = free. Minus key = inwards when typing.
Cut	A red plane follows the mouse over the model; click to cut there. Or drag a line across the model to cut along it.	X / Y / Z direction. Type a height in mm + Enter. K = keep both / one side. L = lay the cut faces on the bed. Cuts are capped.
Drill	A red circle follows the mouse on the surface; click to drill a round hole.	Type the diameter + Enter, or + / −. T = through / blind, [ ] = depth. Ctrl = centre of the face.
Measure	Click two points.	Snaps to corners. Shows the distance and its X / Y / Z parts.

Clay: mould it like clay

Clay is for free-form changes: click a model, press the red MOULD LIKE CLAY button (or the Clay picture in Easy mode), and the panel's keys become seven brushes. Press on the surface and drag. Choosing Sculpt Mode from Blender's own mode menu ends up in the same place: SimpleMesh does the Clay set-up by itself.

Brush	What it does
Pull	The clay follows the mouse and stretches out. Pull a lump, a horn, a handle out of a flat face.
Build up / Push in	Rub to raise the surface / press it in.
Shift	Slide an area sideways without stretching it.
Inflate	Swell outwards in all directions.
Smooth / Flatten	Rub out lumps / level an area.

Brush Size is in millimetres and stays the same at any zoom; it starts at a fifth of the model. Brush + and Brush - on the panel change it (or F, then move the mouse). Holding Ctrl does the opposite, holding Shift smooths, Ctrl+Z undoes a stroke. The read-out shows how many triangles the model has and warns in red when it is getting heavy. Press the red DONE button to go back to the normal tools.

Underneath it is Blender's own sculpting engine, set up for STL work: the model is first given small triangles everywhere (its shape does not change) because an STL's big flat triangles have nothing to mould; more are added under the brush as you work; mirror symmetry is off; and when you press Done the flat areas you did not touch are merged back into big triangles so the file stays small. Detail (the size of the new triangles, in the header row) cannot be set finer than a thirtieth of the brush: a big brush with a tiny Detail makes Blender cut hundreds of thousands of triangles in one drag and stop answering.


Pull: point at a flat face...	...and drag it: +10 mm
Clay ▸ Pull: a horn pulled out of a flat face	Clay ▸ Push in

Pop-ups in Blender's header row (and under More tools on the panel) hold the things that need numbers or are used less often:

Numbers: ÷1000 ÷100 ÷10 ×10 ×1000, inch ↔ mm, set the longest side, exact X/Y/Z, drop / centre / auto lay flat, 90° turns, mirror, hole and cut settings.
Shapes: add a block, cylinder, sphere or cone sized in mm. Make it a hole turns any shape into a red wire "hole"; Cut the holes out removes every hole from whatever it touches (no "select the cutter, then the base"). Weld together, separate loose pieces, copy, delete.
Repair: Check (triangles, volume, surface, holes, inside-out faces), one-click Repair, Simplify.
View: standard views, show everything, looks (Luminous / Clean / Blender default), show flipped faces, laptop navigation (no middle button needed), printer bed size (presets for FlashForge Adventurer 5M, Bambu Lab A1, Creality Ender 3 V2).


Cut: the plane follows the mouse	Hole: the circle follows the mouse
Cut: drag a line across	Measure
Size: drag, or type	The Numbers pop-up
A 5200 mm STL after Open: shrunk to fit, centred	Open: choose the file's units here

Why the tools are like this, and which existing add-ons and programs they were modelled on: docs/DESIGN.md.

What is tested and what is not

Tested in a real Blender 4.0.2 window (virtual display, simulated mouse and keys, 114 checks, tests/gui_session.py; the first part drives the tools through the thin strip with the panel off, the last part drives the panel): Easy mode as a scripted child's session: Blender starts in it; Block is picked up and put down; a Ball is put on top of the Block and lands on it; clicking selects; pulling dots makes the block taller, bigger and spins it; dragging slides it; colour, Copy, Bin; a loop drawn with the mouse becomes a solid; Ideas places a rocket; Glue makes it one closed model; Undo; the arrow buttons and right-drag turn the view; the Clay button and Done; Print! glues, repairs, sits everything on the bed and opens the save box; a saved project reopens in Easy mode. Then the strip tools: start-up tidy (one 3D view, millimetres, two workspace tabs); import of a 5200 mm STL lands centred and sensibly sized on screen; view re-centres after scaling; F finds a model 4.7 m away; every strip tool by click/drag/keys (lay flat by hover+click, move by drag and arrow key, turn by drag and by key, size by typing and by drag, cut by click and by dragging a line, pull a face by typing and by dragging, hole with typed diameter, measure); Clay: entering from the strip, millimetre brush size, a Pull stroke stretching a flat face from 20 to 39 mm, switching to Push in, Ctrl+Z after the first stroke staying in Clay and taking back just that stroke, redo, Done merging flat areas and leaving the model watertight; Sculpt Mode entered the way Blender's own mode menu does it being noticed, set up automatically (small triangles, automatic detail, the Pull brush in millimetres) and a drag then pulling the block from 20 to 39 mm; undo of a tool step; switching tools from the strip while a tool is on; the four pop-ups and the Open file chooser appear. The panel: its mouse watcher starts by itself; a click on the Lay flat key starts the tool, lights the key and turns the red button into FINISH LAY FLAT; the red button finishes it; clicks on the panel do not reach the model behind it; the red button starts Clay and the keys become brushes; Brush +, a brush key, a stroke in the view, the Undo key (the stroke goes, Clay stays), DONE; the Luminous key; Hide clutter and back; the Easy key, a picture button under the panel, a panel tool started from Easy mode and Easy mode taking over again afterwards; a recovery copy written while the panel is watching the mouse. The installer window was driven the same way (tests/test_installer_gui.py, 20 checks): it found and questioned two Blenders, ticking and unticking rows, refusing a program that is not Blender, Install, the two options, Remove, and Open Blender all worked, and Blender then started normally with the add-on on. Plain python3 install.py and the Linux launcher script both opened the window (tests/test_install_launch.py, 14 checks, starts install.py as its own program and looks for its window). With tkinter switched off, the dialog-box version (zenity) was clicked through an install by hand-placed mouse clicks, and the terminal version picked Blender number 1 from its list.

Also tried by hand with real mouse and keyboard events (sent through the display server with xdotool, not Blender's own event simulation; Blender 4.0.2 started normally after the installer; these sessions are not part of the repository's tests): placing a block and pulling a dot; opening a 234-triangle bracket and a 327,680-triangle model through the real file chooser; Lay flat on the bracket; a long Clay Pull stroke on both; Sculpt Mode chosen from Blender's mode menu (in 0.4.2 two long drags changed nothing you could see, in 0.4.3 the set-up runs and the drag pulls a horn out); Ctrl+Z after one and after two Clay strokes; Undo pressed until nothing was left, then adding a shape; Edit Mode and Back to the models; Report a problem (which caught a real error in the first version of the undo repair). With Blender 5.0.1 and version 0.4.2, placing a block, pulling a dot and a Clay Pull stroke worked the same way; nothing later than 0.4.2 was run in a 5.x window. For 0.5.0, on a 1366 x 768 screen: the panel's keys by real clicks (Lay flat and FINISH, MOULD LIKE CLAY, Brush + three times, Build up, strokes, the Undo key, DONE, Luminous, Hide clutter, More tools and its Exact numbers pop-up, Report a problem); four fast clicks on a picture button all counting; an 82,000-triangle model opened through the file chooser and moulded with five strokes (Blender stayed under 0.9 GB and DONE took under 8 seconds on this machine's software rendering). The freeze: with 0.4.3 the same model, five strokes and then Finer everywhere left Blender not answering for several minutes at 4 GB; that button no longer exists.

Tested without a window (tests/test_headless.py, Blender 5.2.2 as the bpy module, also with numpy disabled): all the mesh work behind the tools: import sizes and units, scaling, lay flat, every Easy shape is closed and the right size; hand-drawn outlines (clean loop, overshoot, figure-of-eight, scribble) always give a valid solid; words become closed letters; each of the five Ideas goes through Print! to one watertight model that fits the bed; glue with holes; cuts with any plane (volumes add up, caps watertight), pulling faces, refining for Clay and merging flat areas again, Clay set-up including all seven brushes on Blender 5.2's brush system, drilling through and blind holes, hole shapes, weld, separate, repair, simplify, export and re-import.

Not tested: any real person using it, and in particular no child has tried Easy mode: whether a ten-year-old finds the dots, the stacking and the wording obvious is exactly what a scripted mouse cannot tell me; the Words and Save pop-up boxes themselves (the operators behind them were run); screens smaller than 1366 x 768 (the picture buttons were looked at on 1600 x 900 and 1366 x 768 only); trackpads; the two reported problems on the computer where they were reported: "a drag only changes it slightly" (0.4.3: reproduced here by choosing Sculpt Mode from Blender's own menu) and "on sculpt all controls lock up" (0.5.0: reproduced here with Finer everywhere), so in both cases I fixed something that matches the description without being able to check that it is what happened there; the panel, the look keys and every other 0.4.3 and 0.5.0 change in a window on any Blender other than 4.0.2 (on 5.2 only the windowless tests, where the panel is laid out and its buttons run but nothing is drawn or clicked); Blender 3.x and 4.1 to 4.5 in any form; the panel on high-resolution (Retina / 4K scaled) screens, on two monitors or in more than one Blender window; the recovery copy over a real working session (it was written once on demand and once by its timer); Clay on models above about 330,000 triangles and on slow computers; the dense-model path above 700,000 triangles; large real-world STLs (hundreds of thousands of triangles: hovering builds a lookup of the model first, which may pause for a few seconds); the full scripted window session on Blender 3.x, 4.2+ or 5.x (only the windowless tests ran on 5.2); a real double-click on install.py or the launcher in a desktop file manager (they were started from a command line on a virtual display; the 0.4.2 fix for "install.py shows nothing" was not confirmed on the computer where it was reported); macOS and Windows, including the Mac and Windows double-click launchers and the "Add another Blender..." file chooser box itself; flatpak/snap/Steam Blender with the installer (the search for them is written but there was none here to find); the extension-format zip; the GitHub workflows.

docs/DESIGN.md · HOW_IT_WORKS.md · CHANGELOG.md · CONTRIBUTING.md · SECURITY.md

Source code: The-Dorkknight/simplemesh on GitHub

Pi Hotspot Injector

Matthew Armstrong — Sun, 11 Oct 2026 08:38:05 +0000

Source-available · Non-commercial · Linux desktop · Pi 1 to Pi 5 · Project page

Licence: free for non-commercial use (personal, hobby, educational, charity). Provided as is, with no warranty and no liability. See LICENSE.md (PolyForm Noncommercial 1.0.0). Use it at your own risk: it can erase the wrong drive if you pick the wrong one.

A point-and-click Linux tool that turns a blank SD card into a Klipper 3D-printer controller that broadcasts its own Wi-Fi hotspot. It's handy in a workshop or garage with no Wi-Fi network around: power the Pi on, join its Wi-Fi from your phone or laptop, and open Mainsail in a browser.

One card works in every Raspberry Pi, from the original Pi 1 and Pi Zero W up to the Pi 4, 400 and 5.

It does everything from your Linux PC, with no need to boot the Pi first or plug in a keyboard and screen:

Write the OS image (Raspberry Pi OS Lite, or MainsailOS) to an SD card or USB stick, straight from the downloaded .img.xz / .zip.
Build Klipper: install Klipper, Moonraker and Mainsail (plus Crowsnest if you want a webcam, and the experimental KlipPlug plugin manager if you want plugins) onto a clean Raspberry Pi OS Lite card. Everything comes clean and straight from each project, compiled so it runs on every Pi.
Set up the hotspot: Wi-Fi name, password, country and IP address.
Clone & Backup (optional): save a finished card as an image file, and copy it onto more cards, each one becoming a separate Pi with its own name.
Extras: a Pi Zero / Pi 1 compatibility check-and-fix for existing cards, the Card Inquisitor boot diagnostics, and a standalone hostapd + dnsmasq installer.

Write the image	Build Klipper

Set up the hotspot	Clone & Backup

Sanity check 1 of 2	Sanity check 2 of 2

⚠️ Read this first

This tool writes directly to disks. Used on the wrong drive, it permanently erases that drive's data. It has several safety guards (below), but back up anything important before you use it, and double-check which drive you pick.

Start it

Double-click PiInjector.desktop. The first time, your file manager may ask whether you trust it. That's a one-off security check you have to click through:

Desktop	What to do
Linux Mint (Cinnamon / Nemo)	Click Mark as Trusted (or Launch Anyway)
KDE (Dolphin)	Click Continue / Execute if asked
Ubuntu (GNOME Files)	GNOME Files won't run launchers from ordinary folders. Start it once from a terminal (below), then use Extras → Add to applications menu

Then enter your password when asked. The tool needs administrator rights to write to SD cards, and it asks for them itself.

Or, from a terminal: python3 pi_injector.py

Once it's running, Extras → Add to applications menu puts it in your start menu like any other app.

On startup, a short disclaimer appears that you must accept before you can use the tool. Reading the full licence from that screen is optional.

How to use it

1. Write Image

Press Download Raspberry Pi OS Lite (32-bit). It fetches the official image (about 530 MB) from raspberrypi.com, checks it against their published checksum, and fills it in for you. Flaky Wi-Fi is fine: progress is saved as it goes (a checkpoint every 10 MB, plus wherever the connection drops), and it reconnects by itself and carries on from there. Cancel just pauses it; press Download again later, even after a restart, to continue. (Downloading it yourself is fine too: it's the …-raspios-…-armhf-lite.img.xz file. Not "Raspberry Pi Desktop for PC and Mac", which is a PC ISO that can't run on a Pi.) MainsailOS works too; then skip step 2.
Plug in your SD card (in a USB reader) or USB stick.
Browse... to the image, pick the drive, then Write Image to Drive.
Get past the two sanity checks (below). Writing and verifying take a few minutes.

2. Build Klipper

Leave the freshly written card plugged in. Don't boot it in a Pi first, because the build needs a never-started card.
Choose a login user (default pi), a password (write it down) and a hostname (give each printer its own).
Options: Printer firmware build tools (on by default; lets you compile and flash your printer board's firmware on the Pi, as most guides do; uses about 1 GB), Crowsnest (webcam support) and KlipPlug (plugin manager, experimental; see below).
Build Klipper Card. It takes about 1–2 hours and needs this PC online, so keep the PC awake. What it does:
- enlarges the card's system partition (as the Pi would on its first start);
- sets up the user, SSH and hostname;
- installs Klipper, Moonraker, Mainsail, nginx and (optionally) Crowsnest, straight from each project;
- on a 32-bit card, compiles everything for the oldest Pi and checks every compiled file;
- if you ticked KlipPlug, installs it and runs it once on the card's own Python;
- finally test-starts Moonraker on an emulated Pi to prove it works.
Cancel is safe. A stopped or failed build can simply be started again, and it carries on where it left off.

After the first start, Mainsail will show a Klipper error until you put your printer's configuration into printer.cfg. Klipper's example configs are in ~/klipper/config/.

The KlipPlug option (experimental)

KlipPlug is a separate project by the same author: a plugin manager for Klipper that can run many OctoPrint plugins. Ticking the box adds it to the card as its own service; its page is at http://<hostname>.local:7130 (on the hotspot: http://192.168.50.1:7130), next to Mainsail, which is not changed.

Where it comes from: if a klipplug folder or a klipplug….zip sits next to pi_injector.py, that copy is used. Otherwise it is downloaded from GitHub. Use the local copy for a build without that download, or for a version that isn't on GitHub. A local copy goes onto the card without its .git folder (a clone's settings can hold a login token), so Mainsail's update panel won't list it; a copy downloaded from GitHub is listed there.
If it can't be installed (no download, a broken zip), the build carries on and finishes without it, and tells you so at the end. The Klipper card is complete either way.
What has and hasn't been tried: this option was tested with a stand-in for the card on a PC (the same install step, run in a chroot, then the installed service started against Klipper and Moonraker). It has not been built onto a real SD card or started on a real Pi yet. KlipPlug itself is work in progress and has not been run on a physical printer. A Pi Zero W has little memory (512 MB); how well KlipPlug runs there beside Klipper is not measured.
Licence: KlipPlug is under AGPL-3.0, not this tool's licence. See THIRD_PARTY.md.

3. Hotspot Setup

Leave the card plugged in (or insert a card flashed with another tool).
Check the settings. A random Wi-Fi password is generated for you: write it down. Set the country code to where the Pi will be used.
Inject Hotspot. If the card lacks hostapd/dnsmasq, the tool offers to install them (this PC needs internet access; it takes 5–15 min).
Note the Wi-Fi name, password and web address it shows you.

4. Use it

Put the card in the Pi and power it on. The first boot takes a few minutes because the Pi sets itself up and may restart once. Then join the Wi-Fi network and open http://192.168.50.1 (or whatever address you chose). On a laptop, http://<hostname>.local works too (e.g. http://klipper.local; the hostname is the one set in step 2, not the login user name). Phones often can't open .local names, so use the number there.

If your phone has joined a hotspot with the same name before, choose Forget network on it first. Otherwise it may quietly try the old saved password.

Running more than one of these hotspots at once? Give each card a different Hotspot address number (or press Random), so they don't clash.

Clone & Backup (several Pis)

Setting up several Pis? Build one card with steps 1–3, then:

A. Save a card as an image file: pick the finished card; it is only read, never changed. With Shrink ticked (recommended) the file is only as big as what's on the card, a few GB, so it fits any card big enough. That matters because a "32 GB" card from another brand is often slightly smaller than yours. Optionally compress it to .img.gz.
B. Write a copy onto another card: pick the image and a blank card (the same two safety checks as tab 1). The copy is grown to fill the card and, with Make it a separate Pi ticked, gets its own name (klipper2, klipper3…), a fresh machine ID and new SSH keys, so two Pis never get mixed up on a network.
Run step 3 on the copy to give it its own hotspot name and password.

Keep the image file as a backup: if a card ever dies, write it again in a few minutes. To restore onto the same Pi, untick Make it a separate Pi.

Which Pi?

A card built from Raspberry Pi OS Lite (32-bit) runs in any of these:

Pi	Works	Notes
Pi 1 A/B, Zero, Zero W	✅	Everything is compiled for these (ARMv6). Slow, but fine for one printer.
Zero 2 W, Pi 2, Pi 3	✅
Pi 4, Pi 400	✅	Best choice for printing plus a webcam.
Pi 5	✅	Runs the 32-bit card fine. For a Pi 3, 4 or 5 only, the 64-bit Lite image also works.

The build emulates the Pi Zero's own processor while it compiles, so nothing ends up built for a newer chip than the oldest Pi's. Every newer Pi runs that code natively. That's also why cards built with this tool don't hit the Moonraker Illegal instruction crash that affects some ready-made images on a Pi Zero.

Safety features

Size window: only removable drives sold as 8–32 GB (±1 GB tolerance) are ever offered as write targets. External hard drives, SSDs, 64 GB+ sticks and tiny drives are refused outright.
Internal disks are never offered: SATA/NVMe drives, built-in eMMC storage, the live-USB stick you booted from, and anything holding this PC's system, home folders or swap are excluded.
Two sanity checks before erasing:
1. A summary of the drive, what's on it now (partition names), and the image that will replace it. No is the default button.
2. "Are you reeeeley sure you want to overwrite disk …?" You must type the drive's name (e.g. sdb) to enable the button.
Re-checks the drive right before writing. If it was unplugged or swapped for another one with the same name, nothing is written.
Refuses to write an image file that's stored on the drive being overwritten.
The hotspot, diagnostics and package tools only touch a card that really is a Raspberry Pi OS card (checked read-only first).
Build Klipper checks read-only first that it's a never-started Raspberry Pi OS card, that the user name doesn't clash with a system account, and that the filesystem checks clean with this PC's tools. Only then does it change anything. It never touches a card that's already been used.
Checks that the image fits, and warns if the file doesn't look like a bootable disk image.
Exclusive access: the kernel blocks the write if anything still has the drive open.
Verify after writing (on by default) reads the drive back and compares checksums. This catches faulty and fake-capacity cards.
Won't let you close the window mid-job without a warning. Cancel works during writes and package installs, and the card is tidied up (temporary mounts and files removed) even if the tool is closed or killed.
"Why isn't my drive listed?" explains exactly why each drive was excluded.

The size window is set by MIN_WRITE_TARGET_BYTES / MAX_WRITE_TARGET_BYTES near the top of pi_injector.py. Change it at your own risk.

Compatibility notes

Target images: Raspberry Pi OS / MainsailOS based on Bookworm or newer (NetworkManager-based).
The hostapd + dnsmasq method is recommended. NetworkManager's own AP mode is unreliable on the Pi Zero W's BCM43430 Wi-Fi chip on trixie-based images.
For cards not built with this tool, the optional login user from Hotspot Setup is created via userconf.txt on the boot partition. (A built card already has its user.)
Built from Raspberry Pi OS with desktop instead of Lite? That works too. The card is set to start without the graphical desktop, to leave memory for Klipper (switch it back on with sudo raspi-config → System Options → Boot).
A built card has cloud-init and Raspberry Pi OS's first-boot "create a user" wizard switched off. The build has already set up the user, SSH and hostname, and those first-boot tools would otherwise rename the user and break Klipper's paths.
After you run updates on the Pi itself, pip picks packages for that Pi's own processor. If you later move such a card from a Pi 3/4/5 into a Pi Zero / Pi 1, run Extras → Check card first.
Pi Zero, Zero W and Pi 1 (ARMv6): some recent images (e.g. MainsailOS 3.x, whose build moved to ARMv7) include compiled software these older boards can't run, so Moonraker crash-loops with Illegal instruction. Hotspot Setup warns you when it spots this, and Extras → Fix for Pi Zero / Pi 1 rebuilds the affected Python packages from source for ARMv6, then tests each one on an emulated Pi Zero CPU. The Pi Zero 2 W, 3, 4 and 5 aren't affected.