BiDiB, a universal control set for model railways

The German version is the definitive specification. Any discrepancies between this translation and the original are unintentional.

Accessories

BiDiB - Bidirectional Bus - Logo

Content

General

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.29 of BiDiB, updated June 21, 2023.

The revision history can be found at the general section.

4.6. Accessory and peripheral classes

Overview BiDiB auxiliary equipment
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.

4.6.1. Controlling of track system accessory functions

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'.

Accessory objects each have an 'aspect' 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. The state of an accessory is solely controlled by the host, it cannot be perturbed by external influences. On its own the accessory can only transition into an error state.

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 a problem arises, the node will automatically 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.

MSG_ACCESSORY_NOTIFY can also be used to send intermediate reports during the execution. This may include additional information like turning angle next to the remaining time.

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.

Extensive objects can be controlled through multiple accessories, their "multi-dimensional" state space consists of the aspects of the individual accessories. The node then maps each tuple of the product set of the accessory states onto its outputs. All combinations are viable and selectable – there are no invalid ones –, though some may share the same meaning and impact. The unrestricted composition of the object from the accessories takes place in the host software.

The messages to the various accessories continue to stay independent of each other, an activation must not have side effects on other aspect values. For convenience, a control program may always send the whole aspect combination to all accessories. The switching times and error states of all parts need to be considered in the process.

Example: A main signal with a speed display is represented with two accessories, one for the signal aspect and one for the speed digit. An added distant speed display would constitute a third accessory. This is simpler than to meld all possible combinations of light patterns into a single accessory state.

Even when the additional signal is extinguished as soon as Hp 0 is shown, the activation of the signal aspect will not change the accessory aspect to "display no speed", a query will keep returning the set value. The combination of the aspects "Hp 0"+"digit 3" leads to the same visual pattern as "Hp 0"+"no digit", without requiring special consideration from the host system.

A special case of composed object control is the operating mode. 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 for 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 to the total state 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.

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.

4.6.2. Features for accessory functions

The properties of a node can be given by feature retrieval. Please note: Feature values outside the given range are reserved.

Listing of features for the accessory-control class
NumberNameMeaning
40 FEATURE_ACCESSORY_COUNT Number of turnouts / signals
This feature returns the number of controllable objects. Range: 0…128.
41 FEATURE_ACCESSORY_SURVEILLED Position observation
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.

4.6.3. Downlink: Messages for accessory functions
  • MSG_ACCESSORY_SET:

    Operate an accessory, 2 bytes are following: ANUM, ASPECT. These two bytes define the controllable object and the desired aspect.

    MSG_ACCESSORY_SET parameters
    ParameterDescription
    ANUM Identifies the accessory object within the node, range 0…127.
    ASPECT This byte defines the state of the object, the non-operating state is represented by 0. The value 254 puts the model at a safe rest ("emergency stop"). 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 switching time. After completion another MSG_ACCESSORY_STATE will be sent to indicate the finished sequence.

    SecureSwitch:
    The acknowledgement via MSG_ACCESSORY_STATE is compulsory for the node. It may contain either a success report, a waiting prompt or an error message. As long as it is absent, the control program will not use the accessory but inquire the execution state explicitly. Occasionally the MSG_ACCESSORY_SET command may even be repeated.

    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 responds with MSG_ACCESSORY_STATE, aspect = 255, error code 0x01.

  • MSG_ACCESSORY_GET:

    The state of the object can be queried with this message. One byte is following: ANUM.

    The node replies with MSG_ACCESSORY_STATE.

  • MSG_ACCESSORY_GETALL:

    The state of all accessory objects of the node can be queried with this message. No parameter bytes follow.

    The node replies with a MSG_ACCESSORY_STATE per object. The number of responses to expect corresponds to the FEATURE_ACCESSORY_COUNT.

    The node is responsible for flowcontrol of responses and adjusts to the available transport capacity itself. The node must be able to receive and respond to other messages while delivering the answer sequence.

    The message is available from declared protocol version 0.8 or further.

  • MSG_ACCESSORY_PARA_SET:

    (optional)

    The configuration parameters of an accessory object can be set with this message.

    Two or more bytes are following:

    MSG_ACCESSORY_PARA_SET parameters
    ParameterDescription
    ANUM Identifies the object at the node, range 0…127.
    PARA_NUM Number of the parameter to set.
    DATA[0…] 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
    ValueNameMeaning
    1-248   –   Reserved.
    249 BIDIB_ACCESSORY_PARA_USES_STRINGS The accessory is responsible for the selection of a string for text output on a display, the aspects 0 to TOTAL-1 correspond to the strings from namespace 2 (index 0 to TOTAL-1). A single byte with the value 1 follows. The string namespace 2 has at least the length of TOTAL.
    This parameter allows to offer a suitable aspect switching control for the affected accessories. It is typically non-writable.
    250 BIDIB_ACCESSORY_PARA_HAS_ESTOP The accessory supports the emergency stop aspect.
    A single byte with the value 1 follows. If the parameter is not present or holds a different value, the accessory does not have implemented an emergency stop and will respond only with an error to attempts of using it.
    The parameter is typically non-writable.
    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.
    Nodes that don't have this parameter shall behave as if the value 255 set.
    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.
    • etc.
    The length of the list is limited to 16. Only valid macro numbers are allowed. The end of the list will be indicated with an entry of 255. The list will be adopted by the node until the maximum number of aspects.
    (see also FEATURE_ACCESSORY_MACROMAPPED)
    254 BIDIB_ACCESSORY_SWITCH_TIME Switch time, defined like in the railcom specification.
    BitMeaning
    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.
  • MSG_ACCESSORY_PARA_GET:

    (optional)

    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.

4.6.4. Uplink: Messages for accessory functions
  • MSG_ACCESSORY_STATE:

    This message informs the host about the state of the accessory object. This response will be sent after a query (MSG_ACCESSORY_GET), after a activation command (MSG_ACCESSORY_SET) or spontaneously when reaching the target condition.

    Five or more bytes are following:

    MSG_ACCESSORY_STATE parameters
    ParameterDescription
    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=254 the object did an emergency shutdown, all movements are halted to prevent damage to models. 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 Hp 0, Hp 1, Hp 2: 3 aspects: 0, 1 und 2

    If an object supports the emergency stop aspect, this has to be declared in the parameter HAS_ESTOP.

    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 7Meaning
    0 normal operation
    BitMeaning
    00: Target state reached. WAIT is 0.
    1: Target state not reached. WAIT tells about the expected remaining time.
    10: Target state is verified by feedback (e.g. switching contact).
    1: Verification of target state does not exist.
    6…2reserved, coded as 0
    1 Error happened (e.g. broken coil / manual displacement); WAIT tells the cause (coded like railcom specification) an.
    BitMeaning
    6…0reserved, coded as 0
    In case of an error, the last reported operation state (target reached vs. still moving) is kept.
    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.
    BitMeaning
    7 Base Unit:
    0: 100ms (total range = 0…12,7s)
    1: 1s (total range = 0…127s)
    6…0 switch time, valid range 0…127
    Error Code:
    BitMeaning
    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
    0x00no (more) errors. When bit 6 is set, it is the end of the error list and the next message will start over.
    0x01unknown 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.
    0x02power consumption too high.
    0x03power supply below limits, function not garanteed.
    0x04fuse blown.
    0x05temperature too high.
    0x06feedback error (e.g. detection of unwanted position change, unsuccessful execution). This error code might be sent together with a new aspect, often 255 ("unknown").
    0x07local control (eg. with button on the device). This error code might be sent together with the new aspect.
    0x10bulb out of order.
    0x20servo out of order.
    0x3Finternal error (eg. selftest, checksum error, …).
    An error state with cause 0x06 or 0x07 can be relieved through MSG_ACCESSORY_SET.
    DETAILS[0…40] Optional supplemental details about the current state of the accessory operation. They conduce to precise tracking and display of an accessory, but are not operationally relevant. The node decides which information is appended when, a targeted query is not available. The data is transferred as a list with 0 to 8 key-value pairs, consisting of parameter type and value. 
    DETAILS_LIST ::= ε | DETAIL_PAIR DETAILS_LIST
DETAIL_PAIR ::= D_ENUM1 D_VALUE | D_ENUM2 D_VALUE[2]
D_ENUM1 = 0x00 | … | 0x3F
D_ENUM2 = 0x40 | … | 0x7F
    Encoding of state detail parameters
    NameCodeValue typeDescription
    BIDIB_ACC_DETAIL_CURR_ANGLE1DEG5 0x01 uint8 Current position angle (for instance of a turntable) in units of 1.5 degree, value range 0…239. Objects with an adjustable min/max range also scale their position reports to the range 0…239.
    BIDIB_ACC_DETAIL_TARGET_ANGLE1DEG5 0x02 uint8 Targeted position angle at the end of the movement, in units of 1.5 degree, value range 0…239.
    BIDIB_ACC_DETAIL_TIMESTAMP 0x40 uint16 System timestamp for the moment of position measurement.

    The spontaneous report for the completion of the operation sequence may only be sent when SYS_ENABLE is set. It won't be acknowledged by the host either. The accessory state can however be queried at any time (also during the switching operation) via MSG_ACCESSORY_GET, a repeated polling is conceivable.

    Spontaneous events outside the switching sequence or aspect changes are announced through MSG_ACCESSORY_NOTIFY.

  • MSG_ACCESSORY_NOTIFY:

    This message reports the state of the accessory object to the host. This message will be sent when a spontaneous event (e.g. state detail change, manual displacment or an error condition) occurs. Prerequisite is, that SYS_ENABLE is set and the feature FEATURE_ACCESSORY_SURVEILLED is set to 1.

    Five or more bytes are following, coded in the same way as for MSG_ACCESSORY_STATE.

    SecureSwitch:
    The reception of a MSG_ACCESSORY_NOTIFY (with WAIT=0) must be 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 to eight times, repetition interval is 500ms.
    A MSG_ACCESSORY_NOTIFY with WAIT!=0 is an intermediate update and need not be acknowledged.
    In the case of a change of the ASPECT, either the announced aspect can be accepted as 'new' or it can be attempted to renew the previous aspect.

    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.

  • MSG_ACCESSORY_PARA:

    (optional)

    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.