Operating digital model railway kits is to this day strongly influenced by the used hard ware. There is an agreement between some manufacturers in order to reach mutual compatibility on the level of devices. This agreement is not generally accepted though. There is no common operating language, every system uses its own. To provide high-performance programs software has to be adjusted and tested separately for all used digital systems. In addition a multi user operation is restricted if present at all. The following equally important goals are pursued with the SRCP:
| Consideration of different digital systems with a common operation language in multi user operation over a (computer) network. |
| Further scaling capability in the range of spontaneously built model railway systems, large stationary constructions and operation at model train conventions where individually created modules are to be put together. |
| Paying attention to different safety strategies, from none to my own one. |
| Software shall also be feasible by the interested layman. |
| A SRCP server abstracts the control of the construction. All information are provided either due to inquiring the layout directly where ever possible or by the command history. |
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.
SRCP procures client server communication for operating a model railway. The server is the component that is connected with the layout. A client contacts the server in order to send commands to the layout and to receive information from there. The client can be run on the same computer as the server. It can also be run via the Internet from the other end of the world. The used model railway system is of minor importance to the client. It is the server's task to translate the commands of SRCP into action.
A SRCP server has got no knowledge about the concrete railway system. Neither it knows about the topology nor (generally) is it informed about the installed equipment. It conveys the commands intuitively. Its task however is to collect all available information as precisely as possible. Doing that it handles its knowledge about the possibilities and limits of the controlled layout. Its data have always to be understood as the best knowledge about the state of the railway system.
SRCP does not fulfill any formal real time demands.
A SRCP server SHALL represent exactly one central unit (CU) in the usual sense (hardware or emulated in software). Every CU disposes of at least one bus for addressing devices. Over that bus information is read and/or commands are executed. In case a CU has several of these command channels to the model railway layout it is valid in SRCP and leads to several busses.
If a SRCP server can manage and provide several CUs it is valid. Separating the CUs is made by different bus numbers. The SRCP servers have to be prosecuted on different TCP ports if there are several CUs connected to a computer but without a common SRCP server. Exactly one of these servers HAS TO provide the standard port.
The SRCP is based on the data transfer technologies of TCP. One port is occupied. IANA has registered the port 4303 for both UDP and TCP. The assigned protocol name is srcp .
All character codes are described in their decimal form as # followed by the numeric value of the character.
The entire communication consists of the characters of the 7bit ASCII character set in the range from #32 to #127 (including the borders). In addition the characters #9 (TAB) for space, #10 and #13 (CR, LF) for end of line are valid. All further characters (esp. with a code value >127) are ignored in incoming data and removed. In outgoing data they can be included, but not used within SRCP. The characters #9 and #13 are seen as white space and count as one white space also if repeated several times (also mixed).
Numbers are processed at least as signed 32bit integers. This range of values can be extended in special cases. Zeros in the leading position are not significant. Floating point numbers are NOT used.
Commands are sent in the command mode and in hand shake from client to server. The SRCP server processes the command and generates a respond that is to be sent to the client.
Commands consist of a command word, followed by a command parameter list separated by white space. The end of a command is the end of line. It is not valid to resume a command in the following line. If the list consists of several elements they need to be separated by white space. Elements containing white space are not valid.
If a parameter list contains more elements than specified for the command the supernumerary elements HAVE TO be ignored, the command list has to be shortened and then processed. If the parameter list contains too few elements an error message needs to be generated. If there are several parameter lists defines for one command the list is always to be shortened if in doubt.
The end of line always consists of the character #10 (\n, LF). A prefixed #13 (\r, CR) is valid. The character #13 is ignored. A single line including the end of the line MUST NOT exceed over a length of 1000 characters. Information sent by the server is subject to the same terms. The character #13 MAY be sent immediately before #10.
All words are case-sensitive. Commands and replies of the SRCP are always written in uppercase letters. The only exceptions are explaining texts on error messages and information sent by the devices.
A server HAS TO reply to every command of a client. That is to be sent to the client on the same connection. A reply SHALL be single-line. With the sign \ (Backslash, #92) immediately before the LF (resp CRLF) it is marked that the reply contains another line. In this case the character sequence \LF (resp. \CRLF) is equated with the white space. That way a reply can be spread over several lines. A single line including the end of the line MUST NOT exceed the length of 1000 characters.
A reply is either an acknowledgement of receipt, an error message or the result of a command. If the reply is an error message the command MUST NOT be executed.
A reply is complete with the effective end of line. Processing more than one answer in one line is not valid.
Replies are always proceeded by a time stamp. The time stamp is generated from a unique time source. It's format is seconds.milliseconds. The following sources can be used:
After the server has sent its reply it processes the next command. That way commands are handled by a strictly two-way communication between the client and the server in a changing order of commands and reactions. The server HAS TO process the commands in the chronological order of receiving them.
If the result of a command can be ascertained due to communication with connected model railway devices this opportunity SHALL be used. In case there are insufficient results for a task the answer is " 416 ERROR no data " .
A SRCP server is always in one of three possible states towards the client: hand shake, command mode or info mode.
On connection the hand shake mode is activated. Further operation parameters are determined by the client in this mode. The connection changes from the hand shake mode to either the command mode or the info mode according to the client's demand. From all three modes the connection can be closed any time.
open
|
V
+-----------+
| handshake |
+-----------+
|
+--------------------+--------------------+
| | |
V | V
+--------------+ | +------------------+
| command mode | | | information mode |
+--------------+ | +------------------+
| | |
| | |
V V V
close close close
Subsequently the SRCP commands and their corresponding replies are described in detail. All have to be implemented by an SRCP server.
Commands are processed in hand shake and command mode only. They are not valid during info mode and MUST be ignored.
Commands MUST be processed by the server in the order of receiving them. This involves especially the order while conveying the devices of the layout.
Unknown or unrecognized commands MUST be replied with the message " 410 ERROR unknown command " .
A client establishes a TCP/IP connection with the server. The server sends a single line welcome string. Then the communication parameters and the desired operation mode are negotiated between client and server. The operation mode starts with the final command GO sent by the client and it has to be confirmed by the server.
The server MUST differentiate all client sessions internally. Once a identification number is assigned it MUST NOT be used a second time for any other session during the entire server runtime.
After establishing a connection between server and client the server sends a text line to the client: The welcome. This string is composed of several server information units, each separated by the character ; (semicolon, #59). Every single information unit MUST be seen as a key/value pair. The sequence of these keys is not specified. It is also generally possible to use keys with different values consecutively. For every key exactly one single value is valid. One value consists of one or more words separated by white space. The end of line also counts as the end of the value. A semicolon MAY be missing.
The welcome MAY be created as an error message when not enough resources are available. In this case the server MUST shut down the connection with the client after sending the welcome message and MUST NOT accept and execute commands send by the client.
The following keys MUST be refered to during normal welcome:
| SRCP <version>: supported SRCP version by the server. It MUST correspond exactly to one of the released version numbers. This data MUST be given exactly once. A repeated specification is not valid. |
The following keys MAY be given to show definite information. A server is free to use further keys. Key identifiers starting with the string SRCP MUST NOT be used as long as they are not defined in SRCP.
| SRCPother <version>: SRCP version additionally supported by the server. It must correspond exactly to a released version number and be different from the specification in the key SRCP. A client SHALL ignore this data. |
After establishing a connection and sending the welcome message the server waits for a command from the client. The server executes it and sends a single line reply to the client. Then the server waits for the next command. That way information and commands are being exchanged.
The following commands are defined. If not executed the determined default setting is valid. During the hand shake phase no other commands than listed are valid.
SET PROTOCOL SRCP <VERSION> The desired protocol to be used is arranged. If this command is missing the SRCP version given during welcome is accepted. Every released version number from and including 0.8 is valid as <VERSION>. The server sends as reply either 201 OK PROTOCOL SRCP or the error message 400 ERROR unsupported protocol . Please note that not every SRCP compliant server does support all versions.
SET CONNECTIONMODE SRCP <MODE> Type of connection the client likes to establish. Valid values are INFO for the unidirectional information mode and COMMAND for the bidirectional command mode. The server sends either 202 OK CONNECTIONMODE or the error message 401 ERROR unsupported connection mode back to the client. If this command is missing the mode COMMAND is set as default connection mode.
GO This command terminates the hand shake phase and activates the chosen operation mode. The server sends 200 OK GO <ID> immediately before that to the client. If the command cannot be executed the server sends the error message 402 ERROR insufficient data and remains in the hand shake mode. This is intended for future extensions and embedding SRCP in other protocols. The field <ID> marks the numerical session ID given by the server. This is clear to the server and as long as the server is running it will never be given twice. It MUST NOT be identical to zero.
Instead of a reply or the welcome the hand shake can be cancelled by the error message 500 ERROR out of resources in addition to closing the connection. Any further communication is not possible then.
After completing the hand shake the agreed attributes cannot be changed and are valid for the entire connection.
The following messages are valid during hand shake:
Command accepted and executed. The server leaves hand shake and changes to the selected connection mode. The session id is generated.
Protocol selection accepted and set.
Connection mode accepted and set.
The protocol is not supported
the connection mode is not supported.
Command executed.
no resources left.
To cancel hand shake the TCP connection needs to be closed without further comments.
During command mode the server waits for commands from the client and executes these. As the result of the execution the server always creates a reply to be sent to the client in the same TCP session. Subsequently the next command is executed. An overlapping or otherwise divergent execution of commands is not valid. The following commands are defined:
The server`s replies to the client in the command mode always consist of a time stamp at the beginning, a numerical answer code and further data. The numerical answer code is structured in groups. 100-199 marks information and results, 200-299 includes receipts confirming the processing according to the rules, 400-499 marks error while executing commands, 500-599 errors by the server itself, 600-699 specific error codes in implementation.
| 1xx INFO: Information, results |
| 2xx OK: Command is accepted and brought to execution. Attention: This is no confirmation for actually executing the command. |
| 4xx/5xx ERROR: An error condition has occurred. The command is ignored and not executed. |
| 6xx ERROR: A server specific error has occurred. The processed command is not executed. |
The significance of the time stamp arises from the kind of reply: For quittance (OK, ERROR) it specifies the point in time when the command is processed and the receipt OK or ERROR is generated. During INFO the time stamp defines the point in time when the SRCP server first gets knowledge about the reported result or when the reported operation takes place if the server can detect that. If the subject is only a partial change of parameters in a parameter list this is the point in time of the last change. In this text the specification of the time stamp is generally assumed but for reasons of clarity not indicated if it is not necessary for explaining an issue.
While starting the server program internally commands MAY already be executed without the definite assignment from the client. In any case all changes from the determined default state by this norm have to be made available during INFO mode.
The end of the server program is ensured by the command " the Section called TERM " . A receipt ( " 200 OK " ) follows in this case, too but before its execution. Subsequently the connection to the server is closed. This is valid for all connected clients. During INFO mode SESSIONS are informed at least one second before about the subsequent program end.
Valid commands MUST always be executed. Verifying a command with the current knowledge of the server in order to suppress commands that i.e. would not make a change is not valid (prohibition of optimization). The command INIT generally is used for initialization and configuration of the indicated device or group of device. After processing the INIT command the indicated element is in default state. During INFO mode a message in the form of 101 INFO INIT <devicegroup> <addr> is sent for the affected element.
By the command TERM the initialization is cancelled and the effected element is in default state. Before using it again the affected element has to be reinitialized. During INFO mode a message in the form of 102 INFO <devicegroup> <addr> is sent for the affected element.
After INIT any write access to the affected device by SET or INIT for all active sessions is invalid until reading access is processed by the commands GET or VERIFY (depending on the device group) or TERM. This includes the session executing the INIT.
The command SET changes certain parameters of the element in question. By the SET command the element MAY be initialized implicitly. The reply to SET is a " 200 OK " if successful. The command CHECK corresponds with the command SET in all aspects except for that the actual execution of the command is suppressed. The aim of this command is to support the debugging of clients.
The command GET detects the current parameters. This includes programmed parameters as well that can only be set by INIT. The result is 100 INFO or an appropriate error message. The information represent the best knowledge. If a server can find out about the data by requesting the layout components it SHALL do so. If the current situation or the system based upon does not permit that the server MAY go back to own information i.e. resulting from the last SET. In no case the information can be seen as completely identical to the actual state of the layout.
The command WAIT awaits the arrival of a certain match in the state of a device for a determined time span. Waiting blocks the client session. If the time span is exceeded the error message " 417 ERROR timeout " is generated. If the expected state happens within the determined time an " 200 OK " is generated.
The command RESET is for reinitializing an element. This command SHALL be a shortened order of TERM/INIT. The result is either a " 200 OK " in the case of success or an error message. The affected element MUST be in the default state subsequently.
The command VERIFY is for checking whether an element state corresponds with a determined sample. The reply is either a " 200 OK " in the case of success or an error message. This has to be applied especially with programmable devices if the affected parameters cannot be influenced by SET.
Response messages are generated by the server as reply to commands from the client.
Response messages always start with the time stamp like all replies, followed by the response code and the remaining words according to the response code. One of the messages listed in the following overview MUST be used.
The server generates information about a device.
The server generates information about the initialisation of a device.
The server generates information about the termination of a device.
The command accepted and brought to execution. It does not mean, that the command was executed at all, it may be delayed for various reason!
The command part of the line could be understood by the server.
The actual value is unknown.
a parameter is outside the valid range.
The command cannot execute currently. Please try again later.
The device is currently locked by another session. The session id of this session can only perform read operations.
the command is categorically forbidden.
no information at all is available.
a time limit is exceeded.
the parameter list is too long.
the parameter list is too short.
The device does not support the given protocol.
This device is not supported on the specified bus.
The device group is not supported on the specified bus.
the requested action is not supported by this device.
The affected device is reinitialized. The command GET has to be processed first.
The operation is not supported.
an error has occurred but cannot be specified. This error message SHALL be avoided.
Using further error messages SHALL be avoided. In any case the defined message text is to be used when the named error situation occurs. If there are further data about the determined error these can be attached to the message. A client MAY ignore these.
Parameters are to be given as a list. Single parameters are separated by white space.The position of the parameter within the list indicates its significance (position correlated parametrization). This is valid for all groups of devices. A single parameter MUST NOT contain a white space. For single commands there can be defined different parameter lists that differ by the number of parameters and semantics.
Addressing elements of a construction is based on the following elements: the bus the group of devices and the device address if several devices are possible.
A bus is categorically the abstraction of a concrete hard ware communication string. A bus is generally represented by a central unit. A bus SHALL be used to map parallel address spaces on a real system.
A bus is determined and initialized by the configuration of the server. While running changing the buses is only possible by resetting a server.
A bus is named by a running number starting with zero and counted upwards without a break. Bus 0 is reserved for the server itself. There always MUST be at least one additional bus connected with the CU. It is not relevant whether the CU is implemented by hard or soft ware.
In all commands the number of the bus must be given right after the command word as the first parameter and is used during all replies and informations.
Device groups are the topic of the next paragraph.
The aim of addressing are the devices: decoders and encoders (in the following it is spoken of decoders only; encoders are applied by analogy). Every decoder is an element of at least one bus and a device group, the affiliation of a decoder with several buses at one time is valid but SHALL be avoided. If the bus affiliation (i.e. with locomotives) changes the data are not adopted automatically. It is the client`s task to carry out this transfer. Devices belonging to several device groups at the same time are also valid.
If devices with an identical hard ware address but different control protocols coexist on one bus the SRCP server MUST make sure that the specified device acts comprehensibly. If necessary several buses have to be provided to support addressing.
For an SRCP server all devices count as known that have been addressed before and are not deleted by TERM. A device in the default state MAY also be known. In some hard ware systems broad casts are mapped by certain attributes of the processed data. An SRCP server MAY use them internally In systems not supporting any REQUIRED feature the server MUST emulate those functions.
Device groups are sets of similar devices. The following device groups are defined:
Devices describing other devices or busses.
DESCRIPTION devices can describe other devices with their attributes. Replies by a server MAY be formulated on several lines. It is distinguished between the DESCRIPTION of buses and the DESCRIPTION of device groups.
Feedback sensors.
Feedback devices FB are encoders that signal an occurrence on the construction. They have exactly one way in that is identified by an address and has at least two distinguishable states. If single encoders are pooled in one device group it has no impact on the identification. The group not valid under the bus number 0.
Generic Accessory.
The device group GA is provided for decoders that make one or more ports with two or more possible values at a time available under one address. Usually these are stationary construction elements like switches or decouplers. The group GA is not valid in the bus number 0.
Generic Loco.
The device group GL indicates engine decoders in the engine address room of the hard ware. The group GL is not valid in the bus number 0.
Generic Message.
The device group GM is used to transfer a text message from one session to another. The destination session MUST BE an INFO session.
Devices locking other devices.
The LOCK devices are devices providing a lock over another device. They are optional. If present the server MUST contact the LOCK devices before any actions on the lockable devices. They are ALLOWED to exist on particular buses but not on all buses. Providing lock devices for all buses of a server should be aspired.
Energy Supply.
POWER signifies the state of the energy supply of the particular bus. POWER is invalid on bus number 0. Activating the energy supply on one bus can activate other buses implicitly. This MUST be considered in INFO mode.
SRCP Server.
SERVER together with the bus 0 signifies activities concerning the server (esp. TERM and RESET). The use with other buses is not valid. The SRCP server is the only element of this device group.
SRCP Client Session.
SESSION together with the bus 0 signifies the amount of active client connections. Using other buses than 0 is not valid.
Service Mode.
The service mode SM effects decoders used in the program mode. Therefore it MAY be necessary to displace the decoder on another bus (programming track) or that a bus has to be suspended for other commands. On this bus commands MAY be refused with the error message temporarily prohibited or forbidden. This group is invalid on the bus 0. Technical implementation can include direct access on the used digital systems.
Time Norm.
The time normal TIME is only valid with the bus number 0. It is for providing a uniform model time. This is counted faster or slower than real time going out from a starting point but exactly like real time monotone with model second precision. During INFO mode the model time is processed at every full model minute. The time normal is optional. Only one device is valid in this device group.
Some device groups correspond with the specified layout elements. They are initialized by default on the lowest common denominator in the case of different implementations. Using further features requires an initialization where information about the hard ware is necessary. An overview about what hard ware can (resp. must) be initialized and how it is supposed to be done can be found in the separate document SRCP Devices . The data given there are as binding as the SRCP itself.
Every SRCP server MUST support the device groups SERVER, SESSION and DESCRIPTION in bus 0. The device groups POWER and DESCRIPTION MUST be available for every further bus. All other device groups are optional. If they are supported it MUST be specified in the DESCRIPTION of the bus. Supporting DESCRIPTION for device groups is optional and can be supported separately for every device group.
The following overview is supposed to show the allocation of device groups and commands on the busses.
| SET GET WAIT INIT TERM RESET VERIFY
| CHECK
------------+------------------------------------------
|
GA | 1.. 1.. -- 1.. 1.. -- --
|
GL | 1.. 1.. -- 1.. 1.. -- --
|
FB | 1.. 1.. 1.. 1.. 1.. -- --
|
SM | 1.. 1.. -- 1.. 1.. -- 1..
|
POWER | 1.. 1.. -- 1.. 1.. -- --
|
LOCK | 0.. 0.. -- -- 0.. -- --
|
DESCRIPTION | -- 0.. -- -- -- -- --
|
GM | 0 -- -- -- -- -- --
|
SERVER | -- 0 -- -- 0 0 --
|
SESSION | -- -- -- -- 0 -- --
|
TIME | 0 0 0 0 0 -- --
Entries signed with the -- tag denote combinations that MUST NOT be used.
Feedback sensors have an address where exactly one current value is recorded. In its simplest case a feedback is a binary signal. A default state that can be influenced by the server is not present.
GET <bus> FB <addr>
It supplies the current value of a single feedback sensor as a " 100 INFO <bus> FB <addr> <value> " If no data is available, the error message " 416 ERROR no data " is generated.
INIT <bus> FB <optional parameters for initialization>
An already existing feedback bus is initialized. The exact parameters are known to the server only from its configuration.
TERM <bus> FB
By TERM the specified bus is taken out of the running communication without deleting it from the list of present buses. The attached hard ware SHALL be turned off if all buses taking hold of it are terminated. Running WAITs MUST be closed by time out as long as the WAIT requirement is not met.
WAIT <bus> FB <addr> <value> <timeout>
Waiting until <timeout> seconds (real time) for reaching the specified value. In case the value is already there its eventuation is reported instantly without waiting.
The session blocks further operation until either an error message ( 417 ERROR timeout ) or the value specified occurs ( 100 INFO <bus> FB <addr> <value> ).
A Generic Accessory generally indicates a decoder that can serve one or more ports under one address. Often these are switch decoders or signal decoders working as impulse decoders. One must note that there are restrictions during simultaneous activation and/or deactivation of ports. These are to be taken from the description of the decoder if necessary. An SRCP server cannot always indicate and report these features itself.
The default state of a device is indicated by zero on all ports.
GET <bus> GA <addr> <port>
The server sends all available information about the current state of the switch decoder specified by <addr> to the client as " 100 INFO <bus> GA <addr> <port> <value> " If no data is available, the error message " 416 ERROR no data " is generated. Other error message may occur if the parameters given (addr, port) are out of range.
INIT <bus> GA <addr> <protocol> <optional further parameters>
This command initializes a GA at address <addr> in the server. The following parameters are permitted:
Maerklin/Motorola Format
Valid addresses are from 1 to 324, valid ports are 0 or 1, valid values are: 0 and 1
NMRA-DCC Format
Valid addresses are from 1 to 511, valid ports are 0 or 1, valid values are: 0 and 1
Selectrix Format
Valid addresses are from 0 to 111, valid ports are 1 to 8, valid values are: 0 and 1
Protocol by server
The server uses the initialisation parameters from its own configuration. The parameter list MAY give some parameters. Address, port and value are not limited.
SET <bus> GA <addr> <port> <value> <delay>
The port <port> of the decoder with the address <addr> is set to the value <value> for <delay> milliseconds. After time has expired the server automatically sends the value 0 to the decoder. In case the delay is -1 the automatic deactivation remains undone and the port remains active until it is deactivated by a further SET command. An SRCP server MAY execute momentary deactivations and reactivations of the port during this time. If applicable this is a demand of the hardware that does not permit certain maximum power durations to be exceeded. A delay of 0 is not valid.
Meaning of the arguments
addr must be valid number.
port must be valid. In case an
unsupported port is given, an error message "
412 ERROR wrong value " is created.
value must be valid
(0=>deactivated, >1=>activated) If an invalid value is
given an error message " 412
ERROR wrong value " is created.
delay value in milliseconds
(1.000th seconds). It indicates after what time the server shall
deactivate an active port automatically (i.e. set port value to 0).
If delay is -1 the port is not
automatically deactivated. If value
=0 is given (deactivation) the delay
parameter is ignored but it must be given (useful value is 1). A
port counts as active if its state is not equal zero. A delay of 0
is not valid. An error message " 412 ERROR wrong value " is created.
A generic loco generally indicates all engine decoders. The default state is zero with all parameters.
GET <bus> GL <addr>
The reply is a complete " 100 INFO <bus> GL <addr> <drivemode> <V> <V_max> <f1> . . <fn> " line.
INIT <bus> GL <addr> <protocol> <optional further parameters>
By INIT the kind of data transfers and fundamental features of the decoder is reported to the server. Changing the decoder features on programmable decoders is not permitted (for this the device group SM is to be called upon). Exception: If decoders are programmable by a sequence of normal commands the device group SM MUST NOT be used.
addr must be valid.
protocol must be one of the
following. In case an unsupported protocol is given, an error
message " 412 ERROR wrong
value " is created.
analog operation.
addr: 0, no functions and no speed steps
reserved for native Fleischmann.
reserved for Loconet.
reserved for Maerklin/Motorola MM.
protocolversion The protocol
version is 1 for the old MM protocol (e.g. delta decoder), 2 for
the new protocol (additionally four functions).
decoderspeedsteps The decoder
speed steps comply with those supported by the decoder (if
applicable under attention for the number of the decoder
functions).
numberofdecoderfunctions The
number of decoder features results in the number of the addressable
functions without attention for a possibly unused function. They
are always to be seen consecutively without interception.
reserved for NMRA/DCC.
protocolversion The protocol
version is 1 for the short address format and 2 for the long
address format.
decoderspeedsteps The decoder
speed steps comply with those supported by the decoder (if
applicable under attention for the number of the decoder
functions).
numberofdecoderfunctions The
number of decoder features results in the number of the addressable
functions without attention for a possibly unused function. They
are always to be seen consecutively without interception.
protocol by server.
any address, any number of functions (additional information: any number of speed steps). The server specifies the type of decoder by itself.
reserved for native Selectrix.
reserved for native Zimo.
A server MAY NOT support one or more of these specifications. Specifications that are not given MUST NOT be used. These specifications will be put in concrete terms in later revisions of the SRCP.
Hint: In some protocols there are several scopes for functions. Usually there is one depending on the riding direction and several not depending on the riding direction. A server MUST provide the first as the first function and the others as second, third etc. function.
SET <bus> GL <addr> <drivemode> <V> <V_max> <f1> . . <fn>
The given values are allocated to the decoder. The default state is indicated by the value 0 for all parameters (apart from the address). The meanings of the parameters are as follows:
addr must be valid address.
drivemode must be one of the
following values or an error message " 412 ERROR wrong value " will be sent:
| 0 backward |
| 1 forward |
| 2 emergency stop |
V, V_max speed level and maximum
speed level. 0 is standstill. A value >0 means movement of the
engine (i.e. a real speed level >0). V<0 is not valid as well
as V>V_max. The speed raises from 0 to V_max so that a speed
V2>V1 causes the engine not to go slower on V2 than on V1. In
all error situations an error message "
412 ERROR wrong value " is created.
f1 . . fn 0 (off), 1 (on). If
applicable F1 is dependent on the direction. The SRCP server
rejects invalid values with the error message "
412 ERROR wrong value " . Other values
are valid too.
Example:
INIT 1 GL 1 N 1 128 5 SET 1 GL 1 1 4 100 1 0 1 0 0
The engine 1 (NMRA decoder, 128 decoder speed steps, 1+4 functions) addressed via bus 1 goes forward with speed step 4 (of 100 possible). From the five functions there are only FUNCTION and F2 active.
TERM <bus> GL <addr>
Sets the engine to default mode and removes the engine from the knowledge of the server.
An INFO covers the reaction of the GET as well as the output in INFO mode as a reaction to the SET and INIT commands. It MUST include all current values no matter whether they are currently changed or not. The format is as follows:
parameters of GL address on the specified bus.
Initialisation of a GL device of the specified bus.
Termination of a GL device of the specified bus.
Here the parameter V is not the speed step transmitted by the client, but the real speed step sent to the engine by the server lacking possible special indications: The speed step 0 indicates standstill. The speed steps from 1 to conclusively V_max indicate the movement of the engine in the given <drivemode>
Generic Messages support a client-client communication. This communication can be 1:1 or 1:all.
SET <bus> GM <send_to> <reply_to> <MSGTYPE> [freetext]
bus is allways 0 (Null). The server bus is the only instance to process the Generic Messages device.
The send_to is the sessionid of an INFO session the message MUST BE delivered to or 0 (null) if delivery is done to all INFO sessions.
The reply_to parameter is the sessionid of an INFO session to which message replies SHOULD be directed (if any). Alternatively the 0 (Null) MUST be used to direct the reply to all INFO sessions.
The MSGTYPE is an type specifier. These are registered at some URL and describe the following message. Any MSGTYPE starting with SRCP is reserved for future use.
The freetext is the message being transferred. The message MUST be a valid SRCP string (hints: ASCII, max 1000 character line length)
An error message 412 ERROR wrong value is sent if the session number for the <send_to> or <reply_to> parameters does not specify a valid INFO session.
The devices of the service mode are provided for the permanent change of devices. They are an optional component. If they are not supported an error message " 425 ERROR not supported " must be created. They are intended to be used for decoder programming. A default state is not specified.
GET MUST consult the decoder directly. A reply MUST not be detected from information on the server.
GET <bus> SM <decoderaddress> <type> <1 or more values>
The meaning of the parameter is as with SET. The result is an 100 INFO, that renders the particular value. A GET results in the error message " 416 ERROR no data " , if there is no possibility to read out the decoder.
INIT <bus> SM <protocol>
It initializes the specified bus for programming decoders in the given protocol. Consequently the bus MAY be suspended for other tasks. Valid protocols are:
SET <bus> SM <decoderaddress> <type> <1 or more values>
The following Types and <more values> are defined:
Configuration Variable: The first parameter of the remainder list indicates the address of an NMRA decoder variable (<cvaddress>). It receives the value described in the second parameter <value>. Limitations in the value area of the parameters arise from the specifications of the decoder. A server cannot validate decoder specific value ranges.
Write Configuration Variable bitwise with three parameters. The bit <bit> of the address <cvaddress> is set on the value <value>. <bit> is valid from 0 to 7. <value> is 0 or 1.
Register mode programming. <regaddress> is valid from 1 to 8.
Page mode programming.
Quits the program mode on the specified bus. Possibly incomplete programming cycles are suited for quitting.
TERM <bus> SM
" 100 INFO <bus> SM <decoderaddress> <type> <1 or more values> " .
VERIFY MUST consult the decoder directly. A reply MUST not be detected from information on the server.
VERIFY <bus> SM <decoderaddress> <type> <1 or more values>
As with GET the decoder must be consulted directly. The meaning of the parameters is as with SET. The result is either a 200 OK if the parameter in the decoder complies with the given one or the error message " 412 ERROR wrong value " .
An INFO covers the reaction of the GET as well as the output in INFO mode as a reaction to the SET and INIT commands. It MUST include all current values no matter whether they are currently changed or not. The format is as follows:
parameters of SM decoderaddr on the specified bus.
Initialisation of a GL device of the specified bus.
Termination of a GL device of the specified bus.
By locking a client can suspend a device exclusively for a current session. This is also valid for physically identical devices addressable in several device groups: A LOCK on a decoder in the device group GL also prevents write access to the same decoder in the device group SM! Other sessions, also from the same client, get an error message " 414 ERROR device locked " during write access (SET, INIT, TERM). Executing these commands is allowed to the client session holding the lock only. Read access (GET) is still accepted from all clients and is functional without limitations. Locking a device from the LOCK group, also of another bus, is not valid. A bus cannot be locked as a whole.
The default state is not locked.
For the devices of the group GL an emergency stop is ALWAYS valid for all clients. A lock by another session is without effect in this case. Here the engine MUST execute the emergency stop only, all other parameters, in case they are given, MUST remain unchanged. Particularly the LOCK remains.
A lock is automatically cancelled during the end of the client connection and run-out of the lock time.
The locks are an optional part. If they are unsupported an error message " 425 ERROR not supported " MUST be created.
GET <bus> LOCK <devicegroup> <addr>
Here the session ID is the only clear identification of the session containing the lock.
This command reports the current lock status of a device as 100 INFO line. If the given device is not locked the session ID 0 is reported.
SET <bus> LOCK <device group> <addr> <duration>
Puts a lock on the addressed device. One must pay attention that LOCK devices do not have an own address. They are identified via the device locked by themselves only.
Other clients still have access for reading and writing in areas relevant for safety only. The LOCK is held for <duration> seconds. After this time span runs out the LOCK is automatically terminated by the server. The time starts with the last SET command. A duration of 0 means an unlimited time span. A repeated stop of the SET command restarts the timer each time.
TERM <bus> LOCK <devicegroup> <addr>
A lock on the device <devicegroup> <addr> of the bus <bus> is removed.
parameters of GL addr on the specified bus.
Initialisation of a LOCK on a device of the specified bus.
Termination of a LOCK in a device of the specified bus.
The energy supply is enabled for every bus separately. The default state is OFF.
If the server learns about changes in the energy supply from the construction itself (e.g. recognizing a short circuit), it means the same like a corresponding command and MUST be reported in info mode.
SET <bus> POWER [ON|OFF] [freetext]
Activates (ON) or deactivates (OFF) the energy supply on the affected bus. The <freetext> is an optional addition allowing up to 100 characters. It is reported to other clients in INFO. An SRCP server does not evaluate this parameter.
TERM <bus> POWER
Quits the power supply and turns it off.
Informs about the current state of the power supply and possible additional data.
The model time is opposed to the normal time a time distorted by a constant factor. The time distortion is specified by a multiplier and a divisor to this normal time. The timer is only allowed on bus 0. There is only one timer.
In the default state the timer is stopped.
The timer is an optional part. If it is not supported an error message " 425 ERROR not supported " MUST be created at all commands.
Time coverage consists of the data: day, hour, minute and second. A minute is 60 seconds, an hour is 60 minutes and a day is 24 hours. The days are counted consecutively. A separation into larger time intervals (calendar function) is the client`s task.
If a full model minute is reached the current model time is given in INFO mode. The commands WAIT and GET additionally valuate the model seconds.
The model time is generated as follows:
(Delta) model time = (delta) real time * FX/FY
Examples:
| FX=10 FY=1 -> In every real minute 10 model minutes are generated (one every six seconds) |
| FX=1 FY=10 -> Every 10 real minutes are one model minute. |
| FX=1 FY=1 -> In every real minute there is one model minute. |
GET 0 TIME
Reports the current model time as " 100 INFO 0 TIME <JulDay> <Hour> <Minute> <Second> " .
INIT 0 TIME <fx> <fy>
It initializes the timer with the given distortion. The timer is not started automatically. The parameters must be positive numbers different from zero. A server MAY limit the value range to a bounded scope (e.g. 1 .. 10). These values MUST be given in the documentation.
SET 0 TIME <JulDay> <Hour> <Minute> <Second>
It sets the timer on the defined point of time and starts it. With a running timer the new time starts when the running model second ends so that the new beginning model second corresponds with the new time.
TERM 0 TIME
Stops and removes the timer. All running WAITs are cancelled by TIME OUT with " 417 ERROR timeout " .
WAIT 0 TIME <JulDay> <Hour> <Minute> <Second>
It waits until the model time reaches or outruns the given point and reports an INFO string with the then active model time.
If the timer is not running the error message " 416 ERROR no data " is generated. If the current model time is later than the given time already the condition is fulfilled without further waiting time. Obviously wrong time data are reported to the calling client by " 412 ERROR wrong value " or ignored. The WAIT MUST always evaluate the currently valid model time that can be changed by SET if applicable.
Sessions are active connections from a client to a server. A client MAY have multiple sessions with a server. For the server these are independent of each other. A session is distinguished from others by a session ID. This session ID is generated by the server during hand shake and is unique for the uptime of the server. A session ID given out once cannot be used a second time. A session id is a positive numeric value.
Sessions are only valid on the bus 0. There is no defined default state.
TERM 0 SESSION [<SESSIONID>]
Terminates the currently running session and the adequate socket connection. The last message the server sends to this session is an appropriate acknowledgement.
The DESCRIPTION device groups describes other device groups and buses. They inform the client about the fundamental features.
This command occurs in two versions: with a parameter list and without. If the parameter list is left out the server informs the client about the specified bus. With a parameter list the specified device is described regarding its initialization.
GET <bus> DESCRIPTION
--> INFO <bus> DESCRIPTION <list of device groups>
The INFO covers all device groups supported by the specified server in one line. Example:
| GET 0 DESCRIPTION - -> INFO 0 DESCRIPTION SERVER SESSION TIME |
| GET 1 DESCRIPTION - -> INFO 1 DESCRIPTION FB |
The bus 0 supports the device groups SERVER, SESSION and TIME. The bus 1 only supports feedback.
In the second variant the address of the specified device and as reply the parameters defined during initialization are given.
GET <bus> DESCRIPTION <devicegroup> [<address>]
The address is only ALLOWED to be left out with device groups without an address. The parameter list is identical with the one from the INIT command in this case. Example:
GET 1 DESCRIPTION GL 1 --> INFO 1 DESCRIPTION GL 1 N 128 5
i.e. the engine with the address 1 is an NMRA compatible decoder with 128 real speed steps and five functions.
The server as a whole. This device group is only defined on bus 0. Valid are the commands TERM and RESET. The default state is RUNNING.
GET 0 SERVER
Informs the current state of the server. The following messages are defined:
The last two messages are particularly important in INFO mode.
RESET 0 SERVER
Re-initializes the server. All devices are set to the default state. A RESET during a RESET MUST be refused ( " 413 ERROR temporarily prohibited " ). Existing client sessions remain untouched also during hand shake.
TERM 0 SERVER
Quits the running server and closes all connections. The connected buses SHALL be turned off and the active devices set to default mode. For the calling client the quitting " 200 OK " ) is transmitted. Sessions in INFO mode are informed about the running TERM. A TERM MUST NOT be cancelled.
In information mode all changes of all devices are sent unidirectionally to the connected client. The client is PROHIBITED from sending commands or other data to the server. The server must ensure that data sent anyhow does not have consequences. The server is free to quit the connection.
The info mode part of the server sends all data as they become known on the installation. Like with data given during command mode (see replies to GET commands) they are always supplemented with a time stamp. INFO data are sent only. Especially results of commands are sent only after they have been validated by the actor (decoder) or when they have been transmitted to the construction successfully (in case there cannot be a validation from the construction). There are no changes or interpretations to the data. This particularly concerns the train engine speed that is virtually sent by the client but converted according to the real conditions of the decoder.
When activating the info mode in a session the DESCRIPTIONS for all buses and all active devices known to the server in their current state are transmitted. Subsequently all changes are sent. If there is a clear default state for some device groups, all devices in this default state SHALL not be transmitted. Optional device groups are only ALLOWED to be given if they are supported.
Specifics of the device groups during activation of the info mode:
All devices with the status 0 are not transmitted. All others are in form of " 100 INFO <bus> FB <addr> <value> " .
The individual ports of the devices known to the server are separated and transmitted each with their last activity in form of " 100 INFO <bus> GA <addr> <port> <value> " .
All engines moving or standing with an active function are reported. Engines in standstill MUST be reported (as " 100 INFO <bus> GL <addr> <drivemode> <V> <V_max> <f1> . . <fn> " or " 100 INFO <bus> SM <decoderaddress> <type> <1 or more values> " .) if they have been addressed at least once and not removed by TERM. Likewise changes are reported by INIT. During SM all programming activities are reported. A concluded programming action MUST NOT be sent with new connections.
The state of the energy supply MUST be given as " 100 INFO <bus> POWER [ON|OFF] <freetext> " .
The current model time MUST be transmitted (as " 100 INFO 0 TIME <JulDay> <Hour> <Minute> <Second> " and " 101 INFO 0 TIME fx fy " .) as long as this feature is supported and the timer is running.
The identification of all currently active client sessions is sent " 100 INFO 0 SESSION <SESSIONID> [further optional parameters] " . All further information MUST be detected in command mode.
All current device locks are reported as " 100 INFO <bus> LOCK <devicegroup> <addr> <duration> < sessionid> " .
From the initial transmission of all states all changes on the installation and the server MUST be transmitted also those into the default state. An exception is the device group TIME: It reports every beginning of a new model minute but not of model seconds.
These information contain only the defined INFO messages (response code 100..199).
The terms itemized here form interfaces to other documents.
Julian Date The Julian Date is a simple day count without any further structures (like weeks, months, years). According to the arbitrary origin (beginning of the year, fixed point of time in the past) there are different possibilities to convert into other calendars (basis: 1.1.4713 BC 12-00 GMT: see Collected Algorithms from CACM #199)
XRCP A supplement to the SRCP in order to form a higher level of abstraction. Apart from connecting the clients to the server it is there for the communication of the clients among each other. An XRCP system is created as middle ware between clients and SRCP servers.
The following people did major or minor contributions:
| Torsten Vogt |
| Martin Ostermann |
| Kurt Harders |
| Olaf Schlachter |
| Tobias Schlottke |
| Edbert van Eimeren |
| Stefan Bormann |
| Michael Reukauff |
| Martin Wolf |
| Matthias Peick |
| Martin Schönbeck |