commit d6cda77aaf78015f6f71ce002c58f4e0b1bef94e Author: thomas Date: Thu Jul 23 21:24:48 2026 +0200 Add documentation, manual and screenshots preview diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..c9e935e --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,75 @@ +# TuxDMX arkitektur + +All rights reserved - Thomas / TuxiNet + +## Mål + +TuxDMX er bygget som en browserstyret lyscontroller med ærlig telemetri, simulator-first udvikling og hardwareisolering bag adapterinterfaces. Release 1.0 prioriterer stabil drift på fysisk Debian 13 amd64, testbarhed uden fysisk hardware og et mørkt UI, der kan bruges uden kode. + +## Konkrete valg + +- Backend: FastAPI, Pydantic, SQLAlchemy 2, Alembic og SQLite i WAL mode. +- Frontend: React, TypeScript, Vite og et bevidst dark-only design med semantiske CSS-variabler. +- DMX-engine: Et isoleret frame-loop i en asynkron baggrundsopgave. HTTP kalder aldrig DMX-backenden synkront. +- Hardware: `DmxBackend` som interface med `SimulatorDmxBackend` og `OlaDmxBackend`. `FakeOlaAdapter` bruges i tests. +- Fixtures: OFL importeres via klient, normaliseres til et stabilt internt format og gemmes både som rå kilde og normaliseret model. +- Sikkerhed: Lokale brugere, Argon2, sessionscookies, CSRF-token, API-tokens, auditlog og tydelig rolleopdeling. +- Drift: systemd-units, Linux-installationsscripts, backup/restore, diagnostics bundle og smoke-test. + +## Procesmodel + +Release 1.0 kører som én Python-applikation med tre logiske dele: + +1. FastAPI API og WebSocket-lag. +2. DMX-engine med simulator/OLA-adapter. +3. BPM-, trigger- og telemetritjenester. + +Det reducerer kompleksitet i første release, men modulerne er isoleret, så engine senere kan flyttes til separat proces via lokal IPC uden at bryde API'et. + +## Domænemoduler + +- `app.auth`: brugere, sessions og tokens. +- `app.core`: konfiguration, database, logging og lifecycle. +- `app.dmx`: frame model, merge-regler, simulator og OLA-adapter. +- `app.fixtures`: OFL-klient, normalisering og import. +- `app.scenes`: scene- og layerservice. +- `app.effects`: built-in effekter, sikkerhedsregler og runtime-stack. +- `app.bpm`: manual/tap/audio-abstraktion og beatbus. +- `app.mixitup`: mappings, kø, cooldowns og idempotency. +- `app.telemetry`: systemstatus, hændelser og historik. +- `app.websocket`: live snapshots og reconnect-venlige payloads. + +## Frame og merge + +- Et universe er 512 kanaler med værdier `0..255`. +- HTP bruges til intensitetskanaler og andre udtrykkeligt HTP-markerede kanaler. +- LTP bruges til bevægelse, farve, wheels og fallback-kanaler uden kendt HTP-behov. +- Blackout har absolut prioritet og nulstiller output uden at slette underliggende scene/effect-state. +- Freeze stopper opdateringer til target frame, men bevarer seneste output. + +## Telemetri + +Telemetri skelner eksplicit mellem: + +- beregnet frame, +- frame afleveret til backend, +- og fysisk verifikation. + +Release 1.0 leverer kun software- og backendniveau. Dokumentation og UI siger tydeligt, at fysisk signal ikke er verificeret uden ekstern måling eller understøttet RX/RDM. + +## Simulator-first + +Simulatoren er førsteklasses backend: + +- samme frame-interface som OLA, +- fejlindsprøjtning, +- framehistorik, +- heatmap-venlig output, +- assertions i automatiske tests, +- og visuel brug i UI. + +## Uafklarede, men forberedte områder + +- Flere universer ligger i datamodel og API, men UI fokuserer på universe 1. +- Audio-BPM bruger en adapterstruktur, så lokale Linux-audioinputs kan bruges i drift, mens tests benytter syntetiske click tracks. +- Art-Net, sACN, MIDI Clock og OSC er ikke aktive i 1.0, men backendinterfacet er forberedt til dem. diff --git a/HARDWARE-VALIDATION.md b/HARDWARE-VALIDATION.md new file mode 100644 index 0000000..5345185 --- /dev/null +++ b/HARDWARE-VALIDATION.md @@ -0,0 +1,103 @@ +# Hardware Validation + +All rights reserved - Thomas / TuxiNet + +Target-platformen er en fysisk Debian 13 amd64-maskine. USB-DMX og OLA-output er allerede verificeret af systemejeren på den nuværende host. Codex har ikke selv udført fysisk hardwaretest eller ekstern signalmåling i denne workspace-session. Brug denne checkliste til gentest, ændringsvalidering og installationer på andre hosts. + +## 1. Kør diagnostics + +- Kommando: `scripts/collect-diagnostics.sh` +- Forventet resultat: bundle oprettes uden secrets. +- Fejlsøgning: kontroller skrivbar `data/diagnostics` og læserettigheder til logs. + +## 2. Kontrollér OLA + +- Kommando: `systemctl status olad` +- Forventet resultat: `active (running)`. +- Fejlsøgning: verificér OLA-pakke og pluginvalg. + +## 3. Tilslut USB-DMX + +- Forventet resultat: device ses i `lsusb` og i TuxDMX DMX-status. +- Fejlsøgning: kontroller kabel, strøm og pluginunderstøttelse. + +## 4. Identificér device + +- Forventet resultat: vendor/product ID eller device path vises. +- Fejlsøgning: kontrollér rettigheder til `/dev/ttyUSB*`. + +## 5. Patch port + +- Handling: vælg universe 1 og korrekt OLA-port i UI. +- Forventet resultat: binding gemmes uden fejl. +- Fejlsøgning: genstart `olad`, opdater device scan. + +## 6. Tilslut én simpel lampe + +- Forventet resultat: lampen er alene på DMX-linjen under første test. +- Fejlsøgning: kontrol af terminering og kabling. + +## 7. Sæt lampens DMX address + +- Forventet resultat: lampen matcher patchstartadresse. +- Fejlsøgning: verificér personligheds/mode-kanalantal. + +## 8. Test dimmer + +- Handling: brug kanaltest 20 % og 100 %. +- Forventet resultat: lampen følger niveauerne og nulstilles efter timer. +- Fejlsøgning: kontroller dimmerkanal i korrekt mode. + +## 9. Test RGB + +- Handling: aktivér en simpel farvescene. +- Forventet resultat: farver matcher sceneværdier. +- Fejlsøgning: tjek kanalrækkefølge og fixturemode. + +## 10. Test blackout + +- Handling: aktivér blackout. +- Forventet resultat: output går til nul straks. +- Fejlsøgning: kontroller prioritetslag og master-limit. + +## 11. Test reconnect + +- Handling: træk USB-DMX ud og tilslut igen. +- Forventet resultat: UI går til degraded mode og reconnecter uden tilfældig flash. +- Fejlsøgning: kontroller OLA-device refresh og log for reconnect count. + +## 12. Test scene + +- Handling: aktivér base-scene og en overlay-scene. +- Forventet resultat: merge og return-to-base virker. +- Fejlsøgning: tjek HTP/LTP-precedence og prioritet. + +## 13. Test MixItUp + +- Handling: send testtrigger via Web Request Action. +- Forventet resultat: HTTP 202 og effekt i kø/log. +- Fejlsøgning: verificér token, header og rate limits. + +## 14. Test BPM + +- Handling: tilslut lydinput eller syntetisk click track. +- Forventet resultat: BPM, confidence og beatindikator opdateres. +- Fejlsøgning: kontroller devicevalg, inputkanal og audioadapter. + +## 15. Test reboot/autostart + +- Handling: genstart værtsmaskinen. +- Forventet resultat: OLA og TuxDMX starter automatisk, safe scene aktiveres. +- Fejlsøgning: inspicér systemd-status og journald. + +## 16. Kør 2 timers soak test + +- Handling: hold UI åbent med scener, BPM og triggers aktive. +- Forventet resultat: ingen memory leak, ingen ukontrollerede dropped frames. +- Fejlsøgning: brug telemetri, temperatur og diagnostics bundle. + +## 17. Gem diagnostic bundle + +- Handling: kør diagnostics igen efter testen. +- Forventet resultat: komplet bundle vedlagt til videre fejlsøgning. +- Fejlsøgning: redigeringsfejl i config eller manglende læserettigheder. diff --git a/INSTALL-LINUX.md b/INSTALL-LINUX.md new file mode 100644 index 0000000..0829fed --- /dev/null +++ b/INSTALL-LINUX.md @@ -0,0 +1,159 @@ +# Installation på Debian 13 amd64 + +All rights reserved - Thomas / TuxiNet + +## Platform + +- Debian 13 amd64 +- `systemd` +- OLA / `olad` +- Node.js 20 +- `pnpm` 10.28.2 +- Standardport for TuxDMX: `8000/tcp` + +## 1. Forbered serveren + +```bash +sudo apt-get update +sudo apt-get install -y git curl +git clone tuxdmx +cd tuxdmx +``` + +Hvis du deployer fra et ZIP-arkiv, saa udpak arkivet og skift til den mappe, foer du fortsaetter. + +## 2. Kildeplacering + +- Installeren finder repositoryet ud fra scriptets egen placering. +- Det virker baade ved Git-clone og ved SFTP-kopieret projektmappe. +- `sudo` maa ikke flytte source root til `/root`, fordi scriptet ikke bruger `$HOME` som kilde. + +## 3. Installer TuxDMX + +Interaktiv installation: + +```bash +sudo ./scripts/install-linux.sh +``` + +Ikke-interaktiv installation: + +```bash +sudo ./scripts/install-linux.sh --non-interactive --force +``` + +Hvis du allerede har en gyldig `frontend/dist`, kan du eksplicit springe frontend-build over: + +```bash +sudo ./scripts/install-linux.sh --non-interactive --force --skip-frontend-build +``` + +Dette flag virker kun, hvis `frontend/dist/index.html` allerede findes. + +Scriptet: + +- validerer Debian 13 amd64, +- installerer Python 3, `python3-venv`, SQLite, OLA, OLA Python-binding, Node.js 20-værktøjskæde og `olad`, +- laaser frontend-tooling til `pnpm` 10.28.2, +- bygger frontenden selv med `pnpm install --frozen-lockfile` og `pnpm build`, +- opretter systembrugeren `tuxdmx`, +- opretter `/opt/tuxdmx`, `/var/lib/tuxdmx`, `/var/log/tuxdmx` og `/etc/tuxdmx`, +- bruger staging i `/opt/tuxdmx.new`, +- normaliserer filrettigheder efter kopiering, ogsaa efter SFTP-upload, +- opretter virtualenv med `--system-site-packages`, +- installerer `requirements.lock`, koerer `pip check` og kontrollerer `greenlet`, `sqlalchemy` og `ola`, +- koerer alle Alembic migrations som brugeren `tuxdmx`, +- installerer og aktiverer `tuxdmx.service`, +- health-checker `http://127.0.0.1:8000/api/v1/health`, +- viser automatisk `systemctl status` og `journalctl`, hvis service-start fejler. + +Eksisterende database og konfiguration bevares, fordi de ligger i `/var/lib/tuxdmx` og `/etc/tuxdmx`. + +## 4. Permanente stier + +- Appkode: `/opt/tuxdmx` +- Frontend build: `/opt/tuxdmx/frontend/dist` +- Database og runtime-data: `/var/lib/tuxdmx` +- Backups: `/var/lib/tuxdmx/backups` +- Diagnostics: `/var/lib/tuxdmx/diagnostics` +- Uploads: `/var/lib/tuxdmx/uploads` +- Fixture-cache: `/var/lib/tuxdmx/fixtures` +- Logs: `/var/log/tuxdmx` +- Environment: `/etc/tuxdmx/tuxdmx.env` + +## 5. Kontroller drift + +```bash +systemctl status tuxdmx.service +systemctl status olad +curl -fsS http://127.0.0.1:8000/api/v1/health +curl -fsS http://127.0.0.1:8000/ +``` + +Web UI: + +```text +http://:8000/ +``` + +## 6. Update + +```bash +sudo ./scripts/update-linux.sh +``` + +Med eksisterende `frontend/dist`: + +```bash +sudo ./scripts/update-linux.sh --skip-frontend-build +``` + +Update-scriptet: + +- tager backup af app, data og konfiguration, +- bygger ny frontend eller genbruger eksisterende `dist`, +- kopierer ny kode og `frontend/dist`, +- geninstallerer Python-afhaengigheder, +- koerer migrationer, +- geninstallerer `tuxdmx.service`, +- genstarter `olad` og `tuxdmx.service`, +- ruller tilbage ved fejl. + +## 7. Uninstall + +```bash +sudo ./scripts/uninstall-linux.sh +sudo ./scripts/uninstall-linux.sh --purge-app +sudo ./scripts/uninstall-linux.sh --purge-app --purge-data +``` + +## 8. Logs og health checks + +```bash +journalctl -u tuxdmx.service -f +journalctl -u olad -f +systemctl status tuxdmx.service --no-pager --full +curl -fsS http://127.0.0.1:8000/api/v1/health +``` + +- Health fejler: `journalctl -u tuxdmx.service -n 200 --no-pager` +- OLA-binding mangler: kontroller at `python3-ola` eller `ola-python` findes i Debian-repositoriet +- OLA-runtime fejler: `journalctl -u olad -n 200` +- DB-fejl: `sqlite3 /var/lib/tuxdmx/tuxdmx.db "PRAGMA integrity_check;"` +- Frontend-build fejler: kontroller `node --version`, `pnpm --version` og `package.json` packageManager-feltet +- Importfejl `No module named 'app'`: kontrollér at `/opt/tuxdmx/backend/app/main.py` findes +- Permission-fejl efter SFTP: installeren normaliserer rettigheder til `root:tuxdmx`, 0755 paa mapper og 0644 paa kode/dist-filer + +## 9. Root causes rettet i denne leverance + +- `greenlet` manglede i Python-lockfile, selv om SQLAlchemy async-laget kraever det +- frontend-build var manuel i stedet for en del af installeren +- pnpm-version var ikke fastlaast og kunne glide til en inkompatibel udgave +- backend-layoutet i `/opt/tuxdmx` blev ikke verificeret eksplicit +- relative runtime-stier gav `PermissionError` og uforudsigelig working directory-adfaerd +- SFTP-overfoerte rettigheder blev kopieret ukritisk +- systemd health-check viste ikke automatisk de egentlige servicefejl + +## 10. Hardwarestatus + +Installationsscriptet er lavet til Debian 13 amd64. USB-DMX og OLA-output er verificeret af systemejeren på den fysiske target-host, men Codex har ikke selv udført fysisk hardwaretest i denne workspace-session. Brug [HARDWARE-VALIDATION.md](HARDWARE-VALIDATION.md) til gentest, ændringsvalidering og nye installationer. diff --git a/INSTALL-PI.md b/INSTALL-PI.md new file mode 100644 index 0000000..5dfab9c --- /dev/null +++ b/INSTALL-PI.md @@ -0,0 +1,142 @@ +# Installation på Raspberry Pi + +All rights reserved - Thomas / TuxiNet + +Debian 13 amd64 bruger nu [INSTALL-LINUX.md](INSTALL-LINUX.md) samt `scripts/install-linux.sh` og `scripts/update-linux.sh`. + +## Platform + +- Raspberry Pi 4 eller 5 +- Raspberry Pi OS Lite 64-bit +- OLA/`olad` +- Valgfrit USB audio input til BPM +- Standardport for TuxDMX: `8000/tcp` + +## 1. Forbered Pi + +```bash +sudo apt-get update +sudo apt-get install -y git curl +git clone tuxdmx +cd tuxdmx +``` + +Hvis du deployer fra et ZIP-arkiv i stedet for Git, så udpak til en mappe og skift til den mappe før næste trin. + +## 2. Byg frontend før Pi-installation + +Kør dette på buildmaskinen eller direkte på Pi, før `install-pi.sh`: + +```bash +pnpm install +pnpm build +``` + +Installationsscriptet kræver, at `frontend/dist/index.html` findes. + +## 3. Installer TuxDMX + +Interaktiv installation: + +```bash +sudo ./scripts/install-pi.sh +``` + +Ikke-interaktiv installation: + +```bash +sudo ./scripts/install-pi.sh --non-interactive --force +``` + +Scriptet: + +- installerer systempakker, +- opretter systembrugeren `tuxdmx`, +- opretter `/opt/tuxdmx`, `/var/lib/tuxdmx`, `/var/log/tuxdmx` og `/etc/tuxdmx`, +- genererer `/etc/tuxdmx/tuxdmx.env`, +- installerer Python-afhængigheder, +- kører Alembic migration, +- installerer og starter `tuxdmx.service`. + +## 4. Kontroller service og URL + +```bash +systemctl status tuxdmx.service +systemctl status olad +curl -fsS http://127.0.0.1:8000/api/v1/health +``` + +Web UI: + +```text +http://:8000/ +``` + +## 5. Førstegangsopsætning + +1. Åbn Web UI. +2. Opret administrator. +3. Kontroller systemstatus og OLA-status. +4. Vælg universe 1 og korrekt OLA-port. +5. Sæt master-limit, blackout-adfærd og strobegrænser. +6. Generér MixItUp-token ved behov. +7. Gem safe scene. + +## 6. Logs og drift + +Følg applikationslog: + +```bash +journalctl -u tuxdmx.service -f +``` + +Se OLA-log: + +```bash +journalctl -u olad -f +``` + +Genstart TuxDMX: + +```bash +sudo systemctl restart tuxdmx.service +``` + +## 7. Update + +```bash +sudo ./scripts/update-pi.sh +``` + +Update-scriptet tager backup, kopierer ny version, installerer requirements, koerer migration og health check. Ved fejl rulles app-, data- og konfigurationstilstand tilbage. + +## 8. Uninstall + +Fjern kun service: + +```bash +sudo ./scripts/uninstall-pi.sh +``` + +Fjern service og app: + +```bash +sudo ./scripts/uninstall-pi.sh --purge-app +``` + +Fjern service, app og data: + +```bash +sudo ./scripts/uninstall-pi.sh --purge-app --purge-data +``` + +## 9. Fejlsøgning + +- Health fejler: se `journalctl -u tuxdmx.service -n 200` +- OLA utilgængelig: se `journalctl -u olad -n 200` +- USB-DMX ikke fundet: brug `lsusb`, `dmesg | grep -i usb` og [HARDWARE-VALIDATION.md](HARDWARE-VALIDATION.md) +- Databasefejl: kontrollér `/var/lib/tuxdmx/tuxdmx.db` og `sqlite3 /var/lib/tuxdmx/tuxdmx.db "PRAGMA integrity_check;"` + +## 10. Ikke fysisk testet af Codex + +Denne repository leverer scripts og dokumentation til Pi, men ingen fysisk Raspberry Pi-, OLA- eller USB-DMX-hardware er testet i denne desktop-session. Brug altid [HARDWARE-VALIDATION.md](HARDWARE-VALIDATION.md) efter installation. diff --git a/README.md b/README.md new file mode 100644 index 0000000..50f6c4f --- /dev/null +++ b/README.md @@ -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 ` 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 `. + +## 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. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..559bedf --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,36 @@ +# Security + +All rights reserved - Thomas / TuxiNet + +## LAN deployment + +- Drift antages som udgangspunkt på isoleret LAN eller bag reverse proxy. +- Eksponér ikke adminadgang uden netværkskontrol og HTTPS. + +## Credentials + +- Ingen standard adminpassword. +- Brug Argon2 til passwordhash. +- Sessions og API-tokens skal kunne roteres og tilbagekaldes. + +## Reverse proxy og HTTPS + +- Reverse proxy er anbefalet ved adgang uden for lokalt netværk. +- Brug TLS-terminering, IP-filtrering og stærke cookies i produktion. + +## Secrets + +- Commit aldrig secrets. +- Brug `.env` eller systemd environment-fil på Pi. +- Diagnostics bundle må ikke indeholde rå tokens eller passwordhashes. + +## Backup + +- Krypter backup uden for enheden, hvis den forlader lokal drift. +- Restore kræver administratorvalidering. + +## Reporting + +- Brug auditlog og diagnostics bundle til hændelsesanalyse. +- Fysisk DMX-verifikation er separat fra softwaretelemetri. + diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md new file mode 100644 index 0000000..5bbfdf5 --- /dev/null +++ b/THIRD_PARTY_NOTICES.md @@ -0,0 +1,12 @@ +# Third Party Notices + +All rights reserved - Thomas / TuxiNet + +Dette projekt bruger eller er designet til at arbejde sammen med tredjepartskomponenter, herunder: + +- Python: FastAPI, Pydantic, SQLAlchemy, Alembic, Argon2, httpx, psutil, uvicorn. +- Frontend: React, Vite, TypeScript, ESLint, Vitest, Testing Library. +- Hardware/software integration: Open Lighting Architecture (OLA). +- Fixture metadata: Open Fixture Library (OFL). + +Repository indeholder kun små, reducerede testfixtures i `test-data/fixtures` skrevet særskilt til intern test. De er ikke kopier af tredjeparts kodebaser og er kun beregnet som lovlige testdata til normalisering og simulator. diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 0000000..a5969d2 --- /dev/null +++ b/TROUBLESHOOTING.md @@ -0,0 +1,74 @@ +# Troubleshooting + +All rights reserved - Thomas / TuxiNet + +## OLA kan ikke se USB + +- Bekræft `lsusb`, `systemctl status olad` og at korrekt OLA-plugin er aktivt. +- Genstart OLA før du genpatcher porten i UI. + +## Permission denied på `/dev/ttyUSB*` + +- Sørg for at `tuxdmx` er medlem af `dialout` og `plugdev`. +- Bekræft udev-rettigheder eller device-ejerskab. + +## Ingen DMX-output + +- Bekræft universe, port og fixtureaddress. +- Kontroller, at blackout ikke er aktiv. +- Se DMX monitor for current/target/source. + +## Flimren + +- Reducér frame rate til 25 eller 30 fps. +- Kontroller at ingen overliggende effekt skriver LTP/HTP utilsigtet. + +## Web UI virker ikke + +- Kontroller `tuxdmx.service`. +- Brug `/api/v1/health` og se browser-konsol for WebSocket-fejl. +- Kør `systemctl status tuxdmx.service --no-pager --full`. +- Kør `journalctl -u tuxdmx.service -n 200 --no-pager`. + +## Frontend-build eller pnpm fejler + +- Kontroller `node --version` og bekræft Node 20. +- Kontroller `pnpm --version` og bekræft `10.28.2`. +- Kontroller at `package.json` har `packageManager: pnpm@10.28.2`. +- Hvis build skal genbruges fra en CI-artefakt, brug `--skip-frontend-build` kun naar `frontend/dist/index.html` allerede findes. + +## No module named `app` + +- Kontroller at backend er landet som `/opt/tuxdmx/backend/app`. +- Kontroller `test -f /opt/tuxdmx/backend/app/main.py`. +- Kør importtesten som servicebrugeren: + `sudo -u tuxdmx /opt/tuxdmx/.venv/bin/python -c "import sys; sys.path.insert(0, '/opt/tuxdmx/backend'); import app.main"` + +## PermissionError på `frontend/dist` eller `data/backups` + +- Installeren normaliserer rettigheder til `root:tuxdmx` for appkode og `tuxdmx:tuxdmx` for runtime-data. +- Kontroller `sudo -u tuxdmx test -r /opt/tuxdmx/frontend/dist/index.html`. +- Kontroller `namei -l /opt/tuxdmx/frontend/dist/index.html`. + +## MixItUp timeout + +- Bekræft at endpointet returnerer `202 Accepted`. +- Kontroller rate limiting, token og netværksrute. + +## BPM finder forkert tempo + +- Justér BPM-range og half/double. +- Brug syntetiske click tracks for at isolere lydinputproblemer. + +## Databasefejl + +- Kontroller diskplads og SQLite WAL-filer. +- Kør backup før restore eller manuel reparation. +- Kontroller at `tuxdmx` kan skrive til `/var/lib/tuxdmx`. +- Kontroller `sqlite3 /var/lib/tuxdmx/tuxdmx.db "PRAGMA integrity_check;"`. + +## OLA kan ikke importeres i virtualenv + +- Virtualenv skal oprettes med `python3 -m venv --system-site-packages /opt/tuxdmx/.venv`. +- Kontroller: + `sudo -u tuxdmx /opt/tuxdmx/.venv/bin/python -c "import ola; print(ola.__file__)"` diff --git a/docs/API-ENDPOINTS.md b/docs/API-ENDPOINTS.md new file mode 100644 index 0000000..e78d41a --- /dev/null +++ b/docs/API-ENDPOINTS.md @@ -0,0 +1,65 @@ +# API endpoints + +Roller nedenfor er den tilsigtede adgangsrolle for Release 1.0. Den nuværende kodebase dokumenterer rollerne, men håndhæver dem endnu ikke konsekvent i runtime. + +| Metode | Sti | Rolle | Formål | +| --- | --- | --- | --- | +| `GET` | `/api/v1/health` | Read only | Health check til lokal drift og monitoring. | +| `GET` | `/api/v1/system/status` | Read only | Samlet systemstatus med engine, telemetri og BPM. | +| `GET` | `/api/v1/system/diagnostics` | Administrator | Udvidet diagnostik til support og bundle. | +| `POST` | `/api/v1/system/restart-service` | Administrator | Planlægger restart af TuxDMX-servicen på Linux-værten. | +| `GET` | `/api/v1/dmx/status` | Read only | DMX-engine status og backendforbindelse. | +| `GET` | `/api/v1/dmx/devices` | Operator | Liste over tilgængelige DMX-backends/devices. | +| `GET` | `/api/v1/dmx/universes` | Operator | Oversigt over univers-konfiguration. | +| `GET` | `/api/v1/dmx/frame` | Read only | Aktuelt DMX-frame og source-map. | +| `POST` | `/api/v1/dmx/test-channel` | Operator | Midlertidig kanaltest til setup/diagnostik. | +| `POST` | `/api/v1/dmx/blackout` | Operator | Aktiverer blackout med højeste prioritet. | +| `POST` | `/api/v1/dmx/release-blackout` | Operator | Frigiver blackout. | +| `GET` | `/api/v1/fixtures` | Operator | Lister lokalt importerede fixtures. | +| `POST` | `/api/v1/fixtures/search-ofl` | Operator | Søger fixtures via OFL eller lokal fallback. | +| `POST` | `/api/v1/fixtures/preview-ofl` | Operator | Henter preview og normaliseret modeoversigt før import. | +| `POST` | `/api/v1/fixtures/import-ofl` | Operator | Importerer fixture fra OFL til lokal cache/runtime. | +| `POST` | `/api/v1/fixtures/import-file` | Operator | Importerer fixture fra lokal/custom payload. | +| `POST` | `/api/v1/fixtures/custom` | Operator | Opretter custom fixture uden OFL. | +| `GET` | `/api/v1/fixtures/{id}` | Operator | Henter ét lokalt fixture. | +| `PUT` | `/api/v1/fixtures/{id}` | Operator | Opdaterer et lokalt fixture. | +| `DELETE` | `/api/v1/fixtures/{id}` | Administrator | Sletter et lokalt fixture. | +| `GET` | `/api/v1/patch` | Operator | Lister patch-entries. | +| `POST` | `/api/v1/patch` | Operator | Opretter patch-entry. | +| `PUT` | `/api/v1/patch/{id}` | Operator | Opdaterer patch-entry. | +| `DELETE` | `/api/v1/patch/{id}` | Operator | Sletter patch-entry. | +| `POST` | `/api/v1/patch/validate` | Operator | Validerer startadresse og kanalantal. | +| `GET` | `/api/v1/scenes` | Operator | Lister scener. | +| `POST` | `/api/v1/scenes` | Operator | Opretter scene. | +| `GET` | `/api/v1/scenes/{id}` | Operator | Henter scene. | +| `PUT` | `/api/v1/scenes/{id}` | Operator | Opdaterer scene. | +| `DELETE` | `/api/v1/scenes/{id}` | Operator | Sletter scene. | +| `POST` | `/api/v1/scenes/{slug}/activate` | Operator | Aktiverer scene på engine-stacken. | +| `POST` | `/api/v1/scenes/{slug}/release` | Operator | Frigiver scene-layer. | +| `GET` | `/api/v1/effects` | Operator | Lister effekter. | +| `POST` | `/api/v1/effects` | Operator | Opretter effekt. | +| `PUT` | `/api/v1/effects/{id}` | Operator | Opdaterer effekt. | +| `DELETE` | `/api/v1/effects/{id}` | Operator | Sletter effekt. | +| `POST` | `/api/v1/effects/{slug}/trigger` | Operator | Trigger effekt på engine-stacken. | +| `POST` | `/api/v1/effects/{slug}/stop` | Operator | Stopper aktiv effekt. | +| `GET` | `/api/v1/bpm/status` | Read only | Aktuel BPM-status, mode og confidence. | +| `POST` | `/api/v1/bpm/manual` | Operator | Sætter manuel BPM. | +| `POST` | `/api/v1/bpm/tap` | Operator | Registrerer tap-tempo. | +| `POST` | `/api/v1/bpm/audio/start` | Operator | Starter audioanalyse mod valgt ALSA- eller syntetisk inputdevice. | +| `POST` | `/api/v1/bpm/audio/stop` | Operator | Stopper audio-mode. | +| `POST` | `/api/v1/bpm/external` | Operator | Sætter BPM fra ekstern kilde/API. | +| `GET` | `/api/v1/bpm/devices` | Operator | Lister tilgængelige BPM-devices/kilder. | +| `GET` | `/api/v1/integrations/mixitup` | Administrator | Lister MixItUp-integrationer. | +| `POST` | `/api/v1/integrations/mixitup` | Administrator | Opretter MixItUp-integration. | +| `PUT` | `/api/v1/integrations/mixitup/{id}` | Administrator | Opdaterer MixItUp-integration. | +| `DELETE` | `/api/v1/integrations/mixitup/{id}` | Administrator | Sletter MixItUp-integration. | +| `POST` | `/api/v1/integrations/mixitup/{id}/test` | Administrator | Tester MixItUp-integration. | +| `POST` | `/api/v1/triggers/{slug}` | API token | Hurtigt triggerendpoint til MixItUp/Twitch. | +| `GET` | `/api/v1/telemetry/live` | Read only | Aktuel telemetri. | +| `GET` | `/api/v1/telemetry/history` | Read only | Historiske samples. | +| `GET` | `/api/v1/events` | Read only | Nylige systemevents. | +| `GET` | `/api/v1/logs` | Administrator | Hændelser/logfeed. | +| `POST` | `/api/v1/backups` | Administrator | Opretter ZIP-backup i simulator/runtime. | +| `GET` | `/api/v1/backups` | Administrator | Lister tilgængelige backups. | +| `POST` | `/api/v1/backups/{id}/restore` | Administrator | Gendanner backup og opretter pre-restore backup. | +| `DELETE` | `/api/v1/backups/{id}` | Administrator | Sletter backuparkiv. | diff --git a/docs/BPM.md b/docs/BPM.md new file mode 100644 index 0000000..2a6bbd0 --- /dev/null +++ b/docs/BPM.md @@ -0,0 +1,37 @@ +# BPM-kilder + +## Manual + +- Endpoint: `POST /api/v1/bpm/manual?bpm=` +- UI: knapper og direkte værdisætning +- Status: fuldt implementeret i simulator/runtime + +## Tap + +- Endpoint: `POST /api/v1/bpm/tap` +- UI: `Tap tempo` +- Algoritme: median af de seneste tap-intervaller inden for et kort vindue +- Status: implementeret og verificerbar lokalt + +## Audio input + +- Endpoints: + - `POST /api/v1/bpm/audio/start?device=` + - `POST /api/v1/bpm/audio/stop` + - `GET /api/v1/bpm/devices` +- Devices i denne leverance: + - `synthetic-click-track` + - `jack:auto` + - `alsa:default` +- Status: simuleret/delvist implementeret. API og UI findes, men ægte audioanalyse mod aubio/JACK/ALSA er ikke implementeret endnu i denne kodebase. + +## External + +- Endpoint: `POST /api/v1/bpm/external?bpm=` +- Status: implementeret som simpel ekstern BPM-injektion + +## Verifikation uden hardware + +- Manual og tap kan verificeres direkte i UI eller via API. +- Audio-mode kan verificeres som simulator-flow og device-API, men ikke som ægte beat detection uden videre implementation. + diff --git a/docs/DEPENDENCIES.md b/docs/DEPENDENCIES.md new file mode 100644 index 0000000..08aee76 --- /dev/null +++ b/docs/DEPENDENCIES.md @@ -0,0 +1,54 @@ +# Dependencies og licenser + +Denne oversigt dækker de deklarerede direkte afhængigheder i repositoryet samt de eksterne platformskomponenter, som systemet integrerer med. + +## Python + +| Pakke | Version | Licensfelt | Formål | +| --- | --- | --- | --- | +| `alembic` | `1.14.0` | `MIT` | Database migrations | +| `aiosqlite` | `0.20.0` | `ikke deklareret i metadata` | Async SQLite-driver | +| `argon2-cffi` | `23.1.0` | `ikke deklareret i metadata` | Password hashing | +| `fastapi` | `0.115.6` | `ikke deklareret i metadata` | REST API og WebSocket-app | +| `httpx` | `0.28.1` | `BSD-3-Clause` | OFL HTTP-klient | +| `pydantic` | `2.10.4` | `ikke deklareret i metadata` | Datavalidering | +| `pydantic-settings` | `2.7.0` | `MIT` | Settings fra env | +| `psutil` | `6.1.1` | `BSD-3-Clause` | Systemtelemetri | +| `python-multipart` | `0.0.20` | `ikke deklareret i metadata` | Multipart/form parsing | +| `sqlalchemy` | `2.0.36` | `MIT` | ORM og DB-lag | +| `uvicorn` | `0.34.0` | `BSD-3-Clause` | ASGI-server | +| `mypy` | `1.14.1` | `MIT` | Typecheck | +| `pytest` | `8.3.4` | `MIT` | Test | +| `pytest-asyncio` | `0.25.2` | `Apache 2.0` | Async tests | +| `pytest-cov` | `6.0.0` | `MIT` | Coverage/testhjælp | +| `ruff` | `0.8.6` | `MIT` | Linting | + +## Frontend / Node + +| Pakke | Version | Licens | Formål | +| --- | --- | --- | --- | +| `react` | `18.3.1` | `MIT` | UI runtime | +| `react-dom` | `18.3.1` | `MIT` | DOM rendering | +| `@testing-library/jest-dom` | `6.6.3` | `MIT` | DOM assertions | +| `@testing-library/react` | `16.1.0` | `MIT` | React UI-tests | +| `@eslint/js` | `9.18.0` | `MIT` | ESLint base config | +| `@types/react` | `18.3.18` | `MIT` | TypeScript typer | +| `@types/react-dom` | `18.3.5` | `MIT` | TypeScript typer | +| `@vitejs/plugin-react` | `4.3.4` | `MIT` | Vite React-plugin | +| `eslint` | `9.18.0` | `MIT` | Frontend linting | +| `eslint-plugin-react-hooks` | `5.1.0` | `MIT` | React Hook-regler | +| `eslint-plugin-react-refresh` | `0.4.16` | `MIT` | Vite/React refresh-regler | +| `globals` | `15.14.0` | `MIT` | Browser-globals til ESLint | +| `jsdom` | `25.0.1` | `MIT` | Browser-lignende testmiljø | +| `typescript` | `5.7.3` | `Apache-2.0` | TypeScript compiler | +| `typescript-eslint` | `8.20.0` | `MIT` | TypeScript-parser og regler til ESLint | +| `vite` | `6.0.7` | `MIT` | Frontend dev/build | +| `vitest` | `2.1.8` | `MIT` | Frontend tests | + +## Eksterne komponenter + +| Komponent | Licensstatus | Rolle | +| --- | --- | --- | +| OLA / `olad` | ekstern systempakke, se distributionens licensinfo | DMX-backend | +| Open Fixture Library | ekstern tjeneste/dataformat | Fixture-søgning og import | +| SQLite | ekstern runtimekomponent | Lokal database | diff --git a/docs/IMPLEMENTATION-STATUS.md b/docs/IMPLEMENTATION-STATUS.md new file mode 100644 index 0000000..119f4d5 --- /dev/null +++ b/docs/IMPLEMENTATION-STATUS.md @@ -0,0 +1,47 @@ +# Implementationsstatus + +## Fuldt implementeret og lokalt verificeret + +- FastAPI app-start og health endpoint +- Simulator-DMX-backend +- OLA-DMX-backend med rigtig `SendDmx`-integration via lokal OLA Python-klientadapter +- 512-kanals frame-model +- HTP/LTP merge og blackout-tests +- Backend-status med `connected`, `last_successful_frame`, `frames_sent`, `send_errors`, `reconnect_count`, universe og output-port +- Automatisk reconnect/degraded mode i OLA-backend samt mock OLA-adapter til tests +- Sceneoprettelse og sceneaktivering i runtime +- Effektoprettelse og trigger i runtime +- Manual BPM +- Tap BPM +- MixItUp triggerendpoint med `202 Accepted` +- WebSocket live-feed +- Frontend dark UI med dashboard, fixtures, live desk, scenes, effects, BPM, MixItUp, DMX monitor, telemetry, backup og settings +- Alembic migration fra tom database +- Backup/restore i simulator-mode via service og API +- Linux- og Pi-install/update/uninstall/diagnostics scripts som leverede artefakter +- Debian 13 amd64 install/update/uninstall-flow med staging, frontend-build, `pip check`, OLA-importcheck og systemd health diagnostics +- Patch med persisted grupper/link og fysisk placering +- Fixture-/gruppebaserede scener med persisted targets +- ALSA-baseret BPM-capture, device discovery og syntetiske audio-tests +- Placering/view over patched fixtures i Web UI + +## Delvist implementeret + +- OLA-integrationen er implementeret og testet automatisk mod mock adapter. USB-DMX og OLA-output er verificeret af systemejeren på fysisk Debian 13 amd64-host, men ikke fysisk målt af Codex i denne workspace-session +- Debian 13-installationsflowet er rettet og statisk/testmæssigt verificeret i repositoryet, men ikke end-to-end genkørt af Codex i en rigtig Debian VM i denne desktop-session +- Fixtureimport persistes i runtime, men ikke fuldt i relationel database +- MixItUp integrationer/mappings er dokumenteret, men ikke fuldt persisted eller rollebeskyttet +- Telemetry history er kun stubbet som tom historik +- Backup UI er funktionelt mod backup-endpoints, men uden download-knap + +## Simuleret + +- Hardwaretilstande som USB-frakobling og OLA-fejl via simulator/faults + +## Endnu ikke implementeret + +- Role enforcement og login/session-flow i hele API'et +- Chaser-timeline og den fulde effektliste fra specifikationen +- Avanceret patch-editor med flere universer og mere QLC+-agtig patch-oversigt +- Historisk telemetrilagring, pruning og aggregering +- Fuld scene/effect restore-stack med udløbstider og underliggende state-retur diff --git a/docs/MIXITUP.md b/docs/MIXITUP.md new file mode 100644 index 0000000..2993e67 --- /dev/null +++ b/docs/MIXITUP.md @@ -0,0 +1,104 @@ +# MixItUp integration + +## Triggerendpoint + +Primært endpoint: + +```http +POST /api/v1/triggers/{slug} +Authorization: Bearer +Content-Type: application/json +``` + +Eksempel med `raid`: + +```http +POST /api/v1/triggers/raid +Host: tuxdmx.local:8000 +Authorization: Bearer REPLACE_WITH_TOKEN +Content-Type: application/json +``` + +```json +{ + "eventType": "raid", + "username": "streamviewer42", + "displayName": "StreamViewer42", + "amount": 120, + "eventId": "raid-evt-20260712-001", + "platform": "twitch", + "metadata": { + "source": "mixitup", + "notes": "Raid test i simulator" + } +} +``` + +Forventet svar: + +```json +{ + "accepted": true, + "queue_depth": 1 +} +``` + +HTTP-status: + +```text +202 Accepted +``` + +## Simple endpoints + +- `POST /api/v1/scenes/{sceneSlug}/activate` +- `POST /api/v1/effects/{effectSlug}/trigger` +- `POST /api/v1/dmx/blackout` +- `POST /api/v1/bpm/tap` + +## Headers + +- `Authorization: Bearer ` +- `Content-Type: application/json` + +Token må aldrig sendes i querystring. + +## MixItUp Web Request Action + +1. Vælg `POST`. +2. Brug URL `http://:8000/api/v1/triggers/`. +3. Tilføj header `Authorization` med `Bearer `. +4. Tilføj header `Content-Type` med `application/json`. +5. Indsæt JSON-body. + +## Eksempel-body med MixItUp special identifiers + +```json +{ + "eventType": "raid", + "username": "$username", + "displayName": "$displayname", + "amount": "$raidviewercount", + "eventId": "$eventid", + "platform": "twitch", + "metadata": { + "eventName": "$eventname" + } +} +``` + +## Test i simulator-mode + +```bash +curl -i -X POST http://127.0.0.1:8000/api/v1/triggers/raid \ + -H "Authorization: Bearer test-token" \ + -H "Content-Type: application/json" \ + -d '{"eventType":"raid","displayName":"AuditTest","amount":42,"eventId":"raid-audit-1","platform":"twitch","metadata":{}}' +``` + +## Sikkerhed + +- Roter token ved mistanke om læk. +- Brug IP-allowlist eller reverse proxy, hvis endpointet eksponeres uden for isoleret LAN. +- Rate limiting og duplicate/idempotency skal håndhæves server-side. + diff --git a/docs/OFL.md b/docs/OFL.md new file mode 100644 index 0000000..496d702 --- /dev/null +++ b/docs/OFL.md @@ -0,0 +1,74 @@ +# Open Fixture Library + +## Søgeflow + +1. Web UI sender `POST /api/v1/fixtures/search-ofl?query=`. +2. Backend bruger OFL API, eller falder tilbage til lokale testfixtures i `test-data/fixtures`. +3. Resultater vises som `manufacturer/fixture`. + +## Preview + +Preview kaldes via: + +```http +POST /api/v1/fixtures/preview-ofl?manufacturer_key=&fixture_key= +``` + +Preview returnerer normaliseret fixturedata uden at skrive til lokal fixtureliste. + +I UI kan brugeren: + +- åbne preview, +- se schema-version, +- se kategorier, +- vælge og inspicere modes, +- se kanalindeks, displaynavn, precedence og opløsning. + +## Import + +Import kaldes via: + +```http +POST /api/v1/fixtures/import-ofl?manufacturer_key=&fixture_key= +``` + +Import: + +- henter rå OFL-data, +- normaliserer til TuxDMX-format, +- gemmer resultatet i lokal runtime/cache. + +## Modevalg + +Modevalg bruges i preview til inspektion af kanalstruktur. Importen bevarer alle normaliserede modes i fixturemodellen, så patch/UI senere kan vælge korrekt mode. + +## Fixture-normalisering + +Normalisering sker i `backend/app/fixtures/normalize.py`: + +- OFL JSON læses ikke direkte af runtime. +- Hver mode bliver til en stabil intern struktur med: + - `key` + - `channel_count` + - `channels[]` +- Hver kanal får: + - `index` + - `key` + - `display_name` + - `precedence` + - `resolution` + +Fallback-regel i denne leverance: + +- kanaler med `dim` i navnet bliver markeret som `HTP` +- øvrige kanaler bliver markeret som `LTP`, medmindre OFL-data allerede angiver noget andet + +## Offline fallback + +Hvis OFL ikke kan nås, søger klienten i lokale fixtures under `test-data/fixtures`. + +## Begrænsninger i denne leverance + +- OFL update-diff, warnings og backup før fixturemigration er endnu ikke fuldt implementeret. +- Runtime persistence til database for importerede fixtures er kun delvist implementeret; preview/import virker i simulator-runtime og kan verificeres via API/UI. + diff --git a/docs/audit-screenshots/bpm.png b/docs/audit-screenshots/bpm.png new file mode 100644 index 0000000..e206344 Binary files /dev/null and b/docs/audit-screenshots/bpm.png differ diff --git a/docs/audit-screenshots/dashboard.png b/docs/audit-screenshots/dashboard.png new file mode 100644 index 0000000..56a6ae9 Binary files /dev/null and b/docs/audit-screenshots/dashboard.png differ diff --git a/docs/audit-screenshots/dmx-monitor.png b/docs/audit-screenshots/dmx-monitor.png new file mode 100644 index 0000000..5ff7b23 Binary files /dev/null and b/docs/audit-screenshots/dmx-monitor.png differ diff --git a/docs/audit-screenshots/effects.png b/docs/audit-screenshots/effects.png new file mode 100644 index 0000000..6522001 Binary files /dev/null and b/docs/audit-screenshots/effects.png differ diff --git a/docs/audit-screenshots/fixtures.png b/docs/audit-screenshots/fixtures.png new file mode 100644 index 0000000..3231b6f Binary files /dev/null and b/docs/audit-screenshots/fixtures.png differ diff --git a/docs/audit-screenshots/mixitup.png b/docs/audit-screenshots/mixitup.png new file mode 100644 index 0000000..705ffcb Binary files /dev/null and b/docs/audit-screenshots/mixitup.png differ diff --git a/docs/audit-screenshots/patch.png b/docs/audit-screenshots/patch.png new file mode 100644 index 0000000..54417ca Binary files /dev/null and b/docs/audit-screenshots/patch.png differ diff --git a/docs/audit-screenshots/scenes.png b/docs/audit-screenshots/scenes.png new file mode 100644 index 0000000..4a01f09 Binary files /dev/null and b/docs/audit-screenshots/scenes.png differ diff --git a/docs/audit-screenshots/settings.png b/docs/audit-screenshots/settings.png new file mode 100644 index 0000000..a66ebc3 Binary files /dev/null and b/docs/audit-screenshots/settings.png differ diff --git a/docs/audit-screenshots/telemetry.png b/docs/audit-screenshots/telemetry.png new file mode 100644 index 0000000..4cae454 Binary files /dev/null and b/docs/audit-screenshots/telemetry.png differ diff --git a/docs/system-manual/MANUAL.md b/docs/system-manual/MANUAL.md new file mode 100644 index 0000000..4057ff6 --- /dev/null +++ b/docs/system-manual/MANUAL.md @@ -0,0 +1,323 @@ +# 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) diff --git a/docs/system-manual/README.md b/docs/system-manual/README.md new file mode 100644 index 0000000..7df662e --- /dev/null +++ b/docs/system-manual/README.md @@ -0,0 +1,25 @@ +# TuxDMX Systemmanual + +Denne mappe samler en enkel manuel dokumentationspakke til TuxDMX WebUI. + +Indhold: + +- `MANUAL.md` + Samlet brugermanual med opsaetning, daglig brug, Home Assistant-flow og service/update. +- `SCREENSHOTS.md` + Oversigt over alle genererede screenshots med korte forklaringer. +- `screenshots/` + PNG-screenshots af hele WebUI'et side for side. + +Vigtigt: + +- Screenshots i denne mappe er genereret den 23. juli 2026 fra den lokale WebUI i `mock=1` mode. +- De viser den aktuelle UI-struktur og sideopbygning. +- De er ikke dokumentation for fysisk Raspberry Pi-, OLA-, USB-DMX- eller lys-hardwaretest. +- Hardwareafgraensninger og manuel hardwarevalidering hoerer stadig hjemme i [HARDWARE-VALIDATION.md](../HARDWARE-VALIDATION.md). + +Anbefalet laeseraekkefoelge: + +1. `MANUAL.md` +2. `SCREENSHOTS.md` +3. de enkelte filer i `screenshots/` diff --git a/docs/system-manual/SCREENSHOTS.md b/docs/system-manual/SCREENSHOTS.md new file mode 100644 index 0000000..90388d9 --- /dev/null +++ b/docs/system-manual/SCREENSHOTS.md @@ -0,0 +1,68 @@ +# Screenshots + +Dette er et samlet screenshotsaet af TuxDMX WebUI genereret den 23. juli 2026. + +Kilde: + +- lokal UI-visning i `mock=1` +- capture fra browser via lokal preview-server + +Formaal: + +- vise sideopbygning +- understoette manualen +- give et hurtigt visuelt overblik over systemet + +## Oversigt + +### Dashboard + +![Dashboard](./screenshots/dashboard.png) + +### Live Desk + +![Live Desk](./screenshots/live-desk.png) + +### Fixtures + +![Fixtures](./screenshots/fixtures.png) + +### Patch + +![Patch](./screenshots/patch.png) + +### Placering + +![Placering](./screenshots/placement.png) + +### Scener + +![Scener](./screenshots/scenes.png) + +### Effekter + +![Effekter](./screenshots/effects.png) + +### BPM + +![BPM](./screenshots/bpm.png) + +### MixItUp + +![MixItUp](./screenshots/mixitup.png) + +### DMX monitor + +![DMX monitor](./screenshots/dmx-monitor.png) + +### Telemetry + +![Telemetry](./screenshots/telemetry.png) + +### Backup + +![Backup](./screenshots/backup.png) + +### Settings + +![Settings](./screenshots/settings.png) diff --git a/docs/system-manual/screenshots/backup.png b/docs/system-manual/screenshots/backup.png new file mode 100644 index 0000000..04bd9dc Binary files /dev/null and b/docs/system-manual/screenshots/backup.png differ diff --git a/docs/system-manual/screenshots/bpm.png b/docs/system-manual/screenshots/bpm.png new file mode 100644 index 0000000..42c69e9 Binary files /dev/null and b/docs/system-manual/screenshots/bpm.png differ diff --git a/docs/system-manual/screenshots/dashboard.png b/docs/system-manual/screenshots/dashboard.png new file mode 100644 index 0000000..15f8098 Binary files /dev/null and b/docs/system-manual/screenshots/dashboard.png differ diff --git a/docs/system-manual/screenshots/dmx-monitor.png b/docs/system-manual/screenshots/dmx-monitor.png new file mode 100644 index 0000000..68e66eb Binary files /dev/null and b/docs/system-manual/screenshots/dmx-monitor.png differ diff --git a/docs/system-manual/screenshots/effects.png b/docs/system-manual/screenshots/effects.png new file mode 100644 index 0000000..b7802b2 Binary files /dev/null and b/docs/system-manual/screenshots/effects.png differ diff --git a/docs/system-manual/screenshots/fixtures.png b/docs/system-manual/screenshots/fixtures.png new file mode 100644 index 0000000..3ee0a8f Binary files /dev/null and b/docs/system-manual/screenshots/fixtures.png differ diff --git a/docs/system-manual/screenshots/live-desk.png b/docs/system-manual/screenshots/live-desk.png new file mode 100644 index 0000000..8905dd4 Binary files /dev/null and b/docs/system-manual/screenshots/live-desk.png differ diff --git a/docs/system-manual/screenshots/mixitup.png b/docs/system-manual/screenshots/mixitup.png new file mode 100644 index 0000000..1a75bae Binary files /dev/null and b/docs/system-manual/screenshots/mixitup.png differ diff --git a/docs/system-manual/screenshots/patch.png b/docs/system-manual/screenshots/patch.png new file mode 100644 index 0000000..b8b7e1a Binary files /dev/null and b/docs/system-manual/screenshots/patch.png differ diff --git a/docs/system-manual/screenshots/placement.png b/docs/system-manual/screenshots/placement.png new file mode 100644 index 0000000..70c4701 Binary files /dev/null and b/docs/system-manual/screenshots/placement.png differ diff --git a/docs/system-manual/screenshots/scenes.png b/docs/system-manual/screenshots/scenes.png new file mode 100644 index 0000000..6112cdb Binary files /dev/null and b/docs/system-manual/screenshots/scenes.png differ diff --git a/docs/system-manual/screenshots/settings.png b/docs/system-manual/screenshots/settings.png new file mode 100644 index 0000000..fa5f1f3 Binary files /dev/null and b/docs/system-manual/screenshots/settings.png differ diff --git a/docs/system-manual/screenshots/telemetry.png b/docs/system-manual/screenshots/telemetry.png new file mode 100644 index 0000000..a90a2df Binary files /dev/null and b/docs/system-manual/screenshots/telemetry.png differ