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,173 @@
+# 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.