BiDiB, a universal control set for model railways
- 4.6. Accessory and peripheral classes
The intention of BiDiB protocol is to control a model railway. It allows the control of locomotives, accessories and safe transmission of feedback information from the model railway to the controlling computer.
BiDiB can be transported over different transmission media, framing and protection of messages is guaranteed.
The used terms and the basic principles will be explained in the general part of the protocol description. Hints for usage and the license can be found there too.
This section of the protocol description explains only a part of the messages.
Current revision status
This document describes revision 1.26 of BiDiB, updated aug 15, 2016.
The revision history can be found at the general section.
|1. Accessory||2. Peripheral||3. Macro|
|for objects with a defined state, Operation 'at the track', so for turnouts and signals.||for objects off the track, so for illumination, animation, sound, control panel, etc.||for the combination of port actions to local sequences.|
In the control of stationary model railroad equipment, BiDiB distinguishes between functions of the class accessory and functions of the class peripherals. Only the former are employed for safe train operation, they possess the facilities for aspect requests, position feedback and error handling.
For peripheral effects and for configuration of accessories, there are the simple switching functions and macros, which can directly control the output ports of the devices.
A node can have the potential to represent turnouts, turntables, signals, level crossings and much more, commonly referred to as "objects" in here. Nodes with controls for such track system relevant objects set the flag for the class-ID 'Accessory'.
Objects use 'aspects' which they can present or to which they can change. A typical switch uses 'straight' or 'branch line', but also turnouts with more than one branch, turntables and transfer tables fall under this definition. The 'aspect' at a turntable describes the particular exit track.
When a new aspect is selected, the object assumes the respective state. This switching action might need some time, in this case the node announces the expected switching time as the confirmation and another status message after completing the action. When an error happens, the node will send an error message.
It is possible that an unforeseen status change happens, e.g. through a manual operation. In this case the node will send a MSG_ACCESSORY_NOTIFY message spontaneously. This spontaneous transmission has to be enabled by a 'SYS_ENABLE' and also by the relevant feature setting.
The configuration of the controlled object depends on its activation type, the implementation falls to the manufacturer and may vary based on the device and use case (e.g. solenoid actuator, servo, stepper, light signal, semaphore type signal etc.). Available are common parameters, see MSG_ACCESSORY_PARA_SET, as well the generic messages for user configuration. Furthermore, accessory operations can be mapped to port commands (switching functions), whereby the extensive options for the configuration of single ports can be utilised, see MSG_LC_CONFIGX_SET.
A node only informs the host about the number of aspects of an accessory, not what kind of object it is about. Such assignment is the responsibility of the control program, a systematisation would go beyond the scope of the protocol and could never achieve completeness.
Still, in the arrangement of the aspects there are some guidelines to be followed. The aspect 0 should always represent the position of rest, for turnouts that is usually the main line. For signals, aspect 0 must represent the Stop indication. For turntables, traversers, segment tables etc. there are two different geometries to consider:
- Linear arrangements (like e.g. segment turntable): Each accessible track exit will be associated to an aspect of the accessory object in sequence.
- Rotationally symmetrical arrangements (like e.g. typical turntable):
Each accessible track exit will be associated to an aspect of the accessory object,
in ascending order in clockwise direction when seen from the top.
The position always denotes the same side of the turntable (with control shack).
A track exit might be accessible but unusable, e.g. when the turntable is in an position where the shack is opposite to a usable track exit. Such a position is 'passive', but it's nonetheless added to the aspect set. In which positions the platform can be passed over is to be defined in the host software.
The number of aspects is always even and two aspects are always located 180° opposite to each other.
Example 1: Assume we have 12 track exits, then track exit 0 and 6, 1 and 7, 2 and 8, etc. are located opposite to each other.
Example 2: A turnaround can be achieved by calculating the new position based on the current position via
new = (current + total / 2) % total.
Elaborate objects with a complex state space can be composed from multiple accessories, so that they possess multiple aspects. The unrestricted composition takes place in the host software.
Among that a special case is the operating mode of objects. Here – and only here – the state of one accessory affects the significance of another accessory state. This dependency is observable via the BIDIB_ACCESSORY_PARA_OPMODE. In doing so, the accessory with the operating mode has two or more aspects that are defined as follows:
- Aspect 0 – "(Emergency) stop": The whole object is halted. The aspects of the composite's other accessories are irrelevant in this mode.
- Aspect 1 – "Operating (normally)": The object is in use and follows the aspects of the other accessories, their state is valid. Only in this mode the object may be passed with trains by the control software.
- Further aspects are considered irregular modes and have to be treated like aspect 0,
i.e. the state of the other accessories is invalid and the object must not be utilised.
Examples: In calibration mode a traverser aligns its platform position with a homing sensor, in configuration mode a turntable can be moved by hand.
The messages to the various accessories are not affected by this and stay independent of each other. Even while their state does have no effect on the object, the accessories continue to be controllable normally. Typically the object will not assume the selected aspects until it switches to the mode Operating. Therefore the switching time has to be respected as usually when changing the operating mode.
The properties of a node can be given by feature retrieval. Please note: Feature values outside the given range are reserved.
|40||FEATURE_ACCESSORY_COUNT||Number of turnouts / signals|
This feature returns the number of controllable objects. Range: 0…128.
0: The node does not announce displacements
1: If a displacement happens, the node announces the new state with the message MSG_ACCESSORY_NOTIFY.
|42||FEATURE_ACCESSORY_MACROMAPPED||Mapping of aspects to macros|
0: This node does not have a mapping function
1…n: This node is able to map accessory aspects to macros. The number reflects how many aspects can be mapped to an accessory object at maximum, resp. how many different aspect could be (not must be) configured. The number of truly used aspects of the accessory will be provided by MSG_ACCESSORY_STATE.
If a certain number of accessories is announced via the feature, all of them have to be implemented and addressable.
Apply a setting to an accessory, 2 bytes are following: ANUM, ASPECT. These two bytes are defining the controllable object and the desired aspect.
MSG_ACCESSORY_SET parameters Parameter Description ANUM Identifies the object at the node, range 0…127. ASPECT This byte defines the state of the object, The non-operating state is using 0. Range 0…127.
The node replies with MSG_ACCESSORY_STATE. If the action takes longer than 100ms, the reply have to happen immediately using MSG_ACCESSORY_STATE including the predicted regulating time. After completion another MSG_ACCESSORY_STATE will be sent to indicate the finished action.
If ANUM is indicating an object which does not exist for this node, the node replies with MSG_ACCESSORY_STATE, object number 255, aspect 255, error code 0x01. The number of possible objects can be read out with a feature request.
If the aspect is not in the range of the object, the node responses with MSG_ACCESSORY_STATE, aspect = 255.
- MSG_ACCESSORY_STATE containing error messages or manual operation from a node must be acknowledged with a renewed MSG_ACCESSORY_SET message. In the case of a manual operation, either the announced aspect can be accept as new aspect or the previous aspect can be repeated to override manual operation.
The state of the object can be read out with this message. One byte is following: ANUM.
The node replies with MSG_ACCESSORY_STATE.
The configuration parameters of an accessory object can be set with this message.
Two or more bytes are following:
MSG_ACCESSORY_PARA_SET parameters Parameter Description ANUM Identifies the object at the node, range 0…127. PARA_NUM Number of the parameter to set. DATA[0hellip;] Values to be set, depending on the parameter.
The node is answering with MSG_ACCESSORY_PARA. If PARA_NUM is not known at the object, the node responds with PARA_NUM = BIDIB_ACCESSORY_PARA_NOTEXIST (255) and the unknown parameter.
Encoding of accessory configuration parameters Value Name Meaning 1-250 – Reserved. 251 BIDIB_ACCESSORY_PARA_OPMODE The accessory is part of a composite object with an operating mode.
A single byte ANUM follows which contains the number of the accessory object that represents the operating mode, range 0…127.
The parameter is typically non-writable. Its range does not contain a value for severing the dependency, where no dependency is in effect the whole parameter is not present.
252 BIDIB_ACCESSORY_PARA_STARTUP Behaviour of the accessory at node startup or reset.
A single byte with the following meaning follows:
- 0…127: the respective aspect is put into effect.
- 254: the node backs up the most recently set aspect.
- 255: the node does nothing when starting up. If feedback is available, the aspect for the current position may be assumed, otherwise "unknown" 255 should be used.
In case position surveillance (feedback) is available, the switching action may be avoided if the position already matches the target state (for 0…127, 254).
A node may (and should) dynamically delay necessary switching actions to avoid overloads while powering up. If MSG_ACCESSORY_GET messages are already responded to during that time, an appropriate remaining execution time has to be announced.
253 BIDIB_ACCESSORY_PARA_MACROMAP Assigning of aspects to macros.
Each aspect of the accessory object gets a macro assigned. Further following bytes define the assignment.
- DATA0: Number of the macro, which will be executed for aspect 0.
- DATA1: Number of the macro, which will be executed for aspect 1.
- DATA2: Number of the macro, which will be executed for aspect 2.
(see also FEATURE_ACCESSORY_MACROMAPPED)
254 BIDIB_ACCESSORY_SWITCH_TIME Switch time, defined like in the railcom specification. Bit Meaning 7 base unit:
0: 100ms (total range 0…12.7s)
1: 1s (total range 0…127s)
6…0 switch time, range 0…127 255 BIDIB_ACCESSORY_PARA_NOTEXIST (in uplink only)
The requested PARA_NUM is not known at the node or does not exist for this accessory. Followed by one byte with the number of the requested parameter from protocol version 0.7 and further.
The configuration parameters of an accessory object can be read with this message. Two bytes are following: ANUM, PARA_NUM. The node is answering with MSG_ACCESSORY_PARA.
This message informs the host about the state of the accessory object. This response will be sent after a request (MSG_ACCESSORY_GET) and after a setting (MSG_ACCESSORY_SET).
Five bytes are following:
MSG_ACCESSORY_STATE parameters Parameter Description ANUM identifies the object of this node, range 0…127. For ANUM=255 the requested object doesn't exist. ASPECT This byte describes the current state (or the planned one during a change). Range 0…127. For ASPECT=255 the state is unknown.
This usually corresponds to the set value, unless there is an error.
TOTAL This byte provides the number of possible aspects of their object. Aspect numbers are starting always at 0 and are counted upwards without gaps. Range 0…128.Examples:
- Standard turnout: 2 aspects: 0 and 1
- Signal with Hp0,Hp1,Hp2: 3 aspects: 0, 1 und 2
Note: There will be no aspects when an accessory returns the value 0 for the parameter TOTAL and it will be not possible to switch something. This can happen for example at macro based accessory when no macros are connected to aspects.
EXECUTE This byte reflects the state of the execution: the activity has already finished, if supervision is ongoing and if a failure has happened occasionally: Bit 7 Meaning 0 normal operation Bit Meaning 0 0: Target state reached. WAIT is 0.
1: Target state not reached. WAIT tells about the expected remaining time.
1 0: Target state is verified by feedback (e.g. switching contact).
1: Verification of target state does not exist.
6…2 reserved, coded as 0 1 Error happened (e.g. broken coil / manual operation); WAIT tells the cause (coded like railcom specification) an. Bit Meaning 6…0 reserved, coded as 0 WAIT normal operation:
After the target state has been reached, the value 0 will be announced.
If the target state has not been reached, the remaining time will be provided according to the specification of Railcom.
Bit Meaning 7 Base Unit:
0: 100ms (total range = 0…12,7s)
1: 1s (total range = 0…127s)
6…0 switch time, valid range 0…127 Bit Meaning 7 reserved, coded as 0 6 0: There is only this error.
1: There are more error codes in the node which will be sent with the next messages.
5…0 0x00 no (more) errors. When bit 6 is set, it is the end of the error list and the next message will start over. 0x01 unknown object/invalid aspect. The received command could not be executed and is ignored. This error code is always sent with Aspect=255, but the previous error condition and aspect remain. 0x02 power consumption too high. 0x03 power supply below limits, function not garanteed. 0x04 fuse blown. 0x05 temperature too high. 0x06 feedback error (e.g. detection of unwanted position change, unsuccessful execution). This error code might be sent together with a new aspect, often 255 ("unknown"). 0x07 local control (eg. with button on the device). This error code might be sent together with the new aspect. 0x10 bulb out of order. 0x20 servo out of order. 0x3F internal error (eg. selftest, checksum error, …).
SecureSwitch: The message MSG_ACCESSORY_STATE is sent by the node as answer to MSG_ACCESSORY_SET (in any case). It may contain either an 'execution performed'-, a 'please wait'- or an error message.
This message informs the host about the state of the accessory object. This message will be sent at spontaneous dispatch if there is i.e. a manual opertion or an error condition. Prerequisite is, that SYS_ENABLE is set and the feature FEATURE_ACCESSORY_SURVEILLED is set to 1.
Five bytes are following, coded in the same way as with MSG_ACCESSORY_STATE.
Reaction of the host program:
- The message shall be acknowledged with a query (MSG_ACCESSORY_GET) or command (MSG_ACCESSORY_SET) to this accessory object. If this confirmation is missing, then the node repeats the message MSG_ACCESSORY_NOTIFY up eight times, repetition interval is 500ms.
- If bit 6 in WAIT is set (=there are more error states in the node), these errors should be collected by one or more additional MSG_ACCESSORY_GET messages until error code 0x00 is reached.
This message will be sent as an answer to a request or change of (configuration) parameters.
Two or more bytes are following: ANUM, PARA_NUM [Data], same coding as for MSG_ACCESSORY_PARA_SET.