From c8d84211126fb7c56e798a771aa1eaa2b619bc15 Mon Sep 17 00:00:00 2001 From: adlee-was-taken Date: Sun, 5 Apr 2026 09:42:29 -0400 Subject: [PATCH] docs: add camera subsystem reference --- docs/architecture/subsystems/camera.md | 44 ++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 docs/architecture/subsystems/camera.md diff --git a/docs/architecture/subsystems/camera.md b/docs/architecture/subsystems/camera.md new file mode 100644 index 0000000..b80f95d --- /dev/null +++ b/docs/architecture/subsystems/camera.md @@ -0,0 +1,44 @@ +# camera + +## Purpose + +Owns all per-camera capture, motion detection, recording, and live streaming. One worker process per configured camera pulls RTSP frames with OpenCV, runs MOG2 background-subtraction motion detection plus optional YOLO object detection, writes H.264 segments via FFmpeg, and exposes HLS for the web grid. + +## Key files + +- `vigilar/camera/manager.py` — `CameraManager`, spawns and supervises one `multiprocessing.Process` per camera; polled by main supervisor via `check_and_restart()` +- `vigilar/camera/worker.py` — per-camera capture loop: RTSP read, ring buffer push, motion detect, adaptive-FPS record, YOLO classification, MQTT publish +- `vigilar/camera/motion.py` — MOG2-based `MotionDetector` +- `vigilar/camera/recorder.py` — FFmpeg-subprocess recorder with idle and motion modes; calls `vigilar.storage.encryption.encrypt_file` to produce `.vge` output +- `vigilar/camera/ring_buffer.py` — 5-second pre-motion frame buffer +- `vigilar/camera/hls.py` — HLS segment writer for the web grid view + +## MQTT topics + +**Subscribes:** `vigilar/camera/{id}/config` (runtime threshold updates) +**Publishes:** +- `vigilar/camera/{id}/motion/start` (MOG2 trigger, and YOLO person/vehicle detections) +- `vigilar/camera/{id}/motion/end` +- `vigilar/camera/{id}/heartbeat` +- `vigilar/camera/{id}/error` +- `vigilar/camera/{id}/pet/detected` +- `vigilar/camera/{id}/wildlife/detected` +- `vigilar/pets/{pet_name}/location` (when a known pet is identified) + +## Database tables + +The camera subsystem does not write to SQLite directly; recording metadata and events are persisted by the `events` subsystem after consuming motion topics. Encrypted clips are written to disk by `recorder.py`. + +## Depends on + +- `storage` — uses `vigilar.storage.encryption.encrypt_file` to seal recordings as `.vge` +- `detection` — optional YOLO detector, pet classifier, and wildlife threat classifier are loaded into the worker process + +## Consumed by + +- `events` — subscribes to the whole bus and classifies motion/heartbeat/error topics into rows in `events` and `recordings` +- `web` — reads HLS segments for the camera grid and decrypts recordings for playback + +## Notes + +`CameraManager` is the one subsystem NOT wrapped in `SubsystemProcess`; it owns its own child processes and is polled directly from the main supervisor loop. Adaptive FPS runs at 2 FPS idle and 30 FPS while motion is active, with a 5-second ring buffer flushed into the front of each motion clip for pre-event context. YOLO person/vehicle detections are published as extra `motion/start` messages with an additional `detection` field rather than on dedicated topics.