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](HARDWARE-VALIDATION.md).

## Hurtig simulatorstart

### Backend

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

Windows PowerShell:

```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

```bash
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](ARCHITECTURE.md)
- [INSTALL-LINUX.md](INSTALL-LINUX.md)
- [INSTALL-PI.md](INSTALL-PI.md)
- [HARDWARE-VALIDATION.md](HARDWARE-VALIDATION.md)
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
- [SECURITY.md](SECURITY.md)
- [docs/API-ENDPOINTS.md](docs/API-ENDPOINTS.md)
- [docs/MIXITUP.md](docs/MIXITUP.md)
- [docs/OFL.md](docs/OFL.md)
- [docs/BPM.md](docs/BPM.md)
- [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md)
- [docs/IMPLEMENTATION-STATUS.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
powershell -ExecutionPolicy Bypass -File .\scripts\sync-windows-deploy.ps1
```

Alternativt:

```cmd
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
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>`.

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