Sans is the native touchscreen application for the Libreflip MVPrototype book scanner. One in-process controller thread owns authoritative Machine state and device adapters; the egui render loop sends typed intents and renders snapshots without owning machine policy.
Build and test the active workspace with:
cargo build --workspace
cargo test --workspaceThe repository pins Rust 1.98.0 in rust-toolchain.toml.
The sans tests include rendered-pixel proofs that the previews keep every edge of the crop and stay one-to-one at 100%. They render through wgpu and need an adapter: Metal on macOS, or Mesa's lavapipe Vulkan driver on Linux (sudo apt-get install libvulkan1 mesa-vulkan-drivers). Without an adapter each proof prints a SKIPPED pixel proof notice and passes. Set SANS_REQUIRE_PIXEL_PROOF=1 to make a missing adapter fail instead, as CI does:
SANS_REQUIRE_PIXEL_PROOF=1 cargo test -p sansStart the native application with the normal Machine-profile path:
cargo run -p sansSans opens maximized with its window decorations, so the desktop decides the usable size after its title bar and menu bar. It respects the desktop's scale factor. On a desktop it runs in a normal resizable window at any size down to 280x240 points. Every screen keeps its status line at the top and its actions, such as Capture pair and Exit, in a bar at the bottom. Everything between scrolls by finger or mouse drag, mouse wheel, or the scroll bar.
Use cargo run -p sans -- --config /path/to/sans.toml for an explicit development or deployment profile. The normal path is $XDG_CONFIG_HOME/sans/sans.toml, falling back to ~/.config/sans/sans.toml.
Sans logs to stderr. Errors and warnings, such as a failed Capture pair, a refused Monospace command or an unconfirmed Stop, are always logged. Pass -v after Cargo's -- (cargo run -p sans -- -v) for operator operations, Stop changes and lift-axis link changes, -vv for every Monospace command and reply and every ODrive command and queued write, and -vvv for ODrive reads as well. RUST_LOG adds directives on top of that filter, for example RUST_LOG=sans_core::hardware=debug; a directive replaces only the one for the module it names, so other modules keep their warnings.
On first start, Sans writes the parseable sans.example.toml template to the selected path and opens a fatal screen naming that path. Close Sans, fill every <...> placeholder, commission both zero page-width bounds, then restart. A relative data_root is resolved against the profile location and must be writable.
The profile is schema version 4. For a version 2 profile, remove current_limit_a, velocity_limit_mm_s, acceleration_limit_mm_s2 and deceleration_limit_mm_s2 from [odrive.lift_axis], replace motion.touchdown_press_percent with motion.touchdown_press_current_a in amps, flip direction, negate and swap the travel bounds, then set schema_version = 4. Check that mm_per_turn includes gearbox reduction. For an upstream version 3 profile with positive-down bounds, flip direction, negate and swap the bounds, and set version 4; keep already negative-down bounds unchanged. For a version 1 profile, remove boards.ligature_path, add [odrive], then apply the version 2 changes. Compare against a freshly generated template.
The active production workspace contains sans-app/ and sans-core/. The old HTTP server, worker, remote CLI, shared-types crate, and processing stubs are not production workspace members.
scripts/pi-run builds a binary for a 64-bit Raspberry Pi, uploads it, and runs it in the foreground. Sans uses the Pi's touchscreen; diagnostics use the SSH terminal:
scripts/pi-run pi@sans-pi.local
scripts/pi-run pi@sans-pi.local -- --config /home/pi/sans-test.toml
scripts/pi-run --binary ./sans --env WAYLAND_DISPLAY=wayland-1 sans-pi
scripts/pi-run --bin hw_diag pi@sans-pi.local -- --port /dev/ttyACM0
scripts/pi-run --bin lift_diag pi@sans-pi.local -- \
--config /home/pi/sans.toml --log /home/pi/lift-01.csv--bin selects sans by default, or hw_diag or lift_diag. The build uses cross build --package <package> --bin <name> --release --locked --target aarch64-unknown-linux-gnu and honors CARGO_TARGET_DIR. Sans is in package sans; both diagnostics are in sans-core. Pass --binary <local-path> to upload a prebuilt aarch64 binary instead, keeping --bin to select its remote name and desktop requirements. Arguments after -- reach the selected program unchanged. Each --env NAME=VALUE is set on the Pi before Sans chooses its display.
The binary is streamed over SSH to ~/.local/bin/<name>-dev, so each tool has its own development executable. The upload goes to a temporary file beside it; the byte count is checked, and the file is renamed into place only if it matches, so a broken upload leaves the previous executable as it was. The program runs through ssh -tt, and its exit status is returned. Both connections pass -x, so a ForwardX11 yes SSH setting cannot send the UI to your own display. Build, upload, and display failures stop the command with a nonzero status.
Sans selects the Machine profile on the Pi exactly as it does locally, from $XDG_CONFIG_HOME/sans/sans.toml or ~/.config/sans/sans.toml there. The script never copies, edits, or uploads a profile, and it does not forward your local XDG_CONFIG_HOME.
Requirements:
- 64-bit Raspberry Pi OS on a Pi 4 or newer, with the runtime libraries the CI binary links against (
libv4land the desktop's Wayland or X11 client libraries). - For
sans, an active desktop session on the Pi, owned by the SSH user. An existingDISPLAYorWAYLAND_DISPLAYis kept. Otherwise the script uses the firstwayland-*socket in the remoteXDG_RUNTIME_DIR, skipping lock files. If there is no socket, it stops and suggests--env WAYLAND_DISPLAY=wayland-0or--env DISPLAY=:0. A Wayland display name such aswayland-0resolves insideXDG_RUNTIME_DIR, so if the SSH session does not set it, also pass--env XDG_RUNTIME_DIR=/run/user/<uid>. Diagnostics do not need a desktop session. - Locally,
crosswith a running Docker engine, or--binary. The cross 0.2.5 images exist only forlinux/amd64, so the script runscrosswithDOCKER_DEFAULT_PLATFORM=linux/amd64. On Apple Silicon this runs the build under amd64 emulation (OrbStack or Docker Desktop with Rosetta), which is slower than a native build. Podman ignores that variable; on an arm64 host, use Docker or--binary. <host>is passed tosshunchanged: eitheruser@hostname, or an SSH config alias whoseHostNameandUsercome from your SSH configuration. Port, identity, and jump hosts also come from that configuration. Key authentication is recommended, because the command connects twice.- A POSIX login shell on the Pi. The script never uses
sudo, installs packages, or kills remote processes.
Use the command only during supervised hardware testing. Stop any other Sans instance on the Pi first, because both would open the same serial port and cameras. What happens to Sans on Ctrl-C or when the SSH connection drops has not been validated on hardware, so check that the Machine has reached a safe state before you walk away.
The profile is a complete, versioned commissioning file; the scan workflow never edits it. Protocol baud rates and the 3840×2160 MJPEG camera profile stay fixed in code. Structural validation rejects unstable Camera identities, invalid crops or rotations, nonpositive or unordered fields, and commissioned actuation values above the resolved Issue #15 starting anchors. Those seven Lift-percentage values are immutable software maxima; profile edits may only lower them. Lift requests without a current override use motion.touchdown_press_current_a; the diagnostic CLI requires explicit amps. The Touchdown press current has no software maximum: it is bounded by the ODrive's own current limit. The separately decided Stop-terminal deadline has an immutable 500 ms maximum, and profiles may lower it. Saves are direct truncating complete-file writes and report errors; they make no atomic replacement or storage-synchronization claim.
The [odrive] section names the lift-axis board by USB serial. Its polling interval, telemetry age and request deadlines are configured inside immutable bounds in code. The run 16 summary records measured diagnostic-runner timing. The optional [odrive.lift_axis] table holds the mechanism values; while it is absent the lift axis stays blocked and Sans substitutes no default. For now the profile holds no velocity, acceleration, deceleration or current limits, and uses the limits stored on the board, so commission them there. The board limits are the ceilings, and commissioned travel bounds also apply. Touchdown first applies the requested press-current limit, at most the board's own limit, then sets the temporary firmware velocity limit and torque mode. The hold and lift-away keep the press current. Lift-away restores the velocity settings before moving, and the following motion restores the board's current limit. With the table present and the cameras, Monospace and lift-axis link live, the touchscreen offers Home, which moves the axis only after the operator consents. Supervised commissioning through the diagnostic CLI is recorded in the run 16 summary.
Lift-axis millimetres are 0 at Home and negative downward; commission direction so this holds. mm_per_turn is travel per motor revolution, including the gearbox: with a 10:1 reduction, divide pulley travel per revolution by 10. The table also carries ten required tuning values for host lift-axis operations: position tolerance, stationary velocity, move, Home and cancel timeouts, and the Touchdown grace, dwell, no-progress tolerance, saturation percent and hold depth. Each must be positive and finite, the saturation percent at most 100, and the hold depth at most a 5 mm software policy cap. Tune these values for the mechanism; the run 16 summary records the tested profile. A table missing any of them fails to parse with the field named. The application calls LiftOperations for Home, Stop and Clear Stop. Fresh native homed evidence with ready, error-free encoder feedback establishes Position trust, including after reconnect. Stop and Disarm retain that reference; Clear Stop does not arm or resume work. Home remains available explicitly from Idle.
Sans talks to the MKS ODrive Mini over its native Fibre USB vendor interface (interface 2, bulk 0x03/0x83) and leaves the CDC serial interfaces to the kernel. On each connection it checks the board's USB serial and serial_number against the profile, checks that every endpoint Sans uses exists with the right type and access, and commands the axis idle. It also reads the board's own current limit and trajectory deceleration. The gate writes no limits. Touchdown temporarily selects torque control with a bounded firmware velocity limiter and lowers the current limit to its press current; the lift-away move keeps it, and the motion after that restores the board's own limit as read at connection. Position-move cancellation estimates braking reach from the board's deceleration. Touchdown checks measured travel without projecting a stopping point, since book contact is intended to stop the descent. Other endpoints may differ between firmware builds without blocking the link. Sans never saves, erases, reboots or flashes the board, and restores position/trapezoidal control before lift-away, Arm or Home. The Setup screens show the lift-axis status, the discovered identity and descriptor CRC, with a reconnect action in the action bar; the capture preview keeps its full body for the camera views.
Reconnection happens only from the touchscreen's reconnect button. A new connection opens only after the previous one has released the device: each USB half cancels its pending transfers and waits for nusb to reap them, and a background reaper keeps trying without reporting release early. Each attempt waits at most the connection gate deadline for that release. The USB open itself is not interrupted; on Linux it only reads sysfs and cached descriptors and claims the interface, and an attempt that does not finish within the gate deadline is reported as blocked.
An urgent command overtakes ordinary commands that have not left the host, so a queued move cannot follow a disarm. A command packet never leaves after its deadline, and an arm, Home or move write never leaves after a link fault, after a disarm is accepted, or once the sample it was accepted on is stale; such commands are retired as not transmitted. A new disarm is always possible while the device is open. Non-finite telemetry faults the link. Ignored replies are counted on the panel and logged to standard error, and a shown sample's age keeps updating, so a silent link never looks fresh.
The Pi user running Sans needs access to the USB device. A udev rule such as the following, in /etc/udev/rules.d/70-odrive.rules, grants it to the plugdev group:
SUBSYSTEM=="usb", ATTR{idVendor}=="1209", ATTR{idProduct}=="0d32", MODE="0660", GROUP="plugdev"
Automated tests run the link against a fake Fibre device served from the captured schema. They show host behaviour against upstream fw-v0.5.1 semantics. The run 16 summary separately records supervised component evidence from the vendor board for #60.
Sans is the client of serif, the VM-hosted backend and web portal implemented in c-base_book-scanner. It registers each Scan session there as a job, uploads pages in the background at low priority, confirms the finished book by checksum, shows the access QR code, and deletes old confirmed books only when it needs the space. None of this is implemented yet. The wire contract is libreflip/serif docs/sans-serif-interface.md; the sans-side design is docs/serif-client.md.
cargo run -p sans-core --bin lift_diag -- --config <profile> --log <new.csv>
opens a supervised commissioning CLI for Home, Arm, Disarm, bounded moves,
Touchdown/press hold, lift-away, cancel and cross-board Stop. It uses the
production lift and Stop policies, records CSV evidence and starts without
motion. See the commissioning procedure for profile
prerequisites and commands. The run 16 summary
records successful Touchdown, hold, lift-away and physical-button Stop for #60;
the assembled-book workflow remains #31.
sans-core retains hw_diag and the Linux V4L2 camcal binary. Run them only during supervised hardware work while the sans application is stopped; they open devices directly, and hw_diag can energize relays.