SRCP - Simple Railroad Command Protocol 0.6.0
Torsten Vogt, Martin Ostermann, Kurt Haders, Olaf Schlachter, Matthias Trute, Tobias Schlottke, Edbert van Eimeren, Stefan Bormann
Mai 2000 Version 0.6.0
Inhaltsverzeichnis
1. Einleitung
Das SRCP beschreibt einen Befehlssatz zur Client-Server-Kommunikation zwischen Serverprozessen zur Steuerung von digitalen Modelleisenbahnen und deren Clients. Serverprozesse sind entweder Software-Signalgeneratoren oder Treiber für HW-Interfaces. Clients sind typischerweise Steuerungsprogramme.
Der SRCP-Befehlssatz besteht aus Kommandos, die direkt das Verhalten des Servers betreffen und aus Kommandos, die für die Dekoder der Modellbahnanlage bestimmt sind. Weiterhin werden Kommandos, die die Verarbeitung von Rückmeldungen betreffen spezifiziert.
Der Server kann über ein Zeitgebermodul verfügen, das alle Clients mit einer einheitlichen Modellzeit versorgen kann.
1.1 Konventionen
Die Übertragung der Kommandos von den Clients zum Server erfolgt via tcp/ip. Alle Kommandos werden mit dem Zeichen '\n' (line feed (LF), #10) abgeschlossen. Ein vorangestelltes '\r' (carriage return (CR), #13) wird akzeptiert. Jedes Kommando besteht aus Worten, die durch Whitespace (Leerzeichen, Tabulatoren) getrennt sind.
Die Worte der Kommandos können aus der Menge der Zeichen { '0'..'9', '*', '-', 'A'..'Z', 'a'..'z' } gebildet werden. Der Server wertet die Kommandos case-sensitive aus, d.h. zwischen Groß- und Kleinbuchstaben wird unterschieden.
Kommandos, die unvollständig oder offensichtlich falsch sind werden vom Server ignoriert.
1.2 Übertragungskanäle
Ein SRCP-konformer Server stellt den Clients drei Ports zur Verfügung.
- Kommandoport
- Rückmeldepollport
- Informationsport
Der Kommandoport dient den Clients dazu, dem Server Kommandos übermitteln. Der Server versucht die Kommandos auszuführen. Bei manchen Kommandos erwartet der Client eine Antwort. Die Antwort des Servers wird ebenfalls über den Kommandoport abgewickelt.
Der Rückmeldepollport wird nur unidirektional vom Server zum Client benutzt. Meldet sich ein Client am Rückmeldepollport an, so sendet der Server jede Statusänderung einer Rückmeldeeinheit an den Client zurück. Mit diesem Mechanismus ist es möglich, Rückmeldungen beim Client ereignisgesteuert zu bearbeiten.
Auch der Informationsport wird nur unidirektional von Server zu den Clients benutzt. Er ist eine Art Broadcast-Kanal, der ständig vom Server mit Statusänderungen von Lokdekodern und Schaltdekodern gefüttert wird. Er dient dem asynchronen Abgleich mehrerer Clients am selben Server.
Der Server bestimmt die Portnummern. Standardportnummer für den Kommandoport sollte 12345 sein. Der Rückmeldepollport und der Informationsport sollten die beiden unmittelbar folgenden Portnummern sein. Standardmässig ergeben sich somit folgende Portnummern:
- Kommandoport : 12345
- Rückmeldepollport: 12346
- Informationsport : 12347
Nimmt ein Client zum Kommandoport Kontakt auf und wird vom Server akzeptiert, muß der Server zunächst einen einzeiligen Informationstext über diesen Port zum Client schicken. Dieser Text sollte den Namen des Servers, dessen Versionsnummer und die implementierte SRCP-Version enthalten.
Beispiel:
erddcd v0.9.511; SRCP 0.5.0
Anschliesend wartet der Server auf Kommandos des Client. Der Client muß den Informationstext lesen und kann nun seinerseits Kommandos an den Server schicken.
2. Kommandos zur Serversteuerung
Kommunikationsports
- Client -> Server: Kommandoport
- Server -> Client: entfällt
Kommandos
- SHUTDOWN : Der Server beendet sich
- LOGOUT : Dem Server wird angzeigt, dass sich ein Client ausloggt
- STARTVOLTAGE: Der Server schaltet den Digitalstrom am Booster ein
- STOPVOLTAGE : Der Server schaltet den Digitalstrom am Booster aus
- RESET : Der Server re-initialisiert sich
3. Kommandos zur Digitalsteuerung
3.1 Befehle und Gerätegruppen
SRCP definiert 4 generelle Befehle:
- SET
- Setzt einen Wert vom Client über den Server zum Gerät.
- GET
- Ermittelt den aktuellen Zustand eines Gerätes.
- WAIT
- Wartet, bis ein Gerät einen bestimmten Zustand erreicht hat.
- INIT
- Falls Geräte explizit initialisiert werden müssen.
Geräte entstammen den Gerätegruppen Lokdekoder, Schaltdekoder und Rückmeldeeinheiten.
Über Parameter wird festgelegt, auf welche Gerätegruppe sich ein Befehl bezieht. Der erste Parameter legt immer die Gerätegruppe fest:
- GL
- Lok- und Funktionsdekoder (generic loco)
- GA
- Schaltdekoder (generic accessory)
- FB
- Rückmeldeeinheit (feedback)
- TIME
- Zeitnormal
Anwendbarkeit der Befehle auf Gerätegruppen:
| SET GET WAIT INIT
---+----------------------
|
GL | x x - -
|
GA | x x - -
|
FB | - x x x
|
TIME | x x x x
Bei einigen Befehlen (GET, WAIT) erwartet der Client vom Server eine Antwort. Es kann nun vorkommen, daß der Server zur gestellten Anfrage keine Antwort geben kann. In diesen Fällen muß der Server eine Zeichenkette zum Client senden, die folgendem Format genügt:
INFO <error code> \n
Als 'error code' muß eine negative Zahl übergeben werden. Folgende Konventionen gelten:
INFO -1 ==> Befehl wird nicht unterstützt (not supported)
INFO -2 ==> Keine Information vorhanden (no data)
INFO -3 ==> Zeitlimit überschritten (vgl. WAIT) (timeout)
3.2 Weitere Befehlsparameter
Die weiteren Befehlsparameter legen genau fest, welches konkrete Gerät und welche Eigenschaften beeinflußt oder abgefragt werden sollen.
Befehlsparameter des Befehls SET
Gerätegruppe GL
SET GL <protocol> <addr> <direction> <V> <V_max> <func> <nro_f> <f1> .. <fn>
Länge eines Kommandos (variabel): Befehlsendezeichen ist '\n'
Kommunikationsports
- Client -> Server: Kommandoport
- Server -> Client: entfällt
Bedeutung der Argumente:
- protocol
- M1, M2, M3, M4, MF, NB, N1, N2, N3, N4, PS
- M1: Märklin alt (rel. FRU, 80 Adr., 1 Funkt., 14 FS)
- M2: Märklin neu (abs. FRU, 80 Adr., 5 Funkt., 14 FS)
- M3: M2 erweitert (abs. FRU, 256 Adr., 5 Funkt., 28 FS)
- M4: M2 erweitert (abs. FRU, 256 Adr., 5 Funkt., 14 FS)
- MF: altes Märklin Format für Funktionsdekoder
- NB: NMRA-DCC Basisprotokoll (abs. FRU, 7-bit-Adr., 14 FS)
- N1: NMRA-DCC erweitert (abs. FRU, 7-bit-Adr., 5 Funkt., 28 FS)
- N2: NMRA-DCC erweitert (abs. FRU, 7-bit-Adr., 5 Funkt., 128 FS)
- N3: NMRA-DCC erweitert (abs. FRU, 14-bit-Adr., 5 Funkt., 28 FS)
- N4: NMRA-DCC erweitert (abs. FRU, 14-bit-Adr., 5 Funkt., 128 FS)
- PS: protocol by server, der Server bestimmt den Protokolltyp
- addr
- 0 .. 9999
- direction
- 0 (= rückwärts), 1 (= vorwärts), 2 (= Nothalt)
- V
- 0 .. V_max ((virtuelle) Geschwindigkeit)
- V_max
- 0 .. 999 (maximale (virtuelle) Geschwindigkeit) V_max=0 ==> virtuelle Fahrstufe = reale Fahrstufe
- func
- 0 (= aus), 1 (= an)
- nro_f
- 0 .. x (Anzahl der Zusatzfunktionen (number of functions))
- f1 .. fn
- 0 (= aus), 1 (= an)
Beispiel: SET GL N2 1 1 50 250 1 4 0 1 0 0
Umrechnung der virtuellen Geschwindigkeit in echte Fahrstufen:
gegeben
- DEC_fs (Anzahl der realen Dekoderfahrstufen, implizit bekannt)
- V (virtuelle Geschwindigkeit, Argument)
- V_max (maximale virtuelle Geschwindigkeit, Argument)
gesucht
- V_fs (reale Fahrstufe, die der virtuellen Geschw. entspricht)
Algorithmus: V_fs = round((V * DEC_fs)/V_max)
Hinweise für Entwickler von SRCP-konformen Servern
Es ist darauf zu achten, daß wirklich nur dann die reale Fahrstufe 0 (Stillstand) errechnet wird, wenn das Argument V gleich Null ist. Die Funktion 'round' ist deshalb hinreichend intelligent zu implementieren.
V_fs darf nur als Geschwindigkeitsangabe interpretiert werden. Manche Dekoder reagieren z.B. bei Fahrstufe 1 mit einem Nothalt, andere mit einem Richtungswechsel, wieder andere mit einer Selbstzerstörungssequenz ;-). Sollen solche Dekoder unterstützt werden, dann hat der Server dafür zu sorgen, daß V_fs entsprechend angepaßt wird, bevor das Kommando an den Dekoder gesendet wird. Aus Sicht der Clients müssen die Fahrstufen sukzessive von 0 bis zur maximalen Fahrstufenanzahl durchnummeriert sein.
Wird V_max auf 0 gesetzt, dann darf keine Umrechnung der Fahrstufe vorgenommen werden. D.h. die mit V übermittelte Fahrstufe ist direkt an die Dekoder weiterzusenden. Dies erlaubt Clients den direkten Zugriff auf die Dekoder.
Sendet der Client den Protokolltyp PS (protocol by server), dann muß der Server entscheiden, welches Protokoll er für die übermittelte Adresse wählt. Die anderen Protokolltypen stellen für den Server natürlich auch nur Empfehlungen des Clients dar. Der Server hat immer die Freiheit, einer Adresse ein anderes, geeigneteres Protokoll zuzuweisen.
Beispiele: (50*28)/250 = 5.7 ==> V_fs = 6
(4*28)/250 = 0.448 ==> V_fs = 1 (!!!)
(0*28)/250 = 0 ==> V_fs = 0
Gerätegruppe GA
SET GA <protocol> <acc_nr> <acc_port> <action> <delay>
Länge eines Kommandos (variabel): Befehlsendezeichen ist '\n'
Kommunikationsports:
- Client -> Server: Kommandoport
- Server -> Client: entfällt
Bedeutung der Argumente
- protocol
-
- M: Märklin/Motorola-Format
- N: NMRA-DCC-Format
- acc_nr
- 1 .. 4096 (Nummer der Weiche/des Signals)
- acc_port
- 0, 1 (Ausgang des Dekoders)
- action
- 0, 1 (0 = deaktiviert, 1 = aktiviert)
- delay
- Wert in Millisekunden (1000stel-Sekunden). Gibt an, nach welcher Zeit der Daemon einen aktivierten Ausgang automatisch deaktivieren soll. Wird '-1' als delay übergeben, dann wird der Ausgang nicht automatisch deaktiviert. Ist action=0 (Deaktivierung) wird delay ignoriert, muß aber angegeben werden (sinnvoller Wert: '-1').
Belegung der Dekoderausgänge:
- 0 = Weiche abbiegen, Signal Hp0, ...
- 1 = Weiche gerade, Signal Hp1, ...
Beispiel:
SET GA M 0023 1 1 20
Servicemode
Es gibt Dekoder, die auf einem Programmiergleis oder 'on-track' programmierbar sind. Diese Dekoder erlauben die Änderung von 'Speicherzellen' (Register, CV (configuration variable), Bit). Diese Dekoder können auch von SRCP-Servern unterstützt werden. Dazu dienen die folgenden Befehle.
SET GL SM <protocol> <dest-type> <dest-addr> [bitnr] <value> SET GA SM <protocol> <dest-type> <dest-addr> [bitnr] <value>
Länge eines Kommandos (variabel): Befehlsendezeichen ist '\n'
Kommunikationsports:
- Client -> Server: Kommandoport
- Server -> Client: entfällt
Bedeutung der Argumente
- protocol
- NMRA, ...
- dest-type
- Art der zu ändernden Dekoderspeicherzelle (destination type)
- CV
- NMRA-DCC configuration variable
- CVBIT
- ein Bit einer NMRA-DCC configuration variable
- REG
- Ein Register eines NMRA-DCC-Dekoders
- dest-addr
- Adresse der Speicherzelle, die geändert werden soll
- bitnr
- nur in Verbindung mit CVBIT sinnvoll
- value
- neuer Wert der Speicherzelle
TIME
Die aktuelle Modellzeit und die Verzerrung gegenüber der Realzeit wird festgelegt. Bei erstmaligen Aufruf vergleichbar mit einem INIT TIME.
SET TIME TAG STUNDE MINUTE SEKUNDE FX FY
- TAG
- sequentielle Folge von Tageszahlen (julianisch)
- STUNDE
- 0..23, besteht aus 60 MINUTEN
- MINUTE
- 0..59, besteht aus 60 SEKUNDEN
- SEKUNDE
- 0..59
- FX, FY
- Ganzzahlige Bestandteile der Zeitverzerrung
Beispiel:
SET TIME 1 23 55 0 1 1
setzt auf den Abend des ersten Tages mit Modellzeit gleich Realzeit. (vgl. INIT TIME)
sonstiges
Hier könnte man spezielle Kommandos für Spezialdekoder (z.B. für Drehscheiben) spezifizieren.
Befehlsparameter des Befehls GET
Gerätegruppe GL
GET GL <protocol> <addr>
Länge eines Kommandos (variabel): Befehlsendezeichen ist '\n'
Kommunikationsports:
- Client -> Server: Kommandoport
- Server -> Client: Kommandoport
Bedeutung der Argumente: siehe SET GL
Der Server sendet an den Client alle verfügbare Info zu dem mit >protocol> und <addr> spezifizierten Lok- oder Funktionsdekoder. Diese Info muß wie folgt formatiert werden:
INFO GL <protocol> <addr> <direction> <V> <V_max> <func> <nro_f> <f1> .. <fn>
(vgl. SET GL)
Sollte keine Information vorhanden sein, oder der Server den Befehl GET nicht unterstützen, dann muß der Server 'INFO <error code>' an den Client senden (vgl. Digitalsteuerung).
Gerätegruppe GA
GET GA <protocol> <acc_nr> <acc_port>
Länge eines Kommandos (variabel): Befehlsendezeichen ist '\n'
Kommunikationsports:
- Client -> Server: Kommandoport
- Server -> Client: Kommandoport
Bedeutung der Argumente: siehe SET GA
Der Server sendet an den Client alle verfügbare Info zu dem mit <protocol> und <acc_nr> spezifizierten Schaltdekoder. Diese Info muß wie folgt formatiert werden:
INFO GA <protocol> <acc_nr> <acc_port> <state>
(vgl. SET GA, ersetze <state> durch <action>)
Sollte keine Information vorhanden sein, oder der Server den Befehl GET nicht unterstützen, dann muß der Server 'INFO <error code>' an den Client senden (vgl. Digitalsteuerung).
Gerätegruppe FB
GET FB <module-type> <portnr>
Länge eines Kommandos (variabel): Befehlsendezeichen ist '\n'
Kommunikationsports:
- Client -> Server: Kommandoport
- Server -> Client: Kommandoport
Bedeutung der Argumente
- module-type
-
- S88 (Märklin s88-Bus am Parallelport des PC)
- I8255 (i8255 Karte)
- M6051 (Märklin s88-Bus via Interface 6051)
- portnr
- konkreter Eingang eines Rückmeldemoduls oder '*' für alle verfügbaren Eingänge
Der Server sendet auf dem Rückmeldekanal an den Client den aktuellen Status des mit <module-type> und <portnr> spezifizierten Rückmeldemoduleingangs. Diese Info muß wie folgt formatiert werden:
INFO FB <module-type> <portnr> <state>
Wobei state entweder '0' oder '1' sein darf.
Wurde als portnummer der Platzhalter '*' angegeben, so sendet der Server als portnummer den '*' (ohne Hochkomma), gefolgt von den Zuständen aller angeschlossenen Ports. Diese Zustände werden NICHT durch Leerzeichen getrennt.
Beispiel
INFO FB M6051 * 1100110010101111
Sollte keine Information vorhanden sein, oder der Server den Befehl GET nicht unterstützen, dann muß der Server 'INFO <error code>' an den Client senden (vgl. 3.1).
Servicemode
Hier könnte man spezielle Kommandos zum Auslesen von Konfigurations- variablen diverser Dekoder spezifizieren.
TIME
Liefert die aktuelle Modellzeit und die Verzerrungsfaktoren als INFO-Zeile
sonstiges
Hier könnte man spezielle Kommandos für Spezialdekoder (z.B. für Drehscheiben) spezifizieren.
Befehlsparameter des Befehls WAIT
Gerätegruppe FB
WAIT FB <module-type> <portnr> <value> <timeout>
Länge eines Kommandos (variabel): Befehlsendezeichen ist '\n'
Kommunikationsports:
- Client -> Server: Kommandoport
- Server -> Client: Kommandoport
Wartet, bis portnr den Wert value (0,1) annimmt. Wartet aber höchstens timeout Sekunden. Sendet falls der timeout nicht eingetreten ist, die gleiche Information wie GET FB. Sollte der timeout überschritten werden, wird 'INFO -3' an den Client gesendet.
Sollte keine Information vorhanden sein, oder der Server den Befehl WAIT nicht unterstützen, dann muß der Server 'INFO <error code>' an den Client senden (vgl. 3.1).
TIME
Wartet, bis die Modellzeit den angegebenen Zeitpunkt mind. erreicht hat und liefert einen INFO-String mit der aktuellen Modellzeit.
WAIT TIME <TAG> <STUNDE> <MINUTE> <SEKUNDE>
bei nicht initialisiertem Zeitgeber wird "INFO -1" geliefert. Ist die aktuelle Modellzeit bereits später als die übergebende Zeit ist die Bedingung ohne weitere Wartezeit erfüllt. Offensichtlich falsche Zeitangaben werden ignoriert.
Befehlsparameter des Befehls INIT
Feedback Module
INIT FB <module-type>
Kommunikationsports:
- Client -> Server: Kommandoport
- Server -> Client: entfällt
Initialisiert die entsprechenden Rückmeldeeinheiten. Keine Nachricht an den Client.
TIME
INIT TIME <TAG> <STUNDE> <MINUTE> <SEKUNDE> <FX> <FY>
startet den Zeitgeber mit der Verzerrung FX/FY am angegeben Zeitpunkt. Jede volle Modellminute wird sodann als INFO Paket auf dem INFO-Port aller aktiven und zukünftigen Clients ausgesendet.
Die Modellzeit errechnet sich wie folgt:
(Delta) Modellzeit = (Delta) Realzeit * FX / FY
Beispiel:
- FX=10 FY=1 -> Alle 6 Realsekunden läuft eine Modellminute ab.
- FX=1 FY=10 -> Alle 600 Realsekunden läuft eine Modellminute ab.
- FX=1 FY=1 -> Jede Realminute läuft eine Modellminute
Die Tageszahl wird fortlaufend alle 24 Modellstunden hochgezählt.
4. Datenformate der Serverinformationen
4.1 Rückmeldepollport
Die Datenübertragung auf dem Rückmeldepollport unterliegt den gleichen Beschränkungen wie die des Kommandoports (plain text, '\n' als Endezeichen). Die Daten müssen mit folgendem Format übertragen werden:
INFO FB <module-type> <portnr> <state>
(vgl. GET FB)
Beim Öffnen des Ports werden sofort alle aktuell _belegten_ (state == 1) FB-Ports an den Client übermittelt. Anschließend alle Veränderungen.
4.2 Informationsport
Die Datenübertragung auf dem Informationsport unterliegt den gleichen Beschränkungen wie die des Kommandoports (plain text, '\n' als Endezeichen). Die Daten müssen mit folgenden Formaten - abhängig von der Gerätegruppe - übertragen werden:
INFO GL <protocol> <addr> <direction> <V> <V_max> <func> <nro_f> <f1> .. <fn>
(vgl. GET GL)
INFO GA <protocol> <acc_nr> <acc_port> <state>
(vgl. GET GA)
INFO TIME <TAG> <STUNDE> <MINUTE> <SEKUNDE> <FX> <FY>
(vgl. GET TIME)
5. Ausblicke, zukünftige Erweiterungen
Ich habe bewußt einige Ideen, die andiskutiert wurden, nicht mit aufgenommen. Ich bin der Meinung, daß wir einen vorläufigen Schlußstrich ziehen und die ganzen netten Dinge implementieren sollten. Damit die anderen guten Ideen nicht verloren gehen, werde ich sie in diesem Abschnitt aufführen.
5.1 Zentrale Konfiguration
Von Kurt Haders stammt der Vorschlag einer zentralen Konfigurationsdatei. Hauptanliegen ist es, mehr "Wissen" von den Clients in den Server zu verlagern. Ein Format, wie eine solche Konfigurationsdatei aussehen soll, liegt noch nicht vor. Das Übertragungsprotokoll ist duch den Protokollbezeichner 'PS' (protocol by server) bereits darauf vorbereitet.
5.2 Erweiterung der Befehle auf andere Gerätegruppen
Von Matthias Trute kommt der Vorschlag den Befehl WAIT auch für die Gerätegruppen GL und GA zuzulassen. Allerdings kann es hierbei zu Inkonsistenzen kommen. Weiterhin könnte man man bei WAIT Wildcards ('*') zulassen.
5.3 Quittierung von Befehlen
Martin Ostermann hängt an einer Befehlsquittierung. Dieses könnte über den Rückkanal des Kommandoports realisiert werden.
5.4 Konfiguration des Servers auslesen
Von Edbert van Eimeren kommt der Vorschlag, daß Clients die Konfiguration des Servers abfragen können sollten (neuer Befehl: CONFGET).
