Add documentation, manual and screenshots preview

2026-07-23 21:24:48 +02:00
commit d6cda77aaf
40 changed files with 1571 additions and 0 deletions
@@ -0,0 +1,65 @@
+# API endpoints
+
+Roller nedenfor er den tilsigtede adgangsrolle for Release 1.0. Den nuværende kodebase dokumenterer rollerne, men håndhæver dem endnu ikke konsekvent i runtime.
+
+| Metode | Sti | Rolle | Formål |
+| --- | --- | --- | --- |
+| `GET` | `/api/v1/health` | Read only | Health check til lokal drift og monitoring. |
+| `GET` | `/api/v1/system/status` | Read only | Samlet systemstatus med engine, telemetri og BPM. |
+| `GET` | `/api/v1/system/diagnostics` | Administrator | Udvidet diagnostik til support og bundle. |
+| `POST` | `/api/v1/system/restart-service` | Administrator | Planlægger restart af TuxDMX-servicen på Linux-værten. |
+| `GET` | `/api/v1/dmx/status` | Read only | DMX-engine status og backendforbindelse. |
+| `GET` | `/api/v1/dmx/devices` | Operator | Liste over tilgængelige DMX-backends/devices. |
+| `GET` | `/api/v1/dmx/universes` | Operator | Oversigt over univers-konfiguration. |
+| `GET` | `/api/v1/dmx/frame` | Read only | Aktuelt DMX-frame og source-map. |
+| `POST` | `/api/v1/dmx/test-channel` | Operator | Midlertidig kanaltest til setup/diagnostik. |
+| `POST` | `/api/v1/dmx/blackout` | Operator | Aktiverer blackout med højeste prioritet. |
+| `POST` | `/api/v1/dmx/release-blackout` | Operator | Frigiver blackout. |
+| `GET` | `/api/v1/fixtures` | Operator | Lister lokalt importerede fixtures. |
+| `POST` | `/api/v1/fixtures/search-ofl` | Operator | Søger fixtures via OFL eller lokal fallback. |
+| `POST` | `/api/v1/fixtures/preview-ofl` | Operator | Henter preview og normaliseret modeoversigt før import. |
+| `POST` | `/api/v1/fixtures/import-ofl` | Operator | Importerer fixture fra OFL til lokal cache/runtime. |
+| `POST` | `/api/v1/fixtures/import-file` | Operator | Importerer fixture fra lokal/custom payload. |
+| `POST` | `/api/v1/fixtures/custom` | Operator | Opretter custom fixture uden OFL. |
+| `GET` | `/api/v1/fixtures/{id}` | Operator | Henter ét lokalt fixture. |
+| `PUT` | `/api/v1/fixtures/{id}` | Operator | Opdaterer et lokalt fixture. |
+| `DELETE` | `/api/v1/fixtures/{id}` | Administrator | Sletter et lokalt fixture. |
+| `GET` | `/api/v1/patch` | Operator | Lister patch-entries. |
+| `POST` | `/api/v1/patch` | Operator | Opretter patch-entry. |
+| `PUT` | `/api/v1/patch/{id}` | Operator | Opdaterer patch-entry. |
+| `DELETE` | `/api/v1/patch/{id}` | Operator | Sletter patch-entry. |
+| `POST` | `/api/v1/patch/validate` | Operator | Validerer startadresse og kanalantal. |
+| `GET` | `/api/v1/scenes` | Operator | Lister scener. |
+| `POST` | `/api/v1/scenes` | Operator | Opretter scene. |
+| `GET` | `/api/v1/scenes/{id}` | Operator | Henter scene. |
+| `PUT` | `/api/v1/scenes/{id}` | Operator | Opdaterer scene. |
+| `DELETE` | `/api/v1/scenes/{id}` | Operator | Sletter scene. |
+| `POST` | `/api/v1/scenes/{slug}/activate` | Operator | Aktiverer scene på engine-stacken. |
+| `POST` | `/api/v1/scenes/{slug}/release` | Operator | Frigiver scene-layer. |
+| `GET` | `/api/v1/effects` | Operator | Lister effekter. |
+| `POST` | `/api/v1/effects` | Operator | Opretter effekt. |
+| `PUT` | `/api/v1/effects/{id}` | Operator | Opdaterer effekt. |
+| `DELETE` | `/api/v1/effects/{id}` | Operator | Sletter effekt. |
+| `POST` | `/api/v1/effects/{slug}/trigger` | Operator | Trigger effekt på engine-stacken. |
+| `POST` | `/api/v1/effects/{slug}/stop` | Operator | Stopper aktiv effekt. |
+| `GET` | `/api/v1/bpm/status` | Read only | Aktuel BPM-status, mode og confidence. |
+| `POST` | `/api/v1/bpm/manual` | Operator | Sætter manuel BPM. |
+| `POST` | `/api/v1/bpm/tap` | Operator | Registrerer tap-tempo. |
+| `POST` | `/api/v1/bpm/audio/start` | Operator | Starter audioanalyse mod valgt ALSA- eller syntetisk inputdevice. |
+| `POST` | `/api/v1/bpm/audio/stop` | Operator | Stopper audio-mode. |
+| `POST` | `/api/v1/bpm/external` | Operator | Sætter BPM fra ekstern kilde/API. |
+| `GET` | `/api/v1/bpm/devices` | Operator | Lister tilgængelige BPM-devices/kilder. |
+| `GET` | `/api/v1/integrations/mixitup` | Administrator | Lister MixItUp-integrationer. |
+| `POST` | `/api/v1/integrations/mixitup` | Administrator | Opretter MixItUp-integration. |
+| `PUT` | `/api/v1/integrations/mixitup/{id}` | Administrator | Opdaterer MixItUp-integration. |
+| `DELETE` | `/api/v1/integrations/mixitup/{id}` | Administrator | Sletter MixItUp-integration. |
+| `POST` | `/api/v1/integrations/mixitup/{id}/test` | Administrator | Tester MixItUp-integration. |
+| `POST` | `/api/v1/triggers/{slug}` | API token | Hurtigt triggerendpoint til MixItUp/Twitch. |
+| `GET` | `/api/v1/telemetry/live` | Read only | Aktuel telemetri. |
+| `GET` | `/api/v1/telemetry/history` | Read only | Historiske samples. |
+| `GET` | `/api/v1/events` | Read only | Nylige systemevents. |
+| `GET` | `/api/v1/logs` | Administrator | Hændelser/logfeed. |
+| `POST` | `/api/v1/backups` | Administrator | Opretter ZIP-backup i simulator/runtime. |
+| `GET` | `/api/v1/backups` | Administrator | Lister tilgængelige backups. |
+| `POST` | `/api/v1/backups/{id}/restore` | Administrator | Gendanner backup og opretter pre-restore backup. |
+| `DELETE` | `/api/v1/backups/{id}` | Administrator | Sletter backuparkiv. |
@@ -0,0 +1,37 @@
+# BPM-kilder
+
+## Manual
+
+- Endpoint: `POST /api/v1/bpm/manual?bpm=<tal>`
+- UI: knapper og direkte værdisætning
+- Status: fuldt implementeret i simulator/runtime
+
+## Tap
+
+- Endpoint: `POST /api/v1/bpm/tap`
+- UI: `Tap tempo`
+- Algoritme: median af de seneste tap-intervaller inden for et kort vindue
+- Status: implementeret og verificerbar lokalt
+
+## Audio input
+
+- Endpoints:
+  - `POST /api/v1/bpm/audio/start?device=<navn>`
+  - `POST /api/v1/bpm/audio/stop`
+  - `GET /api/v1/bpm/devices`
+- Devices i denne leverance:
+  - `synthetic-click-track`
+  - `jack:auto`
+  - `alsa:default`
+- Status: simuleret/delvist implementeret. API og UI findes, men ægte audioanalyse mod aubio/JACK/ALSA er ikke implementeret endnu i denne kodebase.
+
+## External
+
+- Endpoint: `POST /api/v1/bpm/external?bpm=<tal>`
+- Status: implementeret som simpel ekstern BPM-injektion
+
+## Verifikation uden hardware
+
+- Manual og tap kan verificeres direkte i UI eller via API.
+- Audio-mode kan verificeres som simulator-flow og device-API, men ikke som ægte beat detection uden videre implementation.
+
@@ -0,0 +1,54 @@
+# Dependencies og licenser
+
+Denne oversigt dækker de deklarerede direkte afhængigheder i repositoryet samt de eksterne platformskomponenter, som systemet integrerer med.
+
+## Python
+
+| Pakke | Version | Licensfelt | Formål |
+| --- | --- | --- | --- |
+| `alembic` | `1.14.0` | `MIT` | Database migrations |
+| `aiosqlite` | `0.20.0` | `ikke deklareret i metadata` | Async SQLite-driver |
+| `argon2-cffi` | `23.1.0` | `ikke deklareret i metadata` | Password hashing |
+| `fastapi` | `0.115.6` | `ikke deklareret i metadata` | REST API og WebSocket-app |
+| `httpx` | `0.28.1` | `BSD-3-Clause` | OFL HTTP-klient |
+| `pydantic` | `2.10.4` | `ikke deklareret i metadata` | Datavalidering |
+| `pydantic-settings` | `2.7.0` | `MIT` | Settings fra env |
+| `psutil` | `6.1.1` | `BSD-3-Clause` | Systemtelemetri |
+| `python-multipart` | `0.0.20` | `ikke deklareret i metadata` | Multipart/form parsing |
+| `sqlalchemy` | `2.0.36` | `MIT` | ORM og DB-lag |
+| `uvicorn` | `0.34.0` | `BSD-3-Clause` | ASGI-server |
+| `mypy` | `1.14.1` | `MIT` | Typecheck |
+| `pytest` | `8.3.4` | `MIT` | Test |
+| `pytest-asyncio` | `0.25.2` | `Apache 2.0` | Async tests |
+| `pytest-cov` | `6.0.0` | `MIT` | Coverage/testhjælp |
+| `ruff` | `0.8.6` | `MIT` | Linting |
+
+## Frontend / Node
+
+| Pakke | Version | Licens | Formål |
+| --- | --- | --- | --- |
+| `react` | `18.3.1` | `MIT` | UI runtime |
+| `react-dom` | `18.3.1` | `MIT` | DOM rendering |
+| `@testing-library/jest-dom` | `6.6.3` | `MIT` | DOM assertions |
+| `@testing-library/react` | `16.1.0` | `MIT` | React UI-tests |
+| `@eslint/js` | `9.18.0` | `MIT` | ESLint base config |
+| `@types/react` | `18.3.18` | `MIT` | TypeScript typer |
+| `@types/react-dom` | `18.3.5` | `MIT` | TypeScript typer |
+| `@vitejs/plugin-react` | `4.3.4` | `MIT` | Vite React-plugin |
+| `eslint` | `9.18.0` | `MIT` | Frontend linting |
+| `eslint-plugin-react-hooks` | `5.1.0` | `MIT` | React Hook-regler |
+| `eslint-plugin-react-refresh` | `0.4.16` | `MIT` | Vite/React refresh-regler |
+| `globals` | `15.14.0` | `MIT` | Browser-globals til ESLint |
+| `jsdom` | `25.0.1` | `MIT` | Browser-lignende testmiljø |
+| `typescript` | `5.7.3` | `Apache-2.0` | TypeScript compiler |
+| `typescript-eslint` | `8.20.0` | `MIT` | TypeScript-parser og regler til ESLint |
+| `vite` | `6.0.7` | `MIT` | Frontend dev/build |
+| `vitest` | `2.1.8` | `MIT` | Frontend tests |
+
+## Eksterne komponenter
+
+| Komponent | Licensstatus | Rolle |
+| --- | --- | --- |
+| OLA / `olad` | ekstern systempakke, se distributionens licensinfo | DMX-backend |
+| Open Fixture Library | ekstern tjeneste/dataformat | Fixture-søgning og import |
+| SQLite | ekstern runtimekomponent | Lokal database |
@@ -0,0 +1,47 @@
+# Implementationsstatus
+
+## Fuldt implementeret og lokalt verificeret
+
+- FastAPI app-start og health endpoint
+- Simulator-DMX-backend
+- OLA-DMX-backend med rigtig `SendDmx`-integration via lokal OLA Python-klientadapter
+- 512-kanals frame-model
+- HTP/LTP merge og blackout-tests
+- Backend-status med `connected`, `last_successful_frame`, `frames_sent`, `send_errors`, `reconnect_count`, universe og output-port
+- Automatisk reconnect/degraded mode i OLA-backend samt mock OLA-adapter til tests
+- Sceneoprettelse og sceneaktivering i runtime
+- Effektoprettelse og trigger i runtime
+- Manual BPM
+- Tap BPM
+- MixItUp triggerendpoint med `202 Accepted`
+- WebSocket live-feed
+- Frontend dark UI med dashboard, fixtures, live desk, scenes, effects, BPM, MixItUp, DMX monitor, telemetry, backup og settings
+- Alembic migration fra tom database
+- Backup/restore i simulator-mode via service og API
+- Linux- og Pi-install/update/uninstall/diagnostics scripts som leverede artefakter
+- Debian 13 amd64 install/update/uninstall-flow med staging, frontend-build, `pip check`, OLA-importcheck og systemd health diagnostics
+- Patch med persisted grupper/link og fysisk placering
+- Fixture-/gruppebaserede scener med persisted targets
+- ALSA-baseret BPM-capture, device discovery og syntetiske audio-tests
+- Placering/view over patched fixtures i Web UI
+
+## Delvist implementeret
+
+- OLA-integrationen er implementeret og testet automatisk mod mock adapter. USB-DMX og OLA-output er verificeret af systemejeren på fysisk Debian 13 amd64-host, men ikke fysisk målt af Codex i denne workspace-session
+- Debian 13-installationsflowet er rettet og statisk/testmæssigt verificeret i repositoryet, men ikke end-to-end genkørt af Codex i en rigtig Debian VM i denne desktop-session
+- Fixtureimport persistes i runtime, men ikke fuldt i relationel database
+- MixItUp integrationer/mappings er dokumenteret, men ikke fuldt persisted eller rollebeskyttet
+- Telemetry history er kun stubbet som tom historik
+- Backup UI er funktionelt mod backup-endpoints, men uden download-knap
+
+## Simuleret
+
+- Hardwaretilstande som USB-frakobling og OLA-fejl via simulator/faults
+
+## Endnu ikke implementeret
+
+- Role enforcement og login/session-flow i hele API'et
+- Chaser-timeline og den fulde effektliste fra specifikationen
+- Avanceret patch-editor med flere universer og mere QLC+-agtig patch-oversigt
+- Historisk telemetrilagring, pruning og aggregering
+- Fuld scene/effect restore-stack med udløbstider og underliggende state-retur
@@ -0,0 +1,104 @@
+# MixItUp integration
+
+## Triggerendpoint
+
+Primært endpoint:
+
+```http
+POST /api/v1/triggers/{slug}
+Authorization: Bearer <mixitup-token>
+Content-Type: application/json
+```
+
+Eksempel med `raid`:
+
+```http
+POST /api/v1/triggers/raid
+Host: tuxdmx.local:8000
+Authorization: Bearer REPLACE_WITH_TOKEN
+Content-Type: application/json
+```
+
+```json
+{
+  "eventType": "raid",
+  "username": "streamviewer42",
+  "displayName": "StreamViewer42",
+  "amount": 120,
+  "eventId": "raid-evt-20260712-001",
+  "platform": "twitch",
+  "metadata": {
+    "source": "mixitup",
+    "notes": "Raid test i simulator"
+  }
+}
+```
+
+Forventet svar:
+
+```json
+{
+  "accepted": true,
+  "queue_depth": 1
+}
+```
+
+HTTP-status:
+
+```text
+202 Accepted
+```
+
+## Simple endpoints
+
+- `POST /api/v1/scenes/{sceneSlug}/activate`
+- `POST /api/v1/effects/{effectSlug}/trigger`
+- `POST /api/v1/dmx/blackout`
+- `POST /api/v1/bpm/tap`
+
+## Headers
+
+- `Authorization: Bearer <token>`
+- `Content-Type: application/json`
+
+Token må aldrig sendes i querystring.
+
+## MixItUp Web Request Action
+
+1. Vælg `POST`.
+2. Brug URL `http://<tuxdmx-host>:8000/api/v1/triggers/<slug>`.
+3. Tilføj header `Authorization` med `Bearer <token>`.
+4. Tilføj header `Content-Type` med `application/json`.
+5. Indsæt JSON-body.
+
+## Eksempel-body med MixItUp special identifiers
+
+```json
+{
+  "eventType": "raid",
+  "username": "$username",
+  "displayName": "$displayname",
+  "amount": "$raidviewercount",
+  "eventId": "$eventid",
+  "platform": "twitch",
+  "metadata": {
+    "eventName": "$eventname"
+  }
+}
+```
+
+## Test i simulator-mode
+
+```bash
+curl -i -X POST http://127.0.0.1:8000/api/v1/triggers/raid \
+  -H "Authorization: Bearer test-token" \
+  -H "Content-Type: application/json" \
+  -d '{"eventType":"raid","displayName":"AuditTest","amount":42,"eventId":"raid-audit-1","platform":"twitch","metadata":{}}'
+```
+
+## Sikkerhed
+
+- Roter token ved mistanke om læk.
+- Brug IP-allowlist eller reverse proxy, hvis endpointet eksponeres uden for isoleret LAN.
+- Rate limiting og duplicate/idempotency skal håndhæves server-side.
+
@@ -0,0 +1,74 @@
+# Open Fixture Library
+
+## Søgeflow
+
+1. Web UI sender `POST /api/v1/fixtures/search-ofl?query=<tekst>`.
+2. Backend bruger OFL API, eller falder tilbage til lokale testfixtures i `test-data/fixtures`.
+3. Resultater vises som `manufacturer/fixture`.
+
+## Preview
+
+Preview kaldes via:
+
+```http
+POST /api/v1/fixtures/preview-ofl?manufacturer_key=<manufacturer>&fixture_key=<fixture>
+```
+
+Preview returnerer normaliseret fixturedata uden at skrive til lokal fixtureliste.
+
+I UI kan brugeren:
+
+- åbne preview,
+- se schema-version,
+- se kategorier,
+- vælge og inspicere modes,
+- se kanalindeks, displaynavn, precedence og opløsning.
+
+## Import
+
+Import kaldes via:
+
+```http
+POST /api/v1/fixtures/import-ofl?manufacturer_key=<manufacturer>&fixture_key=<fixture>
+```
+
+Import:
+
+- henter rå OFL-data,
+- normaliserer til TuxDMX-format,
+- gemmer resultatet i lokal runtime/cache.
+
+## Modevalg
+
+Modevalg bruges i preview til inspektion af kanalstruktur. Importen bevarer alle normaliserede modes i fixturemodellen, så patch/UI senere kan vælge korrekt mode.
+
+## Fixture-normalisering
+
+Normalisering sker i `backend/app/fixtures/normalize.py`:
+
+- OFL JSON læses ikke direkte af runtime.
+- Hver mode bliver til en stabil intern struktur med:
+  - `key`
+  - `channel_count`
+  - `channels[]`
+- Hver kanal får:
+  - `index`
+  - `key`
+  - `display_name`
+  - `precedence`
+  - `resolution`
+
+Fallback-regel i denne leverance:
+
+- kanaler med `dim` i navnet bliver markeret som `HTP`
+- øvrige kanaler bliver markeret som `LTP`, medmindre OFL-data allerede angiver noget andet
+
+## Offline fallback
+
+Hvis OFL ikke kan nås, søger klienten i lokale fixtures under `test-data/fixtures`.
+
+## Begrænsninger i denne leverance
+
+- OFL update-diff, warnings og backup før fixturemigration er endnu ikke fuldt implementeret.
+- Runtime persistence til database for importerede fixtures er kun delvist implementeret; preview/import virker i simulator-runtime og kan verificeres via API/UI.
+
@@ -0,0 +1,323 @@
+# TuxDMX Manual
+
+## Formål
+
+TuxDMX er et browserbaseret lyskontrolsystem med disse hovedspor:
+
+- fysisk DMX-output via `OLA / USB-DMX`
+- virtuelle universer til Home Assistant-bro
+- fixture-baseret patch
+- scenes, live-mixer, effekter og BPM
+
+Denne manual beskriver den nuvaerende WebUI og de vigtigste arbejdsgange.
+
+## Vigtigt
+
+- Screenshots i denne mappe er genereret lokalt i `mock`-tilstand den 23. juli 2026.
+- De afspejler UI og flows, men er ikke bevis for fysisk hardwareafvikling.
+- Fysisk hardwaretest skal stadig vurderes separat paa target-maskinen.
+
+## Arkitektur kort fortalt
+
+- `Universe 1`
+  Typisk fysisk DMX-universe til OLA og USB-DMX.
+- `Universe 10`
+  Typisk internt universe til Home Assistant-mappings.
+- `Patch`
+  Bruges til rigtige DMX-fixtures med fixture-definition, mode, adresse og grupper.
+- `Home Assistant mappings`
+  Bruges til virtuelle enheder, som reagerer paa DMX-vaerdier fra et valgt HA-universe.
+
+## Foerstegangsopsætning
+
+### 1. DMX backend
+
+Gaa til `Settings` og vaelg:
+
+- `Backend = OLA / USB-DMX`
+- korrekt `Universe`
+- korrekt `OLA output-port`
+
+Gem derefter `DMX output`.
+
+### 2. Home Assistant-bro
+
+Hvis du vil styre Home Assistant parallelt:
+
+- indsaet `Base URL`
+- indsaet `Long-lived token`
+- saet `Standard HA-universe`, typisk `10`
+- saet `Bro aktiv = Ja`
+- tryk `Test forbindelse`
+- tryk `Hent HA-enheder`
+
+Der skal normalt ikke installeres noget ekstra i Home Assistant. TuxDMX bruger HA API direkte.
+
+### 3. Fixtures
+
+Gaa til `Fixtures` og:
+
+- soeg i OFL
+- preview fixture
+- import fixture
+
+Hvis din fixture ikke findes i OFL, kan du bruge fixture-fil import, hvis formatet er understoettet af TuxDMX.
+
+### 4. Patch
+
+Gaa til `Patch` og:
+
+- vaelg fixture
+- vaelg mode
+- giv fixture et navn
+- saet startadresse
+- brug grupper/link som fx `front`, `wash`, `synk-a`
+- gem patch
+
+## Daglig brug
+
+## Dashboard
+
+`Dashboard` er et overblik:
+
+- backend-status
+- BPM-status
+- kø-status
+- CPU/RAM/oppetid
+- hurtig adgang til blackout og systemkontrol
+
+## Live Desk
+
+`Live Desk` er den manuelle mixer.
+
+Her vises nu:
+
+- patched fixtures
+- virtuelle Home Assistant-enheder fra dine HA-mappings
+
+Du kan:
+
+- vaelge en enhed i venstre liste
+- se universe og kanalrange
+- justere kanaler live med sliders
+- nulstille den valgte enhed
+- bruge blackout / release blackout
+
+For HA-enheder vises ogsaa:
+
+- `entity_id`
+- status
+- senest sendte HA-servicekald
+
+## Fixtures
+
+`Fixtures` bruges til bibliotek og import:
+
+- OFL-soegning
+- OFL-preview
+- OFL-import
+- filimport
+- videresendelse til patch-flow
+
+## Patch
+
+`Patch` bruges til rigtig DMX-adressering:
+
+- fixturevalg
+- modevalg
+- start/slutadresse
+- overlap-validering
+- grupper/link
+- universe-grid
+- fysisk placering
+
+## Placering
+
+`Placering` viser patched fixtures som et simpelt layout-view.
+
+Det bruges til:
+
+- scene-layout
+- gruppering og overblik
+- senere visualisering og positionseffekter
+
+## Scener
+
+`Scener` er fixture- og gruppebaseret.
+
+Du bygger scener ud fra:
+
+- en bestemt fixture
+- eller en gruppe
+
+Derefter vaelger du attributter og vaerdier som fx:
+
+- Dimmer
+- RGB
+- strobe
+- andre importerede attributter fra fixture-mode
+
+## Effekter
+
+`Effekter` er beregnet til effekt- og triggerarbejde.
+
+Siden bruges til:
+
+- oprettelse af effekter
+- trigger
+- stop
+- senere BPM- og triggerbindinger
+
+## BPM
+
+`BPM` bruges til:
+
+- manuel BPM
+- tap tempo
+- audio-start og audio-stop
+- lydniveau og beatstatus
+- effektkobling til BPM
+
+ALSA-input skal vaelges i `Settings`, og derefter bruges BPM-siden til selve drift og trigger-workflow.
+
+## MixItUp
+
+`MixItUp` er til trigger-workflow og eksterne events.
+
+Herfra kan du teste triggerflow og senere knytte stream-events til scener eller effekter.
+
+## DMX monitor
+
+`DMX monitor` viser DMX-aktivitet.
+
+Formålet er:
+
+- se hvilke kanaler der bærer vaerdier
+- se hvor data kommer fra
+- kontrollere frame-output under fejlfinding
+
+## Telemetry
+
+`Telemetry` viser tekniske driftsdata:
+
+- CPU
+- RAM
+- temperatur, hvis tilgaengelig
+- reconnects
+- queue depth
+- events og fejlspor
+
+## Backup
+
+`Backup` bruges til:
+
+- backup-oprettelse
+- restore
+- hurtig recovery af driftstilstand
+
+## Settings
+
+`Settings` samler de vigtigste driftsindstillinger:
+
+- DMX output
+- Home Assistant-bro
+- BPM / audio-input
+- servicegenstart
+- host-genstart
+
+Det er her de fleste systemvalg foretages, men selve daglig styring foregaar typisk i `Live Desk`, `Scener`, `Effekter` og `BPM`.
+
+## Home Assistant workflow
+
+Den anbefalede model er:
+
+- fysisk DMX paa `Universe 1` via OLA / USB-DMX
+- HA-bro paa `Universe 10`
+
+Eksempel:
+
+- `Universe 10`, `adresse 1`, `fixturetype switch`, `entity light.loft_bunker`
+- `Universe 10`, `adresse 10`, `fixturetype rgb`, `entity light.bar_rgb`
+
+### Vigtigt om fixturetype
+
+`fixturetype` styrer kun hvordan TuxDMX fortolker DMX-data:
+
+- `switch`
+  binær on/off med hysterese
+- `dimmer`
+  brightness
+- `rgb`, `rgbw`, `cct`
+  farvepayload
+- `scene`, `automation`
+  rising-edge trigger
+
+Selve HA-service-domænet udledes nu fra `entity_id`, fx:
+
+- `light.loft_bunker` → `light.turn_on/off`
+- `switch.relay` → `switch.turn_on/off`
+- `scene.party_mode` → `scene.turn_on`
+- `automation.something` → `automation.trigger`
+
+## Opdatering og deploy
+
+### Windows
+
+Fra denne workspace:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\sync-windows-deploy.ps1
+```
+
+### Linux target-host
+
+```bash
+cd ~/TuxDMXWebUI
+sudo bash ./scripts/update-linux.sh --non-interactive --force
+sudo systemctl restart tuxdmx.service
+```
+
+Kontrol:
+
+```bash
+systemctl status tuxdmx.service --no-pager
+curl http://127.0.0.1:8000/api/v1/health
+```
+
+## Fejlfinding kort
+
+### Home Assistant forbinder men reagerer ikke
+
+Kontroller:
+
+- korrekt `entity_id`
+- korrekt `fixturetype`
+- at HA-mapping ligger paa det forventede universe
+- at service-routing passer til entity-domænet
+
+### DMX virker ikke fysisk
+
+Kontroller:
+
+- `Backend = OLA / USB-DMX`
+- korrekt OLA-port
+- korrekt universe
+- at `olad` koerer
+
+### Audio/BPM reagerer ikke
+
+Kontroller:
+
+- valgt ALSA-input
+- at device ikke er optaget
+- at der er signal paa input
+
+## Bilag
+
+- [SCREENSHOTS.md](./SCREENSHOTS.md)
+- [API-ENDPOINTS.md](../API-ENDPOINTS.md)
+- [BPM.md](../BPM.md)
+- [MIXITUP.md](../MIXITUP.md)
+- [OFL.md](../OFL.md)
+- [IMPLEMENTATION-STATUS.md](../IMPLEMENTATION-STATUS.md)
+- [HARDWARE-VALIDATION.md](../HARDWARE-VALIDATION.md)
@@ -0,0 +1,25 @@
+# TuxDMX Systemmanual
+
+Denne mappe samler en enkel manuel dokumentationspakke til TuxDMX WebUI.
+
+Indhold:
+
+- `MANUAL.md`
+  Samlet brugermanual med opsaetning, daglig brug, Home Assistant-flow og service/update.
+- `SCREENSHOTS.md`
+  Oversigt over alle genererede screenshots med korte forklaringer.
+- `screenshots/`
+  PNG-screenshots af hele WebUI'et side for side.
+
+Vigtigt:
+
+- Screenshots i denne mappe er genereret den 23. juli 2026 fra den lokale WebUI i `mock=1` mode.
+- De viser den aktuelle UI-struktur og sideopbygning.
+- De er ikke dokumentation for fysisk Raspberry Pi-, OLA-, USB-DMX- eller lys-hardwaretest.
+- Hardwareafgraensninger og manuel hardwarevalidering hoerer stadig hjemme i [HARDWARE-VALIDATION.md](../HARDWARE-VALIDATION.md).
+
+Anbefalet laeseraekkefoelge:
+
+1. `MANUAL.md`
+2. `SCREENSHOTS.md`
+3. de enkelte filer i `screenshots/`
@@ -0,0 +1,68 @@
+# Screenshots
+
+Dette er et samlet screenshotsaet af TuxDMX WebUI genereret den 23. juli 2026.
+
+Kilde:
+
+- lokal UI-visning i `mock=1`
+- capture fra browser via lokal preview-server
+
+Formaal:
+
+- vise sideopbygning
+- understoette manualen
+- give et hurtigt visuelt overblik over systemet
+
+## Oversigt
+
+### Dashboard
+
+![Dashboard](./screenshots/dashboard.png)
+
+### Live Desk
+
+![Live Desk](./screenshots/live-desk.png)
+
+### Fixtures
+
+![Fixtures](./screenshots/fixtures.png)
+
+### Patch
+
+![Patch](./screenshots/patch.png)
+
+### Placering
+
+![Placering](./screenshots/placement.png)
+
+### Scener
+
+![Scener](./screenshots/scenes.png)
+
+### Effekter
+
+![Effekter](./screenshots/effects.png)
+
+### BPM
+
+![BPM](./screenshots/bpm.png)
+
+### MixItUp
+
+![MixItUp](./screenshots/mixitup.png)
+
+### DMX monitor
+
+![DMX monitor](./screenshots/dmx-monitor.png)
+
+### Telemetry
+
+![Telemetry](./screenshots/telemetry.png)
+
+### Backup
+
+![Backup](./screenshots/backup.png)
+
+### Settings
+
+![Settings](./screenshots/settings.png)