CRCF - Common Railroad Configuration Files 0.2.0: Unterschied zwischen den Versionen

Die CRCF beschreiben einen Reihe von Dateien zur Konfiguration von Serverprozessen zur Steuerung von digitalen Modelleisenbahnen. Clientprozesse können auf diese Informationen über einen entsprechenden Auskunftsbefehl zugreifen.

Die in CRCF zu speichernden Informationen ergeben sich aus dem Bedarf des SRCP (Simple Railroad Command Protocol) wie von Torsten Vogt & anderen definiert. In diesem Sinne sind die CRCF eine Ergänzung zum SRCP.

Ziel ist es eine klare, auch vom Menschen lesbare Basis für die Fähigkeiten einer konkreten Serverimplementierung einerseits und eine Beschreibung der verwendeten Dekoder mit ihren spezifischen Eigenschaften andererseits zu schaffen.

Diese Fassung basiert auf SRCP Version 0.7.1.

Alle Informationen werden einzeilig mit variabler Länge gespeichert. Eine Zeile wird mit dem Zeichen '\n' (line feed, LF, #10) abgeschlossen. Ein vorangestelltes '\r' (carriage return, CR, #13) wird akzeptiert. Jede Informationszeile besteht aus Worten, die durch Whitespace (Leerzeichen, Tabulatoren) getrennt sind.

Die Worte der Informationszeilen können aus der Menge der Zeichen { '0', .., '9', '-', 'A', .., 'Z', 'a', .., 'z' } gebildet werden. Der Server wertet die Informationszeilen case-sensitive aus, d.h. zwischen Groß- und Kleinbuchstaben wird unterschieden.

Kommentarzeilen beginnen mit dem Zeichen '#' und enden mit dem Zeilenende. Sie werden ebenso ignoriert wie Leerzeilen (nur White Spaces und CR, LF). Sie dürfen alle druckbaren Zeichen des ASCII Zeichensatzes enthalten. Sie dienen ausschliesslich der besseren Lesbarkeit durch einen Menschen.

Einzelne Bereiche werden durch Überschriften getrennt. Diese beginnen (Zeilenanfang) mit '= ' und enden mit ' ='. Weiterer Text in der Überschriftzeile ist Kommentar und wird ignoriert.

Alle Informationszeilen beginnen mit einer Kennung aus vier Buchstaben, die die Art der Information kennzeichnet. Die weiteren Angaben sind je nach Art der Information unterschiedlich. Informationen über Protokolle enthalten eine weitere Angabe zur genauen Identifizierung (Protokoll/Modultyp). Informationen über Dekoder und Rückmelder enthalten zwei weitere Angaben zur genauen Identifizierung (Protokoll/Modultyp + Adresse/Portnummer). Für jede vom Server unterstützte Funktion / Eigenschaft gibt es eine Informationszeile. Für jeden dem Server bekannten Dekoder / Rückmelder gibt es eine Informationszeile.

Informationszeilen, die unvollständig oder offensichtlich falsch sind werden vom Server ignoriert. Eine (summarische) Fehlermeldung sollte in diesem Fall vom Server beim Start ausgegeben werden. In Protokoll- oder Trace-Dateien kann ggfs. jeder Fehler einzeln aufgeführt werden.

Die Informationen sind in Bereiche aufgeteilt. Jeder Bereich hat eine Überschrift. Alle Informationen aus einem Bereich müssen hinter dieser Überschrift stehen. Stehen sie an einer anderen Stelle, so werden sie als Fehler gewertet. Innerhalb eines Bereichs ist eine angemessene Ordnung sinnvoll (Name | Protokoll | Adresse | ...). Diese Ordnung ist für die bessere Lesbarkeit und daher nicht zwingend vorgeschrieben. Es steht im Ermessen des Erstellers, welche Ordnung, wenn überhaupt, er/sie benutzt.

An einigen Stellen sind Werte reserviert, die im SRCP noch nicht festgelegt sind, da es zur Zeit noch keine Server gibt, die das unterstützen. Diese Werte sind als Platzhalter zu betrachten, sie können sich noch ändern. Solche reservierten Werte sind mit kursiver Schrift markiert.

Überschrift: '= Version ='

Es gibt genau eine Zeile mit den Informationen über die Version des Servers, des verwendeten SRCP und CRCF.

Format: VERS <name> <vers> SRCP <srcp> CRCF <crcf>

Welche Kanäle werden von einer Serverimplementierung zur Kommunikation mit Clients benutzt.
Dies ist durch das SRCP weitgehend festgelegt.

Überschrift: '= Ports ='

Format: PORT <port> <source>

Welche Befehle werden von einer Server zu seiner Steuerung akzeptiert.
Dies ist durch das SRCP weitgehend festgelegt.

Überschrift: '= Server Commands ='

Format: SCMD <command> 

Welche Befehle werden von einer Server zur Steuerung der Digitalanlage akzeptiert.
Dies ist durch das SRCP weitgehend festgelegt.

Überschrift: '= General Commands ='

Format: GCMD <command> <group>

Beim Befehl CONFGET werden statt der Gerätegruppen die Konfigurationstypen als Argument verwendet. Siehe dazu den Abschnitt 5.1 Konfigurationstypen.

Welche Protokolle für Lokdekoder werden von einem Server akzeptiert. (Funktionsdekoder werden wie Lokdekoder behandelt.)
Dies ist zwar durch das SRCP festgelegt, jedoch muss ein Server nicht alle in SRCP beschriebenen Protokolle unterstützen (z.B. Ansteuerung einer systemspezifischen Zentraleinheit). Weiter sind bereits Werte für noch nicht unterstützte Protokolle reserviert.

Überschrift: '= Protocols Loco & Function ='

Format: PRGL <prot> <addr_max> <step_max> <dir> <nro_f>

Welche Protokolle für Schaltdekoder werden von einem Server akzeptiert.
Dies ist zwar durch das SRCP festgelegt, jedoch muss ein Server nicht alle in SRCP beschriebenen Protokolle unterstützen (z.B. Ansteuerung einer systemspezifischen Zentraleinheit). Weiter sind bereits Werte für noch nicht unterstützte Protokolle reserviert.

Überschrift: '= Protocols Accessory ='

Format: PRGA <prot> <addr_max>

Welche Rückmelde Module und Anschlussarten werden von einem Server akzeptiert.
Dies ist zwar durch das SRCP festgelegt, jedoch muss ein Server nicht alle in SRCP beschriebenen Module oder Arten unterstützen. Weiter sind bereits Werte für noch nicht definierte Protokolle reserviert.

Überschrift: '= Feedback Types ='

Format: PRFB <module-type> <port_max> <port_inc>

Überschrift: '= Locomotive & Function ='

Format: DCGL <prot> <addr> <step> <dir> <func> <prog> <ps_addr> <V_max> <d_type> <name>

Wie im Abschnitt 2.5 Protokolle Lokdekoder definiert. Dekoder, die über mehrere Protokolle angesprochen werden können, haben für jedes Protokoll einen Eintrag. PS (Protocol by Server) ist hier nicht zulässig, da es sich um reale Dekoder handelt.

Die Funktionen werden durch ein Wort <func> beschrieben, das aus Zeichenpaaren aufgebaut ist:
Das erste Zeichenpaar besteht aus zwei Ziffern und gibt die Zahl m der verfügbaren Funktionen inkl. der Standardfunktion an. Die Zeichenpaare 2 bis m+1 sind jeweils ein Kürzel für die Art der Verwendung der Funktionen F0 - Fn. [ m = n+1 ! ]. F0 ist dabei die Standardfunktion, F1 -Fn sind die Zusatzfunktionen. Das zweite Zeichenpaar bezeichnet also die Verwendung der Standardfunktion, das dritte der ersten Zusatzfunktion. Wird eine Funktion nicht benutzt so steht an der Stelle des Kürzels das Zeichenpaar '--'. Damit ist sowohl klar, wieviele Funktionen verfügbar sind, als auch, welche davon wirklich benutzt werden. Das minimale Wort für Funktion ist damit das Zeichenpaar '00' (keinerlei Funktion).
Den Kürzeln wird in der Tabelle FTXT ein Langtext zugeordnet. Siehe dazu den Abschnitt 4.1 Langtexte.

Überschrift: '= Accessory ='

Format: DCGA <prot> <addr_min> <addr_max> <d_type> <name>

Wie im Abschnitt 2.6 Protokolle Schaltdekoder" angegeben.

Überschrift: '= Feedback Units ='

Format: DCGA <modul-type> <port_min> <port_max> <d_type> <name>

Wie im Abschnitt 2.7 Protokolle Rückmelder definiert.

Im Laufe der Diskussion um das CRCF hat sich gezeigt, dass es notwendig ist sowohl Kurzformen (=Abkürzungen), als auch Langformen (=Text) für bestimmte Informationen zur Verfügung zu stellen. Mit den Tabellen in diesem Abschnitt wird eine Zuordnung zwischen Abkürzungen und zugehörigen Text hergestellt.
Je nach Art der Information kann diese Tabelle zwingend sein, das heißt nur Werte in der Tabelle sind zulässig, oder optional, das heißt es können auch Abkürzungen verwendet werden, die nicht in der Tabelle enthalten sind.

Überschrift: '= Messages ='

Format: <TEXT-TYPE> <short> <lang> <freetext>

Kennung für die Art der Zuordnung.
Für den Befehl CONFGET ist dies ein Konfigurationstyp. (Siehe Abschnitt 5.1)

FTXT <short> <lang> <freetext> (Funktionen in Lokdekodern)

 FTXT    Da    de    Dampf
 FTXT    Sl    de    Spitzlicht
 FTXT    Pf    de    Pfeife
 FTXT    Gl    de    Glocke
 FTXT    Tl    de    Triebwerksbeleuchtung
 FTXT    Lu    de    Lüfter
 FTXT    Sa    de    Stromabnehmer
	...
 FTXT    ST    en    Steam         (Dampf)
 FTXT    Hl    en    Headlight     (Spitzlicht)
 FTXT    Wh    en    Whistle       (Pfeife)
 FTXT    Bl    en    Bell          (Glocke)
 FTXT    Nb    en    Numberboard   (Nummerntafel)
	...

ITXT <short> <lang> <freetext> (INFO liefert eine Zahl zurück)

 ITXT    -1    de    nicht unterstützt
 ITXT    -2    de    keine Daten
 ITXT    -3    de    Zeitlimit überschritten

 ITXT    -1    en    unsupported
 ITXT    -2    en    no data
 ITXT    -3    en    timeout

LTXT <short> <lang> <freetext> (Zuordnung der Sprachen)

 LTXT    de    de    deutsch
 LTXT    en    de    englisch
 LTXT    fr    de    franzoesisch

 LTXT    en    en    english
 LTXT    fr    en    french
 LTXT    de    en    german

 LTXT    en    fr    anglais
 LTXT    fr    fr    francais
 LTXT    de    fr    allemand

Der Befehl CONFGET dient dazu, Clients die Möglichkeit zu geben beim Server nachzufragen, welche Fähigkeiten er hat. (Siehe Abschnitt 2) Diese Angaben sind verbindlich.

Als zweites kann mit diesem Befehl abgefragt werden, welche Lok-, Funktions-, Schalt-Dekoder und Rückmelde Module dem Server bekannt sind. (Siehe Abschnitt 3) Diese Information dient (mehreren) Clients dazu einen gleichen Informationsstand zu haben. Diese Informationen sind jedoch nicht verbindlich.

• Die Informationen müssen nicht vollständig sein.
• Nicht alle bekannten Loks müssen sich auf einer Anlage befinden.
• Es können sich "Fremdloks" auf der Anlage befinden, die natürlich nicht in der Konfigurationsdatei beschrieben sind.

Informationen zu Schaltdekodern und Rückmeldern als ortsfeste Bauteile hingegen sollten (in der Regel) korrekt und vollständig sein.

Anmerkungen:
Die Spezifikation des Befehl CONFGET gehört eigentlich in das SRCP (Simple Railroad Command Protocol). Da der Befehl CONFGET jedoch unmittelbar von den Festlegungen im CRCF abhängt, wird er vorerst hier beschrieben. Der Befehl CONFGET hat nur dann Sinn, wenn die Konfigurations Dateien existieren und nach dem CRCF gestaltet sind.

Ein Befehl CONFSET zum Setzen von Konfigurations Informationen ist zur Zeit nicht definiert. Es ist nicht klar, ob dafür ein Bedarf existiert. Wie auch immer, sinnvoll wäre ein solcher Befehl nur für die Informationen zu Lokdekodern wie sie in Abschnitt 3.1 festgelegt sind. Die Servereigenschaften (siehe Abschnitt 2) ändern sich nicht, solange ein Server läuft. Auch die Angaben zu einer (zukünftigen) Beschreibung des Anlagenlayouts ändern sich nicht während des laufenden Betriebs. Ein Lok jedoch kann ohne weiteres hinzugefügt, entfernt oder umprogrammiert werden.

INFO CONF <conf-type> [<spec_1>] [<spec_2>] [.*]

[.*] steht dabei für alle weiteren Angaben entsprechend dem Konfigurationstyp. 

Hinweise:
[<conf-type>] ist wie im Abschnitt 5.1 Konfigurationstypen definiert.
[<spec_1>] und [<spec_2>] sind wie im Abschnitt 5.2 Befehl CONFGET definiert.
Die Antwort auf einen Befehl CONFGET kann mehrere Zeilen "INFO CONF ..." umfassen. Ein Client muss darauf vorbereitet sein, diese sinnvoll zu verarbeiten.

In der Diskussion um das SRCP wurde mehrfach der Wunsch nach einer Datei für die Konfiguration geäussert. Dies ist für eine einzige Serverimplementierung sicher nicht zwingend. Werden jedoch unterschiedliche Server angeboten, so ist es für alle weiteren Programme (Clients, Middleware, ...) sinnvoll, die Eigenschaften eines Servers ermitteln zu können.

Weiter wurde angeregt eine gemeinsame Datenbasis für alle Clients bezüglich Lokdekoder, Schaltdekoder und Rückmelder zu haben. Diese Datenbasis, soll ebenso wie die Informationen über die Eigenschaften des Servers über einen SRCP-konformen Befehl abgefragt werden können.

Diesen Wünschen soll mit dieser Definition Rechnung getragen werden.

Bisher ist nichts zur Aufteilung der Konfigurationsdaten auf Dateien gesagt worden. Dieser Punkt ist bewusst offengelassen, da ich dafür keinen Vorschlag machen will. Sinnvoll ist sicherlich eine Aufteilung in eine Datei für die Servereigenschaften (siehe Abschnitt 2) und eine Datei für die Dekoder und Rückmelder (siehe Abschnitt 3). Sollte eines Tages Informationen über das Layout einer Modellbahn Anlage definiert werden, so ist dafür ebenso eine weitere Datei sinnvoll.

Ob eine weitere Aufteilung wünschenswert ist soll die Diskussion zeigen. 
Um Namensvorschläge wird gebeten!

Für die Definition der Dekoder und Rückmelder sind Namen eingeführt worden. Dies ist ein Konzept, dass im SRCP bisher nicht existiert und dort auch nicht notwendig ist. Es dient dazu, dass alle Clients Dekoder und Rückmelder mit gleichen Namen darstellen können.
Namen wie "V188-003" oder "Abzweig-Valkenburg" sind für einen Mensch als Benutzer der Clients sicherlich einfacher zuzuordnen als M3-17 oder N-327.

Ebenso sind Typen zur Klassifizierung verschiedener Dekoder- / Rückmeldertypen eingeführt worden. Auch diese sind in SRCP weder definiert noch notwendig. Sie dienen hauptsächlich der Dokumentation. Inwieweit ein Client diese Information verwendet bleibt ihm überlassen.

2 Servereigenschaften , 3 Geräte und Eigenschaften :
Einige Parameternamen geändert: Das Zeichen '-' durch '_' ersetzt, sowie in einigen Parameternamen das Zeichen '_' eingefügt. Die Abschnitte 5.1 Konfigurationstypen und 5.2 Befehl CONFGET wurden entsprechend angepasst.

2.1 Serverversion :
Angabe der verwendeten CRCF Version hinzugefügt

2.3 Serverbefehle :
TIME (= Unterstützung einer Modellzeit) hinzugefügt

2.4 Allgemeine Befehle :
Argument <group> hinzugefügt. Damit können Befehle und die Gerätegruppen auf die sie angewendet werden definiert werden. Die Abschnitte 5.1 Konfigurationstypen und 5.2 Befehl CONFGET wurden entsprechend angepasst.

2.5 Protokolle Lokdekoder :
Das Protokoll PS (Protocol by Server) hinzugefügt.

3.1 Lokdekoder , 3.2 Schaltdekoder , 3.3 Rückmelder :
Parameter <name> an das Ende der Liste gerückt.
Soll kein Name angegeben werden, so ist das Wort "---" statt des Zeichens '-' zu verwenden.
Der Parameter <d_type> ist nicht mehr optional.
Soll keine Typkennung angegeben werden, so ist jetzt das Wort "---" zu verwenden.

3.1 Lokdekoder :
Beim Parameter <prog> wird nun das Zeichen '-' statt 'N' für eine nicht vorhandene Funktion verwendet. (besser zu erkennen)
Parameter <ps_addr> als Adresse für das "Protocol by Server" eingeführt. (Vorschlag Martin Ostermann)
Parameter <V_max> für eine virtuelle Höchstgeschwindigkeit eingeführt.
Die Funktionen werden jetzt im Parameter <func> detailiert beschrieben, (Vorschlag Martin Ostermann und Matthias Trute)

4.1 Langtexte :
Dieser Abschnitt ist neu. Er definiert, was in Version 0.1 als Idee vorgeschlagen wurde.
Ziel ist eine Zuordnung zwischen Abkürzungen und Langtext einzuführen. Dies ist als Ergänzung zur Definition der Funktionen aus Abschnitt 3.1 Lokdekoder notwendig geworden. Bei dieser Gelegenheit wurden gleich Definition für INFO und Sprache mit eingeführt. Die Abschnitte 5.1 Konfigurationstypen und 5.2 Befehl CONFGET wurden entsprechend angepasst.

5.1 Konfigurationstypen , 5.2 Befehl CONFGET :
Diese Abschnitte wurden an die Änderungen in den Abschnitten 2 Servereigenschaften (Parameternamen, TIME, neue Parameter, neues Protokoll, ...), 3 Dekoder und Eigenschaften (Parameternamen, neue Parameter, Änderung von Parametern, neues Protokoll, ...), 4 Sonstiges (Zuordnung von Langtexten) angepasst.

Vieles an der internen Struktur vereinfacht, so dass dies Dokument jetzt etwas kleiner ist und damit schneller zu laden und darzustellen ist.