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.

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.

BoosterStatus

Dieses Kommando erfragt den Status eines oder aller Booster.

Pakettyp Kommando Paketnummer Booster-Adresse Neu
 0x20 0x91 0x00 .. 0xFF 1..63, 255 0x00 .. 0x02

Von Steuersoftware zu senden

Über die Booster-Adresse kann entweder ein einzelner Booster (1 bis 63) oder alle Booster (255) angesprochen werden.

Das Feld Neu hat die folgenden Bedeutungen:

  • 0x00: alle Booster
  • 0x01: neue Booster
  • 0x02: nur Railspeed
Pakettyp Kommando Paketnummer Anzahl Booster-Adresse Status A Status B
 0x21 0x91 0x00 .. 0xFF   1..63 0x00 .. 0x01  0x00 .. 0x01

Antwort vom Gerät

Das Feld Anzahl gibt die Anzahl der gelesenen Booster zurück jeder Booster belegt im Paket jeweils drei Bytes.

Booster-Adresse entspricht der µCon-Adresse des gefundenen Boosters. Status A und Status B enthalten die Statusinformation der beiden Booster-Kanäle nach dem folgenden Muster:

  • Status X = 0: Booster-Kanal aus
  • Status X = 1: Booster-Kanal ein
  • Status X = 2: Booster-Kanal Kurzschluss

BoosterCurrent

Dieses Kommando fragt Informationen zur Spannung, zu der Stromstärke beider Kanäle und zur Temperatur ab.

Pakettyp Kommando Paketnummer Booster-Adresse
 0x20 0x92 0x00 .. 0xFF 1..63, 255

Von Steuersoftware zu senden

Über die Booster-Adresse kann entweder ein einzelner Booster (1 bis 63) oder alle Booster (255) angesprochen werden.

Pakettyp Kommando Paketnummer Anzahl Booster-Adresse Spannung Strom A Strom B Temp.
 0x21 0x92 0x00 .. 0xFF   1..63 0..255  0..255 0..255 0..255

Antwort vom Gerät

Das Feld Anzahl gibt die Anzahl der gelesenen Booster zurück jeder Booster belegt im Paket jeweils fünf Bytes.

Booster-Adresse entspricht der µCon-Adresse des gefundenen Boosters.

Das Feld Spannung enthält die am Booster gemessene Ausgangsspannung. Sie lässt sich nach der folgenden Formel ermitteln: Spannung*17.0/146.0.

Die Felder Strom A und Strom B enthalten den am jeweiligen Booster-Kanal gemessenen Strom. Er lässt sich nach der folgenden Formel ermitteln: Strom*2.5/127.0.

Das Feld Temperatur wird zur Zeit nicht verwendet und ist immer 0.

BoosterGetConfig

Dieses Kommando liest die Einstellungen eines Boosters.

Pakettyp Kommando Paketnummer Booster-Adresse
 0x20 0x93 0x00 .. 0xFF 1 .. 63

Von Steuersoftware zu senden

Die Booster-Adresse gibt den zu lesenden Booster (1 bis 63) an.

Pakettyp Kommando Paketnummer Booster-Adresse Empfindlichkeit Ausschaltzeit Startmodus Railcom
 0x21 0x93 0x00 .. 0xFF 1 .. 63 10 .. 50  0 .. 15 0 .. 1 0 .. 1

Antwort vom Gerät

Die Booster-Adresse gibt den Booster an, dessen Einstellungen gelesen wurden.

Die Empfindlichkeit stellt die Zeitdauer ein, bis ein Kurzschluss ausgelöst wird. Die folgenden Einstellungen sind möglich:

  • 10: 50ms "sehr schnell"
  • 20: 100ms "schnell"
  • 30: 300ms "normal"
  • 40: 500ms "langsam"
  • 50: 700ms "sehr langsam"

Die Ausschaltzeit gibt an, wie lange der Booster nach einem Kurzschluss ausgeschaltet bleiben soll, bevor er automatisch wieder einschaltet. Dieser Wert wird in Sekunden angegeben.

Mit dem Startmodus wird das Verhalten nach einem Kurzschluss eingestellt.

  • 0: Nach einem Kurzschluss wird der Booster nach Ablauf der in Empfindlichkeit eingestellten Zeit wieder eingeschaltet.
  • 1: Der Booster bleibt nach einem Kurzschluss ausgeschaltet.

Das Feld Railcom gibt an, ob der Booster einen Railcom-Cutout generiert.

  • 0: Der Booster generiert keinen Railcom-Cutout.
  • 1: Der Booster generiert einen Railcom-Cutout.

BoosterGetBus

Dieses Kommando liest den gesamten µCon-Bus aus.

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

Von Steuersoftware zu senden

Pakettyp Kommando Paketnummer Anzahl Typ0 .. Typ63
 0x21 0xA0 0x00 .. 0xFF 64      

Antwort vom Gerät

Die 64 Typ-Felder sind aufsteigend mit allen µCon-Adressen beginnend mit 0 gefüllt. Die Werte entsprechen den Typen der vorhandenen Geräte.

  • 0: Kein Gerät auf Adresse vorhanden
  • 1: µCon-Booster
  • 2: Railspeed
  • 3: LoDi-Booster
  • 4: CDE-Anschluss

Railspeed-Kommandos

RailspeedConfigGet

Liest die Einstellungen eines Railspeed-Sensors.

Pakettyp Kommando Paketnummer Adresse
 0x20 0x9E 0x00 .. 0xFF 1 .. 63

Von Steuersoftware zu senden

Das Feld Adresse enthält die µCon-Adresse des einzustellenden Railspeed-Sensors.

Pakettyp Kommando Paketnummer Adresse ScaleHigh ScaleLow Sprache LenAktiv TolAktiv
 0x21 0x9E 0x00 .. 0xFF 1 .. 63     0 .. 1 0 .. 1 0 .. 1

Von Steuersoftware zu senden

Das Feld Adresse enthält die µCon-Adresse des einzustellenden Railspeed-Sensors.

Die beiden Feldern ScaleHigh und ScaleLow den Maßstab 1:n für die Messung an. Wobei sich n wie folgt berechnet: n = (ScaleHigh*256 + ScaleLow) / 10.

Das Feld Sprache legt die Sprache für das Display des Railspeed-Sensors fest.

  • 0: Deutsch
  • 1: Englisch

Die Einstellung LenAktiv aktiviert die Längenmessung.

  • 0: Längenmessung inaktiv
  • 1: Längenmessung aktiv

Mit TolAktiv wird die Toleranzmessung aktiviert.

  • 0: Die Toleranzmessung der Geschwindigkeit ist inaktiv
  • 1: Die Toleranzmessung der Geschwindigkeit ist aktiv.

RailspeedConfigSet

Setzt die Einstellungen eines angeschlossenen Railspeed-Sensors.

Pakettyp Kommando Paketnummer Adresse ScaleHigh ScaleLow Sprache LenAktiv TolAktiv
 0x20 0x9B 0x00 .. 0xFF 1 .. 63     0 .. 1 0 .. 1 0 .. 1

Von Steuersoftware zu senden

Das Feld Adresse enthält die µCon-Adresse des einzustellenden Railspeed-Sensors.

In den beiden Feldern ScaleHigh und ScaleLow wird der Maßstab 1:n für die Messung eingestellt. Wobei sich n wie folgt berechnet: n = (ScaleHigh*256 + ScaleLow) / 10. Für den Maßstab H0 (n=87) ist also ScaleHigh auf 3 und ScaleLow auf 102 zu setzen.

Das Feld Sprache legt die Sprache für das Display des Railspeed-Sensors fest.

  • 0: Deutsch
  • 1: Englisch

Die Einstellung LenAktiv aktiviert die Längenmessung.

  • 0: Längenmessung inaktiv
  • 1: Längenmessung aktiv

Mit TolAktiv wird die Toleranzmessung aktiviert.

  • 0: Die Toleranzmessung der Geschwindigkeit ist inaktiv
  • 1: Die Toleranzmessung der Geschwindigkeit ist aktiv.
Pakettyp Kommando Paketnummer
 0x21 0x9B 0x00 .. 0xFF

Antwort vom Gerät

RailspeedTextSet

Ändert den im Railspeed-Sensor angezeigten Text.

Pakettyp Kommando Paketnummer Adresse Länge Zeichen 1 .. Zeichen 16
 0x20 0x9F 0x00 .. 0xFF 1 .. 63 0 .. 16      

Von der Steuersoftware zu senden

Das Feld Adresse enthält die µCon-Adresse des Railspeed-Sensors.

Das Feld Länge bestimmt die Länge des anzuzeigenden Strings und damit auch die Länge des Pakets.

Die Einträge Zeichen 1 bis Zeichen 16 enthalten die einzelnen Zeichen des Strings. Der String wird nicht 0-terminiert.

RailspeedActiveSet

Aktiviert und deaktiviert die Events von Railspeed-Sensoren.

Pakettyp Kommando Paketnummer Adresse Aktiv
 0x20 0x9C 0x00 .. 0xFF 1 .. 63, 255 0 .. 1

Von der Steuersoftware zu senden

Das Feld Adresse enthält die µCon-Adresse des zu aktivierenden Railspeed-Sensors. Wird 255 angegeben, werden die Events aller am Bus vorhandenen Railspeed-Sensoren aktiviert oder deaktiviert.

Der Eintrag Aktiv gibt an, ob die Events des Sensor aktiviert oder deaktiviert werden sollen.

  • 0: Events deaktivieren
  • 1: Events aktivieren

RailspeedEvent

Dieser Event wird automatisch vom Gerät gesendet, wenn Railspeed-Events eingeschaltet sind.

Pakettyp Kommando Paketnummer Adresse Typ WertHi WertLo Status Valid SensorL SensorR
 0x22 0x9D 0x00 .. 0xFF 1 .. 63 1, 2, 4     0 .. 1 0 .. 1 0 .. 1 0 .. 1

Event vom Gerät

Das Feld Adresse enthält die µCon-Adresse des auslösenden Railspeed-Sensors.

Typ bestimmt, die Art des Events.

  • 1: Geschwindigkeitsmessung
  • 2: Längenmessung
  • 3: Toleranz der Geschwindigkeit

Die Einträge WertHi und WertLo geben den Messwert an. Bei Geschwindigkeits- und Toleranzmessung ist die Einheit mm/s, bei Längenmessung mm. Sind WertHi und WertLo 0, so ist die Messung ungültig.

Der Messwert wird dabei wie folgt ermittelt: Wert = WertHi*256 + Wert Low.

Das Feld Status zeigt an, ob die Messung beendet ist.

  • 0: Messung beendet, bereit für nächste Messung
  • 1: Messung läuft noch

Valid gibt an, ob der in WertHi und WertLo angezeigt Wert gültig ist.

  • 0: WertLo und WertHi sind ungültig.
  • 1: WertLo und WertHi sind gültig.

Die Einträge SensorL und SensorR zeigen die aktuelle Verdeckung des linken und rechten Sensors an.

  • 0: Sensor frei
  • 1: Sensor verdeckt

Generator

Der Generator kann DCC- und Motorola-Gleissignale erzeugen. Er ist nur aktiv, wenn der CDE-Anschluss entweder abgeschaltet ist oder auf Ausgang steht.

GeneratorActivate

Aktiviert oder deaktiviert den Generator. Mit der Aktvierung des Generators wird ein Idle-Signal auf dem Gleis erzeugt.

Pakettyp Kommando Paketnummer Protokoll
 0x20 0x80 0x00 .. 0xFF 0 .. 2

Von der Steuersoftware zu senden

Protokoll definiert, ob der Generator aktiv ist und welches Protokoll im Leerlauf verwendet werden soll.

  • 0: Generator deaktiviert
  • 1: DCC
  • 2: Motorola

GeneratorProtokollGet

Liest das Default-Protokoll des Generators.

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

Von der Steuersoftware zu senden

Pakettyp Kommando Paketnummer Protokoll
 0x21 0x81 0x00 .. 0xFF 1 .. 2

Antwort vom Gerät

Das Feld Protokoll enthält das aktive Default-Protokoll des Generators.

  • 1: DCC
  • 2: Motorola

GeneratorMessage

Schickt neue DCC- oder Motorola-Daten an den Generator.

Pakettyp Kommando Paketnummer Info Data 0 .. Data n
 0x20 0x82 0x00 .. 0xFF        

Von der Steuersoftware zu senden

Das Feld Info hat eine Doppelfunktion und ist wie folgt aufgeteilt:

  • Bit 0 bis 5: Länge der Daten
  • Bit 6 und 7: Protokoll
    • 1: DCC
    • 2: Motorola

Die Einträge Daten 0 bis Daten n enthalten das DCC- bzw. Motorola-Paket ohne Prüfsumme. Diese wird vom Generator selbst errechnet.

Ein UDP-Paket  kann mehrere solcher DCC- oder Motorola-Pakete enthalten.

Pakettyp Kommando Paketnummer Hinzugefügt Idle-Zähler
 0x21 0x82 0x00 .. 0xFF    

Antwort vom Gerät

Das Feld Hinzugefügt enthält die Anzahl der DCC- bzw. Motorola-Pakete, die in den Puffer aufgenommen wurden.

Der Idle-Zähler enthält die Anzahl der gesendeten Idle-Pakete seit der letzten Nachricht.