TuxDMX-WebUI/docs/system-manual/MANUAL.md

# TuxDMX Manual

## Formå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.

Formå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)