Dot2 X-Touch Controller Bridge

Eine Python-Brücke zur Steuerung von dot2 (MA Lighting) über einen Behringer X-Touch MIDI-Controller mit integrierter Web-Oberfläche zur Konfiguration und Visualisierung.

Features

• Bidirektionale Kommunikation: Steuere dot2 über Fader, Buttons und Encoder des X-Touch
• Echtzeit-Visualisierung: Web-Oberfläche zeigt aktuelle Executor-Namen, Werte und Zustände an
• Profile-System: Mehrere Benutzerprofile mit individuellen MIDI-Mappings und Passwortschutz
• Executor-Farben: Individuelle Farben für Displays (gespeichert in SQLite-Datenbank)
• Spezialfunktionen: Store, Delete, Move, Edit-Modus direkt am Controller
• Page-Sync: Optionale Synchronisation zwischen Controller-Seite und dot2-Seite
• Blackout-Taste: Hardware-Steuerung des Blackout-Masters
• Encoder-Steuerung: Pan/Tilt, Dim, Zoom, RGB-Encoder mit Geschwindigkeitsregelung
• Robustheit: Automatische Reconnects für MIDI und dot2, Send-Queue für den dot2-Socket, Thread-Safe MIDI-Output
• Fehlercodes: Jede Fehlermeldung trägt einen Code im Format [XX######] (siehe Errorcode.md)

Architektur

┌─────────────┐      MIDI      ┌─────────────────┐    Send-Queue     ┌─────────┐
│   X-Touch   │◄──────────────►│  Controller.py  │──┐                │  dot2   │
│  (HW)       │                │  (MIDI I/O,     │  │     Sender     │  Console│
│             │                │   RLock gesicherter Output)│◄──┘      │         │
└─────────────┘                └────────┬────────┘  ▲   Thread       └────┬────┘
                                        │           └──────────────────────┘
                                        ▼
                               ┌─────────────────┐
                               │ Message_Handler │◄──────┐
                               │   (Logik)       │       │
                               └────────┬────────┘       │
                                        │                │
                                        ▼                ▼
                               ┌─────────────────┐    ┌──────────┐
                               │    Database     │    │  WebGUI  │
                               │ (SQLite, 1x     │    │ (Flask + │
                               │  persist. Conn) │    │    SSE)  │
                               └─────────────────┘    └──────────┘

Threading-Architektur

Thread	Aufgabe	Hinweis
MIDI-Input	Liest MIDI-Events, routet an Message_Handler	blockiert nie auf Netzwerk/DB
dot2 Listen	Empfängt dot2-WebSocket-Antworten	Reconnect + Heartbeat
dot2 Sender	Schickt Send-Queue sequenziell in den Socket	websocket-client ist nicht thread-safe, daher zentraler Sender
WebGUI	Flask-Server (HTTP + SSE)	Debug-Modus aus
Controller-Time	LCD-Uhr/Seite/Profil alle 100ms	RLock-geschützter MIDI-Output

Installation

Voraussetzungen

• Python 3.10+
• dot2 Software (läuft auf gleichem oder separatem PC/Server)
• Behringer X-Touch USB
• Netzwerkverbindung zwischen dot2 und diesem Rechner

Abhängigkeiten

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Hinweis: python-rtmidi braucht auf Linux ggf. sudo apt install portmidi1-dev libasound2-dev (Alsa/PortMIDI), auf Windows läuft es out of the box.

Hardware-Setup

1. X-Touch angeschlossen per USB oder MIDI-Interface
2. Auf X-Touch USB und CtrlRel ausgewählt

Konfiguration

Umgebungsvariablen

Alle Zugangsdaten laufen über Umgebungsvariablen – nichts steht im Klartext im Code:

Variable	Pflicht	Beschreibung
DOT2_HOST	nein (Default 127.0.0.1)	IP-Adresse/Hostname des dot2-Systems
DOT2_PASSWORD	ja	dot2-Remote-Passwort (wird md5-gehasht)
WEBGUI_PORT	nein (Default 5000)	Port der Web-Oberfläche

Beispiele:

Linux / macOS (Bash):

export DOT2_HOST="192.168.178.46"
export DOT2_PASSWORD="dein-dot2-passwort"
python main.py

Windows – PowerShell (das ist der Standard im Windows Terminal):

$env:DOT2_HOST = "192.168.178.46"
$env:DOT2_PASSWORD = "dein-dot2-passwort"
python main.py

Windows – CMD:

set DOT2_HOST=192.168.178.46
set DOT2_PASSWORD=dein-dot2-passwort
python main.py

⚠️ export ist ein Bash-Befehl und gibt es in PowerShell/CMD nicht – deshalb $env: bzw. set. Die Variablen gelten nur für die laufende Terminal-Session. Für einen dauerhaften Wert: Windows → „Umgebungsvariablen des Systems bearbeiten" | Linux: in der .bashrc/.profile.

Fehlt DOT2_PASSWORD, bricht der Start mit [MN000002] ab.

⚠️ games.py ist ein standalone-Spiel-Tool für den X-Touch und wird von main.py nicht verwendet – es kann getrost ignoriert bzw. separat aufgerufen werden.

Erststart

Beim ersten Start wird automatisch eine data.db (SQLite, WAL-Modus) neben dem Code erstellt mit:

• Tabelle Profiles (Profile-Verwaltung)
• Tabelle MAPPING (MIDI-zu-dot2 Zuordnungen)
• Tabelle Display_Color (Executor-Farben)
• Tabelle AppState (letztes aktive Profil)

Nutzung

Standardbedienung

X-Touch Element	Funktion
Fader 1-8	Executor 1-8 der aktuellen Page
Fader-Touch	Berührungserkennung (Motorstop beim Bewegen)
Encoder	Je nach Modus: Pan, Tilt, Dim, Zoom, RGB
Buttons 1-8 (oben)	Executor-Buttons (oberer Reihe)
Buttons 9-16 (unten)	Executor-Buttons (unterer Reihe)
Blackout-Taste	Taste 57: Blackout On/Off
CC 70-77	Fader-Werte (MIDI)

Spezialmodi (über MIDI-Mapping konfigurierbar)

• STORE: Executor speichern (Merge/Overwrite/Remove)
• DELETE: Executor löschen
• MOVE: Executor verschieben (Quelle -> Ziel)
• EDIT: Executor umbenennen (öffnet Web-Modal)
• PAGE: Seite wechseln (Links/Rechts)

Motorfader-Verhalten

• Bei Berührung (Note 110-117) wird die Motorsteuerung deaktiviert
• Nach Loslassen: 0.3s Sperre, bevor der Fader wieder externe Werte annimmt
• Bei Seitenwechsel fahren Fader ohne Executor sichtbar nach unten (CC → 0)
• Verhindert das „Kämpfen" gegen den Motor

Web-Oberfläche

Zugriff

http://<host>:5000

Features der GUI

• Live-View: Zeigt alle 8 Executors mit Namen, Werten und Farben
• Fader-Steuerung: Virtuelle Fader zum Testen und Steuern
• Farbeditor: Klick auf Executor-Name öffnet Farbwahl
• Profile-Manager: Profile erstellen/umbenennen/löschen, Passwortschutz, klonen, Import/Export als JSON
• MIDI-Mapping: Lernmodus (MIDI-Capture), CC-Live-Modus, Highlighting der Mappings
• SSE (Server-Sent Events): Echtzeit-Updates ohne Polling

MIDI-Mapping Referenz

Standard-Noten (X-Touch)

Note	Funktion
8-15	Buttons Executor 1-8 (Reihe 1)
16-23	Buttons Executor 1-8 (Reihe 2)
24-31	Fader-Buttons oben
32-39	Fader-Buttons unten
57	Blackout
58-65	Gruppen 1-8
70-77	Fader-CCs
110-117	Fader-Touch (Berührungserkennung)

Variablen in Mappings

• {page}: Aktuelle Seitennummer (1-basiert)
• {cc_value}: CC-Wert (0-127)

Beispiel: "SpecialMaster 2.1 At {cc_value}" für Blackout-Steuerung.

Fehlerdiagnose

Jede Fehlermeldung (Konsole und log.txt) beginnt mit einem Fehlercode:

[CT000102] MIDI-Verbindung verloren: …

Die vollständige Referenz mit Ursachen und Lösungen steht in Errorcode.md.

Schnellstart:

# Die 10 häufigsten Fehler
grep -oE '\[[A-Z]{2}[0-9]{6}\]' log.txt | sort | uniq -c | sort -rn | head -10

# Konkreten Code filtern
grep 'CT000102' log.txt

Troubleshooting-Checkliste

• X-Touch im richtigen MIDI-Modus (USB + CtrlRel, nicht Mackie)?
• DOT2_HOST / DOT2_PASSWORD korrekt gesetzt?
• data.db beschreibbar? (Rechte am Ordner prüfen)
• Port 5000 (WebGUI) frei?
• [LG000001] im Log → Logger selbst kann nicht schreiben (Rechte/Platz)
• [DT000308] im Log → dot2-Passwort-Abweichung
• [CT000111] im Log → X-Touch wird vom System nicht erkannt
• USB-Power-Saving am PC deaktiviert? (häufigste Ursache für CT000102 auf Laptops)

Bekannte Probleme & Hinweise

• Flask-Dev-Server: Läuft bewusst einfach; bei hohem SSE-Bedarf gunicorn/Werkzeug vorziehen.
• exit() bei session == -1: Früher beendete dot2 hier den ganzen Prozess; inzwischen wird sauber neu verbunden.
• Erster Seitenaufruf schwarz: Wurde durch FA000101-Handling + Neunamen-Check behoben. Falls es wiederkehrt: Errorcode.md → MH000202 + [Diag]-Zeilen im Log prüfen.

Roadmap / Ideen

• Systemd-/Dienste-Start: Auto-Start beim Booten mit DOT2_HOST/DOT2_PASSWORD aus /etc/default/midi-controller
• Log-Rotation: log.txt wächst unendlich – logging.handlers.RotatingFileHandler einbauen
• Health-Check-Endpunkt: GET /health in der WebGUI (dot2 verbunden? MIDI da? Queue voll?)
• dot2-Protokoll-Monitor: DEBUG_DOT2=1 druckt alle WS-Nachrichten – nützlich bei FA000101
• Profil-Vorsatz: DOT2_PROFILE als Env-Variablen-Default
• Fader-Debouncer für Web-Fader (aktuell: jeder Bewegungspunkt = dot2-Request)
• MIDI-Activity-LED: X-Touch-Note 57 kurz anblitzen bei DT000305/DT000306
• WebGUI-Dark-Mode-Polish + Mobile-Layouthinzugefügt: Fehlercode-Badge im Seitenkopf der GUI
• Multi-Controller: Zweiten X-Touch als zweites Profil (z.B. für Crew)
• Tests: tests/ mit pytest – bisher keine automatisierten Tests vorhanden

Lizenz & Entwicklung

Privates Projekt zur Steuerung von dot2-Konsolen über MIDI-Hardware.