Der Einsatz digitaler Modellbahnausrüstung ist bislang sehr stark von der eingesetzten Hardware geprägt. Es gibt eine Übereinkunft zwischen einigen Herstellern, 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.
Um dem Modellbahner leistungsfähige Programme bereitstellen zu können, muß die Software deshalb für alle derzeit eingesetzten und zukünftigen Digitalsysteme extra angepaßt und getestet werden.
Darüberhinaus ist ein Multiuserbetrieb nur eingeschränkt möglich, wenn überhaupt vorhanden.
Mit dem Simple Railroad Command Protocol werden folgende gleichrangigen Ziele verfolgt:
Vorliegender Text definiert sowohl das Protokoll an sich als auch Syntax und Semantik der zu verwendenden Geräte.
In diesem Text werden die Konventionen entsprechend RFC 1122 in einer deutschen Übersetzung verwendet. Im einzelnen sind dies "MUSS", "SOLL", "EMPFOHLEN", "KANN" und "OPTIONAL".
"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.
SRCP vermittelt eine Client-Serverkommunikation zur Steuerung einer Modellbahn sowie ein einheitliches Datenmodell für die aktiven Elemente der 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 vom anderen Ende der Welt aus die Anlage steuern. Für den Client ist das verwendete Modellbahnsystem von untergeordneter Bedeutung. Es ist Aufgabe des Servers, die Befehle des SRCP geeignet umzusetzen.
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. Wann immer die Anlage die Daten liefern kann, wird der Server dies nutzen.
SRCP erfüllt keine formalen Echtzeitforderungen zur Steuerung. Inbesondere gibt es keine garantierten Aktionszeiten.
Eine Central Unit (CU) ist in der klassischen Modellbahnsteuerung dasjenige Element, das die alleinige Steuerhoheit über die Anlage hat. Jede CU verfügt über Möglichkeiten, die unterschiedlichen aktiven Elemente zu adressieren und an sie Informationen zu übermitteln bzw. von ihnen Informationen abzufragen.
Ein SRCP Server SOLL genau eine Central Unit im herkömmlichen Sinn repräsentieren. 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 mehrere (ggf. unterschiedliche) SRCP-Server auf unterschiedlichen TCP Ports (s.u.) zu betreiben. Genau einer dieser Server MUSS den Standardport bereitstellen.
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
offiziellen Namen verleihen. Der vorläufige Name ist srcp
12345tcp/.
Alle Zeichencodes werden in ihrer dezimalen Form als # gefolgt vom numerischen Wert des Zeichens beschrieben.
Die gesamte Kommunikation besteht aus den Zeichen des 7Bit ASCII Zeichensatzes im Bereich #32 bis #127 (einschl. der Grenzen). Zusätzlich 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.
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.
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. Die Elemente der Kommandoliste werden ihrerseits durch Whitespace voneinander getrennt. Das Ende eines Kommandos ist das Zeilenende. Die Fortsetzung eines Kommandos in der Folgezeile oder mehrere Kommandos in einer Zeile sind nicht zulässig. Elemente der Parameterliste, 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, verschieden lange Parameterlisten definiert, ist immer die längstmögliche Listeninterpretation anzuwenden.
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.
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.
Ein Server MUSS auf jedes Kommando eines Clients mit einer Antwort reagieren. Diese wird auf der gleichen TCP Verbindung an den Client gesendet. Eine Antwort SOLL einzeilig sein. Durch das Zeichen \ (Backslash, #92) 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.
Eine Antwort ist entweder eine Eingangsbestätigung eines Kommandos (Quittung), eine Fehlermeldung oder das Ergebnis des Kommandos. Wenn die Antwort eine Fehlermeldung ist, DARF das Kommando NICHT ausgeführt werden.
Eine Antwort ist mit dem wirksamen Zeilenende abgeschlossen. Das Übermitteln von mehr als einer Antwort in einer Zeile ist nicht zulässig.
Antworten des Servers werden immer mit einem Timestamp eingeleitet. Einzige Ausnahme ist der Welcome Der Timestamp wird, sofern nicht anders definiert, aus der aktuellen Systemzeit wie folgt gebildet: Angabe der Sekunden seit dem 1.1.1970 00:00:00 ("POSIX-Sekunden") einem Punkt und den Millisekunden der laufenden Sekunde als Festkommazahl mit 3 Nachkommastellen.
In diesem Text wird bei allen Angaben der Zeitstempel implizit immer vorangestellt, aus Gründen der Übersichtlichkeit jedoch nicht angegeben, sofern es nicht zur Verdeutlichung eines Sachverhaltes notwendig ist.
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.
Ist das Ergebnis eines Kommandos sowohl aufgrund einer
Kommunikation mit angeschlossenen Modellbahnelementen, als auch
anhand sonstiger Daten ermittelbar, so SOLL die Möglichkeit der
direkten Anlagenabfrage benutzt werden. Stehen für eine Anfrage
keine ausreichend abgesicherten Ergebnisse bereit, so ist die
Antwort 416 ERROR no data.
Ein SRCP Server befindet sich gegenüber dem Client immer in einem von 3 möglichen Zuständen: Handshake, Kommandomodus oder Infomodus.
Mit der Verbindungsaufnahme wird der Handshakemodus aktiviert. In diesem werden vom 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, ein expliziter Endebefehl ist nicht spezifiziert.
open
|
V
+-----------+
| Handshake |
+-----------+
|
+----------------------+----------------------+
| | |
V | V
+-----------+ | +-----------+
| Kommando- | | | Infomodus |
| modus | | +-----------+
+-----------+ | |
| | |
V V V
close close close
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.
Kommandos MÜSSEN in der Reihenfolge ihres Eintreffens vom Server abgearbeitet werden. Insbesondere betrifft dies die Reihenfolge bei der Übermittlung an Anlagenbestandteile.
Unbekannte oder nicht erkannte Kommandos MÜSSEN mit der Meldung
410 ERROR unknown command quittiert werden.
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 GO, der vom Client an den Server gesendet wird
und von diesem bestätigt wird, startet der Betriebsmodus.
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.
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.
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:
500 ERROR out of ressources
Folgende Schlüssel MÜSSEN im normalen Welcome angegeben werden:
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.
SRCP
verschieden sein.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.
Folgende Kommandos sind definiert, werden sie nicht ausgeführt, gelten die angegebenen Standardeinstellungen. Andere als die Aufgeführten sind in der Handshakephase verboten.
SET PROTOCOL SRCP <VERSION> Das gewünschte SRCP
Protokoll, das benutzt werden soll, wird vereinbart. Fehlt dieses
Kommando wird die SRCP Version voreingestellt, die im Welcome
angegeben wurde. Der Server sendet entweder ein 201 OK
PROTOCOL SRCP oder eine Fehlermeldung 400 ERROR
unsupported protocol als Antwort.
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
202 OK CONNECTIONMODE oder eine Fehlermeldung
401 ERROR unsupported connection mode an den Client.
Fehlt dieses Kommando wird als connection mode der COMMAND Modus
gesetzt.
GO Durch diesen Befehl wird die Handshakephase beendet
und der jeweilige Betriebsmodus aktiviert. Der Server sendet als
Quittung 200 OK GO <ID> an den Client. Wenn der
Befehl nicht ausgeführt werden kann, so sendet der Server die
Fehlermeldung 402 ERROR unsufficient data 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.
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:
400 ERROR unsupported protocol Protokoll wird nicht
unterstützt.
401 ERROR unsupported connection mode
Verbindungsmodus wird nicht unterstützt.
402 ERROR unsufficient data Ungenügende
Angaben.
410 ERROR unknown command Unbekanntes Kommando.
500 ERROR out of ressources Keine Ressourcen mehr
frei.
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 des Eintreffens abweichende Bearbeitung ist nicht zulässig.
Die Antworten des Servers an den Client im Kommandomodus beginnen immer mit einem Zeitstempel, gefolgt von einem numerischen Antwortcode und weiteren Angaben. Der numerische Antwortcode ist in Gruppen gegliedert
1xx INFO: Informationen, Ergebnisse
2xx OK: Befehl wurde angenommen und zur Ausführung gebracht. Achtung: Dies ist keine Bestätigung, das der Befehl auch tatsächlich ausgeführt wurde.
4xx/5xx ERROR: Eine Fehlerbedingung ist aufgetreten, der Befehl wird ignoriert und nicht ausgeführt.
6xx ERROR: Ein serverspezifischer Fehlerzustand ist aufgetreten. Der betreffende Befehl wird nicht ausgeführt. Details sind der Serverdokumentation zu entnehmen.
Die Bedeutung des Zeitstempels ergibt sich der Art der Antwort: Für Quittungen (OK, ERROR) ist er der Zeitpunkt, an dem das das Kommando abgearbeitet und die Quittung (OK oder ERROR) generiert wurde. Bei einem INFO kennzeichnet der Zeitstempel denjenigen Zeitpunkt, an dem das gemeldete Ereignis dem SRCP Server erstmalig 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 einer Parameterliste handelt, so ist dies der Zeitpunkt der letzten Änderung.
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). Werden von verschiedenen Sessions Kommandos für ein und dasselbe Gerät gesendet, so sind diese in der Reihenfolge des Eintreffens auszuführen.
Folgende Kommandos sind definiert:
GET Abfrage von Werten
SET Setzen von Werten
CHECK Prüft einen Befehl
WAIT Wartet auf Werte
INIT Initialisierung von Elementen
TERM Beendet von mit INIT initialisierte Elemente
RESET Reinitialisiert ein Element
VERIFY Überprüft die Einstellungen eines Elements
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 die entsprechende
101 INFO-Meldung gesendet, sofern definiert.
Der INIT informiert den Server über die Eigenschaften des betreffenden Gerätes, die daraufhin modifiziert werden KÖNNEN. Der Befehl verändert weder die Buszugehörigkeit noch die Adresse.
Nach einem INIT ist für alle aktiven Sessions jeglicher Schreibzugriff mittels SET, RESET oder INIT auf das betreffende Gerät unzulässig, bis ein Lesezugriff durch die Befehle GET, WAIT oder VERIFY (je nach Gerätegruppe) oder ein TERM ausgeführt wurde. Einzige Ausnahme hiervon ist die Session, die den INIT veranlaßt hat.
Durch das Kommando TERM wird die Initialisierung wieder
aufgehoben und das betreffende Element in den Grundzustand
versetzt. Anschließend kann keine Auskunft über das Element gegeben
werden. Vor einer erneuten Benutzung muß das betreffende Element
neu initialisiert werden. Im Infomodus wird für das betreffende
Element die entsprechende 102 INFO-Meldung
gesendet.
Durch den TERM eines Gerätes wird auch ein eventueller LOCK ohne weitere Befehle beendet (impliziter TERM LOCK).
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 200 OK. Der Befehl CHECK entspricht in allen
Aspekten dem Befehl SET, nur dass die tatsächliche Ausführung des
Befehls unterdrückt wird. Zweck dieses CHECK-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 die 100 INFO 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 diesem Fall ist der
numerische Code nicht 100 sondern 110, also 110
INFO.... 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 417 ERROR
timeout generiert. Trifft der erwartete Zustand in der
angegebenen Zeit ein, wird ein 200 OK 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 200 OK 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 200 OK 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 oder nicht via GET direkt ermittelbar sind.
Parameter der Kommandos sind als Liste anzugeben. Einzelne Parameter werden durch Whitespace voneinander getrennt. Die Position des Parameters innerhalb der Liste kennzeichnet seine Bedeutung (positionsbezogene Parametrierung). Ein einzelner Parameter DARF KEINEN Whitespace enthalten. Für einzelne Befehle können mehrere unterschiedliche Parameterlisten definiert sein, die sich anhand der Anzahl der Parameter unterscheiden und eine unterschiedliche Bedeutung 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 z.B. 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 aufsteigend gezählt wird. Bus 0 ist für den Server selbst reserviert.
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 u/o Gerätegruppen ist zulässig.
Wechselt die Buszugehörigheit (z.B. bei Loks), so werden die Daten nicht automatisch übernommen. Es ist Aufgabe der Clients, diesen Transfer zu erkennen und darauf zu reagieren.
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.
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:
416 ERROR
no data erzeugt.416 ERROR no data erzeugt.Für einen SRCP Server gelten alle diejenigen Geräte als bekannt, die bereits angesprochen wurden und nicht mittels TERM gelöscht wurden. Zusätzlich KÖNNEN Elemente von der Anlage selbst gemeldet werden, sofern diese dies ermöglicht. Hierbei KANN auch ein Gerät im Grundzustand als bekannt gelten. Bei einigen Hardwaresystemen werden einige Aktivitäten durch bestimmte Eigenschaften der übermittelten Daten abgebildet. Ein SRCP Server KANN diese selbst 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 (z.B. für Broadcasts).
Fehlermeldungen werden vom Server als Antwort auf Kommandos des Clients generiert, wenn das Kommando nicht wie verlangt ausgeführt werden kann.
Fehlermeldungen beginnen wie alle Antworten immer mit dem
Timestamp, gefolgt von dem dem Fehlercode und der Angabe
ERROR. Daran MUSS sich eine der in der nachfolgenden
Liste angegebenen Meldungen anschließen:
410 ERROR unknown command Unbekanntes Kommando.
411 ERROR unknown value Unbekannter Wert.
412 ERROR wrong value Ein Parameter ist außerhalb
des zulässigen Bereichs.
413 ERROR temporarily prohibited Befehl ist derzeit
verboten.
414 ERROR device locked Gerät ist gesperrt.
415 ERROR forbidden Befehl ist grundsätzlich
verboten.
416 ERROR no data Keine Informationen
verfügbar.
417 ERROR timeout Ein Zeitlimit ist
überschritten.
418 ERROR list to long Die Parameterliste ist zu
lang.
419 ERROR list to short Die Parameterliste ist zu
kurz.
420 ERROR unsupported device protocol Dieses Gerät
unterstützt das angegebene Protokoll nicht.
421 ERROR unsupported device Dieses Gerät wird auf
dem angegeben Bus nicht unterstützt.
422 ERROR unsupported device group Die Gerätegruppe
ist auf dem angegebenen Bus nicht verfügbar.
423 ERROR unsupported operation Die angeforderte
Aktion/Befehl wird von diesem Gerät nicht unterstützt.
424 ERROR device reinitialized Das betreffende
Gerät wurde neu initialisiert. Ein GET Befehl muß zunächst
ausgeführt werden.
499 ERROR unspecified error Ein Fehler ist
aufgetreten, kann aber nicht näher angegeben werden. Diese
Fehlermeldung SOLL vermieden werden.
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 Angaben ignorieren.
Gerätegruppen sind Zusammenstellungen von gleichartigen Geräten. 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 unterschiedlichen Betriebsmodi per default auf den kleinsten gemeinsamen Nenner initialisiert. Eine Nutzung der weitergehenden Features erfordert eine Initialisierung, bei der hardwarenahme Informationen benötigt werden.
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 im Unterschied zu den DESCRIPTION der Busse optional und MUSS aber für jede Gerätegruppe des betreffenden Busses ggf. vorhanden 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 Zuständen bereitstellen. Dies sind üblicherweise ortsfeste Anlagenelemente wie Weichen und Entkuppler. Die Gerätegruppe GL kennzeichnet Lokdecoder: Dekoder mit mind. einem Ausgang für die Fahrstufen, einem für die Fahrtrichtung und ggf. Funktionsausgängen. 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.
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 temporarily prohibited oder
forbidden abgewiesen werden. 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. Das Zeitnormal ist optional. Es ist nur ein Gerät in dieser Gerätegruppe zulässig, eine Adressierung entfällt.
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 den LOCK 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. Durch einen LOCK sind die folgenden Befehle auf dem Gerät exklusiv für die den LOCK haltende Session reserviert: SET, TERM, INIT, RESET.
Die DESCRIPTION Geräte können andere Geräte mit ihren Eigenschaften beschreiben. 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, eine weitere Adressierung entfällt.
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 zulässige Verteilung der Gerätegruppen und Befehle auf die Busse darstellen. Nicht jedes Gerät ist auf jedem Bus zulässig:
| 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.. --
|
TIME | 0 0 0 0 0 0 --
|
POWER | 1.. 1.. -- 1.. 1.. -- --
|
SERVER | -- 0 -- -- 0 0 --
|
SESSION | -- 0 -- -- 0 -- --
|
LOCK | 0.. 0.. -- 0.. 0.. -- --
|
DESCRIPTION | -- 0.. -- -- -- -- --
Die mit -- gekennzeichneten Einträge markieren
Kombinationen, die NICHT verwendet werden DÜRFEN.
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.
INIT <bus> FB <optionale Parameter zur Initalisierung>
Ein serverseitig vorkonfiguriertes Rückmeldesystem wird initialisiert. Die exakten Parameter sind nur dem Server bekannt. Eine Initialisierung einzelner FB Geräte ist nicht vorgesehen. Die optionalen Parameter KÖNNEN serverseitige Vorgaben verändern.
GET <bus> FB <addr>
Liefert den aktuellen Wert des Rückmelders als 100
INFO.
TERM <bus> FB
Mit dem TERM werden auf dem betreffendem Bus alle FB aus der laufenden Kommunikation herausgenommen, 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.
WAIT <bus> FB <addr> <value> <timeout>
Wartet 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.
100 INFO <bus> FB <addr> <value> 101 INFO <bus> FB 102 INFO <bus> FB
Der aktuelle Wert des Rückmelders bzw. die Initialisierung resp Terminierung des FB-Systems auf diesem Bus.
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.
INIT <bus> GA <addr> <device protocol> <optional weitere Parameter>
Mit diesem Befehl wird ein GA Gerät im Server initialisiert. Folgende Parameter sind zulässig:
addr Adresse aus dem Protokollbereich.
device protocol
SET <bus> GA <addr> <port> <value> <delay>
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.
Bedeutung der Argumente
addr Zahl > 0 (Nummer der Weiche/des Signals)
port 0, 1, 2,... (Ausgang des Decoders), wird ein nicht
unterstützter Port angegeben, wird eine Fehlermeldung 412
ERROR wrong value erzeugt.
value 0, 1, 2, ... (0 => deaktiviert, >0 =>
aktiviert), wird ein ungültiger Wert angegeben, wird eine
Fehlermeldung 412 ERROR wrong value erzeugt.
delay Wert in Millisekunden. 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. Ein Port gilt als
aktiv, wenn sein Status ungleich Null ist. Ein Delay von 0 ist für
Values <0 nicht zulässig, es wird eine Fehlermeldung 412
ERROR wrong value erzeugt.
GET <bus> GA <addr> <port>
Der aktuelle Zustand des Ports wird an den Client übermittelt.
100 INFO <bus> GA <addr> <port> <value> 101 INFO <bus> GA <addr> <device protocol> <optional weitere Parameter> 102 INFO <bus> GA <addr>
Das Gerät an der angegebenen Adresse hat am angegebenen Port den angegebenen Wert bzw die Initialisierungs und Terminierungsangaben.
Ein Generic Loco kennzeichnet allgemein alle Lokdecoder.
Der Grundzustand ist Null bei allen Parametern.
INIT <bus> GL <addr> <device protocol> <optional weitere Parameter>
Mit dem INIT wird die Art 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 zu verwenden), Ausnahme: Wenn sich Decoder durch eine Sequenz "normaler" Steuerbefehle programmieren lassen, so DARF NICHT die SM Gerätegruppe benutzt werden.
Zulässige Werte der Parameter
device protocol
nachfolgend sind die derzeit gültigen Werte definiert.
A Analogbetrieb addr: 0, keine f (Zusatzinfo:
keine Fahrstufen)F Reserviert für FleischmannL Reserviert für LoconetM Reserviert für Märklin/Motorola
<Protokollversion>
<Dekoderfahrstufen>
<Anzahl_Dekoderfunktionen>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.
N Reserviert für NMRA/DCC:
<Protokollversion>
<Dekoderfahrstufen>
<Anzahl_Dekoderfunktionen>Die Ausführungen zu den Dekoderfahrstufen und Anzahl Funktionen
gelten wie bei M.
P protocol by server: beliebige Adresse, beliebige
Anzahl Funktionen (Zusatzinfo: beliebige Anzahl Fahrstufen). Der
Server kennt den Typ des Decoders.S Reserviert für native SelectrixZ Reserviert für native ZimoEin 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.
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 fahrtrichtungsabhängigen vor den fahrtrichtungsunabhängigen anordnen.
GET <bus> GL <addr>
Die Antwort ist eine 100 INFO-Meldung.
SET <bus> GL <addr> <drivemode> <V> <V_max> <f1> .. <fn>
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:
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 akzeptiert werden und MUSS mit einer Fehlermeldung abgewiesen werden.
drivemode
= unverändert0 rückwärts1 vorwärts2 Nothalt412 ERROR wrong value 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, solcherart,
daß eine Geschwindigkeit V2>V1 bewirkt, das die Lok bei V2 nicht
langsamer als bei V1 fährt. In allen Fehlersituationen wird eine
Fehlermeldung 412 ERROR wrong value erzeugt. Der
Einsatz des Wildcard = ist nur bei beiden Parametern
gleichzeitig zulässig.
f1 .. fn = (= unverändert), 0 (= aus), 1 (= an) nicht
zulässige Werte bewirken eine Fehlermeldung 412 ERROR wrong
value.
Ein Beispiel:
INIT 1 GL 1 N 1 128 5 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.
Der INFO MUSS alle aktuellen Werte umfassen, unabhängig ob sie aktuell geändert wurden oder nicht. Das Format ist wie folgt:
100 INFO <bus> GL <addr> <drivemode> <V> <V_max> <f1> .. <fn> 101 INFO <bus> GL <addr> <device protocol> <optional weitere Parameter> 102 INFO <bus> GL <addr>
Hierbei ist der Parameter V 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 <drivemode>.
TERM <bus> GL <addr>
Setzt die Lok in den Grundzustand und entfernt die Lok aus dem Wissenbestand des Servers.
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 422 ERROR
unsupported device group generiert werden. Sie sind für den
Einsatz zur Decoderprogrammierung vorgesehen
Ein Grundzustand ist nicht definiert.
INIT <bus> SM <protocol>
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.
Zulässige Protokolle sind
NMRA: Decoder nach NMRA Standard.
SET <bus> SM <decoderaddress> <type> <1 or more values>
Folgende <more values> sind definiert.
type
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>
Die Bedeutung der Parameter ist wie bei SET. Das Ergebnis ist
ein 100 INFO, das den betreffenden Wert widergibt. Ein
GET hat die Fehlermeldung 416 ERROR no data als
Ergebnis, wenn es keine Möglichkeit gibt, den Decoder
auszulesen.
VERIFY <bus> SM <decoderaddress> <type> <1 or more values>
Wie bei GET MUSS der Decoder direkt befragt werden.
Die Bedeutung der Parameter ist wie bei SET. Das Ergebnis ist
entweder ein 200 OK, wenn der Parameter im Decoder dem
angegebenen entspricht oder die Fehlermeldung 412 ERROR wrong
value.
TERM <bus> SM
Beendet den mit INIT begonnenen Programmiermodus auf dem betreffenden Bus. Eventuell unvollständige Programmierzyklen sind geeignet zu beenden.
100 INFO <bus> SM <decoderaddress> <type> <1 or more values> 101 INFO <bus> SM <protocol> 102 INFO <bus> SM
Die Bedeutung der Parameter ist wie bei SET bzw. INIT.
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, ggf.
auch des gleichen Clients, wird beim schreibenden Zugriff die
Fehlermeldung 414 ERROR device locked gemeldet. Die
Ausführung dieser Befehle ist dann nur dem den Lock haltenden
Clientsession gestattet. Lesezugriffe 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".
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.
SET <bus> LOCK <devicegroup> <addr> <duration>
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.
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 setzen des LOCK bzw. dem letzten SET Befehl. Eine Dauer von 0 bedeutet eine unbefristete Spanne. Ein wiederholtes Absetzen des SET Befehls startet den Zeitgeber jeweils neu.
TERM <bus> LOCK <devicegroup> <addr>
Ein Lock wird auf das Gerät <devicegroup> <addr> des Busses <bus> entfernt.
100 INFO <bus> LOCK <devicegroup> <addr> <Duration> <sessionid> 101 INFO <bus> LOCK <devicegroup> <addr> <duration> 102 INFO <bus> LOCK <devicegroup> <addr>
Die SessionID ist hierbei die eindeutige Kennung der Session, die den Lock hält. Die <Duration> ist die verbleibende Zeitdauer
GET <bus> LOCK <devicegroup> <addr>
Diesr Befehl liefern den aktuellen Lockstatus eines Gerätes als
100 INFO-Zeile. Ist das angegebene Gerät nicht
gelockt, wird die SessionID 0 angegeben.
Die Energieversorgung wird für jeden Bus getrennt geschaltet
Der Grundzustand ist OFF.
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.
INIT <bus> POWER
Initialisiert die Stromversorgung, sie wird jedoch noch nicht eingeschaltet!
GET <bus> POWER
Liefert den aktuellen Zustand der Energieversorgung als
100 INFO.
SET <bus> POWER ON|OFF [freetext]
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
100 INFO an andere Clients gemeldet. Ein SRCP Server
wertet diesen Parameter nicht aus.
TERM <bus> POWER
Beendet die Stromversorgung und schaltet sie ab.
100 INFO <bus> POWER ON|OFF <freetext> 101 INFO <bus> POWER 102 INFO <bus> POWER
Informiert über den aktuellen Zustand der Energieversorgung und eventuell vorhandene Zusatzangaben.
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.
Im Grundzustand ist der Zeitgeber gestoppt.
Der Zeitgeber ist optionaler Bestandteil. Wird er nicht
unterstützt, so MUSS eine Fehlermeldung 422 ERROR unsupported
device group 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.
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
Beispiele:
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.
SET 0 TIME <JulDay> <Hour> <Minute> <Second>
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.
GET 0 TIME
Liefert die aktuelle Modellzeit als 100 INFO.
WAIT 0 TIME <JulDay> <Hour> <Minute> <Second>
Wartet, bis die Modellzeit den angegebenen Zeitpunkt erreicht
oder überschritten hat und liefert einen 100
INFO-String mit der dann aktuellen Modellzeit.
Bei nicht laufendem Zeitgeber wird eine Fehlermeldung generiert:
416 ERROR no data. Ist die aktuelle Modellzeit bereits
später als die angegebene Zeit, ist die Bedingung ohne weitere
Wartezeit erfüllt. Offensichtlich falsche Zeitangaben werden durch
412 ERROR wrong value 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.
TERM 0 TIME
100 INFO 0 TIME <JulDay> <Hour> <Minute> <Second> 101 INFO 0 TIME <fx> <fy> 102 INFO 0 TIME
Liefert alle Parameter und aktuellen Werte des Zeitgebers.
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.
Sessions sind nur im Bus 0 zulässig. Ein Grundzustand ist nicht definiert.
GET 0 SESSION <SESSIONID>
Liefert Angaben zur Session als INFO.
TERM 0 SESSION [<sessionid>]
Beendet die aktuelle oder die angegebene SESSION und schließt
die Socketverbindung. Als letzte Meldung vom Server an den Client
erfolgt eine Quittung des Befehls 200 OK.
100 INFO 0 SESSION <SESSIONID> [optionale weitere Parameter] 101 INFO 0 SESSION <SESSIONID> [optionale weitere Parameter] 102 INFO 0 SESSION <SESSIONID> [optionale weitere Parameter]
Die Angaben für die Session werden geliefert. Die weiteren Parameter können die Art der Session, IP Adresse des Clients, die Portnummer und weitere Angaben enthalten.
Die DESCRIPTION Gerätegruppe beschreibt andere Gerätegruppen und Busse. Sie informieren den Client über die grundsätzlichen Eigenschaften.
Dieser Befehl kommt in zwei Versionen vor: Mit kurzer Parameterliste und mit langer. Die kurze Parameterliste enthält nur die Busnummer. Mit dieser informiert der Server den Client über den betreffenden Bus. Die lange Parameterliste enthält Gerätergruppe und ggf Geräteadresse. Mit dieser 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:
GET 0 DESCRIPTION
--> 100 INFO 0 DESCRIPTION SERVER SESSION TIME
GET 1 DESCRIPTION
--> 100 INFO 1 DESCRIPTION FB POWER
Der Bus 0 unterstützt die Gerätegruppen SERVER, SESSION und TIME, der Bus 1 nur Rückmelder (und natürlich POWER).
In der zweiten Variante wird die Adresse des betreffenden Gerätes angegeben und als Antwort die bei der Initialisierung definierten Parameter angegeben.
GET <bus> DESCRIPTION <devicegroup> [<address>]
Die Adresse DARF NUR bei Gerätegruppen ohne eine Adressierung weggelassen werden. Beispiel:
GET 1 DESCRIPTION GL 1 --> 101 INFO 1 GL 1 N 128 5
d.h. die Lok mit der Adresse 1 ist eine NMRA kompatibler Dekoder mit 128 realen Fahrstufen und 5 Funktionen.
Diese Gerätegruppe ist nur im Bus 0 definiert. Zulässig sind die Befehle TERM und RESET. Der Grundzustand ist RUNNING.
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 TERM 0
SERVER bewirkt. Eine Quittung (200 OK) 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.
TERM 0 SERVER
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 200 OK gesendet. Sessions im INFO Modus
werden über den laufenden TERM unterrichtet.
RESET 0 SERVER
Re-initialisiert den Server. Alle (aktiven) Geräte werden
mittels RESET in den Grundzustand versetzt. Während eines RESET
MÜSSEN alle Kommandos abgewiesen werden (413 temporarily
prohibited). Bestehende Sessions, auch im Handshake, bleiben
unberührt.
100 INFO 0 SERVER <Zustandsinfo>
Informiert über den aktuellen Zustand des Servers. Folgende Meldungen sind definiert:
Im Infomodus werden unidirektional alle Veränderungen aller Geräte vom Server 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; der Server KANN in diesem Fall die Verbindung seinerseits beenden.
Der Infomodus sendet alle Angaben so schnell wie möglich. Sie werden genauso wie die entsprechenden Angaben des Kommandomodus (siehe Antworten auf GET Befehle) immer mit dem Zeitstempel versehen. Es werden ausschließlich INFO Angaben gesendet. Insbesondere werden die Wirkungen von Kommandos erst dann gemeldet, wenn sie entweder vom Aktor (Dekoder) bestätigt wurden bzw. wenn sie erfolgreich an die Anlage übermittelt wurden (Wenn es keine Bestätigungen von der Anlage geben kann).
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.
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:
FB Alle Geräte, die im Zustand 0 sind, werden nicht gemeldet.
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.
POWER Der Zustand der Energieversorgung MUSS angegeben werden.
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.
LOCK Alle derzeit gelockten Geräte werden gemeldet.
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.
Bei der Initialisierung und Beendigung von Bussen MÜSSEN die
jeweils definierten 101 INFO-Meldungen generiert
werden. Bei der TERMinierung die 102
INFO-Meldungen.
Es werden keine sicherheitsrelevanten Maßnahmen vorgesehen.
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; siehe Collected Algorithms from CACM #199)
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.