move_detect/deploy

Edge deployment (Raspberry Pi 5, air-gapped / 폐쇄망)

Offline-installable bundle + systemd unit for the move-detect edge daemon. The bundle is fully self-contained (all wheels + pose model + source): the Pi performs zero network fetches at install or run time. The only runtime network use is the cloud POST / config-poll / heartbeat, and even that tolerates being offline (events buffer in the local sqlite queue and flush on reconnect).

Scope: this covers the CPU MoveNet + USB (UVC) webcam path — the one the daemon wires today (edge/daemon.py:main) and the one verified end-to-end. Hailo-8 acceleration (edge/adapters/hailo_pose.py) and the CSI camera (edge/adapters/picamera_source.py) are separate device-validated paths — see docs/hardware-bringup.md.

Files

File	Runs on	Purpose
bundle/build_offline_bundle.sh	build machine (has internet)	downloads wheels + model, stages source, emits one tarball
bundle/install_offline.sh	the Pi (no internet)	venv + --no-index install, systemd unit, service account
systemd/move-detect-edge.service	the Pi	the daemon unit (auto-restart, device access, hardening)
systemd/move-detect-edge.env.example	the Pi	env template → /etc/move-detect/edge.env

1. Build the bundle (on a machine WITH internet)

Most reliable: build on an aarch64 host (a Pi 5, or an arm64 CI runner) so the downloaded wheels match the target exactly:

deploy/bundle/build_offline_bundle.sh            # native aarch64 wheels

From an x86 box you can attempt a cross build (best-effort — onnxruntime/opencv wheel tags may not resolve; if it fails, build natively):

deploy/bundle/build_offline_bundle.sh --cross    # target aarch64 / cp311

Output: dist/move-detect-edge-bundle-aarch64-cp311.tar.gz (+ MANIFEST.txt listing the bundled wheels). This single file crosses the air gap.

2. Transfer + install (on the air-gapped Pi)

Copy the tarball across the gap (USB, one-way transfer, etc.), then:

tar xzf move-detect-edge-bundle-aarch64-cp311.tar.gz
cd move-detect-edge-bundle
sudo ./install_offline.sh

The installer: creates the movedetect service account (in video/render/ plugdev/hailo groups), lays down source + model under /opt/move-detect, builds a venv and installs the bundled wheels with --no-index, verifies the package imports, seeds /etc/move-detect/edge.env, and installs the systemd unit.

3. Configure + start

sudo nano /etc/move-detect/edge.env      # DEVICE_ID, DEVICE_SECRET, CAFE24_URL, ...
sudo systemctl enable --now move-detect-edge
journalctl -u move-detect-edge -f

DEVICE_ID/DEVICE_SECRET must match a devices row in the cloud (see cloud/docs/cloud-deploy.md §6). MOVENET_ONNX should point at the bundled model (/opt/move-detect/models/movenet_lightning.onnx).

4. Verify the air gap (do this before trusting a build)

• On a host with networking disabled, install_offline.sh completes — the --no-index installs prove nothing is fetched. If pip tries to reach PyPI, a wheel is missing from the bundle: rebuild (step 1) natively.
• Step [4/6] of the installer prints edge import OK (onnxruntime + cv2 + numpy + requests all import from the venv).
• systemctl status move-detect-edge is active (running); the log shows frames processed and (if the cloud is reachable) heartbeats.
• Pull the network cable → events keep queueing (QUEUE_DB grows) → restore → the queue flushes. (End-to-end behavior verified in the edge e2e harness.)

Not bundled (by design)

• MySQL / the cloud app — a separate host; see cloud/docs/cloud-deploy.md.
• HailoRT + yolov8s_pose.hef — the Hailo runtime and HEF are installed via Hailo's own Pi packages; the CPU MoveNet path here needs neither.