0 Fork 0

mirror of https://github.com/Klipper4FlashForge/firmware.git synced 2026-10-23 05:42:17 -05:00

Files

T

Oleksandr ShyshatskyiandClaude Opus 5 f8b925e48f Replace opkg with apk, and sign the feed

docs/notes/85-packaging.md chose opkg in 2026-08 on one argument: every package
is cross-built here anyway, so the winner is whichever format is cheapest to
PRODUCE -- and .ipk had an upstream tool where .apk meant abuild, a keypair and
an Alpine host. Two lines of that comparison were wrong.

apk mkpkg is an applet of apk itself: -I key:value metadata, -F directory, no
keypair, no abuild, no Alpine host. The "making a package" row described
apk-tools 2. And the on-device client was counted a wash when it is better than
one -- openssl and zlib were already cross-built for CPython, and libarchive
existed in this tree only for opkg, so adopting apk REMOVES a cross-build.

What made it possible at all is that apk resolves its database relative to
--root and uses the same root as the file destination, while / here is a
read-only squashfs -- measured: neither /lib/apk nor /etc/apk can be created.
pkgs/3rdparty/apk-tools/prefix.patch splits the two. Upstream already carries
root_fd and dest_fd separately and merely aliases them in context.c, so the
patch defaults the database root to $MODDIR and leaves files extracting at /.
That is opkg's compile-time VARDIR plus `dest root /`, in apk's spelling.

THE FEED IS SIGNED NOW, which it never was: opkg signed the index and
bin/build-packages.sh signed nothing, so nothing was verified on a printer.
apk verifies with raw PEM public keys, not X.509 -- measured on the machine,
where every certificate directory is empty. ./bin/apk-keygen.sh makes an RSA
pair, APK_SIGN_KEY in config.env points at the private half, and the public
half both seeds the USB stick (so the first install can verify) and ships in
anvil-core (so the printer keeps trusting). An empty APK_SIGN_KEY still builds
an unsigned feed, deliberately: `make packages` has to run on a bare checkout
or the packaging lane stops being a CI gate.

WHAT IT COST is a carried patch, against an internal with one consumer, on a
branch mid v2->v3 transition, on an architecture with no upstream apk port to
share the rebasing. That is the standing risk and it does not go away.

Four bugs this shook out, all silent, all found by a gate rather than by
reading:

  * The prune deleted seventeen packages it had just built. The all -> noarch
    mapping went into the emitter and not into pkg_pkgfile, so the prune looked
    for a name nothing wrote. `make packages` exited 0.
  * Whitespace-separated Depends dropped nineteen packages. opkg's pkg_parse.c
    splits that field on ',' and nothing else, so the whole list became one
    dependency whose name contained spaces and resolved to nothing -- and opkg
    neither warned nor failed. `make build` shipped a payload with no Tornado
    in it. test_the_payload_is_dependency_closed is what catches that now.
  * Ownership was recorded as `nobody`. apk resolves an owner to a NAME against
    <--root>/etc/passwd and the build lane runs --user with no passwd entry, so
    every file in every package would have installed as uid 65534, with no
    error at build or install time. build-packages.sh writes a two-line
    synthetic passwd naming the build user root and points --root at it.
  * Four recipes carried versions apk cannot parse -- two spelled a commit
    +git<sha> where the grammar's hash slot is ~, x264 had a snapshot name
    whose -2245 reads as a malformed release, and helixscreen had
    0.99.115.creator5.3 where apk allows one trailing letter and then only a
    suffix from a closed set of nine words. All four were valid opkg versions,
    which is why nothing had noticed. pkg_version_ok gates every recipe now.

A v3 .apk begins with ADBd magic and is not a tar stream, so there is no apk
equivalent of the `ar -p | gunzip | tar` that hand-unpacked anvil-opkg: you
cannot open a package without a package manager. bin/build-payload.py puts the
cross-built binary on the stick at /mnt/apk instead. It is the same build
anvil-apk-tools contains, that package installs normally, and the bootstrap
copy never lands.

Two gates retired rather than moved. apk's installed database is plain text
(F: sets a directory, R: names a file in it), so the payload-ownership check
reads one file where it used to glob info/*.list. And it carries no clock at
all -- apk records no install time and mkpkg sets no build-time -- so the
Installed-Time normalisation case-build-payload.sh did on every build is gone,
and the test asserts the ABSENCE of a t: line instead. Clock-free by
construction rather than by repair.

Also removed: PKG_SECTION, which 45 recipes declared and nothing read once
apk's schema had no field for it, and the `make apk-host` target -- the
packager is built on demand by bin/build-packages.sh and stamped on the pin,
the way pkg_toolchain and pkg_buildpython already work.

Verified from a cold work/host and work/packages: 47 packages built and signed,
`make build` installs 35 and verifies them against the shipped public key,
`make qa-static` 195 passed, `make qa-replica` 135 passed -- the printer
installing off a simulated USB stick and booting. The installed set was checked
against the declared closure of the eleven roots: 35 expected, 35 installed,
nothing extra and nothing missing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013rbKEyLXrzSE6wm3iNApVp

2026-08-31 14:32:07 +03:00

4.8 KiB

Raw Blame History

firmwareExe analysis — overview

Analyzed binary: firmwareExe (20.9 MB, ELF 32-bit MIPS32r2, Ingenic XBurst2 SoC, Linux 3.10.14, not stripped — full C++ symbols). Machine identifies itself as "Creator 5 Pro", cloud backend api.voxelshare.com.

The single most important finding

The printer already runs Klipper. firmwareExe is NOT the motion firmware — it is the LVGL touchscreen UI + orchestration daemon. It:

starts Klipper with /usr/prog/klipper/start.sh &
talks to Klipper's native API socket at /tmp/uds (stock webhooks JSON: gcode/script, objects/query, objects/subscribe, …)
implements everything "smart" (toolchange orchestration, print lifecycle, filament runout auto-swap, calibration wizards, cloud/camera/LAN APIs) app-side, by sending G-code strings.

The Klipper fork itself ships no START/END/PAUSE/RESUME/CANCEL macros and no toolchange motion code — a print started from Mainsail/Moonraker gets none of that behaviour unless something re-provides it. That something is this repo: ff_toolchange.py + the config/macros.

System architecture

firmwareExe (touchscreen app)
 ├─ LVGL UI on /dev/fb0 + touch /dev/input/event2
 ├─ KlipperAPI ──/tmp/uds──► Klipper fork (/usr/prog/klipper)
 │                            ├─ mcu           main board: X/Y/Z, bed
 │                            ├─ eboard        /dev/ttyS5 carriage extruder driver
 │                            ├─ eheaterboard  /dev/ttyS4 4 hotend heaters + 24V
 │                            └─ levelboard    /dev/ttyS7 fixed under-bed cylinder
 ├─ DryingService ──/dev/ttyS3──► filament drying box (own MCU, not Klipper)
 ├─ OrcaServer / MQTT cloud / camera
 └─ /usr/data/firmwareRes/config/*.json — per-unit calibration + state

Printer facts

4-tool toolchanger: docked heads T0–T3 at X≈297 (250/280 are the staging and approach waypoints, not the docks), picked up by the X carriage with a lock motor. temperature_sensor motor_value exists (printer.motor.cfg) but the app only ever logged it -- no grab/release decision reads it; see 25-app-vs-klipper-ownership.md.
Bed ~250×250, 10×10 bed mesh from the carriage eddy ([probe], eboard:PG0). Nozzle XY/Z offset calibration uses a different sensor: the fixed inductive cylinder under the bed ([e_stop X/Y/Z] on levelboard:PD0).
4 filament channels, each a direct-drive extruder on its own head — there is no feed hub; manual_stepper gear_stepper is the tool LOCK motor (see 47-filament-load-recovered.md). Presence sensors fd_ex0..3, motion sensors fm_ex0..3.
Chamber heater + 4 fans + LED, front/top door switches.

Method

The binary is not stripped, so targeted questions are answered by reading symbols and disassembling straight from the file (capstone), rather than a full Ghidra project — Ghidra's auto-analysis wrongly marked the logging helpers noreturn and truncated ~916 functions (29k bogus CALL_RETURN overrides), so its decompile of exactly the interesting CommMgr methods was misleading until repaired. Addresses cited in these notes are verified against the live binary.

Notes map

Files ending -recovered are reconstructions of the stock app's behaviour; the matching -port note says what this repo actually shipped.

10-hardware.md — MCUs, serial ports, Klipper objects the UI expects
20-klipper-fork.md — fork delta: custom commands, the Tn interception
25-app-vs-klipper-ownership.md — which side owns which behaviour, and what is ported
30-toolchange.md — dock/grab/release sequences, sensors, mounted-tool state
40-offsets.md — where per-unit numbers live; per-tool offsets; the absolute print Z offset
44-vfa-calibration.md — VFA (motor torque-ripple) compensation: the stock chain, what applies it, and the numpy gap that stopped klippy booting
45-tool-offset-calibration.md — the Klipper port: storage layout, commands, guards
46-offset-calibration-recovered.md — the app's calibration sequence it was ported from
47-filament-load-recovered.md / 48-filament-load-port.md — load/unload/purge
49-runout-recovered.md — runout and clog handling (ported: ff-runout.cfg)
50-print-lifecycle.md — start/pause/resume/cancel/complete, address-verified
50a-nozzle-clean-recovered.md / 50b-nozzle-clean-port.md — the pre-print nozzle clean
51-pa-calibration-recovered.md — automatic pressure advance: the sweep, and how to port it
60-background.md — filament system, calibration flows, config keys (background context)
70-error-codes.md — full E-code table (behavioral spec)
80-s6-migration.md — the prefix root and s6 supervision plan
85-packaging.md — apk vs opkg, why the first answer was opkg, and the migration to apk that reversed it

4.8 KiB Raw Blame History Unescape Escape