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 25. juli 2026.
• De afspejler UI og flows, men er ikke bevis for fysisk hardwareafvikling.
• Fysisk hardwaretest skal stadig vurderes separat paa target-maskinen.

Navigation

WebUI bruger nu en kompakt sidebar med grupperede undermenuer:

• Overblik Dashboard og Live Desk
• Live-kontrol Scener, Effekter og BPM
• Lysopsaetning Fixtures, DMX Patch og Placering
• Integrationer MixItUp og MIDI
• Overvaagning DMX monitor og Telemetry
• System Backup og Indstillinger

Kun den aktive sektion staar aaben ad gangen, saa UI ikke fylder unodigt meget i venstre side.

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.

MIDI

MIDI samler den separate MIDI-bridge og dens mappings.

Herfra kan du:

• se aktive bridges
• oprette og tilbagekalde bridge-tokens
• bruge MIDI Learn
• mappe knapper og faders til scener, effekter, blackout og master

MIDI sender ikke DMX direkte. Den kalder backendens eksisterende scene-, effekt- og systemhandlinger.

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 -ExecutionPolicy Bypass -File .\scripts\sync-windows-deploy.ps1

Hvis du vil pushe dokumentation, screenshots og kode videre til TuxiNet Git:

powershell -ExecutionPolicy Bypass -File .\scripts\push-git-tuxinet.ps1 -InitIfNeeded -SetOrigin -StageAll -Commit -CommitMessage "Update docs and screenshots" -Push

Linux target-host

cd ~/TuxDMXWebUI
sudo bash ./scripts/update-linux.sh --non-interactive --force
sudo systemctl restart tuxdmx.service

Kontrol:

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
• API-ENDPOINTS.md
• BPM.md
• MIXITUP.md
• OFL.md
• IMPLEMENTATION-STATUS.md
• HARDWARE-VALIDATION.md