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,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)