Dateiformat DMX-Modul

Aus PyroNeo Wiki
Zur Navigation springenZur Suche springen

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

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 ; ..