TuxDMX-WebUI/README.md

TuxDMX

All rights reserved - Thomas / TuxiNet

TuxDMX er en headless, browserbaseret DMX-controller med FastAPI-backend, React dark UI, simulator-first udvikling og hardwareabstraktion mod OLA/USB-DMX.

Status

• Simulator mode kan startes lokalt og bruges til backend-, UI- og API-verifikation uden fysisk hardware.
• Primær target-platform er fysisk Debian 13 amd64.
• USB-DMX og OLA-output er verificeret af systemejeren på target-hosten.
• Codex påstår ikke, at den fysiske hardware er målt eller testet direkte i denne workspace-session.
• Resten af den manuelle hardwarevalidering og regressionstest er samlet i HARDWARE-VALIDATION.md.

Hurtig simulatorstart

Backend

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.lock
python -m uvicorn app.main:app --app-dir backend --reload

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.lock
python -m uvicorn app.main:app --app-dir backend --reload

Frontend

pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm dev

Standard-URL'er

• Web UI: http://127.0.0.1:8000/ når backend serverer frontend/dist
• API health: http://127.0.0.1:8000/api/v1/health
• Live WebSocket: ws://127.0.0.1:8000/ws/live

Verifikation

• Backend-tests: pytest
• Frontend-tests: pnpm test
• Frontend linting: pnpm lint
• TypeScript typecheck: pnpm typecheck
• Frontend production build: pnpm build
• Python lint/typecheck: ruff check backend og mypy backend/app

Dokumentation

• ARCHITECTURE.md
• INSTALL-LINUX.md
• INSTALL-PI.md
• HARDWARE-VALIDATION.md
• TROUBLESHOOTING.md
• SECURITY.md
• docs/system-manual/README.md
• docs/system-manual/MANUAL.md
• docs/API-ENDPOINTS.md
• docs/MIXITUP.md
• docs/OFL.md
• docs/BPM.md
• docs/MIDI_BRIDGE.md
• docs/DEPENDENCIES.md
• docs/IMPLEMENTATION-STATUS.md

Repositoryoversigt

• backend/: FastAPI, simulator, DMX-engine, auth, fixtures, BPM, triggers, backups og tests.
• frontend/: React dark UI, sidekomponenter og frontend-tests.
• scripts/: Linux/Pi-installation, update, uninstall, smoke-test og diagnostics.
• systemd/: systemd-unit og environment-eksempel til Linux-drift.
• test-data/fixtures/: små lovlige fixtures til simulator- og OFL-tests.

Produktion på Linux

• Debian 13 amd64: sudo ./scripts/install-linux.sh, sudo ./scripts/update-linux.sh og sudo ./scripts/uninstall-linux.sh
• Raspberry Pi / ARM: sudo ./scripts/install-pi.sh og sudo ./scripts/update-pi.sh

Windows sync til Linux-share

Hvis du arbejder i Windows og vil kopiere den deploy-klare kode til et mounted share som Q:\home\thomas\TuxDMXWebUI, kan du bruge:

powershell -ExecutionPolicy Bypass -File .\scripts\sync-windows-deploy.ps1

Alternativt:

scripts\sync-windows-deploy.cmd

Scriptet kopierer projektet uden data, node_modules, .venv, cache-mapper, __pycache__ og git-metadata. Det sletter ikke noget paa destinationen. Brug -DryRun for at se, hvad der vil blive kopieret, eller -DestinationRoot <sti> for at pege paa en anden mappe.

Hvis sharet ikke tillader overwrite af enkelte filer, kan du bygge en lokal update-pakke i stedet:

powershell -ExecutionPolicy Bypass -File .\scripts\sync-windows-deploy.ps1 -PackageOnly

Standard-stien for pakken er Desktop\TuxDMXWebUI-update, og den kan aendres med -StageRoot <sti>.

Dokumentation og screenshots

• Den opdaterede systemmanual ligger i docs/system-manual/.
• Screenshot-saettet er regenereret den 25. juli 2026 fra lokal mock=1 preview og matcher den nuvaerende kompakte navigation med grupperede menuer.
• Saettet indeholder ogsaa MIDI-siden, saa hele den aktuelle WebUI er dækket.

Git upload via PowerShell

Hvis du vil stage, committe og pushe direkte til TuxiNet Git fra PowerShell, kan du bruge helper-scriptet:

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

Standard-remote er:

https://git.tuxinet.dk/thomas/TuxDMX-WebUI.git

Hvis du kun vil se status og remote uden at pushe endnu:

powershell -ExecutionPolicy Bypass -File .\scripts\push-git-tuxinet.ps1 -SetOrigin

Produktionsnoter

• Debian 13 amd64 er nu førsteborger-platform for Linux-installation.
• Den nuværende produktionsmaskine er en fysisk Debian 13 amd64-host.
• Frontend-tooling er fastlaast til Node 20 og pnpm 10.28.2 via packageManager og engines.
• OLA og OLA Python-binding forventes fra Debian-pakker, og virtualenv oprettes med --system-site-packages.
• Permanente data ligger under /var/lib/tuxdmx, logs under /var/log/tuxdmx og environment i /etc/tuxdmx/tuxdmx.env.

Home Assistant live-test

Denne sektion beskriver en konkret live-testopsætning for parallel drift med fysisk USB-DMX og Home Assistant. Den er en testopskrift og ikke en påstand om, at den er udført direkte fra denne Codex-workspace-session.

Mål

• Universe 1: fysisk OLA-output til USB-DMX og almindelige DMX-lamper
• Universe 10: internt HA-universe til Home Assistant-bro

Testsetup

1. Sæt DMX-backend til OLA / USB-DMX, Universe 1 og korrekt OLA-port i Settings.
2. Under Home Assistant-bro:
   • sæt Base URL
   • indsæt long-lived token
   • sæt Standard HA-universe til 10
   • tryk Test forbindelse
3. Tryk Hent HA-enheder og vælg de relevante entiteter.

Konkrete mappings

• RGB med master:

  • Universe 10
  • Startadresse 1
  • Fixturetype rgb
  • Entity light.bar_rgb
  • Master dimmer = ja
  • Kanalbrug:
    • 1 = master
    • 2 = rød
    • 3 = grøn
    • 4 = blå

• Dimmer:

  • Universe 10
  • Startadresse 5
  • Fixturetype dimmer
  • Entity light.bar_dimmer

• Scene-trigger:

  • Universe 10
  • Startadresse 6
  • Fixturetype scene
  • Entity scene.party_mode

Forventet adfærd

• DMX på Universe 1 går fortsat ud via OLA og USB-DMX uden afhængighed af Home Assistant.
• HA-mappings på Universe 10 oversætter kun de valgte kanaler til HA-kald.
• Scene og automation trigges kun på rising edge.
• Switch bruger hysterese og må ikke flappe omkring midtpunktet.
• Ved langsomt eller utilgængeligt HA droppes gamle pending opdateringer, så kun nyeste ønskede værdi sendes videre.
• Fade sendes som HA transition frem for mange mellemtrin.