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.

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

00000009h: 02 ; .

Padding

0000000ah: 20 20 ;

Teilbereich-Info

0000000ch: 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 ; ..