281 lines
14 KiB
Markdown
281 lines
14 KiB
Markdown
## Roadmap – Dynamische Kamera-Konfiguration (config.html)
|
||
|
||
**Ziel:** Live-Auflösung pro Kamera zur Laufzeit umschalten, ohne Datei-Editor oder
|
||
Container-Restart. Erreichbar über einen Link aus `index.html`.
|
||
|
||
**Priorität (unverändert):** Latenz > CPU > Bildqualität. Bandbreite ist der Engpass
|
||
beim Internet-Zugriff.
|
||
|
||
---
|
||
|
||
## Kontext
|
||
|
||
Alle drei Kameras (C270, C920, C922) unterstützen dieselben MJPEG-nativen Auflösungen.
|
||
Auf dem Host bestätigt (`v4l2-ctl --list-formats-ext`):
|
||
|
||
| Auflösung | Pixel | Faktor ggü. 640×480 | Seitenverhältnis |
|
||
|-----------|-------|----------------------|------------------|
|
||
| 160×120 | 19'200 | −94% | 4:3 |
|
||
| 320×240 | 76'800 | −75% | 4:3 |
|
||
| 640×360 | 230'400 | −25% | 16:9 |
|
||
| 640×480 | 307'200 | Referenz (aktuell) | 4:3 |
|
||
| 800×600 | 480'000 | +56% | 4:3 |
|
||
| 1280×720 | 921'600 | +200% | 16:9 |
|
||
|
||
Nur MJPEG-native Auflösungen verwenden – sonst fällt V4L2 auf YUYV (unkomprimiert) zurück
|
||
und FFmpeg muss software-encoden (~50% CPU pro Kamera). Siehe `09_Bug_reports.md`.
|
||
|
||
---
|
||
|
||
## ℹ️ Info: C920 Bandbreiten-Anomalie (nur Doku, NICHT umsetzen)
|
||
|
||
Messung auf dem Host (2026-06-07), alle Kameras auf `liveSize: 320x240`:
|
||
|
||
| Setup | Gesamt-Bandbreite |
|
||
|-------|-------------------|
|
||
| nur cam0 (C270) bzw. cam1 (C270) | ~4 Mbps pro Kamera |
|
||
| **cam2 (C920) allein** | **~13 Mbps** |
|
||
|
||
**Befund:** Die C920 produziert bei kleinen 4:3-Auflösungen (320×240) unverhältnismässig
|
||
grosse MJPEG-Frames. Ihr Hardware-Encoder ist für den nativen 1920×1080-Sensor (16:9)
|
||
kalibriert und komprimiert bei heruntergerechneten 4:3-Formaten kaum – ~3× mehr Bandbreite
|
||
als die C270 bei identischer Auflösung. Die `compression_quality` lässt sich per V4L2 nicht
|
||
steuern (auf dem Host geprüft: Control existiert nicht), und es gibt kein Logitech-Tool dafür.
|
||
|
||
**Mögliche spätere Gegenmassnahmen für cam2 (bewusst NICHT Teil dieser Roadmap):**
|
||
|
||
1. **Native 16:9-Auflösung erzwingen** – `640x360` statt `320x240`. Mehr Pixel, aber der
|
||
Encoder arbeitet im nativen Seitenverhältnis evtl. effizienter. Muss gemessen werden.
|
||
2. **FPS senken** – `liveFps: 10` für cam2. Linear weniger Bandbreite, keine Latenz-Kosten.
|
||
3. **Server-Re-Encode** – `"encode": "mjpeg"` + steuerbares `-q:v` nur für cam2. Volle
|
||
Kontrolle über die Frame-Grösse, kostet aber ~20% CPU für diese eine Kamera.
|
||
|
||
→ Diese drei Punkte sind ein separates Thema (MJPEG-Qualität / FPS). Diese Roadmap deckt
|
||
**nur die Auflösungs-Umschaltung** ab. Die Erkenntnis ist hier nur dokumentiert, damit bei
|
||
der UI-Auswahl klar ist, warum 320×240 für die C920 nicht automatisch „sparsam" bedeutet.
|
||
|
||
---
|
||
|
||
## Geplante UI: `/config.html`
|
||
|
||
Separate Admin-Seite (kein Viewer-Umbau nötig). Pro Kamera eine Zeile mit ComboBox:
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ AppRobotWebcam · Konfiguration [← zum Viewer] │
|
||
├──────────┬──────────────┬────────────────┬──────────────┤
|
||
│ cam0 │ Kamera 0 │ [320×240 ▼] │ aktuell: 320×240 │
|
||
│ cam1 │ Kamera 1 │ [640×360 ▼] │ aktuell: 640×360 │
|
||
│ cam2 │ Kamera 2 ⚠ │ [Aus ▼] │ aktuell: aus │
|
||
├──────────┴──────────────┴────────────────┴──────────────┤
|
||
│ Status: bereit [Speichern & Anwenden] │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**ComboBox-Optionen pro Kamera** (zentral als Konstante, von Server + Client geteilt):
|
||
`Aus`, `160×120`, `320×240`, `640×360`, `640×480`, `800×600`, `1280×720`
|
||
|
||
- `Aus` → `stream: false` = **Snapshot-Modus**: kein Video. Der Viewer zeigt stattdessen
|
||
alle 15 s ein **HD-Einzelbild** (`GET /api/snapshot/<id>/hires`, HD-Auflösung pro Kamera
|
||
aus cameras.json) mit grossem Banner „Single Picture no Video". Server-seitig öffnet jeder
|
||
Grab das Gerät kurz und schliesst es wieder → Gerät meist geschlossen, minimale Mobil-
|
||
Bandbreite (1 HD-JPEG / 15 s statt 30 Frames/s). Der generische Endpunkt
|
||
`GET /api/snapshot/<id>` (z. B. fürs Homing) bleibt unverändert (Live-Frame bzw. one-shot
|
||
via `grabSnapshot()` an `liveSize`).
|
||
- Auflösung → `stream: true` + `liveSize: "<W>x<H>"` (kontinuierlicher MJPEG-Stream)
|
||
- Bei cam2 (C920) ein dezenter ⚠-Hinweis-Tooltip: „C920 braucht bei kleinen 4:3-Auflösungen
|
||
überdurchschnittlich Bandbreite – siehe Doku."
|
||
|
||
---
|
||
|
||
## Implementierung
|
||
|
||
Reihenfolge: Phase 3 (Hot-Reload) → Phase 1 (API) → Phase 2 (UI) → Phase 4 (Link).
|
||
So ist jede Phase einzeln testbar (zuerst per `curl`, dann erst die UI).
|
||
|
||
### Erlaubte Auflösungen – Single Source of Truth
|
||
|
||
Neue Datei `src/liveSizes.js`, von `server.js` und `config.html` (über `/api/config`) genutzt:
|
||
|
||
```js
|
||
'use strict';
|
||
// MJPEG-native Auflösungen ALLER eingesetzten Kameras (C270/C920/C922).
|
||
// Auf dem Host mit `v4l2-ctl --list-formats-ext` verifiziert (2026-06-07).
|
||
const LIVE_SIZES = ['160x120', '320x240', '640x360', '640x480', '800x600', '1280x720'];
|
||
module.exports = { LIVE_SIZES };
|
||
```
|
||
|
||
`videoOutArgs`/Re-Encode bleibt unberührt. Validierung im POST-Handler nutzt diese Liste.
|
||
|
||
### Phase 3 – Hot-Reload in `CameraSwitch` (`src/cameraSwitch.js`)
|
||
|
||
Neue Methode `reconfigure({ liveSize, stream })`. Nutzt die vorhandenen Bausteine
|
||
(`_killCurrentAndWait`, `_spawnLive`), respektiert Lock und On-Demand:
|
||
|
||
```js
|
||
async reconfigure({ liveSize, stream } = {}) {
|
||
// Während eines HD-Grabs nicht eingreifen – nach dem Grab gilt eh die neue liveSize.
|
||
if (this.lock) { if (liveSize) this.liveSize = liveSize; this.streamEnabled = stream; return; }
|
||
|
||
const sizeChanged = liveSize && liveSize !== this.liveSize;
|
||
if (liveSize) this.liveSize = liveSize;
|
||
|
||
// Laufenden Live-Prozess stoppen, damit er mit neuer Auflösung neu startet.
|
||
if (sizeChanged && this.proc && this.state === 'live') {
|
||
await this._killCurrentAndWait(); // FD frei (close-Event)
|
||
}
|
||
// Neu starten nur wenn Stream erwünscht UND (On-Demand: Verbraucher vorhanden).
|
||
if (this.state === 'stopped' && !this.proc &&
|
||
(!this.onDemand || this.subscribers > 0)) {
|
||
this._spawnLive();
|
||
}
|
||
}
|
||
```
|
||
|
||
> **Umgesetzt:** `CameraSwitch` hat ein `streamEnabled`-Flag, das NUR den kontinuierlichen
|
||
> Live-Stream sperrt (`_spawnLive`/`acquire`/`_scheduleRestart` sind dadurch gegated).
|
||
> Einzel-Snapshots umgehen das über `grabSnapshot()` (one-shot open/grab/close an
|
||
> `liveSize`) – so liefert eine „Aus"-Kamera weiterhin Bilder, ohne dauerhaft zu streamen.
|
||
> `reconfigure({stream:false})` killt einen evtl. laufenden Live-Prozess und startet ihn
|
||
> nicht neu.
|
||
|
||
**Wichtig – laufende Browser-`<img>`-Streams:** Eine reine *Auflösungs*-Änderung ist für
|
||
den Client nahtlos – der multipart-Stream läuft weiter, nur die Frame-Grösse ändert sich
|
||
(kurzes Einfrieren während des FFmpeg-Neustarts, wie beim HD-Grab). Ein *Aus*-Schalten wirkt
|
||
erst nach Viewer-Reload. Das in der UI-Statuszeile vermerken.
|
||
|
||
### Phase 1 – API (`server.js`, neuer Router `src/configService.js`)
|
||
|
||
`server.js` hält bereits `camerasJson` (vollständig geparst) und `switches`/`camsMeta`.
|
||
Den geparsten `camerasJson` als `let` im Modulscope behalten, damit der POST-Handler beim
|
||
Schreiben **alle übrigen Felder erhält** (device, name, hiresSize, note …) und nur
|
||
`liveSize`/`stream` patcht.
|
||
|
||
**GET `/api/config`** → aktuelle Konfiguration + erlaubte Optionen:
|
||
```json
|
||
{
|
||
"liveSizes": ["160x120","320x240","640x360","640x480","800x600","1280x720"],
|
||
"cameras": [
|
||
{ "id": "cam0", "name": "Kamera 0", "liveSize": "320x240", "stream": true },
|
||
{ "id": "cam1", "name": "Kamera 1", "liveSize": "640x360", "stream": true },
|
||
{ "id": "cam2", "name": "Kamera 2", "liveSize": "320x240", "stream": false }
|
||
]
|
||
}
|
||
```
|
||
`liveSize` pro Kamera aus `switches[id].liveSize` (Laufzeit-Wahrheit), `stream`/`name` aus
|
||
`camsMeta`.
|
||
|
||
**POST `/api/config`** (Body = Array von `{ id, liveSize?, stream }`):
|
||
1. **Validieren:** jede `id` muss existieren; `liveSize` (falls gesetzt) muss in
|
||
`LIVE_SIZES` sein; sonst `400` mit Fehlertext, **keine** Teiländerung.
|
||
2. **In-Memory patchen:** `camsMeta[i].stream` setzen; in `camerasJson.cameras[i]`
|
||
`liveSize`/`stream` setzen (übrige Felder bleiben).
|
||
3. **Persistieren:** `cameras.json` atomar schreiben → in `cameras.json.tmp` schreiben,
|
||
dann `fs.renameSync` über das Original (kein halb-geschriebenes File bei Crash).
|
||
4. **Anwenden:** für jede geänderte Kamera `await switches[id].reconfigure({...})`.
|
||
5. Antwort `200` mit der frischen Config (wie GET), damit die UI sofort den Ist-Stand zeigt.
|
||
|
||
`express.json()`-Middleware in `server.js` ergänzen (aktuell nicht aktiv). Router unter
|
||
`app.use('/api/config', createConfigRouter(switches, camsMeta, () => camerasJson, persistFn))`.
|
||
|
||
### Phase 2 – `public/config.html` + `public/config.js`
|
||
|
||
- Stil aus `index.html` übernehmen (dunkles Monospace-Theme, gleiche Header-Leiste).
|
||
- Beim Laden `GET /api/config` → Tabelle rendern, `<select>` aus `liveSizes` + `Aus`,
|
||
aktuellen Wert vorselektieren.
|
||
- `[Speichern & Anwenden]` → `POST /api/config` mit dem Array; Statuszeile zeigt
|
||
Erfolg/Fehler. Bei Erfolg Hinweis: „Auflösungs-Änderung sofort aktiv; Ein/Aus erst nach
|
||
Viewer-Reload."
|
||
- Link `[← zum Viewer]` zurück auf `/`.
|
||
- Keine Authentifizierung (internes Netz, wie der Viewer). Bei späterem Internet-Zugang
|
||
nachrüsten (siehe Abgrenzung).
|
||
|
||
### Phase 4 – Link aus `index.html`
|
||
|
||
In die `<header>`-Leiste von `public/index.html` einen Link neben `#snapAllBtn` setzen,
|
||
z. B. vor oder nach dem Snapshot-Button:
|
||
```html
|
||
<a id="configLink" href="config.html" title="Kamera-Konfiguration">⚙ Config</a>
|
||
```
|
||
Styling analog `#snapAllBtn` (kleiner Button-Look, `margin-left`/Reihenfolge beachten,
|
||
damit `snapAllBtn` mit `margin-left:auto` weiterhin rechts bündig bleibt – Link davor
|
||
einfügen oder eine kleine Flex-Gruppe rechts bilden).
|
||
|
||
---
|
||
|
||
## Test-Strategie
|
||
|
||
Zwei Ebenen: **Jest-Unit-Tests** für reine Logik (auf der Dev-Maschine, ohne Hardware) und
|
||
**Host-Tests** für alles, was echte Kameras/FFmpeg/Bandbreite betrifft.
|
||
|
||
### Phase 5 – Jest-Unit-Tests (neu)
|
||
|
||
**Setup** (Jest wird in anderen Projekten bereits genutzt):
|
||
- `package.json`: `jest` als **devDependency** + Script `"test": "jest"`.
|
||
- Wichtig: `docker-compose.yaml` installiert mit `npm install --omit=dev` → Jest landet
|
||
**nicht** im Container, bläht das Image nicht auf. Tests laufen nur lokal/CI.
|
||
- Konvention: Tests unter `test/*.test.js` (CommonJS, wie der Rest des Projekts).
|
||
- **Der bestehende `test/grabSnapShot.py` bleibt unverändert** – das ist der manuelle
|
||
Integrationstest gegen den laufenden Server, keine Jest-Datei (`testMatch` greift nur
|
||
`*.test.js`, `.py` wird ignoriert).
|
||
|
||
**Test-Umfang – nur testbare reine Logik / Entscheidungslogik:**
|
||
|
||
| Datei | Was getestet wird |
|
||
|-------|-------------------|
|
||
| `test/configValidate.test.js` | POST-Validierung: unbekannte `id` → Fehler; `liveSize` ∉ `LIVE_SIZES` → Fehler; `Aus`/`stream:false` ok; gültige Auflösung ok. Kein Teil-Apply bei einem Fehler. |
|
||
| `test/configMerge.test.js` | **Kernrisiko:** Patch von `liveSize`/`stream` in einem cameras.json-Objekt lässt `device`, `name`, `hiresSize`, `note` etc. unangetastet. Reine Objekt-Transformation (kein fs). |
|
||
| `test/reconfigure.test.js` | `CameraSwitch.reconfigure()` mit gemockten `_killCurrentAndWait`/`_spawnLive` (und gemocktem `spawn`): geänderte `liveSize` → genau 1× kill + 1× spawn; keine Änderung → no-op; `lock===true` → nur Feld setzen, kein kill/spawn. |
|
||
| `test/mpjpegParser.test.js` | **Bonus, schon jetzt sinnvoll:** `MpjpegParser` (bereits exportiert) – ein Frame, mehrere Frames in einem Chunk, über Chunk-Grenzen gesplittetes Frame, Müll vor Header. |
|
||
| `test/readJpegWidth.test.js` | **Bonus:** `readJpegWidth` mit echten kleinen JPEG-Headern (SOF0/SOF2) + Fehlerfall (kein Marker → `null`). |
|
||
|
||
**Damit gut testbar wird,** Validierung und Merge als **reine, exportierte Funktionen**
|
||
faktorieren (z. B. in `src/configService.js`):
|
||
```js
|
||
function validateConfig(reqCameras, knownIds, liveSizes) { /* → {ok, errors} */ }
|
||
function mergeConfig(camerasJson, patch) { /* → neues camerasJson, übrige Felder erhalten */ }
|
||
```
|
||
So braucht der Test weder Express noch fs noch FFmpeg.
|
||
|
||
**Nicht** Jest-getestet (bewusst, gehört auf den Host): echtes `/dev/videoN`-Öffnen,
|
||
FFmpeg-Spawn, atomares `fs.rename` gegen ein reales Volume, Bandbreite/Latenz.
|
||
|
||
### Host- / Integrationstests (wie gehabt)
|
||
|
||
1. **Phase 1 per curl** (vor der UI):
|
||
```bash
|
||
curl http://<host>:8444/api/config
|
||
curl -X POST http://<host>:8444/api/config -H 'Content-Type: application/json' \
|
||
-d '{"cameras":[{"id":"cam0","liveSize":"640x360","stream":true}]}'
|
||
```
|
||
Danach `cameras.json` prüfen (übrige Felder erhalten?) und im Viewer das Live-Bild auf
|
||
neue Auflösung kontrollieren.
|
||
2. **Auf dem Host messen**, nicht vorhersagen (Bandbreite vor/nach pro Kamera), gemäss
|
||
`04_Delay_roadmap.md` / Memory.
|
||
3. **`test/grabSnapShot.py`** unverändert als Smoke-Test der HD-Grab-Kette weiterverwenden.
|
||
|
||
---
|
||
|
||
## Abgrenzung (NICHT im Scope dieser Roadmap)
|
||
|
||
- MJPEG Re-Encode-Qualität (`-q:v`) und C920-Gegenmassnahmen → siehe Info-Block oben,
|
||
separates Thema.
|
||
- `liveFps` per Kamera im UI → triviale spätere Erweiterung, exakt analog zu `liveSize`.
|
||
- Authentifizierung auf `/config.html` → erst bei geplantem Internet-Zugang.
|
||
- `hiresSize` per Kamera (HD-Grab) → bereits in `cameras.json`, kein UI nötig.
|
||
- Persistenz-Konflikt: Wenn `cameras.json` per Volume gemountet ist (siehe
|
||
`docker-compose.yaml`), landet die Änderung dauerhaft auf dem Host – gewünscht. Bei
|
||
read-only-Mount würde Schritt 3 fehlschlagen → dann sauber `500` melden.
|
||
|
||
---
|
||
|
||
## Manueller Test (sofort möglich, ohne diese Roadmap)
|
||
|
||
`cameras.json` direkt bearbeiten und Container neu starten:
|
||
|
||
```json
|
||
{ "id": "cam0", "...": "...", "liveSize": "320x240" }
|
||
```
|
||
|
||
Fehlt `liveSize`, gilt der globale `LIVE_SIZE`-Default (640×480, aus `server.js`/Env).
|