Important
This project was developed entirely with AI coding assistance (Gemini 4 Argon) and has not undergone rigorous review. It is provided as-is and may require adjustments for other environments.
CardputerZero Photo Sync
Automatic one-way background photo syncing from an M5Stack CardputerZero (Raspberry Pi CM0 / ARM64 Debian Linux) to a Mac over Tailscale.
Photos saved in watched folders on CardputerZero (default: /home/pi/Pictures/DCIM/Camera) are queued locally in SQLite whenever your Mac is sleeping or offline, then streamed over Tailscale to a background macOS HTTP receiver into ~/Pictures/CardputerZero/<folder_label>/<rel_path> without overwriting collisions.
Architecture Overview
| Component | Path | Runs On | Purpose |
|---|---|---|---|
| Mac Receiver & CLI | mac-receiver/ |
macOS (LaunchAgent) |
Zero-dependency Python 3 (>= 3.9) HTTP receiver (cp0-mac-receiver) restricted to Tailscale/loopback IPs, atomic .part + SHA-256 verification, macOS notifications, and cp0-mac-sync management CLI. |
| Device Sync Daemon | device-daemon/ |
CardputerZero (systemd --user) |
Zero-dependency Python 3 daemon (cp0-syncd) with SQLite WAL deduplication queue, Linux ctypes inotify (+ polling fallback), sleep-aware /health wake-probe uploader, and AF_UNIX JSON IPC. |
| Companion UI | device-ui/ |
CardputerZero (/dev/fb0 + cp0-keys) & macOS (--sim) |
C++17 320×170 UI (cp0-sync-ui) in shadcn/ui Zinc Dark/Light themes with FreeType2 (+ 5×7 bitmap fallback) and optional CP0_HAS_LVGL hooks. |
| Debian Packaging | packaging/ |
ARM64 Docker / Bookworm | Builds cp0-sync_1.0.0_m5stack1_arm64.deb with cp0-syncd.service and APPLaunch menu entry (Photo Sync). |
Quick Start
1. Start the Receiver on Your Mac
Ensure Tailscale is connected on both your Mac and CardputerZero, then install and start the macOS LaunchAgent:
./mac-receiver/bin/cp0-mac-sync install-service
./mac-receiver/bin/cp0-mac-sync status
(Optional) Add mac-receiver/bin to your PATH (or symlink cp0-mac-sync into ~/.local/bin / /usr/local/bin) and change the default destination (~/Pictures/CardputerZero) anytime:
cp0-mac-sync set-dir ~/Pictures/CardputerZero
2. Build & Install the .deb on CardputerZero
Build cp0-sync_1.0.0_m5stack1_arm64.deb on your Mac via Docker Desktop (linux/arm64) and install it on the CardputerZero:
# On Mac
./packaging/build-deb.sh
scp packaging/dist/cp0-sync_1.0.0_m5stack1_arm64.deb pi@<cardputerzero-tailscale-host>:/tmp/
# On CardputerZero
sudo dpkg -i /tmp/cp0-sync_1.0.0_m5stack1_arm64.deb
systemctl --user status cp0-syncd.service
3. Select Your Target Mac on CardputerZero
- Launch Photo Sync from the CardputerZero
APPLaunchlauncher (or runcp0-sync-ui). - On tab
1 Status, pressCto pick your Mac from discovered online Tailscale peers (or pressTinside the picker to enter<host>[:port]manually). - Photos taken into
/home/pi/Pictures/DCIM/Camera(or any folder added under2 FoldersviaA) now queue offline and upload automatically whenever your Mac is awake on Tailscale.
Companion UI Keyboard Shortcuts (320×170)
| Key | Where | Action |
|---|---|---|
1, 2, 3 |
Main tabs | Switch between Status, Folders, and Logs |
Left / Right |
Main tabs | Cycle between tabs |
Enter |
Global (no modal) | Trigger immediate sync / wake-probe |
T |
Main tabs | Toggle Zinc Dark (#09090b) / Zinc Light (#fafafa) theme |
C |
1 Status |
Open Target Mac Tailscale peer picker ([T] inside modal for manual host[:port]) |
A |
2 Folders |
Open directory browser (Enter drill down, Backspace up, Space watch highlighted, . watch current dir, T type path) |
D / Delete |
2 Folders |
Remove selected watched folder (Y confirm / N cancel — never deletes photos) |
j / k or Up / Down |
Lists / Modals | Move cursor or scroll log rows |
R |
3 Logs |
Re-queue all FAILED files for retry |
Esc / Q |
Modal / Main tabs | Close active modal, or exit cp0-sync-ui cleanly back to APPLaunch |
Documentation
- Building & Installation Guide — Prerequisites, building
cp0-sync_1.0.0_m5stack1_arm64.deb(Dockerlinux/arm64or native on device), font bundling, macOS SDL2 simulator builds, and test suites. - Usage, Configuration & Operations Guide —
cp0-mac-syncCLI reference, UI workflows, deduplication & sleep-backoff behavior, config paths, environment variables, and troubleshooting. - Design Specification — Full hardware constraints, HTTP/IPC contracts, SQLite schema, and visual design tokens.
- Implementation Plan — 7-task architecture and TDD plan.
Repository Layout
.
├── mac-receiver/ # macOS HTTP receiver, cp0-mac-sync CLI, & tests
├── device-daemon/ # CardputerZero systemd user daemon, SQLite queue, & tests
├── device-ui/ # C++17 320x170 companion UI (fbdev/evdev & SDL2 simulator)
├── packaging/ # ARM64 Debian .deb builder, systemd unit, APPLaunch entry
└── docs/ # Build/install guide, usage docs, spec, and implementation plan