Update docs and screenshots

2026-07-25 10:26:29 +02:00
parent d6cda77aaf
commit 1f110866f5
170 changed files with 24657 additions and 3 deletions
@@ -0,0 +1,124 @@
+# MIDI Bridge
+
+## Formål
+
+TuxDMX kan modtage normaliserede MIDI-events fra en ekstern Windows- eller Linux-maskine via en separat Python-bro i `tools/tuxdmx-midi-bridge/`.
+
+Bridgen læser kun MIDI og sender events videre til TuxDMX. Den genererer aldrig DMX direkte.
+
+## Eksisterende arkitektur før ændringen
+
+- Sceneaktivering fandtes allerede via `POST /api/v1/scenes/{scene_slug}/activate`
+- Scenerelease fandtes allerede via `POST /api/v1/scenes/{scene_slug}/release`
+- Blackout fandtes allerede via `POST /api/v1/dmx/blackout` og `POST /api/v1/dmx/release-blackout`
+- Effektstart/-stop fandtes allerede via `POST /api/v1/effects/{effect_slug}/trigger` og `POST /api/v1/effects/{effect_slug}/stop`
+- Live status blev sendt ud via WebSocket på `/ws/live`
+- Session/CSRF og API-tokenmodeller fandtes i backend, men MIDI-broen havde ingen eksisterende transport eller mappingmodel
+
+## Nye backend-endpoints
+
+### Admin / WebUI
+
+- `GET /api/v1/integrations/midi/bridges`
+- `GET /api/v1/integrations/midi/mappings`
+- `POST /api/v1/integrations/midi/mappings`
+- `PUT /api/v1/integrations/midi/mappings/{mapping_id}`
+- `DELETE /api/v1/integrations/midi/mappings/{mapping_id}`
+- `POST /api/v1/integrations/midi/mappings/{mapping_id}/test`
+- `GET /api/v1/integrations/midi/tokens`
+- `POST /api/v1/integrations/midi/tokens`
+- `DELETE /api/v1/integrations/midi/tokens/{token_id}`
+- `GET /api/v1/integrations/midi/learn`
+- `POST /api/v1/integrations/midi/learn/start`
+- `POST /api/v1/integrations/midi/learn/cancel`
+
+### Bridge transport
+
+- `POST /api/v1/integrations/midi/bridge/heartbeat`
+- `POST /api/v1/integrations/midi/bridge/events`
+
+Bridge-endpoints kræver `Authorization: Bearer <token>`.
+
+## Datamodel
+
+### `midi_bridges`
+
+- `bridge_id`
+- `device_name`
+- `ip_address`
+- `protocol_version`
+- `online`
+- `last_heartbeat_at`
+- `last_event_at`
+- `last_error`
+- `last_event`
+
+### `midi_bridge_tokens`
+
+- `label`
+- `token_hash`
+- `bridge_id` valgfri låsning til ét bridge-id
+- `scopes`
+- `last_used_at`
+- `revoked_at`
+
+### `midi_mappings`
+
+- `name`
+- `enabled`
+- `bridge_id`
+- `device_name`
+- `message_type`
+- `channel`
+- `number`
+- `action`
+- `target_type`
+- `target_id`
+- `mode`
+- `minimum_value`
+- `maximum_value`
+
+## Understøttede actions
+
+- `activate_scene`
+- `deactivate_scene`
+- `toggle_scene`
+- `flash_scene`
+- `blackout_on`
+- `blackout_off`
+- `blackout_toggle`
+- `set_master_dimmer`
+- `set_scene_intensity`
+- `start_effect`
+- `stop_effect`
+
+## Modes
+
+- `trigger`
+- `toggle`
+- `hold`
+- `flash`
+- `continuous`
+
+## Sikkerhed
+
+- Tokens returneres kun i klartekst ved oprettelse
+- Efter lagring vises kun `token_preview`
+- Bridge-token logges ikke
+- Protokolversion skal være `1`
+- Bridge kan låses til specifikt `bridge_id`
+- Ugyldige eller tilbagekaldte tokens afvises med `401`
+
+## Bridge-installation
+
+Se den fulde bridgepakke i:
+
+- `tools/tuxdmx-midi-bridge/README.md`
+- `tools/tuxdmx-midi-bridge/config.example.yaml`
+- `tools/tuxdmx-midi-bridge/tuxdmx-midi-bridge.service.example`
+
+## Kendte begrænsninger
+
+- Fysisk MIDI-hardware er ikke testet i denne workspace-session
+- Bridge bruger HTTP, ikke indgående WebSocket, selv om UI stadig bruger WebSocket til live status
+- `set_effect_speed` er ikke implementeret, fordi effektmotoren endnu ikke har et stabilt genanvendeligt speed-interface