> 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.
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.
| **Debian Packaging** | [`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`:
```bash
./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:
```bash
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:
1. Launch **Photo Sync** from the CardputerZero `APPLaunch` launcher (or run `cp0-sync-ui`).
2. On tab **`1 Status`**, press **`C`** to pick your Mac from discovered online Tailscale peers (or press **`T`** inside the picker to enter `<host>[:port]` manually).
3. Photos taken into `/home/pi/Pictures/DCIM/Camera` (or any folder added under **`2 Folders`** via **`A`**) 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 |
| `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](docs/building-and-installation.md)** — Prerequisites, building `cp0-sync_1.0.0_m5stack1_arm64.deb` (Docker `linux/arm64` or native on device), font bundling, macOS SDL2 simulator builds, and test suites.