Common Railroad Configuration Format (CRCF)

Author: Jeroen Vreeken
Date: 2019-10-16
Version: 0.2
Status: Draft

1 Terms

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

2 Introduction

The CRCF protocol was first discussed at http://www.der-moba.de/index.php/SRCP-Erweiterungen , this specification aims to formalize it.

CRCF is a protocol which extends the Simple Railroad Command Protocol (SRCP). CRCF clients exchange messages using the GM device group. The GM device group was introduced in SRCP version 0.8.4, CRCF thus depends on an SRCP implementation with that version or higher. CRCF enables the exchange of configuration data between SRCP clients. It is used for data which is typically not of interest to the SRCP server but which is common between the various clients.

An SRCP client can act as an CRCF client, server or both. CRCF defines requests and responses. In order to send CRCF messages a SRCP client MUST open a command session. In order to receive CRCF messages a SRCP client MUST open an information session. A typical client will thus need to open both a command and an information session.

+---------------------+      +---------------------+
| CRCF implementation |      | CRCF implementation |
+---------------------+      +---------------------+
   |               A	     	|		A
   |               |	     	|		|
command       information    command	   information
session         session      session	     session
   |               |	     	|		|
   V               |	     	V		|
+--------------------------------------------------+
|     SRCP server                                  |
+--------------------------------------------------+

3 Definitions

The following data format definitions will be used in this document:

3.1 Alphanumeric value

Alphanumeric which are URL encoded following RFC 2396.

3.2 Numeric value

A numerical value with attribute specific limits. Negative number MUST begine with a minus sign '-'. An attribute MAY allow non integer numbers. The decimal point MUST be denoted with a dot '.'. A base 10 exponent MAY be given for non integer numbers. The character 'e' or 'E' MUST be used as separator between the significant digits and the exponent.

3.3 UUID

A 36 character UUID following RFC 4122.

3.4 Tuple

Multiple data values. An attribute MUST specifiy any limit to the tuple size and the data formats. The values MUST be separated by a comma ','.

4 CRCF messages

A CRCF message has the following format:

GM <send_to> <reply_to> CRCF <actor> <actor_id> <method> <attribute> [<attribute_value>]

4.1 send_to

The send_to session id MAY be targeted at a specific information session when the message is a response to an request. A message targeted at all information sessions MUST be targeted at session id 0.

4.1 reply_to

Session id of an INFO session to which message replies SHOULD be directed (if any). Alternatively 0 MUST be used to sollicit replies to all INFO sessions.

4.2 CRCF

All messages must start with the four letters 'CRCF' to identify it as an CRCF message and allow distinction between different communication protocols using SRCP GM communication. Any messages not starting with this identifier MAY be ignored by an CRCF implementation.

4.3 actor

Actor type this message is directed to or originating from.

4.4 actor_id

Id of the specific actor this message is directed to or origination from. An actor id is an UUID. An actor MAY be a static property in which case it MUST stay the same over multiple sessions. An actor id MUST not collide with any other actor id.

Certain actor types MAY allow the use of a wildcard UUID for certain request methods when broadcasted. This MUST be specified specifically for those methods. '00000000-0000-0000-0000-000000000000' MUST be used as wildcard UUID. Typically this option will be used in order to discover actors which are not referenced by other actors.

4.5 method

The method which is requested or which has generated the result.

4.5.1 INFO

Response message.

4.5.2 SET

Setting values. When the request is not directed at session id 0 the receiving CRCF implementation MUST reply with either an INFO or an ERROR message.

4.5.3 GET

Getting values. When the request is not directed at session id 0 the receiving CRCF implementation MUST reply with either an INFO or an ERROR message. The attribute_value field MUST not be used.

4.5.4 LIST

Request a list. This is only possible with attributes which can have multiple values. The response MUST be first the size of the list. This will be done by an INFO reply where the attribute is suffixed with COUNT and the attribute_value will be set to the list length. Following the this length N INFO replies with the list entries MUST be send were N is the length of the list. When the request can not be answered an ERROR message MUST be send.

4.5.5 ADD

Add a new entry to a list. The new entry will be added to the end of the list. When the request is not directed at session id 0 the receiving CRCF implementation MUST reply with either an INFO or an ERROR message.

4.5.7 REMOVE

Remove an entry from a list. The entry will be removed from the list. Any entries following will move up one position in the list. When the request is not directed at session id 0 the receiving CRCF implementation MUST reply with either an INFO or an ERROR message.

4.5.8 CLEAR

Clear all entries from a list. When the request is not directed at session id 0 the receiving CRCF implementation MUST reply with either an INFO or an ERROR message.

4.5.9 ERROR

When an request can not be successfully fullfilled an ERROR reply MUST be send. The only exception is when a request's send_to field was set to 0 or the actor_id was set to the wildcard UUID. An error code MUST be reported in the attribute field. The attribute_value field MAY be used for a error text. The error code MUST be a valid SRCP error code.

4.6 attribute

Attribute of the actor this message is directed at or comming from. Each actor MUST specify which attributes it has.

Some attributes are dynamic and may change over time. Others are static properties which never change. Each attribute MUST specify which attributes are dynamic and which are static.

4.7 attritbute_value

The value of the attribute. For each actor MUST specify the type of each of its attributes.

5 actors

Actors are objects with attributes which respond to and generate CRCF messages. Each actor MUST implement the ID attribute of the type UUID. Actors MAY reference other actors in their attributes. This reference SHALL also be of the type UUID.

Unless an actor is a 'root' object they should have one attribute refering to their 'parent' object. Any object can and MUST belong to a single root object.

5.1 STOCKDB

Rolling stock database of available vehicles such as locomotives or cars and their attributes.

Attributes which must be implemented:

name type static /
dynamic relation description

ID UUID static root

NAME alphanumeric static

VEHICLE UUID static static list of vehicles

TRAIN UUID dynamic dynamic list of trains

5.2 VEHICLE

An inseparable unit of rolling stock such as a Locomotive or car.

Attributes which must be implemented:

name type static /
dynamic relation description

ID UUID static

NAME alphanumeric static Description of the vehicle

STOCKDB UUID static parent Stock DB this vehicle belongs to.

DECODER UUID static list of decoders in this vehicle. The amount of decoders MAY be zero

V_MAX numeric static Maximum speed in km/h. Scaling will have to be applied. The specific scalling is not specified.

LENGTH numeric static Length of the unit in meters. This value SHALL be the actual length of the model from coupler to coupler. A value of '0' MAY be used if the length is unknown.

DETECTABLE boolean static Boolean value (0 or 1) indicating wether this vehicle is detected by feedback sensors.

POWERED boolean static Boolean value (0 or 1) indicating wether this vehicle is powered. Set to true (1) for actual locomotives or multiple units Dummys should also have this set to true, but for example cab cars have this attribute set to false (0).

ELECTRIC boolean static Boolean value (0 or 1) indicating wether this vehicle is powered by electricity. The value true (1) only makes sense if the POWERED attribute is also true.

IMAGE UUID static Image of the vehicle

5.3 DECODER

Attributes which must be implemented:

name type static /
dynamic relation description

ID UUID static

NAME alphanumeric static Description, e.g. decoder make and model.

VEHICLE UUID static parent Vehicle to which this decoder belongs

PROTOCOL UUID static List of supported protocols

5.4 PROTOCOL

Configuration data specific to a decoder's protocol

Attributes which must be implemented:

name type static /
dynamic relation description

ID UUID static

NAME alphanumeric static Protocol format. Valid values are SRCP GL protocol values for e.g.:
NMRA-DCC: 'N'

Motorola: 'M'

Selectrix: 'S'

Server: 'P'

VERSION alphanumeric static Protocol version.

DECODER UUID static parent Decoder which implements this protocol

ADDRESS numeric static Address

BUS numeric static Bus

SPEEDSTEPS numeric static number of speedsteps

REVERSE numeric static Boolean value (0 or 1) which is set to true (1) when the direction send to the decoder has to be reversed for proper locomotive operation.

SPEEDCALIBRATION tuple static Speed calibration. The tuple MUST have an even number of elements. Each pair will consist of an numeric value representing a speedstep and a floating point value of the locomotives speed in m/s at this speedstep. The tuple MAY have zero values if there is no calibration data available.

FUNCTION UUID static List of functions

5.5 FUNCTION

Attributes of a protocol's function.

Attributes which must be implemented:

name type static /
dynamic relation description

ID UUID static

NAME alphanumeric static Function description. See chapter 'Function names'

PROTOCOL UUID static parent Protocol this function belongs to

NUMBER numeric static Function number

MODE numeric static Trigger mode. Value MUST be 0 for switching or 1 for push button

5.5.1 Function names

A number of common function names has been defined. It is recommended to use these such that common behaviour can automatically be coupled with common functions.

Defined values are:

name

LIGHT_HEAD

LIGHT_INTERIOR

SHUNTING

INERTIA_DISABLE

AUDIO_ENGINE

AUDIO_HORN_LOW

AUDIO_HORN_HIGH

AUDIO_MUTE

5.6 TRAIN

A train is a collection of linked vehicles. Trains move as a single entity through sections of track.

Attributes which must be implemented:

name type static /
dynamic relation description

ID UUID static

NAME alphanumeric static

STOCKDB UUID static parent Stock DB this train belongs to.

VEHICLE tuple dynamic List of vehicles. Each entry in the list is a tuple with two elements. The first is a UUID of the vehicle, the second element is a numerical value representing the relative direction of the vehicle. The direction value MUST be 0 when the vehicle's direction is the same as the train's, and it MUST be 1 if the vehicles direction is reversed.

5.7 IMAGE

An image.

Attributes which must be implemented:

name type static /
dynamic relation description

ID UUID static root

NAME alphanumeric static

URL alphanumeric static URL pointing to an image

5.8 RWCC

Railway control center. A railway control center controls a number of sections. It monitors trains passing through these sections and will intervene when safety rules are violated.

Attributes which must be implemented:

name type static /
dynamic relation description

ID UUID static root

NAME alphanumeric static

SCALE numeric static Scaling factor use for this railway. Only the denominator shall be used. e.g. '87' for 1/87 HO scale.

SECTION UUID static List of sections which are controlled by this control center.

ROUTE UUID static List of routes which are controlled by this control center.

5.9 SECTION

Section of track. A section of track with section ends on its boundaries. Each section has a 'zero' location to which the section ends refer with their location. This location may be anywhere within the section. Section locations MAY be described both from left to right and from right to left, but all locations within a section MUST use the same direction.

Example section with four secion ends. In this example the locations are described
from left (negative) to right (positive).

                 |--\
                     \
|------------+-------+---------|
             \
              \----------|

^       ^    ^   ^   ^   ^     ^
|       |    |   |   |   |     |
|       |    |   |   |   |     Section end (location=1.0, reverse=false)
|       |    |   |   |   Section end (location 0.8, reverse=false)
|       |    |   |   switch
|       |    |   Section end (location 0.3, reverse=true)
|       |    switch
|       zero location
Section end (location=-1.0, reverse=true)

Note that this example is given to illustrate the different aspects,
in reality it is probably better to split it into two sections each with three ends.

Attributes which must be implemented:

name type static /
dynamic relation description

ID UUID static

NAME alphanumeric static

RWCC UUID static parent Control center this section belongs to.

FEEDBACK UUID static List of feedback sensors providing feedback on this section.

ACCESSORY UUID static List of accessories such as switches on this section.

OCCUPIED boolean dynamic Boolean indicating this section is occupied. The RWCC may set this value based on feedback sensors. This value may also be set by other clients. (e.g. in case the section is occupied by a vehicle which is not detected automaticly)

TRAIN tuple dynamic Train occupying this section. This attribute is a tuple with two elements. The first is a UUID of the train, the second element is a numerical value representing the relative direction of the train. The direction value MUST be 0 when the train's direction is positive in respect to the section locations. The direction value MUST be 1 when the train's direction is negative in respect to the section locations. When it is known that a train occupies a section this attribute MAY be set. When a route is requested for a train which contains occupied sections this attribute MAY be used by the RWCC to allow or deny the state of a route to change.

ELECTRIFIED boolean static Boolean indicating this section is equiped with overhead wire. A section with this attribute set to true may be used by electric vehicles.

SECTIONEND UUID static List of section ends.

SECTIONROUTE UUID static List of section routes.

5.10 FEEDBACK

Feedback sensor. A feedback actor maps to the 'FB' feedback sensor as defined by the SRCP protocol.

Attributes which must be implemented:

name type static /
dynamic relation description

ID UUID static

NAME alphanumeric static Protocol format. e.g. 'S88'

SECTION UUID static parent Section this feedback sensor provides feedback on.

ADDRESS numeric static Address

BUS numeric static Bus

5.11 SECTIONEND

A section end. Sections can have multiple ends. (A CRCF implementation MAY impose a sanity check to ensure each section has at least two setion ends.)

Attributes which must be implemented:

name type static /
dynamic relation description

ID UUID static

SECTION UUID static parent Section this end belongs to.

LOCATION numeric static Location in meters of the section end relative to the section zero point.

REVERSE numeric static Boolean value (0 or 1) which is set to true (1) when one would have to travel in reverse direction to cross this section end when starting at the section zero point.

SECTIONEND UUID static If the section is connected to another section via this section end this attribute MUST contain the id of the corresponding section end.

5.12 SECTIONROUTE

A route between two section ends. The section route describes the state where a train can travel between the two ends.

Attributes which must be implemented:

name type static /
dynamic relation description

ID UUID static

SECTION UUID static parent Section this section route belongs to.

SECTIONEND UUID static List of section ends connected by this section route.

ACCESSORYSTATE UUID static List of accessory states required to set this route.

V_MAX numeric static Maximum speed in km/h for this specific route through the section. Scaling will have to be applied. The specific scalling is not specified.

STATE numeric dynamic ?

5.13 ACCESSORY

Configuration data specific to an accessory decoder's protocol

5.14 ACCESSORYSTATE

An accessory may be set to a certain state. The accessory state contains all information needed to send an SRCP GA SET command.

Attributes which must be implemented:

name type static /
dynamic relation description

ID UUID static

NAME alphanumeric static Common name for the state. e.g. 'straight' or 'curved'

ACCESSORY UUID static parent Accessory this accessory state belongs to

PORT numeric static Port

VALUE numeric static value

DELAY numeric static delay

5.15 ROUTE

A route for a train from through a number of sections

Attributes which must be implemented:

name type static /
dynamic relation description

ID UUID static

NAME alphanumeric static Common name for this route

RWCC UUID static parent
SECTIONROUTE UUID static List of sections routes that together define the whole route. The sections must be in order they are driven through with the starting section first.

TRAIN UUID dynamic Train taking this route. The RWCC may refuse to change the state of the route if not all sections are free or occupied by another train.

STATE numeric dynamic 0: Not active
1: Active
2: Requested

Appendix A Examples

A.1 Discovery of available vehicle actors

An CRCF implementation requests all STOCKDB actors to list their VEHICLE objects. One CRCF implementation answers with a list of 3 VEHICLE objects.

SET 0 GM 0 4 CRCF STOCKDB 00000000-0000-0000-0000-000000000000 LIST VEHICLE
SET 0 GM 4 2 CRCF STOCKDB c76f46ce-eba9-471e-a48a-ca84984ff95b INFO VEHICLECOUNT 3
SET 0 GM 4 2 CRCF STOCKDB c76f46ce-eba9-471e-a48a-ca84984ff95b INFO VEHICLE 93be6fa1-aa4d-43cb-971e-bbd756b2dfd9
SET 0 GM 4 2 CRCF STOCKDB c76f46ce-eba9-471e-a48a-ca84984ff95b INFO VEHICLE b422d1b4-ea64-45ec-99ff-bfc3a5f27616
SET 0 GM 4 2 CRCF STOCKDB c76f46ce-eba9-471e-a48a-ca84984ff95b INFO VEHICLE 4bdab508-af32-4318-86af-7b6478ab9a0a

A.2 Speed calibration tuple

This locomotive has been calibrated at speedsteps 10, 80 and 126. The measured speeds were 0.01 m/s, 0.5 m/s and 1 m/s respectively.

SET 0 GM 4 2 CRCF PROTOCOL a184bf57-dedf-4f72-8c4c-5b7b8d86d203 INFO SPEEDCALIBRATION 10,0.01,80,0.5,126,1

name	type	static / dynamic	relation	description
ID	UUID	static	root
NAME	alphanumeric	static
VEHICLE	UUID	static		static list of vehicles
TRAIN	UUID	dynamic		dynamic list of trains