Dateiformat DMX-Modul
Das DMX-Modul benutzt ein kompaktes Binärformat, damit Sequenzen möglichst schnell aufgerufen und gefunden werden können. Diese Seite ermöglicht es Softwareentwicklern, direkt die vom DMX-Modul verwendeten Dateien zu schreiben.
Inhaltsverzeichnis
Grundsätze
Die Dateiendung ist .DMX. Alle in der Datei angegebenen Integer-Daten sind im Big-Endian-Format abgelegt, d.H. das höherwertige Byte wird zuerst gespeichert. Nach dem Dateiheader folgt eine Versionskennung welche es für die Zukunft ermöglicht, das Dateiformat aktuellen Entwicklungen anzupassen. Dabei wird die Rückwärtskompatibilität aufrecht erhalten. Alte Dateiformate können also weiterhin vom DMX-Modul geladen werden.
Allgemeiner Header
Die vom DMX-Modul verwendeten Dateien beginnen alle mit dem folgenden Header:
| Offset | Länge | Bedeutung |
| 0 | 9 Bytes | String "SDDMXDATA" |
| 9 | 8 Bit | Versionsnummer |
| 10 | 16 Bit | Padding (0-Bytes) |
Dateiformat Version 1
Version 1 des Dateiformats wurde nur intern verwendet und wurde nie öffentlich benutzt. Hierzu existiert daher keine Beschreibung.
Dateiformat Version 2
Version 2 untergliedert die DMX-Datei in verschiedene Bereiche, welche unterschiedliche Zwecke erfüllen. Nicht jeder Bereich muss vorhanden sein. In der Zukunft können für erweiterte Funktionen andere Bereiche hinzu kommen. Unbekannte Bereiche werden vom DMX-Modul ignoriert.
Teilbereiche
Hinter dem Dateiheader befindet sich eine Tabelle in welcher die unterschiedlichen Bereiche zusammen mit ihrem Offset innerhalb der Gesamtdatei angegeben sind. Der Aufbau ist wie folgt:
- 32 Bit Anzahl der folgenden Bereiche (= n)
Die folgende Struktur wird n-mal wiederholt:
| Offset (Byte) | Größe | Bedeutung |
|---|---|---|
| 0 | 4 Byte | Name des Bereichs, aufgefüllt mit 0-Bytes |
| 4 | 32 Bit | Reserviert, auf 0 setzen |
| 8 | 32 Bit | Startposition des Bereichs innerhalb der Datei (Offset) |
| 12 | 32 Bit | Länge des Bereichs |
Hinter der Tabelle der Teilbereiche folgen die Daten der einzelnen Teilbereiche.
Bereich DAFT
Im DAFT-Bereich (DMX Address Flag Table) werden unterschiedliche Konfigurationen für die benutzten DMX-Kanäle festgelegt. Für jeden der 513 DMX-Datenkanäle (Kanal 0 wird zusätzlich mit 0 belegt) wird ein Flag-Feld angegeben. Jedes Feld ist 32 Bit groß. Der gesamte Teilbereich hat daher eine Größe von 2052 Bytes. Folgende Flags sind vergeben:
| Name | Flag-Wert | Bedeutung |
| FLAG_ARMING_LOCK | 1 | Der Kanal wird auf 0 gehalten, bis das Modul scharf geschaltet ist |
| ALWAYS_INTERNAL | 2 | Der Kanal wird nie vom DMX-Eingang übernommen sondern IMMER intern gesetzt. |
| COPY_ARMED_VALUE | 4 | Der Wert des Kanals wird beim unscharf schalten NICHT zurückgesetzt |
Bereich DSQT
Im DSQT-Bereich (DMX SeQuence Table) werden die einzelnen DMX-Sequenzen verwaltet. Der Bereich wird verwendet um eine bestimmte Sequenz innerhalb der Sequenzdaten (Bereich DSQD) schnell anspringen zu können:
- 16 Bit Anzahl der gespeicherten Sequenzen (= n)
Folgende Struktur wird n-mal wiederholt:
| Offset (Byte) | Länge | Bedeutung |
| 0 | 16 Bit | Sequenznummer |
| 2 | 32 Bit | Sequenzoffset innerhalb des DSQD-Bereichs |
| 6 | 32 Bit | Dauer der Sequenz in Millisekunden |
Bereich DSQD
Im Bereich DSQD (DMX SeQeuence Data) werden die einzelnen Sequenzen abgelegt welche dann vom DMX-Modul ausgeführt werden. Die Sequenzdaten beinhalten außerdem Einsprungpunkte um bestimmte Stellen innerhalb der Sequenzdaten schnell anspringen zu können. Jede Sequenz beginnt mit der erneuten Angabe der Nummer der Sequenz:
| Offset | Länge | Bedeutung |
| 0 | 16 Bit | Wiederholung der Sequenznummer |
| 2 | 32 Bit | Dauer der Sequenz in Millisekunden |
Sequenz-Flags
Sequenz-Flags bestimmen den Ablauf einer Sequenz sowie die Bedingungen unter denen eine Sequenz ausgeführt werden darf:
| Offset | Länge | Bedeutung |
| 0 | 32 Bit | Kennung der Flags (Wert 0x0200xxxx), xxxx entspricht den Sequenz-Flags |
| 4 | 32 Bit | Länge der Sequenztabelle: Wert 0 |
Folgende Flags werden z.Zt. erkannt:
| Name | Wert | Bedeutung |
| MAY_RUN_DISARMED | 1 | Die Sequenz darf auch gestartet werden/ablaufen wenn das DMX-Modul NICHT scharf geschaltet ist. |
Einsprungpunkte
Es folgt die Tabelle mit den Einsprungpunkten. Im Schnitt wird pro 100 DMX-Befehle eine Sprungmarke gesetzt.
| Offset | Länge | Bedeutung |
| 0 | 32 Bit | Kennung der Sprungmarkentabelle (Wert 0x01000000) |
| 4 | 32 Bit | Byte-Länge der Sprungmarken-Daten (Offset der Programmdaten) |
Anschließend folgen die eigentlichen Sprungmarken-Daten (entsprechend oft wiederholt):
| Offset | Länge | Beschreibung |
| 0 | 32 Bit | Aktuelle Sequenzzeit in Millisekunden |
| 4 | 32 Bit | Byte-Offset innerhalb der Programmierdaten |
Programmdaten
Die eigentlichen DMX-Daten bestehen aus einzelnen Befehlen, die vom DMX-Modul ausgeführt werden. Dies können Befehle zur Ansteuerung von DMX-Ausgängen, aber auch Befehle zum Abwarten einer Wartezeit sein. Es können in Zukunft Befehle hinzu kommen. Jeder Befehl hat eine implizite Länge; diese wird verwendet um den nächsten Befehl zu finden. Der Bereich der Programmdaten beginnt mit dem folgenden Header:
| Offset | Länge | Bedeutung |
| 0 | 32 Bit | Kennung der Programmdaten (Wert 0) |
| 4 | 32 Bit | Byte-Länge der Programmdaten |
Anschließend folgen die einzelnen Befehle. Ab hier wird auch der Offset in der Sprungtabelle gezählt:
Befehl 0, Ende der Sequenz
Befehl 0 besteht nur aus einem Nullbyte. Er beendet die laufende Sequenz bzw. kennzeichnet deren Ende.
Befehl 1, relative Wartezeit
| Offset | Länge | Bedeutung |
| 0 | 8 Bit | Befehl: 1 |
| 1 | 16 Bit | Wartezeit in Millisekunden |
Es wird ab der aktuellen Sequenzzeit die angegebene Zeit gewartet
Befehl 2, absolute Wartezeit
| Offset | Länge | Bedeutung |
| 0 | 8 Bit | Befehl: 2 |
| 1 | 32 Bit | Sequenzzeit in Millisekunden. |
Es wird gewartet, bis die angegebene Sequenzzeit erreicht ist.
Befehl 3, DMX-Kanal setzen
| Offset | Länge | Bedeutung |
| 0 | 8 Bit | Befehl: 3 |
| 1 | 16 Bit | DMX-Kanal 1-512 |
| 3 | 8 Bit | Neuer Wert des Kanals |
Setzt den angegebenen DMX-Kanal auf den angegebenen Wert
Bereich MDSI
Im Bereich MDSI (Manual DMX Sequence Information) werden Informationen zu von Hand am DMX-Modul aufrufbaren Sequenzen abgelegt. Die Einträge werden dabei einfach hintereinander abgelegt:
| Offset | Länge | Bedeutung |
| 0 | 20 Byte | Name der Sequenz |
| 20 | 8 Byte | (Reserviert, 0-Bytes) |
| 28 | 16 Bit | Sequenznummer |
| 30 | 16 Bit | Flags |
Folgende Flags können angegeben werden:
| Name | Wert | Bedeutung |
| ARM_BEFORE_RUN | 1 | Das Modul muss temporär und lokal scharf geschaltet werden, damit die Sequenz laufen kann |
Beispielhafte DMX-Datei der Version 2
Header-Kennung
00000000h: 53 44 44 4D 58 44 41 54 41 ; SDDMXDATA
Version 2
02 ; .
Padding
20 20 ;
Teilbereich-Info
00 00 00 04 ; ....
Header DAFT
00000010h: 44 41 46 54 00 00 00 00 00 00 00 50 00 00 08 04 ; DAFT.......P....
Header DSQT
00000020h: 44 53 51 54 00 00 00 00 00 00 08 54 00 00 00 0C ; DSQT.......T....
Header DSQD
00000030h: 44 53 51 44 00 00 00 00 00 00 08 60 00 00 00 92 ; DSQD.......`...’
Header MDSI
00000040h: 4D 44 53 49 00 00 00 00 00 00 08 F2 00 00 00 00 ; MDSI.......ò....
Sektion "DAFT", Offset 0x50
00000050h: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ; ................
..
(Nur 0-Bytes)
..
00000840h: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ; ................
00000850h: 00 00 00 00 ; ....
Sektion DSQT
Ein Eintrag in der Sequenztabelle.
00000854h: 00 01 ; ..
Eintrag für Sequenz 1, Beginn bei Offset 0, Länge 0x2af8/11000ms:
00000856h: 00 01 00 00 00 00 00 00 2A F8 ; ..........*ø
Sektion DSQD
Daten der Sequenzen (bzw. hier der einen Sequenz):
Sequenz 1:
00000860h: 00 01 ; ..
Dauer der Sequenz in Millisekunden:
00000862h: 00 00 2A F8 ; ..*ø
Flags der Sequenz MIT Flag-Kennung 0x02000000, Länge der Flag-Daten 0:
00000866h: 02 00 00 00 00 00 00 00 ; ........
Einsprungpunkte der Sequenz (Kennung 0x01000000), mit Länge 8 Byte:
0000086eh: 01 00 00 00 00 00 00 08 ; ........
Erster (und einziger) Sprungpunkt, Zeit 0, Offset 0:
00000876h: 00 00 00 00 00 00 00 00 ; ........
Kennung Programmbereich (0x0) mit Länge der Daten 0x6c/108 Byte:
0000087eh: 00 00 00 00 00 00 00 6C ; .......l
Befehl 3, Kanal 4 auf 255:
00000886h: 03 00 04 FF ; ...ÿ
Befehl 3, Kanal 5 auf 255:
0000088ah: 03 00 05 FF ; ...ÿ
Befehl 3, Kanal 6 auf 255:
0000088eh: 03 00 06 FF ; ...ÿ
Befehl 1, Wartezeit 0x1f4/500ms:
00000892h: 01 01 F4 ; ..ô
Befehl 3, Kanal 1 auf 255:
00000895h: 03 00 01 FF
(Rest unkommentiert)
00000899h: 03 00 02 00 03 00 03 ; ...ÿ.......
000008a0h: 00 01 03 E8 03 00 01 00 03 00 02 FF 01 03 E8 03 ; ...è.......ÿ..è.
000008b0h: 00 02 00 03 00 03 FF 01 03 E8 03 00 03 00 01 03 ; ......ÿ..è......
000008c0h: E8 03 00 01 FF 01 03 E8 03 00 01 00 03 00 02 FF ; è...ÿ..è.......ÿ
000008d0h: 01 03 E8 03 00 02 00 03 00 03 FF 01 03 E8 03 00 ; ..è.......ÿ..è..
000008e0h: 03 00 01 0D AC 03 00 04 00 03 00 05 00 03 00 06 ; ....¬...........
000008f0h: 00 00 ; ..
