SRCP 0.5.0 (plain text)

aus DerMoba, der Wissensdatenbank für Modellbahner
Version vom 17. Januar 2006, 10:52 Uhr von Werner Falkenbach (Diskussion | Beiträge) (neu)

(Unterschied) ← Nächstältere Version | Aktuelle Version (Unterschied) | Nächstjüngere Version → (Unterschied)
Wechseln zu: Navigation, Suche
               SRCP - Simple Railroad Command Protocol
                           Version 0.5.0
              Torsten Vogt, Martin Ostermann, Kurt Haders, 
            Olaf Schlachter, Matthias Trute, Tobias Schlottke
                          Edbert van Eimeren
 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.
 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.
 
     1. Kommandoport
     2. Rückmeldepollport
     3. 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)
 Anwendbarkeit der Befehle auf Gerätegruppen:
       |  SET  GET  WAIT  INIT
    ---+----------------------
       |
    GL |   x    x    -     -  
       |
    GA |   x    x    -     -
       |
    FB |   -    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.
 3.2.1 Befehlsparameter des Befehls SET
 3.2.1.1 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
 3.2.1.2 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, N
              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
 3.2.1.3 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

 3.2.1.4 sonstiges

 Hier könnte man spezielle Kommandos für Spezialdekoder (z.B.
 für Drehscheiben) spezifizieren.  
 3.2.2 Befehlsparameter des Befehls GET
 3.2.2.1 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 3.2.1.1
 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. 3.2.1.1)
 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).

 3.2.2.2 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 3.2.1.2
 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. 3.2.1.2, 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. 3.1). 
 3.2.2.3 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 
 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. 

 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).              
 3.2.2.4 Servicemode
 Hier könnte man spezielle Kommandos zum Auslesen von Konfigurations-
 variablen diverser Dekoder spezifizieren.
 3.2.2.5 sonstiges
 Hier könnte man spezielle Kommandos für Spezialdekoder (z.B.
 für Drehscheiben) spezifizieren.
 3.2.3 Befehlsparameter des Befehls WAIT
 3.2.3.1 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).
 3.2.6 Befehlsparameter des Befehls INIT
 INIT FB <module-type>
 Kommunikationsports: Client -> Server: Kommandoport
                      Server -> Client: entfällt
 Initialisiert die entsprechenden Rückmeldeeinheiten. Keine Nachricht
 an den Client.


 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. 3.2.2.3)
 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. 3.2.2.1)
 INFO GA <protocol> <acc_nr> <acc_port> <state> 
 (vgl. 3.2.2.2)


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