Files
cardputerzero-sync/docs/building-and-installation.md

8.9 KiB
Raw Blame History

Building & Installation Guide

This guide covers building the ARM64 Debian package for CardputerZero, installing the background receiver on macOS, running the desktop SDL2 UI simulator, and running all test suites.


1. Prerequisites

macOS Host

  • Python: 3.9+ (macOS system/Homebrew Python 3; both mac-receiver and device-daemon use the Python standard library with zero third-party pip dependencies).
  • Tailscale: Signed into the same private tailnet as your CardputerZero.
  • Docker Desktop (for building the CardputerZero .deb on Mac): Apple Silicon or linux/arm64 binfmt/emulation support enabled.
  • Homebrew packages (only needed for building/running the macOS SDL2 desktop UI simulator & C++ tests):
    brew install cmake pkg-config sdl2 freetype sqlite3
    

CardputerZero Device

  • M5Stack CardputerZero running Raspberry Pi CM0 ARM64 Debian Bookworm (or compatible arm64 Debian) with systemd --user, APPLaunch, and tailscale connected to your tailnet.
  • Runtime packages declared by packaging/debian/control: python3 (>= 3.9), libsqlite3-0, libfreetype6.
  • Native build packages (only required if compiling .deb directly on the CardputerZero instead of via Docker):
    sudo apt-get update
    sudo apt-get install -y build-essential cmake pkg-config libsqlite3-dev libfreetype-dev dpkg-dev python3
    

2. Optional: Bundling TrueType Fonts (Inter + JetBrains Mono)

At runtime, cp0-sync-ui searches for Sans and Mono fonts in this order (device-ui/src/app_ui.cpp):

  1. CP0_FONT_SANS / CP0_FONT_MONO environment variable overrides
  2. /usr/share/cp0-sync/fonts/ (Inter-Regular.ttf / Inter.ttf and JetBrainsMono-Regular.ttf / JetBrainsMono.ttf)
  3. assets/fonts/ relative to working directory
  4. System Debian (DejaVuSans.ttf, LiberationSans-Regular.ttf, /usr/share/fonts/truetype/inter/...) or macOS (/System/Library/Fonts/SFNS.ttf, Menlo.ttc, etc.)
  5. Built-in crisp 5×7 pixel bitmap font (kFont5x7) if no .ttf / .ttc font is found

If you want Inter and JetBrains Mono bundled inside the .deb at /usr/share/cp0-sync/fonts/, place .ttf or .otf font files in packaging/fonts/ (or device-ui/assets/fonts/) before running packaging/build-deb.sh:

packaging/fonts/
├── Inter-Regular.ttf
└── JetBrainsMono-Regular.ttf

Note: When building the CardputerZero target inside a clean container or minimal Bookworm image without bundled fonts, installing fonts-dejavu-core on the device also activates FreeType anti-aliased rendering automatically without needing custom files in packaging/fonts/.


3. Building the CardputerZero ARM64 .deb

packaging/build-deb.sh uses packaging/Dockerfile.arm64 (--platform linux/arm64, debian:bookworm-slim) to compile device-ui with -DCP0_UI_TARGET_DEVICE=ON (Linux fbdev + evdev), run C++ unit tests inside the container, and package cp0-sync_1.0.0_m5stack1_arm64.deb:

./packaging/build-deb.sh

Output artifact:

packaging/dist/cp0-sync_1.0.0_m5stack1_arm64.deb

(packaging/dist/ and device-ui/build-arm64/ are gitignored.)

build-deb.sh Options

Flag Description
(none) Build inside --platform linux/arm64 Docker container and copy .deb to packaging/dist/
--local Compile device-ui (CP0_UI_TARGET_DEVICE=ON) and build .deb directly on a Linux ARM64 host
--stage-only <dir> Stage package file tree without calling dpkg-deb (requires existing binary or --ui-bin)
--ui-bin <path> Use a prebuilt cp0-sync-ui binary instead of recompiling
--out-dir <dir> Write .deb into a custom directory instead of packaging/dist/

Method B: Build Directly on CardputerZero (or ARM64 Linux Host)

git clone <your-repo-url> cardputerzero-sync
cd cardputerzero-sync
sudo apt-get update && sudo apt-get install -y build-essential cmake pkg-config libsqlite3-dev libfreetype-dev dpkg-dev python3
./packaging/build-deb.sh --local

Package Contents (cp0-sync_1.0.0_m5stack1_arm64.deb)

  • /usr/bin/cp0-sync-ui — 320×170 companion UI (fbdev + evdev binary)
  • /usr/bin/cp0-syncd — Background Python sync daemon CLI entrypoint
  • /usr/lib/cp0-sync/cp0_syncd/*.py — Sync daemon Python modules
  • /usr/lib/systemd/user/cp0-syncd.service — systemd --user service unit
  • /usr/share/APPLaunch/applications/cp0-sync.desktop — Photo Sync app launcher entry
  • /usr/share/APPLaunch/share/images/cp0-sync.png — 80×80 app icon
  • /usr/share/cp0-sync/fonts/* — Optional bundled fonts (if provided at build time)

4. Installing & Uninstalling on CardputerZero

Copy the .deb over Tailscale and install:

scp packaging/dist/cp0-sync_1.0.0_m5stack1_arm64.deb pi@<cardputerzero-host>:/tmp/
ssh pi@<cardputerzero-host> "sudo dpkg -i /tmp/cp0-sync_1.0.0_m5stack1_arm64.deb"

If dpkg reports missing shared runtime dependencies (libfreetype6 or libsqlite3-0), resolve them with:

sudo apt-get install -f -y

What postinst / prerm Do

  • postinst (configure): Runs systemctl --global enable cp0-syncd.service || true and best-effort restarts cp0-syncd.service for active logged-in user sessions via loginctl.
  • prerm (remove / deconfigure): Stops active user instances, runs systemctl --global disable cp0-syncd.service || true, and cleans Python __pycache__ files under /usr/lib/cp0-sync without deleting your ~/.config/cp0-sync/ or ~/.local/share/cp0-sync/ data.

Verify the background service is active under your user session:

systemctl --user status cp0-syncd.service

To uninstall later:

sudo dpkg -r cp0-sync

5. Installing the Mac Receiver

On your Mac, run the LaunchAgent installer from the repository:

./mac-receiver/bin/cp0-mac-sync install-service
./mac-receiver/bin/cp0-mac-sync status

This creates and loads ~/Library/LaunchAgents/com.cardputerzero.photosync.plist (RunAtLoad=true, KeepAlive=true), starting mac-receiver/bin/cp0-mac-receiver automatically at login.

(Optional) Symlink the CLI scripts into your PATH (both entrypoints resolve the mac-receiver/ package cleanly through symlinks):

mkdir -p ~/.local/bin
ln -sf "$(pwd)/mac-receiver/bin/cp0-mac-sync" ~/.local/bin/cp0-mac-sync
ln -sf "$(pwd)/mac-receiver/bin/cp0-mac-receiver" ~/.local/bin/cp0-mac-receiver

To stop and remove the LaunchAgent:

./mac-receiver/bin/cp0-mac-sync uninstall-service

6. Building & Running the Desktop Simulator (device-ui)

You can run and visually inspect the 320×170 UI natively on macOS using SDL2 without CardputerZero hardware:

cmake -S device-ui -B device-ui/build -DCP0_UI_BUILD_TESTS=ON -DCP0_UI_BUILD_APP=ON
cmake --build device-ui/build

Run a scaled 3× simulator window (connected to ~/.config/cp0-sync/ or offline fallback):

./device-ui/build/cp0-sync-ui --sim --scale 3

Render a headless 320×170 PPM snapshot without opening a window:

./device-ui/build/cp0-sync-ui --render-test /tmp/status_dark.ppm --theme dark --tab status
./device-ui/build/cp0-sync-ui --render-test /tmp/folders_light.ppm --theme light --tab folders

CMake Options Reference (device-ui/CMakeLists.txt)

Option Default Notes
CP0_UI_BUILD_TESTS ON Builds test_ipc_and_theme and test_ui_navigation
CP0_UI_BUILD_APP ON Builds the cp0-sync-ui executable (set OFF to build only cp0_ui_core + tests)
CP0_UI_TARGET_DEVICE OFF Linux only: targets /dev/fb0 + /dev/input/event* instead of SDL2 (errors cleanly on non-Linux hosts)
(Optional LVGL) auto-detected If system lvgl (find_package(lvgl) / pkg-config lvgl) is present, enables CP0_HAS_LVGL=1 style hooks alongside the built-in 320×170 renderer; never downloads over network via FetchContent

7. Running All Test Suites

All test suites use zero third-party Python dependencies (unittest stdlib) and CTest:

# 1. Mac Receiver unit & HTTP server tests (24 tests)
PYTHONPATH=mac-receiver python3 -m unittest discover -s mac-receiver/tests -v

# 2. Device Daemon config, SQLite store, watcher, uploader & IPC tests (25 tests)
PYTHONPATH=device-daemon:mac-receiver python3 -W error -m unittest discover -s device-daemon/tests -v

# 3. Companion UI C++ tests (2 CTest targets: test_ipc_and_theme, test_ui_navigation)
cmake --build device-ui/build && ctest --test-dir device-ui/build --output-on-failure -V

# 4. Packaging validation tests (7 tests)
python3 -m unittest discover -s packaging/tests -v

(Note on macOS sandboxing: test_server.py, test_daemon_integration.py, and test_ipc_and_theme open local TCP loopback or AF_UNIX sockets; if running inside a restricted sandbox that blocks sockets with Operation not permitted / EPERM, run them outside the sandbox.)