Merge pull request #40 from GyeongHoKim/feature/rpi

feat(rpi): embed mtxrpicam under a Raspberry Pi build channel

Author: GyeongHoKim

.github/workflows/ci.yml

@@ -63,3 +63,70 @@ jobs:
 
       - name: Run tests
         run: make test
+
+  mtxrpicam-version-pin:
+    name: MTXRPICAM version pin
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      # Catch drift between the three places that pin mediamtx-rpicamera:
+      # Makefile's MTXRPICAM_VERSION, the .goreleaser.yml pre-hook, and the
+      # header comment in scripts/mtxrpicam.sha256. They are bumped together
+      # by hand, so a missed file should fail PR CI loudly.
+      - name: Verify MTXRPICAM version pin is consistent
+        run: |
+          set -euo pipefail
+          mk=$(sed -n 's/^MTXRPICAM_VERSION[[:space:]]*?=[[:space:]]*\(v[0-9.]*\).*/\1/p' Makefile)
+          gr=$(grep -oE 'fetch-mtxrpicam\.sh.*v[0-9.]+' .goreleaser.yml \
+                | grep -oE 'v[0-9.]+' | sort -u)
+          sh=$(sed -n 's/.*mediamtx-rpicamera \(v[0-9.]*\).*/\1/p' scripts/mtxrpicam.sha256 \
+                | sort -u)
+          echo "Makefile=$mk goreleaser=$gr sha256=$sh"
+          [ -n "$mk" ] && [ -n "$gr" ] && [ -n "$sh" ] || {
+            echo "could not extract a version from one or more files" >&2; exit 1; }
+          [ "$(echo "$gr" | wc -l)" = "1" ] || {
+            echo ".goreleaser.yml pre-hook references multiple versions" >&2; exit 1; }
+          [ "$(echo "$sh" | wc -l)" = "1" ] || {
+            echo "scripts/mtxrpicam.sha256 references multiple versions:" >&2
+            echo "$sh" >&2
+            exit 1; }
+          [ "$mk" = "$gr" ] && [ "$mk" = "$sh" ] || {
+            echo "MTXRPICAM version drift between Makefile, .goreleaser.yml, and scripts/mtxrpicam.sha256" >&2
+            exit 1; }
+
+  rpicam-build-check:
+    name: RPi build check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - uses: actions/setup-go@v6.4.0
+        with:
+          go-version-file: .go-version
+          cache: true
+
+      - uses: actions/setup-node@v6.3.0
+        with:
+          node-version-file: .node-version
+          cache: npm
+          cache-dependency-path: internal/gui/frontend/package-lock.json
+
+      # rpicam-build-check cross-compiles ./..., which includes internal/gui;
+      # that package's //go:embed all:frontend/dist requires the dist tree to
+      # exist at compile time even though the rpi channel itself never ships
+      # the GUI binary.
+      - name: Install frontend dependencies
+        working-directory: internal/gui/frontend
+        run: npm ci
+
+      - name: Build frontend (populate internal/gui/frontend/dist for go:embed)
+        working-directory: internal/gui/frontend
+        run: npm run build
+
+      # Cross-compile the rpicam-tagged code for both Pi targets against the
+      # placeholder mtxrpicam blob (no network fetch). This catches type drift
+      # in internal/rpicamera/camera_rpicam.go that the disabled stub would
+      # otherwise hide on the default linux/amd64 build.
+      - name: Cross-compile rpicam-tagged code
+        run: make rpicam-build-check

.github/workflows/release.yml

@@ -22,6 +22,16 @@ jobs:
           go-version-file: .go-version
           cache: true
 
+      # Cache the fetched mtxrpicam binaries across releases. Keyed on the
+      # SHA-256 file so a version bump invalidates the cache automatically.
+      - name: Cache mtxrpicam binaries
+        uses: actions/cache@v4
+        with:
+          path: |
+            internal/rpicamera/mtxrpicam_32
+            internal/rpicamera/mtxrpicam_64
+          key: mtxrpicam-${{ hashFiles('scripts/mtxrpicam.sha256') }}
+
       - uses: goreleaser/goreleaser-action@v7.0.0
         with:
           version: v2.15.3

.gitignore

@@ -24,4 +24,13 @@ coverage/
 # Web
 
 node_modules
-internal/gui/frontend/package.json.md5
+internal/gui/frontend/package.json.md5
+
+# Raspberry Pi build channel — the real mtxrpicam binaries are fetched at
+# release time and verified against scripts/mtxrpicam.sha256. The directories
+# themselves stay in git with a `placeholder` file checked in so //go:embed
+# stays satisfied during PR CI.
+internal/rpicamera/mtxrpicam_32/*
+!internal/rpicamera/mtxrpicam_32/placeholder
+internal/rpicamera/mtxrpicam_64/*
+!internal/rpicamera/mtxrpicam_64/placeholder

.goreleaser.yml

@@ -21,6 +21,33 @@ builds:
       - -X github.com/GyeongHoKim/onvif-simulator/internal/version.Commit={{.Commit}}
       - -X github.com/GyeongHoKim/onvif-simulator/internal/version.Date={{.Date}}
 
+  # Raspberry Pi build channel. Embeds mtxrpicam (32+64) so the artifact runs
+  # standalone on Raspberry Pi OS with libcamera. The pre hook fetches the
+  # binary blob from the pinned mediamtx release; the rpicam build tag selects
+  # the rpicamera runtime in internal/rpicamera.
+  - id: cli-rpi
+    main: ./cmd/cli
+    binary: onvif-simulator-rpi
+    env:
+      - CGO_ENABLED=0
+    flags:
+      - -tags=rpicam
+    goos:
+      - linux
+    goarch:
+      - arm
+      - arm64
+    goarm:
+      - "7"
+    hooks:
+      pre:
+        - cmd: ./scripts/fetch-mtxrpicam.sh {{ if eq .Arch "arm" }}32{{ else }}64{{ end }} v2.4.3 internal/rpicamera/mtxrpicam_{{ if eq .Arch "arm" }}32{{ else }}64{{ end }}
+    ldflags:
+      - -s -w
+      - -X github.com/GyeongHoKim/onvif-simulator/internal/version.Version={{.Version}}
+      - -X github.com/GyeongHoKim/onvif-simulator/internal/version.Commit={{.Commit}}
+      - -X github.com/GyeongHoKim/onvif-simulator/internal/version.Date={{.Date}}
+
 archives:
   - id: cli
     ids:
@@ -33,6 +60,13 @@ archives:
           - zip
     name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
 
+  - id: cli-rpi
+    ids:
+      - cli-rpi
+    formats:
+      - tar.gz
+    name_template: "{{ .ProjectName }}-rpi_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+
 checksum:
   name_template: "checksums.txt"
   algorithm: sha256
@@ -66,3 +100,5 @@ release:
   extra_files:
     - glob: ./scripts/install.sh
     - glob: ./scripts/install.ps1
+    - glob: ./onvif-simulator.example.json
+    - glob: ./onvif-simulator.example.rpi.json

AGENTS.md

@@ -22,6 +22,8 @@ Use `make` targets rather than calling `go`, `golangci-lint`, or `wails` directl
 | --- | --- |
 | Build CLI/TUI binary | `make cli` |
 | Build GUI binary (requires Wails CLI) | `make gui` |
+| Build CLI for Raspberry Pi (arm + arm64) | `make cli-rpi` |
+| Cross-compile rpicam-tagged code (no fetch) | `make rpicam-build-check` |
 | Format | `make format` |
 | Lint | `make lint` |
 | Unit tests (race detector) | `make test` |
@@ -38,16 +40,25 @@ Run a single Go test: `go test -race -run TestName ./internal/<pkg>/...`.
 
 Toolchain versions are pinned in `mise.toml`. Run `mise install` after cloning.
 
-GUI frontend lives in `frontend/` (React + Vite + Tailwind, shadcn registry) and is hosted by Wails. `wails dev` starts the dev harness; Wails invokes the frontend build for production. The TUI is a Bubble Tea program and has no web assets.
+GUI frontend lives in `internal/gui/frontend/` (React + Vite + Tailwind, shadcn registry), is built by npm into `internal/gui/frontend/dist`, and is hosted by Wails from `cmd/gui`. Run `wails dev` inside `cmd/gui` for the dev harness; Wails invokes the frontend build for production. The TUI is a Bubble Tea program in `internal/tui` with no web assets; launch it with `onvif-simulator tui` (same binary as the CLI).
+
+## Build channels
+
+The repo ships two Go binary build channels:
+
+- **default** — built with `make cli` and goreleaser build id `cli`. Runs on linux/darwin/windows × amd64/arm64. No platform-specific embedded assets. Produces `onvif-simulator`.
+- **rpi** — built with `make cli-rpi` and goreleaser build id `cli-rpi`. Runs on linux/arm (Pi Zero/2/3 32-bit) and linux/arm64 (Pi 3/4/5 64-bit). The build pipeline fetches `mtxrpicam_32.tar.gz` and `mtxrpicam_64.tar.gz` from the pinned mediamtx-rpicamera release (a separate repo from mediamtx itself) into `internal/rpicamera/mtxrpicam_{32,64}/` and `go build -tags rpicam` embeds them via `//go:embed`. Produces `onvif-simulator-rpi-arm` / `onvif-simulator-rpi-arm64`. The default channel never carries this asset and `kind=rpicam` profiles fail fast with `rpicamera.ErrUnsupported` on non-rpi builds.
+
+The `rpicam` build tag controls every rpicam runtime path. PR CI does not download the binary — it cross-compiles `-tags rpicam` against a 1-byte placeholder file checked into each `mtxrpicam_*` directory (`make rpicam-build-check`). The pinned mediamtx-rpicamera version lives in `Makefile`'s `MTXRPICAM_VERSION`; tarball checksums in `scripts/mtxrpicam.sha256` are bumped in lockstep so the fetch step (`scripts/fetch-mtxrpicam.sh`) refuses unverified blobs. Those hashes are cross-checkable against mediamtx's own `internal/staticsources/rpicamera/mtxrpicamdownloader/HASH_MTXRPICAM_*_TAR_GZ`, giving an out-of-band verification source independent of the release page itself. GUI is intentionally CLI/TUI-only on the rpi channel — there is no `make gui-rpi` and there will not be one.
 
 ## Architecture
 
 Responsibilities are split into tightly separated layers. Folder names are intentionally omitted here — some of today's packages are placeholders and will be reorganized. Locate the layers by role with the symbol/grep tools.
 
 - **Configuration** — owns the on-disk configuration schema (`onvif-simulator.json`). The root `Config` struct contains:
   - `DeviceConfig` — static device identity (UUID, manufacturer, model, serial, scopes).
-  - `NetworkConfig` — HTTP port and WS-Discovery XAddr list.
-  - `MediaConfig` — list of pass-through media profiles (RTSP/snapshot URIs, codec, resolution).
+  - `NetworkConfig` — HTTP port, **RTSP port** for the embedded RTSP listener (0 means use the default 8554 via `RTSPPortOrDefault`), optional bind `interface`, and WS-Discovery XAddr list.
+  - `MediaConfig` — ONVIF media **profiles**. Each profile declares a **`kind`** (default `"file"`, also `"rpicam"`). For `kind=file`, **`media_file_path`** points at a local **H.264/H.265 MP4** the simulator loops; width, height, FPS, and encoding are **probed from the file at startup** and published in the live config snapshot (persisted JSON may still carry prior values for those fields). For `kind=rpicam`, **`rpicam`** carries capture parameters (camera_id, width, height, fps, bitrate, idr_period, hflip/vflip, sharpness/contrast/brightness/saturation) and the simulator captures live H.264 from a Raspberry Pi camera through the embedded `mtxrpicam` helper; this kind is only available on binaries built with the `rpicam` tag (the dedicated Pi build channel — see *Build channels* below). Optional **`snapshot_uri`** (HTTP(S) URL returned by `GetSnapshotUri`; the process does not render snapshots itself), optional **metadata** configuration entries, and **`MaxVideoEncoderInstances`** are profile-level fields shared by both kinds.
   - `AuthConfig` — authentication switch, user credentials, Digest and JWT tuning.
   - `RuntimeConfig` — device state that ONVIF Device Management Set* operations mutate at runtime (discovery mode, hostname, DNS, default gateway, network protocols, system date/time). Persisted so the simulator retains the last applied values across restarts.
   - `EventsConfig` — event service parameters (max pull points, default subscription timeout, topic list). Each `TopicConfig` entry has an `Enabled` flag; disabled topics are hidden from `GetEventProperties` but still routable by the broker.
@@ -70,7 +81,11 @@ Responsibilities are split into tightly separated layers. Folder names are inten
 
 - **WS-Discovery** — message encoding/decoding (Hello, Bye, Probe/ProbeMatch, Resolve/ResolveMatch), scope matching, and UDP multicast transport. Discovery Proxy is out of scope.
 
-- **Simulator lifecycle + front-ends** — the composition root that assembles the layers above into a runnable simulator, plus the GUI, TUI, and CLI surfaces. These exist as stubs today and will be wired up later.
+- **Embedded RTSP** (`internal/rtsp`) — in-process RTSP server (gortsplib) on **`NetworkConfig`'s RTSP port**. It starts when **at least one** profile has a usable source — `kind=file` with non-empty `media_file_path`, **or** `kind=rpicam` with `rpicam` configured. Each such profile is served at **`rtsp://<advertised-host>:<port>/<profile-token>`**. **`GetStreamUri`** always returns that form of URI for this device even when no source is registered (clients then see no media on that path). Sources implement the small `rtsp.Source` interface (`Describe`/`AttachStream`/`Ready`/`Run`); file-backed sources loop the MP4 (`looper`), live sources push access units through `LiveSource`. `Ready` lets the live path hold `DESCRIBE` until the first IDR so clients never see a pre-keyframe SDP. Video tracks are limited to **H.264 and H.265** packetization today.
+
+- **Raspberry Pi camera** (`internal/rpicamera`) — vendored and adapted from mediamtx's [rpicamera static source](https://github.com/bluenviron/mediamtx/tree/main/internal/staticsources/rpicamera). On a binary built with the `rpicam` tag (linux/arm or linux/arm64), `rpicamera.Open` extracts the embedded `mtxrpicam` helper into `/dev/shm`, fork+execs it, and surfaces H.264 access units through an `OnData` callback. On every other build the package compiles to a disabled stub whose `Open` returns `rpicamera.ErrUnsupported` so the simulator can fail with a clear "this build does not support the Raspberry Pi camera" message. Capture parameters live in `rpicamera.Params`; the upstream wire-format struct stays internal so the public surface tracks only what the simulator's `MediaConfig.RPICam` exposes.
+
+- **Simulator lifecycle + front-ends** — `internal/simulator` is the composition root: it starts the HTTP server (ONVIF SOAP), optional embedded RTSP, WS-Discovery, and the event broker. **CLI** entrypoint is **`cmd/cli`** (`serve` by default, plus `tui`, `config`, `event`). **GUI** entrypoint is **`cmd/gui`** (Wails app in **`internal/gui`**). **TUI** is **`internal/tui`**, driven from the CLI **`tui`** subcommand.
 
 - **Observability** — every long-lived component (auth, event broker, ONVIF service handlers, RTSP server, WS-Discovery listener, simulator lifecycle) accepts a `*slog.Logger` via a `WithLogger` functional option. Nil falls back to a discard logger so unit tests can construct components without any wiring. The composition root creates a single root logger and derives child loggers via `.With("component", "<name>")`. SOAP HTTP endpoints are wrapped in a request middleware that attaches a request id, a request-scoped logger, and emits one summary log line per request (level scaled by HTTP status). The logger is **owned by the simulator**, not the front-ends: when constructed without an explicit logger, the simulator reads `LoggingConfig` from the on-disk config and builds a single **file-only JSON sink** (defaulting to a path under `os.UserCacheDir`) plus an internal hot-reload State that the reload path mutates whenever `LoggingConfig` changes. Front-ends only forward optional flag/env overrides through `Options.LogLevel` / `Options.LogFile` and stay otherwise oblivious. There is no stderr/stdout sink: stdout is reserved for user-facing CLI program output, and stderr is only ever written by pre-logger fatal paths. Tests that need to capture records inject an `slog.Handler` via `Options.LogExtras`.
 

Makefile

@@ -18,7 +18,19 @@ endif
 
 FRONTEND_DIST := internal/gui/frontend/dist
 
-.PHONY: build cli gui gui-windows gui-darwin gui-linux format lint test test-go test-frontend coverage e2e clean setup manual
+# Pinned mediamtx-rpicamera release tag. mediamtx-rpicamera lives in its own
+# repo (bluenviron/mediamtx-rpicamera) with versioning independent from
+# mediamtx itself; mediamtx v1.13.1 internally pins this same v2.4.3 (see
+# its internal/staticsources/rpicamera/mtxrpicamdownloader/VERSION). Bump
+# together with scripts/mtxrpicam.sha256 so the Pi build channel ships a
+# reviewable, reproducible binary blob.
+MTXRPICAM_VERSION ?= v2.4.3
+RPICAM_DIR_32     := internal/rpicamera/mtxrpicam_32
+RPICAM_DIR_64     := internal/rpicamera/mtxrpicam_64
+
+.PHONY: build cli gui gui-windows gui-darwin gui-linux \
+        cli-rpi cli-rpi-arm cli-rpi-arm64 rpicam-fetch rpicam-build-check \
+        format lint test test-go test-frontend coverage e2e clean setup manual
 
 build: cli gui
 
@@ -37,6 +49,38 @@ gui-darwin: $(FRONTEND_DIST)
 gui-linux: $(FRONTEND_DIST)
 	cd cmd/gui && wails build -platform linux/amd64 -tags webkit2_41
 
+# Raspberry Pi build channel. Embeds mtxrpicam_{32,64} into the simulator
+# binary so a Pi user gets a single self-contained artifact. The fetch step
+# is idempotent: it skips the download when the on-disk blob already matches
+# the checksum pinned in scripts/mtxrpicam.sha256.
+rpicam-fetch: $(RPICAM_DIR_32)/mtxrpicam $(RPICAM_DIR_64)/mtxrpicam
+
+$(RPICAM_DIR_32)/mtxrpicam:
+	./scripts/fetch-mtxrpicam.sh 32 $(MTXRPICAM_VERSION) $(RPICAM_DIR_32)
+
+$(RPICAM_DIR_64)/mtxrpicam:
+	./scripts/fetch-mtxrpicam.sh 64 $(MTXRPICAM_VERSION) $(RPICAM_DIR_64)
+
+cli-rpi: cli-rpi-arm cli-rpi-arm64
+
+cli-rpi-arm: rpicam-fetch
+	GOOS=linux GOARCH=arm GOARM=7 CGO_ENABLED=0 \
+	  $(GO) build -tags rpicam -o bin/$(BINARY)-rpi-arm ./cmd/cli
+
+cli-rpi-arm64: rpicam-fetch
+	GOOS=linux GOARCH=arm64 CGO_ENABLED=0 \
+	  $(GO) build -tags rpicam -o bin/$(BINARY)-rpi-arm64 ./cmd/cli
+
+# rpicam-build-check verifies that the rpicam-tagged code paths still compile
+# without spending time downloading the upstream binary. PR CI calls this; it
+# relies on the placeholder file checked into mtxrpicam_{32,64}/ to satisfy
+# //go:embed and cross-compiles for both Pi targets.
+rpicam-build-check:
+	GOOS=linux GOARCH=arm GOARM=7 CGO_ENABLED=0 \
+	  $(GO) build -tags rpicam ./...
+	GOOS=linux GOARCH=arm64 CGO_ENABLED=0 \
+	  $(GO) build -tags rpicam ./...
+
 format:
 	golangci-lint fmt ./...
 

NOTICE

@@ -0,0 +1,36 @@
+onvif-simulator
+Copyright (c) 2025 GyeongHo Kim and contributors
+
+Licensed under the MIT License (see LICENSE).
+
+================================================================================
+Third-party software embedded in this distribution
+================================================================================
+
+The Raspberry Pi build channel (binaries with the rpicam build tag, named
+onvif-simulator-rpi-arm and onvif-simulator-rpi-arm64) embeds the mtxrpicam
+capture helper from the mediamtx project:
+
+  Project: mediamtx
+  URL:     https://github.com/bluenviron/mediamtx
+  License: MIT
+
+The mtxrpicam helper dynamically links against libcamera at runtime:
+
+  Project: libcamera
+  URL:     https://libcamera.org
+  License: LGPL-2.1-or-later
+
+End-user replacement of libcamera is possible through the standard library-
+replacement provisions of the LGPL by replacing the libcamera*.so files on the
+target Raspberry Pi OS image. mediamtx and libcamera license texts apply
+unchanged when distributed inside the Raspberry Pi build channel artifacts.
+
+The default build channel (linux/darwin/windows × amd64/arm64) does NOT embed
+mtxrpicam; this notice is shipped in every archive for legal hygiene.
+
+The Go-language portions of internal/rpicamera/ are adapted from
+github.com/bluenviron/mediamtx/internal/staticsources/rpicamera (MIT). The
+adaptation strips mediamtx-internal types and replaces them with simulator-
+local equivalents but keeps the wire protocol with mtxrpicam unchanged so the
+upstream-released binary stays compatible.