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.

Änderungen gegenüber der vorherigen Version werden mit einem farbigen Strich am rechten Rand markiert. Dabei bedeutet rot Neues, grün wesentliche (inhaltliche) Änderungen, und blau Weglassungen. Alle geänderten Abschnitte sind grau hinterlegt. Dies gilt auch für Abschnitte mit textlichen Korrekturen, die keine extra Randmarkierung haben. Korrekturen von Tipfehlern werden nicht markiert.

Hier werden die Eigenschaften beschrieben, die eine Serverimplementierung ausmachen, das heißt, welche Möglichkeiten ein Server seinen Clients zur Verfügung stellt.

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>

Die Versionsinformation sollte als erstes in einer Konfigurationsdatei stehen.

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>

Befehle des Clients an den Server, direkte Antworten des Servers darauf.
Rückmelde Port
Statusänderungen von Rückmelde Modulen.
Info Port (Broadcast Kanal)
Statusänderungen von Lok- und Schaltdekodern, Modellzeit.

Unidirektional vom Server zum Client
Bidirektional

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

Überschrift: '= Server Commands ='

Format: SCMD <command>

Befehl zur Neu-Initialisieung des Servers.
Befehl zum Beenden des Servers.

Digitalstrom über SET POWER [ON/OFF] ein-/ausschalten
Aktueller Befehl in SRCP (ab Version 0.???)
Digitalstrom über STARTVOLTAGE/STOPVOLTAGE schalten
Kompatibilität zu früheren Versionen des SRCP

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>

Befehl zum Setzen eines Wertes.
Befehl zum Ermitteln eines Wertes.
Befehl zum Warten bis ein bestimmter Zustand erreicht wird.
Befehl zum Initialisieren von Geräte(gruppen).
Befehl zum Aufheben von mit INIT getroffenen Einstellungen.

Befehl zum Programmieren eines Wertes eines Dekoders.
Befehl zum Lesen eines Wertes eines Dekoders.
Befehl zum Überprüfen eines Wertes eines Dekoders.

Befehl zum Ermitteln von Konfigurationsinformationen.

Generic Loco (Lokdekoder) [SET, GET, WRITE, READ, VERIFY]
Generic Acessory (Schaltdekoder) [SET, GET, WRITE, READ, VERIFY]
Feedback (Rückmelder) [GET, WAIT, INIT]
Zeitnormal (Modellzeit) [SET, GET, WAIT, INIT]
Energieversorgung der Modellanlage [SET, GET]

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

Eine Kombination Befehl - Argument, die nicht eingetragen ist, wird nicht unterstützt. Lediglich der Befehl SET ist zwingend vorgeschrieben, alle anderen können implementiert werden.
Der Befehl GET wird meistens unterstützt, der Befehl WAIT falls Rückmelder oder Modellzeit unterstützt werden. Die Befehle WRITE, READ, VERIFY dienen dem Programmieren von Dekodern. Sie werden nur dann unterstützt, wenn ein Server diese Funktionalität bereitstellt. Der Befehl CONFGET wird natürlich nur dann unterstützt, wenn ein Server das CRCF für die zentrale Konfiguration benutzt.

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>

Protokolle nach den Märklin/Motorola Standards.
Protokolle nach den NMRA-DCC Standards.

Protokolle nach den Trix Selectrix Standards.
Protokolle nach den Fleischmann FMZ Standards.
Protokolle nach den ZIMO Standards.

Der Punkt ist durch geeignete Buchstaben/Ziffern zu ersetzen. Siehe dazu die aktuelle Spezifikation des SRCP. Die Werte für Selectrix, FMZ und ZIMO sind reserviert für zukünftige Entwicklungen (Intellibox, Twin-Box, ...).

Höchste Adresse, die von diesem Protokoll unterstützt wird. Aktuelle Werte für den Adressbereich sind 80, 99, 256, 9999. Ein Adressbereich beginnt immer bei der Adresse 0.

Höchste Fahrstufen, die von diesem Protokoll unterstützt wird. Aktuelle Werte für die höchste Fahrstufe sind 14, 27, 28, 30, 128. Ein Fahrstufenbereich beginnt immer bei der Fahrstufe 0.

Zahl der Zusatzfunktionen, die von diesem Protokoll unterstützt werden. Aktuelle Dekoder untertützen 0, 2, 4, 8 Zusatzfunktionen. Es wird implizit davon ausgegeangen, dass eine Standardfunktion immer implementiert ist.

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>

Protokoll nach den Märklin/Motorola Standards.
Protokoll nach den NMRA-DCC Standards.

Protokoll nach den Trix Selectrix Standards.
Protokoll nach den Fleischmann FMZ Standards.
Protokoll nach den ZIMO Standards.

Höchste Adresse, die von diesem Protokoll unterstützt wird. Aktuelle Werte für den Adressbereich sind ???, 4096. Ein Adressbereich beginnt bei der Adresse 1.

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>

Rückmelde-Module aus dem Lenz System.
Rückmelde-Module aus dem Digitrax System (LocoNet).
Rückmelde-Module aus dem Trix Selectrix System.
Rückmelde-Module aus dem Fleischmann FMZ System.
Rückmelde-Module aus dem ZIMO System.

Höchste Adresse, die für diesen Modultyp zulässig ist. Ein Nummerbereich beginnt mit (0 | 1) ???.

Dies kann erst dann spezifiziert werden, wenn entsprechende Definitionen in SRCP vorliegen.

Hier werden die Eigenschaften beschrieben, die ein tatsächliches Gerät (Lok-, Schaltdekoder, Rückmelde Modul) hat. Das heißt, welche Funktionen von einem Dekoder oder Modul tatsächlich realisiert werden. Dies kann ggfs. weniger sein, als das Protokoll erlaubt. Weiter gibt es einige Parameter, die nur für die Clients von Interesse sind (<d_type>, <name>, ...). Solche Parameter stehen am Ende der Parameterliste.

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.

Adresse dieses Dekoders unter dem gewählten Protokoll. Multiprotokoll-Dekoder dürfen für jedes Protokoll eine andere Adressen benutzen.

Höchste Fahrstufen, die von diesem Dekoder unterstützt wird. Für Funktionsdekoder ist dieser Wert ggfs. auf 0 zu setzen.

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.

Modus (P = Programmiergleis, F = on the Fly [im Betrieb])
WRITE- Befehl (W = unterstützt)
READ- Befehl (R = unterstützt)
VERIFY-Befehl (V = unterstützt)

Wird eine Funktion nicht unterstützt, so ist statt dessen das Zeichen '-' (= none) zu setzen. Beispiele:
"PW--R--" Nur Register auf dem Programmiergleis schreiben.
"FWR-RV-" Register + Variablen im laufenden Betrieb lesen + schreiben.
"-------" Nicht über Digitalbefehle programmierbar.

Adresse, unter der dieser Dekoder mit "Protocol by Server" angesprochen wird. Dekoder, die über mehrere Protokolle / Adressen angesprochen werden, sollen jeweils die selbe PS-Adresse verwenden.
Durch <ps_addr> wird eine virtuelle Adresse definiert. Da im SRCP (ab 0.7.1) keine Beschränkung für die Größe einer Adresse besteht, kann man die in Deutschland ab Epoche IV übliche sechstellige Zahl für eine Lok verwenden. Dies völlig unabhängig davon, wieviel Adressen der Dekoder real unterstützt.

Virtuelle Höchstgeschwindigkeit: Dieser Wert wird in einem Server zusammen mit einem Wert V (<= V_Max) für die Soll-Geschwindigkeit dazu benutzt die reale Fahrstufe zu berechnen. Im SRCP wird keine Vorgabe über die Masseinheit dieses Wertes gemacht. Empfehlenswert ist eine Orientierung an der Vorbild-Geschwindigkeit, also in km/h.
Hinweis: Wird dieser Wert auf 0 gesetzt, so verwendet der Server den Wert von V als reale Fahrstufe.

Kennung für den Dekodertype: Dekoder eines Typs erhalten die gleiche Kennung. Die Kennung muss ein Wort sein. Das heisst es darf kein Leerzeichen oder Tabultorzeichen enthalten. Zur optischen Gliederung ist ggfs. das Zeichen '-' einzusetzen. Sinnvollerweise hält man sich an die Bezeichnung des Hersteller.
Soll keine Kennung angegeben werden, ist statt dessen das Wort "---" zu verwenden.

Eindeutiger Name für diesen Lok-/Funktions-Dekoder: Der Name muss ein Wort sein. Das heisst es darf kein Leerzeichen oder Tabultorzeichen enthalten. Zur optischen Gliederung ist ggfs. das Zeichen '-' einzusetzen. Beispiele: "V188-003", "Berghexe", "Zuckersusi".
Soll keine Name angegeben werden, ist statt dessen das Wort "---" zu verwenden.
Dekoder, die über mehrere Protokolle angesprochen werden können, dürfen den gleichen Namen verwenden.

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

Kennung für den Dekodertype: Dekoder eines Typs erhalten die gleiche Kennung. Die Kennung muss ein Wort sein. Das heisst es darf kein Leerzeichen oder Tabultorzeichen enthalten. Zur optischen Gliederung ist ggfs. das Zeichen '-' einzusetzen. Sinnvollerweise hält man sich an die Bezeichnung des Hersteller.
Soll keine Kennung angegeben werden, ist statt dessen das Wort "---" zu verwenden.

Eindeutiger Name für diesen Schaltdekoder: Der Name muss ein Wort sein. Das heisst es darf kein Leerzeichen oder Tabultorzeichen enthalten. Zur optischen Gliederung ist ggfs. das Zeichen '-' einzusetzen . Beispiele: "Bahnhof-Links", "Gleis-1-2", "Abzweig-Abc".
Soll keine Name angegeben werden, ist statt dessen das Wort "---" zu verwenden.

Für einen Einzeldekoder gilt <addr_min> = <addr_max> Auf diese Art kann je nach Wunsch eine Gruppendefiniton aller Ausgänge des Schaltdekoders oder eine Einzeldefinition eines Ausgangs erfolgen.

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

Kennung für den konkreten Typ eines Rückmelde Modules: Hier dient sie hauptsächlich zur Unterscheidung verschiedener Lieferanten eines Modultyps. Rückmelder eines Typs erhalten die gleiche Kennung. Die Kennung muss ein Wort sein. Das heisst es darf kein Leerzeichen oder Tabultorzeichen enthalten. Zur optischen Gliederung ist ggfs. das Zeichen '-' einzusetzen. Sinnvollerweise hält man sich an die Bezeichnung des Hersteller.
Soll keine Kennung angegeben werden, ist statt dessen das Wort "---" zu verwenden.

Eindeutiger Name für dieses Rückmelde Modul: Der Name muss ein Wort sein. Das heisst es darf kein Leerzeichen oder Tabultorzeichen enthalten. Zur optischen Gliederung ist ggfs. das Zeichen '-' einzusetzen. Beispiele: "GBM-Bonn", "GBM-Strecke", "Weichen-Bhf".
Soll keine Name angegeben werden, ist statt dessen das Wort "---" zu verwenden.

Dies ist der Platz für Festlegungen, die übergreifend sind.
Als erstes wird ein Bereich für die Zuordnung von Kurzformen zu Langtexten definiert.
Weitere übergreifende Funktionen folgen nach Bedarf.

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 #5.1 Konfigurationstypen)

Sprache (z.B. de := deutsch, en := englisch). Für <lang> werden die im Internet üblichen zwei Zeichen Abkürzungen verwendet.

Alle weiteren Worte in dieser Zeile sind dann der Meldungstext.
Die Reihenfolge innerhalb einer Tabelle ist ohne Bedeutung. Sinnvollerweise wird man jedoch die Einträge für eine Sprache zusammenhalten und alphabetisch nach den Kürzeln sortieren.

ITXT <short> <lang> <freetext> (INFO liefert eine Zahl zurück)
LTXT <short> <lang> <freetext> (Zuordnung der Sprachen)

FTXT ist eine optionale Tabelle, insbesondere werden in verschiedenen Sprachen unterschiedliche Abkürzungen verwendet.
ITXT und LTXT sollen vollständig sein.

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 #2 Servereigenschaften). 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 #3 Geräte und Eigenschaften) 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.

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.