11 KiB
Usage, Configuration & Operations Guide
1. Mac Receiver Operations (cp0-mac-sync)
Manage where photos land, check Tailscale/receiver health, view logs, and control the macOS background service using cp0-mac-sync.
Command Reference
| Command | Description |
|---|---|
cp0-mac-sync status |
Show LaunchAgent state (com.cardputerzero.photosync), live HTTP /health check (0.0.0.0:<port>), destination directory, Tailscale CLI status, and active config path. |
cp0-mac-sync set-dir <path> |
Create <path> if needed and update dest_root in config.json. Picked up automatically on the next upload (no daemon restart required). |
cp0-mac-sync set-port <1-65535> |
Update listen_port in config.json and restart the LaunchAgent if installed (launchctl kickstart -k). Default: 8765. |
cp0-mac-sync logs [-n LINES] [-f] |
Print recent lines (-n 100 default) or tail live receiver logs (~/Library/Logs/cp0-mac-sync.log). |
cp0-mac-sync install-service |
Write ~/Library/LaunchAgents/com.cardputerzero.photosync.plist and load/enable the service (gui/<uid>/com.cardputerzero.photosync). |
cp0-mac-sync uninstall-service |
Stop and unload the LaunchAgent and remove its .plist. |
Running cp0-mac-receiver Manually (Foreground / Debug)
For foreground debugging without launchd:
./mac-receiver/bin/cp0-mac-receiver --config ~/.config/cp0-mac-sync/config.json --log-file /tmp/cp0-rec.log
Destination Layout & Collision Safety
Uploaded files are written into:
<dest_root>/<folder_label>/<rel_path>
For example, if dest_root is ~/Pictures/CardputerZero and CardputerZero watches /home/pi/Pictures/DCIM/Camera (label Camera):
IMG_0042.JPG→~/Pictures/CardputerZero/Camera/IMG_0042.JPG2026-11/IMG_0043.JPG→~/Pictures/CardputerZero/Camera/2026-11/IMG_0043.JPG
Collision & safety guarantees (mac-receiver/cp0_mac_receiver/server.py):
- Atomic staging: Body streams to a
.cp0-*.parttemp file, hashes SHA-256, validatesX-CP0-SHA256, appliesos.utime(X-CP0-Mtime) when valid,fsyncs, and atomically replaces into place (60ssocket timeout cleans up.partfiles if a connection drops mid-upload). - Idempotent duplicate: If a file already exists at the destination with the same SHA-256, it returns
200 OK(status: "duplicate") without creating extra copies. - Collision rename: If a file exists at the destination with a different SHA-256, it is saved alongside it as
<stem>_<YYYYMMDD_HHMMSS>_<sha8><ext>(never overwriting). - Tailscale IP allowlist (
tailscale_only: true): Only accepts HTTP requests from Tailscale CGNAT (100.64.0.0/10), Tailscale IPv6 (fd7a:115c:a1e0::/48), or loopback (127.0.0.0/8,::1/128); all other client IPs receive403 Forbidden. - Notifications: When
notify_on_batch: true, debounced macOS Notification Center alerts (2sdebounce window) summarize batch uploads (e.g.,"Synced 5 photos from CardputerZero").
2. CardputerZero Companion UI (cp0-sync-ui)
Launch Photo Sync from APPLaunch or run cp0-sync-ui from a shell. The UI refreshes daemon state every 1000 ms over the daemon's Unix domain socket (falling back cleanly to read-only SQLite + config.json display when cp0-syncd is stopped).
Top-Bar Status Pills
| Badge | Meaning |
|---|---|
Mac Online |
Daemon running, target Mac configured, and last upload/probe succeeded. |
Syncing |
Daemon is actively streaming queued photos over Tailscale. |
Mac Sleeping |
Target Mac unreachable; queued photos waiting safely until next wake-probe or [Enter]. |
No Target |
Daemon running, no Mac host configured yet — press C on 1 Status. |
Daemon Off |
cp0-syncd IPC socket unreachable (shows read-only cached counts/logs below if state.db exists). |
Tabs & Workflows
Tab 1 Status
Displays two Bento summary tiles (Pending Queue file count + total bytes, Total Synced count + 1-way verified status), your Target host (host:port) with retry countdown/uploading/cached indicator, destination directory on the Mac, and last synced filename or error summary.
- Press
Cto open the Target Mac Picker:- Automatically queries
tailscale status --jsonand sorts online macOS peers first. - Navigate with
j/korUp/Down, pressEnterto select<peer-ip-or-dns>:8765. - Press
Tinside the picker to manually enter<host>or<host>:<port>(or IPv6[host]:port).
- Automatically queries
Tab 2 Folders
Lists all watched directories with badges (N queued, synced, N err, or ! missing). On first run, cp0-syncd creates /home/pi/Pictures/DCIM/Camera (label Camera) automatically.
- Add folder (
A): Opens the on-device filesystem directory picker starting at your home directory (~):j/korUp/Down: move highlightEnter: drill down into highlighted subdirectoryBackspace: go up to parent directorySpace: select & add the highlighted directory.: select & add the directory you are currently insideT: switch to manual path typing (supports~/...expansion)- Nested or overlapping watched directories (parent or child of an existing watched folder) are rejected cleanly with an error toast to avoid double-uploading; duplicate base folder names (e.g., two
Cameradirectories) automatically get unique labels (Camera,Camera_2, ...).
- Remove folder (
DorDelete): Opens confirmation modal[Y] Confirm / [N] Cancel. Removing a watched folder stops watching it and purgesPENDING/UPLOADINGqueue items, never deleting photos on disk and retaining historicalSYNCEDdedup records so re-adding the folder later won't re-upload old files.
Tab 3 Logs
Displays timestamped INFO, WARN, and ERROR entries from SQLite (state.db retains the most recent 500 log rows).
j/korUp/Down: scroll through recent log rows.R: Reset allFAILEDrows back toPENDINGand trigger an immediate sync/wake probe.
Theme Toggle (T) & Exit (Esc / Q)
- Press
Ton any main tab (with no modal open) to toggle live between Zinc Dark (#09090b) and Zinc Light (#fafafa). The choice is saved toconfig.jsonviacp0-syncd. - Press
EscorQon main tabs to exitcp0-sync-uicleanly (leavingcp0-syncdrunning in the background) and return toAPPLaunch.
3. Daemon CLI & Runtime Behavior (cp0-syncd)
cp0-syncd CLI Flags
cp0-syncd [--config PATH] [--db PATH] [--sock PATH] [--verbose]
File Filtering & Queue Lifecycle
- Watched media extensions (
DaemonConfig.extensions):.jpg,.jpeg,.png,.webp,.gif,.bmp,.dng,.raw,.mp4,.mov(case-insensitive). - Ignored names: Prefixes
.or~(DEFAULT_IGNORE_PREFIXES), suffixes.part,.tmp,.crdownload(DEFAULT_IGNORE_SUFFIXES), and 0-byte files (logged once asWARNwithout enqueueing). - Watch engine: On Linux, uses native
ctypesinotify(IN_CLOSE_WRITE | IN_MOVED_TO | IN_CREATE | IN_DELETE_SELF | IN_MOVE_SELF) plusIN_ONLYDIRancestor watches so removable SD card mounts are detected automatically; falls back to periodic directory polling on non-Linux hosts. - Wake-probe backoff: When a Mac sleeps or refuses connections,
Uploaderpauses uploads, logs cleanly, probesGET /health(3stimeout) on backoff(5s → 10s → 20s → 40s → 60s max)or wakes immediately on new captured photos orEnterin the UI. - HTTP failure triage: Network errors,
403,408, and5xxpause the queue and retry once the Mac recovers;400,413, and422(and missing local files) mark only that single fileFAILEDso later photos keep flowing. - Crash recovery: On startup, any rows left in
UPLOADINGstate from an unexpected power loss automatically reset toPENDINGbefore scanning begins.
4. Configuration Files & Environment Variables
On Mac
| Item | Default Path | Override Env Var |
|---|---|---|
| Config JSON | ~/.config/cp0-mac-sync/config.json |
CP0_MAC_CONFIG |
| Rotating Logs | ~/Library/Logs/cp0-mac-sync.log (5 MB × 2 backups) |
— |
| LaunchAgent | ~/Library/LaunchAgents/com.cardputerzero.photosync.plist |
— |
| Synced Photos | ~/Pictures/CardputerZero/<folder_label>/... |
(via cp0-mac-sync set-dir) |
Mac config.json schema (MacConfig):
{
"dest_root": "/Users/you/Pictures/CardputerZero",
"listen_host": "0.0.0.0",
"listen_port": 8765,
"notify_on_batch": true,
"tailscale_only": true
}
On CardputerZero
| Item | Default Path | Override Env Var |
|---|---|---|
| Config JSON | ~/.config/cp0-sync/config.json |
CP0_SYNC_CONFIG |
| SQLite WAL DB | ~/.local/share/cp0-sync/state.db |
CP0_SYNC_DB |
| Unix IPC Socket | $XDG_RUNTIME_DIR/cp0-sync.sock (fallback /tmp/cp0-sync.sock) |
CP0_SYNC_SOCK |
| Sans / Mono Fonts | /usr/share/cp0-sync/fonts/ → system fonts → 5×7 fallback |
CP0_FONT_SANS, CP0_FONT_MONO |
Framebuffer (device build) |
/dev/fb0 |
CP0_FB_DEVICE |
Keyboard evdev (device build) |
Auto-scans /dev/input/event* for EV_KEY |
CP0_EVDEV_DEVICE |
5. Troubleshooting
UI displays Daemon Off
Check whether the background systemd --user service is running on CardputerZero:
systemctl --user status cp0-syncd.service
journalctl --user -u cp0-syncd.service -n 50 --no-pager
Restart it if needed:
systemctl --user restart cp0-syncd.service
Status stays on Mac Sleeping while the Mac is awake
- On Mac, verify the receiver is running and listening:
cp0-mac-sync status - Verify macOS Firewall / Little Snitch isn't blocking incoming connections to Python on TCP port
8765. - From CardputerZero over SSH, test reachability over Tailscale:
A healthy response returns HTTP
curl -i http://<mac-tailscale-ip-or-magicdns>:8765/health200with{"ok": true, "version": "1.0.0", "dest_root": "..."}. If you get403, confirm traffic is traveling over Tailscale (100.64.0.0/10) rather than an unallowed LAN interface.
One photo shows FAILED in Logs
Open 3 Logs in cp0-sync-ui to view the error reason (e.g., permission denied, missing source file, destination path conflict), resolve the issue, and press R to re-queue all FAILED entries.
Re-uploading previously synced photos
Because one-way sync tracks (folder_id, rel_path, sha256) in state.db so deleted files on your Mac aren't re-copied, intentionally re-syncing everything requires resetting state.db:
systemctl --user stop cp0-syncd.service
rm ~/.local/share/cp0-sync/state.db*
systemctl --user start cp0-syncd.service