API LoDi-Shift-Commander

Einführung

Im folgenden werden die vom LoDi-Shift-Commander verstandenen Kommandos aufgelistet. Die Kommunikation zum Gerät wird im Abschnitt Allgemeine API erklärt.

Basis-Kommandos

GetVersion

Dieses Kommando liefert die Gerätekennung sowie die FW-Version des Geräts.

Pakettyp Kommando Paketnummer
 0x20 0x0F 0x00 .. 0xFF

Von Steuersoftware zu senden

Pakettyp Kommando Paketnummer Gerätetyp Major Minor Patch
 0x21 0x0F 0x00 .. 0xFF 0x09      

Antwort vom Gerät

Der Gerätetyp ist beim LoDi-Shift-Commander immer 0x09.

Die Firmware-Version setzt sich aus den drei Komponenten Major, Minor und Patch zusammen. Sie wird im Format "v<Major>.<Minor>.<Patch>" angezeigt. Beispiel: "v01.01.01"

Die Major-Version ändert sich nur, wenn eine komplett neue Hardware mit geänderten Eigenschaften und Funktionsumfang herausgebracht wird.

Die Minor-Version ändert sich, wenn Ergänzungen an der API erfolgen. Diese können bei einzelnen Kommandos auch inkompatibel sein.

Die Patch-Version ändert sich bei allgemeinen Fehlerbehebungen, die nicht die API betreffen.

DeviceConfigGet

Dieses Kommando liest die Einstellungen des LoDi-Shift-Commanders.

Pakettyp Kommando Paketnummer
 0x20 0x64 0x00 .. 0xFF

Von Steuersoftware zu senden

Pakettyp Kommando Paketnummer Bus-Konfig MaxAktivWeichen WeichenStart
 0x21 0x64 0x00 .. 0xFF 0 .. 1 0 .. 10  0 .. 2

Antwort vom Gerät

Das Feld Bus-Konfig enthält die Konfiguration des Busses. Es ist in mehrere Bits aufgeteilt.

  • Bit 0: Bus 1 aktiv
    • 0: Bus 1 inaktiv
    • 1: Bus 1 aktiv
  • Bit 1: Bus 2 aktiv
    • 0: Bus 2 inaktiv
    • 1: Bus 2 aktiv
  • Bit 2: Bus Kofniguration
    • 0: Licht-Bus (96 Ausgänge)
    • 1: Schalt-Bus (384 Ausgänge)

Im Feld MaxAktivWeichen wird die Anzahl der gleichzeitig geschalteten Weichen definiert. Auf diese Weise wird bei Magnetartikel eine Überlast im Netzteil vermieden.

  • 0: Keine Begrenzung
  • >0: Die eingestellte Anzahl an Weichen kann gleichzeitig aktiv sein. Sonst wird mit der Befehlsausführung gewartet, bis die anderen Weichen geschaltet haben.

Der Eintrag WeichenStart legt die Initialisierung der Weichen beim Einschalten fest.

  • 0: Es erfolgt keine Initialisierung der Weichen
  • 1: Die Weichen werden auf den letzten Zustand gestellt.
  • 2: Alle Zustände der Weichen werden einmal durchgeschaltet. Danach wird der letzte vor dem Ausschalten bekannte Zustand eingestellt.

OperatorNameGet

Liest den Namen eines LoDi-Operator aus.

Pakettyp Kommando Paketnummer BusNr OperatorPos
 0x20 0x73 0x00 .. 0xFF 1..2 0..47

Von Steuersoftware zu senden

Pakettyp Kommando Paketnummer Länge Zeichen 1 .. Zeichen n
 0x21 0x73 0x00 .. 0xFF  0 .. 16      

Antwort vom Gerät

Die BusNr gibt den zu verwendenden Bus an. Innerhalb des Busses bestimmt die OperatorPos den zu lesenden Operator-Namen. Jeder LoDi-Operator wird dabei als ein Gerät gezählt.

 

Die Länge bestimmt die Anzahl der folgenden Zeichen.

Schalt-Kommandos

CommandListGet

Liest die Liste aller vom LoDi-Shift-Commander unterstützten Kommandos.

Pakettyp Kommando Paketnummer
 0x20 0x61 0x00 .. 0xFF

Von Steuersoftware zu senden

Pakettyp Kommando Paketnummer Anzahl KommandoNr Zustände Ausgänge Kategorie
 0x21 0x61 0x00 .. 0xFF    0 .. 255 1 .. 16  1 .. 10 0 .. 3

Antwort vom Gerät

Im Feld Anzahl wird die Anzahl möglichen Kommandos übergeben. Dieser Eintrag bestimmt wie viele Kommandobeschreibungen folgen.

Das Feld KommandoNr ist die Kennung des Kommandos.

Der Eintrag Zustände gibt an, wievele Zustände von 0 an gezählt das Kommando einnehmen kann. Eine einfache Weiche hat typischerweise 2 Zustände. Signale können durchaus 10 oder mehr Zustände haben.

Ausgänge beschreibt die Anzahl der vom Kommando auf der Hardware belegten Ausgänge. Eine einfache Weiche belegt zwei Ausgänge, Signale durchaus 6 und mehr.

Im Feld Kategorie wird die Klassifizierung des Kommandos ausgegeben. Die folgenden Werte sind möglich:

  • 0: Weichen - Weichen werden beim Start initialisiert, wenn dies so im Gerät eingestellt ist
  • 1: Signale - Alle Gleissignale, egal ob Licht oder Formsignale
  • 2: Effekte - Alle Lichteffekte
  • 3: Spezial - Alle speziellen Dekoderkommandos wie z.B. für den LoDi-Light-Operator

CommandNameGet

Liest den Namen eines Kommandos und weitere Zusatzinformationen.

Pakettyp Kommando Paketnummer KommandoNr
 0x20 0x62 0x00 .. 0xFF 0 .. 255

Von der Steuersoftware zu senden

Das Feld KommandoNr enthält die Kennung des zu lesenden Kommandos.

Pakettyp Kommando Paketnummer Länge Zeichen 0 .. Zeichen n
 0x21 0x62 0x00 .. 0xFF        

Antwort vom Gerät

Das Feld Länge bestimmt die Anzahl der in Zeichen 0 bis Zeichen n folgenden Zeichen. Der daraus resultierende String muss noch wie folgt interpretiert werden:

<Kommandoname>|<Farbe Ausgang 1>|..|<Farbe Ausgang n>

Die Farben sind wie folgt festgelegt:

  • ws: weiß
  • rt: rot
  • gn: grün
  • ge: gelb
  • bl: blau

Die Farben werden den jeweiligen Ausgängen zugeordnet. Sie dienen hauptsächlich der Anzeige.

Bei einigen Kommandos wird nur der Kommandoname ohne zusätzliche Farbkennung zurückgegeben.

 

Beispiel:

"DB BS|rt|gn" -> Deutsche Bahn Block Signal mit den Farben rot und grün

NodeConfigGet

List die Konfiguration aller Knoten aus dem LoDi-Shift-Commander.

Pakettyp Kommando Paketnummer
 0x20 0x66 0x00 .. 0xFF

Von Steuersoftware zu senden

Pakettyp Kommando Paketnummer GlobDelay Anzahl AusgangHi AusgangLo KommandoNr Delay
 0x21 0x66 0x00 .. 0xFF 0 .. 250        0 .. 255 0 .. 255

Antwort vom Gerät

GlobDelay gibt die Kommandodauer an, wenn Delay auf 0 gesetzt wird. Die Kommandodauer wird in 20ms Schritten interpretiert. Ein Wert von 10 bedeutet also 200ms. Die genaue Wirkung ist vom Kommando abhängig.

Das Feld Anzahl gibt die Anzahl der folgenden Knoten-Datensätze an. Jeder Datensatz ist vier Bytes lang. Der Index des Datensatzes bestimmt die Adresse des Knotens. Die Zählung beginnt bei 0 (Die Anzeige addiert 1 dazu).

AusgangHi und AusgangLo ergeben zusammen den ersten vom Knoten angesprochenen Ausgang. Die Nummer des Ausgangs wird wie folgt berechnet:

Ausgang = AusgangHi*256 + AusgangLo

Der Eintrag KommandoNr bestimmt das auszuführende Kommando. Ist das Kommando 0, so liegt auf dieser Adresse keine Funktion.

NodeNameGet

List den Namen eines oder mehrerer Knoten.

Pakettyp Kommando Paketnummer Anzahl Knoten
 0x20 0x71 0x00 .. 0xFF 0 .. 255 0 .. 255

Von Steuersoftware zu senden

Pakettyp Kommando Paketnummer Anzahl Länge Zeichen 1 .. Zeichen n
 0x21 0x71 0x00 .. 0xFF  0 .. 255 0..16      

Antwort vom Gerät

Das Feld Anzahl gibt an wie viele Knoten gelesen werden. Die Knoten (Adressen) können in beliebiger Reihenfolge angegeben werden.

In der Antwort folgen entsprechend der Anzahl festgelegt die Namen in der Reihenfolge der Anfrage, wobei immer erst die Länge und entsprechend der Länge die Zeichen folgen.

NodeStatusGet

List den aktuellen (remanent gespeicherten) Zustand aller Knoten aus dem LoDi-Shift-Commander aus.

Pakettyp Kommando Paketnummer
 0x20 0x6A 0x00 .. 0xFF

Von Steuersoftware zu senden

Pakettyp Kommando Paketnummer Anzahl Status
 0x21 0x6A 0x00 .. 0xFF  0 .. 255 0..15

Antwort vom Gerät

Das Feld Anzahl gibt die Anzahl der folgenden Status-Felder an. Es werden nur so viele Status-Felder übermittelt wie für die höchste belegte Adresse benötigt werden. Jedes Status-Feld entspricht dabei einer Adresse. Die Zählung beginnt mit Adresse 0.

NodeStatusSend

Setzt den Zustand eines oder mehrerer Knoten (Adressen), d.h. schaltet Weichen, Signale o.ä.

Pakettyp Kommando Paketnummer Anzahl Knoten Zustand
 0x20 0x6C 0x00 .. 0xFF 0 .. 255 0 .. 255 0 .. 15

Von Steuersoftware zu senden

Pakettyp Kommando Paketnummer
 0x21 0x6C 0x00 .. 0xFF

Antwort vom Gerät

Das Feld Anzahl gibt die Anzahl der folgenden Knoten/Zustand-Paare an.

 

Jeder Knoten (jede Adresse) kann einen Zustand von 0 bis 15 annehmen.

 

Beispiel für Adresse 5: 0x20 0x6C 0xXX 0x01 0x05 0x01

Der Shift-Commander schickt dann eine Bestätigung: 0x21 0x6C 0xXX 

 

Beispiel für mehrere Adressen schicken ( 1,2,3,4): 0x20 0x6C 0xXX 0x04 0x01 0x01 0x02 0x01 0x03 0x01 0x04 0x01  

Der Shift-Commander schickt dann eine Bestätigung: 0x21 0x6C 0xXX 

 

Anmerkungen:

  • Es ist nicht notwendig das Senden von Weichenbefehlen zu verzögern. Der LoDi-Shift-Commander sorgt dafür, dass nicht zu viele Weichen auf einmal schalten.
  • Der gesetzte Zustand wird remanent gespeichert und ist dem LoDi-Shift-Commander somit nach dem nächsten Einschalten bekannt.

OutputsGet

Liest den Status aller Ausgänge.

Pakettyp Kommando Paketnummer
 0x20 0x60 0x00 .. 0xFF

Von Steuersoftware zu senden

Pakettyp Kommando Paketnummer AnzahlHigh AnzahlLow Zustand
 0x21 0x60 0x00 .. 0xFF     0 .. 255

Antwort vom Gerät

Die Felder AnzahlHigh und AnzahlLow ergeben zusammen die Anzahl der folgenden Ausgangszustände.

Anzahl = AnzahlHigh*256 + AnzahlLow

 

Die Anzahl der nachfolgenden Ausgänge richtet sich nach der Einstellung von Bus 2. Stehen beide Busse auf Lichtbus, so werden 192 Ausgangszustände übertragen. Steht Bus 2 auf Schaltbus, so werden 480 Ausgänge übertragen.

 

Bus 1 beginnt beim ersten und endet beim 96. Byte. Bus 2 beginnt ab dem 100. Byte.

 

Das Feld Zustand beinhaltet den internen Ausgangszustand. Es ist wie folgt zu interpretieren:

  • Wert <= 100: Ausgang ist an.
  • Wert zwischen 100 und 164: Ausgang ist gedimmt.
  • Wert >= 164 Ausgang ist aus.

Raumlichtsteuerung

Die Raumlichtsteuerung ist prinzipiell auch nur ein LoDi-Operator, jedoch mit einigen Zusatzfunktionen. Der LoDi-Operator 4-C-LED  kann genauso mit NodeStatusSend geschaltet werden.

 

Die Belegung der Zustände ist dabei wie folgt:

  • 0: Beleuchtung aus
  • 1: Licht-Kurve 1
  • 2: Licht-Kurve 2
  • 3: Licht-Kurve 3
  • 8: Blitz
  • 9: Doppelblitz
  • 10: zufälliges Blitzen
  • 11: Wolkenzug

Der LoDi-Shift-Commander simuliert einen 24-Stundentag. Die simulierte Zeit wird zyklisch an alle LoDi-Operator 4-C-LED übertragen. Die Operatoren sind aber auch in der Lage ohne Zeitsynchronisation die Zeit für sich zu weiterzuzählen.

TimeSpeedSet

Set die Geschwindigkeit des Zeitablaufs in Vielfachen der normalen Zeit.

Pakettyp Kommando Paketnummer Faktor
 0x20 0x76 0x00 .. 0xFF 0 .. 250

Von Steuersoftware zu senden

Pakettyp Kommando Paketnummer
 0x21 0x76 0x00 .. 0xFF

Antwort vom Gerät

Das Feld Faktor gibt die Zeitbeschleunigung in Vielfachen zum normalen Zeitablauf an. Ein Wert von 0 stoppt die Zeit.

Bei einem Wert von 120 ist eine Stunde z.B. nur noch 30 Sekunden lang.

TimeGet

Liest die aktuelle simulierte Zeit aus.

Pakettyp Kommando Paketnummer
 0x20 0x78 0x00 .. 0xFF

Von Steuersoftware zu senden

Pakettyp Kommando Paketnummer ZeitHigh ZeitLow
 0x21 0x78 0x00 .. 0xFF    

Antwort vom Gerät

Die aktuelle Zeit wird in 2 Sekunden-Schritten gezählt. Sie wird wie folgt berechnet:

Zeit = ZeitHigh*256 + ZeitLow

 

Eine Stunde ist 1800 Zeiteinheiten lang. Der höchste Wert für die Zeit beträgt 43199.

 

Eine Zeit von 36000 entspricht also 20:00 Uhr.

TimeSet

Setzt die aktuelle simulierte Zeit.

Pakettyp Kommando Paketnummer ZeitHigh ZeitLow
 0x20 0x77 0x00 .. 0xFF    

Von Steuersoftware zu senden

Pakettyp Kommando Paketnummer
 0x21 0x77 0x00 .. 0xFF

Antwort vom Gerät

Die aktuelle Zeit wird in 2 Sekunden-Schritten gezählt. Sie wird wie folgt berechnet:

Zeit = ZeitHigh*256 + ZeitLow