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.

General

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:

  • Automatic Plug & Play without programming in order to avoid address conflicts in modular and/or variable designs. Switchboard files can be easily copied.
  • Largely free arrangement of detectors and output devices, no displacement of addresses through new added blocks.
  • Easy scalability and extensibility due to support of hub-blocks.
  • Extremely fast data transmission, secured via CRC.
  • Monitoring of the entire bus transmission, including feedback components through Secure-ACK-Technology guarantees reliable, failure-free feedback signal transmission.
  • Full support of BiDiB feedback detectors with transmission of addresses, CV-messages and actual loco speed.
  • Notification of multiple locos in one section.
  • Mixed operation of normal and BiDi-ready feedback modules without problems: There is the possibility to install BiDi detectors at critical points (e.g. single track) and simple, normal detectors at all other sections.
  • Flexible, open protocol, future-proof.

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 workling 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:

  • Prior to any publication or intended implementation, the BiDiB working group must be informed. This information will be considered confidential.
  • The functions described in the following (unless indicated as optional) must be fully implemented and it must be clearly indicated which features and classes are supported (Example: support of BiDiB protocol version x.xx, occupancy detection including address and direction).
  • The used vendor IDs and product IDs must be published, together with a short description of the product, the supported classes and a link to the description of the product to (manual / data sheet) at bidib.org.
    PC programs may only implement a subset (i.e. the functions for firmware update may be omitted in layout control programs. However, if a certain function is implemented, this must done in general way and must be conform to the specification.
  • Any extension of the protocol must be agreed in advance by the BiDiB working group. Furthermore, the protocol and reference implementation must be disclosed. This limitation is primarily to ensure compatibility and clarity, not to block competitors or preventing any new features.
  • The encoding of data, which are transmitted over BiDiB must be disclosed and freely usable. Exceptions are only allowed in exceptional cases (i.e. firmware-update). This limitation is primarily to ensure compatibility and clarity, not to block competitors or preventing any new features.
  • Each implementation must be linked to the reference document (-> BiDiB.org). This reference must be made either in the product brochure / data sheet and in the manual (whatever the medium is).
  • Each publication elsewhere (even partly) requires a written permission and must be linked to the reference document -> BiDiB.org.
  • Devices using BiDiB must be marked with the logo. This applies specially to interface connectors, on which BiDiB is implemented. The logo may be used only with the explicit permission of the BiDiB working group. This limitation is primarily to ensure compatibility and clarity, not to block competitors or preventing any new features.
  • Equipment and/or software that implements BiDiB must be provided free of charge in case of an compatibility check request.
  • The licensee is obligated to carry out necessary tests regarding the interoperability of its components (both hardware and software) with the necessary care.
    In case of compatibility problems, the corresponding components must be improved and all necessary information and materials about the troubleshooting results and performed tests must be provided free of charge.
    The licensee agrees to solve the incompatibility within 2 months. This period may be extended to the next release in case the components is a pure software product. If the problem is not solved within the above period, the license for this product can be revoked.
    In most cases, the interaction between several components is the reason of incompatibility. The involved parties are obliged to investigate the problem together in the first step and clarify why these components does not work together.
    If an final agreement can't be reached, the issue shall be submitted to the BiDiB working group in order to decide for further action.
  • Conscious violations of the license conditions will result in a withdrawal of the license for all products of the licensee.

1.4. Revision status

This document describes revision 1.26 of BiDiB, updated aug 15, 2016.

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.262016-08-15 added: BIDIB_PCFG_IS_PAIRED, 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 UniqueID 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 implemention, 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, UniqueID: Manufacturer pre-programmed unique identifier in the detector, consisting a 16-bit manufacturer code and a 32-bit vendor-specific number (e.g. product serial number and index).
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 number (Unique-ID) programmed. 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.

Host internally, the nodes are also stored with their unique ID, beside the PC internal things like screen position and detector 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 assignment between the object at the user interface and the hardware is made via the unique ID and is therefore independent on the current address assignment.

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 be able to transport messages with a minimum 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:

  • MSG_LENGTH contains one byte and describes the message size in bytes. Here, the length is specified from the first byte of MSG_ADDR until the end of the DATA field. A message which contains only address 0, MSG_NUM and MSG_TYPE has therefore the length 3. Value range 0…127, MSB is reserved.
    Note: If future enlargement requires an increasing of the messages size, the reserved MSB can be used for this extension. For example – according to the following rule: If the first byte in the MSG_LENGTH field is less than 128, then the MSG_LENGTH field is only one byte. If the MSB is set in the first byte of the MSG_LENGTH field, the length will be calculated as follows: (First byte & 0x7F) * 128 + (second byte & 0x7F); The MSB may not be set in the 2nd byte.
  • MSG_ADDR describes the assigned destination or source address of this message. MSG_ADDR consists of one to four bytes, each byte defines the local address (NODE_ADDR) within a level.
    If the NODE_ADDR is 0, then the packet is addressed directly to the interface or the node. If the NODE_ADDR is unequal to 0, then the corresponding node behind the interface will be addressed. In this case, the interface forwards the packet accordingly, however the address will be reduced by one byte. For messages that come from a lower node, the interface add the local address from which this message was received.
  • MSG_NUM denotes a continuous message index, which is incremented by one with each message. The 0 is skipped (1,2,...,255,1,2,...). The receiver is able to check the MG_NUM and can determine whether if a message has been lost. In the event of lost messages, it is up to the receiver how he react. Restart can be made with the protocol commands, a retransmit of single messages is not provided.
    Usually, the receiver will request all occupancy states again and if Secure ACK is enabled, the repeat will be made automatically.
    When MSG_NUM is transmitted with value 0, then the transmitter skip the verification of the sequence, an appropriate error message is not allowed. The 0 resets also the sequence in the receiver, after 0 it will start with the continuous message index at 1.
    In broadcast messages, the MSG_NUM is completely ignored, it is preset to 0.
  • MSG_TYPE: A byte which encodes the message type and defines in principle what kind of message is available here.
    For faster decoding, the message types are summarized in groups:
    0x00Offset for downlink messages
    0x80Offset for uplink messages
    0x00Offset for system messages
    0x10Offset for feature and user messages
    0x20Offset for feedback detector messages
    0x30Offset for booster messages
    0x38Offset for accessory, switch and macro messages
    0x60Offset for DCC generator messages
    0x70Offset for local messages
    The detailed message coding can be found in the bidib_messages.h file, which is available for all licensees.
  • DATA: depending on MSG_TYPE, other parameters of the message will follow. There are all bytes 0…255 allowed for DATA.

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.

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:

  • Downstream: A node that receives a MESSAGE will check the destination address of this message: it contains its local NODE_ADDR in the current structure, possibly followed by further sub addresses. If the next byte is not 0 (belonging to MSG_ADDR_STACK), the node transmits the MESSAGE to the next subnode, but the first byte (his own NODE_ADDR) will be removed.
    If the next byte is equal to 0 and the MSG_ADDR_STACK is empty, the node itself is addressed.
    For broadcast messages, the MSG_ADDR_STACK is always empty.
  • Upstream: A node which receives a MESSAGE froma a sub-node, adds the local address (NODE_ADDR) of the subnode to the message and transmits them to its interface.

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

  • MSG_NODETAB_GETALL, MSG_NODETAB_GETNEXT: Associated sub-nodes from a node will be queried with this command.
    The node answer this query with a MSG_NODETAB_COUNT (indicates the size of the table), the individual table entries are requested with a MSG_NODETAB_GETNEXT, this will be answered with a single MSG_NODETAB message in each case. If the node has no sub-nodes at all, the length of the node table is 1 and the only included entry is the node itself.
    If a power-up event has been send but the bus arbitration in the sub-node structure is not yet complete, the query will be answered with MSG_NODETAB_COUNT = 0. The node table request should be answered only after the sub-node structure has become stable. Frequent messages about state changes at the start can be avoided.

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 internal programmed unique number, this number is called Unique-ID. The Unique-ID contains 7 bytes:

Structure of Unique-ID
1. Byte ClassID

This is a bit field, which indicates the class of this node. This bit field is a quick reference for the host which shows the available features on this specific node. If a node has implemented commands of a particular class, the appropriate class bit must be set too. A node can also belong to several classes at once.

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 ClassID is used for a rapid locating of partly functionalities, a host program must only query the features of the nodes which have set the corresponding class bit.

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 made 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 64 bytes.
  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.
  • Mandatory:
    • All system messages
    • All messages for node management (NEW, LOST, etc.)
    • Overload safety: An interface must not lose messages, appropriate buffers need to be provided.
  • Optional:
    • User configuration
    • Firmware update
Class Occupancy:
The node contains occupancy detectors.
  • Mandatory:
    • All system messages
    • FEATURE_BM_SIZE, FEATURE_BM_ON
    • Messages for Occupancy reporting (GET_RANGE, GET_CONFIDENCE, FREE, OCC, MULTIPLE, CONFIDENCE)
  • Optional:
    • SECACK, features and MIRROR-messages
    • Current measurement
    • Address detection, features and messages (ADDR_GET_RANGE, ADDRESS)
    • BiDi-detection, features and messages
    • User configuration
    • Firmware update
Class DCC-Generator:
The node provides DCC drive and switch commands.
  • Mandatory:
    • All system messages
    • FEATURE_GEN_WATCHDOG, FEATURE_GEN_POM_REPEAT, FEATURE_GEN_DRIVE_BUS
    • Messages for track signal output (MSG_CS_SET_STATE, MSG_CS_DRIVE, MSG_CS_ACCESSORY, MSG_CS_BIN_STATE, MSG_CS_POM)
  • Optional:
    • local operation, features and messages
    • Extended Acknowledgement, Evaluation of the ACK-line
    • RailcomPlus, feature and messages
    • User configuration
    • Firmware update
Class DCC-Programming:
The node provides DCC service mode commands.
  • Mandatory:
    • Class DCC-Generator
    • Programming mode (BIDIB_CS_STATE_PROG)
    • Programming messages (MSG_CS_PROG, MSG_CS_PROG_STATE)
Class Accessory Control:
The node provides control functions for track system accessories.
  • Mandatory:
    • All system messages
    • FEATURE_ACCESSORY_COUNT
    • Messages for accessory control (MSG_ACCESSORY_SET, MSG_ACCESSORY_GET)
  • Optional:
    • User configuration
    • Firmware update
Class Booster:
A booster amplifies the DCC signal for decoders (but does not generate it).
  • Mandatory:
    • All system messages
    • FEATURE_BST_INHIBIT_AUTOSTART
    • Messages for boosters
  • Optional:
    • Diagnostics, FEATURE_BST_CURMEAS_INTERVAL and MSG_BOOST_DIAGNOSTIC
    • BiDi-detection, features and messages
    • User configuration
    • Firmware update
Class Peripherals:
The node provides switching and animation functionality for peripheral equipment and lights.
  • Mandatory:
    • All system messages
    • FEATURE_CTRL_*_COUNT or FEATURE_CTRL_PORT_FLAT_MODEL
    • Messages for port commands and configuration
  • Optional:
    • FEATURE_CTRL_PORT_QUERY_AVAILABLE and messages for port queries
    • FEATURE_CTRL_INPUT_NOTIFY and spontaneous input events
    • FEATURE_CTRL_MAC_LEVEL and messages for macro controls
    • User configuration
    • Firmware update

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.