27 KiB
CardputerZero Photo Sync — Design Specification
Date: 2026-11-18
Project Size: Project (3 coordinated deliverables: on-device background sync daemon, on-device LVGL companion UI packaged as an arm64 .deb, and macOS receiver LaunchAgent + CLI)
1. Intent & Why
The M5Stack CardputerZero (powered by the Raspberry Pi CM0, running ARM64 Debian Linux — not the ESP32-based Cardputer/ADV) includes an 8MP Sony IMX219 camera and built-in Camera app, plus support for third-party camera tools and SD card storage. Getting photos off the device currently requires manual copying or plugging in cables, and fails whenever the user's Mac is asleep or away from home Wi-Fi.
This project provides automatic, reliable, one-way photo syncing from the CardputerZero to the user's Mac over Tailscale:
- Photos taken with the native Camera app (or any other camera/screenshot app saving into a watched directory) are detected automatically in the background.
- When the Mac is asleep or offline, photos remain safely queued on the CardputerZero and upload automatically as soon as the Mac becomes reachable again.
- An
APPLaunchcompanion app gives the user an on-device frontend on the 320×170 screen to configure watched folders, pick the target Mac, trigger a manual sync, and view queue status and logs.
2. Goals, Non-Goals, and Anti-Goals
Goals
- App-agnostic background watching: Watch one or more user-defined directories on the CardputerZero so photos from the built-in Camera app or any other app are captured automatically without opening the sync UI.
- Resilient offline queueing: Persist queued uploads across CardputerZero reboots and Mac sleep/wake cycles; resume cleanly with zero manual intervention once the Mac wakes.
- Tailscale transport: Sync transparently over the user's existing Tailscale network (both on LAN and remotely).
- One-way "upload once" guarantees: Track uploaded files locally so moving, renaming, or deleting photos on the Mac after arrival never causes re-uploads.
- Native
APPLaunchcompanion UI: Provide a keyboard-first 320×170 LVGL UI (1:Status,2:Folders,3:Logs) integrated into the CardputerZero launcher. - Configurable Mac destination: Store received photos on the Mac in an easily changeable root folder, defaulting to
~/Pictures/CardputerZero/<watched-folder-name>/.
Non-Goals
- Building a custom camera capture UI or replacing the native Camera app.
- Two-way sync or deleting photos on the CardputerZero when deleted on the Mac.
- Cloud relay servers, external object storage, or multi-Mac sync tracking (User Decision) — sync targets a single configured Mac; if multi-Mac sync is ever needed later, it is out of scope for v1.
- Publishing or submitting packages to the official
CardputerZeroRepositoryAppStore viaCardputerZero-AppBuilder(czdev) (User Decision).
Anti-Goals
- Uploading partial/in-progress writes while the camera is still flushing an image to disk.
- Silently overwriting different photos that share a filename (e.g.,
IMG_0001.jpgafter a counter reset). - Requiring heavy typing of Linux file paths or Tailscale MagicDNS hostnames on the 46-key matrix keyboard (
fn/symlayers) when interactive pickers can handle selection.
3. Constraints
- Device Hardware (CardputerZero):
- Broadcom BCM2837 / RP3A0 (Raspberry Pi CM0, quad-core ARM Cortex-A53 @ 1 GHz), 512 MB LPDDR2 RAM.
- 1.9-inch 320×170 LCD, no touchscreen.
- 46-key physical QWERTY matrix keyboard (
cp0-keys) wherefn,shift, andsymmodify keys via hold, tap-latch, or double-tap lock (e.g., arrows arefn + F/X/Z/C, Delete isfn + Backspace).
- Device OS & Packaging:
- ARM64 Debian Linux running
APPLaunch.serviceas asystemd --userservice. - Apps register a
.desktopfile under/usr/share/APPLaunch/applications/and icon assets under/usr/share/APPLaunch/share/images/. - Distributed as a local
arm64Debian package (cp0-sync_1.0.0_m5stack1_arm64.deb) built via CMake/CPack (in an ARM64 Docker container or directly on the CardputerZero over SSH) for personal installation viasudo apt install ./cp0-sync_1.0.0_m5stack1_arm64.deb(User Decision).
- ARM64 Debian Linux running
- Network & Mac Environment:
- Tailscale is already installed and running on both the CardputerZero and the Mac on a strictly private tailnet of authorized devices (User Decision).
- Mac receiver runs on macOS as a user background agent (
LaunchAgent).
4. Approaches Considered & Selected
Three architectural approaches were evaluated:
-
Approach 1 (Selected by User): Official
CardputerZero/TemplateC++ (LVGL UI) + Zero-Dependency Python 3 Sync Daemon & Mac Receiver- How it works: The
APPLaunchfrontend (cp0-sync-ui) is built in C++ / LVGL usingCardputerZero/Template(CMake + CPack.deb, with local macOS SDL2 simulator support). Both the on-device backgroundsystemdservice (cp0-syncd) and the Mac receiver (cp0-mac-receiver+cp0-mac-syncCLI) are written in pure Python 3 standard library (sqlite3,http.server/urllib,ctypesLinuxinotify). - Tradeoffs: Native LVGL performance and full
CardputerZero/Template/APPLaunchcompatibility without AppStore/CI submission constraints, while keeping networking, hashing, queueing, and filesystem watching in zero-dependency Python (~12 MB RSS) that shares protocol logic cleanly between device and Mac and is easy to inspect/debug on-device.
- How it works: The
-
Approach 2: All-C++ Device Package (LVGL UI + C++ Daemon) + Python Mac Receiver
- How it works: Both
cp0-sync-uiandcp0-syncdare compiled C++ binaries usinglibcurl,libsqlite3, and<sys/inotify.h>. - Tradeoffs: Lowest device RAM usage (~3 MB RSS) and single-language device codebase, but requires
libcurl/sqlite3ARM64 cross-compile sysroot dependencies and recompiling the.debfor any daemon change.
- How it works: Both
-
Approach 3: All-Python Stack (Python Framebuffer/SDL UI + Python Daemon + Python Mac Receiver)
- How it works: Everything, including the 320×170 UI, is written in Python (
pygame/pillow). - Tradeoffs: Avoids C++ cross-compilation, but diverges from the official
CardputerZero/TemplateLVGL UX and adds heavy Python graphics dependencies.
- How it works: Everything, including the 320×170 UI, is written in Python (
5. Detailed Architecture & Component Design
Attribution key: Items marked (User Decision) were explicitly requested or confirmed by the user. Items marked (Our Call) are design decisions filled in during specification with rationale provided.
5.1 Repository Layout (Our Call)
Monorepo under cardputerzero-sync/:
device-daemon/— Python 3cp0-syncdservice, SQLite queue store,inotifywatcher, HTTP/Tailscale uploader, Unix socket control server, and unit tests.device-ui/—CardputerZero/Template-based C++/LVGL companion app (cp0-sync-ui), SDL desktop simulator preset,APPLaunch.desktop+ icon assets, and CMake/CPack.debpackaging config.mac-receiver/— Python 3cp0-mac-receiverHTTP server,cp0-mac-syncCLI helper,LaunchAgentplist installer, and unit tests.packaging/— Debian maintainer scripts (postinst,prerm,postrm),systemduser unit file (cp0-syncd.service), and shared protocol schema docs.
5.2 On-Device Background Sync Daemon (cp0-syncd)
Service Lifecycle & Shared Storage (Our Call)
- Installed at
/usr/bin/cp0-syncdwith asystemd --userservice at/usr/lib/systemd/user/cp0-syncd.service(matchingAPPLaunch.service, which also runs undersystemd --user). - Debian
postinstrunssystemctl --global enable cp0-syncd.serviceso the daemon starts automatically on boot for the device's desktop user under the exact same$HOMEand UID ascp0-sync-ui. - Shared state paths (also overrideable via environment variables
CP0_SYNC_CONFIG,CP0_SYNC_DB,CP0_SYNC_SOCKfor testing):- Config file:
~/.config/cp0-sync/config.json - SQLite database:
~/.local/share/cp0-sync/state.db(WAL mode enabled socp0-sync-uican read live status concurrently without locking the daemon) - Control Unix domain socket:
${XDG_RUNTIME_DIR:-/tmp}/cp0-sync.sock
- Config file:
Configuration Schema (~/.config/cp0-sync/config.json) (Our Call + User Decisions)
target_host: Tailscale MagicDNS hostname or100.x.y.zIP of the Mac (initially empty until configured in UI or CLI; daemon stays idle and logsNo target host configuredwithout error loops).target_port: Integer, default8765.theme:"dark"or"light"(default"dark"), controlling the UI's Zinc Dark vs. Zinc Light palette (User Decision).- No
auth_tokenrequired (User Decision): Because the tailnet contains strictly private, authorized devices, transport security relies on Tailscale WireGuard encryption plus the Mac receiver's Tailscale CIDR allowlist (100.64.0.0/10,fd7a:115c:a1e0::/48, and loopback). watched_folders: List of objects{ "id": "<uuid-or-slug>", "path": "/abs/path", "label": "Camera", "enabled": true }.- Label uniqueness: Derived initially from folder basename (
Camera,DCIM,Screenshots), automatically disambiguated if two watched paths share a basename (e.g.,DCIM,DCIM-2) so Mac subfolders never collide. - First-run default (User Decision): On first boot when no config exists,
cp0-syncdpre-populates a single default watched folder:~/Pictures/DCIM/Camera(i.e.,/home/pi/Pictures/DCIM/Camera, labelCamera), matching the native CardputerZero Camera app. Additional folders (such as SD card paths or other app output directories) can be added anytime via Tab2:Folders. - Overlap prevention:
add_folderresolves canonical paths (os.path.realpath) and warns/blocks (or skips duplicate ingestion) if a newly added folder overlaps an already-watched ancestor/descendant directory.
- Label uniqueness: Derived initially from folder basename (
extensions: Case-insensitive media allowlist, defaulting to[".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp", ".dng", ".raw", ".mp4", ".mov"].ignore_prefixes:[".", "~"],ignore_suffixes:[".part", ".tmp", ".crdownload"].
File Watching & Queue Ingestion (Our Call)
- Startup reconciliation: On daemon startup (and whenever a watched folder is added), recursively walk each enabled watched folder (
os.walkwithfollowlinks=False). Any matching file not already recorded asSYNCED(same path, size, andmtime_ns— or matching SHA-256) is enqueued asPENDING. - Real-time
inotifywatcher & mount resilience: Pure-Pythonctypesbindings againstlibc.so.6(inotify_init1,inotify_add_watch,inotify_rm_watch) watching each directory and dynamically attaching watches to newly created subdirectories (IN_CREATE | IN_ISDIR).- If a configured watched folder does not currently exist (e.g., an unmounted SD card path), the daemon keeps it in config (showing
! unmounted/missingin UI) and watches its nearest existing ancestor directory (or re-checks on a periodic timer) so inserting an SD card later automatically attaches watches and triggers a scan. - Only reacts to
IN_CLOSE_WRITEandIN_MOVED_TOevents (neverIN_CREATEfor files), guaranteeing the camera app has finished writing and closed the file descriptor before hashing or uploading. - Enqueues newly closed/moved media files immediately into SQLite (
status='PENDING') and wakes the uploader thread.
- If a configured watched folder does not currently exist (e.g., an unmounted SD card path), the daemon keeps it in config (showing
SQLite State Schema (state.db) (Our Call)
filestable:idINTEGER PRIMARY KEYfolder_idTEXT NOT NULLabs_pathTEXT NOT NULLrel_pathTEXT NOT NULL (relative to watched folder root, preserving any camera date subdirectories)size_bytesINTEGER NOT NULLmtime_nsINTEGER NOT NULLsha256TEXT NOT NULLstatusTEXT NOT NULL (PENDING,UPLOADING,SYNCED,FAILED)retry_countINTEGER DEFAULT 0last_errorTEXTdiscovered_atINTEGER NOT NULL (Unix epoch ms)synced_atINTEGER- Unique index on
(folder_id, rel_path, sha256)— ensures global one-way "upload once" behavior for the configured single-Mac target (User Decision) even if files are later moved or deleted on the Mac, while re-uploading if a file at the same path is genuinely modified/replaced with different content.
logstable:idINTEGER PRIMARY KEY AUTOINCREMENTtsINTEGER NOT NULL (Unix epoch ms)levelTEXT NOT NULL (INFO,WARN,ERROR)messageTEXT NOT NULL- Automatically pruned to the newest 500 rows to bound SD/eMMC wear and disk usage.
metatable:- Key-value runtime summary (
mac_online,mac_dest_root,last_probe_ts,next_retry_ts,last_sync_ts,last_synced_file) written by the daemon so Tab1:Statusrenders instantly without expensive queries.
- Key-value runtime summary (
Wake Probe, Upload Loop & Backoff (Our Call)
- When
PENDINGrows exist andtarget_hostis configured:- Daemon sends
GET http://<target_host>:<target_port>/healthwith a short 3-second connect/read timeout. - If unreachable (Mac sleeping, offline, or Tailscale tunnel asleep): marks
mac_online = falseinmeta, sleeps with adaptive backoff (5s → 10s → 20s → 40s → 60s max, resetting to 5s whenever a new photo is captured), and keeps everything queued safely in SQLite. - If
200 OK: marksmac_online = true, cachesmac_dest_rootfrom the health JSON (for display on Tab1:Status), and streamsPENDINGfiles sequentially in FIFO order (discovered_at ASC) viaPOST /upload. - Failure handling: Network drop,
5xx, or auth/access rejection (401/403) keeps the file asPENDING(pausing the upload queue with backoff and surfacing an error state inmeta/logsrather than poisoning individual files). Only per-file payload rejections (400/413/422) mark that specific fileFAILEDwithlast_errorso it doesn't block the rest of the queue; the user can retry failed items from Tab3:Logs([R]). - Immediate wake on command:
Sync Nowor config edits over the Unix socket interrupt the backoff sleep immediately (threading.Event.set()), resetting backoff and probing at once.
- Daemon sends
Local Control IPC Protocol (/tmp/.../cp0-sync.sock) (Our Call)
Newline-delimited JSON request/response over Unix stream socket:
{"cmd": "status"}→ returns currentmeta+ queue counts + watched folder list with per-folderpending/syncedcounts.{"cmd": "sync_now"}→ interrupts sleep, resets retry backoff, triggers immediate folder rescan +/healthprobe + queue flush.{"cmd": "add_folder", "path": "...", "label": "..."}→ validates directory exists, saves config, attachesinotifywatch, triggers rescan.{"cmd": "remove_folder", "folder_id": "..."}→ removes folder fromconfig.json, detachesinotifywatch, purges un-syncedPENDINGqueue entries for that folder (never touches files on disk).{"cmd": "set_target", "host": "...", "port": 8765}→ savesconfig.jsonand immediately probes new target.{"cmd": "set_theme", "theme": "dark" | "light"}→ persists the active UI theme inconfig.json.{"cmd": "retry_failed"}→ flipsFAILEDrows back toPENDINGand triggerssync_now.
5.3 Mac Receiver & CLI (cp0-mac-receiver & cp0-mac-sync)
User-Specified Requirements (User Decision)
- Lightweight receiver daemon running on the Mac (
LaunchAgent), communicating over Tailscale. - Stores synced photos under
~/Pictures/CardputerZero/by default, grouped into subfolders by watched folder label (~/Pictures/CardputerZero/<folder_label>/<rel_path>). - Destination root path on the Mac must be easy to set and change.
Configuration & Service Management (Our Call)
- Config file:
~/.config/cp0-mac-sync/config.json:{ "dest_root": "/Users/<user>/Pictures/CardputerZero", "listen_host": "0.0.0.0", "listen_port": 8765, "notify_on_batch": true, "tailscale_only": true } - Logging:
~/Library/Logs/cp0-mac-sync.log(rotated at 5 MB, keeping 2 backups). LaunchAgent:~/Library/LaunchAgents/com.cardputerzero.photosync.plistwithRunAtLoad = trueandKeepAlive = true, managed vialaunchctl bootstrap/bootout.cp0-mac-syncCLI (installed to/usr/local/bin/cp0-mac-syncor~/.local/bin/cp0-mac-sync):cp0-mac-sync install-service— initializes config, creates default~/Pictures/CardputerZero, installs and loads theLaunchAgent.cp0-mac-sync uninstall-service— unloads and removes theLaunchAgent(keeps synced photos intact).cp0-mac-sync set-dir <path>— validates/creates<path>, updatesconfig.json, and reloads/notifies the receiver immediately (no manual plist editing).cp0-mac-sync set-port <port>— updates port and restarts theLaunchAgent.cp0-mac-sync status— prints service running state, Tailscale IP/MagicDNS name (viatailscale status --jsonif available), currentdest_root, and recent upload count.cp0-mac-sync logs [--follow]— displays or tails~/Library/Logs/cp0-mac-sync.log.
HTTP Receiver Protocol & Security (Our Call + User Decision)
Pure Python ThreadingHTTPServer:
- Source IP filtering (User Decision + Our Call): Because the user's tailnet contains strictly private/authorized devices, no pairing token is used. When
tailscale_onlyistrue(default), the receiver rejects any client IP outside Tailscale CGNAT (100.64.0.0/10), Tailscale IPv6 (fd7a:115c:a1e0::/48), or loopback (127.0.0.1,::1) with403 Forbidden. Listening on0.0.0.0:8765avoids binding failures if the Tailscale interface comes up after user login, while the CIDR allowlist guarantees LAN/public interfaces cannot reach it. GET /health: Returns200 OKJSON:{ "status": "ok", "version": "1.0.0", "hostname": "<mac-hostname>", "dest_root": "/Users/<user>/Pictures/CardputerZero" }POST /upload:- Headers:
Content-Length,X-CP0-Folder-Label,X-CP0-Rel-Path,X-CP0-SHA256,X-CP0-Mtime(Unix epoch seconds float/int). - Path traversal sanitization: Rejects (
400) empty/absolute paths or any..segment infolder_labelorrel_path; enforces resolved destination strictly insidedest_root. - Streaming & atomic commit:
- Streams request body in 64 KB chunks to
<target_dir>/.cp0-<uuid>.partwhile computing SHA-256 incrementally. - If stream disconnects prematurely or computed SHA-256 !=
X-CP0-SHA256, deletes.partfile and returns400/499. - If destination path already exists:
- Computes existing file's SHA-256; if identical, deletes
.partand returns200 {"status": "already_exists"}(deduplication on retry). - If different content exists at that name, renames destination to
<stem>_<YYYYMMDD_HHMMSS>_<sha8><ext>so no photo is ever overwritten.
- Computes existing file's SHA-256; if identical, deletes
- Atomically renames
.part→ final path (os.replace) and applies original capture timestamp viaos.utime. - Returns
200 {"status": "saved", "saved_path": "..."}.
- Streams request body in 64 KB chunks to
- Headers:
- Batch macOS Notification: A 5-second debounce timer fires a single native macOS notification via
osascript(display notification "Synced N photos to CardputerZero" with title "CardputerZero Sync") once a burst of uploads settles, rather than spamming one banner per photo.
5.4 CardputerZero Companion UI (cp0-sync-ui)
Visual & Design System — shadcn/ui Zinc Style for LVGL v9 (User Decision + Our Calls)
- Built on
CardputerZero/Templateusing C++ / LVGL v9 for the 320×170 display (User Decision). - Layout & Component Geometry (Option A: Bento Cards + Segmented Tabs) (User Decision):
- Top bar (24 px): Segmented
TabsListpill container (radius: 5px,padding: 2px) on the left (1 Status,2 Folders,3 Logswithradius: 4pxactive pill) + right-aligned pill statusBadge(radius: 999px,1pxborder:● Mac Online/● Mac Sleeping/↻ Syncing/○ No Target). - Main content (126 px): Full 320px width dedicated to the active tab:
1 Status: Two side-by-side borderedCardstat tiles (Pending QueueandTotal Synced,radius: 6px,1pxborder) above a full-width borderedTargetsummary card (Target <host>, retry/last-sync indicator, and→ <dest_root>/<folder>).2 Folders: Stacked borderedCardrows (radius: 6px,1pxborder) showing full path on the left and a pillBadge(queued/synced/missing) on the right.3 Logs: Monospace log list separated by1pxhairline row dividers (HH:MM:SS,OK/IN/WN/ERtag, message).
- Bottom key-hint bar (20 px):
<kbd>keycap badges (radius: 3px,1pxborder) paired with context-sensitive shortcut labels.
- Top bar (24 px): Segmented
- Dual Toggleable Theme Tokens (Zinc Dark & Standard Zinc Light) (User Decision):
- Zinc Dark (
"theme": "dark", default):--background:#09090b(zinc-950),--card:#09090b,--muted:#18181b(zinc-900),--border:#27272a(1px),--ring(focused row/control border):#d4d4d8,--foreground:#fafafa,--muted-foreground:#a1a1aa, active tab pill:#27272afill /#fafafatext.- Semantic accents (badges/dots only): Online/Synced
#4ade80, Sleeping/Queued#fbbf24, Missing/Error#f87171.
- Zinc Light (
"theme": "light", balanced standardshadcn/uilight skin):--background:#fafafa(zinc-50),--card:#ffffff,--muted:#f4f4f5(zinc-100),--border:#e4e4e7(1px),--ring(focused row/control border):#71717a(balanced neutral focus ring rather than stark high-contrast black),--foreground:#09090b,--muted-foreground:#71717a, active tab pill:#fffffffill with#e4e4e7border /#09090btext.- Semantic accents (badges/dots only): Online/Synced
#16a34a(#dcfce7badge fill), Sleeping/Queued#d97706(#fef3c7badge fill), Missing/Error#dc2626(#fee2e2badge fill).
- Zinc Dark (
- Typography (Our Call): Proportional sans-serif (
Interbundled and loaded via LVGL FreeType) for UI chrome, headers, tabs, and badges paired with monospace (JetBrains Monovia FreeType) for paths, stat counts, hostnames,<kbd>keycaps, and log timestamps. - Data access (Our Call): Polls
cp0-syncdover the Unix socket every 1 second while open (with direct read-only SQLite fallback to display cached state even if the daemon is restarting) and sends mutations (sync_now,add_folder,remove_folder,set_target,set_theme,retry_failed) over the socket.
Tab Views & Keyboard Map (Our Call)
Designed around the cp0-keys 46-key matrix so common actions do not require multi-key fn chords unless desired:
-
Global shortcuts (when no modal is open):
1/2/3: Jump directly toStatus,Folders, orLogstab.Enter: TriggerSync Now(sync_nowIPC) and flash feedback in the status banner.T: Toggle live between Zinc Dark and Zinc Light and persist"theme"viaset_themeIPC (User Decision). (When inside the Target Config or Directory Picker modal,Tretains its modal role of opening manual text input.)EscorQ: Quitcp0-sync-uiback toAPPLaunch(leavingcp0-syncdrunning in the background).- Navigation: Both
LV_KEY_UP/DOWN(fn+F/fn+X) andk/jmove selection/scroll;LV_KEY_LEFT/RIGHT(fn+Z/fn+C) also switch tabs.
-
Tab
1:Status:- Displays:
QUEUE: <N> pending (<X.X> MB)|SYNCED: <M>,TARGET: <host>:<port>,DEST: <mac_dest_root>/<folder>(fetched from/health), and a status strip showingLast sync: ...orNext retry in <N>s/ current upload filename. [C]opens Target Mac Config Modal:- Runs
tailscale status --jsonlocally to list online/offline Tailscale peers (filtering to non-self nodes, prioritizing macOS/Darwin peers at the top), so the user can pick their Mac with arrow/j/k+Enterwithout typing.ts.netaddresses. - Also includes a
[T] Type host manuallyoption with an LVGL text input field + port field.
- Runs
- Displays:
-
Tab
2:Folders:- Scrollable list of watched folders showing path (left) and status badge (
3 queuedamber /✓ syncedgreen /! missingred). [A]opens Keyboard Directory Picker Modal:- Root choices
/home,/media,/(or starts in$HOME). - Arrow/
j/kmoves cursor,Enterdrills into directory,Backspacegoes up parent directory (..),Spacewatches the highlighted directory (or current directory),[T]opens a manual path text input fallback.
- Root choices
[D]orDelete(fn+Backspace): Opens a brief[Y/N]confirmation bar to remove the selected folder from the watch list (explicitly noting local files on disk are not deleted).
- Scrollable list of watched folders showing path (left) and status badge (
-
Tab
3:Logs:- Scrollable monospace log viewer reading the newest entries from
state.db(HH:MM:SS+ concise message, color-coded byINFO/WARN/ERROR). [R]retries allFAILEDfiles (retry_failedIPC).
- Scrollable monospace log viewer reading the newest entries from
5.5 Packaging & Launcher Integration (Our Call + User Decision)
- Package name, version, & build path:
cp0-sync_1.0.0_m5stack1_arm64.debgenerated locally via CMake/CPack (ARM64 Docker build script or native build on CardputerZero over SSH) for personal installation viasudo apt install ./cp0-sync_1.0.0_m5stack1_arm64.deb(User Decision). NoCardputerZeroRepositoryorczdevCI submission layout constraints apply. - Files installed on CardputerZero:
/usr/bin/cp0-sync-ui(compiled C++/LVGL binary)/usr/bin/cp0-syncd(Python 3 daemon entrypoint,chmod +x)/usr/lib/systemd/user/cp0-syncd.service(WantedBy=default.target,After=network-online.target)/usr/share/APPLaunch/applications/cp0-sync.desktop/usr/share/APPLaunch/share/images/cp0-sync.png(custom app icon sized forAPPLaunch)
- Debian
Depends:python3 (>= 3.9)(zero third-party pip packages required) plus standard LVGL/runtime shared deps resolved viadpkg-shlibdeps. - Maintainer scripts:
postinst: runssystemctl --global enable cp0-syncd.serviceand restarts the user service for active graphical sessions if present.prerm: stops/disablescp0-syncd.servicecleanly on package removal.
6. What's Left to the Builder
- LVGL v9
lv_style_ttoken table, bundled FreeType.ttfsubsetting/loading (Inter+JetBrains Mono), and live theme switcher implementing the specifiedshadcn/uiZinc Dark and Zinc Light palettes on the 320×170 display. - CMake toolchain/preset configuration for both local macOS SDL2 simulator testing and local ARM64
.debpackaging (Dockerlinux/arm64build script or native CardputerZero SSH build). - Concrete implementation of Python modules (
cp0-syncd,cp0-mac-receiver,cp0-mac-sync), plist template, andpostinst/prermpackaging scripts. - Automated unit and end-to-end integration tests:
- Python tests for
inotifyclose-write handling, SQLite queue persistence/dedup, atomic.parttransfer, collision renaming, Tailscale CIDR allowlist, and sleep/wake retry recovery. - C++ UI state/IPC parsing tests and SDL2 simulator verification at 320×170.
- Python tests for