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.
BiDiB - Bidirectional Bus - Logo

Content

1. General

1.1. Objective target, special properties

BiDiB is designed to control model railways, as there are control of locos, accessories and safe transmission from feedback information out of the layout to a connected PC. BiDiB is short for Bidirectional Bus and has the following advantages:

The above picture shows a typical arrangement. The protocol is suitable for different feedback systems and can manage simple home layouts up to large exhibition layouts. The Protocol can be easily adapted to nearly all requirements. For this purpose, there is a mandatory set of query and setting parameters existing that must be implemented in every feedback system. The following used terms will be summarized and explaned in the glossary.

1.2. Origin and History

Lenz and Tams introduced BiDi feedback systems by 2009, therefore the use of bi-directional data transfer between DCC decoders and control units was theoretically possible. Suitable feedback systems has been announced, but by the end of 2010, only the simple Tams RC Talk was available in the market. From the discussion about a future proof successor, the BiDiB protocol was created. This was the base for an enhanced draft, which also includes command stations, accessories and control panels.

At this point, I would like to say "Thank you" to my discussion partners, Mr. Tams, Mr. Bluecher and Mr. Herzog for their constructive input.

1.3. Disclaimer, License

BiDiB® is maintained and developed further by a working group (BiDiB-Implement-Group). Among other, the sirs Kersten Tams, Markus Herzog and Wolfgang Kufer are authoritative members of this group.

Legal: This specification is provided "as is" and without any warranty of any kind, expressed or implied. Without limitation, there is no warranty of non-infringement, no warranty of merchantability, and no warranty of fitness for a particular purpose. all warranties are expressly disclaimed. The user assumes the full risk of using this specification. In no event shall any member of BiDiB-Implement-Group be liable for any actual, direct, indirect, punitive, or consequential damages arising from such use, even if advised of the possibility of such damages.

BiDiB is intended for use with model railroad control software and may be implemented without license costs at the PC side as well as on the hardware side. To ensure compatibility, the following license terms & conditions have to be observed:

1.4. Revision status

This document describes revision 1.27 of BiDiB, updated apr 07, 2017.

This document describes the basic message structure. Messages that are specifically associated with an application (e.g. switching, detection, driving,...) will be described in other documents or chapters.

Revision history
1.272017-04-07 added: position reports, BiDiB system time, porttype SWITCHPAIR, configuration fingerprints, accessory emergency stop, accessory details
1.262016-08-15 added: BIDIB_ACCESSORY_PARA_STARTUP, BIDIB_ACCESSORY_PARA_OPMODE. Rework of all parts, explanations and clarifications.
 2016-02-25 revised port control, added MSG_LC_PORT_QUERY_ALL, protocol version 0.6⇒0.7
1.252015-11-28 revised byte order of port addresses in the flat model
1.242015-03-22 added MSG_CONFIGX_GET_ALL, flat port model (see port control), protocol version 0.5⇒0.6
 2014-12-04 added new macro command FLAG_QUERY0
1.232014-11-11 add new configuration messages for ports (CONFIGX*)
 2014-08-14 additional defines for POM (DCC generation)
 2014-07-25 additional items in the licence section
V1.222014-06-26 added: BIDIB_MSYS_SERVOMOVE_QUERY, longer responses for version queries
V1.222014-02-07 added: MSG_ACCESSORY_NOTIFY, MSG_BM_DYN_STATE, MSG_CS_PROG, MSG_CS_PROG_STATE
V1.212013-12-16 added: MSG_STRING_GET, _SET, MSG_STRING, FEATURE_STRING_SIZE
V1.202013-11-18 added hints and explanation for turntables; BIDIB_CS_STATE_GO_IGN_WD
V1.202013-10-29 added MSG_SYS_GET_UNIQUE_ID mandatory for standalone bootloader
V1.19.12013-10-21 Translation from speed to DCC28/DCC14 now mandatory, formula and example added
V1.192013-10-04 MSG_LC_OUTPUT_QUERY added; new features: FEATURE_RELEVANT_PID_BITS, FEATURE_CTRL_PORT_QUERY_AVAILABLE
new: BIDIB_MSYS_ACC_OKAY_QIN1, BIDIB_MSYS_ACC_OKAY_QIN0, BIDIB_MSYS_ACC_OKAY_NF
V1.182013-07-18 Additional responses to GET_SYS_MAGIC (Support for tiny bootloader). Added SecureSwitch definition to accessory
 2013-06-29 Update of licence conditions
V1.172013-06-18 Introduction of a watchdog for DCC generation, added FEATURE_GEN_WATCHDOG
V1.162013-06-02 more details on MSG_SYS_RESET, added FEATURE_CTRL_STRETCH_DIMM
V1.152013-04-20 added transmission of error codes for accessory
V1.142013-04-02 unified definition of switch time
V1.132013-03-25 MSG_LOGON_REJECTED added. Error handling in case of too much participants
V1.122013-02-23 MSG_BOOST_CURRENT will be replaced with MSG_BOOST_DIAGNOSTIC.
V1.112013-01-30 Parameter added for MSG_BOOST_ON and _OFF
V1.102013-01-23 MSG_CS_BIN_STATE completed
V1.092013-01-17 FEATURE_BST_INHIBIT_AUTOSTART completed
V1.092012-12-21 Explanations for MSG_CS_DRIVE_ACK; MSG_BOOST_QUERY completed
V1.082012-11-13 Explanation and final coding for MSG_BM_SPEED, FEATURE_BM_ISTSPEED_INTERVAL
V1.072012-10-12 Supplementation of the class accessory, Parameter at MSG_STALL; Explanation for MSG_CS_DRIVE
V1.062012-09-26 Accessory class: MSG_LC_WAIT added, Spelling corrections.
V1.052012-09-24 Occupancy class: Additional commands MSG_BM_GET_CONFIDENCE and MSG_BM_CONFIDENCE.
V1.042012-07-25 Additional explanations for MSG_VENDOR*. MSG_SYS_PING / MSG_SYS_PONG got a new parameterp
Supplementation for switch class: BIDIB_MACRO_RESTORE, BIDIB_MSYS_DELAY_RANDOM, MACRO_PARA now 32 Bit.
V1.032012-07-25 Additional explanations for MSG_VENDOR*.
V1.022012-06-06 Explanation for MSG_NODE_LOST corrected.
V1.012012-03-19 MSG_FEATURE_GETALL, MSG_FEATURE_GETNEXT, MSG_NODETAB_GETALL, MSG_NODETAB_GETNEXT, Transmission process for Features und Nodes explained.
V0.132012-02-21 MSG_BM_ADDRESS with opportunity to report multiple occupancy. reference at MSG_BM_SPEED.
V0.122011-07-20 Local command for PING and PONG added; MSG_BM_MIRROR_OCC and _FREE added.
V0.112011-07-20 New feature-parameter for Booster, system time, MSG_BOOST_STAT messages extended. Current setting for booster added.
V0.102011-04-02 Suggestions for decoder registration added, new message MSG_BM_BLOCK_CV for block reading of CVs..
V0.092011-02-24 Changes at the NODE_TAB (in case of no sub-nodes), more failure codes added.
MSG_SYS_GET_ERROR added.
V0.082010-12-20 Booster class completed.
V0.072010-12-07 Explanations for Vendor config, V_VALUE added; failure messages extended; MSG_SYS_MAGIC with index 0; Enable /Disable with auto-forward to sub-nodes. BM_MSG for accessory added.
MSG_SYS_IDENTIFY_STATE added.
V0.062010-12-06 Explanations for NODE_CHANGE added
V0.052010-12-01 Unique-ID explained, PKT_CAPACITY new added, ClassID added
V0.042010-11-29 Packet structure for routing optimized, Fine tuning.
new added: MSG_BM_SET_SIZE, MSG_BM_GET_SIZE
V0.032010-11-25 Extension for hubs and sub-nodes.
V0.022010-11-17 Extension for heterogeneous feedback modules, Individualisation of feature sets for single modules
V0.012010-11-03 Initial document

1.5. Design principles

BiDiB is designed as a stateless protocol. There exist several safeguards to deal with message losses.

The most important property to achieve a high error tolerance is the idempotence of the messages. Generally messages transmit states, not commands or orders. Their reception is typically acknowledged by the node with a message of equal content. Thereby the transmission can simply be repeated in case of an error, without causing undesired actions when received multiple times. This holds in particular for the critical model railroad applications driving, controlling and feedback. An identifier is always used in sequential transmissions with multiple messages, so that missing information can be requested again.

Communication errors on the other hand are reported once only and not repeated, which simplifies the implementation. A loss of an error message can be handled the same way as the absence of the regular answer. If multiple errors occur together, they can be put in a queue to be retrieved, but they don't have to be repeated either. If an error persists, it simply is reported again at the next attempt of using the object. A recovery from an error is generally not reported. Some objects where fault/error conditions are intrinsic (e.g. boosters and accessories) constitute exceptions hereof, retention or repetition might be required for them.

Likewise dealt with are spontaneous events that are not mission-critical. The loss of such messages can only be detected by checking sequence numbers, but there is no mandated error handling and no way to retransmit the message. For operation critical events (Occupancy, Accessory) there are acknowledgement mechanisms "Secure-ACK" and "Secure-Switch" as safeguards.

The continuing revolution of BiDiB is deep-seated in the protocol. Rigorous attention is paid to backward compatibility of new revisions of the specification. Extensions to the functional range are usually readily possible, as they are typically optional and can be ignored. In case of backward incompatible changes the protocol version is incremented, which can be retrieved from every node. This does allow the support of out-dated implementations and even assures the compatibility with unknown functions to some degree.

1.6. Glossary

The following terms for each protocol participant or properties will be used in this document:

BiDiB: The protocol standard, the way how messages are encoded.
BiDiBus: One possible physical implementation, specially for wired connections within a model railway. BiDiBus is based on RS485 and uses RJ45 cables.
Bus system: The complete setup, consisting interface and nodes (i.e. detectors) + possibly internal connections.
Class: Nodes are divided in classes, depending on their basic properties. There are as example: occupancy detectors, DCC Generators, Switch outputs, Track panels.
Detector: A single node within the BiDiB system which is able to detect track occupancy and recognize BiDi feedback signals.
Feature: Particular property of a node (e.g. 'detector can recognize loco direction'). Features can be queried and configured individually.
Host: The control computer, usually a standard PC with appropriate software.
Hub: A node in one level of the bus system, which is also an interface to the next lower level.
Interface: The location within a level (structure) in the bus system, which communicates with the host or parent-node.
Logon: The attempt of a node to get a logical connection to an interface. The logon is acknowledged and the host is notified about the change.
Node: A subscriber inside the BiDiB system (occasionally distributed) hardware. A subscriber within a level might be also an interface for the next sub-level (Hub-functionality).
Unique-ID, Unique-ID: The globally biunique node identifier. It contains the announced classes, the manufacturer code, and a vendor-specific number derived from the hardware ID.
Node-address: The automatic assigned number from the interface (byte), under which the node is (at this level) addressed in this session. (NODE_ADDR)
Magic: A (meaningless) number, which will be queried by the host during interface startup. For example the correct baud setting can be recognized. (=system id)

1.7. Principles of node assignment, addressing

An system addressed with BiDiB is organized like folders: The host provides an interface that allows it to establish a communications link and the interface allows him access to a (flat) array of nodes. Each of these nodes is usually a component that contains a particular function (for example, a detector with feedback contacts). But it is also possible that this block itself is an interface too, which holds a further structure (like subfolders). This achieves high flexibility in wiring possibilities and also in the heterogeneity of the connected detectors.

BiDiB is able to assign addresses automatically to nodes. Each node has an unique manufacturer-programmed number that is part of the Unique-ID. During startup of the feedback system, the interface searches existing nodes within its structure and assign a local address to each node. This address has the length of one byte. The interface builds a assignment table with all available nodes, their Unique-ID and their local address. Nodes itself can be also interfaces which gives a threaded structure. The maximum address length within the thread is 4 bytes.

This assignment table is different on each startup and will be automatically extended if a new node is added to the bus. In this case, the interface transmits a message to the host.

Internal to the host, the nodes are also stored with their unique ID, besides the program-specific things like screen position and node name. The host will retrieve the mapping from the interface during startup and gets the valid local addresses for this session that belongs to the unique IDs. The mapping between the object on the user interface and the model hardware is done through the node identity and is therefore independent from the current address assignment.

To facilitate the replacement of nodes, it should be minded in host programs that the Uniqued-ID assigned to a node object can easily be exchanged for another one. Because the unique ID of a device cannot be set by the user, they cannot program the replacement node to the "old address" to continue using the mapping configured in the program; instead it is necessary to make the change within the host software. The swapping of the unique ID is needed for instance when replacing a defective device by a identically constructed one, when upgrading hardware to a superior product with more outputs, or when deploying a different product firmware for more functionality.

How does the first time node assignment is working?
If the host reads the mapping table and he found one ore more new node(s) which are not listed in the layout, he may show this newly available nodes in a separate pool of 'new detectors/command stations/boosters etc.'. For example, you can trigger a flashing of the occupancy detection (or Identify) by pressing the identify button on the target node and then assign the correct section of track in the PC.
What happens if a node with occupancy functionality fails or has been replaced?
The PC can display an error message if he reads the mapping table and miss a unique ID for an already configured occupancy detector. It might be also possible that a new indicator appears in parallel. In this case, the program could ask whether this new detector replaces the old one right away.

2. Physical implementation

BiDiB protocol is suitable for different transmission media such as serial connection, USB, RS485, Ethernet or wireless (with an adapted framing for each media). For specifications, refer to the respective documents.

The respective physical layer ensures the correct framing and bytewise, transparent transport of BiDiB message packets. The transfer layer must secure the transport of the data with CRC. The transfer layer must at least be able to transport messages with a size of 64 bytes.

CRC means the CRC8-Byte; On the transmitter side, the polynom x8 + x5 + x4 + 1 will be generated over the message, starting at the first byte from the message, Init=0, none inverted. On receiver side, the CRC with the same polynom will be generated over the whole message including CRC. The result must be 0.

3. Protocol description

3.1. Basic message structure

A MESSAGE is structured as follows:

MESSAGE ::= MSG_LENGTH  MSG_ADDR  MSG_NUM  MSG_TYPE  DATA
MSG_LENGTH ::= 0x00 | … | 0x7f
MSG_ADDR ::= MSG_ADDR_STACK  0x00
MSG_ADDR_STACK ::= ε | NODE_ADDR  MSG_ADDR_STACK
NODE_ADDR ::= 0x01 | … | 0xff
MSG_NUM ::= 0x00 | … | 0xff
MSG_TYPE ::= 0x00 | … | 0xff
DATA ::= ε | ANY_BYTE  DATA
ANY_BYTE ::= 0x00 | … | 0xff

A message contains the length, an address specification, a (consecutive) message number, a type specification and optional parameters. These fields are described below:

The data securing against transmission errors is the responsibility of the respective transport medium (e.g. CRC in case of serial transmission). The protocol itself doesn't provide message retransmit, critical messages are secured at a higher level (e.g. with Secure-ACK or corresponding response of the node).

The message length (MSG_LENGTH) does not only delimit messages where multiple are sequenced back-to-back, but also specifies how many DATA bytes are actually available as message parameters. This might indeed be more or less bytes than the message type suggests. Thereby optional parameters can be accomplished that are set to default values if not existent. If less parameters are sent than necessary, the node responds with an error message. If more parameters are sent than expected, the surplus bytes are ignored; this assures forward compatibility.

A message may have a length up to 64 bytes (MSG_LENGTH=63), all transport layers need to support these. Longer downstream messages can, as long as supported by the respective transport layer and node, be allowed per node via the MSG_PKT_CAPACITY message. To send a long message to a node, all interfaces on the transport path have to support this as well. Longer upstream messages shall be limited in accordance with the lengths used in the downstream.

3.2. Routing

BiDiB allows to wire subnets and connect them in star topology via hubs (similar to USB). This provides scalability for large model layouts. For smaller layouts, probably only one network will be build and therefore the information in this chapter can be skipped for now.

Local address assignment in sub-networks is described in a further document For the protocol description, only the results of this process are relevant.

A maximum of 4 cascaded networks is allowed. This limitation is intended to facilitate host implementations, thereby the respective current local address of a endnode is limited to 32 bits.

The following rules apply for the routing of messages:

To enable the parent node, respectively the host, to detect this structure, appropriate commands are existing:

If there is a change in the assignment table during operation (e.g. connect or disconnect), the interface sends a MSG_NODE_LOST or MSG_NODE_NEW message anyway. This message must be acknowledged by MSG_NODE_CHANGED_ACK (or a complete node table query). Both messages MSG_NODE_LOST, MSG_NODE_NEW and also MSG_NODE_CHANGED_ACK have the (continuous) version number of the table as a parameter. This ensures that all changes at the bus structure will be recognized.

Changes in the node table should be avoided by the interface (e.g. transmit no logon request). If there is a change in the node table while being queried and transmitted with MSG_NODETAB_GETNEXT, the interface must start over again with the transmission of a new MSG_NODETAB_COUNT (but with an incremented version number).

3.3. Unique-ID

Each node has a distinct identifer, this number is called Unique-ID. The Unique-ID contains 7 bytes:

Structure of Unique-ID
1. Byte ClassID

This is a bit field indicating the class membership of this node. A node may also belong to several classes at once.

The classes serve as a quick reference for the host about which functionalities can be found on this specific node. To rapidly locate a feature-based subfunctionality it is enough to only query the nodes which have set the corresponding class bit.

If a node has implemented commands of a particular class, the appropriate class bit must be set as well. Conversely, it must know the commands of the announced classes and answer them correctly. Even if in the current configuration no objects are available, it should register the class and yield 0 for the count.

Bit 71: Node contains sub-nodes (is an interface itself)
Bit 61: Node contains occupancy detection functions
Bit 5reserved (1: Node contains operating functions, HMI)
Bit 41: Node contains DCC signal generator for driving, switching
Bit 31: Node contains DCC signal generator for programming
Bit 21: Node contains accessory control functions
Bit 11: Node contains booster functions
Bit 01: Node contains switching functions, e.g. light animation

Reserved bits must be coded as 0.

2. Byte ClassID Extension; this byte is reserved and must be coded with 0.
3. Byte Vendor-ID: The same coding as DCC is used here, see NMRA Manufacturer ID Numbers.
4.-7. Byte Product ID, comprising of 32 Bit.

These 4 bytes (= 32 bits) are split into a product identifier (lower 'p' bits) and a serial number (upper 's' bits). This allows for an easier identification of nodes by analysis tools and host programs. The coding in BiDiB is always little-endian (low-byte first), the product identifier starts at bit 0, first byte. It is up to the vendor, how many bits he uses for product and for serial number. However, a default of 16 bit / 16 bit is recommended. The feature FEATURE_RELEVANT_PID_BITS defines, how many bits are used for product ('p').

If the feature FEATURE_RELEVANT_PID_BITS doesn't exist, the default of 16 bits / 16 bits is used.

The uniqueness of the product ID (and with it, the Unique-ID) is guaranteed by every vendor through the hardcoded serial numbers. Neither the unique ID nor the product ID constitute a fixed hardware identifier however, one and the same device can have several firmwares installed which may differ in their classes or even product types. Only the serial number remains the same normally, but on its own that is not necessarily unique.

Representation of the unique-ID at host programs / stickers / tools:
A unified representation of the unique-ID is recommended, so users can easily assign modules. Vendor-ID should be detached from the unique-ID and the 4. until 7.byte (in this order) should be displayed as a HEX value.
Examples:
  • VID 0D PID 0278456B
  • Vendor: Public Domain & Do-It-Yourself Decoders, Unique ID 0x0278456B

Additionally, there might be a user string stored in the node (nick name, see MSG_STRING). This name can be used as alternative for the presentation of the node.

3.4. Typical protocol startup

Connecting to a BiDiB system can be done according to the following list:

  1. Connection to the first node (usually the interface).
    For example, with a serial interface: The host sends two MAGIC characters, followed by a MSG_SYS_GET_MAGIC message. This will be made with the possible baud rates and determine whether a error free response is coming from the interface. A 300ms timeout is enough at this point.
  2. Stopping the BiDiB system.
    By sending a MSG_SYS_DISABLE, the spontaneous transmission of messages is suppressed. This is primarily used to avoid interruption through spontaneous messages in the following read-out phase.
    Alternatively, the system can also execute a complete restart of the node including new assignment through MSG_SYS_RESET.
  3. Now we read the properties of the first node.
    Important here is the answers to MSG_GET_SYS_MAGIC, MSG_SYS_GET_P_VERSION and the class bits from the Unique-ID, that indicate the properties of the node and which messages it does support.
    If the node is an interface, the node list must be queried (MSG_NODETAB_GETALL). Furthermore, you can query all features and other information of this node (MSG_FEATURE_GETALL).
    Please note that the simultaneous queries for a single node are limited, the expected response may not exceed the size of 48 bytes.
    If a node supports configuration fingerprinting, you can quickly check with the answer to MSG_SYS_GET_UNIQUE_ID whether the settings still match the already known ones.
  4. Additional nodes.
    If additional nodes have been reported, step 3 must be repeated for all nodes that have been obtained in the node list. In case there is again a node with an interface, this interface will be also queried for the node list.
    It is possible to handle multiple nodes in parallel. For example, transmitting a MSG_FEATURE_GETNEXT for each MSG_FEATURE immediately. A 500ms timeout is enough at this point
  5. Release.
    If all data has been read, then the system can be released for spontaneous messages with MSG_SYS_ENABLE.

3.5. Classes

Nodes declare different classes via their Unique ID, e.g. occupancy detection, hub or booster functionality. To what extent a class is implemented is announced through feature settings.

For each class there are mandatory messages that have to be implemented, as well as optional messages that are only available if a feature declares them to be.

Class Interface:
An Interface (Hub) transports messages from and to further nodes on a sub level.
Class Occupancy:
The node contains occupancy detectors.
Class DCC-Generator:
The node provides DCC drive and switch commands.
Class DCC-Programming:
The node provides DCC service mode commands.
Class Accessory Control:
The node provides control functions for track system accessories.
Class Booster:
A booster amplifies the DCC signal for decoders (but does not generate it).
Class Peripherals:
The node provides switching and animation functionality for peripheral equipment and lights.

3.6. System time

A BiDiB system has a global system time available to achieve a higher accuracy in time-based measurements. Various messages may contain a timestamp for the respective event, this allows for better results in vehicle tracking and calibration. The uncertainty in the latency of the data transmission is eliminated.

The BiDiB system time has a resolution of 1 millisecond and is represented by a 16-bit integer with cyclic overflow An error margin of ±5 ms between the clocks of all nodes in a system is aspired.

To facilitate a time measurement across different nodes, the clocks of the nodes have to be synced. This synchronisation happens on every bus level depending on the transport layer and is carried out by the respective interface. Whether an interface/hub does or not support it must be stated in the product description.

The synchronisation typically happens through a periodically emitted broadcast message with a timestamp. On the receipt of this message, the local node clock is set to the system time. Delays on the communication path or internally at the transmission and reception need to be considered and have to be corrected through according offsets, the arising inaccuracy should be ±1ms per bus level at most. With this approach a (small) step in the time series at the point of adjustment may occur, a host will need to take such into account.

If the synchronisation is absent, a node must refrain from the use of timestamps as soon as the resulting uncertainty becomes larger than ±3 ms. Example: if a processor clock rate has a divergence of up to 10ppm (0,01 ‰), then it should not use its local clock from about 100 s after the last synchronisation.

An interface should wait for synchronisation from the upper level before supplying the system time to its subnodes. If a synchronisation message fails to appear until the SYS_ENABLE (or a reasonable timeout), the interface may use its local clock time and synchronise the bus structure on its own.

4. Messages

The messages, which are used on the BiDiB system, can be divided into the following categories:

System Software and hardware version and product identification query, system start and -stop, connection settings, node address settings and queries.
Feature Querying and setting of the node properties (features).
User-Config Open messages for advanced, vendor-specific configuration.
Messages for firmware updates Uploading of new node software.
Messages for Detectors Occupancy reports and decoder feedback
Messages for Booster Monitoring of boosters
Messages for command stations DCC motion and switch commands
Messages for accessory control Turnouts, signals, track system functions
Messages for configuration and direct port control Illumination, animations, sound, peripheral equipment

Downlink describes the direction Host -> BiDiB-System, uplink means the direction to the host.

In general, messages occur spontaneously at the uplink (after approval at the interface). Some messages types can be switch on or off by feature settings.

4.1. System messages

System messages are mandatory for all standard BiDiB nodes, only exception are bootloader nodes, see MSG_SYS_MAGIC for more details.

4.1.1. Downlink: System messages

Common system messages

System messages for bus management

Hints for implementation: this messages are mandatory, but these messages include only variable data at interface nodes. Simple nodes have constant data. This means the answers to MSG_NODETAB_GET* etc. can be stored as constants and can be implemented also on very small microcontrollers. BiDiB has an automatic node assignment (e.g. detector, booster, etc.). This mapping is stored in the interface and can be collected from there. For this purpose, the following messages are provided:

System messages for layout management

(Hints for implementation: this messages are mandatory)

4.1.2. Uplink: System messages

Common system messages

System messages for bus management

(Note about implementation: These messages are for interface nodes with variable data, simple end nodes have constant data, corresponding responses can therefore be statically stored in the processor flash memory).

4.2. Querying and setting of feature settings

Preamble: There are different implementation and requirements for a BiDiB system, which are also partially specific to the layout. In addition, nodes with different properties might be installed at the layout.

Examples:
In an model layout with center rail, the direction signal is invalid; the user shall (and have to) disable this property in the occupancy detector.
The occupancy detector of company XYZ is able to perform current measurement but the software from company ABC can't interpret this data. So the software ABC will disable the transmission of current measurement values.

For this reason, there is the ability in the protocol to query properties of nodes and also to configure the node, this means to enable this property. This is done through the feature-settings. If a node does not support a particular property, then the corresponding feature-setting can not be changed. The host can control this by testreading the settings that have been made.

The answering for feature messages is mandatory for nodes, but features are not. The ID's for certain feature setting are mandatory. Not assigned feature IDs are reserved. Extensions for new features (new ID's) must be applied for at the BiDiB workgroup.

Listing of general purpose features
NumberNameMeaning
252 FEATURE_STRING_SIZE Maximum number of chars for strings. Range: 0; 8…24
(If the feature FEATURE_STRING_SIZE is missing, the node can't handle the corresponding messages.
253 FEATURE_RELEVANT_PID_BITS Number of significant bits for the product ID (contained in the Unique ID). Range: 1…31.
Default 16. (If the feature FEATURE_RELEVANT_PID_BITS is missing, the default 16 bits for product ID and 16 bits for serial number is used.
4.2.1. Downlink: Messages for querying and setting of feature settings

The encoding of feature sets for each class is provided in the documentation of the individual classes.

If a node is addressed with a unknown feature ID, a MSG_FEATURE_NA (= feature not available) will be returned.

4.2.2. Uplink: Messages for feature notifications

For the answer to a query feature, the following message types are used:

4.3. Messages for user configuration

There are some vendor-specific parameters, which goes beyond the normal configuration. For this part of the protocol, only the transmission technique is defined, parameter name and content is in the responsibility of the manufacturer.

Vendor-specific data transmissions may not be used for control, feedback and other commands, for which a counterpart is existing in the normal protocol.

Before these parameters can be transmitted, the corresponding node must be activated with its UNIQUE-ID. No other messages except VENDOR_** are allowed between VENDOR_ENABLE and VENDOR_DISABLE. Other requests are only allowed after the node has confirmed MSG_VENDOR_DISABLE.

4.3.1. Downlink: Messages for user configuration

V_NAME and V_VALUE are ASCII sequences. If the sequence begins with a 0 to 9 digit, it is a numeric value. V_NAME should usually begin with a letter. The classical CV programming is emulated with numeric values for V_NAME, the address range is counted from 1 (as usual in decoder manuals). A user input can be directly forwarded to the node with this function. V_NAME = "0" is void.

Examples for MSG_VENDOR_:
MSG_VENDOR_GET 0x01 0x38 (=1 '8'): CV 8 (vendor ID at normal decoders) will be read: 1 is the length of the string, which consists only the ASCII-character for 8.
MSG_VENDOR_SET 8 'S'C'H'W'E'L'L'E' 3 '2'5'5': The message begins with the identification MSG_VENDOR_SET, followed by the length specification of 8 and finally the parameter name 'Schwelle'. Again followed by a length specification (3), then the parameter value (255). The principle is similar to the entries in an INI file.

It is recommended to use descriptive names for the parameters and their values, but limit oneself to about 32 bytes of total length. A hard limit is given by the packet size, with a maximal message length of 64 bytes there remain 55 bytes for the two strings V_NAME_STR and V_VALUE_STR.

4.3.2. Uplink: Messages for user config

4.4. Firmware-Updates

A module may change its unique ID after a firmware update but there are also modules available, which offer only firmware update function at the beginning. In this case, they log on normally but all class bits has been set to zero.

4.4.1. Procedure of firmware updates

For troubleshooting or retrofitting new features, it is desirable that nodes have the ability to update their software. Whether and how the software of a node can be updated is determined by a feature.

The sequence of FEATURE_FW_UPDATE_MODE = 1 is shown in the following example:

  1. The host sends a message to the desired node, that a firmware update is scheduled. (MSG_FW_UPDATE_OP, Parameter BIDIB_MSG_FW_UPDATE_OP_ENTER) For security reasons, this message contains the unique ID of the node. After this message no other commands are permitted, the node changes into a restricted mode where only firmware update commands are executed.
  2. The node sends a 'ready' message, which contains a indication that he is ready to receive the firmware.
  3. The host sends a message that indicates the type and the destination memory of the following firmware. e.g. contents of flash-memory.
  4. The node acknowledges receipt and indicates that he expect the data set.
  5. The host reads the Intel Hex file (provided by the manufacturer of the node), and sends them line by line to the node. The transfer takes place directly in ASCII format.
  6. The node acknowledges the receipt of each line to indicate that he is ready for the next data sets. The host is only allowed to send the next row after he got the acknowledge from the node.
  7. Lastly, the host sends a message that the last line has been transferred and any last fragments needs to be written into the memory.
  8. The node sends a 'ready' message and is again ready to receive a firmware package.

At the end of the firmware update, the host sends a command to reboot or exit. The node acknowledges this message and waits for 1s (the interface logs off the node within this time), then the node restart and will be logged in automatically. It is recommended to implement specific actions within the firmware (e.g. CRC check at startup), to check the complete and correct transfer of the firmware.

As the node is freshly logging on to the BiDiB system, it's state for SYS_ENABLE is off. Therefore it may be required to notify the node after FW update with a MSG_SYS_ENABLE.

4.4.2. Features for firmware updates
Listing of features for firmware-updates
NumberNameMeaning
254 FEATURE_FW_UPDATE_MODE 0: no firmware-update possible
1: firmware-update with Intel-Hex method possible. The maximum line length is 16 data-bytes (i.e. the intelhex-line starts with ':10' or smaller).

Target memory areas:

Depending on the implementation of the nodes, different memory areas like Flash, EEPROM etc. can exist. For each of these target memory areas there will be a single update file from the manufacturer.

For update-files a consistent naming scheme has been set out:

name_version.ddd.hex
PlaceholderSubstitution
name_version name of the firmware, this name should show the manufacturer and product in a recognizable way. Furthermore it should show the firmware version. All files for different target memories must use the same string for name_version.
ddd Target memory area, 3-digit, filled in with leading "0".
hex file extension, the fixed extension .hex will be used.
Example:
xyz_occupancydetector_v1_23f.000.hex
xyz_occupancydetector_v1_23f.001.hex

000 and 001 is the corresponding number of the destination memory area in this example. It is recommended to use 000 for the main program memory and 001 for the configuration memory (EEPROM).

4.4.3. Downlink: Messages for firmware updates

During a firmware update, the node will change into an restricted mode (=update-mode). Normal operation will be switch off during this update-mode (e.g. no track output, no detection, no interface function). In this state, it's not allowed so send other commands to the node.

Also here, a strict handshaking applies: Every message from the host must be confirmed by the node. New messages can be sent only when the confirmation of the previous message is present. This is due to occasional storage periods in which the node writes into the flash memory and, therefore, is not capable to execute normal program code.)

4.4.4. Uplink: Messages for firmware updates

4.5. Track-output devices

4.5.1. Track-output control

Track-output devices are nodes with the ability to generate a DCC-signal. This DCC signal is by default only known by the node itself and all directly connected devices. The node can be enabled through system messages in order to control the distribution of the DCC signal (via the corresponding line pair). BiDiB contains the ability to run different DCC systems in parallel. Possible applications for the above feature is e.g. a separate programming track, which can be operated independently of the main track or a separate DCC signal branch, which is used for switch accesories only.

A common problem on exhibition layouts are 'down' locos with contact problems. This locos are not able to receive commands and therefore they interrupt the operation. BiDiBus provides a fast information transfer via a separate channel which allows to receive a railcom acknowledgement from the loco. This information is received from the track-output unit and can be combined to one message if the corresponding loco is still in communication with the control station. If the control station detects a lost loco, it reports this information to the host.

During regular operation, the track-output device is addressed by the host. However, there might be the request that DCC generators can be addressed decentralized and also from the host. The already existing trade-off ('who controls the loco, who secures driveway'), becomes an additional conflict: which device receives an acknowledgement from the command and the successfull output to the track? In BiDiB, it is intended (in regular opration conditions) that local control devices (distributed handhelds and switch boards) sends their demands to the host. The host checks and filters occasional (i.e. no turnout operation in a reserved route) and issue the appropriate command to the track-output device. In regular operation, the track-output device acknowledges against the host.

Accident and test mode: Moreover, there might be situations in which the host is not able to provide desired commands, e.g. because the operating situation is not intended, the PC program has crashed or the PC is simply not connected. Direct local control is provided for this scenario (accident and test operation).

For this emergency operation, DCC generators are allowed to listen for loco control commands on local bus structures (e.g. BiDiBus) and execute these commands without acknowledge. This ability is controlled by a feature. If this feature is enabled, handheld commands (which are actually sent to the host) will be read from the track-output device in 'spy mode' and are being executed. With this solution, the trade-off (who controls) can be resolved. The host has the possibility to stop this 'spy mode' via the command MSG_CS_ALLOCATE and the handheld will be therefore 'locked out'. This handheld 'lock out' with the command MSG_CS_ALLOCATE is only valid for a limited time, therefore MSG_CS_ALLOCATE has to be repeated continuously. That guarantees a smooth transition between PC and handheld control, also driving without a PC is possible without further actions.

Watchdog: The track output is equipped with an optional connection monitoring for the event of an unexpected connection loss between host program and track output which result also in a lost of the locos controls. The host program must renew the ON-status at the command station in regular intervals via MSG_CS_SET_STATE (BIDIB_CS_STATE_GO). The feature FEATURE_GEN_WATCHDOG defines the interval until the status renewal must be made.

If the renewal doesn't take place within the time limit, the track ouput controller stopps all locos which are currently controlled by the host.

A host program must fetch the feature FEATURE_GEN_WATCHDOG in advance before controlling any locos and it must renew the ON-status accordingly.

General note: This section 'command station' is still in the testing phase. Certainly, there might be still a need for one or other for the control of loco's – e.g. address reallocation, set control format, manage loco names (who manages this – the output unit?), etc.

4.5.2. Features for track-output
Listing of features for the track signal class
NumberNameMeaning
100 FEATURE_GEN_SPYMODE Spymode
Here will be set if local control (monitoring of handheld messages) is allowed or not.
0: Monitoring not allowed.
1: Monitoring allowed in general, but might be disabled by MSG_CS_ALLOCATE.
101 FEATURE_GEN_WATCHDOG Host Monitoring
0: No monitoring (=no watchdog function).
1…100: host control program must repeat MSG_CS_SET_STATE(GO) permanently. The repetition must occur before FEATURE_GEN_WATCHDOG * 100ms is elapsed. default = 20, corresponding to 2s.
102 FEATURE_GEN_DRIVE_ACK Acknowledge for drive and programming commands – bit field:
Bit 0 additionally activates level 1 (track output)
103 FEATURE_GEN_SWITCH_ACK Acknowledge for switch commands – bit field:
Bit 0 additionally activates level 1 (track output)
106 FEATURE_GEN_POM_REPEAT Number of DCC PoM messages, which are generates for each PoM command to the command station
2: according to railcom specification (default).
3…8: larger number of DCC messages (for decoders, which are not fully spec conform).
107 FEATURE_GEN_DRIVE_BUS DCC-bus control (within BiDiBus)
0: Node receives DCC from BiDiBus
1: Node drives DCC at the BiDiBus
108 FEATURE_GEN_LOK_LOST_DETECT Track output detects and reports 'lost' locos
0: Lost locos will not be recognized or reported.
1: Lost locos will be recognized and reported.
109 FEATURE_GEN_NOTIFY_DRIVE_MANUAL The track output may have occasional local controls.
Bit:Meaning
0 0: Local operated locos will not be reported.
1: Local operated locos will be reported. (default)
1 0: Local operated accessories will not be reported.
1: Local operated accessories will be reported. (default)
2…7 reserved
110 FEATURE_GEN_START_STATE Initial state of generator after power up.
0: DCC is off.
1: DCC is on.
111 FEATURE_GEN_RCPLUS_AVAILABLE 1: The generator supports the RailcomPlus messages MSG_CS_RCPLUS and MSG_CS_RCPLUS_ACK
4.5.3. Downlink: Messages for track-output
4.5.4. Uplink: Messages for track-output

For drive, switch and programming instructions there is a multi-level handshake process:

  1. Acknowlegdement Level 0: The node has received the command.
  2. Acknowlegdement Level 1: The command is issued at the track.
  3. Acknowlegdement Level 2: The decoder has confirmed the command by ACK (via BiDi).

While level 0 is always compulsory, the higher levels can optionally be activated with features. Their acknowledgement messages are sent additionally.

Kodierung der Werte für ACK-Parameter
ValueLevelMeaning
0 0

Immediate acknowledgement: The command could not be accepted.

This happens when the corresponding buffers are full or the track output is switched off.

Also a 0 acknowledgement is sent when the output unit does not support the requested command (e.g. XPOM opcode, DRIVE format).

1 0

Immediate acknowledgement: The command has been accepted and will soon be issued to the track.

2 0

Immediate acknowledgement: The command has been accepted and will be issued to the track with a delay.

This acknowledgement is an indication to the host that currently a certain bottleneck exists in the rail output and a reduction of instructions is advised by the output unit.

The track-output device must still be able to accept at least one DRIVE command after an acknowledgement with 2.

3 1

Spontaneous acknowledgement: The command packet for this address was output on the track.

4 2

Spontaneous acknowledgement: The command packet had been output to the track, but was not confirmed by any decoder.

5 2

Spontaneous acknowledgement: The command packet had been output to the track and was confirmed by at least one decoder.

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.

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:

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:

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
4.6.4. Uplink: Messages for accessory functions
4.6.5. Controlling of peripheral functions

Nodes with switching functions could be used for light effects, animations (with movement) or similar. Another possibility is an operator panel, nodes could have key inputs. The class-ID flag 'Peripheral' is set for Nodes with switching functions.

Nodes with switching functionality have one or more in- and outputs, which are referred to as 'ports'. Each port can be configured, queried, and activated individually.

Peripherals can have significant differences, depending on the kind of outputs: There are pure switching outputs, light outputs with dimming or blinking functions, servo (with positioning), sound, analogue outputs etc. According to this there are execution commands which result in a change of the output, and configuration commands to set the properties.

Nodes can offer different functionalities on one port, for example they might be able to change the type of a port from output to input. Such reconfiguration shall take place during setup, not in operation mode. It shall not have any impact on the other properties of the port.

Furthermore a peripheral node may support macros, this optional feature allows for further commands and configuration abilities:

For the accessing of ports, there are two different addressing models since protocol version 0.6. Both use two bytes, but they differ in the alignment of the available ports in this address space.

type-based port model flat port model
Definition Each output and input port has a fixed type. Each port type has its own number range, which is counted from 0, the addresses are distributed over the types. The port function is therefore directly encoded in its address. All output and input ports share a common number range, the addresses are appointed linearly. Their type (function) is only defined by the configuration of the respective port. This scheme also allows to change the type of a port with a reconfiguration message when supported by the node.
For operations that act on multiple out- and inputs there are port types which occupy multiple consecutive addresses. Such ports are addressed using the first of these addresses, the other addresses are deactivated and throw the error PORT_INACTIVE on usage. The number of occupied addresses is called width of the type.
Activation The type-based port model is active on nodes whose FEATURE_CTRL_PORT_FLAT_MODEL and FEATURE_CTRL_PORT_FLAT_MODEL_EXTENDED do not exist or are set to 0.
The number of available ports per type is announced via the respective FEATURE_CTRL_*_COUNT.
The flat port model is active on nodes where FEATURE_CTRL_PORT_FLAT_MODEL and/or FEATURE_CTRL_PORT_FLAT_MODEL_EXTENDED is > 0. Their values also determine the total number of available ports as the sum PORT_FLAT_MODEL_EXTENDED*256+PORT_FLAT_MODEL.
If present, the FEATURE_CTRL_*_COUNTs denote the maximum count of ports configurable to the respective type.
This scheme is only available since protocol version 0.6.
PORT0 PTYPE port type. PORTADDRESS Number of ports on the node, counted from 0 in principle. It is encoded as a 16 bit little endian integer whose 4 MSB are reserved (0). Value range 0…4095
PORT1 PORTNUM Number of the port per type, counted from 0 in principle. Value range 0…127, bit 7 is reserved (0)
Encoding of port types
ValueNameMeaningWidthOperationsPossible Configurations
0 SWITCH Switching output (fka SPORT) 1 off/on none
1 LIGHT Light output (fka LPORT) 1 off/on/blinking/dimming Brightness, Speed of dimming
2 SERVO Output for servo 1 Positioning end position, rotational speed
3 SOUND sound output 1 play/stop volume, source
4 MOTOR Motor output 1 Rotation/Speed Regulation
5 ANALOGOUT general purpose 1 Voltage Maximum values
6 BACKLIGHT Light output 1 Brightness Speed of dimming, channel mapping
7 SWITCHPAIR 2 switch outputs with exclusive activation 2 first/second Pulse time
8…14 reserved
15 INPUT Contact input, e.g. push button or micro switch 1 open/closed none
16…254 reserved
255 reserved (internal use in nodes or host programs)
4.6.6. Features for peripherals

The properties of the nodes (for example the quantity of each specific kind of output) can be read with feature-requests:

Listing of features for the peripherals class
NumberNameMeaning
50 FEATURE_CTRL_INPUT_COUNT Quantity of inputs (e.g. for keys)
Range: 0…128.
51 FEATURE_CTRL_INPUT_NOTIFY Spontaneous messages of key inputs are allowed. The node provides changes of the key status to the host of its own.
Range: 0…1.
52 FEATURE_CTRL_SWITCH_COUNT Quantity of standard outputs
The number of switching outputs will be provided. Range: 0…128.
53 FEATURE_CTRL_LIGHT_COUNT Quantity of light outputs
Light outputs have extended properties like blinking, dimming, etc.
The number of light outputs will be provided. Range: 0…128.
54 FEATURE_CTRL_SERVO_COUNT Quantity of Servo outputs
The number of servo outputs will be provided. Range: 0…128.
55 FEATURE_CTRL_SOUND_COUNT Quantity of playable sounds
The number of sounds will be provided. Range: 0…128.
56 FEATURE_CTRL_MOTOR_COUNT Quantity of motor outputs
Motor outputs for accessories (e.g. carousel)
Range: 0…128.
57 FEATURE_CTRL_ANALOGOUT_COUNT Quantity of analogue outputs
The number of analogue outputs will be provided. Range: 0…128.
58 FEATURE_CTRL_STRETCH_DIMM Additional slow down for brightness transitions. Range 1…250
59 FEATURE_CTRL_BACKLIGHT_COUNT Quantity of light outputs (dimmable, for room lights)
This addresses environmental light, the brightness will be set with the operational command.
Range: 0…128.
70 FEATURE_CTRL_PORT_FLAT_MODEL Support of the flat port model, low byte of the number of addressable ports. Total count of the existing output and input ports.
Range: 0…255.
71 FEATURE_CTRL_PORT_FLAT_MODEL_EXTENDED Support of the flat port model, high byte of the number of addressable ports. Total count of the existing output and input ports.
Range: 0…16.
66 FEATURE_CTRL_PORT_QUERY_AVAILABLE Query of port states
0 = output states cannot be queried. (default)
1 = output states can be queried, the node will respond to MSG_LC_PORT_QUERY(_ALL).
67 FEATURE_SWITCH_CONFIG_AVAILABLE (deprecated, from protocol version 0.6 use MSG_LC_CONFIGX for port configuration)
Configuration of switch ports possible
0 = ports are simple, no configuration possible. (default)
1 = ports can be configured.
4.6.7. Downlink: Messages for peripheral / switching functions
4.6.8. Uplink: Messages for peripheral / switching functions.
4.6.9. Local macros

Accessories controllers can have the ability to provide macro functionality, this ability may vary significantly and is defined by a level. Whether macros are supported and which level of the macro capability is supported, can be checked by a feature query.

Similarly, the number and possible length of macro channels can also be checkes through a feature query.

Macros with level 1 functionality contain a linear list of switchpoints with the ability to perfom certain actions. A switching point is defined by the time interval to the previous switchpoint, by the port that is acted on and the command value. Each of those action corresponds to a MSG_LC_OUTPUT instruction. In addition, a macro have also general parameters, such as step speed on which the macro itself is running.

(Note: Through smart programming, the MSG_LC_OUTPUT command can be reduced to 2 bytes. This allows a large number of switching points in macros even with low memory.)

Macros with level 2 functionality also contain a linear list of switching points (corresponding to level 1), in addition, there are switching points with the ability to start and stop other macros and synchronize different macro runs and also allows input queries (e.g. limit switches or control buttons). This allows the implementation of small local sequences, often used for animated scenes on the model railroad.

A macro is therefore a sequence of actions on a node that is executed in a specific pattern. The grid for macro execution is defined by MACRO_TICK. MACRO_TICK is given by BIDIB_MACRO_PARA_SLOWDOWN (see below), multiplied by the base unit of 20ms.

Example: Adjust BIDIB_MACRO_PARA_SLOWDOWN to 50, the result is MACRO_TICK value 50 * 20ms = 1s. The macro will be incremented by one TICK at every second.

Macros are independent. Macros can be individually loaded, modified and started. A specific action or a specific output port may appear in several different macros. The number of simultaneously started macros is depending on the decoder.

Macro example:

This example shows a traffic light, a macro A should change the traffic light to the aspect 'STOP', another macro B should switch the traffic light to aspect 'GO'.

Macro A (traffic light switchs over from green to red)
DelayAction
0Turn on output for 'YELLOW'.
0Turn off output for 'GREEN'.
10Turn on output for 'RED'.
0Turn off output for 'YELLOW'.

Explanation: At the macro start, YELLOW will be switched on and GREEN will be switched off without any delay (i.e. the traffic light jumps to yellow). The next action is delayed for 10 ticks, after this waiting time the RED light will be switch on and the YELLOW light switch off without any further delay.

Macro B (traffic light swichts from red via red-yellow to green)
DelayAction
0Turn on output for 'YELLOW'.
10Turn off output for 'RED'.
0Turn off output for 'YELLOW'.
0Turn on output for 'GREEN'.

With this macro, YELLOW is switched on first, then RED and YELLOW will be switched off after a delay and GREEN will be switched on at the same time.

4.6.10. Features for local macros

The ability to perform and the level of support for macros can be ckecked with feature-requests:

Listing of features for macro support
NumberNameMeaning
60 FEATURE_CTRL_MAC_LEVEL Supported level for macros
0 = No macro support
1 = Macros of level 1 (simple list of actions)
2 = Macros of Level 2 (list of actions, with requests, start, stop, random)
61 FEATURE_CTRL_MAC_SAVE Persistent storage of macros
0 = No persistent storage available;
1…n = Number of storage locations for persistent storage usable
62 FEATURE_CTRL_MAC_COUNT Quantity of possible macros
0 = No macro support
1…n = Quantity of macros whith the given level
63 FEATURE_CTRL_MAC_SIZE Size of local macros
0 = no macro support;
1…n = Number of steps for each macro
64 FEATURE_CTRL_MAC_START_MAN Starting macros caused by local inputs
0 = It is not possible to start macros because of local inputs
1 = Macros can be started because of local inputs. The following assignment is valid: Input 0 is starting macro 0, input 1 is starting macro 1, etc.
65 FEATURE_CTRL_MAC_START_DCC Starting macros caused by DCC
0 = It is not possible to start macros because of DCC.
1 = Macros can be started by DCC commands. The selection of the DCC address will be done with the usual actions (e.g. via programming key or CV programming). accessory command 0 is starting macro 0, etc.
4.6.11. Downlink: Messages for local macros

There are the following commands to create and manage macros:

4.6.12. Uplink: Messages for local macros

4.7. Occupancy Detection

4.7.1. Detection and protection

Occupancy detection is used to report the location of vehicles. This detection is usually done by current measurement. In parallel, occupancy detectors may also be able to detect and evaluate bi-directional messages (railcom) of vehicles.

Detectors have set the bit 'occupancy' in their ClassID. Detectors are only used to show occupancy conditions but not to report other events like key press or an input from an layout through a control panel. This is provided by the class 'accessory'.

A lost occupancy detection can have a dramatic effect in computer operated layouts. If the occupancy indication of a stop-section is not received, the train will not be stopped in time and this can lead to an accident with material damage and operation interruption.

Therefore, the transmission in BiDiB is protected with CRC and the message sequence is also sequentially numbered in order to detect transmission errors. Moreover BiDiB provides further security methods for occupancy detectors:

Secure-ACK-Acknowledge method for occupancy and position notification
Secure-ACK is an advanced, automated acknowledgement process, which guarantees the correct reading of the feedback information even with existing transmission errors.
With activated Secure ACK handshaking, the host sends all received messages back to the feedback module. The feedback module compares the actual feedback condition with the confirmed state. If there is a difference, then the faulty feedback information will be retransmitted. If the retransmission of the host does not arrive within the specified time, the feedback module automatically attempts to send the message again.
Both the feedback module and the host program must clearly indicate whether the Secure-ACK handshaking is supported or not.
'Confidence'- Control
A detector can report the occupancy quality to the host, well the detector can report if the occupancy states are confident or not.
It may occur an situation (due to a short circuit on the track) where only 'frozen' occupancy detection exists or even the whole occupancy detection itself is impossible. In this case, the detector can report this condition to the host, and possibly prevent damage caused by faulty occupancy report to the host program.
'Alive'-Control
The interface controls the connection to it's detectors (Nodes) and the host sends a change notification when a sensor has been lost or a new one has been added. Moreover, the host can periodically send a PING message to a detector. This message will be answered within a predetermined time either in a standard message or with a PONG message (which is simply a blank message).

Another issue on bidi detection is the used address space. DCC knows two address spaces: short and long address, yet it is common practice in command stations to merge these into one. Whenever an address fits in the short format, it will be used.

BiDiB handles all DCC addresses as unique (as per RCN 211), the distinction between short and long doesn't exist in the protocol.

4.7.2. Features for occupancy detectors
Listing of features for the occupancy-detection class
NumberNameMeaning
0 FEATURE_BM_SIZE Number of occupancy feedback channels. The number of feedback bit's will be queried from the node. For detectors with an unknown number of inputs (e.g. S88-Bus Interface bridge), this variable can be writable. Value range: 0…128.
1 FEATURE_BM_ON 0: The node does not provide occupancy detection.
1: The node provides occupancy detection (spontaneously). This occurs automatically during a occupancy state change.
2FEATURE_BM_SECACK_AVAILABLE 0: No Secure-ACK.
1: The detector supports the Secure-ACK method for occupancy messages
3FEATURE_BM_SECACK_ON If this feature is unequal to 0, then Secure-ACK is enabled. This value specifies the retransmission interval in units of 10ms. A setting of 20 – corresponding to 200ms – is recommended.
4FEATURE_BM_CURMEAS_AVAILABLE 0: no current measurement values
1: The detector is able to provide current values (from a track section).
5FEATURE_BM_CURMEAS_INTERVAL If this feature is unequal to 0, current measurement is enabled.
This value specifies the sampling intervall of the current measurement in units of 10ms. A setting of 200 – corresponding to 2s – is recommended.
6FEATURE_BM_DC_MEAS_AVAILABLE 0: No substitution measurement available. (see also MSG_BM_CONFIDENCE)
1: Substitution measurement: The detector is able to provide occupancy states even when the track power is off
7FEATURE_BM_DC_MEAS_ON 1: The detector will provide occupancy states even when the track power is off
8FEATURE_BM_ADDR_DETECT_AVAILABLE 1: The detector is able to provide recognized loco address datas (if enabled in the decoder)
9FEATURE_BM_ADDR_DETECT_ON 1: The detector provides the address data
30 FEATURE_BM_TIMESTAMP_ON 0: The detector provides no timestamps
1: The detector provides occupancy reports with system timestamps
4.7.3. Downlink: Messages for occupancy detectors

Preliminary remark: The number of detectors of a node can be queried or modified with the MSG_FEATURE... commands. It is also possible to configure the number of detectors via the feature setting. This option is specifically designed to support interfaces to existing detection systems. For example: A S88 system has an unknown length and therefore the size must be defined. The number of detectors per node is limited to 128.

4.7.4. Uplink: Messages for occupancy detectors

Preliminary remark: Generally, messages occur spontaneously in the uplink (after enable by the interface). Certain types of messages can be switched on/off by feature setting.

3 different message types will be used for occupancy reporting:

4.7.5. Features for bidi detectors

Bidirectional messaging (railcom) of decoders can be detected and evaluated in different nodes like occupancy detectors or boosters. These may announce the following features:

Listing of features for bidi detectors
NumberNameMeaning
10FEATURE_BM_ADDR_AND_DIR 1: The detector provides direction data, i.e. the basic ability for that. *)
11FEATURE_BM_ISTSPEED_AVAILABLE 1: The detector is able to report speed values from the decoder
12FEATURE_BM_ISTSPEED_INTERVAL 0: The detector does not forward speed messages.
1…255: The detector forwards speed messages, the value specifies the speed message intervall in units of 10ms. A setting of 50 – corresponding to 500ms is recommended.
13FEATURE_BM_CV_AVAILABLE 1: The detector is able to read CV-responses from decoders.
14FEATURE_BM_CV_ON 0: The detector does not forward CV-responses from the decoder
1: The detector forwards CV-responses from the decoder
28FEATURE_BM_DYN_STATE_INTERVAL 0: The detector does not forward DYN-responses from the loco decoder
1…255: The detector forwards DYN-responses from the loco decoder; Interval in units of 100ms
29 FEATURE_BM_RCPLUS_AVAILABLE 0: The detector does not support RailcomPlus decoder responses
1: The detector forwards RailcomPlus decoder responses by occupancy section.
2: The detector forwards RailcomPlus decoder responses globally (MNUM=255)
31 FEATURE_BM_POSITION_ON 0: The detector does not forward position reports from the decoder
1: The detector forwards position reports from the decoder
32 FEATURE_BM_POSITION_SECACK 0: The detector does not repeat position reports from the decoder.
1…255: The Secure-Acknowledge method for position reports is enabled. This value specifies the retransmission interval in units of 10ms. A setting of 20 – corresponding to 200ms – is recommended.
4.7.6. Downlink: Messages for bidi detectors
4.7.7. Uplink: Messages for bidi detectors

Both occupancy detectors and others nodes like boosters may have the ability to evaluate bidirectional messaging (railcom) of vehicle and stationary decoders. Global detectors which don't distinguish between multiple detection sections set the MNUM field to 255.

For the reporting of decoder addresses, the following scheme is used:

Encoding of addresses
ValueMeaning
0 no address recognized.
1…10239 loco or accessory decoder address; To distinguish the two MSBs will be used.
Bit 15,14Bits 13…0
00Loco address, orientation with left side towards detector
10Loco address, orientation with right side towards detector
01Basic accessory address (11 bit switch address, "output pair" according to RCN 217)
11Extended accessory address (11 bit)
Hints about orientation:
The direction code in the MSB is only valid if the corresponding feature setting (FEATURE_BM_ADDR_AND_DIR) announces the availability of the direction transfer. If this feature is disabled, the direction bits shall be set to 0, and must not be evaluated.
The direction bit encodes the enrailment direction (independent of driving direction), it is set when the rail that is connected to the detector is on the right-hand side. Left/right refers to the locomotive, when looking ahead (driving forward, towards smokebox door or driver's cab 1). If the loco is wired with colors according to NEM 650, the wheel pickup connection to the left side is run in black, to the right side in red.
On which side of the track the detector is installed may vary from section to section, it is however recommended to consistently wire through DCC1 (positive polarity, labelled also as +, P or A) from booster to rail as a common pole and put (occupacy as well as bidi) detectors in the DCC2 (negative polarity, labelled also as -, N or B) line.

Nodes that support bidi detection use the following BiDiB messages to forward the respective feedback:

4.8. Booster

4.8.1. Using a booster

The intention of a booster is to amplify and to purify the track signal. Depending on the model railway several booster can be installed.

Booster are amplifying the track signal and providing this at a dedicated output. To achieve this a separate power supply is needed. If BiDiBus is used as the physical connection, the DCC signal (using RS485 voltage levels) will be provided too.

A Booster might be equipped with several diagnosis possibilities (measurement of output current and voltage, short cut identification), operations (switching on and off) and could have a global detector for railcom. In this case the booster is able to send corresponding messages (see class occupancy detections). It uses the value 255 for MNUM fields.

Controlling a booster:

In general it needs to be distinguished between the state of the track (GO, SOFTSTOP, STOP) and the state of the booster. This means that even when the track signal changes to STOP the booster will stay powered on. The booster will power down only when the track signal will be completely switched off. This is neccessary to avoid an accidentally driving of locomotives caused by analogue recognition mode of the decoders.

It can happen that two booster devices will be connected at the output ports (For example a vehicle creating a short while changing from one booster area to the next). This will be handled by BiDiB in the way that booster messages has to be sent normally as a broadcast message. Because of this the host will sent a change of the booster state (ON, OFF) only to the interface, which will sent this message as a broadcast to all connected boosters.

It is also possible to switch a specific booster on or off (using direct addressing). But independent how a booster state was changed, via broadcast or individually, it will announce his status change to the host. For example having a system with 10 booster and sending a MSG_BOOST_ON (broadcast) to the interface will result in ten MSG_BOOST_STAT messages.

Several track signal nodes and booster:

It is imaginable that not only the interface but also other nodes (for example a separate DCC controller) are containing a track signal creator. Those nodes have to be controlled by the Host with separate BOOST_ON resp. BOOST_OFF messages. If there is such a node with a substructur containing further booster modules, the broadcasts are valid only for this branch, the main branch is separated from this.

4.8.2. Features for boosters

If the booster also implements a global detector for decoder feedback, it also has to provide the corresponding features (see bidi detector section).

Listing of features for the booster class
NumberNameMeaning
15 FEATURE_BST_VOLT_ADJUSTABLE Adjustable output voltage
The output voltage of the booster can be configured if this feature is unequal to 0.
16 FEATURE_BST_VOLT This value contains the output voltage in Volt.
17 FEATURE_BST_CUTOUT_AVAIALABLE Cutout available. 1 = the booster is able to create the cutout.
18 FEATURE_BST_CUTOUT_ON Cutout switched on. 1 = the booster creates the cutout
19 FEATURE_BST_TURNOFF_TIME Normal switch off time
The time period which will be needed after a shortage until the output is switched off. If the booster is not able to handle this in a variable manner it needs to provide the used value. The unit is 1ms.
20 FEATURE_BST_INRUSH_TURNOFF_TIME Inrush switch off time (optional)
This is the time period in which a shortage (caused by inrush current) will be accepted after switching on the booster. The unit is 1ms.
21 FEATURE_BST_AMPERE_ADJUSTABLE Adjustable output current
The maximum output current of the booster can be configured if this feature is unequal to 0.
22 FEATURE_BST_AMPERE Maximum output current
The coding of this feature is the same as for the current measurent (see MSG_BST_CURRENT). It is possible that the desired value cannot be set to exactly this value. In this case the node will select the next lower value, if it is zero, the minimal possible current will be set. The configured value can be read.
Example values
0x52 = 820.5A (496mA)
0x71 = 1131A (992mA)
0x83 = 1311.5A (1472mA)
0x8B = 1392A (1984mA)
0x93 = 1472.5A (2496mA)
0x9B = 1553A (3008mA)
0xAA = 1704A (3968mA)
0xBA = 1865A (4992mA)
23 FEATURE_BST_CURMEAS_INTERVAL Interval for current measurement
The booster can provide current measurements if this feature is unequal to 0.
The unit is 10ms. A value of 200 is recommended which corresponds to 2s.
The node shall not be set to a shorter value than 100ms.
26 FEATURE_BST_INHIBIT_AUTOSTART Usually a booster starts automatically if DCC is available at the inputs. If this feature is set to 1 this startup will be suppressed and the booster has to be switched on explicitely by the message MSG_BOOST_ON. With that option it is possible to switch off dedicated areas of the model railway.
27 FEATURE_BST_INHIBIT_LOCAL_ONOFF If a booster consists of local keys for stop and go, this feature controls the usage of those keys. A key press event will not have a direct effect but will be sent to the host (as booster status) if this feature is set to 1. The host has to decide in this case about the further processing (Application: local emergency stop key)
4.8.3. Downlink: Messages to the boosters
4.8.4. Uplink: Messages from boosters

Booster are able to report current and CV results besides the status. CV will be reported with the message MSG_BM_CV (see occupancy detections). While the track supply is active, removable as permanent failures could occur at a booster. Possbile failures are over temperature, external supply, short circuit, ...

Still in discussion: Shall those be sent with a separate message or is it better to use the status?

© Wolfgang Kufer 28.10.2010, update 07.04.2017, (www.bidib.org)

('RailCom' is a registered trademark of Lenz GmbH, Giessen)