mirror of
https://github.com/cottongin/cardputerzero-sync.git
synced 2026-11-21 06:54:48 -06:00
7.3 KiB
7.3 KiB
CardputerZero Photo Sync — Implementation Summary
Date: 2026-11-18 09:15 EST
Branch: feat/cardputerzero-photo-sync
Range: 23db23a (design spec & plan) → 6685844 (final fix wave)
Task Description
Implemented an end-to-end, zero-external-Python-dependency one-way photo syncing system for the M5Stack CardputerZero (Raspberry Pi CM0, arm64 Debian Linux, 320×170 non-touch LCD, cp0-keys 46-key matrix keyboard, APPLaunch) and macOS over an existing private Tailscale tailnet:
mac-receiver/: Background macOS HTTP receiver daemon (MacReceiverServer) +cp0-mac-syncCLI +LaunchAgentinstaller saving uploaded photos to~/Pictures/CardputerZero/<folder_label>/<rel_path>with atomic.partstaging, SHA-256 verification, non-overwriting collision naming, and debounced macOS Notification Center summaries.device-daemon/: On-device Pythoncp0-syncd(systemd --user) service with SQLite WAL queue (SyncStore, keyed on(folder_id, rel_path, sha256)), Linuxctypesinotify+ fallback polling watcher (INotifyWatcher) supporting removable SD mounts via ancestor watches, sleep-aware wake-probe uploader (Uploader), andAF_UNIXJSON IPC server (IpcServer).device-ui/: C++17320×170companion UI (cp0-sync-ui) styled withshadcn/uiZinc Dark & balanced Zinc Light themes ([T]live toggle), segmented1 Status · 2 Folders · 3 Logstabs, Tailscale peer & customhost[:port]target picker ([C]), directory tree drill-down ([A]), non-destructive folder removal confirmation ([D]), retry trigger ([R]), FreeType2 + 5×7 fallback font rendering, macOS SDL2 simulator, Linuxfbdev+evdevbackend, and optional LVGL v9 hooks (CP0_HAS_LVGL).packaging/: Debianarm64.debbuilder (build-deb.sh,Dockerfile.arm64),cp0-syncd.service(systemd --user),APPLaunchcp0-sync.desktop&80×80icon (cp0-sync.png), Debian maintainer scripts (control,postinst,prerm), and packaging verification tests.
Key Changes Made
| Commit | Summary |
|---|---|
23db23a |
Design specification (docs/superpowers/specs/2026-11-18-cardputerzero-photo-sync-design.md) and 7-task TDD plan |
555919a, 23ed06f |
mac-receiver/cp0_mac_receiver/{__init__,config,server}.py & tests/test_server.py (Tailscale/loopback IP allowlist, atomic .part upload, osascript on run argv escaping) |
a5f8c5d |
mac-receiver/cp0_mac_receiver/cli.py, bin/{cp0-mac-receiver,cp0-mac-sync}, tests/test_cli.py (set-dir, set-port, install-service, uninstall-service, status, logs) |
69224f3 |
device-daemon/cp0_syncd/{__init__,config,store}.py & tests/test_store_and_config.py (overlap guard, unique label disambiguation, SQLite WAL state/dedup/log store) |
da4d963, c6a672f |
device-daemon/cp0_syncd/{watcher,uploader,ipc,daemon}.py, bin/cp0-syncd, tests/test_daemon_integration.py (Linux ctypes inotify + fallback poller, crash UPLOADING recovery, atomic _state_lock wake/probe handling, uniform subdir prefix ignore, AF_UNIX JSON IPC) |
b6fcf5a, 8ea46a2 |
device-ui/CMakeLists.txt, src/{theme,ipc_client}.{hpp,cpp}, tests/test_ipc_and_theme.cpp (non-blocking IPC client, fail-closed corrupt SQLite fallback, Tailscale peer parser, Zinc Dark/Light palettes) |
7d369b2, eeacf0e |
device-ui/src/{ui_controller,app_ui}.{hpp,cpp}, src/fb_blit.hpp, src/main.cpp, tests/test_ui_navigation.cpp (320×170 renderer, modals, cp0-keys/SDL2/fbdev+evdev loops, bounds/bitfield-checked framebuffer blit, CP0_HAS_LVGL lifecycle, cross-tab feedback toasts) |
ec8a414 |
packaging/{Dockerfile.arm64,build-deb.sh,cp0-syncd.service,cp0-sync.desktop,cp0-sync.png}, packaging/debian/{control,postinst,prerm}, packaging/tests/test_packaging.py |
6685844 |
Final cross-component fixes: gate SQLite fallback folder synthesis on !config_loaded, show top-bar "Daemon Off" badge when from_fallback is true, and add 60s socket timeout (408), X-CP0-Mtime validation / pre-replace os.utime, .expanduser(), and directory-collision 400/500 handling in server.py |
(41 files added across implementation commits prior to this summary.)
Verification Results
Observed on 6685844:
- Mac Receiver (
PYTHONPATH=mac-receiver python3 -m unittest discover -s mac-receiver/tests -v,BypassSandbox: true):24/24passed in6.319s(OK). - Device Daemon (
PYTHONPATH=device-daemon:mac-receiver python3 -W error -m unittest discover -s device-daemon/tests -v,BypassSandbox: true):25/25passed in4.766s(OK, zero warnings). - Companion UI (
cmake --build device-ui/build && ctest --test-dir device-ui/build --output-on-failure -V,BypassSandbox: true): Clean build (-Wall -Wextra -Wpedantic, zero warnings) and2/2tests passed in0.18 sec(test_ipc_and_theme0.16s,test_ui_navigation0.01s). - Packaging (
python3 -m unittest discover -s packaging/tests -v):7/7passed in0.134s(OK). - ARM64 Container Verification (observed at
ec8a414before finalmac-receiver/device-ui6685844edits): Builtcp0-sync_1.0.0_m5stack1_arm64.deb(98704bytes) underlinux/arm64debian:bookworm-slim(CP0_UI_TARGET_DEVICE=ONzerog++warnings,ctest2/2,dpkg-deb -I/-c,dpkg -i/-r, anddevice-daemon/tests25/25exercising real Linux kernelctypesinotify).
Lessons Learned
- Pre-empt Python/C++ schema & fallback drift: Pinning the 18-key
statusIPC JSON schema early kept Pythondaemon.pyand C++ipc_client.cppin sync, and checking SQLite fallback behavior againstremove_foldercaught subtle ghost-folder and stale"Mac Online"badge mismatches across offline daemon restarts. - Isolating hardware-specific code behind testable C++ headers: Extracting
UiControllerandfb_blit.hpp(pack_fb_channel/blit_framebuffer) allowed deterministicctestcoverage on macOS for keyboard modal flows, RGB/BGR bitfields, and stride bounds before compiling the Linuxfbdev/evdevtarget inside ARM64 Docker. - Sandboxed socket testing & GPG commits: Loopback TCP and
AF_UNIXtests predictably hit macOS sandboxEPERM, so pure logic/UI/packaging tests run inside the sandbox while live socket suites and GPG-signed commits isolate cleanly to singleBypassSandbox: truesteps.
Follow-Up Items
- On real CardputerZero hardware: Re-build the
.debvia./packaging/build-deb.sh(so6685844changes are included), optionally placeInter-Regular.ttf/JetBrainsMono-Regular.ttfinpackaging/fonts/for FreeType glyphs instead of the 5×7 bitmap fallback, installcp0-sync_1.0.0_m5stack1_arm64.debviasudo dpkg -i, and test/dev/fb0,cp0-keysevdev,APPLaunch, andsystemctl --user status cp0-syncd. - On Mac: Install the receiver daemon via
mac-receiver/bin/cp0-mac-sync install-serviceand verify live end-to-end Tailscale transfers from the device. - Deferred minor improvements (non-blocking): Unicode multi-byte UTF-8 glyph rendering in
app_ui.cpp, clampinglog_scrollupper bound tologs.size() - 6inui_controller.cpp, explicitlibc6, libstdc++6inpackaging/debian/control,LC_NUMERIC/EINTRhardening inipc_client.cpp, transaction context aroundSyncStore.log, and separatinglaunchdstdout/stderr log path fromRotatingFileHandler.