Skip to content

docs: fix documentation drift from codebase #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Sbussiso wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

docs: fix documentation drift from codebase #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -238,8 +238,8 @@ All outbound calls use `ApiClient` in `src/api/client.rs`:

| Method | Path | Header | Body | When |
|--------|------|--------|------|------|
| POST | `/api/nodes/register` | `X-API-Key` | `RegisterRequest` JSON | Startup |
| POST | `/api/nodes/heartbeat` | `X-API-Key` | `HeartbeatRequest` JSON | Every `heartbeat_interval` s (fallback path; WS heartbeat is primary) |
| POST | `/api/nodes/register` | `X-Node-API-Key` | `RegisterRequest` JSON | Startup |
| POST | `/api/nodes/heartbeat` | `X-Node-API-Key` | `HeartbeatRequest` JSON | Every `heartbeat_interval` s (fallback path; WS heartbeat is primary) |
| POST | `/api/cameras/{id}/codec` | `X-Node-API-Key` | `{video_codec, audio_codec}` JSON | After first segment or codec change |
| POST | `/api/cameras/{id}/push-segment?filename=…` | `X-Node-API-Key` | raw `.ts` bytes (`video/mp2t`) | Every segment |
| POST | `/api/cameras/{id}/playlist` | `X-Node-API-Key` | playlist text (`text/plain`) | Every playlist rewrite |
Expand Down Expand Up @@ -328,7 +328,7 @@ cargo run -- --once # Run one detection cycle and exit (if supported by curr

**Build:** `docker build -t opensentry-cloudnode:latest .`

Published image: `ghcr.io/sourcebox-llc/opensentry-cloudnode`. Tags track the Cargo version (`:0.1.16`), plus floating `:latest` and `:0.1`. The image is built + pushed by `.github/workflows/release.yml` on tag push. Pi (ARM64) builds are source-only at the moment — no ARM image is published.
Published image: `ghcr.io/sourcebox-llc/opensentry-cloudnode`. Tags track the Cargo version (`:0.1.16`), plus floating `:latest` and `:0.1`. The image is built + pushed by `.github/workflows/release.yml` on tag push. Multi-arch images (`linux/amd64`, `linux/arm64`) are built via Docker Buildx with QEMU emulation; prebuilt ARM64 binaries are also published to GitHub Releases (built on native `ubuntu-24.04-arm` runners).

**Run:**
```bash
Expand All @@ -352,8 +352,8 @@ docker run -d \
- Add user to video group: `sudo usermod -a -G video $USER`
- Camera devices: `/dev/video0`, `/dev/video1`, etc.

**Raspberry Pi (Linux ARM64):** production-ready, build from source only
- Build: `cargo build --release` — no prebuilt binaries on the releases page for ARM
**Raspberry Pi (Linux ARM64):** production-ready
- Prebuilt binaries and Docker images (`linux/arm64`) are published on every release
- Encoder: **libx264 CPU** only. `h264_v4l2m2m` is in `RETIRED_ENCODERS` because every Pi hardware revision we tested writes a non-conforming SPS that browsers reject.
- Preset: libx264 `ultrafast` keeps a 1080p30 stream under ~1.5 cores on a Pi 4, leaving room for a second camera. See "HLS generation" for the full rationale.
- USB: plug cameras into the Pi directly, not through an unpowered hub. Hub EMI faults show up as `usb-port: disabled by hub (EMI?)` + `xhci_hcd: Setup ERROR` in `dmesg` and wedge the whole USB controller until reboot.
Expand Down Expand Up @@ -382,7 +382,7 @@ docker run -d \
| `tokio-tungstenite` + `futures-util` | WebSocket client |
| `serde` / `serde_json` | JSON serialization |
| `clap` | CLI parser |
| `tracing` / `tracing-subscriber` / `tracing-appender` | Logging |
| `tracing` / `tracing-subscriber` | Logging |
| `crossterm` | Terminal raw mode + input events (dashboard TUI) |
| `inquire` / `indicatif` | Interactive prompts + progress bars (setup wizard) |
| `colored` | ANSI color formatting |
Expand Down
25 changes: 24 additions & 1 deletion config.example.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,33 @@ cameras:
streaming:
# Target frames per second
fps: 30

# JPEG quality (1-100)
jpeg_quality: 85

# Video encoder override (auto-detected if empty)
# Supported: h264_nvenc (NVIDIA), h264_qsv (Intel), h264_amf (AMD), libx264 (CPU)
# encoder: ""

# HLS output settings
hls:
enabled: true
# Segment duration in seconds
segment_duration: 1
# Number of segments in the rolling playlist window
playlist_size: 15
# Target bitrate (e.g. "2M" for 2 Mbps)
# bitrate: "2M"

# Motion detection settings
motion:
# Toggle motion detection on/off
enabled: true
# Scene-change score threshold (0.0 = identical, 1.0 = totally different)
threshold: 0.02
# Minimum seconds between events per camera
cooldown_secs: 30

# Recording settings
recording:
# Enable local recording
Expand Down