Benutzer:Edbert van Eimeren/Test2: Unterschied zwischen den Versionen

aus DerMoba, der Wissensdatenbank für Modellbahner
Wechseln zu: Navigation, Suche
(SRCP 0.8.0)
(SRCP 0.7.2, Anker für interne Links?)
Zeile 1: Zeile 1:
''''' Torsten Vogt, Martin Ostermann, Kurt Harders, Olaf Schlachter, Matthias Trute (Maintainer), Tobias Schlottke, Edbert van Eimeren, Stefan Bormann, Michael Reukauff, Martin Wolf, Matthias Peick, Martin Schönbeck '''''
+
''' Torsten Vogt, Martin Ostermann, Kurt Haders, Olaf Schlachter, Matthias Trute, Tobias Schlottke, Edbert van Eimeren, Stefan Bormann, Michael Reukauff '''
  
2000, 2001
+
Juli 2000
  
----
 
  
'' Das SRCP ist ein TCP basiertes Internetprotokoll zur Steuerung und Programmierung von (digitalen) Modelleisenbahnanlagen. ''
 
  
----
+
== 1. Einleitung ==
  
== 1. Einführung ==
+
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 Einsatz digitaler Modellbahnausrüstung ist bislang sehr stark von der eingesetzten Hardware geprägt. Es gibt eine Übereinkunft zwischen einigen Herstellern, um auf der Ebene der Bauelemente gegenseitige Einsetzbarkeit zu erreichen. Diese Übereinkunft ist jedoch nicht allgemein akzeptiert. Eine gemeinsame Steuersprache existiert nicht, jedes System benutzt seine eigene.
+
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.
  
Um dem Modellbahner leistungsfähige Programme bereitstellen zu können, muß die Software deshalb für alle derzeit eingesetzten Digitalsysteme extra angepaßt und getestet werden.
+
Der Server kann über ein Zeitgebermodul verfügen, das alle Clients mit einer einheitlichen Modellzeit versorgen kann.
  
Darüberhinaus ist ein Multiuserbetrieb nur eingeschränkt möglich, wenn überhaupt vorhanden.
 
  
Mit dem SRCP werden folgende gleichrangigen Ziele verfolgt:
+
=== 1.1 Konventionen ===
  
* Berücksichtigung verschiedener Digitalsysteme mit einer einheitlichen Steuersprache im Multiuserbetrieb im Netzwerk.
+
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.
* Weite Skalierfähigkeit im Bereich von spontan aufgebauter "Teppichbahn", stationärer Großanlage und Einsatz bei Modellbahntreffen, bei denen individuell gestaltete Module zusammengefügt werden.
+
* Beachten von unterschiedlichen Sicherungsstrategien; von "keine" bis "meine eigene".
+
* Software muß auch vom "interessierten Laien" erstellbar sein.
+
* Ein SRCP Server abstrahiert die Ansteuerung der Anlage. Alle Informationen werden entweder aufgrund von direkten Abfragen der Anlage, wo immer möglich, bzw. anhand der Kommandohistorie bereit gestellt.
+
  
Vorliegender Text definiert sowohl das Protokoll an sich als auch Syntax und Semantik der zu verwendenden Geräte.
+
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.
  
=== 1.1 Begriffliches ===
+
Zahlen sind Ganzzahlen. Eine Beschränkung des Wertebereiches besteht nicht generell.
  
In diesem Text werden die Konventionen entsprechend RFC 1122 in einer deutschen Übersetzung verwendet. Im einzelnen sind dies "MUSS", "SOLL", "EMPFOHLEN", "KANN" und "OPTIONAL".
+
Kommandos, die unvollständig oder offensichtlich falsch sind werden vom Server ignoriert.
  
"MUSS" (bzw. "ERFORDERLICH" bzw. die Verneinung "DARF NICHT") kennzeichnet eine zwingend einzuhaltende Vorschrift. "SOLL" und "EMPFOHLEN" stehen für eine pragmatische Empfehlung, die auch ignoriert werden darf, aber erst nach gründlicher Erwägung. "KANN" und "OPTIONAL" stehen für Eigenschaften, die man guten Gewissens weglassen kann.
 
  
 +
=== 1.2 Übertragungskanäle ===
  
 +
Ein SRCP-konformer Server stellt den Clients drei Ports zur Verfügung.
  
== 2. Überblick ==
+
# Kommandoport
 +
# Rückmeldepollport
 +
# Informationsport
  
=== 2.1 Das Große Bild ===
+
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.
  
SRCP vermittelt eine Client-Serverkommunikation zur Steuerung einer Modellbahn. Der Server ist diejenige Komponente, die mit der Anlage verbunden ist. Ein Client nimmt mit dem Server Kontakt auf, um Befehle an die Anlage zu senden und Informationen von dort zu erhalten. Der Client kann auf dem gleichen Rechner wie der Server laufen, er kann aber auch über das Internet am anderen Ende der Welt laufen. Für den Client ist das verwendete Modellbahnsystem von untergeordneter Bedeutung. Es ist Aufgabe des Servers, die Befehle des SRCP geeignet umzusetzen.
+
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.
  
Ein SRCP Server hat kein Wissen über die konkrete Anlage. Er kennt weder die Topologie noch ist er (im allgemeinen) darüber informiert, welche Ausrüstung installiert ist. Er übermittelt die Befehle "auf Verdacht". Seine Aufgabe ist es jedoch, alle verfügbaren Informationen so exakt wie nur irgend möglich zu beschaffen. Hierbei bedient er sich seines Wissens über die Möglichkeiten und Grenzen der von ihm angesteuerten Anlage. Seine Angaben sind immer als "bestes Wissen" über den Anlagenzustand anzusehen.
+
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.
  
SRCP erfüllt keine formalen Echtzeitforderungen zur Steuerung.
+
Der Server bestimmt die Portnummern. Standardportnummer für den Kommandoport ist 12345. Der Rückmeldepollport und der Informationsport sind die beiden unmittelbar folgenden Portnummern. Standardmässig ergeben sich somit folgende Portnummern:
  
 +
* Kommandoport : 12345
 +
* Rückmeldepollport: 12346
 +
* Informationsport : 12347
  
=== 2.2 SRCP Server und Central Units ===
+
Nimmt ein Client zum Kommandoport Kontakt auf, 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.
  
Ein SRCP Server SOLL genau eine Central Unit im herkömmlichen Sinn repräsentieren (Hardware oder in Software emuliert). Jede CU verfügt über mind. einen Bus zur Adressierung von Geräten über den Informationen eingelesen u/o Befehle ausgeführt werden. Wenn eine CU mehrere dieser Befehlskanäle zur Modellanlage hat, ist dies im SRCP zulässig und führt hier zu mehreren Bussen.
+
Beispiel:
  
Wenn ein SRCP-Server mehrere CU verwalten oder bereitstellen kann, so ist dies zulässig. Eine Trennung zwischen den CU erfolgt dann durch die Busnummer. Wenn an einem Rechner zwar mehrere CU angeschlossen sind, es jedoch keinen gemeinsamen SRCP Server gibt, so sind die SRCP-Server auf unterschiedlichen TCP Ports zu betreiben. Genau einer dieser Server MUSS den Standardport bereitstellen.
+
----
 +
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.3 Netzwerkverbindung ===
 
  
Das SRCP basiert auf den abgesicherten Datenübertragungstechniken des TCP. Hierbei wird ein Port belegt. Derzeit SOLL der Port 12345 benutzt werden. Eine Registrierung bei der IANA kann dies zukünftig verlagern und dem Port auch einen Namen verleihen. Der vorläufige Name ist <code>srcp 12345</code>tcp/.
 
  
 +
== 2. Allgemeine Kommandos zur Serversteuerung ==
  
=== 2.4 Lexikalische Einheiten ===
+
Kommunikationsports
  
Alle Zeichencodes werden in ihrer dezimalen Form als # gefolgt vom numerischen Wert des Zeichens beschrieben.
+
* Client -> Server: Kommandoport
 +
* Server -> Client: entfällt
  
Die gesamte Kommunikation besteht aus den Zeichen des 7Bit ASCII Zeichensatzes im Bereich #32 bis #127 (einschl. der Grenzen). Zuzüglich sind die Zeichen #9 (TAB) für Leerraum, #10 und #13 (CR, LF) für das Zeilenende zulässig. Alle weiteren Zeichen (insb. Zeichen mit einem Codewert >127) werden in eingehenden Daten ignoriert und entfernt. In ausgehenden Daten können diese als Bestandteil von Daten enthalten sein, im SRCP werden sie nicht benutzt. Die Zeichen #9 und #32 werden als Whitespace angesehen und gelten auch bei mehrfacher unmittelbarer Wiederholung (auch gemischt) als ein Whitespace.
+
Kommandos
  
Zahlen werden mindestens als vorzeichenbehaftete 32Bit Ganzzahlen verarbeitet. Dieser Wertebereich kann in Sonderfällen auch erweitert werden. Führende Nullen sind nicht signifikant. Gleitkommazahlen werden NICHT verwendet.
+
* SHUTDOWN : Der Server beendet sich
 +
* LOGOUT : Dem Server wird angzeigt, dass sich ein Client ausloggt
 +
* RESET : Der Server re-initialisiert sich
  
 +
Folgende Kommandos sind von Clients nicht mehr zu verwenden, müssen vom Server jedoch implementiert werden
  
=== 2.5 Kommandos ===
+
* STARTVOLTAGE identisch mit SET POWER ON
 +
* STOPVOLTAGE identisch mit SET POWER OFF
  
Kommandos werden im Kommandomodus und im Handshake vom Client an den Server gesendet. Der SRCP Server bearbeitet das Kommando und generiert eine Antwort, die an den Client gesendet wird.
 
  
Kommandos bestehen aus einem Kommandowort, gefolgt von einer durch Whitespace abgetrennten Kommandoparameterliste. Das Ende eines Kommandos ist das Zeilenende. Die Fortsetzung eines Kommandos in der Folgezeile oder mehrere Kommandos in einer Zeile sind nicht zulässig. Besteht die Liste aus mehreren Elementen, so sind diese durch Whitespace zu trennen. Elemente, die Whitespace enthalten, sind nicht zulässig.
 
  
Enthält eine Parameterliste mehr Elemente als für den betreffenden Befehl spezifiziert ist, so MÜSSEN die überzähligen Elemente ignoriert, die Befehlsliste verkürzt und dann bearbeitet werden. Enthält die Parameterliste zuwenig Elemente, so ist eine Fehlermeldung zu generieren. Sind für einen Befehl mehrere Parameterlisten definiert, ist die Liste im Zweifelsfall immer zu kürzen.
+
== 3. Kommandos zur Digitalsteuerung ==
  
Das Zeilenende besteht aus dem Zeichen #10 (\n, LF). Ein vorangestelltes #13 (\r, CR) ist zulässig. Das Zeichen #13 wird ignoriert. Eine einzelne Zeile DARF NICHT inkl. des Zeilendes eine maximale Länge von '''1000''' Zeichen überschreiten. Vom Server gesendete Informationen unterliegen den gleichen Bedingungen. Das Zeichen #13 KANN unmittelbar vor dem #10 gesendet werden.
+
=== 3.1 Befehle und Gerätegruppen ===
  
Bei allen Worten wird zwischen Groß- und Kleinschreibung unterschieden. Die Kommandos und Antworten des SRCP sind immer groß geschrieben. Einzige Ausnahme sind erläuternde Texte bei den Fehlermeldungen und Informationen, die von den Geräten übermittelt werden.
+
SRCP definiert 8 generelle Befehle, die über den Kommandoport abgewickelt werden.
  
 +
; '''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.
 +
; '''TERM'''
 +
:    Falls die mit INIT getroffenen Einstellungen wieder entfernt werden sollen.
 +
; '''READ'''
 +
:    Liest einen Wert aus, Ergänzung zum WRITE
 +
; '''WRITE'''
 +
:    Setzt einen Wert vom Client und liefert eine Antwort (Quittung) zurück.
 +
; '''VERIFY'''
 +
:    Überprüft, ob ein Wert einen bestimmten Wert hat.
  
=== 2.6 Antworten ===
+
Geräte entstammen den Gerätegruppen Lokdekoder, Schaltdekoder, Rückmeldeeinheiten und sonstigen Bereichen.
  
Ein Server MUSS auf jedes Kommando eines Clients mit einer Antwort reagieren. Diese wird auf der gleichen Verbindung an den Client gesendet. Eine Antwort SOLL einzeilig sein. Durch das Zeichen \ (Backslash, #47) unmittelbar vor dem LF (resp. dem CRLF) wird signalisiert, das die Antwort eine weitere Zeile umfaßt. In diesem Fall ist die Zeichenfolge \LF (resp. \CRLF) dem Whitespace gleichzusetzen. Eine Antwort kann so auf beliebig viele Zeilen verteilt werden. Eine einzelne Zeile DARF inkl. des Zeilenendes eine maximale Länge von '''1000''' Zeichen NICHT überschreiten.
+
Über Parameter wird festgelegt, auf welche Gerätegruppe sich ein Befehl bezieht. Der erste Parameter legt immer die Gerätegruppe fest:
  
Eine Antwort ist entweder eine Eingangsbestätigung eines Kommandos (Quittung), eine Fehlermeldung oder das Ergebnis eines Kommandos. Wenn die Antwort eine Fehlermeldung ist, DARF das Kommando NICHT ausgeführt werden.
+
Die Befehle WRITE, VERIFY und READ sind für die Verwendung von Programmierinterfaces (Dekoder) vorgesehen.
  
Eine Antwort ist mit dem wirksamen Zeilenende abgeschlossen. Das Übermitteln von mehr als einer Antwort in einer Zeile ist nicht zulässig.
+
; '''GL'''
 +
:    Lok- und Funktionsdekoder (generic loco)
 +
; '''GA'''
 +
:    Schaltdekoder (generic accessory)
 +
; '''FB'''
 +
:    Rückmeldeeinheit (feedback)
 +
; '''TIME'''
 +
:    Zeitnormal
 +
; '''POWER'''
 +
:    Energieversorgung der Modellanlage
  
Nachdem ein Server die Antwort gesendet hat, bearbeitet er das nächste Kommando. Kommandos werden so in einer wechselseitigen Folge von Befehlen und deren Reaktion durch eine streng wechselseitige Kommunikation zwischen Client und Server abgewickelt. Der Server MUSS die Kommandos in der zeitlichen Reihenfolge des Eintreffens verarbeiten.
+
Anwendbarkeit der Befehle auf Gerätegruppen:
  
Ist das Ergebnis eines Kommandos aufgrund einer Kommunikation mit angeschlossenen Modellbahnelementen ermittelbar, so SOLL diese Möglichkeit benutzt werden. Stehen für eine Anfrage keine ausreichend abgesicherten Ergebnisse bereit, so ist die Antwort <code>416 ERROR no data</code>.
+
----
  
 +
        |  SET  GET  WAIT  INIT TERM
 +
      ---+----------------------------
 +
        |
 +
      GL |  x    x    -    -    -
 +
        |
 +
      GA |  x    x    -    -    -
 +
        |
 +
      FB |  -    x    x    x    -
 +
        |
 +
    TIME |  x    x    x    x    -
 +
        |
 +
  POWER |  x    x    -    -    -
  
 +
----
  
== 3. Serverzustand ==
+
Bei den Befehlen GET und 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:
  
Ein SRCP Server befindet sich gegenüber dem Client immer in einem von 3 möglichen Zuständen: Handshake, Kommandomodus oder Infomodus.
+
----
 +
  INFO <error code> \n
 +
----
  
Mit der Verbindungsaufnahme wird der Handshakemodus aktiviert. In diesem werden von dem Client die weiteren Betriebsparameter festgelegt. Aus dem Handshakemodus wechselt die Verbindung auf Anforderung des Clients entweder in den Kommandomodus oder den Infomodus. Aus allen drei Modi kann die Verbindung jederzeit geschlossen werden.
+
Als "error code" muß eine negative Zahl übergeben werden. Folgende Konventionen gelten:
  
<!--blockquote><code-->
+
INFO -1 ==> Befehl wird nicht unterstützt (not supported)
  
+
INFO -2 ==> Keine Information vorhanden (no data)
                              open
+
                                |
+
                                V
+
                          +-----------+
+
                          | Handshake |
+
                          +-----------+
+
                                |
+
        +----------------------+----------------------+
+
        |                      |                      |
+
        V                      |                      V
+
  +-----------+                |              +-----------+
+
  | Kommando- |                |              | Infomodus |
+
  | modus    |                |              +-----------+
+
  +-----------+                |                      |
+
        |                      |                      |
+
        V                      V                      V
+
      close                  close                  close
+
  
<!--/code></blockquote-->
+
INFO -3 ==> Zeitlimit überschritten (vgl. WAIT) (timeout)
  
  
 +
=== 3.2 Weitere Befehlsparameter ===
  
== 4. Kommandos ==
+
Die weiteren Befehlsparameter legen genau fest, welches konkrete Gerät und welche Eigenschaften beeinflußt oder abgefragt werden sollen.
  
Im weiteren werden die SRCP Kommandos und ihre jeweiligen Antworten detailiert beschrieben. Sie müssen alle von einem SRCP Server implementiert werden.
 
  
Kommandos werden ausschließlich während des Handshakes und im Kommandomodus abgewickelt. Im Infomodus sind sie nicht zulässig und MÜSSEN ignoriert werden.
+
==== Befehlsparameter des Befehls SET ====
  
Kommandos MÜSSEN in der Reihenfolge ihres Eintreffens vom Server abgearbeitet werden. Insbesondere betrifft dies die Reihenfolge bei der Übermittlung an Anlagenbestandteile.
+
<a name="SET GL"></a>
 +
===== Gerätegruppe GL =====
  
Unbekannte oder nicht erkannte Kommandos MÜSSEN mit der Meldung <code>410 ERROR unknown command</code> quittiert werden.
+
----
 +
  SET GL <protocol> <addr> <direction> <V> <V_max> <func> <nro_f> <f1> .. <fn>
 +
----
  
 +
Länge eines Kommandos (variabel): Befehlsendezeichen ist "\n"
  
=== 4.1 Verbindungsaufnahme ===
+
Kommunikationsports
  
Ein Client stellt eine TCP/IP Verbindung zum Server her. Der Server sendet einen einzeiligen Welcomestring. Daraufhin werden zwischen Client und Server die Kommunikationsparameter und der gewünschte Betriebsmodus ausgehandelt. Durch den abschließenden Befehl <code>GO</code>, der vom Client an den Server gesendet wird und von diesem bestätigt wird, startet der Betriebsmodus.
+
* Client -> Server: Kommandoport
 +
* Server -> Client: entfällt
  
Der Server MUSS intern eine Unterscheidung der verschiedenen Clientsessions vornehmen. Eine einmal vergebenes Kennzeichen DARF während der gesamten Laufzeit des Servers NICHT ein zweites Mal verwendet werden.
+
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)
 +
:*    M5: M2 erweitert nach Märklin (abs. FRU, 80 Adr, 5 Funkt., 27 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/9/13 Funkt., 28 FS)
 +
:*    N2: NMRA-DCC erweitert (abs. FRU, 7-bit-Adr., 5/9/13 Funkt., 128 FS)
 +
:*    N3: NMRA-DCC erweitert (abs. FRU, 14-bit-Adr.,5/9/13 Funkt., 28 FS)
 +
:*    N4: NMRA-DCC erweitert (abs. FRU, 14-bit-Adr., 5/9/13 Funkt., 128 FS)
 +
:*    PS: protocol by server, der Server bestimmt den Protokolltyp
 +
; '''addr'''
 +
:    Zahl >= 0
 +
; '''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)
  
==== Welcome ====
+
Beispiel
  
Nachdem eine Verbindung zwischen Client und Server hergestellt wurde, sendet der Server eine Textzeile an den Client: den Welcome. Dieser besteht aus durch das Zeichen ";" (Semikolon, #59) zu trennenden Informationen über den Server. Jede dieser Informationen ist als "Schlüssel" - "Wert" Paar anzusehen. Die Reihenfolge der Schlüssel ist nicht festgelegt. Ebenso ist es im allgemeinen zulässig, dass Schlüssel mit unterschiedlichen Werten wiederholt angegeben werden. Pro Schlüssel ist genau ein Wert zulässig. Ein Wert besteht aus einem oder mehr durch Whitespace getrennten Worten. Das Zeilenende gilt als Ende des letzten Wertes, ein Semikolon DARF fehlen.
+
----
 +
  SET GL N2 1 1 50 250 1 4 0 1 0 0
 +
----
  
Der Welcome DARF bei nicht mehr ausreichenden Ressourcen als Fehlermeldung gestaltet werden. In diesem Fall MUSS der Server nach dem Senden des Welcomes die Verbindung zum Client schließen und DARF KEINE Kommandos des Clients entgegennehmen und ausführen.
+
Umrechnung der virtuellen Geschwindigkeit in echte Fahrstufen:
  
Folgende Schlüssel MÜSSEN im normalen Welcome angegeben werden:
+
gegeben sind
  
* SRCP <Version>: Vom Server unterstützte SRCP Version. Sie MUSS exakt einer der freigegebenen Versionsnummern entsprechen. Diese Angabe MUSS genau einmal angegeben werden. Eine mehrfache Angabe ist nicht zulässig.
+
* DEC_fs (Anzahl der realen Dekoderfahrstufen, implizit bekannt)
 +
* V (virtuelle Geschwindigkeit, Argument)
 +
* V_max (maximale virtuelle Geschwindigkeit, Argument)
  
Folgende Schlüssel KÖNNEN angebeben werden, um definierte Informationen anzuzeigen. Einem Server steht es frei, weitere Schlüssel zu verwenden. Schlüssel, deren Bezeichner mit der Zeichenfolge SRCP beginnt, DÜRFEN NICHT verwendet werden, wenn sie nicht im SRCP definiert sind.
+
gesucht
  
* SRCPother <Version>: Vom Server zusätzlich unterstützt SRCP Version. Sie MUSS exakt mit einer freigegebenen Versionsnummer entsprechen und von der Angabe im Schlüssel <code>SRCP</code> verschieden sein. Ein Client SOLL diese Angabe ignorieren.
+
* V_fs (reale Fahrstufe, die der virtuellen Geschw. entspricht)
  
 +
Algorithmus: V_fs = round((V * DEC_fs)/V_max)
  
==== Handshake ====
+
''' Hinweise für Entwickler von SRCP-konformen Servern '''
  
Nachdem die Verbindung hergestellt und der Welcome gesendet wurde, wartet der Server auf ein Kommando des Clients. Dieses führt der Server aus und generiert eine einzeilige Antwort, die an den Client gesendet wird. Im Anschluß daran wartet der Server auf das nächste Kommando. Auf diese Weise werden wechselseitig Informationen und Kommandos ausgetauscht.
+
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.
  
Folgende Kommandos sind definiert, werden sie nicht ausgeführt, gelten die angegebenen Standardeinstellungen. Andere als die Aufgeführten sind in der Handshakephase verboten.
+
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.
  
: '''SET PROTOCOL SRCP <VERSION>''' Das gewünschte SRCP Protokoll, das benutzt werden soll, wird vereinbart. Fehlt dieses Kommando wird die SRCP Version angenommen, die im Welcome angegeben wurde. Als <VERSION> ist jede freigegebene Versionsnummer ab und einschließlich 0.8 gültig. Der Server sendet entweder ein <code>201 OK PROTOCOL SRCP</code> oder eine Fehlermeldung <code>400 ERROR unsupported protocol</code> als Antwort.
+
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.
  
: '''SET CONNECTIONMODE SRCP <MODE>''' Die Art der Verbindung wird vereinbart. Zulässig sind INFO für den unidirektionalen Informationsbetrieb und COMMAND für den bidirektionalen Kommandobetrieb. Der Server sendet entweder ein <code>202 OK CONNECTIONMODE</code> oder eine Fehlermeldung <code>401 ERROR unsupported connection mode</code> an den Client. Fehlt dieses Kommando wird als Connection mode der COMMAND gesetzt.
+
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.
  
: '''GO''' Durch diesen Befehl wird die Handshakephase beendet und der jeweilige Betriebsmodus aktiviert. Der Server sendet unmittelbar vorher ein <code>200 OK GO <ID></code> an den Client. Wenn der Befehl nicht ausgeführt werden kann, so sendet der Server die Fehlermeldung <code>402 ERROR unsufficient data</code> und verbleibt im Handshakemodus. Dies ist für zukünftige Erweiterungen und das Einbetten von SRCP in andere Protokolle vorgesehen. Das Feld <ID> kennzeichnet die vom Server vergebene numerische Session-ID. Diese ist für den Server eindeutig und wird niemals, solange der Server läuft, zweimal vergeben. Sie DARF NICHT nicht identisch mit Null sein.
+
Beispiele
  
Der Handshake kann anstelle einer Antwort oder des Welcome durch die Fehlermeldung <code>500 ERROR out of ressources</code> verbunden mit einem Schließen der Verbindung abgebrochen werden. Eine weitere Kommunikation ist dann nicht mehr möglich.
+
----
 +
      (50*28)/250 = 5.7  ==> V_fs = 6
 +
      (4*28)/250  = 0.448 ==> V_fs = 1 (!!!)
 +
      (0*28)/250  = 0    ==> V_fs = 0
 +
----
  
Nach Abschluß des Handshakes können die dort vereinbarten Eigenschaften nicht mehr verändert werden und gelten für die gesamte weitere Verbindung.
 
  
Folgende Fehlermeldungen sind im Handshake zulässig:
+
<a name="SET GA"></a>
 +
===== Gerätegruppe GA =====
  
: <code>400 unsupported protocol </code> Protokoll wird nicht unterstützt.
+
----
 +
  SET GA <protocol> <acc_nr> <acc_port> <action> <delay>
 +
----
  
: <code>401 unsupported connection mode </code> Verbindungsmodus wird nicht unterstützt.
+
Länge eines Kommandos (variabel): Befehlsendezeichen ist "\n"
  
: <code>402 unsufficient data </code> Ungenügende Angaben.
+
Kommunikationsports:
  
: <code>500 out of ressources </code> Keine Ressourcen mehr frei.
+
* Client -> Server: Kommandoport
 +
* Server -> Client: entfällt
  
Um den Handshake abzubrechen ist die TCP Verbindung ohne weitere Angaben zu schließen.
+
Bedeutung der Argumente
  
 +
; '''protocol'''
 +
:
 +
:*  M: Märklin/Motorola-Format
 +
:*  N: NMRA-DCC-Format
 +
; '''acc_nr'''
 +
:    Zahl >= 0 (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").
  
=== 4.2 Kommandomodus ===
+
Belegung der Dekoderausgänge:
  
Im Kommandomodus wartet der Server auf Kommandos des Clients und führt diese aus. Im Ergebnis der Ausführung generiert der Server immer eine Antwort, die er auf dem gleichen TCP Session an den Client zurücksendet. Anschließend wird das nächste Kommando ausgeführt. Eine überlappende oder sonstig von der Reihenfolge der Kommandos abweichende Bearbeitung ist nicht zulässig. Folgende Kommandos sind definiert:
+
* 0 = Weiche abbiegen, Signal Hp0, ...
 +
* 1 = Weiche gerade, Signal Hp1, ...
  
: '''GET''' Abfrage von Werten
+
Beispiel:
  
: '''SET''' Setzen von Werten
+
----
 +
  SET GA M 0023 1 1 20
 +
----
  
: '''CHECK''' Prüft einen Befehl
 
  
: '''WAIT''' Wartet auf Werte
+
===== TIME =====
  
: '''INIT''' Initialisierung von Elementen
+
----
 +
      SET TIME <Tag> <Stunde> <Minute> <Sekunde> <fx> <fy>
 +
----
  
: '''TERM''' Beendet von mit INIT initialisierte Elemente
+
Kommunikationsports:
  
: '''RESET''' Reinitialisiert ein Element
+
* Client -> Server: Kommandoport
 +
* Server -> Client: entfällt
  
: '''VERIFY''' Überprüft die Einstellungen eines Elements
+
Bedeutung der Argumente
  
Die Antworten des Servers an den Client bestehen beginnen immer mit einem Zeitstempel, einem numerischen Antwortcode und weiteren Angaben. Der numerische Antwortcode ist in Gruppen gegliedert: 100-199 kennzeichnet Informationen und Ergebnisse, 200-299 umfaßt Quittungen die die ordnungsgemäße Weiterverarbeitung bestätigen, 400-499 Fehler bei der Abarbeitung von Kommandos, 500-599 Fehler des Servers selbst, 600-699 sind für implementierungspezifische Fehlercodes vorgesehen.
+
Die aktuelle Modellzeit und die Verzerrung gegenüber der Realzeit wird festgelegt. Bei erstmaligen Aufruf vergleichbar mit einem INIT TIME.
  
: '''1xx INFO'''<nowiki>: Informationen, Ergebnisse </nowiki>
+
; '''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
  
: '''2xx OK'''<nowiki>: Befehl wurde angenommen und zur Ausführung gebracht. Achtung: Dies ist keine Bestätigung, das der Befehl auch tatsächlich ausgeführt wurde. </nowiki>
+
Beispiel:
 
+
: '''4xx/5xx ERROR'''<nowiki>: Eine Fehlerbedingung ist aufgetreten, der Befehl wird ignoriert und nicht ausgeführt. </nowiki>
+
 
+
: '''6xx ERROR'''<nowiki>: Ein serverspezifischer Fehlerzustand ist aufgetreten. Der betreffende Befehl wird nicht ausgeführt. </nowiki>
+
 
+
Der Zeitstempel wird aus der Systemzeit des Servers generiert. Er besteht aus der Angabe der Sekunden seit dem 1.1.1970 00:00:00 ("POSIX-Sekunden") einem Punkt und den Millisekunden der laufenden Sekunde. Er gibt den Zeitpunkt an, zu dem das das Kommando abgearbeitet und die Quittierung, OK oder ERROR generiert ist. Bei einem INFO kennzeichnet der Zeitstempel den Zeitpunkt, an dem das gemeldete Ergebnis dem SRCP Server bekannt wurde, oder, sofern der Server dies ermitteln konnte, zu dem das Ereignis eingetreten ist. Wenn es sich nur um eine teilweise Aktualisierung von Parametern handelt, so ist dies der Zeitpunkt der letzten Änderung. In diesem Text wird bei allen Angaben der Zeitstempel implizit immer vorausgesetzt, aus Gründen der Übersichtlichkeit jedoch nicht angegeben, sofern es nicht zur Verdeutlichung eines Sachverhaltes notwendig ist.
+
 
+
Bei Programmstart des Servers KÖNNEN Befehle intern bereits ausgeführt werden, ohne dass ein Client diese ausdrücklich anweisen muss. In jedem Fall müssen alle Änderungen gegenüber dem in dieser Norm festgelegten Grundzustandes im INFO-Modus bereitgestellt werden.
+
 
+
Das Programmende des Servers wird durch den Befehl <code>TERM 0 SERVER</code> bewirkt. Eine Quittung (<code>200 OK</code>) erfolgt auch in diesem Fall, allerdings vor der Ausführung. Anschließend wird die Verbindung vom Server beendet (dies gilt für alle angeschlossenen Clients. Im INFO-Modus befindliche SESSIONS werden mindestens eine Sekunde vor dem Programmende über das bevorstehende Programmende informiert.
+
 
+
 
+
==== Kommandos ====
+
 
+
Gültige Kommandos MÜSSEN immer ausgeführt werden. Eine Überprüfung des Kommandos mit dem aktuellen Wissen des Servers mit dem Ziel, Kommandos zu unterdrücken, die z.B. keine Veränderung bewirken könnten, ist nicht zulässig (Optimierungsverbot).
+
 
+
Das Kommando INIT dient generell der Initialisierung und Konfiguration des angegebenen Gerätes bzw. der Gerätegruppe. Nach einem INIT befindet sich das betreffende Element im Grundzustand. Im Infomodus wird für das betreffende Element eine Meldung der Form <code> 101 INFO INIT <devicegroup> <addr></code> gesendet.
+
 
+
Durch das Kommando TERM wird die Initialisierung wieder aufgehoben und das betreffende Element in den Grundzustand versetzt. Vor einer erneuten Benutzung muß das betreffende Element neu initialisiert werden. Im Infomodus wird für das betreffende Element eine Meldung der Form <code> 101 INFO TERM <devicegroup> <addr></code> gesendet.
+
 
+
Nach einem INIT ist für alle aktiven Sessions jeglicher Schreibzugriff mittels SET oder INIT auf das betreffende Gerät unzulässig, bis ein Lesezugriff durch die Befehle GET oder VERIFY (je nach Gerätegruppe) oder ein TERM ausgeführt wurde. Dies gilt auch für die Session, die den INIT ausgeführt hat.
+
 
+
Der Befehl SET verändert bestimmte Parameter des betreffenden Elements. Durch den SET Befehl KANN das Element implizit initialisiert werden. Die Antwort auf einen SET ist im Erfolgsfall ein <code>200 OK</code>. Der Befehl CHECK entspricht in allen Aspekten dem Befehl SET, nur dass die tatsächliche Ausführung des Befehls unterdrückt wird. Zweck dieses Befehls ist die Unterstützung des Debuggings von Clients.
+
 
+
Der Befehl GET ermittelt die aktuellen Parameter. Dies umfaßt auch programmierte Parameter, die nur über ein INIT eingestellt werden können. Ergebnis ist ein <code>100 INFO</code> oder eine geeignete Fehlermeldung. Die Informationen stellen "bestes Wissen" dar. Wenn ein Server die Angaben durch Abfragen der Anlagenkomponenten ermitteln kann, so SOLL er diese abfragen. Wenn die aktuelle Situation oder das zugrundeliegende System es nicht zuläßt, so KANN er auf eigene Informationen, die z.B. aus dem letzten SET resultieren, zurückgreifen. In keinem Fall sind die Informationen als garantiert identisch mit dem tatsächlichem Anlagenzustand anzusehen.
+
 
+
Der Befehl WAIT wartet eine begrenzte Zeitspanne auf das Eintreffen eines bestimmten Musters im Zustand eines Gerätes. Dieses Warten blockiert die Clientsession. Wird diese Zeitspanne überschritten, wird eine Fehlermeldung <code>417 ERROR timeout</code> generiert. Trifft der erwartete Zustand in der angegebenen Zeit ein, wird ein <code>200 OK</code> generiert.
+
 
+
Der Befehl RESET dient dem erneuten Initialisieren eines Elements. Dieser Befehl SOLL eine verkürzte Abfolge von TERM/INIT sein. Das Ergebnis ist entweder ein <code>200 OK</code> im Erfolgsfall oder eine Fehlermeldung. Das betreffende Element MUSS sich anschließend im Grundzustand befinden.
+
 
+
Der Befehl VERIFY dient der Überprüfung, ob ein Elementzustand mit einem vorgegeben Muster übereinstimmt. Das Ergebnis ist entweder ein <code>200 OK</code> wenn dies zutrifft oder eine Fehlermeldung. Dies ist insbesondere bei programmierbaren Geräten anzuwenden, wenn die betreffenden Parameter nicht durch ein SET beeinflußbar sind.
+
 
+
 
+
==== Fehlermeldungen ====
+
 
+
Fehlermeldungen werden vom Server als Antwort auf Kommandos des Clients generiert.
+
 
+
Fehlermeldungen beginnen wie alle Antworten immer mit dem Timestamp, gefolgt von dem dem Fehlercode und der Angabe <code>ERROR</code>. Daran MUSS sich eine der in der nachfolgenden Liste angegebenen Meldungen anschließen (das Wort ERROR zwischen dem Zahlencode und der Beschreibung wurde weggelassen):
+
 
+
: <code>499 unspecified error </code> Ein Fehler ist aufgetreten, kann aber nicht näher angegeben werden. Diese Fehlermeldung SOLL vermieden werden.
+
 
+
: <code>410 unknown command </code> Unbekanntes Kommando.
+
 
+
: <code>411 unknown value </code> Unbekannter Wert.
+
 
+
: <code>412 wrong value </code> Ein Parameter ist außerhalb des zulässigen Bereichs.
+
 
+
: <code>413 temporarily prohibited </code> Befehl ist derzeit verboten.
+
 
+
: <code>414 device locked </code> Gerät ist gesperrt.
+
 
+
: <code>415 forbidden </code> Befehl ist grundsätzlich verboten.
+
 
+
: <code>416 no data </code> Keine Informationen verfügbar.
+
 
+
: <code>417 timeout </code> Ein Zeitlimit ist überschritten.
+
 
+
: <code>418 list to long </code> Die Parameterliste ist zu lang.
+
 
+
: <code>419 list to short </code> Die Parameterliste ist zu kurz.
+
 
+
: <code>420 unsupported device protocol </code> Dieses Protokoll wird nicht unterstützt.
+
 
+
: <code>421 unsupported device </code> Dieses Gerät wird auf dem angegeben Bus nicht unterstützt.
+
 
+
: <code>422 unsupported device group </code> Die Gerätegruppe ist auf dem angegebenen Bus nicht verfügbar.
+
 
+
: <code>423 unsupported operation </code> Die angeforderte Aktion wird von diesem Gerät nicht unterstützt.
+
 
+
: <code>424 device reinitialized </code> Das betreffende Gerät wurde neu initialisiert. Ein GET Befehl muß zunächst ausgeführt werden.
+
 
+
: <code>425 not supported </code> Die angegebene Gerätegruppe wird nicht unterstützt.
+
 
+
Der Einsatz weiterer Fehlermeldungen SOLL vermieden werden. Auf jeden Fall ist bei Auftreten der genannten Fehlersituationen der definierte Meldungstext zu verwenden.
+
 
+
Wenn es weitere Informationen zu dem betreffenden Fehler gibt, so können diese im Anschluß an die obige Meldung angehängt werden. Ein Client KANN diese ignorieren.
+
 
+
 
+
==== Adressierung und Parameter ====
+
 
+
Parameter sind als Liste anzugeben. Einzelne Parameter werden durch Whitespace voneinander getrennt. Die Position des Parameters innerhalb der Liste kennzeichnet seine Bedeutung (positionsbezogene Parametrierung). Dies gilt für alle Gerätegruppen. Ein einzelner Parameter DARF KEINEN Whitespace enthalten. Für einzelne Befehle können unterschiedliche Parameterlisten definiert sein, die sich anhand der Anzahl der Parameter unterscheiden und eine unterschiedliche Semantik haben.
+
 
+
Die Adressierung der Elemente einer Anlage basiert auf den folgenden Elementen: dem Bus, der Gerätegruppe und, sofern mehrere Geräte möglich sind, der Geräteadresse.
+
 
+
Ein Bus ist grundsätzlich die Abstraktion eines konkreten Hardwarekommunikationsstrangs. Ein Bus ist i.allg. durch eine Central Unit repräsentiert. Ein Bus SOLL auch genutzt werden, um parallele Adreßbereiche auf einem realen System abzubilden.
+
 
+
Ein Bus wird durch die Konfiguration eines Servers festgelegt und initialisiert. Im laufenden Betrieb ist eine Veränderung an den Bussen nur über den Reset eines Servers zulässig.
+
 
+
Ein Bus wird durch eine laufende Nummer bezeichnet, die bei Null (0) beginnt und lückenlos aufwärts gezählt wird. Bus 0 ist für den Server selbst reserviert. Darüberhinaus MUSS immer mind. ein weiterer Bus vorhanden sein, der mit einer CU verbunden ist. Hierbei ist es nicht relevant, ob die CU durch Hardware oder in Software realisiert ist.
+
 
+
Die Busnummer ist bei allen Kommandos als erster Parameter unmittelbar nach dem Kommandowort anzugeben und wird bei allen Antworten und Informationen verwendet.
+
 
+
Gerätegruppen sind Gegenstand des nachfolgenden Abschnitts
+
 
+
Zielpunkt der Adressierung sind die Geräte: De- bzw. Encoder (im weiteren wird nur von Decodern gesprochen, Encoder gelten sinngemäß). Jeder Decoder ist Element mindestens eines Busses und einer Gerätegruppe, die gleichzeitige Zugehörigkeit eines Decoders zu mehreren Bussen ist zulässig, sie SOLL jedoch vermieden werden. Wechselt die Buszugehörigheit (z.B. bei Loks), so werden die Daten nicht automatisch übernommen. Es ist Aufgabe des Clients, diesen Transfer vorzunehmen. Eine gleichzeitige Zugehörigkeit von Geräten zu unterschiedlichen Gerätegruppen ist ebenfalls zulässig.
+
 
+
Wenn auf einem Bus Geräte mit einer identischen Hardwareadresse jedoch unterschiedlichem Ansteuerungsprotokoll koexistieren, so MUSS der SRCP Server sicherstellen, das das betreffende Gerät nachvollziehbar agiert. Erforderlichenfalls sind mehrere Busse für die Unterstützung der Ansteuerung vorzusehen.
+
 
+
Bei der Angabe von Parametern sind Wildcards im allgemeinen nicht zulässig. Bei einzelnen Gerätegruppen KÖNNEN sie entsprechend der folgende Bedeutung unterstützt werden:
+
 
+
* <nowiki>* (Asterisk, #42): Alle dem Server bekannten Werte. Sind dem SRCP Server keine bekannt, wird eine Fehlermeldung </nowiki><code>416 ERROR no data</code> erzeugt.
+
* <nowiki>= (Gleichheitszeichen, #61): Dieser Wert wird nicht verändert. Kennt der SRCP Server den aktuellen Wert nicht, wird eine Fehlermeldung </nowiki><code>416 ERROR no data</code> erzeugt.
+
 
+
Für einen SRCP Server gelten alle diejenigen Geräte als bekannt, die bereits angesprochen wurden und nicht mittels TERM gelöscht wurden. Hierbei KANN auch ein Gerät im Grundzustand als bekannt gelten. Bei einigen Hardwaresystemen werden Broadcasts durch bestimmte Eigenschaften der übermittelten Daten abgebildet. Ein SRCP Server KANN diese einsetzen, um das definierte Wildcardverhalten umzusetzen. Bei Systemen, die dies nicht direkt unterstützen, MUSS der Server diese Funktion emulieren. Ein SRCP Server DARF eventuell mögliche direkte Parametrierungen dieser Art NICHT von einem Client annehmen. Dies betrifft insbesondere speziell reservierte Adressen.
+
 
+
 
+
==== Gerätegruppen ====
+
 
+
Gerätegruppen stellen Zusammenstellungen von gleichartigen Geräten dar. Folgende Gerätegruppen sind definiert:
+
 
+
: '''GL''' Generic Loco
+
 
+
: '''GA''' Generic Accessoire
+
 
+
: '''FB''' Feed Back
+
 
+
: '''SM''' Service Mode
+
 
+
: '''TIME''' Zeitnormal
+
 
+
: '''POWER''' Energieversorgung
+
 
+
: '''SERVER''' SRCP Server
+
 
+
: '''SESSION''' SRCP Clientsession
+
 
+
: '''LOCK''' Geräte, die andere Geräte sperren
+
 
+
: '''DESCRIPTION''' Geräte, die andere Geräte und Gerätegruppen beschreiben
+
 
+
Einige Gerätegruppen entsprechen Anlagenelementen. Diese werden im Fall von mehreren Implementationen per default auf den kleinsten gemeinsamen Nenner initialisiert. Eine Nutzung der weitergehenden Features erfordert eine Initialisierung, bei der hardwarenahme Informationen benötigt werden. Eine Übersicht, welche Hardware wie initialisiert werden kann (resp. muß) wird in einem separaten Dokument "SRCP Geräte" gepflegt. Die dort gemachten Angaben sind ebenso verbindlich wie das SRCP selbst.
+
 
+
Jeder SRCP Server MUSS die Gerätegruppen SERVER, SESSION und DESCRIPTION im Bus 0 unterstützen. Für jeden weiteren Bus MÜSSEN die Gerätegruppen POWER und DESCRIPTION verfügbar sein. Alle anderen Gerätegruppen sind optional. Werden sie unterstützt, MUSS dies in der DESCRIPTION des Busses angegeben werden. Eine Unterstützung der DESCRIPTION für Gerätegruppen ist optional und kann für jede Gerätegruppe separat unterstützt sein.
+
 
+
Die Gerätegruppe GA ist für Decoder vorgesehen, die unter einer Adresse einen oder mehr Ports mit jeweils zwei oder mehr möglichen Werten bereitstellen. Dies sind üblicherweise ortsfeste Anlagenelemente wie Weichen und Entkuppler. Die Gerätegruppe GL kennzeichnet Lokdecoder im Lokadreßraum der Hardware. In der Busnummer 0 sind die Gruppen GA und GL nicht zulässig.
+
 
+
Feedback Geräte FB sind Encoder, die das Auftreten eines Ereignisses auf der Anlage signalisieren. Sie haben exakt einen Eingang, der vermittels einer Adresse identifiziert wird und der über mindestens zwei unterscheidbare Zustände verfügt. Sind einzelne Encoder zu einer Gerätegruppe zusammengefaßt, so hat dies keine Auswirkungen auf die Identifikation. In der Busnummer 0 ist diese Gruppe nicht zulässig.
+
 
+
Der Service Mode SM betrifft Decoder, die im Programmiermodus betrieben werden. Hierfür KANN es erforderlich sein, das der Decoder auf einen anderen Bus versetzt werden muß (Programmiergleis) oder ein Bus für andere Befehle gesperrt wird. In diesem Bus KÖNNEN normale Steuerbefehle dann mit der Fehlermeldung <code>temporarily prohibited</code> oder <code>forbidden</code> abgewiesen werden. In der Busnummer 0 ist diese Gruppe nicht zulässig. Eine technische Realisierung kann einen direkten Durchgriff auf das benutzte Digitalsystem umfassen.
+
 
+
Das Zeitnormal TIME ist nur in der Busnummer 0 zulässig. Es dient der Bereitstellung einer einheitlichen Modellzeit. Diese wird ausgehend von einem Startzeitpunkt schneller oder langsamer als die Echtzeit aber genau wie diese monoton mit Modellsekundengenauigkeit gezählt. Im INFO Modus wird die Modellzeit zu jeder vollen Modellminute gesendet. Das Zeitnormal ist optional. Es ist nur ein Gerät in dieser Gerätegruppe zulässig.
+
 
+
Die LOCK Geräte sind Geräte, die eine Sperre über ein anderes Gerät bereitstellen. Sie sind optional. Wenn vorhanden, so MUSS der Server vor Aktionen auf den lockbaren Geräten die Lockgeräte konsultieren. Sie DÜRFEN auf einzelnen Bussen existieren, und auf anderen Bussen nicht. Es ist jedoch anzustreben, das alle Busse eines Servers mit Lockgeräten versehen sind.
+
 
+
Die DESCRIPTION Geräte können andere Geräte mit ihren Eigenschaften beschreiben. Antworten des Servers KÖNNEN mehrzeilig sein! Es wird je nach Art der Parameterliste zwischen der DESCRIPTION von Bussen und der DESCRIPTION von Gerätegruppen unterschieden.
+
 
+
POWER kennzeichnet den Zustand der Energieversorung des betreffenden Busses. POWER im Bus 0 ist nicht zulässig. Das Aktivieren der Energieversorgung in einem Bus kann implizit auch andere Busse aktivieren, dies MUSS im INFO Modus berücksichtigt werden!
+
 
+
SERVER kennzeichnet zusammen mit dem Bus 0 Aktivitäten, die den Server betreffen (insb. TERM und RESET). Eine Verwendung mit anderen Bussen ist nicht zulässig. Der SRCP Server ist einziges Element dieser Gerätegruppe.
+
 
+
SESSION kennzeichnet zusammen mit dem Bus 0 die Menge der aktiven Clientverbindungen. Eine Verwendung anderer Busse als 0 ist nicht zulässig.
+
 
+
Folgende Übersicht soll die Verteilung der Gerätegruppen und Befehle auf die Busse darstellen.
+
  
 
----
 
----
 
+
  SET TIME 1 23 55 0 1 1
            |  SET GET  WAIT  INIT TERM  RESET VERIFY
+
            | CHECK
+
          ---+------------------------------------------
+
            |
+
          GL |  1..  1..  --  1..  1..  1..  --
+
            |
+
          SM |  1..  1..  --  1..  1..  1..  1..
+
            |
+
          GA |  1..  1..  --  1..  1..  1..  --
+
            |
+
          FB |  1..  1..  1..  1..  1..  1..  --
+
            |
+
        TIME |  0   0    0    0    0    0    --
+
            |
+
      POWER |  1..  1..  1..  1..  1..  --    --
+
            |
+
      SERVER |  --  0    --  --  0    0    --
+
            |
+
    SESSION |  --  0    --  --  0    --    --
+
            |
+
        LOCK |  0..  0..  --  0..  0..  --    --
+
            |
+
DESCRIPTION |  --  0..  --  --  --    --    --
+
 
+
 
----
 
----
  
Die mit <code>--</code> gekennzeichneten Einträge markieren Kombinationen, die NICHT verwendet werden DÜRFEN.
+
setzt auf den Abend des ersten Tages mit Modellzeit gleich Realzeit. (vgl. [[#INIT TIME | INIT TIME]])
  
  
===== Gerätegruppe FB: Feedback =====
+
<a name="SET POWER"></a>
 
+
===== POWER =====
Rückmelder haben eine Adresse, unter der genau ein aktueller Wert erfaßt ist. Im einfachsten Fall ist ein Rückmelder ein binäres Signal. Ein vom Server beeinflußbarer Grundzustand ist nicht vorhanden.
+
 
+
<big>''' INIT '''</big>
+
  
 
----
 
----
  INIT <bus> FB <optionale Parameter zur Initalisierung>
+
      SET POWER <state> <freetext>
 
----
 
----
  
Ein bereits existierender Rückmelder wird initialisiert. Die hierfür erforderlichen und im Befehl angegebenen Parameter (Wie I/O Adressen, Portnamen usw.) MÜSSEN vom Server vor Gebrauch überprüft werden, um Schäden vorzubeugen. Ein SRCP Server SOLL diese Befehle nicht anhand von Clientbefehlen, sondern anhand einer Konfiguration bei Programmstart ausführen.
+
Kommunikationsports:
  
Beispiel:
+
* Client -> Server: Kommandoport
----
+
* Server -> Client: entfällt
    INIT 1 FB S88 /dev/lp0 4
+
----
+
  
Initialisiert den Bus 1 als Rückmeldebus. Die eingesetzten Rückmelder sind S88 Module (4 Stück) am Parallelport /dev/lp0. Folgende Rückmeldesysteme sind definiert:
+
Bedeutung der Argumente
  
* '''S88''' <Gerätename> <Anzahl_Module> <poll_frequency>
+
; '''State'''
* '''4S88''' <Gerätename> <Anzahl_Module> <poll_frequency>
+
:
* '''I8255''' <IO_Adresse> <poll_frequency>
+
:;  '''ON'''
 +
::      Schaltet die Energieversorgung ein
 +
:;  '''OFF'''
 +
::      Schaltet die Energieversorgung ab
 +
; '''Freetext'''
 +
:    Ein optionaler Text mit maximal 100 Zeichen, der an das INFO Packet angehängt wird und nähere Informationen geben kann. Es werden ausdrücklich keine Vorgaben über den Inhalt gemacht.
  
Die FB Systeme S88, 4S88 und I8255 werden als Bus initialisiert, eine separate Initialisierung der einzelnen Ports ist werder erforderlich noch erlaubt.
 
  
<big>''' GET '''</big>
+
==== Befehlsparameter des Befehls GET ====
----
+
  GET <bus> FB <addr>
+
----
+
  
Liefert den aktuellen Wert des Rückmelders. Bei der Adresse ist der Einsatz des Wildcards "*" zulässig. Dann werden alle Adressen gemeldet, deren Zustand von Null verschiedenen ist. Die Antwort ist ein INFO für jede angeforderte Adresse.
+
<a name="GET GL"></a>
 +
===== Gerätegruppe GL =====
  
<big>''' TERM '''</big>
 
 
----
 
----
   TERM <bus> FB
+
   GET GL <protocol> <addr>
 
----
 
----
  
Mit dem TERM wird der betreffende Bus aus der laufenden Kommunikation herausgenommen, ohne ihn aus der Liste der vorhandenen Busse löschen. Die angeschlossene Hardware SOLL hiermit abgeschaltet werden, wenn alle Busse, die darauf zugreifen, terminiert wurden. Laufende WAIT MÜSSEN mit timeout beendet werden, sofern die WAIT Bedingung nicht erfüllt ist.
+
Länge eines Kommandos (variabel): Befehlsendezeichen ist "\n"
  
<big>''' WAIT '''</big>
+
Kommunikationsports:
----
+
  WAIT <bus> FB <addr> <value> <timeout>
+
----
+
  
Warten bis zu <timeout> Sekunden (Echtzeit) auf das Erreichen des spezifizierten Wertes. Wenn das Wert bereits vorliegt, so wird nicht gewartet, sondern dessen Eintreten sofort gemeldet.
+
* Client -> Server: Kommandoport
 +
* Server -> Client: Kommandoport
  
<big>''' INFO '''</big>
+
Bedeutung der Argumente: siehe [[#SET GL | SET GL]]
----
+
  INFO <bus> FB <addr> <value>
+
----
+
  
Der aktuelle Wert des Rückmelders.
+
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:
  
 
===== Gerätegruppe GA: Generic Accessoire =====
 
 
Ein Generic Accessoire kennzeichnet allgemein einen Decoder, der unter einer Adresse einen oder mehrere Ausgänge (Ports) bedienen kann. Dies sind häufig Weichendecoder oder Signaldecoder, die als Impulsdecoder arbeiten. Hier ist zu beachten, dass es Einschränkungen bei der gleichzeitigen Aktivierung und/oder Deaktivierung von Ausgängen geben kann. Diese sind ggf. der Beschreibung des Decoders zu entnehmen. Ein SRCP Server kann diese Eigenschaften nicht immer selbst erkennen und melden!
 
 
Der Grundzustand eines Gerätes ist durch Null auf allen Ports gekennzeichnet.
 
 
<big>''' INIT '''</big>
 
 
----
 
----
  INIT <bus> GA <addr> <protocol> <optional weitere Parameter>
+
  INFO GL <protocol> <addr> <direction> <V> <V_max> <func> <nro_f> <f1> .. <fn>
 
----
 
----
  
Mit diesem Befehl wird ein GA im Server initialisiert. Folgende Parameter sind zulässig:
+
(vgl. [[#SET GL | SET GL]])
  
: '''addr''' Adresse aus dem Protokollbereich.
+
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. Kommandos zur Digitalsteuerung | Digitalsteuerung]]).
  
: '''Protocol'''
 
:* M Märklin/Motorola-Format: addr 1..256, port: 0,1, value: 0,1
 
:* N NMRA-DCC-Format: addr 1..511, port: 0,1, value: 0,1
 
:* P Protocol by Server: Der Server bestimmt den Protokolltyp. addr, port und value nicht beschränkt. Dies ist der Default.
 
  
<big>''' SET '''</big>
+
<a name="GET GA"></a>
 +
===== Gerätegruppe GA =====
 +
 
 
----
 
----
  SET <bus> GA <addr> <port> <value> <delay>
+
  GET GA <protocol> <acc_nr> <acc_port>
 
----
 
----
  
Der Port <port> des Decoders mit der Adresse <addr> wird für <delay> Millisekunden auf den Wert <value> gesetzt. Nach Ablauf der Zeit wird vom Server automatisch der Wert 0 an den Decoder gesendet. Ist die Verzögerung -1, unterbleibt die automatische Deaktivierung und der Ausgang bleibt solange aktiv, bis er von einem weiteren SET Befehl deaktiviert wird. Ein SRCP Server KANN während dieser Zeit kurzzeitige De- und Reaktivierung des Ports ausführen. Dies ist ggf. ein Erfordernis der Hardware, die ein Überschreiten bestimmter maximaler Einschaltdauern nicht zuläßt. Ein Delay von 0 ist nicht zulässig.
+
Länge eines Kommandos (variabel): Befehlsendezeichen ist "\n"
 
+
Bedeutung der Argumente
+
  
: '''addr''' Zahl > 0, oder das Zeichen * (Asterisk, #42) (Nummer der Weiche/des Signals oder alle dem SRCP Server bekannten Geräte)
+
Kommunikationsports:
  
: '''port''' 0, 1, 2,... (Ausgang des Decoders), wird ein nicht unterstützter Port angegeben, wird eine Fehlermeldung <code>412 ERROR wrong value</code> erzeugt.
+
* Client -> Server: Kommandoport
 +
* Server -> Client: Kommandoport
  
: '''value''' 0, 1, 2, ... (0 => deaktiviert, >0 => aktiviert), wird ein ungültiger Wert angegeben, wird eine Fehlermeldung <code>412 ERROR wrong value</code> erzeugt.
+
Bedeutung der Argumente: siehe [[#SET GA | SET GA]]
  
: '''delay''' Wert in Millisekunden (1000stel-Sekunden). Gibt an, nach welcher Zeit der Server einen aktivierten Port automatisch deaktivieren (d.h. auf 0 setzen) soll. Wird "-1" als delay übergeben, dann wird der Port nicht automatisch deaktiviert. Ist action=0 (Deaktivierung) wird delay ignoriert, muß aber angegeben werden (sinnvoller Wert: "-1"). Ein Port gilt als aktiv, wenn sein Status ungleich Null ist. Ein Delay von 0 ist nicht zulässig, es wird eine Fehlermeldung <code>412 ERROR wrong value</code> erzeugt.
+
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:
  
<big>''' GET '''</big>
 
 
----
 
----
   GET <bus> GA <addr> <port>
+
   INFO GA <protocol> <acc_nr> <acc_port> <state>
 
----
 
----
  
Der Server sendet an den Client alle verfügbare Info über den aktuellen Zustand zu dem mit <addr> spezifizierten Schaltdecoder. Als Adresse ist das "*" zulässig. Dann werden alle dem Server bekannten Decoder gemeldet.
+
(vgl. [[#SET GA | SET GA]], ersetze <state> durch <action>)
  
<big>''' INFO '''</big>
+
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. Kommandos zur Digitalsteuerung | Digitalsteuerung]]).
----
+
  INFO <bus> GA <addr> <port> <value>
+
----
+
 
+
<code>value </code> ist hierbei der aktuelle Wert des Ports.
+
 
+
 
+
===== Gerätegruppe GL: Generic Loco =====
+
  
Ein Generic Loco kennzeichnet allgemein alle Lokdecoder.
 
  
Der Grundzustand ist Null bei allen Parametern.
+
<a name="GET FB"></a>
 +
===== Gerätegruppe FB =====
  
<big>''' INIT '''</big>
 
 
----
 
----
   INIT <bus> GL <addr> <protocol> <optional weitere Parameter>
+
   GET FB <module_type> <portnr>
 
----
 
----
  
Mit dem INIT wird die Art des Datentransfers und grundlegende Eigenschaften des Decoders dem Server bekannt gemacht. Eine Veränderung der Decodereigenschaften bei programmierbaren Decodern ist nicht zulässig (hierfür ist die Gerätegruppe SM heranzuziehen), Ausnahme: Wenn sich Decoder durch eine Sequenz "normaler" Steuerbefehle programmieren lassen, so DARF NICHT die SM Gerätegruppe benutzt werden.
+
Länge eines Kommandos (variabel): Befehlsendezeichen ist "\n"
  
Zulässige Werte der Parameter
+
Kommunikationsports:
  
: '''protocol'''
+
* Client -> Server: Kommandoport
nachfolgend sind die derzeit gültigen Werte definiert.
+
* Server -> Client: Kommandoport
:* <code>A </code> Analogbetrieb addr: 0, keine f (Zusatzinfo: keine Fahrstufen)
+
:* <code>F </code> Reserviert für native Fleischmann
+
:* <code>L </code> Reserviert für Loconet
+
:* <code>M </code> Reserviert für Märklin/Motorola <blockquote><code> <Protokollversion> <Dekoderfahrstufen> <Anzahl_Dekoderfunktionen> </code></blockquote> Protokollversion ist 1 für das "alte" MM Protokoll (z.B. Delta Dekoder), 2 für das "neue" Protokoll (zusätzlich 4 Funktionen) Die Dekoderfahrstufen entsprechen denen, die der Dekoder tatsächlich unterstützt (ggf. unter Beachtung der Anzahl der Dekoderfunktionen). Die Anzahl der Dekoderfunktionen ergibt sich aus der Anzahl der ansprechbaren Funktionen, ohne Beachtung einer evt. nicht genutzten Funktion. Sie sind immer fortlaufend ohne Unterbrechung anzusehen.
+
:* <code>N </code> Reserviert für NMRA/DCC: <blockquote><code> <Protokollversion> <Dekoderfahrstufen> <Anzahl_Dekoderfunktionen> </code></blockquote> Protokollversion ist 1 für das "kurze" Adreßformat, 2 für das "lange" Adreßformat. Die Ausführungen zu den Dekoderfahrstufen und Anzahl Funktionen gelten wie bei <code>M</code>.
+
:* <code>P </code> protocol by server: beliebige Adresse, beliebige Anzahl Funktionen (Zusatzinfo: beliebige Anzahl Fahrstufen). Der Server bestimmt den Typ des Decoders selbständig.
+
:* <code>S </code> Reserviert für native Selectrix
+
:* <code>Z </code> Reserviert für native Zimo
+
  
Ein Server KANN ein oder mehr dieser Angaben nicht unterstützen. Nicht angeführte Angaben DÜRFEN NICHT verwendet werden. Diese Angaben werden in zukünftigen Revisionen des SRCP konkretisiert.
+
Bedeutung der Argumente
  
Hinweis: Bei einigen Protokollen existieren mehrere Bereiche für Funktionen, üblich sind eine fahrtrichtungsabhängige und mehrere von der Fahrtrichtung unabhängige. Ein Server MUSS die erstere als erste Funktion, die weiteren als zweite, dritte... bereitstellen.
+
; '''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
  
<big>''' GET '''</big>
+
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:
----
+
  GET <bus> GL <addr>
+
----
+
 
+
Die Antwort ist eine vollständige INFO GL Zeile.
+
  
<big>''' INFO '''</big>
 
 
----
 
----
   SET <bus> GL <addr> <drivemode> <V> <V_max> <f1> .. <fn>
+
   INFO FB <module_type> <portnr> <state>
 
----
 
----
  
Der Decoder wird mit den angegeben Werten belegt. Der Grundzustand ist durch den Wert 0 für alle Parameter (außer der Adresse) gekennzeichnet. Die Bedeutung der Parameter ist allg. folgende:
+
Wobei state entweder "0" oder "1" sein darf.
  
: '''addr''' Zahl >= 0 oder * (Asterisk, #42), die am Decoder eingestellte Adresse, entsprechend dem Protocol können Einschränkungen gelten. Der * kennzeichnet die Broadcastadresse, bei der alle dem SRCP Server bekannten Loks auf die angegebenen Werte gesetzt werden. Wenn eine Adresse eine Sonderfunktion im zugrundeliegenden System hat (Broadcast), so DARF sie NICHT eingesetzt werden und MUSS mit einer Fehlermeldung abgewiesen werden.
+
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.
  
: '''drivemode'''
+
Beispiel
:* <code><nowiki>= </nowiki></code> unverändert
+
:* <code>0 </code> rückwärts
+
:* <code>1 </code> vorwärts
+
:* <code>2 </code> Nothalt
+
Wird ein nicht unterstützter Fahrmodus angegeben, wird eine Fehlermeldung <code>412 ERROR wrong value</code> erzeugt.
+
  
: '''V, V_max''' Fahrstufe und maximale Fahrstufe, 0 ist Stillstand, ein Wert >0 bedeutet Bewegung der Lok (d.h. eine reale Fahrstufe >0), V<0 ist nicht zulässig ebenso V>V_max. Die Geschwindigkeit steigt von 0 bis V_max, so daß eine Geschwindigkeit V2>V1 bewirkt, das die Lok bei V2 nicht langsamer als bei V1 fährt. In allen Fehlersituationen wird eine Fehlermeldung <code>412 ERROR wrong value</code> erzeugt. Der Einsatz des Wildcard <code><nowiki>=</nowiki></code> ist nur bei beiden Parametern gleichzeitig zulässig.
 
 
: '''f1 .. fn''' = (= unverändert), 0 (= aus), 1 (= an), F1 ist ggf. Fahrtrichtungsabhängig. Es ist zulässig, andere als die Werte =, 0 oder 1 anzugeben, der SRCP Server weist konkret nicht zulässige Werte mit einer Fehlermeldung <code>412 ERROR wrong value</code> zurück.
 
 
Ein Beispiel:
 
 
----
 
----
   INIT 1 GL 1 N 1 128 5
+
   INFO FB M6051 * 1100110010101111
  SET 1 GL 1 1 4 100 1 0 1 0 =
+
 
----
 
----
  
Die über den Bus 1 adressierte Lok 1 (NMRA Decoder, 128 Dekoderfahrstufen, 1+4 Funktionen) fährt mit Speedstep 4 (von 100 möglichen) vorwärts. Von den 5 Funktionen sind FUNKTION und F2 aktiviert. Der Wert von F4 wird anhand des Wissens des Servers über den aktuellen Zustand gesetzt.
+
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 Befehle und Ger&auml;tegruppen | Befehle und Gerätegruppen]]).
  
<big>''' INFO '''</big>
 
  
Ein INFO umfaßt sowohl die Reaktion des GET, als auch die Ausgaben im Infomodus als Reaktion auf die SET und INIT Befehle. Er MUSS alle aktuellen Werte umfassen, unabhängig ob sie aktuell geändert wurden oder nicht. Das Format ist wie folgt:
+
<a name="GET TIME"></a>
----
+
===== Zeit =====
  INFO <bus> GL <addr> <drivemode> <V> <V_max> <f1> .. <fn>
+
----
+
  
Hierbei ist der Parameter <code>V</code> nicht der vom Client übermittelte Speedstep, sondern der vom Server an die Lok gesendete echte Fahrstufe unter Auslassung eventueller Sonderbedeutungen: Die Fahrstufe 0 kennzeichnet Stillstand, die Fahrstufen von 1 bis einschließlich V_max kennzeichnen die Bewegung der Lok im angegebenen <code><drivemode></code>.
 
 
<big>''' TERM '''</big>
 
 
----
 
----
   TERM <bus> GL <addr>
+
   GET TIME
 
----
 
----
  
Setzt die Lok in den Grundzustand und entfernt die Lok aus dem Wissenbestand des Servers.
+
Kommunikationsports:
 
+
 
+
===== Gerätegruppe SM: Servicemode =====
+
  
Die Geräte des Servicemode werden für die permanente Veränderung von Geräten bereitgestellt. Sie sind optionaler Bestandteil. Werden sie nicht unterstützt, so MUSS eine Fehlermeldung <code>425 ERROR not supported</code> generiert werden. Sie sind für den Einsatz zur Decoderprogrammierung vorgesehen
+
* Client -> Server: Kommandoport
 +
* Server -> Client: Kommandoport
  
Ein Grundzustand ist nicht definiert.
+
Liefert die aktuelle Modellzeit und die Verzerrungsfaktoren als INFO-Zeile
  
<big>''' INIT '''</big>
 
 
----
 
----
  INIT <bus> SM <protocol>
+
  INFO TIME <Tag> <Stunde> <Minute> <Sekunde <fx> <fy>
 
----
 
----
  
Initialisiert den betreffenden Bus für die Programmierung von Decodern im angegebenen Protokoll. Als Folge hiervon KANN der Bus für andere Aufgaben gesperrt sein.
+
Sollte keine Modellzeit definiert sein, so muß der Server dies mit "INFO -2" (no data) an den Client senden (vgl. [[#3.1 Befehle und Ger&auml;tegruppen | Befehle und Gerätegruppen]]).
  
Zulässige Protokolle sind
 
  
: '''NMRA'''<nowiki>: Decoder nach NMRA Standard. </nowiki>
+
===== Power =====
  
<big>''' SET '''</big>
 
 
----
 
----
   SET <bus> SM <decoderaddress> <type> <1 or more values>
+
   GET POWER
 
----
 
----
  
Folgende <more values> sind definiert.
+
Kommunikationsports:
  
: '''type'''
+
* Client -> Server: Kommandoport
:* '''CV'''<nowiki>: Configuration Variable: der erste Parameter der Restliste kennzeichnet die Adresse einer NMRA Decodervariablen (<typeaddress>). Diese erhält den mit dem zweiten Parameter <value> beschriebenen Wert. Einschränkungen im Wertebereich der Parameter ergeben sich aus der Spezifikation des Decoders. Ein Server kann Decoderspezifische Wertebereiche nicht überprüfen.</nowiki>
+
* Server -> Client: Kommandoport
:* '''CVBIT'''<nowiki>: Configuration Variable Bit: 3 Parameter: <typeadress> <bit> <value> Das Bit <bit> der Adresse <typeadress> wird auf den Wert <value> gesetzt. <bit> ist von 0 bis 7, <value> 0 oder 1.</nowiki>
+
:* '''REG'''<nowiki>: Register</nowiki>
+
  
<big>''' GET '''</big>
+
Ermittelt den aktuellen Zustand der Energieversorgung. Als Antwort erscheint
  
Der GET MUSS den Decoder direkt befragen. Eine Antwort DARF NICHT anhand von servergespeicherten Informationen ermittelt werden. Der Einsatz von Wildcards ist nicht zulässig.
 
 
----
 
----
  GET <bus> SM <decoderaddress> <type> <1 or more values>
+
INFO POWER [ON|OFF] <Message_Text>
 
----
 
----
  
Die Bedeutung der Parameter ist wie bei SET. Das Ergebnis ist ein INFO, das den betreffenden Wert widergibt. Ein GET hat die Fehlermeldung <code>416 ERROR no data</code> als Ergebnis, wenn es keine Möglichkeit gibt, den Decoder auszulesen.
+
Messagetext ist hierbei der zuletzt gesetzte Wert (vgl. [[#SET POWER | SET POWER]])
  
<big>''' VERIFY '''</big>
 
----
 
  VERIFY <bus> SM <decoderaddress> <type> <1 or more values>
 
----
 
  
Wie bei GET MUSS der Decoder direkt befragt werden.
+
==== Befehlsparameter des Befehls WAIT ====
  
Die Bedeutung der Parameter ist wie bei SET. Das Ergebnis ist entweder ein <code>200 OK</code>, wenn der Parameter im Decoder dem angegebenen entspricht oder die Fehlermeldung <code>412 ERROR wrong value</code>.
+
===== Gerätegruppe FB =====
  
<big>''' TERM '''</big>
 
 
----
 
----
   TERM <bus> SM
+
   WAIT FB <module_type> <portnr> <value> <timeout>
 
----
 
----
  
Beendet den mit INIT begonnenen Programmiermodus auf dem betreffenden Bus. Eventuell unvollständige Programmierzyklen sind geeignet zu beenden.
+
Länge eines Kommandos (variabel): Befehlsendezeichen ist "\n"
  
<big>''' INFO '''</big>
+
Kommunikationsports:
----
+
  INFO <bus> SM <decoderaddress> <type> <1 or more values>
+
----
+
  
Die Bedeutung der Parameter ist wie bei SET.
+
* Client -> Server: Kommandoport
 +
* Server -> Client: Kommandoport
  
 +
Wartet, bis der angegebene Port 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.
  
===== Gerätegruppe LOCK: Schreibsperren =====
+
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.
  
Mit Locks kann ein Client ein Gerät exklusiv für die betreffende Session sperren. Dies gilt auch für physisch identische Geräte, die in unterschiedlichen Gerätegruppen ansprechbar sind: Ein LOCK auf einen Decoder in der Gerätegruppe GL verhindert auch Schreibzugriff auf den gleichen Decoder in der Geräte SM! Anderen Sessions, auch des gleichen Clients, wird beim schreibenden Zugriff (SET, INIT, TERM) die Fehlermeldung <code>414 ERROR device locked</code> gemeldet. Die Ausführung dieser Befehle ist dann nur dem den Lock haltenden Clientsession gestattet. Lesezugriffe (GET) werden weiterhin von allen Clients akzeptiert und funktionieren ohne Einschränkungen. Ein Lock auf ein Gerät der LOCK-Gerätegruppe, auch eines anderen Busses, ist nicht zulässig. Ebensowenig kann ein Bus als ganzes gesperrt werden.
 
  
Der Grundzustand ist "nicht gelockt".
+
===== TIME =====
  
Für die Geräte der Gerätegruppe GL ist für alle Clients IMMER der Notstop zulässig. Ein Lock durch eine andere Session hat in diesem Fall keine Wirkung. Hierbei MUSS die Lok nur den Notstop ausführen, alle anderen Parameter, auch wenn sie angegeben sein sollten, MÜSSEN unverändert bleiben. Insbesondere bleibt der LOCK erhalten.
 
 
Ein Lock wird automatisch mit dem Ende der Clientverbindung und dem Ablaufen der Sperrzeit aufgehoben.
 
 
Die Locks sind optionaler Bestandteil. Werden sie nicht unterstützt, so MUSS eine Fehlermeldung <code>425 ERROR not supported</code> generiert werden.
 
 
<big>''' SET '''</big>
 
 
----
 
----
   SET <bus> LOCK  <devicegroup> <addr> <duration>
+
   WAIT TIME <Tag> <Stunde> <Minute> <Sekunde>
 
----
 
----
  
Setzt einen Lock auf das adressierte Gerät. Zu beachten ist, das die LOCK-Geräte keine eigene Adresse haben, sie werden ausschließlich über das von ihnen gesperrte Gerät identifiziert.
+
Kommunikationsports:
  
Andere Clients können noch lesend und nur in sicherheitsrelevanten Bereichen schreibend zugreifen. Der LOCK wird für <duration> Sekunden gehalten. Nach Ablauf dieser Zeitspanne wird der LOCK automatisch vom Server beendet. Die Zeit beginnt mit dem letzten SET Befehl. Eine Dauer von 0 bedeutet eine unbefristete Spanne. Ein wiederholtes Absetzen des SET Befehls startet den Zeitgeber jeweils neu.
+
* Client -> Server: Kommandoport
 +
* Server -> Client: Kommandoport
  
<big>''' TERM '''</big>
+
Wartet, bis die Modellzeit den angegebenen Zeitpunkt mind. erreicht hat und liefert einen INFO-String mit der aktuellen Modellzeit.
----
+
  TERM <bus> LOCK <devicegroup> <addr>
+
----
+
  
Ein Lock wird auf das Gerät <devicegroup> <addr> des Busses <bus> entfernt.
+
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 durch "INFO -1" an den anfordernden Client ignoriert.
  
<big>''' INFO '''</big>
 
----
 
  INFO <bus> LOCK <devicegroup> <addr> <Duration> <sessionid>
 
----
 
  
Die SessionID ist hierbei die eindeutige Kennung der Session, die den Lock hält.
+
==== Befehlsparameter des Befehls INIT ====
 +
 
 +
===== Feedback Module =====
  
<big>''' GET '''</big>
 
 
----
 
----
   GET <bus> LOCK <devicegroup> <addr>
+
   INIT FB <module_type>
 
----
 
----
  
Diesr Befehl liefern den aktuellen Lockstatus eines Gerätes als INFO-Zeile. Ist das angegebene Gerät nicht gelockt, die SessionID 0 angegeben.
+
Kommunikationsports:
  
 +
* Client -> Server: Kommandoport
 +
* Server -> Client: entfällt
  
===== Gerätegruppe POWER: Energieversorgung =====
+
Initialisiert die entsprechenden Rückmeldeeinheiten. Keine Nachricht an den Client.
  
Die Energieversorgung kann für jeden Bus getrennt geschaltet werden. Die Energieversorgung im Bus 0 betrifft alle vorhandenen Busse identisch, ein POWER ON im Bus 0 aktiviert also die Energieversorung in allen Bussen gleichermaßen. Alle Veränderungen MÜSSEN im Infomodus gemeldet werden.
 
  
Der Grundzustand ist OFF.
+
<a name="INIT TIME"></a>
 +
===== TIME =====
  
Wenn der Server von Veränderungen der Energieversorgung durch die Anlage selbst erfährt (z.b. Kurzschlußerkennung), so ist die gleichbedeutend mit entsprechenden einem Befehl und MUSS im Infomodus mitgeteilt werden.
 
 
<big>''' INIT '''</big>
 
 
----
 
----
  INIT <bus> POWER
+
  INIT TIME <Tag> <Stunde> <Minute> <Sekunde> <fx> <fy>
 
----
 
----
  
Initialisiert die Stromversorgung, sie wird jedoch noch nicht eingeschaltet!
+
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:
  
<big>''' GET '''</big>
 
 
----
 
----
   GET <bus> POWER
+
   (Delta) Modellzeit = (Delta) Realzeit * FX / FY
 
----
 
----
  
Liefert den aktuellen Zustand der Energieversorgung als INFO.
+
Beispiel:
  
<big>''' SET '''</big>
+
* FX=10 FY=1 -> Jede Realminute werden 10 Modellminuten generiert (also alle 6 Sekunden eine).
----
+
* FX=1 FY=10 -> Alle 10 Realminuten läuft eine Modellminute ab.
  SET <bus> POWER ON|OFF <freetext>
+
* FX=1 FY=1 -> Jede Realminute läuft eine Modellminute ab
----
+
  
Aktiviert (ON) oder deaktiviert (OFF) die Energieversorgung auf dem betreffenden Bus. Der <freetext> ist eine optionale Ergänzung, die bis zu 100 Zeichen umfassen kann. Sie wird im INFO an andere Clients gemeldet. Ein SRCP Server wertet diesen Parameter nicht aus.
+
Die Tageszahl wird fortlaufend alle 24 Modellstunden hochgezählt.
  
<big>''' TERM '''</big>
 
----
 
  TERM <bus> POWER
 
----
 
  
Beendet die Stromversorgung und schaltet sie ab.
+
==== Befehlsparameter des Befehls TERM ====
  
<big>''' INFO '''</big>
+
Keine bislang
----
+
  INFO <bus> POWER ON|OFF <freetext>
+
----
+
  
Informiert über den aktuellen Zustand der Energieversorgung und eventuell vorhandene Zusatzangaben.
 
  
  
===== Gerätegruppe TIME: Zeitnormal =====
+
== 4. Kommandos zur Dekoderprogrammierung ==
  
Die Modellzeit ist eine gegenüber der Normalzeit um einen konstanten Faktor verzerrte Zeit. Die Zeitverzerrung wird durch einen Multiplikator und einen Divisor gegenüber dieser Normalzeit angeben. Der Zeitgeber ist nur im Bus 0 zulässig, es gibt nur einen.
+
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 werden die Befehle WRITE, VERIFY und READ spezifiziert.
  
Im Grundzustand ist der Zeitgeber gestoppt.
+
In INFO Zeilen wird als Gerätegruppe das Wort SM benutzt: ServiceMode.
  
Der Zeitgeber ist optionaler Bestandteil. Wird er nicht unterstützt, so MUSS eine Fehlermeldung <code>425 ERROR not supported</code> bei allen Kommandos generiert werden.
 
  
Die Zeiterfassung besteht aus den Angaben: Tag, Stunde, Minute und Sekunde. Eine Minute besteht aus 60 Sekunden, eine Stunde aus 60 Minuten und ein Tag aus 24 Stunden. Die Tage werden fortlaufend gezählt, eine Unterteilung in größere Zeitintervalle (Kalenderfunktionen) ist Aufgabe des Clients.
+
=== 4.1 Dekodereinstellungen ändern ===
  
Bei Erreichen einer vollen Modellminute wird im INFO Modus die aktuelle Modellzeit ausgegeben. Die Befehle GET und WAIT werten zusätzlich die Modellsekunden aus.
 
 
Die Modellzeit errechnet sich wie folgt:
 
 
----
 
----
   (Delta) Modellzeit = (Delta) Realzeit * FX / FY
+
   WRITE GL <protocol> <dest-type> <dest-addr> <value>
 +
  WRITE GA <protocol> <dest-type> <dest-addr> <value>
 
----
 
----
  
Beispiele:
+
Länge eines Kommandos (variabel): Einzeilig, Befehlsendezeichen ist "\n"
  
* FX=10 FY=1 -> Jede Realminute werden 10 Modellminuten generiert (also alle 6 Sekunden eine).
+
Kommunikationsports:
* FX=1 FY=10 -> Alle 10 Realminuten läuft eine Modellminute ab.
+
* FX=1 FY=1 -> Jede Realminute läuft eine Modellminute ab
+
  
<big>''' INIT '''</big>
+
* Client -> Server: Kommandoport
----
+
* Server -> Client: Kommandoport
  INIT 0 TIME <fx> <fy>
+
----
+
  
Initialisiert den Zeitgeber mit der angegebenen Verzerrung. Der Zeitgeber wird nicht automatisch gestartet. Die Parameter müssen positive, von Null verschiedene Zahlen sein. Ein Server KANN den Wertebereich auf einen eingeschränkten Bereich (z.B. 1..10) begrenzen. Diese Werte MÜSSEN in der Dokumentation angegeben werden.
+
Bedeutung der Argumente
  
<big>''' SET '''</big>
+
; '''protocol'''
----
+
:    NMRA, ...
  SET 0 TIME <JulDay> <Hour> <Minute> <Second>
+
; '''dest-type'''
----
+
:    Art der zu ändernden Dekoderspeicherzelle (destination type)
 +
:;  '''CV'''
 +
::      NMRA-DCC configuration variable
 +
:;  '''CVBIT'''
 +
::      ein Bit einer NMRA-DCC configuration variable, dest-addr enthält dann zwei Worte: Speicherzelle und Bitnummer (0-7) in dieser Speichezelle
 +
:;  '''REG'''
 +
::      Ein Register eines NMRA-DCC-Dekoders
 +
; '''dest-addr'''
 +
:    Adresse der Speicherzelle, die geändert werden soll (ggf. enthält sie die Bitnummer (0-7, bei CVBIT) als zweites Wort der Adresse.
 +
; '''value'''
 +
:    neuer Wert der Speicherzelle
  
Setzt den Zeitgeber auf den angegebenen Zeitpunkt und startet ihn. Bei einem laufenden Zeitgeber wird die neue Zeit mit dem Ablauf der laufenden Modellsekunde wirksam, so daß die neu beginnende Modellsekunde der neuen Zeit entspricht.
+
Ein SRCP-Server sendet immer nach dem Empfang und der Abarbeitung eines WRITE-Kommandos eine Information an den Client. Diese Information muss folgendes Format haben:
  
<big>''' GET '''</big>
 
 
----
 
----
   GET 0 TIME
+
   INFO GL SM <value>
 +
  INFO GA SM <value>
 
----
 
----
  
Liefert die aktuelle Modellzeit als INFO.
+
Wobei <value> folgende Werte annehmen kann:
  
<big>''' WAIT '''</big>
+
* 0: WRITE ist fehlgeschlagen
----
+
* 1: WRITE wurde erfolgreich ausgeführt
  WAIT 0 TIME <JulDay> <Hour> <Minute> <Second>
+
* 2: Der Server weiss nicht, ob WRITE erfolgreich war
----
+
  
Wartet, bis die Modellzeit den angegebenen Zeitpunkt erreicht oder überschritten hat und liefert einen INFO-String mit der dann aktuellen Modellzeit.
+
Sollte WRITE oder ein bestimmter Parameter von WRITE nicht vom Server unterstützt werden, so sendet der Server auf dem Kommandoport die Information "INFO -1".
  
Bei nicht laufendem Zeitgeber wird eine Fehlermeldung generiert: <code>416 ERROR no data</code>. Ist die aktuelle Modellzeit bereits später als die angegebene Zeit, ist die Bedingung ohne weitere Wartezeit erfüllt. Offensichtlich falsche Zeitangaben werden durch <code>412 ERROR wrong value</code> an den anfordernden Client gemeldet und ignoriert. Der WAIT MUSS immer die aktuell gültige Modellzeit auswerten, die ggf. durch SET verändert werden kann.
 
 
<big>''' TERM '''</big>
 
----
 
  TERM 0 TIME
 
----
 
  
Stoppt und entfernt den Zeitgeber. Alle laufenden WAIT werden mit einem TIMEOUT beendet.
+
=== 4.2 Dekodereinstellungen verifizieren ===
  
<big>''' INFO '''</big>
 
 
----
 
----
   INFO 0 TIME <JulDay> <Hour> <Minute> <Second>
+
   VERIFY GL <protocol> <dest-type> <dest-addr> <value>
 +
  VERIFY GA <protocol> <dest-type> <dest-addr> <value>
 
----
 
----
  
Liefert alle Parameter und aktuellen Werte des Zeitgebers.
+
Länge eines Kommandos (variabel): Befehlsendezeichen ist "\n"
  
 +
Kommunikationsports:
  
===== SESSION =====
+
* Client -> Server: Kommandoport
 +
* Server -> Client: Kommandoport
  
Sessions sind aktive Verbindungen eines Clients mit einem Server. Ein Client KANN mehrere Sessions bei einem Server haben. Diese sind für den Server voneinander unabhängig. Eine Session wird anhand einer SessionID von anderen unterschieden. Diese SessionID wird während des Handshake vom Server erzeugt und ist für die Laufzeit des Servers eindeutig. Eine einmal vergebene SessionID kann von einem Server nicht ein zweites Mal vergeben werden.
+
Bedeutung der Argumente
  
Sessions sind nur im Bus 0 zulässig. Ein Grundzustand ist nicht definiert.
+
; '''protocol'''
 
+
:    NMRA, ...
<big>''' GET '''</big>
+
; '''dest-type'''
----
+
:    Art der zu verifizierenden Dekoderspeicherzelle (destination type)
   GET 0 SESSION <SESSIONID>
+
:;  '''CV'''
----
+
::      NMRA-DCC configuration variable
 +
:;  '''REG'''
 +
::      Ein Register eines NMRA-DCC-Dekoders
 +
; '''dest-addr'''
 +
:   Adresse der Speicherzelle, die verifiziert werden soll
 +
; '''value'''
 +
:    zu verifizierender Wert der Speicherzelle
  
Liefert Angaben zur Session als INFO. Der Einsatz des Wildcards "*" ist zulässig und liefert INFO für alle SESSIONS.
+
Ein SRCP-Server sendet immer nach dem Empfang und der Abarbeitung eines VERIFY-Kommandos eine Information an den Client. Diese Information muss folgendes Format haben:
  
<big>''' TERM '''</big>
 
 
----
 
----
  TERM 0 SESSION [<sessionid>]
+
    INFO GL SM <value>
 +
    INFO GA SM <value>
 
----
 
----
  
Beendet die aktuelle SESSION und schließt die Socketverbindung. Als letzte Meldung vom Server an den Client erfolgt eine Quittung des Befehls <code>200 OK</code>. Wird eine sessionid angegeben, wird die betreffende Session beendet.
+
Wobei <value> folgende Werte annehmen kann:
  
<big>''' INFO '''</big>
+
* 0: Der mit <value> angegebene Wert ist nicht der aktuelle Wert der Speicherzelle.
----
+
* 1: Der mit <value> angegebene Wert wurde verifiziert.
  INFO 0 SESSION <SESSIONID> [optionale weitere Parameter]
+
* 2: Der Server kann kein VERIFY durchführen.
----
+
  
Die Angaben für die Session werden geliefert. Die weiteren Parameter können die IP Adresse, die Portnummer und weitere Angaben enthalten.
+
Sollte VERIFY oder ein bestimmter Parameter von VERIFY nicht vom Server unterstützt werden, so sendet der Server auf dem Kommandoport die Information "INFO -1".
  
  
===== DESCRIPTION =====
+
=== 4.3 Dekodereinstellungen auslesen ===
  
Die DESCRIPTION Gerätegruppe beschreibt andere Gerätegruppen und Busse. Sie informieren den Client über die grundsätzlichen Eigenschaften.
+
Reserviert für zukünftige Erweiterungen.
  
<big>''' GET '''</big>
 
  
Dieser Befehl kommt in zwei Versionen vor: Mit Parameterliste und ohne. Wird die Parameterliste weggelassen, so informiert der Server den Client über den betreffenden Bus. Mit angegebener Parameterliste wird das betreffende Gerät bzgl. seiner Initialisierung beschrieben.
 
----
 
    GET <bus> DESCRIPTION
 
    --> INFO <bus> DESCRIPTION <list of devicegroups>
 
----
 
  
Der INFO umfaßt in einer Zeile alle von dem betreffenden Bus unterstützten Gerätegruppen. Beispiel:
+
== 5. Datenformate der Serverinformationen ==
----
+
    GET 0 DESCRIPTION
+
    --> INFO 0 DESCRIPTION SERVER SESSION TIME
+
    GET 1 DESCRIPTION
+
    --> INFO 1 DESCRIPTION FB
+
----
+
  
Der Bus 0 unterstützt die Gerätegruppen SERVER, SESSION und TIME, der Bus 1 nur Rückmelder.
+
=== 5.1 Rückmeldepollport ===
  
In der zweiten Variante wird die Adresse des betreffenden Gerätes angegeben und als Antwort die bei der Initialisierung definierten Parameter angegeben.
+
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:
----
+
    GET <bus> DESCRIPTION <devicegroup> <address>
+
----
+
  
Die Parameterliste ist in diesem Fall identisch zu der des INIT Befehls. Beispiel:
 
 
----
 
----
   GET 1 DESCRIPTION FB 1
+
   INFO FB <module_type> <portnr> <state>
  --> INFO 1 DESCRIPTION FB S88 /dev/lp1 4
+
 
----
 
----
  
d.h. der Bus 1 ist ein S88 Bus mit 4 Modulen an /dev/lp1.
+
(vgl. [[#GET FB | GET FB]])
  
 +
Beim Öffnen des Ports werden sofort alle aktuell ''belegten'' (state == 1) FB-Ports an den Client übermittelt. Anschließend alle Veränderungen.
  
===== SERVER =====
 
  
Der Server als Ganzes. Diese Gerätegruppe ist nur im Bus 0 definiert. Zulässig sind die Befehle TERM und RESET. Der Grundzustand ist RUNNING.
+
=== 5.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:
  
<big>''' TERM '''</big>
 
 
----
 
----
   TERM 0 SERVER
+
   INFO GL <protocol> <addr> <direction> <V> <V_max> <func> <nro_f> <f1> .. <fn>
 
----
 
----
  
Beendet den laufenden Server und schließt alle Verbindungen. Die angeschlossenen Busse SOLLEN abgeschaltet und die aktiven Geräte in den Grundzustand versetzt werden. Für den anfordernden Client wird die Quittung <code>200 OK</code> gesendet. Sessions im INFO Modus werden über den laufenden TERM unterrichtet. Ein TERM DARF NICHT abgebrochen werden.
+
(vgl. [[#GET GL | GET GL]])
  
<big>''' RESET '''</big>
 
 
----
 
----
   RESET 0 SERVER
+
   INFO GA <protocol> <acc_nr> <acc_port> <state>
 
----
 
----
  
Re-initialisiert den Server. Alle Geräte werden in den Grundzustand versetzt. Ein RESET während eines RESET MUSS abgewiesen werden (<code>413 temporarily prohibited</code>). Bestehende Clientsessions, auch im Handshake, bleiben unberührt.
+
(vgl. [[#GET GA | GET GA]])
  
<big>''' INFO '''</big>
 
 
----
 
----
   INFO 0 SERVER <Zustandsinfo>
+
   INFO TIME <TAG> <STUNDE> <MINUTE> <SEKUNDE> <FX> <FY>
 
----
 
----
  
Informiert über den aktuellen Zustand des Servers. Folgende Meldungen sind definiert:
+
(vgl. [[#GET TIME | GET TIME]])
  
* RUNNING: Server im Normalbetrieb
+
----
* RESETTING: Server führt einen Reset aus
+
  INFO POWER ON|OFF <erläuternder Text>
* TERMINATING: Server wird beendet.
+
----
  
Die letzten beiden Meldungen sind insbesondere im INFO Modus zu beachten
+
Der Zustand der Energierversorgung: Aktiv oder nicht aktiv. Der optionale "erläuternde Text" kann Hinweise auf die Ursache der Veränderung enthalten, er wird ggf. dem begleitenden Text des "SET POWER" Befehls entnommen. Bei automatisch erzeugten Texten ist sicherzustellen, das die Textlänge 100 Zeichen nicht übersteigt.
  
  
=== 4.3 Infomodus ===
 
  
Im Infomodus werden unidirektional alle Veränderungen aller Geräte an den angeschlossenen Client gesendet. Dem Client ist es VERBOTEN, Kommandos oder anderes an den Server zu senden. Der Server muß sicherstellen, das trotzdem gesendete Daten keine Auswirkungen haben, es steht dem Server frei, die Verbindung zu beenden.
+
== 6. Ausblicke, zukünftige Erweiterungen ==
  
Der Infomodus sendet alle Angaben so, wie sie auch auf der Anlage bekannt werden. Es erfolgen keine Umwandlungen oder Interpretationen der Daten. Dies betrifft insb. die Geschwindigkeit von Lokomotiven, die von Clients zwar virtuell gesendet werden, jedoch vom Server auf die realen Gegebenheiten des betreffenden Decoders umgerechnet werden.
+
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.
  
Beim Aktivieren des Infomodus in einer Session werden für alle Busse die DESCRIPTIONS und alle dem Server bekannten und aktiven Geräte mit ihrem aktuellem Zustand übermittelt. Anschließend werden alle Veränderungen gesendet. Wenn für einzelne Gerätegruppen ein eindeutiger Grundzustand existiert, so SOLLEN alle Geräte, die sich in diesem Grundzustand befinden nicht übermittelt werden. Optionale Gerätegruppen DÜRFEN NUR angegeben werden, wenn sie auch unterstützt werden.
 
  
Besonderheiten der Gerätegruppen bei Aktivieren des Infomodus:
+
=== 6.1 Zentrale Konfiguration ===
  
: '''FB''' Alle Geräte, die im Zustand 0 sind, werden nicht gemeldet.
+
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.
  
: '''GA''' Die einzelnen Ports der dem Server bekannten Geräte werden getrennt mit ihrer jeweils letzten Aktivität übermittelt. Wenn unterschiedliche Ports angesprochen wurden, so MUSS für jeden Port getrennt der INFO mit dem Zeitstempel der letzten Aktivierung gesendet werden. Dies SOLL in der korrekten zeitlichen Reihenfolge geschehen. Es MÜSSEN auch Informationen über Geräte übermittelt werden, die sich zwar gegenwärtig im Grundzustand befinden, die jedoch bereits mind. einmal aktiviert wurden und nicht mit TERM beendett wurden.
 
  
: '''GL,SM''' Alle in Bewegung befindlichen oder mit einer aktivierten Funktion stehenden Loks werden gemeldet. Stillstehende Loks MÜSSEN gemeldet werden, wenn sie wenigsten einmal angesprochen und nicht mit TERM entfernt wurden. Ebenso werden Veränderungen durch INIT gemeldet. Bei SM werden alle Programmieraktionen gemeldet. Eine abgeschlossene Programmieraktion DARF bei neuen Verbindungen NICHT gesendet werden.
+
=== 6.2 Erweiterung der Befehle auf andere Gerätegruppen ===
  
: '''POWER''' Der Zustand der Energieversorgung MUSS angegeben werden.
+
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.
  
: '''TIME''' Die aktuelle Modellzeit MUSS übermittelt werden, sofern dieses Feature unterstützt wird und der Zeitgeber läuft.
 
  
: '''SESSION''' Eine Identifizierung aller derzeit aktiven Clientsessions wird gesendet. Alle weiteren Informationen MÜSSEN im Kommandomodus ermittelt werden.
+
=== 6.3 Quittierung von Befehlen ===
  
: '''LOCK''' Alle derzeit gelockten Geräte werden gemeldet.
+
Martin Ostermann hängt an einer Befehlsquittierung. Dieses könnte über den Rückkanal des Kommandoports realisiert werden.
  
Ab der initialen Übermittlung aller Zustände MÜSSEN alle Veränderungen, auch solche in den Grundzustand, an der Anlage und dem Server übermittelt werden. Ausnahme ist die Gerätegruppe TIME: Sie meldet jeden Start einer neuen Modellminute, nicht jedoch jeder Modellsekunde.
 
  
 +
=== 6.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).
  
== 5. Glossar ==
 
  
Die hier angeführten Begriffe bilden Schnittstellen zu anderen Dokumenten.
 
  
: '''Julianisches Datum''' Das Julianische Datum ist eine einfache Tageszählung ohne eine weitere Strukturierung (etwa in Wochen/Monate/Jahre) vorzunehmen. Je nach Nullpunkt (Jahresanfang, fester Zeitpunkt in der Vergangenheit) existieren unterschiedliche Umrechnungsmöglichkeiten in andere Kalender (Basis: 1.1.4713 v.Chr. 12-00 GMT Collected Algorithms from CACM #199)
+
== 7. Glossar ==
  
: '''XRCP''' Eine Ergänzung des SRCP, um ein höheres Abstraktionsniveau zu schaffen. Neben der Anbindung der Clients an den Server dient es zur Kommunikation der Clients untereinander. Ein XRCP System ist als Middleware zwischen Clients und SRCP Servern gestaltet.
+
; '''Julianische Tageszahl'''
 +
:    Laufende Tageszählung anstelle eines strukturierten Kalenders. Ausgehend von einem festgelegten Starttag und -zeitpunkt wird alle 24 Stunden der folgende Tag begonnen. Gebräuchlich sind als Startzeitpunkt wiederkehrend Neujahr 0h:0:0 (wie in der C Runtime) bzw. einmalig der 1.1.4713 v.Chr. 12-00 GMT in der Astronomie (daher der Name!).
 +
Es existieren Algorithmen zur Umrechung von Kalenderinformationen in diese Darstellungsform und umgekehrt (z.B. in Collected Algorithms from CACM #199)
  
 
[[Kategorie:SRCP]]
 
[[Kategorie:SRCP]]

Version vom 24. Februar 2006, 15:07 Uhr

Torsten Vogt, Martin Ostermann, Kurt Haders, Olaf Schlachter, Matthias Trute, Tobias Schlottke, Edbert van Eimeren, Stefan Bormann, Michael Reukauff

Juli 2000


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.

Zahlen sind Ganzzahlen. Eine Beschränkung des Wertebereiches besteht nicht generell.

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 ist 12345. Der Rückmeldepollport und der Informationsport sind die beiden unmittelbar folgenden Portnummern. Standardmässig ergeben sich somit folgende Portnummern:

  • Kommandoport : 12345
  • Rückmeldepollport: 12346
  • Informationsport : 12347

Nimmt ein Client zum Kommandoport Kontakt auf, 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. Allgemeine 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
  • RESET : Der Server re-initialisiert sich

Folgende Kommandos sind von Clients nicht mehr zu verwenden, müssen vom Server jedoch implementiert werden

  • STARTVOLTAGE identisch mit SET POWER ON
  • STOPVOLTAGE identisch mit SET POWER OFF


3. Kommandos zur Digitalsteuerung

3.1 Befehle und Gerätegruppen

SRCP definiert 8 generelle Befehle, die über den Kommandoport abgewickelt werden.

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.
TERM
Falls die mit INIT getroffenen Einstellungen wieder entfernt werden sollen.
READ
Liest einen Wert aus, Ergänzung zum WRITE
WRITE
Setzt einen Wert vom Client und liefert eine Antwort (Quittung) zurück.
VERIFY
Überprüft, ob ein Wert einen bestimmten Wert hat.

Geräte entstammen den Gerätegruppen Lokdekoder, Schaltdekoder, Rückmeldeeinheiten und sonstigen Bereichen.

Über Parameter wird festgelegt, auf welche Gerätegruppe sich ein Befehl bezieht. Der erste Parameter legt immer die Gerätegruppe fest:

Die Befehle WRITE, VERIFY und READ sind für die Verwendung von Programmierinterfaces (Dekoder) vorgesehen.

GL
Lok- und Funktionsdekoder (generic loco)
GA
Schaltdekoder (generic accessory)
FB
Rückmeldeeinheit (feedback)
TIME
Zeitnormal
POWER
Energieversorgung der Modellanlage

Anwendbarkeit der Befehle auf Gerätegruppen:


        |  SET  GET  WAIT  INIT TERM
     ---+----------------------------
        |
     GL |   x    x    -     -    -
        |
     GA |   x    x    -     -    -
        |
     FB |   -    x    x     x    -
        |
   TIME |   x    x    x     x    -
        |
  POWER |   x    x    -     -    -

Bei den Befehlen GET und 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

<a name="SET GL"></a>

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)
  • M5: M2 erweitert nach Märklin (abs. FRU, 80 Adr, 5 Funkt., 27 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/9/13 Funkt., 28 FS)
  • N2: NMRA-DCC erweitert (abs. FRU, 7-bit-Adr., 5/9/13 Funkt., 128 FS)
  • N3: NMRA-DCC erweitert (abs. FRU, 14-bit-Adr.,5/9/13 Funkt., 28 FS)
  • N4: NMRA-DCC erweitert (abs. FRU, 14-bit-Adr., 5/9/13 Funkt., 128 FS)
  • PS: protocol by server, der Server bestimmt den Protokolltyp
addr
Zahl >= 0
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 sind

  • 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


<a name="SET GA"></a>

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
Zahl >= 0 (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


TIME

      SET TIME <Tag> <Stunde> <Minute> <Sekunde> <fx> <fy>

Kommunikationsports:

  • Client -> Server: Kommandoport
  • Server -> Client: entfällt

Bedeutung der Argumente

Die aktuelle Modellzeit und die Verzerrung gegenüber der Realzeit wird festgelegt. Bei erstmaligen Aufruf vergleichbar mit einem INIT TIME.

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)


<a name="SET POWER"></a>

POWER

      SET POWER <state> <freetext>

Kommunikationsports:

  • Client -> Server: Kommandoport
  • Server -> Client: entfällt

Bedeutung der Argumente

State
ON
Schaltet die Energieversorgung ein
OFF
Schaltet die Energieversorgung ab
Freetext
Ein optionaler Text mit maximal 100 Zeichen, der an das INFO Packet angehängt wird und nähere Informationen geben kann. Es werden ausdrücklich keine Vorgaben über den Inhalt gemacht.


Befehlsparameter des Befehls GET

<a name="GET GL"></a>

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


<a name="GET GA"></a>

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


<a name="GET FB"></a>

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. Befehle und Gerätegruppen).


<a name="GET TIME"></a>

Zeit

  GET TIME

Kommunikationsports:

  • Client -> Server: Kommandoport
  • Server -> Client: Kommandoport

Liefert die aktuelle Modellzeit und die Verzerrungsfaktoren als INFO-Zeile


 INFO TIME <Tag> <Stunde> <Minute> <Sekunde <fx> <fy>

Sollte keine Modellzeit definiert sein, so muß der Server dies mit "INFO -2" (no data) an den Client senden (vgl. Befehle und Gerätegruppen).


Power

  GET POWER

Kommunikationsports:

  • Client -> Server: Kommandoport
  • Server -> Client: Kommandoport

Ermittelt den aktuellen Zustand der Energieversorgung. Als Antwort erscheint


INFO POWER [ON|OFF] <Message_Text>

Messagetext ist hierbei der zuletzt gesetzte Wert (vgl. SET POWER)


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 der angegebene Port 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.


TIME

  WAIT TIME <Tag> <Stunde> <Minute> <Sekunde>

Kommunikationsports:

  • Client -> Server: Kommandoport
  • Server -> Client: Kommandoport

Wartet, bis die Modellzeit den angegebenen Zeitpunkt mind. erreicht hat und liefert einen INFO-String mit der aktuellen Modellzeit.

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 durch "INFO -1" an den anfordernden Client 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.


<a name="INIT TIME"></a>

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 -> Jede Realminute werden 10 Modellminuten generiert (also alle 6 Sekunden eine).
  • FX=1 FY=10 -> Alle 10 Realminuten läuft eine Modellminute ab.
  • FX=1 FY=1 -> Jede Realminute läuft eine Modellminute ab

Die Tageszahl wird fortlaufend alle 24 Modellstunden hochgezählt.


Befehlsparameter des Befehls TERM

Keine bislang


4. Kommandos zur Dekoderprogrammierung

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 werden die Befehle WRITE, VERIFY und READ spezifiziert.

In INFO Zeilen wird als Gerätegruppe das Wort SM benutzt: ServiceMode.


4.1 Dekodereinstellungen ändern


  WRITE GL <protocol> <dest-type> <dest-addr> <value>
  WRITE GA <protocol> <dest-type> <dest-addr> <value>

Länge eines Kommandos (variabel): Einzeilig, Befehlsendezeichen ist "\n"

Kommunikationsports:

  • Client -> Server: Kommandoport
  • Server -> Client: Kommandoport

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, dest-addr enthält dann zwei Worte: Speicherzelle und Bitnummer (0-7) in dieser Speichezelle
REG
Ein Register eines NMRA-DCC-Dekoders
dest-addr
Adresse der Speicherzelle, die geändert werden soll (ggf. enthält sie die Bitnummer (0-7, bei CVBIT) als zweites Wort der Adresse.
value
neuer Wert der Speicherzelle

Ein SRCP-Server sendet immer nach dem Empfang und der Abarbeitung eines WRITE-Kommandos eine Information an den Client. Diese Information muss folgendes Format haben:


  INFO GL SM <value>
  INFO GA SM <value>

Wobei <value> folgende Werte annehmen kann:

  • 0: WRITE ist fehlgeschlagen
  • 1: WRITE wurde erfolgreich ausgeführt
  • 2: Der Server weiss nicht, ob WRITE erfolgreich war

Sollte WRITE oder ein bestimmter Parameter von WRITE nicht vom Server unterstützt werden, so sendet der Server auf dem Kommandoport die Information "INFO -1".


4.2 Dekodereinstellungen verifizieren


  VERIFY GL <protocol> <dest-type> <dest-addr> <value>
  VERIFY GA <protocol> <dest-type> <dest-addr> <value>

Länge eines Kommandos (variabel): Befehlsendezeichen ist "\n"

Kommunikationsports:

  • Client -> Server: Kommandoport
  • Server -> Client: Kommandoport

Bedeutung der Argumente

protocol
NMRA, ...
dest-type
Art der zu verifizierenden Dekoderspeicherzelle (destination type)
CV
NMRA-DCC configuration variable
REG
Ein Register eines NMRA-DCC-Dekoders
dest-addr
Adresse der Speicherzelle, die verifiziert werden soll
value
zu verifizierender Wert der Speicherzelle

Ein SRCP-Server sendet immer nach dem Empfang und der Abarbeitung eines VERIFY-Kommandos eine Information an den Client. Diese Information muss folgendes Format haben:


    INFO GL SM <value>
    INFO GA SM <value>

Wobei <value> folgende Werte annehmen kann:

  • 0: Der mit <value> angegebene Wert ist nicht der aktuelle Wert der Speicherzelle.
  • 1: Der mit <value> angegebene Wert wurde verifiziert.
  • 2: Der Server kann kein VERIFY durchführen.

Sollte VERIFY oder ein bestimmter Parameter von VERIFY nicht vom Server unterstützt werden, so sendet der Server auf dem Kommandoport die Information "INFO -1".


4.3 Dekodereinstellungen auslesen

Reserviert für zukünftige Erweiterungen.


5. Datenformate der Serverinformationen

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


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


 INFO POWER ON|OFF <erläuternder Text>

Der Zustand der Energierversorgung: Aktiv oder nicht aktiv. Der optionale "erläuternde Text" kann Hinweise auf die Ursache der Veränderung enthalten, er wird ggf. dem begleitenden Text des "SET POWER" Befehls entnommen. Bei automatisch erzeugten Texten ist sicherzustellen, das die Textlänge 100 Zeichen nicht übersteigt.


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


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


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


6.3 Quittierung von Befehlen

Martin Ostermann hängt an einer Befehlsquittierung. Dieses könnte über den Rückkanal des Kommandoports realisiert werden.


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


7. Glossar

Julianische Tageszahl
Laufende Tageszählung anstelle eines strukturierten Kalenders. Ausgehend von einem festgelegten Starttag und -zeitpunkt wird alle 24 Stunden der folgende Tag begonnen. Gebräuchlich sind als Startzeitpunkt wiederkehrend Neujahr 0h:0:0 (wie in der C Runtime) bzw. einmalig der 1.1.4713 v.Chr. 12-00 GMT in der Astronomie (daher der Name!).

Es existieren Algorithmen zur Umrechung von Kalenderinformationen in diese Darstellungsform und umgekehrt (z.B. in Collected Algorithms from CACM #199)