BiDiB, a universal control set for model railways

Content

• 1. General
  • 1.1. Objective target, special properties
  • 1.2. Origin and History
  • 1.3. Disclaimer, License
  • 1.4. Revision status
  • 1.5. Design principles
  • 1.6. Glossary
  • 1.7. Principles of node assignment, addressing
• 2. Physical implementation
• 3. Protocol description
  • 3.1. Basic message structure
  • 3.2. Routing
  • 3.3. Unique-ID
  • 3.4. Typical protocol startup
  • 3.5. Classes
  • 3.6. System time
• 4. Messages
  • 4.1. System messages
    • 4.1.1. Downlink: System messages
    • 4.1.2. Uplink: System messages
  • 4.2. Querying and setting of feature settings
    • 4.2.1. Downlink: Messages for querying and setting of feature settings
    • 4.2.2. Uplink: Messages for feature notifications
  • 4.3. Messages for user configuration
    • 4.3.1. Downlink: Messages for user configuration
    • 4.3.2. Uplink: Messages for user config
  • 4.4. Firmware-Updates
    • 4.4.1. Procedure of firmware updates
    • 4.4.2. Features for firmware updates
    • 4.4.3. Downlink: Messages for firmware updates
    • 4.4.4. Uplink: Messages for firmware updates
  • 4.5. Track-output devices
    • 4.5.1. Track-output control
    • 4.5.2. Features for track-output
    • 4.5.3. Downlink: Messages for track-output
    • 4.5.4. Uplink: Messages for track-output
  • 4.6. Accessory and peripheral classes
    • 4.6.1. Controlling of track system accessory functions
    • 4.6.2. Features for accessory functions
    • 4.6.3. Downlink: Messages for accessory functions
    • 4.6.4. Uplink: Messages for accessory functions
    • 4.6.5. Controlling of peripheral functions
    • 4.6.6. Features for peripherals
    • 4.6.7. Downlink: Messages for peripheral / switching functions
    • 4.6.8. Uplink: Messages for peripheral / switching functions.
    • 4.6.9. Local macros
    • 4.6.10. Features for local macros
    • 4.6.11. Downlink: Messages for local macros
    • 4.6.12. Uplink: Messages for local macros
  • 4.7. Occupancy Detection
    • 4.7.1. Detection and protection
    • 4.7.2. Features for occupancy detectors
    • 4.7.3. Downlink: Messages for occupancy detectors
    • 4.7.4. Uplink: Messages for occupancy detectors
    • 4.7.5. Features for bidi detectors
    • 4.7.6. Downlink: Messages for bidi detectors
    • 4.7.7. Uplink: Messages for bidi detectors
  • 4.8. Booster
    • 4.8.1. Using a booster
    • 4.8.2. Features for boosters
    • 4.8.3. Downlink: Messages to the boosters
    • 4.8.4. Uplink: Messages from boosters
  • 4.9. Distributed Control

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

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

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.

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:

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 x⁸ + x⁵ + x⁴ + 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 1 to 5 bytes, each byte defines the local address (NODE_ADDR) on a level. Thus there are up to four address bytes not equal to 0. The last byte of MSG_ADDR is always 0.
  If the MSG_ADDR equals 0 (so the MSG_ADDR_STACK is empty), the message is addressed directly to the interface or node. If the MSG_ADDR doesn't equal 0, the one node behind the interface will be addressed whose local address corresponds to the first NODE_ADDR. In this case, the interface forwards the message accordingly, at which the MSG_ADDR_STACK will be reduced by one byte. Conversely, for messages that are received from a lower node the interface prepends the local node address.
• 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 and in local messages (MSG_LOCAL_*), 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. The MSB denotes the normal direction.
  For faster decoding, the message types are summarized in groups:

  0x00	Offset for downlink messages
  0x80	Offset for uplink messages
  0x00	Offset for system messages
  0x10	Offset for feature and user messages
  0x20	Offset for feedback detector messages
  0x30	Offset for booster messages
  0x38	Offset for accessory, switch and macro messages
  0x60	Offset for DCC generator messages
  0x70	Offset for local messages (with special rules, see below)

  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.

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:

• 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 from 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 distinct identifer, this number is called Unique-ID. The Unique-ID contains 7 bytes:

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.

• 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)
  • SecureSwitch (MSG_ACCESSORY_STATE)
• Optional:
  • Surveillance and spontaneous reports (MSG_ACCESSORY_NOTIFY)
  • 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

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:

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 switched on or off by feature settings.

Local Messages

For local communication inside a specific bus level further messages may be used for link control, logon/logoff or time synchronisation.> Depending on the topology and used physical layer a different set of local messages may be required, governed by the respective transport layer specification.

The message type ranges 0x70 to 0x7F (downstream) and 0xF0 to 0xFF (upstream) are reserved for local messages. This allows the partitioning and separate handling of these messages on the link layer.

Local messages are categorically exempt from sequence numbering to not interfere with the index progression of the overarching connection between host and target node. They are transmitted with sequence number 0. On reception, it is not evaluated and the receive-counter is not modified.

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

• MSG_SYS_GET_MAGIC:

  The addressed BiDiB Node should transmit the system identifier. No other data will follow. This message shall be send prior any other request to the node.

  The node responds with its SYS_MAGIC, which also codes the general behaviour of the node.

• MSG_SYS_GET_P_VERSION:

  Query for the supported BiDiB protocol version. No other data will follow.

  The corresponding node responds with the version of the protocol supported by its software.

• MSG_SYS_ENABLE:

  No other data will follow. The node will be released, from now on, spontaneous messages are possible (e.g. change of occupancy states, new added hardware). The message is automatically passed to all other subnodes (inherited). No acknowledgement will follow.

  Hints:

  MSG_SYS_ENABLE controls only the release of spontaneous messages. Is it possible to communicate with the node and use all available functions even without SYS_ENABLE.

  If a new node has been added after a MSG_SYS_ENABLE, this note didn't have any information about the heredity. This node must be supplied with the current state of SYS_ENABLE after NODETAB_CHANGE_ACK.

  It is recommend to perform a complete query of the node table and features first, after the completion of this initialization, MSG_SYS_ENABLE can be send.

• MSG_SYS_DISABLE:

  The BiDiB system will be blocked, spontaneous messages are disabled at this point. Events which occur in the SYS_DISABLE state will not be cached, yet node states can be queried targeted. The message is automatically passed to all other subnodes (inherited) and should therefore be addressed only to node 0. No acknowledgement will follow.

• MSG_SYS_GET_UNIQUE_ID:

  Query for the Unique-ID and configuration fingerprint of a node. No other data will follow.

  The corresponding node responds with MSG_SYS_UNIQUE_ID.

  (The Unique-ID of a node is also stored in the node table of its interface).

• MSG_SYS_GET_SW_VERSION:

  Query of the node's installed software version(s). No other data will follow.

• MSG_SYS_PING:

  Followed by one byte.

  The corresponding node in the BiDiB system is initiated to send an empty message (MSG_SYS_PONG) back. This response must be received within 250 ms, otherwise the host has to consider the corresponding node as failed. The passed parameter (byte) is returned by MSG_SYS_PONG.

• MSG_LOCAL_PING:

  This message is used only on a local level to support the outage detection of the transport layer (e.g. serial link).

  No other data will follow.

  The corresponding node in the BiDiB system is initiated to send a message of type MSG_LOCAL_PONG back. This response must be received within 250 ms, otherwise the host has to consider the corresponding node as failed and transmit this failure with MSG_NODE_LOST to the host.

  (In case of BiDiBus, the token and the answer to that token takes over this function.)

• MSG_SYS_IDENTIFY:

  Followed by one byte: Identify is switched off, 1: Identify is switched on.

  The corresponding node in the BiDiB system is instructed to display a local identify indicator (e.g. a flashing LED). The node responds with a MSG_SYS_IDENTIFY_STATE message.

• MSG_SYS_GET_ERROR:

  The last occurred (but not any spontaneous) error message is read. The error memory is cleared through reading. If there is no error, an empty error message (i.e. error number 0) is returned.

• MSG_LOCAL_SYNC:

  This message is used only on a local level to support the system time synchronisation on the transport layer.

  Followed by two bytes (TIME_L, TIME_H) with the BiDiB system time, TIME indicates the point in time of the last frame marker prior to the message. The node sets its local clock to the received timestamp, possible data transit times must to be compensated by corresponding offsets. The message is not replied to.

  Example: A node receives MSG_LOCAL_SYNC 3. The duration from the frame signal to the processing of the message amounts to 2 ms. The internal clock will be set to 5.

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:

• MSG_SYS_RESET:

  The BiDiB system will be reset with regard to the host interface and the allocation of all nodes is carried out again. The previous assignment table is void.

  All message sequence numbers in the upstream will be set back to zero but the function of the node remains.

  If this message is addressed to a node, it shall log off (ie. shutdown for 1s, the interface will drop the node) an try to reconnect again. Internal states of the node may be lost.

  Attention: All undelivered messages in the uplink and downlink are lost by a MSG_SYS_RESET and the BiDiB system goes into the status SYS_DISABLE. After a reset, the data consistency must be checked and all information must be read again from the BiDiB system.

  Attention: A bus structure will be reset through a MSG_SYS_RESET, this means a 1 second break on the bus in case of BiDiBus (RS485) in order to allow all node to switch into disconnected state. Only after this time, the bus is back up and the node table is valid again. During this time, MSG_NODETAB_GETALL is answered with 0.

  Attention: The access to nodes and forwarding of messages is only possible if the node table becomes valid again, especially for broadcast messages, such as MSG_SYS_ENABLE or MSG_SYS_CLOCK.

• MSG_NODETAB_GETALL:

  With this command, the interface is caused to transfer the current assignment table of Unique-ID and local address. This transfer is a series of messages, it is started with a MSG_NODETAB_COUNT and will be followed by MSG_NODETAB, each of which are triggered by MSG_NODETAB_GETNEXT.

  While the transfer is in progress, new inquiries with MSG_NODETAB_GETALL lead to abortion and restart of the transfer.

  If the table does not yet exist, the interface responds with a MSG_NODETAB_COUNT = 0 message. In this case, the host must ask for it again after a few ms.

  If the table is existing, the interface responds with MSG_NODETAB_COUNT = 'table length'.

  Hint:

  This message applies only to nodes which have a registered hub in their Unique-ID. Nodes, which contain no substructure must answer this request anyway. In this case the node table has only one entry, local address is 0.

• MSG_NODETAB_GETNEXT:

  This command causes the interface to send the next line of the node table. No parameters follow.

  The node responds with a MSG_NODETAB message. In case there is no (more) line on hand, it responds with MSG_NODE_NA 255 instead. If there was a change in the node table since the last transmission of MSG_NODETAB_COUNT, the node responds with MSG_NODETAB_COUNT and starts over with sending MSG_NODETAB messages (with the incremented version number).

• MSG_GET_PKT_CAPACITY:

  With this command, it is possible to read in the maximum message length that a node can handle. This corresponds to the maximum length of a message sequence when it consists of only one message, and thereby the maximum number of bytes in a packet (between two frame markers).

  The node responds with a MSG_PKT_CAPACITY message. Until a node responds with a value above 64, the default restriction to 64 is in effect.

• MSG_NODE_CHANGED_ACK:

  Followed by one byte with the confirmed sequence number (version number of the node table) of NODE_NEW or NODE_LOST message. The host sends this message within 250ms to an interface when he received a notification for a lost or newly added node. If the interface gets the same version of node table that it has sent in the last change notification, this and all previous changes are considered as acknowledged.

• MSG_LOCAL_LOGON_ACK (formerly MSG_LOGON_ACK):

  This message is used only on a local level to manage the address assignment in the transport layer (e.g. BiDiBus).

  Followed by one byte with the local address (NODE_ADDR) and 7 bytes with the Unique-ID. Only if the node has verified that the received Unique-ID and the internal Unique-ID is identical, he may set his local address to received NODE_ADDR.

  This message will be sent as broadcast and with MNUM = 0. It is always interpreted, even if no login attempt was made. It is therefore possible to assign a local address to a node before the general logon.

• MSG_LOCAL_LOGON_REJECTED (formerly MSG_LOGON_REJECTED):

  This message is used only on a local level to manage the address assignment in the transport layer (e.g. BiDiBus).

  Followed by 7 bytes with the Unique-ID. The logon attempts of the addressed node are refused.

  Possible causes for the rejection of the LOGON can be:

  • The interface table is full, the max. number of participants is reached.
  • A double Unique-ID was recognized on the bus.

  Simultaneously with the MSG_LOCAL_LOGON_REJECTED, the interface sends an error message with BIDIB_ERR_BUS to the host.

System messages for layout management

(Hints for implementation: this messages are mandatory)

• MSG_SYS_CLOCK:

  This command transmits a model time for layout appliances. This clock typically runs accelerated compared to the real time. Followed by 4 bytes (TCODE₀, TCODE₁, TCODE₂, TCODE₃) with the time value. The coding of these bytes is the same as the coding of the corresponding DCC command.

  Structure of model time

  Field	Encoding	Meaning
  TCODE0	00mmmmmm	mmmmmm = Minute indication, value range 0…59.
  TCODE1	100HHHHH	HHHHH = Hour indication, value range 0…23.
  TCODE2	01000www	www = Weekday, 0=Monday, 1=Tuesday, ... 6=Sunday.
  TCODE3	11ffffff	ffffff = Clock acceleration factor, ffffff=0 means clock is stopped.

  Every field consists of a 2-bit type and 6-bit value. The host sends the complete time package every model-minute.

  Is the system is stopped, the clock factor 0 should be sent.

  On bus implementations, this message should be preferably send as broadcast.

4.1.2. Uplink: System messages

Common system messages

• MSG_SYS_MAGIC:

  Transmission of the system identifier: This variable is used for identification and transmission control. Followed by 2 data bytes, MAGIC_L, MAGIC_H which indicates the system identifier. The system identifier is transmitted with a transmission sequence index 0, this restarts the synchronisation of message sequence at host side.

  Encoding of system identifier

  MAGICL	MAGICH	Description
  0xFE	0xAF	BIDIB_SYS_MAGIC = Regular BiDiB Node
  0x0D	0xB0	BIDIB_BOOT_MAGIC = reduced bootloader
  …	…	reserved

  If a node responds to MSG_GET_SYS_MAGIC with BIDIB_BOOT_MAGIC (=0xB00D), this node has a very reduced functionality support only some commands (see table) and firmware update (bootloader). The node doesn't know any features and will not respond to feature queries. However, the feature FEATURE_FW_UPDATE_MODE (254) is equal 1 (although it isn't queriable). Also the fault detection and treatment is reduced in this node, but the check of the integrity of the data transmission (CRC) is still mandatory. The node hasn't set any ClassID bits.

  Messages of a Node with BIDIB_BOOT_MAGIC

  Downstream	Upstream
  MSG_SYS_GET_MAGIC	MSG_SYS_MAGIC
  MSG_SYS_GET_P_VERSION	MSG_SYS_P_VERSION
  MSG_SYS_GET_SW_VERSION	MSG_SYS_SW_VERSION
  MSG_SYS_IDENTIFY	MSG_SYS_IDENTIFY_STATE
  MSG_FW_UPDATE_OP	MSG_FW_UPDATE_STAT
  MSG_SYS_RESET
  MSG_LOCAL_LOGON_ACK	MSG_LOCAL_LOGON
  MSG_SYS_GET_UNIQUE_ID	MSG_SYS_UNIQUE_ID

  Notes:

  The intention of this reduced command set is the realisation of a tiny bootloader, which fits into the boot area of smaller microcontrollers (<4k).

  MSG_SYS_GET_UNIQUE_ID is only required for nodes, where the Unique-ID can not be queried from the node table of an interface (to which the node is connected). (Reason: a host program needs the unique to be able to select the corresponding firmware files). (ie a node, which is directly connected as is serial transport).

  If there is enough memory, the bootloader shall be implemented a full featured BiDiB node.

• MSG_SYS_PONG:

  Followed by one byte. This message is a response to the MSG_SYS_PING request, while the transferred byte in PING will be sent back.

• MSG_LOCAL_PONG:

  This message is used only on a local level to support the outage detection of the transport layer (e.g. serial link).

  Empty message, no other data will follow. This message is the response to MSG_LOCAL_PING.

• MSG_SYS_P_VERSION:

  Transmission of the supported protocol version. Followed by 2 data bytes which encode the BiDiB protocol version.

  MSG_SYS_P_VERSION parameters

  Parameter	Description
  P_VERSIONL	Minor protocol version number
  P_VERSIONH	Major protocol version number

• MSG_SYS_UNIQUE_ID:

  The node sends its unique identifier. Followed by 7 bytes with the Unique-ID and optionally 4 bytes with a configuration fingerprint.

  The fingerprint is a 32 bit checksum applied to all settings of the node. Those include:

  • Features (MSG_FEATURE)
  • User configuration (MSG_VENDOR and MSG_STRING)
  • Accessory configuration (MSG_ACCESSORY_PARA)
  • Port configuration (MSG_LC_CONFIGX)
  • Macro configuration (MSG_LC_MACRO and MSG_LC_MACRO_PARA)

  Explicitly exempt are all bus and operation states (even those that are persisted across power cycles), supported protocol versions and firmware revisions (assuming nothing else changes).

  The fingerprint is computed by the node using a good (uniformly distributed, chaotic, efficient) but not necessarily cryptographic hash function. When a configuration value changes, the fingerprint changes as well.

  Hints:

  Fingerprinting is optional for nodes. When it is not supported, only the Unique-ID is transmitted.

  The hash function needs to deliver the current value on every request, it is not sufficient to compute it only once during startup. For increasing the efficiency it is possible to choose an incremental algorithm which individually incorporates every change of a setting into the result.

  The fingerprint is destined for quickly loading node configurations at the start of a session. Once read or written, a host can locally store the configuration values for a node together with the corresponding fingerprint. When the node is met the next time, the values can be identified by Unique-ID and fingerprint in the cache, and may be loaded directly without needing to interrogate the node.

• MSG_SYS_SW_VERSION:

  Transmission of the software version: Followed by 1 to 16 triples (3 bytes each), vendor specific. Inside each triple the sub revision index is transmitted first, the main revision index is transferred last. Newer versions have a numerically larger version index.

  The first triple denotes the software version of the node, additional triples may code the version of subsystems (like coprocessors, hardware).

  Note: up to BiDiB specification revision 1.21 only one triple was defined as answer.

• MSG_SYS_IDENTIFY_STATE:

  Followed by 1 byte with the identify status: 0: off, 1: on.

  This message is sent when identification of the node was triggered, either by host command (MSG_SYS_IDENTIFY) or locally by the identification button.

  Recommendation: If the identify button is assigned to more than one function (e.g. if a decoder can also be programmed via DCC address-learning), a short press should execute identify, a long press should execute the DCC learning mode. This recommendation ensures the same behaviour across different modules.

• MSG_SYS_ERROR:

  Error message of a node. The errors take place either by a query (by MSG_SYS_GET_ERROR) or spontaneous (if the node is enabled). Followed by one byte with the error type and occasionally other parameters. Depending on the error, the processing of the data will not be possible any more.

  Encoding of error type

  Value	Name	Meaning
  0x00	BIDIB_ERR_NONE	The node has no errors (any more) in the fault memory.
  0x01	BIDIB_ERR_TXT	The node sends a text error message: followed by one byte with the length description, followed by ASCII-characters of the error message.
  0x02	BIDIB_ERR_CRC	The received message (or the message packet) had a CRC error, followed by one byte with the MSG_NUM of the faulty message. The node discards the received message packet. Note: this error message is only useful on point-to-point links. On implementations with broadcasted messages, the receiver should not response with an error message (only discard the received data).
  0x03	BIDIB_ERR_SIZE	The received message has too small length (too few parameters). Followed by one byte with the MSG_NUM. The node discards the received message.
  0x04	BIDIB_ERR_SEQUENCE	The received message sequence has an sequence error, messages have been lost. Followed by one byte with the expected MSG_NUM (if there had been no sequence error) and optionally one byte with the MSG_NUM of the current message, i.e. the first one that was correctly received again. However, the node processes the received messages and the current sequence number is taken over as the new starting point.
  0x05	BIDIB_ERR_PARAMETER	The received message has an parameter error. Followed by one byte with the MSG_NUM of the message which contains the error. The message is not processed.
  0x10	BIDIB_ERR_BUS	The sub-structure associated to this node has a bus error. Followed by one byte with the fault code: 0 Short circuit 1 Bus interrupted, missing termination resistors 2 too many termination resistors 3 Logon failure, inconsistencies in the node table. 4 Logon failure, too many nodes in this level. 5 Bus failure, Overrun occurred at the bus master (usually a result of a programming error). 6 Bus failure, Token at the bus master occurred.
  0x11	BIDIB_ERR_ADDRSTACK	A message from a sub-node contains 3 local addresses, i.e. the available address stack is fully utilized (because there are too many levels in line). The message can not be routed any more. Followed by 4 bytes: NODE ADDR_STACK NODE: the node, which has submitted the too long address. ADDR_STACK: The remaining bytes of this address. With this data, the host can identify the level in which the address violation occurred.
  0x12	BIDIB_ERR_IDDOUBLE	A node is trying to log on which already is logged on or which has the same ID as one that already is present in the node table. Optional followed by 7 bytes with the Unique-ID of the node.
  0x13	BIDIB_ERR_SUBCRC	A message from a subnode was not received because of an CRC error. Followed by 1 byte: NODE NODE: Local address of the currently addressed node.
  0x14	BIDIB_ERR_SUBTIME	A message from a subnode was not full received because of an timeout. Followed by 1 byte. NODE NODE: Local address of the currently addressed node.
  0x15	BIDIB_ERR_SUBPAKET	A package with a message from a subnode had a consistency error in the size specification. Followed by 1 byte with the NODE-address and optional further bytes with the contents of the data package. NODE: Local address of the currently addressed node.
  0x16	BIDIB_ERR_OVERRUN	An interface could no longer relay all transferred messages to its sub-structure, messages have been lost.
  0x20	BIDIB_ERR_HW	The node has detected an internal error. Followed by 1 byte with the error number (vendor specific)
  0x21	BIDIB_ERR_RESET_REQUIRED	The node requires a reset. Ie there was reconfiguration which gets valid after a reset.
  0x30	BIDIB_ERR_NO_SECACK_BY_HOST	The maximum number of occupancy message repetitions was reached without the host having mirrored the status.

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

• MSG_NODETAB_COUNT:

  This message is sent prior to the transmission of individual MSG_NODETAB, if the host has requested with MSG_NODETAB_GETALL. Followed by 1 byte with the node table length. This table is fetched with a corresponding number of MSG_NODETAB_GETNEXT queries.

• MSG_NODETAB:

  Followed by 9 bytes with an entry of the node mapping table:

  MSG_NODETAB parameters

  Parameter	Description
  NODETAB_VERSION	Current version of the table, will be incremented at each change, overflow: 255→1
  NODE_ADDR	Assigned local address of the node (value range 0…127) Address 0 represents the node itself.
  UNIQUE_ID[7]	The Unique-ID of the node, consisting of 7 bytes

  If a node has no subnodes (no class bit 'Hub' is set in the Unique-ID), the node table has only one entry length and contains the node itself.

  The transmission of the node table is done by one or more MSG_NODETAB messages. While transfer is in progress, no nodes should be added or removed from the table. If a change happens nonetheless, the interface must start over again with the transmission of a new MSG_NODETAB_COUNT.

• MSG_PKT_CAPACITY:

  With this message, a node reports the maximum message length that it can locally handle. This is generally restricted by the size of the receive buffer for packets of the respective transport layer (which is otherwise transparent towards the host). For packet based transmission of message sequences, the length corresponds to the maximum number of bytes for the packet content (as a sequence of only one message), e.g. 64 at BiDiBus.

  Followed by a length designation, consisting of 1 byte, value range 64…127. The minimum value is 64, smaller values are reserved and to be ignored. (MSB is reserved for length-extension)

• MSG_NODE_NA:

  Followed by a byte with the (local) number of the addressed node. The message is rejected from the interface and will be returned if the host attempts to contact a node, which is not (or no longer) in the list.

  This message will be (with node 255) also sent, if all nodes has been already transferred by MSG_NODETAB_GETNEXT.

• MSG_NODE_LOST:

  Followed by the current version number of the node table and the table entry of the lost node (see MSG_NODETAB), consisting the local address (1 byte) and the Unique-ID (7-bytes).

  An already registered node does not respond any more. If (for example) the lost node is an detector, the host can (and should) take appropriate action (partial or general emergency-stop, traffic control). The MSG_NODE_LOST must be confirmed by the host. If this message will not be confirmed within 250 ms, the interface repeat it at a maximum of 16 times.

• MSG_NODE_NEW:

  A new, not yet existing node is detected and added to the node list. Followed by the current version number of the node table, and the table entry of this new node (see MSG_NODETAB) consisting of local address (1 byte) and Unique-ID (7-bytes).

  The messages for MSG_NODE_LOST and MSG_NODE_NEW will be sent only after the first reading of the node table and only if the (spontaneous)-enable at the interface is activated. MSG_NODE_NEW must be confirmed to the host, as well as MSG_NODE_LOST. This is done with MSG_NODE_CHANGED_ACK or a complete query beginning with MSG_NODETAB_GETALL, otherwise up to 16 repeats take place.

  If multiple changes occur in succession, the version number is incremented each time and a message is generated, but only the last change will be repeated.

• MSG_STALL:

  Followed by a byte which identifies the status.

  0:

  The node operates normal

  1:

  A node sends this message if he detects that his output data buffer is going to be full and therefore the current downstream message can not be handled. Such a situation may occur if the host "deluge" the node with requests. STALL can also occur if e.g. a sublevel of an interface has a lower bandwidth: the interface node isn't able to forward all messages to its subnodes. In this case, the host shall not continue to send messages to subnodes this interface.

  A MSG_STALL=1 will be terminated from the node with a MSG_STALL=0.

  Hint:

  In BiDiB, it is desired and allowed that the host summarizes messages and transfers to the node. It should, however, not lead to an overloading of the node. For example, this occurs at a BiDiBus structure if the answer to an transmitted data package generates more then 48 bytes in total.

  This means, it is possible without any problems, to send a block of MSG_GET_SW_VERSION, MSG_GET_P_VERSION, MSG_FEATURE_GETALL, MSG_FEATURE_GETNEXT, MSG_FEATURE_GETNEXT, MSG_FEATURE_GETNEXT to read data from the node.

• MSG_LOCAL_LOGON (formerly MSG_LOGON):

  This message is used only on a local level to manage the address assignment in the transport layer (e.g. BiDiBus).

  Followed by 7 bytes with the Unique-ID. The node is trying to logon. This message is used at system start up in the process of assigning the local bus addresses.

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.

A complete list of all feature-ids can be found in bidib_messages.h.

4.2.1. Downlink: Messages for querying and setting of feature settings

• MSG_FEATURE_GETALL:

  This command is used to begin the query of all feature settings. Followed by an optional byte for requesting a streaming transmission. The node resets its internal counter for MSG_FEATURE_GETNEXT queries and responds with a MSG_FEATURE_COUNT, which specifies the number of existing features. If this number is 0, the node has no features.

  If the optional parameter is set to value 1, this signals to the node that it should begin sending the feature messages without waiting for MSG_FEATURE_GETNEXT queries. The optional parameter with the value 0 signals that the host does not want the feature values ​​to be streamed. The values ​​2..255 are reserved. Supporting this functionality is optional, but recommended for nodes from declared protocol version 0.8.

• MSG_FEATURE_GETNEXT:

  With this message, a feature value is queried. No byte will follow. The answer is either a MSG_FEATURE (the node itself selects and sends the respective next FEATURE) or a MSG_FEATURE_NA message (with feature_num = 255), if all features have been already submitted.

• MSG_FEATURE_GET:

  Query for a single feature. Followed by a byte with the feature number, which was queried.

  The node responds with MSG_FEATURE.

• MSG_FEATURE_SET:

  Setting of a single feature. Followed by 2 bytes: feature number, value.

  The node responds with a MSG_FEATURE as confirmation. If a value has been sent that is not adjustable, the actual value which was set is returned.

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:

• MSG_FEATURE:

  Followed by 1 byte with the feature number and 1 byte with the value. Logical features are enabled at 1 and disabled at 0.

• MSG_FEATURE_NA:

  This message will be sent if a feature was requested that is not available on this node. Followed by 1 byte with the (not implemented) feature number.

  This message is also sent (with feature number 255) in response to MSG_FEATURE_GETNEXT, if all features have already been transmitted.

• MSG_FEATURE_COUNT:

  This message is sent prior to the transmission if the host has made a request with MSG_FEATURE_GETALL. Followed by 1 byte with the number of the existing feature messages and optionally 1 byte for announcing the transmission mode.

  The mode byte is set to the value 1 when the host requested streaming and the node supports it. The node begins sending the MSG_FEATURE on its own and is responsible for flow control, adjusting to the available transport capacity itself. The node must remain fully operable and be able to receive and respond to other messages during the transmission. The count allows the host to determine when all feature messages have arrived.

  Otherwise, the feature values are polled individually using a sequence of MSG_FEATURE_GETNEXT. The count allows the host to make the suitable number of requests.

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, content and meaning lie within 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

• MSG_VENDOR_ENABLE:

  Followed by 7 bytes of the previously read UNIQUE-ID. The node responds with a MSG_VENDOR_ACK.

• MSG_VENDOR_DISABLE:

  No other data will follow; the node is disabled. The node responds with a MSG_VENDOR_ACK.

• MSG_VENDOR_SET:

  Followed by the data below, which are structured as follows:

  VENDOR_DATA ::= V_NAME  V_VALUE
  V_NAME ::= LENGTH  V_NAME_STR
  V_NAME_STR ::= V_NAME_CHAR | V_NAME_CHAR  V_NAME_STR
  V_VALUE ::= LENGTH   V_VALUE_STR
  V_VALUE_STR ::= ε | V_VALUE_CHAR  V_VALUE_STR

  The node stores the parameter value in its configuration, in case the key (V_NAME) is known. It responds with a MSG_VENDOR message, this includes the same V_NAME and the saved value. When a problem appears during processing, the saved value may deviate from the value transmitted in MSG_VENDOR_SET, then usually the previously stored value is kept.

• MSG_VENDOR_GET:

  Followed by the data below, which are structured as follows:

  V_NAME ::= LENGTH  V_NAME_STR
  V_NAME_STR ::= V_NAME_CHAR | V_NAME_CHAR  V_NAME_STR

  The node responds with a MSG_VENDOR message, which contains the same V_NAME and the stored value of this parameter. When the key (V_NAME) is not known to the node, it responds with an empty value (V_VALUE = 0x00 "").

The node configuration is treated like an associative array (key-value pairs). V_NAME and V_VALUE are ASCII sequences, so that a user input can be directly forwarded to the node. When the sequence consists of digits 0…9, it represents a numeric value. The keys (V_NAME) should generally begin with a letter. 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.

The classical CV programming is emulated with numeric values for V_NAME and V_VALUE, the address range begins at 1 (as usual in decoder manuals). V_NAME = 0x01 "0" is invalid.

• MSG_STRING_SET:

  This message type is used to send a string value to a node. This command is followed by data denoting the addressed namespace, the addressed identifier (variable to be set, channel), the string size and the string itself.

  This function is only available in a node if announced by the respective feature.

  MSG_STRING_SET parameters

  Parameter	Description
  NAME_SPACE	denotes the addressed namespace inside the node, range 0…255 0: String variables of the node in general 1: Debug-Streams 2: text output for accessories, selectable via aspect where BIDIB_ACCESSORY_PARA_USES_STRINGS = 1 3…255: reserved
  STRING_ID	denotes the addressed string inside the given namespace. Namespace 0: STRING_ID = 0: product name, readonly (stored by manufacturer). STRING_ID = 1: node name, read/write, given by user (aka "username"). STRING_ID = 2…255: reserved Namespace 1 (for downstream, MSG_STRING_SET): STRING_ID = 0: Standard input of a text terminal. STRING_ID = 1…255: reserved Namespace 1 (for upstream, MSG_STRING): STRING_ID = 0: Standard output, as reaction to stdin inputs. STRING_ID = 1: Standard error, as reaction stdin inputs. Errors occuring independent from the terminal are reported normally via MSG_SYS_ERROR. STRING ID = 2: Log messages on level Warning STRING ID = 3: Log messages on level Info STRING ID = 4: Log messages on level Debug STRING ID = 5: Log messages on level Trace STRING_ID = 6…255: reserved Namespace 2: STRING_ID = 0: Default displayed value, e.g. empty string STRING_ID = 1…N: additional texts, which can be selected as accessory aspects for output (see BIDIB_ACCESSORY_PARA_USES_STRINGS) STRING_ID = 255: comma-separated list, starting with number of available entries (max. 128) and maximum length per string, each coded as a decimal string; additional parameters may follow. This string typically is not writable.
  SIZE	length of the string. 0: String doesn't exist. 1…127: number of chars.
  CHARS	String, coded according to ISO 8859-1 (simple 8-bit coding). 0x00 is not allowed as string character.

  The node responds (for namespace 0 and 2) with MSG_STRING and the newly stored value. If the written string is longer than allowed, it is truncated by the node or the message is rejected with BIDIB_ERR_PARAMETER. If the response for a string results in the size 0, then the string doesn't exist.

  Hints for namespace 0:

  The FEATURE_STRING_SIZE defines the maximum length of strings inside the node. Out of consideration for displaying in host programs, the valid range for the maximum is 8 to 24. If FEATURE_STRING_SIZE doesn't exist (or is 0), the node can't handle strings.

  The node responds with MSG_STRING and the newly stored value. If a string message is answered with size = 0, this string does not exist on this node.

  User definable strings (i.e. node name) should be filled with ' ' (= blank) and should have a size of 1. This allows host programs to easily distinguish between 'factory state' and 'already configured by user'.

  The STRING 1 is a user-configurable nickname for the node, i.e. Station-Sigs-left

  Hints for namespace 1:

  The FEATURE_STRING_DEBUG determines how the namespace 1 is used. When it has the value 1, the node can provide a simple text terminal and use MSG_STRING messages for debug outputs on various channels. When the features doesn't exist or has the value 0, debug output is disabled.

  Each channel represents a text stream of utf8 bytes, the transmitted characters from each messages are concatenated. Example: A sequence of MSG_STRING 1 0 3 "abc", MSG_STRING 1 0 3 "def" is interpreted the same as a single MSG_STRING 1 0 6 "abcdef".
  The newline character \n is used as delimiter. That way, also longer inputs or outputs can be transmitted, and multiple channels can be displayed line by line. A sequence error in the transmission should be handled like a newline.

  The sender shall utilise the maximal sensible message length to minimise overhead. No response to MSG_STRING_SET or MSG_STRING_GET is expected, though there may be nodes that respond with an empty string. The outputs via MSG_STRING are treated as spontaneous messages. The node is responsible for buffering, a flood of log messages shall not block other upstream messages. The limited available bandwidth shall be used responsibly.

  The command syntax on the terminal is arbitrary, any inputs may be ignored by the node. The selection of messages to log can be hardcoded (e.g. for debugging during the development process) or happen dynamically through the input.

  The (firmware) update protocol serves for the transmission of binary data.

  Hints for namespace 2:

  Bit 2 of FEATURE_STRING_NAMESPACES_AVAILABLE determines whether namespace 2 is available and, in particular, whether its STRING_ID 255 is available.

  To enable setting the text dynamically per accessory via MSG_STRING_SET, there should be at least as many text entries as accessories, so that one can map each accessory to a fixed index and assign the respective aspect.

  Storage is volatile in RAM, though the initial values available at node startup may be configurable.

• MSG_STRING_GET:

  Query of a string variable inside a node. Two bytes are following, denoting addressed namespace and string identifier. This function is only available in nodes if announced via the respective feature (FEATURE_STRING_SIZE, FEATURE_STRING_NAMESPACES_AVAILABLE).

  The node responds with a MSG_STRING that contains the queried string. If a string doesn't exist, the returned SIZE is 0.

4.3.2. Uplink: Messages for user config

• MSG_VENDOR:

  This message type is used for the answer to a userconfig. Followed by the data below, which are structured as follows:

  VENDOR_DATA ::= V_NAME  V_VALUE
  V_NAME ::= LENGTH  V_NAME_STR
  V_NAME_STR ::= V_NAME_CHAR | V_NAME_CHAR  V_NAME_STR
  V_VALUE ::= LENGTH  V_VALUE_STR
  V_VALUE_STR ::= ε | V_VALUE_CHAR  V_VALUE_STR

• MSG_VENDOR_ACK:

  Followed by a date: 0: No user config-mode, 1: Confirmation that the node has changed into userconfig mode.

• MSG_STRING:

  This message type is used as the answer to MSG_STRING_SET or MSG_STRING_GET. The message may also be sent spontaneously for namespace 1 once the node is enabled.

  Followed by data denoting the used namespace, the string identifier, the string size and the string itself. Order and format of the parameters corresponds to MSG_STRING_SET, for details see there.

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

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:

xyz_occupancydetector_v1_23f.000.hex
xyz_occupancydetector_v1_23f.001.hex

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

• MSG_FW_UPDATE_OP:

  It is followed by another byte which indicates the desired operation. Depending on this byte, further paramters may follow.

  The node responds with a MSG_FW_UPDATE_STAT.

  Encoding of firmware update operation type

  Value	Name	Meaning
  0x00	BIDIB_MSG_FW_UPDATE_OP_ENTER	Node should switch to update mode. 7 byte will follow with the Unique-ID of the node. Only if the Unique ID matches with the node, the node will switch into update mode. The node responds with MSG_FW_UPDATE_STAT(BIDIB_MSG_FW_UPDATE_STAT_READY), if he succesfully changed into his boot-loader, or with MSG_FW_UPDATE_STAT(BIDIB_MSG_FW_UPDATE_STAT_EXIT), if he could not go into the boot-loader.
  0x01	BIDIB_MSG_FW_UPDATE_OP_EXIT	Node shall exit the update mode.
  0x02	BIDIB_MSG_FW_UPDATE_OP_SETDEST	Select target memory. With this command, the target area is defined, in which the following data should be stored. It is followed by a byte with the number of the target range. 0: Flash (Application) 1: EEPROM
  0x03	BIDIB_MSG_FW_UPDATE_OP_DATA	Data: A data set will be send for the currently selected target memory. The data will be transmitted as a line of Intel Hex file. 'White'-Characters (0x20, 0x09, 0x0D and 0x0a) will not be transmitted.
  0x04	BIDIB_MSG_FW_UPDATE_OP_DONE	No more data available for the currently selected target memory. Node shall perform the update of the target memory.

4.4.4. Uplink: Messages for firmware updates

• MSG_FW_UPDATE_STAT:

  After a MSG_FW_UPDATE_OP command, a status message will always be send. Followed by 2 Bytes:

  MSG_FW_UPDATE_STAT parameters

  Parameter	Description
  STATUS	Process state Encoding of firmware update operation status Value Name Meaning 0x00 BIDIB_MSG_FW_UPDATE_STAT_READY Node is in update-mode, ready. 0x01 BIDIB_MSG_FW_UPDATE_STAT_EXIT Node is leaving the update-mode. The node confirms this messages and logs out of its superior structure (e.g. through waiting long enough on the. BiDiBus). Afterwards, the node execute a reset and will be registered again. 0x02 BIDIB_MSG_FW_UPDATE_STAT_DATA Node is awaiting (more) data. 0x255 BIDIB_MSG_FW_UPDATE_STAT_ERROR Node has detected an error and cancelled the current operation. It remains in the previous state.
  TIMEOUT or ERROR	After a successfull execution, this byte indicates the minimum time that the host needs to be wait until the next packet can be sent: Value Meaning 0 The next message to the node can be sent immediately. 1…255 The next message to the node shall be send after a pause of 'timeout'. 'timeout' is specified in units of 10ms. In case of an error (STAT_ERROR) this byte encodes the cause: Value Name Meaning 1 BIDIB_FW_UPDATE_ERROR_NO_DEST Target memory area not available. 2 BIDIB_FW_UPDATE_ERROR_RECORD Eror at record (e.g. invalid characters). 3 BIDIB_FW_UPDATE_ERROR_ADDR Record ouside of memory. 4 BIDIB_FW_UPDATE_ERROR_CHECKSUM Checksum error at hex-record. 5 BIDIB_FW_UPDATE_ERROR_SIZE Record too large;. 6 BIDIB_FW_UPDATE_ERROR_APPCRC CRC error at application, firmware not started.

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

Inquiry: When a control or monitoring host program meets a running track signal generator and doesn't reset it, it will want to know about the active vehicles. The MSG_CS_QUERY command and the accompanying MSG_CS_DRIVE_STATE answer allow such a query of addresses, formats and states.

4.5.2. Features for track-output

4.5.3. Downlink: Messages for track-output

• MSG_CS_ALLOCATE:

  Followed by a byte with content 0. (= local bus address of the host)

  The track-output node does not receive commands from any other local addresses. This lock is valid for 2 seconds and then expires by itself.

• MSG_CS_SET_STATE:

  With this command, the state of the track output is set or queried. Followed by one byte which encodes the new state. The node responds with a MSG_CS_STATE.

  Before first turn on, the speed settings of all locos should be checked resp. the loco stack should be cleared. This avoid unintentional driving of loco with speed settings from a previous session.

  Encoding of states of track-output devices

  Value	Name	Meaning
  0x0	BIDIB_CS_STATE_OFF	Track output will be switched off. As a consequence, also all connected boosters will be turn off.
  0x1	BIDIB_CS_STATE_STOP	All locos will be stopped by an emergency stop, turnouts may still be operated. If stop is not supported by the control station, then OFF will be executed.
  0x2	BIDIB_CS_STATE_SOFTSTOP	All locos will be stopped with speed step 0 (with their own delay), turnouts may still be operated. If soft-stop is not supported by the control station, then STOP will be executed. The track-output device execute the soft-stop and changes over to STOP mode afterwards.
  0x3	BIDIB_CS_STATE_GO	Resumption of operation, locos and turnouts can be operated. If the watchdog-feature is enabled, this command must be repeated in the given interval by host program.
  0x4	BIDIB_CS_STATE_GO_IGN_WD	Resumption of operation, locos and turnouts can be operated. A watchdog event will be ignored.
  0x8	BIDIB_CS_STATE_PROG	Programming mode; the control station has switched over to programming mode and is ready to execute programming instructions (on the programming track). Normal operation is not active.
  0x9	BIDIB_CS_STATE_PROGBUSY	Programming mode; This message indicates that there is currently a programming operation is active at the programming track. (only on request).
  0xD	BIDIB_CS_STATE_BUSY	The track output is not able to receive new commands, e.g. because corresponding output FIFOs are full. (Message only on request)
  0xFF	BIDIB_CS_STATE_QUERY	The state is queried. (only for MSG_CS_SET_STATE).

• MSG_CS_DRIVE:

  Motion commands will be issued with this command. Following by further parammeters, which contains format and output functions. If an loco has no higher functions, the appropriate groups of the function commands should be marked as inactive. This conserves the limited bandwidth at the track.

  MSG_CS_DRIVE commands will be acknowledged by one or more MSG_CS_DRIVE_ACK messages. The various acknowledgement levels can be activated in the output unit via FEATURE_GEN_DRIVE_ACK. If multiple commands for the same DCC address are issued, the output device is allowed to combine them in case of low bandwidth. In this case, intermediate acknowledgements can be omitted.

  Motion commands will be passed always with the step number of 127 + direction bits. Only the track-output unit converts this motion command to the appropriate speed-step on the track depending from the selected format.

  MSG_CS_DRIVE parameters

  Parameter	Description
  ADDRL	Address, lower 8 Bits.
  ADDRH	Address, upper 6 Bits. The complete address is given by ADDRH*256+ADDRL. The address designates the real (DCC) address and is counted from 0. Address 0 is not assigned to a specific loco and has a special role. (3) (4)
  DATA0	Bitfield Bit Meaning 3…0 Format (5): 0000: DCC14 (14 speed steps) 0001: DCC SDF (126 speed steps) 0010: DCC28 (28 speed steps) 0011: DCC128 (126 speed steps) 0100: MM14 (14 speed steps) 0101: MM27a (27 speed steps with alternating command with 14 steps ) 0110: MM27b (28 speed steps by using the light bit) 0111: M4/MFX (126 speed steps) 1000…1111: reserved 7…4 reserved
  DATA1	Bitfield output active For formats DCC14, DCC28, DCC128 Bit Meaning 0 0: Do not output speed 1: Do output speed 1 0: Do not output F1…F4 1: Do output F1…F4 2 0: Do not output F5…F8 1: Do output F5…F8 3 0: Do not output F9…F12 1: Do output F9…F12 4 0: Do not output F13…F20 1: Do output F13…F20 5 0: Do not output F21…F28 1: Do output F21…F28 7…6 reserved These bits indicating the valid data fields in subsequent bytes. Only those data fields whose bits are set will be taken over by the output device. If all bits are set to 0, then the loco will be removed from the repeat-memory at the output device (2), this is acknowledged with ACK=1.
  DATA2	Speed, consisting of direction (MSB) and velocity (7 LSBs) (1)
  DATA3	FL, F4 – F1; 3 MSB is reserved. The bit order of the function bits is: 3*reserved, FL (Light), F4, F3, F2, F1
  DATA4	F12 – F5
  DATA5	F20 – F13
  DATA6	F28 – F21

  (1)

  Speed is coded similar to the DCC 128 speed command, regardless of the loco format.

  • MSB is coding the travel direction: 1 = Forward, 0 = Reverse
  • The LSB's (Bit 6…0) are coding the speed: 0 = Stop, 1 = Emergeny stop

  Values from 2…127 are describing the speed step. Only the track-output unit converts the speed step into the respective format. The following conversion shall be applied:

  • DCC128: speed_step (1…126) = speed - 2 + 1 = (speed-1)
  • DCC28: speed_step (1…28) = integer((speed - 2) * 2 / 9) + 1 = ((speed-1) * 2 + 7) / 9
  • DCC14: speed_step (1…14) = integer((speed - 2) / 9) + 1 = ((speed-1) + 8) / 9

  See also: Notes on the speed encoding.

  (2)

  An unused loco should be unregistered at the output unit in order to save limited bandwidth on the track that would be used up by unnecessary refresh-cycles.

  (3)

  If loco 0 is unsubscribed from the output unit, then all locos are removed from the loco stack. (init)

  (4)

  In DCC there are two addressing schemes: short and long address. Theoretically these are two completely disjoined address spaces. It is however customary in control units to merge them into a single address space. In BiDiB, all loco addresses are generally represented in one 16 bit address space as well – independent from format or addressing.
  In accordance with RCN 211, all DCC decoder with addresses up to and including 127 are approached by short address, from 128 onwards by long address. The DCC address space is nominally restricted to 1 … 10239. The output unit won't check for that, when using addresses greater than this duplicate addresses may occur on the track.
  Tip: By ORing the address with 0xC000 it is possible to force long addressing. Still, the address must not be used as a short address at the same time (feedback does not distinguish them).

  (5)

  When a format (track protocol) is not supported by an output unit, it sends a MSG_CS_DRIVE_ACK with ACK=0.

• MSG_CS_ACCESSORY:

  Accessory items will be controlled with this command. Followed by 4 bytes: ADDR_L, ADDR_H, DATA, TIME

  The accessory decoder with address [ADDR_H * 256 + ADDR_L] is driven by the term in DATA. DATA is a bit structure, constisting of CONFIG (Bit 7,6) ACTIVATE (Bit 5) and ASPECT (Bit 4 – Bit 0).

  MSG_CS_ACCESSORY parameters

  Parameter	Description
  ADDRL	Address, lower 8 bits.
  ADDRH	Address, upper 3 bits. The complete address is given by ADDRH*256+ADDRL. The address designates the real (DCC) address and is counted from 0.
  DATA	Bitfield Bit Meaning 7 Extended / normal Accessory: 0=normal, 1=extended 6 Timing control: 0 = conventional control via coil-on/coil-off, 1 = Output unit does the timing; see note below 5 Activate: 0=coil-off / 1=coil-on If ACTIVATE is set, the track output generates the appropriate ON-command for the coil output. If ACTIVATE is not set, the track output generates the OFF-command. 4…0 ASPECT Accessory decoder with 2 aspects will be controlled with (ASPECT 0 = red) and (ASPECT 1 = green).
  TIME	Switch time, given like the specification of railcom. Bit Meaning 7 Base unit: 0: 100ms (total range 0…12.7s) 1: 1s (total range 0…127s) 6…0 value 0…127 This allows to set timings in a range between 10ms and 127s.

  Hints:

  If accessory timing control is implemented in the output unit:

  • only possible with normal accessory (bit 7 = 0)
  • the aspect is limited to 0 and 1
  • both aspects are not interlocked at the output unit.
  • The number of simultaneously active accessory commands may be limited. In this case, an MSG_CS_ACCESSORY is rejected and must be repeated some time later.

  Addressing scheme:
  BiDiB transports the address of the DCC command 'as is', there is no translation. DCC basic accessory addresses are limited in their address space through the DCC standard: decoder address 0 is not used (and therefore the addresses 0…3 are not used) and address 2047 with aspect 0 denotes an emergency stop command.

  There is a multi-level acknowledgement mechanism for accessory commands too. Its levels can be activated via FEATURE_GEN_SWITCH_ACK. The node sends the respective MSG_CS_ACCESSORY_ACK messages.

  Note: This message targets accessory decoders connected to DCC. It is recommended to directly connect accessories to BiDiB. These use the messages for class accessory and offer more features.

• MSG_CS_POM:

  Programming commands for the main track (Program On Main) will be issued with this command. Followed by other parameters that describe address, selected CV, data and operation to be performed. Programming commands will be acknowledged by one or multiple MSG_CS_POM_ACK messages. The various acknowledgement levels can be activated in the output unit via FEATURE_GEN_DRIVE_ACK. If a track output unit can not issue a command (e.g. because the operation is not implemented), it sends a MSG_CS_POM_ACK with ACK=0 nonetheless.

  If a Railcom-capable decoder answered the POM command, the appropriate bidi detector generates a MSG_BM_CV or MSG_BM_XPOM message.

  POM commands are available in several variations, with the following key differences:

  • Addressing of the target decoder can be done either via the DCC address (normal procedure) or via the decoder identifier. The decoder identifier is a 40-bit number consisting an manufacturer ID and a unique ID. In the command the MID (manufacturer ID) field is used to decide whether addressing is done via loco address or DID.
  • The target decoder can be a loco or an accessory decoder. At accessory decoders there is a further distinction between accessory and extended accessory. This is encoded in the two MSBs of the address, similar to addresses from bidi detectors.
  • Addressing of the target CV within the decoder: There is a classic version (POM) where 1024 CV's will be addressed and the content (read/write) is one or four bytes. With the introduction of Railcom, another version came up which extends the CV address to 24 bits and transmits 32 bits (XPOM). These are distinguished by the OPCODE of the BiDiB command.

  The parameters of the command MSG_CS_POM will always be encoded with the maximum field size, even if only short CV's will be addressed. Therefore, the address field is always 8+32 bit, the CV address field is 24 bit and the data field is 32 bit wide. As customary in BiDiB, the LSB will be transmitted first (little-endian).

  MSG_CS_POM parameters

  Parameter	Description
  ADDRL	Address, lower 8 bits (DID0 at decoder addressing).
  ADDRH	Address, upper 8 bits. The complete address is given by ADDRH*256+ADDRL. The address designates the real (DCC-)address and is counted from 0. (DID1 at decoder addressing); The distinction whether a accessory or loco decoder is addressed, is encoded in bit 14 and 15: Bit 15,14 = 00: Loco decoder Bit 15,14 = 10: (reserved) Bit 15,14 = 01: Standard accessory decoder Bit 15,14 = 11: Extended accessory decoder
  ADDRXL	0 at loco addressing, DID2 at decoder addressing
  ADDRXH	0 at loco addressing, DID3 at decoder addressing
  MID	0: Addressing via loco address 1…255: Addressing via decoder ID, then this field is the manufacturer ID (=DID4)
  OPCODE	Byte, defines the operation to be performed Value Name Meaning 0x00 BIDIB_CS_POM_RD_BLOCK PoM (standard CV 0…1023) block-byte (4 bytes) read 0x01 BIDIB_CS_POM_RD_BYTE PoM (standard CV 0…1023) byte read 0x02 BIDIB_CS_POM_WR_BIT PoM (standard CV 0…1023) bit write 0x03 BIDIB_CS_POM_WR_BYTE PoM (standard CV 0…1023) byte write 0x43 BIDIB_CS_XWR_BYTE1 Short Form CV Access write 1 byte 0x47 BIDIB_CS_XWR_BYTE2 Short Form CV Access write 2 byte 0x80 BIDIB_CS_xPOM_reserved XPoM (extended CV 24-Bit) reserved 0x81 BIDIB_CS_xPOM_RD_BLOCK XPoM (extended CV 24-Bit) block-byte read 0x82 BIDIB_CS_xPOM_WR_BIT XPoM (extended CV 24-Bit) bit write 0x83 BIDIB_CS_xPOM_WR_BYTE1 XPoM (extended CV 24-Bit) write 1 byte 0x87 BIDIB_CS_xPOM_WR_BYTE2 XPoM (extended CV 24-Bit) write 2 byte 0x8B BIDIB_CS_xPOM_WR_BYTE3 XPoM (extended CV 24-Bit) write 3 byte 0x8F BIDIB_CS_xPOM_WR_BYTE4 XPoM (extended CV 24-Bit) write 4 byte Hints: Bit 0,1: corresponds to DCC CC bits Bit 2,3: denotes number of bytes -1 in XPOM operation Bit 6,7: denotes POM/short form/XPOM
  CVL, CVH, CVX	CV-Address, low byte first. CVX is only required with XPOM and will be transferred as 0 for classic POM. CV starts counting at 0 (same as track the command). The CV naming of decoders starts at CV1 (CV1 will be coded with 0). For Short Form CV Access, this field directly sets the 4-bit Instruction Type, with the following values: Opcode Value Meaning XWR_BYTE1 0b0010 Acceleration Value, CV23:=DATA0 XWR_BYTE1 0b0011 Deceleration Value, CV24:=DATA0 XWR_BYTE1 0b1001 Service Mode Decoder Lock XWR_BYTE2 0b0100 long address, CV17:=DATA0, CV18:=DATA1, CV29.5=1 XWR_BYTE2 0b0101 index register, CV31:=DATA0, CV32:=DATA1
  DATA[1…4]	CV values. For standard POM there is only one datum, for XPOM write there are up to 4 data bytes.

  Hints:

  When writing a bit, the bit to be written is determined by DATA: DATA = 1111DBBB. BBB indicates the bit position and D indicates the value of the bit (identical to DCC definition).

  For each access from the track-output, a sequence ID (modulo 4) is generated for XPOM. This sequence ID will be transmitted together with the command. The track output must be 'in_order' with the commands.
  To ease the implementation of detectors, there should only be a global sequence generator instead of separate ones for each decoder.

  Decoder ID, CV address and data bytes are represented in little endian format. DCC transmission uses big endian and sends them in reverse order; e.g. DID₄,DID₃,DID₂,DID₁,DID₀ for the decoder ID.

• MSG_CS_BIN_STATE:

  With this command, individual actions can be triggered at the decoder, e.g. activate coupling or analogue functions. Followed by 5 bytes: ADDR_L, ADDR_H, STATE_L, STATE_H, DATA. STATE denotes the type of DCC message.

  MSG_CS_BIN_STATE parameters

  Parameter	Description
  ADDRL	Address, lower 8 bits.
  ADDRH	Address, upper 6 bits. The complete address is given by ADDRH*256+ADDRL. The address designates the real (DCC-)address and is counted from 0. Address 0 is reserved.
  STATEL	Binary state number, lower 8 bits	Function control with group commands (RCN 212 2.3.1-4) 0: reserviert. 1: functions F1…F4, F0. 2: functions F5…F8. 3: functions F9…F12. 4: functions F13…F20. 5: functions F21…F28. 6: functions F29…F36. 7: functions F37…F44. 8: functions F45…F52. 9: functions F53…F60. 10: functions F61…F68.	Analogue Channel (RCN 212 2.3.8), range 0…255
  STATEH	Binary state number, upper 7 bits. MSB is 0.	0x80 (Opcode 0, MSB is 1).	0x81 (Opcode 1, MSB is 1).
  DATA	Binary state condition. Value range 0,1	Bit vector with the functions as in the table above, first named function in LSB. range 0…255	Analogue value, range 0…255

  Binary states include 32767 possible outputs, they will be transmitted on the track together with the date D in 2 bytes: DCC codes this as DLLLLLLL HHHHHHHH. The Binary state number 0 means the addressing of all binary states in the decoder.

  Functions and analogue values are output once (with standard repeat count) to the track, they are not recorded in the command repeat memory. If a function command is already present in repeat-memory (ie from a previous MSG_CS_DRIVE), the value in there is updated.

  The support for analogue function commands and function groups up to F68 is announced in the FEATURE_GEN_EXT_AVAILABLE.

  MSG_CS_BIN_STATE commands will be acknowledged with a MSG_DRIVE_ACK (same as for motion commands).

• MSG_CS_QUERY:

  A query of active vehicles is performed with this command. Followed by 1 or more bytes encoding the query: QUERY[, ADDR_L, ADDR_H]

  MSG_CS_QUERY parameter

  Parameter	Description
  QUERY	ENUM of queried information and query mode: Bit Meaning 7 Query mode: 0: 0: Single query of object defined by ADDRL and ADDRH The node responds with a MSG_CS_DRIVE_STATE. 1: Query all objects of the specified type The node autonomously sends one MSG_CS_DRIVE_STATE for each address known in repeat memory, adjusting to the available transport capacity itself. The node must be able to receive and respond to other messages while delivering the answer sequence. If no object is known, the node responds with a MSG_CS_DRIVE_STATE on address 0. 6…4 Reserved, preset with 0 3…0 Type of object: 1: locomotive address
  ADDRL	Adress, lower 8 bits.
  ADDRH	Adress, upper 6 bits. The complete address is given by ADDRH*256+ADDRL. The address designates the real (DCC-)address and is counted from 0. Address 0 is reserved.

  The support of the generator for this command is determined by the FEATURE_GEN_EXT_AVAILABLE.

• MSG_CS_PROG:

  Service mode commands (at programming track) will be issued with this command. These track commands are only supported from output units with enabled class bit 3.

  Followed by further parameters, which describes the addressed CV, data and operations to be performed. MSG_CS_PROG command will be acknowledged by one or more MSG_CS_PROG_STATE message(s).

  Programming commands are available in several variations (for historical reasons) and they have the following key differences:

  • Address programming: simple, direct programming from the target address, no CV select possible. Will not be supported from BiDiB.
  • Register programming (paged): Selection from a CV within the range 1…8, further CVs can be addressed by setting of an page address. This is not any more supported by BiDiB.
  • CV-Programming, byte-mode: CV's can be queried byte-wise within an range of 1-1024.
  • CV-Programming, bit-mode: A single bit can be queried or set within a CV.

  The target decoder can be an loco decoder (standard) or an accessory decoder. There is no difference between an loco or accessory decoder if the programming is made at the programming track.

  Addressing the target CV within the decoder: 1024 CVs can be addressed with the programming track commands. Any higher CVs can be addressed by setting of an index register (CV 31 and CV 32) at host side.

  MSG_CS_PROG parameters

  Parameter	Description
  OPCODE	Byte, defines the operation to be performed Value Name Meaning 0x00 BIDIB_CS_PROG_BREAK Cancel the current operation 0x01 BIDIB_CS_PROG_QUERY Query the remaining time of current operation 0x02 BIDIB_CS_PROG_RD_BYTE Byte read 0x03 BIDIB_CS_PROG_RDWR_BIT Bit read/write 0x04 BIDIB_CS_PROG_WR_BYTE Byte write
  CVL, CVH	CV-address, low byte first. CV will be counted from 0 (same like track command). Decoder CV designation starts at CV1 (CV1 is coded as 0)
  DATA[0…1]	CV-Data. In case of byte-read, DATA is not required but may still be included in the command.

  Hints:

  In case of bit writing, the bit to be written will be determined by DATA: DATA = 111KDBBB, BBB indicates the bit position and D indicates the value of the bit. K is the correspondig command (1=write, 0=read) (identical with DCC definition).

  The answer to a bit operation will be either OKAY or FAILED (ie. with timeout). If a set bit inside a CV is queried with 'verify,D=1', the answer will be OKAY. If this bit is queried with 'verify,D=0', the answer will be FAILED, TIMEOUT, since there is no acknowledge from the decoder.

  The node responds immediately with an MSG_CS_PROG_STATE and after completion of the operation he responds again with another MSG_CS_PROG_STATE. [Discussion: should we require continuous STATE messages – progress bar?]

  MSG_CS_PROG is sequential action, the first programming action must be terminated before a second action can be started.

  Programming mode:The output unit must turn on programming mode by a status change to BIDIB_CS_STATE_PROG before programming commands can be executed. No normal track commands are possible as long as a service mode action is running. Output unit must be switched back to the normal operating mode after the service mode operations are completed.

  Service mode is a global and address-free method to change CVs in the decoders. This involves the risk that the user accidentally re-programm all locos and attached accessory decoders on the layout. A host program should inform the user (e.g. with an warning message) before the programming mode gets activated and if possible, the software should also switch off all dependent boosters and keep only the booster with the service mode alive.

• MSG_CS_RCPLUS:

  (optional, whether a node supports this command is defined by the FEATURE_GEN_RCPLUS_AVAILABLE)

  This command controls the Railcom-Plus packet output of the signal generator. Followed by at least one byte (OPCODE), depending on this opcode value followed by further bytes.

  Every MSG_CS_RCPLUS is responded to by one or multiple MSG_CS_RCPLUS_ACK with the respective OPCODE.

  Encoding of opcode for RailcomPlus command

  Name	Meaning
  RC_GET_TID	The track output device will return the current TID.
  RC_SET_TID	Setting of TID. Followed by another 6 bytes: CID0, CID1, CID2, CID3, CID4, SID
  RC_PING	Permanent transmission of the RailcomPlus track identifier (TID). Followed by another parameter INTERVAL, which defines the time difference between the transmissions in the unit of 100ms. A value of 0 disables the transmission.
  RC_PING_ONCE_P0	Singular transmission of the RailcomPlus track identifier (TID).
  RC_PING_ONCE_P1
  RC_BIND	Assigning a decoder address. Followed by another 7 bytes: DEC_MUN0,DEC_MUN1,DEC_MUN2,DEC_MUN3, DEC_MID, NEW_ADDRL, NEW_ADDRH. The new address is coded as follows: Bit 15,14 Bits 13…0 00 loco address (short format up to and including 127, long format from 128; Value range 1…59391) 10 (reserved) 01 accessory address (value range 0, 4, 8…2044) 11 extended accessory address (value range 0…2046) With address 0 a decoder can be logged off, with DID 0 even all at once. In doing so, the SID has to be incremented as well.
  RC_FIND_P0	A FIND packet with (un)set P-bit is issued. Followed by 5 bytes: DEC_MUN0,DEC_MUN1,DEC_MUN2,DEC_MUN3, DEC_MID
  RC_FIND_P1

  Hints:

  The permanent transmission of the TID is inactive (INTERVAL = 0) after every start or reset of the node.

  At the permanent transmission of the TID both phases are approached. The interval is the maximal time for gaps between two transmissions with the same phase bit.

  To ensure the delivery of the packets to every decoder, they will have to be repeated (typically back-to-back). The number of repetitions can be set via the feature FEATURE_GEN_POM_REPEAT.

4.5.4. Uplink: Messages for track-output

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

0. Acknowlegdement Level 0: The node has received the command.
1. Acknowlegdement Level 1: The command is issued at the track.
2. 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.

• MSG_CS_STATE:

  With this message, the current state of the output is reported, followed by one byte which encodes the current state. The state is encoded similar to MSG_CS_SET_STATE.

• MSG_CS_DRIVE_ACK:

  Motion commands will be acknowledged with this command. Followed by further parameters:

  MSG_CS_DRIVE_ACK parameters

  Parameter	Description
  ADDRL	Address, lower 8 bits.
  ADDRH	Address, upper 6 bits. The complete address is given by ADDRH*256+ADDRL. The address designates the real (DCC-)address and is counted from 0.
  ACK	Acknowledge, coded as described above.

• MSG_CS_ACCESSORY_ACK:

  Switching commands will be acknowledged with this command. Followed by further parameters:

  MSG_CS_ACCESSORY_ACK parameters

  Parameter	Description
  ADDRL	Address, lower 8 bits
  ADDRH	Address, upper 3 bits. The complete address is given by ADDRH*256+ADDRL. The address designates the real (DCC-)address and is counted from 0.
  ACK	Acknowledge, coded as described above.

• MSG_CS_POM_ACK:

  POM commands will be acknowledged with this command. Followed by further parameters, address and acknowledge. Address is coded identically to the MSG_CS_POM command and will be just 'passed through' at the node.

  MSG_CS_POM_ACK parameters

  Parameter	Description
  ADDRL	Address, lower 8 bits (DID0 at decoder addressing)
  ADDRH	Address, upper 8 bits. (DID1 at decoder addressing); The complete address is given by ADDRH*256+ADDRL. The address designates the real (DCC-)address and is counted from 0. The distinction whether a accessory or loco decoder is addressed, is encoded in bit 14 and 15: Bit 15,14 = 00: Loco decoder Bit 15,14 = 10: (reserved) Bit 15,14 = 01: Standard accessory decoder Bit 15,14 = 11: Extended accessory decoder
  ADDRXL	0 at loco addressing, DID2 at decoder addressing
  ADDRXH	0 at loco addressing, DID3 at decoder addressing
  MID	0: Addressing via loco address 1…255: Addressing via decoder ID, then this field is the manufacturer ID (=DID4)
  ACK	Acknowledge, coded as described above.

• MSG_CS_DRIVE_MANUAL:

  Manual operation (via handheld) of an loco will be reported with this command. For this purpose, the feature FEATURE_GEN_NOTIFY_DRIVE_MANUAL has be set to 1. Followed by further parameters with the same structure like MSG_CS_DRIVE:

  MSG_CS_DRIVE_MANUAL parameters

  Parameter	Description
  ADDRL	Address, lower 8 bits
  ADDRH	Address, upper 6 bits
  DATA0	Bitfield, Format
  DATA1	Bitfield Output active
  DATA2	Speed
  DATA3	3*reserved, FL (light), F4, F3, F2, F1
  DATA4	F12 – F5
  DATA5	F20 – F13
  DATA6	F28 – F21

• MSG_CS_DRIVE_EVENT:

  This command reports the events in a loco. Followed by further parameters:

  MSG_CS_DRIVE_EVENT parameters

  Parameter	Description
  ADDRL	Address, lower 8 bits
  ADDRH	Address, upper 6 bits. The complete address is given by ADDRH*256+ADDRL. The address designates the real (DCC-)address and is counted from 0.
  EVENT	Event, coded as follows: Value Meaning 0 No event present 1 LOST: The loco is not responding to commands. This tracing can be enabled through FEATURE_GEN_LOK_LOST_DETECT.

  Notes on LOST:

  A common fault during operation are 'down' or 'hanging' locos which are not able to receive motion commands due to contact problems. If a model railway is fully equipped with railcom detectors, the track-output unit can notice the lost connection and report it to the host.

  The track-output unit monitors the ACK-wire at the BiDiBus and is activating the watchdog for a loco decoder address if ACK-confirmations will be received for this decoder. After 10 loco commands without ACK-confirmation, the MSG_CS_DRIVE_EVENT should be generated. This will work, of course, only if the system is fully equipped with railcom detectors, otherwise the 'LOST' message already appears if a loco is running on non railcom-monitored track sections.

• MSG_CS_DRIVE_STATE:

  This command reports results of MSG_CS_QUERY inquiries. Followed by one parameter which encodes the type of response, further parameters are coded identical to MSG_CS_DRIVE_MANUAL. When a non-existing loco is queried, the address is reported with all data fields set to 0.

  MSG_CS_DRIVE_STATE parameters

  Parameter	Description
  OPCODE	ENUM of the query mode and the requested information: Bit Meaning 7 Query mode: 0: Message is response to single query 1: Message is one of many responses in a stream 6 End: 0: more messages will follow 1: last message of the transmission (also set in single responses) 6…4 Reserved, preset with 0 3…0 Type of object: 1: locomotive address
  ADDR[2]	Coded identical to MSG_CS_DRIVE_MANUAL
  DATA[7]

• MSG_CS_PROG_STATE:

  This command reports results from an programming operation in service mode. Followed by further parameters:

  MSG_CS_PROG_STATE parameters

  Parameter	Description
  STATE	Result Wert Name Meaning 0x00 BIDIB_CS_PROG_START This status is returned after receipt of the programming command. 0x01 BIDIB_CS_PROG_RUNNING Status during execution. RUNNING will be send during longer operations as an intermediate message for an QUERY request. 0x80 BIDIB_CS_PROG_OKAY Programming operation successful. 0xC0 BIDIB_CS_PROG_STOPPED Der Programming operation was stopped, Result is not valid. 0xC1 BIDIB_CS_PROG_NO_LOCO Programming operation was stopped, no load recognized at the track. 0xC2 BIDIB_CS_PROG_NO_ANSWER Programming operation was stopped, programming was not acknowledged by loco or no repsonse during reading. 0xC3 BIDIB_CS_PROG_SHORT Programming operation stopped, short detected. 0xC4 BIDIB_CS_PROG_VERIFY_FAILED Programming operation stopped, verify failed (see hint below).
  TIME	Predicted remaining time in units of 100ms. For technical reasons, the remaining time is difficult to estimate, especially on decoder assemblies which does not support bit-mode the result is fluctuating greatly. The node attempts data just sequentially through and is done by an 'Hit'.
  CVL, CVH	CV-address low byte first. CV will be counted from 0 (same as track command). The CV designations of decoders start at CV1 (CV1 will be coded with 0). Value range 0…1023
  DATA[0…1]	CV-Data. DATA is not needed in case of byte-write or an error message but can be included in the command yet.

  Hints:

  At STATE, MSB is coding the status 'running / done' and bit 6 'Error occurred'.

  If a STATE is reported as 'finished', the TIME field is present but invalid and must be encoded with 0.

  BIDIB_CS_PROG_VERIFY_FAILED may, for example, occur if 2 decoders are present at the track output: Replies can overlap during bit-wise reading of CV contents and the read result will not be confirmed at the final check.

• MSG_CS_RCPLUS_ACK:

  (optional, whether a node supports this message is defined by the FEATURE_GEN_RCPLUS_AVAILABLE)

  This message acknowledges Railcom-Plus commands. Followed by at least one byte (OPCODE), depending on this opcode value followed by further bytes.

  MSG_CS_RCPLUS_ACK parameters

  Parameter	Description
  OPCODE	Classification of the response, see below
  ACK	(for BIND, PING_ONCE and FIND) Acknowledge, coded as described above. Additionally to the usual level 0 receipt acknowledgement as the immediate response to MSG_CS_RCPLUS, the device may send acknowlegements of higher levels. Support for this is defined by FEATURE_GEN_DRIVE_ACK. The permanent transmissions of the TID with the interval set via RC_PING are then reported with OPCODE = RC_PING_ONCE_P0/P1.

  Enoding of opcode for RailcomPlus acknowledgement

  Value		Meaning
  RC_TID		Reports the queried or assigned TID. Followed by another 6 bytes: CID0, CID1, CID2, CID3, CID4, SID
  RC_PING		Reports the interval between transmissions of the TID. Followed by another byte INTERVAL (unit 100ms, the value means "inactive")
  RC_BIND		Assignment of a decoder address. Followed by another 6 bytes: ACK, DEC_MUN0,DEC_MUN1,DEC_MUN2,DEC_MUN3, DEC_MID
  RC_PING_ONCE	P0	Transmission of the TID. Followed by 1 byte with the acknowledge code.
  	P1
  RC_FIND	P0	Search for decoders. Followed by another 6 bytes: ACK, DEC_MUN0,DEC_MUN1,DEC_MUN2,DEC_MUN3, DEC_MID
  	P1

4.6. Accessory and peripheral classes

In the control of stationary model railroad equipment, BiDiB distinguishes between functions of the class accessory and functions of the class peripherals. Only the former are employed for safe train operation, they possess the facilities for aspect requests, position feedback and error handling.

For peripheral effects and for configuration of accessories, there are the simple switching functions and macros, which can directly control the output ports of the devices.

4.6.1. Controlling of track system accessory functions

A node can have the potential to represent turnouts, turntables, signals, level crossings and much more, commonly referred to as "objects" in here. Nodes with controls for such track system relevant objects set the flag for the class-ID 'Accessory'.

Accessory objects each have an 'aspect' which they can present or to which they can change. A typical switch uses 'straight' or 'branch line', but also turnouts with more than one branch, turntables and transfer tables fall under this definition. The 'aspect' at a turntable describes the particular exit track. The state of an accessory is solely controlled by the host, it cannot be perturbed by external influences. On its own the accessory can only transition into an error state.

When a new aspect is selected, the object assumes the respective state. This switching action might need some time, in this case the node announces the expected switching time as the confirmation and another status message after completing the action. When a problem arises, the node will automatically send an error message.

It is possible that an unforeseen status change happens, e.g. through a manual operation. In this case the node will send a MSG_ACCESSORY_NOTIFY message spontaneously. This spontaneous transmission has to be enabled by a 'SYS_ENABLE' and also by the relevant feature setting.

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

The configuration of the controlled object depends on its activation type, the implementation falls to the manufacturer and may vary based on the device and use case (e.g. solenoid actuator, servo, stepper, light signal, semaphore type signal etc.). Available are common parameters, see MSG_ACCESSORY_PARA_SET, as well the generic messages for user configuration. Furthermore, accessory operations can be mapped to port commands (switching functions), whereby the extensive options for the configuration of single ports can be utilised, see MSG_LC_CONFIGX_SET.

A node only informs the host about the number of aspects of an accessory, not what kind of object it is about. Such assignment is the responsibility of the control program, a systematisation would go beyond the scope of the protocol and could never achieve completeness.

Still, in the arrangement of the aspects there are some guidelines to be followed. The aspect 0 should always represent the position of rest, for turnouts that is usually the main line. For signals, aspect 0 must represent the Stop indication. For turntables, traversers, segment tables etc. there are two different geometries to consider:

• Linear arrangements (like e.g. segment turntable): Each accessible track exit will be associated to an aspect of the accessory object in sequence.
• Rotationally symmetrical arrangements (like e.g. typical turntable): Each accessible track exit will be associated to an aspect of the accessory object, in ascending order in clockwise direction when seen from the top. The position always denotes the same side of the turntable (with control shack).
  A track exit might be accessible but unusable, e.g. when the turntable is in an position where the shack is opposite to a usable track exit. Such a position is 'passive', but it's nonetheless added to the aspect set. In which positions the platform can be passed over is to be defined in the host software.
  The number of aspects is always even and two aspects are always located 180° opposite to each other.

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.

A special case of composed object control is the operating mode. Here the state of one accessory affects the significance of another accessory state. This dependency is observable via the BIDIB_ACCESSORY_PARA_OPMODE. In doing so, the accessory for the operating mode has two or more aspects that are defined as follows:

• Aspect 0 – "(Emergency) stop": The whole object is halted. The aspects of the composite's other accessories are irrelevant to the total state in this mode.
• Aspect 1 – "Operating (normally)": The object is in use and follows the aspects of the other accessories, their state is valid. Only in this mode the object may be passed with trains by the control software.
• Further aspects are considered irregular modes and have to be treated like aspect 0, i.e. the state of the other accessories is invalid and the object must not be utilised.
  Examples: In calibration mode a traverser aligns its platform position with a homing sensor, in configuration mode a turntable can be moved by hand.

Even while their state does have no effect on the object, the accessories continue to be controllable normally. Typically the object will not assume the selected aspects until it switches to the mode Operating. Therefore the switching time has to be respected as usually when changing the operating mode.

4.6.2. Features for accessory functions

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

If a certain number of accessories is announced via the feature, all of them have to be implemented and addressable.

4.6.3. Downlink: Messages for accessory functions

• MSG_ACCESSORY_SET:

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

  MSG_ACCESSORY_SET parameters

  Parameter	Description
  ANUM	Identifies the accessory object within the node, range 0…127.
  ASPECT	This byte defines the state of the object, the non-operating state is represented by 0. The value 254 puts the model at a safe rest ("emergency stop"). Range 0…127.

  The node replies with MSG_ACCESSORY_STATE. If the action takes longer than 100ms, the reply have to happen immediately using MSG_ACCESSORY_STATE including the predicted switching time. After completion another MSG_ACCESSORY_STATE will be sent to indicate the finished sequence.

  SecureSwitch:

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

  If ANUM is indicating an object which does not exist for this node, the node replies with MSG_ACCESSORY_STATE, object number 255, aspect 255, error code 0x01. The number of possible objects can be read out with a feature request.

  If the aspect is not in the range of the object, the node responds with MSG_ACCESSORY_STATE, aspect = 255, error code 0x01.

• MSG_ACCESSORY_GET:

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

  The node replies with MSG_ACCESSORY_STATE.

• MSG_ACCESSORY_GETALL:

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

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

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

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

• MSG_ACCESSORY_PARA_SET:

  (optional)

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

  Two or more bytes are following:

  MSG_ACCESSORY_PARA_SET parameters

  Parameter	Description
  ANUM	Identifies the object at the node, range 0…127.
  PARA_NUM	Number of the parameter to set.
  DATA[0…]	Values to be set, depending on the parameter.

  The node is answering with MSG_ACCESSORY_PARA. If PARA_NUM is not known at the object, the node responds with PARA_NUM = BIDIB_ACCESSORY_PARA_NOTEXIST (255) and the unknown parameter.

  Encoding of accessory configuration parameters

  Value	Name	Meaning
  1-248	–	Reserved.
  249	BIDIB_ACCESSORY_PARA_USES_STRINGS	The accessory is responsible for the selection of a string for text output on a display, the aspects 0 to TOTAL-1 correspond to the strings from namespace 2 (index 0 to TOTAL-1). A single byte with the value 1 follows. The string namespace 2 has at least the length of TOTAL. This parameter allows to offer a suitable aspect switching control for the affected accessories. It is typically non-writable.
  250	BIDIB_ACCESSORY_PARA_HAS_ESTOP	The accessory supports the emergency stop aspect. A single byte with the value 1 follows. If the parameter is not present or holds a different value, the accessory does not have implemented an emergency stop and will respond only with an error to attempts of using it. The parameter is typically non-writable.
  251	BIDIB_ACCESSORY_PARA_OPMODE	The accessory is part of a composite object with an operating mode. A single byte ANUM follows which contains the number of the accessory object that represents the operating mode, range 0…127. The parameter is typically non-writable. Its range does not contain a value for severing the dependency, where no dependency is in effect the whole parameter is not present.
  252	BIDIB_ACCESSORY_PARA_STARTUP	Behaviour of the accessory at node startup or reset. A single byte with the following meaning follows: 0…127: the respective aspect is put into effect. 254: the node backs up the most recently set aspect. 255: the node does nothing when starting up. If feedback is available, the aspect for the current position may be assumed, otherwise "unknown" 255 should be used. Nodes that don't have this parameter shall behave as if the value 255 set. In case position surveillance (feedback) is available, the switching action may be avoided if the position already matches the target state (for 0…127, 254). A node may (and should) dynamically delay necessary switching actions to avoid overloads while powering up. If MSG_ACCESSORY_GET messages are already responded to during that time, an appropriate remaining execution time has to be announced.
  253	BIDIB_ACCESSORY_PARA_MACROMAP	Assigning of aspects to macros. Each aspect of the accessory object gets a macro assigned. Further following bytes define the assignment. DATA0: Number of the macro, which will be executed for aspect 0. DATA1: Number of the macro, which will be executed for aspect 1. DATA2: Number of the macro, which will be executed for aspect 2. etc. The length of the list is limited to 16. Only valid macro numbers are allowed. The end of the list will be indicated with an entry of 255. The list will be adopted by the node until the maximum number of aspects. (see also FEATURE_ACCESSORY_MACROMAPPED)
  254	BIDIB_ACCESSORY_SWITCH_TIME	Switch time, defined like in the railcom specification. Bit Meaning 7 base unit: 0: 100ms (total range 0…12.7s) 1: 1s (total range 0…127s) 6…0 switch time, range 0…127
  255	BIDIB_ACCESSORY_PARA_NOTEXIST	(in uplink only) The requested PARA_NUM is not known at the node or does not exist for this accessory. Followed by one byte with the number of the requested parameter from protocol version 0.7 and further.

• MSG_ACCESSORY_PARA_GET:

  (optional)

  The configuration parameters of an accessory object can be read with this message. Two bytes are following: ANUM, PARA_NUM. The node is answering with MSG_ACCESSORY_PARA.

4.6.4. Uplink: Messages for accessory functions

• MSG_ACCESSORY_STATE:

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

  Five or more bytes are following:

  MSG_ACCESSORY_STATE parameters

  Parameter	Description
  ANUM	identifies the object of this node, range 0…127. For ANUM=255 the requested object doesn't exist.
  ASPECT	This byte describes the current state (or the planned one during a change). Range 0…127. For ASPECT=254 the object did an emergency shutdown, all movements are halted to prevent damage to models. For ASPECT=255 the state is unknown. This usually corresponds to the set value, unless there is an error.
  TOTAL	This byte provides the number of possible aspects of their object. Aspect numbers are starting always at 0 and are counted upwards without gaps. Range 0…128. Examples: Standard turnout: 2 aspects: 0 and 1 Signal with Hp 0, Hp 1, Hp 2: 3 aspects: 0, 1 und 2 If an object supports the emergency stop aspect, this has to be declared in the parameter HAS_ESTOP. Note: There will be no aspects when an accessory returns the value 0 for the parameter TOTAL and it will be not possible to switch something. This can happen for example at macro based accessory when no macros are connected to aspects.
  EXECUTE	This byte reflects the state of the execution: the activity has already finished, if supervision is ongoing and if a failure has happened occasionally: Bit 7 Meaning 0 normal operation Bit Meaning 0 0: Target state reached. WAIT is 0. 1: Target state not reached. WAIT tells about the expected remaining time. 1 0: Target state is verified by feedback (e.g. switching contact). 1: Verification of target state does not exist. 6…2 reserved, coded as 0 1 Error happened (e.g. broken coil / manual displacement); WAIT tells the cause (coded like railcom specification) an. Bit Meaning 6…0 reserved, coded as 0 In case of an error, the last reported operation state (target reached vs. still moving) is kept.
  WAIT	normal operation: After the target state has been reached, the value 0 will be announced. If the target state has not been reached, the remaining time will be provided according to the specification of Railcom. Bit Meaning 7 Base Unit: 0: 100ms (total range = 0…12,7s) 1: 1s (total range = 0…127s) 6…0 switch time, valid range 0…127 Error Code: Bit Meaning 7 reserved, coded as 0 6 0: There is only this error. 1: There are more error codes in the node which will be sent with the next messages. 5…0 0x00 no (more) errors. When bit 6 is set, it is the end of the error list and the next message will start over. 0x01 unknown object/invalid aspect. The received command could not be executed and is ignored. This error code is always sent with Aspect=255, but the previous error condition and aspect remain. 0x02 power consumption too high. 0x03 power supply below limits, function not garanteed. 0x04 fuse blown. 0x05 temperature too high. 0x06 feedback error (e.g. detection of unwanted position change, unsuccessful execution). This error code might be sent together with a new aspect, often 255 ("unknown"). 0x07 local control (eg. with button on the device). This error code might be sent together with the new aspect. 0x10 bulb out of order. 0x20 servo out of order. 0x3F internal error (eg. selftest, checksum error, …). An error state with cause 0x06 or 0x07 can be relieved through MSG_ACCESSORY_SET.
  DETAILS[0…40]	Optional supplemental details about the current state of the accessory operation. They conduce to precise tracking and display of an accessory, but are not operationally relevant. The node decides which information is appended when, a targeted query is not available. The data is transferred as a list with 0 to 8 key-value pairs, consisting of parameter type and value. DETAILS_LIST ::= ε | DETAIL_PAIR DETAILS_LIST DETAIL_PAIR ::= D_ENUM1 D_VALUE | D_ENUM2 D_VALUE[2] D_ENUM1 = 0x00 | … | 0x3F D_ENUM2 = 0x40 | … | 0x7F

  Encoding of state detail parameters

  Name	Code	Value type	Description
  BIDIB_ACC_DETAIL_CURR_ANGLE1DEG5	0x01	uint8	Current position angle (for instance of a turntable) in units of 1.5 degree, value range 0…239. Objects with an adjustable min/max range also scale their position reports to the range 0…239.
  BIDIB_ACC_DETAIL_TARGET_ANGLE1DEG5	0x02	uint8	Targeted position angle at the end of the movement, in units of 1.5 degree, value range 0…239.
  BIDIB_ACC_DETAIL_TIMESTAMP	0x40	uint16	System timestamp for the moment of position measurement.

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

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

• MSG_ACCESSORY_NOTIFY:

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

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

  SecureSwitch:

  The reception of a MSG_ACCESSORY_NOTIFY (with WAIT=0) must be be acknowledged with a query (MSG_ACCESSORY_GET) or command (MSG_ACCESSORY_SET) to this accessory object. If this confirmation is missing, then the node repeats the message MSG_ACCESSORY_NOTIFY up to eight times, repetition interval is 500ms.
  A MSG_ACCESSORY_NOTIFY with WAIT!=0 is an intermediate update and need not be acknowledged.

  In the case of a change of the ASPECT, either the announced aspect can be accepted as 'new' or it can be attempted to renew the previous aspect.

  If bit 6 in WAIT is set (=there are more error states in the node), these errors should be collected by one or more additional MSG_ACCESSORY_GET messages until error code 0x00 is reached.

• MSG_ACCESSORY_PARA:

  (optional)

  This message will be sent as an answer to a request or change of (configuration) parameters.

  Two or more bytes are following: ANUM, PARA_NUM [Data], same coding as for MSG_ACCESSORY_PARA_SET.

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:

• Configuration of the controlling source for a port (via switching command, via time)
• Combination of switching functions to local macro sequences
• Configuration for those macro sequences (sequence speed, start condition)

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.

In the type-based port model only port types of width 1 are used. Other widths are applicable only in the flat model, where a different number of ports may be available depending on the type configuration. Two outputs with exclusive activation can be represented as one SWITCH port in the type-based model.

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:

4.6.7. Downlink: Messages for peripheral / switching functions

• MSG_LC_OUTPUT:

  Direct output operation, followed by 3 Bytes: PORT₀, PORT₁, PORTSTAT. These 3 bytes define the number of the output and the operation which is carried out at this output.

  MSG_LC_OUTPUT parameters

  Parameter	Description
  PORT[2]	These bytes address the port
  PORTSTAT	This byte describes the status of the port, the meaning depends on the output type. Output type Encoding of output commands 0 (=BIDIB_PORTTYPE_SWITCH) Normal switch output, the following operations are available: Value Name Operation 0 BIDIB_PORT_TURN_OFF Switch output OFF 1 BIDIB_PORT_TURN_ON Switch output ON 2-255 - reserved Other possible modes: Output pulse (for turnouts) 1 (=BIDIB_PORTTYPE_LIGHT) Switch output for light control, the following operations are available: Value Name Operation 0 BIDIB_PORT_TURN_OFF Switch output directly to brightness OFF 1 BIDIB_PORT_TURN_ON Switch output directly to brightness ON 2 BIDIB_PORT_DIMM_OFF Dim output directly to brightness OFF 3 BIDIB_PORT_DIMM_ON Dim output directly to brightness ON 4 BIDIB_PORT_TURN_ON_NEON Switch output to brightness ON with neon flickering 5 BIDIB_PORT_BLINK_A Output flashes with approx. 1Hz, flashing starts with the ON-phase. A configured dimming is active here. 6 BIDIB_PORT_BLINK_B Output flashes with approx. 1Hz, flashing starts with the OFF-phase. A configured dimming is active here. 7 BIDIB_PORT_FLASH_A Output flashes with approx. 3Hz, flashing starts with the ON-phase. 8 BIDIB_PORT_FLASH_B Output flashes with approx. 3Hz, flashing starts with the OFF-phase. 9 BIDIB_PORT_DOUBLE_FLASH Output drives double flashes, repetitive (rescue vehicle) Modes 5 and 6 are intended for railway crossings, the modes 7 and 8 for warning lights. 2 (=BIDIB_PORTTYPE_SERVO) Servo output, PORTSTAT is the target position of the servo in this case. A PORTSTAT of 0 corresponds to the lower stop, 255 to the higher stop. The stops can optionally be configurable (see below), their maximum range shall be a servo pulse width from 0.5 ms to 2.5ms. These values are chosen broader than the normed 1ms to 2ms, as many real servos are controllable beyond those. 3 (= BIDIB_PORTTYPE_SOUND) Sound function, the following operations are available: Value Name Operation 0 BIDIB_PORT_TURN_OFF Stop playing 1 BIDIB_PORT_TURN_ON Play sound 2-255 - reserved BIDIB_PCFG_TICKS is used to distinguish between continuous (repeat) mode and moment activation. 4 (= BIDIB_PORTTYPE_MOTOR) Motor function, PORTSTAT denotes the speed. The encoding equals that of DCC128: The MSB encodes the direction of rotation: 1 = Forward, 0 = Reverse The LSBs (Bit 6…0) encode the 126-step speed value with 0 = Stop and 1 = Emergeny stop. 5 (= BIDIB_PORTTYPE_ANALOGOUT) Analog function (Detailed definition will follow) 6 (= BIDIB_PORTTYPE_BACKLIGHT) Light function, direct dimming. PORTSTAT denotes the target brightness, range 0…255. 7 (=BIDIB_PORTTYPE_SWITCHPAIR) Alternating activation of two switch outputs, e.g. for coil drives. The following operations are available: Value Name Operation 0 BIDIB_PORT_TO_0 Switch first output on and second one off 1 BIDIB_PORT_TO_1 Switch first output off and second one on 2-255 - reserved Compare RCN 213, Description of the R-Bit in the format of basic accessory commands. For standard applications, PORTSTAT = 0 means turnout to diverging or left track resp. signal at stop ("red") and PORTSTAT = 1 means turnout to straight or right track resp. signal at clear ("green"). 7…15 reserved

  A node responds with a MSG_LC_STAT message if he receive a switch command. If a port outside of the available range is selected or a switching state which is not supported, the node responds with a MSG_LC_NA message. If a node does not support a particular state transition, he should perform the next possible transition: e.g. neon flickering is not available, it should be switch on normal.

• MSG_LC_PORT_QUERY:

  (up to and including protocol version 0.6 known as MSG_LC_OUTPUT_QUERY, for outputs only)

  This message queries the state of an output or input port, followed by 2 Bytes to address the port. The node shall respond with a MSG_LC_STAT, or MSG_LC_NA in case.

  Hints:

  This message is optional for outputs. Whether this message is answered by the node is defined by the feature FEATURE_CTRL_PORT_QUERY_AVAILABLE. If this feature is missing or has a value of 0, there may be no answer to MSG_LC_PORT_QUERY. When the node has inputs, these always are queryable.

  This message is supposed to allow the host to retrieve the state of output ports so that it can e.g. display them appropriately on the screen.

  Output states are internal to the node, they may change at any time through accessory switching, macro execution, as reaction to inputs, caused by timers or more. The host is not automatically notified of such changes. If that is necessary an accessory should be used instead, for which the protocol provides the respective safety messages.

• MSG_LC_KEY_QUERY:

  (deprecated, from declared protocol version 0.7 use MSG_LC_PORT_QUERY)

  With this message, the state of a local push button on a node can be queried. Whether the node has push buttons (and how many) must be read from the node by a feature-query. Followed by one byte: PORT.

  MSG_LC_KEY_QUERY parameters

  Parameter	Description
  PORT	Button number. Corresponds to PORT0 in the flat port model and to PORTNUM in the type-based one (with PTYPE=15).

  The node responds with a MSG_LC_KEY message, which contains the present status of the button, or with MSG_LC_NA in case.

• MSG_LC_PORT_QUERY_ALL:

  Query of multiple port states. Followed by 0, 2 or 6 bytes. If any parameters follow, they set the requested types and range.

  MSG_LC_QUERY_GET_ALL parameters

  Parameter	Description
  SELECT[2]	These bytes form a 16 bit long bitmap that allows to filter the queried ports by type. Bit 0 of SELECT0 corresponds to SWITCH, bit 1 to LIGHT and so on. If the respective bit is not set, the port will be skipped.
  START[2]	These bytes address the first port to be transmitted.
  END[2]	These bytes address the first port to be no more transmitted.

  If the parameters are omitted, SELECT takes the value 0xFFFF, START the value 0 and END the value 0xFFFF. It is required that START <= END.

  The node responds with multiple MSG_LC_STAT messages, one for every port on the node that lies in the range denoted by START and END and for which the bit corresponding to its type is set in SELECT. The order of the ports must be adhered, the answer messages need to be sequenced by the port address in ascending order.

  At the end of the transmission, the node sends a MSG_LC_NA with the port address 0xFFFF.

  Hints:

  The request for multiple port states of a node is available from declared protocol version 0.7.

  If the node does not support queries for output states (FEATURE_CTRL_PORT_QUERY_AVAILABLE), those ports are ignored (SELECT &= 0xFF00).

  This message is destined for quickly reading in the port states of a node. The transmission of the responses uses the block transfer capabilities of the transport protocol, with the node adjusting to the available capacity itself. The host does not need to take any precautions against data flow stalling (cp. MSG_STALL). The node must be able to receive and respond to other messages while processing the answer sequence.

  The number of answer messages to be expected can be determined using suitable feature queries.

  MSG_LC_PORT_QUERY_ALL messages are not buffered. When a new MSG_LC_PORT_QUERY_ALL message is sent to the node during an ongoing transmission, the current sequence is aborted and a new transmission is started. By requesting an empty range, a transmission can be aborted through this.

  The MSG_LC_NA is a marker that allows to safely detect the end of the transmission even without any knowledge about the existing ports and their types.

  Examples:

  A query MSG_LC_PORT_QUERY_ALL 0xFF 0xFF, 0x00 0x00, 0xFF 0xFF returns the states of all ports of the node (like a query without parameters would).

  A query MSG_LC_PORT_QUERY_ALL 0x00 0xFF, 0x00, 0x00, 0x08, 0x00 on a node with the type-based port model returns only MSG_LC_NA 0xFF 0xFF, as the filter selects only inputs and the range only outputs.

  A query MSG_LC_PORT_QUERY_ALL 0x06 0x00, 0x01 0x00, 0xFF 0xFF returns the states of all light and servo ports from port address 16 and up.

• MSG_LC_CONFIGX_SET:

  Port configuration. Followed by n parameter:

  MSG_LC_CONFIGX_SET parameters

  Parameter	Description
  PORT[2]	These bytes address the port
  DATA[2…41]	List with 1 to 8 key-value pairs, consisting of parameter type and value. P_LIST ::= P_PAIR | P_PAIR P_LIST P_PAIR ::= P_ENUM P_VALUE

  The node stores the parameters and responds with a MSG_LC_CONFIGX message, all filed values will be transmitted and possible parameter problems be reported via BIDIB_PCFG_NONE. If a port outside of the available range is selected, the node responds with a MSG_LC_NA message instead.

  Encoding of port configuration parameters

  Name	Code	Value type	Description
  BIDIB_PCFG_NONE	0x00	uint8	0: no parameters available 1…n: parameter error (unknown or unavailable type, invalid value). The byte denotes that parameter code. For merely invalid values, the old setting shall be conserved and sent along.
  BIDIB_PCFG_LEVEL_PORT_ON	0x01	uint8	Analog brightness value for status ON, value range 0…255; (1)
  BIDIB_PCFG_LEVEL_PORT_OFF	0x02	uint8	Analog brightness value for status OFF, value range 0…255
  BIDIB_PCFG_DIMM_UP	0x03	uint8	Pace for dimming to ON, as steps performed per 10ms (2), range 1…255
  BIDIB_PCFG_DIMM_DOWN	0x04	uint8	Pace for dimming to OFF, as steps performed per 10ms (2), range 1…255
  BIDIB_PCFG_OUTPUT_MAP	0x06	uint8	Mapping to output channel (like for DMX) (3)
  BIDIB_PCFG_SERVO_ADJ_L	0x07	uint8	Servo Adjust Low (4)
  BIDIB_PCFG_SERVO_ADJ_H	0x08	uint8	Servo Adjust High (4)
  BIDIB_PCFG_SERVO_SPEED	0x09	uint8	Servo Speed
  BIDIB_PCFG_SERVO_EXTRA	0x0a	uint8	Special settings for servo, bitfield. Bit 0: Switch off voltage. If this bit is set, servo power is turned off after motion. This saves current and reduces possible small movements in the target position.
  BIDIB_PCFG_TICKS	0x0b	uint8	Output activation time, unit 10ms. After the stated time, the output is switched off automatically to prevent an overload. Through repeated switch commands the tripping may be postponed. The value 0 represents a continuous output.
  BIDIB_PCFG_SWITCH_CTRL	0x0d	uint8	Electrical behaviour of SWITCH ports. The upper nibble encodes the behaviour for the ON state, the lower nibble for the OFF state. Each of the two nibbles has the following value range: 0: LOW (put to GND) 1: HIGH (put to VCC) 2: Z (high impedance) 3: WEAK_LOW (pulled to GND with resistor, no current load) 4: WEAK_HIGH (pulled to VCC with resistor, no current load) If WEAK_LOW or WEAK_HIGH are not supported, the node has to treat them like Z.
  BIDIB_PCFG_INPUT_CTRL	0x0e	uint8	Electrical behaviour of INPUT ports. Value range: 0: ACTIVE_LOW (the input is active when connected to GND) 1: ACTIVE_HIGH (the input is active when VCC is applied) 2: ACTIVE_LOW + PULLUP (the input is pulled to VCC with a great resistor for well-defined idle state) 3: ACTIVE_HIGH + PULLDOWN (the input is pulled to VCC with a great resistor for well-defined idle state) If PULLUP or PULLDOWN are not supported, the node has to respect only the LSB.
  BIDIB_PCFG_LOAD_TYPE	0x0f	uint8	Load type of an OUTPUT port. Value range: 0: general (switch only, ignore possible errors) 1: resistive load 2: magnetic coil without limit stop 3: magnetic coil with limit stop If switch observation is not supported, the parameter is not used.
  BIDIB_PCFG_MOVE_TYPE	0x10	uint8	Servo motion pattern, motion curve (5) The value consists of 2 nibbles of 4 bits each. Each nibble selects a type of movement, with the low-order nibble (4 LSBs) applies to movements where the target value is greater than the start value. The higher-order nibble (4 MSBs) applies to movements, where the target value is less than the start value. Value range: 0=linear movement 1=Smooth start, smooth end 2=Smooth start, coasting with teetering. 3=Smooth start, coasting with rebound. 4-14=reserved 14=reserved for full user defined 1 15=reserved for full user defined 2 If the node does not support a BIDIB_PCFG_MOVE_TYPE, the default value 0=linear motion is used.
  BIDIB_PCFG_DIMM_UP_8_8	0x43	uint16	Pace for dimming to ON, as steps performed per 10ms (2), range 1…65535 (6)
  BIDIB_PCFG_DIMM_DOWN_8_8	0x44	uint16	Pace for dimming to OFF, as steps performed per 10ms (2), range 1…65535 (6)
  BIDIB_PCFG_TRANSITION_TIME	0x46	uint16	Time for gentle transition between port states, like fading colors or dimming brightness. Unit 10ms, range 0…65535
  BIDIB_PCFG_RGB	0x80	uint24	RGB value of a coloured output: first byte Red, second Green, third Blue
  BIDIB_PCFG_RECONFIG	0x81	uint24	Port Reconfiguration (7)
  BIDIB_PCFG_CONTINUE	0xFF	none	an additional message will follow

  (1)

  If the light control system have a different internal resolution, the values will be converted by the light control system to their own resolution. A possible need for an gamma correction should be calculated by the node itself.

  (2)

  The dimming pace is specified as an increment, i.e. the maximum value 'passes through' the brightness range in one step (no intermediate steps). An step width of 1 controls all possible intermediate steps. The time for one dimming step is 10ms, so times up to 2.5s can be achieved which meets the typical behaviour of light signals.

  (3)

  Channel mapping: By specifying a sequence number, different LIGHT or BACK LIGHT LIGHT ports can be mapped to a common output. This allows for a configuration of different dimming speeds applied on one output.

  (4)

  The values are always specified in the range from 0 to 255 and will be mapped to the servo pulse width range of 0.5ms to 2.5ms.

  (5)

  The motion curves are scaled linearly with the adjustment values ​​of the servo (BIDIB_PCFG_SERVO_ADJ_L and BIDIB_PCFG_SERVO_ADJ_H) and stretched in time. The start and end points are inside the maximum possible range, in order to have some reserve, e.g. for planned overshoots when teetering.

  (6)

  If a node provides dimming times with 16-bit values, then this node can provide slower dimming ramps. This is particularly interesting for an day/night simulation at the layout illumination systems. A Node may either use 8 bit oder 16 bit values for dimming, not both.

  (7)

  The type configuration parameter describes which port types are possible for the respective port, and which type is currently in use. The value consists of 3 Bytes: ACT_TYPE PORTMAP₀ PORTMAP₁. ACT_TYPE denotes the (to be) set port type. PORTMAP announces the available port types as a 16-bit-long bitmap; bit 0 of PORTMAP₀ corresponds to SWITCH, bit 1 to LIGHT and so on. The PORTMAP is ignored when setting the parameter.

  Hints:

  This message obsoletes MSG_LC_CONFIG_SET. Port configuration with 'CONFIGX…' messages is available and mandatory from declared protocol version 0.6 and further.

  P_ENUM = BIDIB_PCFG_NONE is only necessary at the upstream.

  If a node cannot immediately apply the saved parameter values, it should deactivate the respective port; i.e. so that any output or query messages are declined using MSG_LC_NA with the cause BIDIB_ERR_LC_PORT_INACTIVE until the configuration becomes enabled. Additionally the node may detail the reason via MSG_SYS_ERROR, e.g. the need for a reset.

  If a port has more than 8 configuration parameters, an P_ENUM BIDIB_PCFG_CONTINUE is added after the last parameter of the first message; only one answer (consisting of multiple messages) of the node is then expected.

  A host program may only send those P_ENUMs to a node that previously has been reported from this node and this port.

• MSG_LC_CONFIGX_GET:

  Port configuration query. Followed by 2 parameters:

  MSG_LC_CONFIGX_GET parameters

  Parameter	Description
  PORT[2]	These bytes address the port

  Message MSG_LC_CONFIGX_GET will be answered by a MSG_LC_CONFIGX message, while all current values will be received. If a port outside of the available range is selected, the node responds with a MSG_LC_NA message instead.

  Hints:

  This message obsoletes MSG_LC_CONFIG_GET. Port configuration with 'CONFIGX…' messages is available and mandatory from declared protocol version 0.6 and further.

  The response length of an MSG_LC_CONFIGX_GET can be up to 45 bytes, this needs to be considered in the data flow control. Typically, it is necessary to wait for the reply from MSG_LC_CONFIGX_GET before a new requests can be send to this node. MSG_LC_CONFIGX_GET_ALL doesn't have this restriction.

• MSG_LC_CONFIGX_GET_ALL:

  Query of multiple port configurations. Followed by 0 or 4 bytes; those parameters set the requested range.

  MSG_LC_CONFIGX_GET_ALL parameters

  Parameter	Description
  START[2]	These bytes address the first port to be transmitted.
  END[2]	These bytes address the first port to be no more transmitted.

  If the parameters are omitted, START takes the value 0 and END the value 0xFFFF. It is required that START <= END.

  The node returns multiple MSG_LC_CONFIGX messages, one for every port that is present on the node and lies in the range denoted by START and END. The order of the ports must be adhered, the answer messages need to be sequenced by the port address in ascending order.

  Hints:

  Port configuration with 'CONFIGX…' messages is available and mandatory from declared protocol version 0.6 and further.

  This message is destined for quickly reading in the port configuration of a node. The transmission of the answers uses the block transfer capabilities of the transport protocol, with the node adjusting to the available capacity itself. The Host does not need to take any precautions against data flow stalling. The node must be able to receive and respond to other messages while processing the answer sequence.

  The number of answer messages to be expected can be determined using suitable feature queries.

  MSG_LC_CONFIGX_GET_ALL messages are not buffered. When a new MSG_LC_CONFIGX_GET_ALL message is sent to the node during an ongoing transmission, the current sequence is aborted and a new transmission is started.

  Examples:

  A query MSG_LC_CONFIGX_GET_ALL 0, 0, 0xFF, 0xFF returns all ports of a node (just like a query without parameters).

  With the type-based port model in effect, the query MSG_LC_CONFIGX_GET_ALL BIDIB_PORTTYPE_SERVO, 0, BIDIB_PORTTYPE_SERVO+1, 0 returns all servo ports of the node.
  The same result can be obtained with MSG_LC_CONFIGX_GET_ALL BIDIB_PORTTYPE_SERVO, 0, BIDIB_PORTTYPE_SERVO, $SERVO_COUNT (using the memorized number of servos).

• MSG_LC_CONFIG_SET:

  (deprecated, use MSG_LC_CONFIGX_SET instead) Port configuration in terms of its parameters. Followed by 6 parameters:

  MSG_LC_CONFIG_SET parameters

  Parameter	Description
  PORT[2]	These bytes address the port (using the type-based port model)
  DATA[4]	Configuration values

  The configuration values are always given as a uint8 (in the range 0…255). Their meaning depends on the port type, each of them corresponds to a CONFIGX-key-value-pair:

  Typ (PORT0)	DATA0	DATA1	DATA2	DATA3
  Switch output 0 (=BIDIB_PORTTYPE_SWITCH)	Typically, there is no configuration for switch outputs. However, for special applications a configuration may be useful. The feature FEATURE_SWITCH_CONFIG_AVAILABLE defines whether this configuration of switch ports is available. If the feature is missing, configuration is not possible and the switches can only be set.
  	IO-Setup (1)	BIDIB_PCFG_TICKS	reserved	reserved
  Light output 1 (=BIDIB_PORTTYPE_LIGHT)	For light outputs, the minimum / maximum brightness and the dimming speed can be configured. It is possible to additionally slow down the dimming via the feature FEATURE_CTRL_STRETCH_DIMM (if available) up to a factor of 250. The whole transition may last up to 10min and can be used for daylight-night simulations on a layout.
  	BIDIB_PCFG_LEVEL_PORT_OFF	BIDIB_PCFG_LEVEL_PORT_ON	BIDIB_PCFG_DIMM_DOWN	BIDIB_PCFG_DIMM_UP
  Servo output 2 (=BIDIB_PORTTYPE_SERVO)	For servo outputs, the lower and upper limits and the turnaround speed of the servo are adjustable.
  	BIDIB_PCFG_SERVO_ADJ_L	BIDIB_PCFG_SERVO_ADJ_H	BIDIB_PCFG_SERVO_SPEED	reserved
  Light output 6 (=BIDIB_OUTTYPE_BACKLIGHT)	For light outputs with directly settable brightness a channel mapping for the assignment to actual hardware and the dimming speed can be configured.
  	BIDIB_PCFG_DIMM_DOWN	BIDIB_PCFG_DIMM_UP	BIDIB_PCFG_OUTPUT_MAP	reserved
  3, 4, 5, …	Detailed definitions for sound, motor and analogue voltage outputs will follow.

  Reserved values are coded with 0.

  (1)

  IO behaviour:

  • 0=output (direct controlled) (default setting),
  • 1=High pulse (if turned on (1), the output will go off (0) alone after the given time S).
  • 2=Low pulse (if turned off (0), the output will go on (1) alone after the given time S).
  • 3=Tristate (high Z)
  • 4=Input, pullup.
  • 5=Input, pulldown.

  The node stores this parameters and responds with a MSG_LC_CONFIG message. If an non existing port (outside of the available range) is selected, the node responds with a MSG_LC_NA message instead.

• MSG_LC_CONFIG_GET:

  (deprecated) Query of a port in terms of its parameters. Followed by 2 parameters:

  MSG_LC_CONFIG_GET parameters

  Parameter	Description
  PORT[2]	These bytes address the port

  If a port outside of the available range is selected, the node responds with a MSG_LC_NA message instead of MSG_LC_CONFIG.

4.6.8. Uplink: Messages for peripheral / switching functions.

• MSG_LC_NA:

  This port message is sent in exceptional cases. It might occur when switching or configuring an output errors, or when the end of a QUERY_ALL transmission is reached. Followed by 2 or 3 bytes stating the port and an error cause.

  MSG_LC_NA parameters

  Parameter	Description
  PORT[2]	These bytes address the port. Port 0xFFFF signals the completion of a transmission of multiple ports.
  ERRCAUSE[0…1]	Optional for cause of the exception

  Encoding of error causes

  Value	Name	Meaning
  0	reserved	(internal use in nodes or host programs)
  1	BIDIB_ERR_LC_PORT_GENERAL	(or when omitted) Error cause not detailed
  2	BIDIB_ERR_LC_PORT_UNKNOWN	Port is unknown and not usable. The addressed port or type does not exist on this node. This problem is not salvageable. Example: A node announces only 16 ports via its features, but port 20 is addressed.
  3	BIDIB_ERR_LC_PORT_INACTIVE	Port is currently unusable because of the node configuration. It is deactivated, not available for the requested action. This error can be averted through a reconfiguration. Example 1: Assuming the flat port model, port 0 can be configured as either SWITCH or SWITCHPAIR, but blocks port 1 in the second case. Port 1 then responds to commands with BIDIB_ERR_LC_PORT_INACTIVE. Example 2: A port has been configured with incompatible (but on its own valid) parameters, or a parameter change is not yet effective until a reboot. Meanwhile, it declines switching commands.
  4	BIDIB_ERR_LC_PORT_EXEC	Execution of operation impossible. Examples: A SWITCH port receives a command with PORTSTAT 5. Or an output port in the flat port model is getting a MSG_LC_KEY_QUERY request.
  5…254		reserved
  255	BIDIB_ERR_LC_PORT_BROKEN	Problem with hardware. This message is dedicated for the announced port. More precise reports on the cause (like internal exception, power supply, etc) may be sent through the generic error messages.

  Hint:

  A host program should show the cause when the ERRCAUSE parameter exists. When the value is unknown, the plain number should be shown.

• MSG_LC_STAT:

  This message transmits the current state of a port. Followed by 3 bytes: PORT₀, PORT₁, PORTSTAT.

  For outputs, it is sent as the answer to a query or as the acknowledgement to an operation command when the output reaches the desired state. If the output has more than 100 ms switching time, a MSG_LC_WAIT message is sent back immediately after receiving the MSG_LC_OUTPUT.

  For inputs, it is sent as the answer to a query or also spontaneously when the condition of the port changes while the node is enabled and has the FEATURE_CTRL_INPUT_NOTIFY set.

  MSG_LC_STAT parameters

  Parameter	Description
  PORT[2]	These bytes address the port
  PORTSTAT	Depending on the port type: output status, coded like for MSG_LC_OUTPUT, or input status: 0: inactive (open). 1: active (closed). (Usually switches/push buttons are connected to ground, they will pull the processor input to low if the key is closed/pressed (=active low). This can be configured differently through PCFG_INPUT_CTRL if available.)

  Hint:

  This message is supposed to allow the host to access the node-internal port states, e.g. for displaying them appropriately. However, the transmission is not specially secured with acknowledgements or message repetition. Where this is required, accessories or detectors should be used.

• MSG_LC_WAIT:

  This message is sent as an immediate acknowledgement when the output reaches its requested state only after a time of 100ms or more.

  Followed by 3 bytes: PORT₀, PORT₁, TIME.

  MSG_LC_WAIT parameters

  Parameter	Description
  PORT[2]	These bytes address the port
  TIME	Predicted rotation time. This rotation time is coded analogously to the railcom specification as follows: The lower 7 bits of the remaining running time indicates the running time until the end-status of the requested switching action (predicted rotation time). Depending on the MSB, the time is specified in units of 1/10 seconds (MSB = 0), or 1 second (MSB = 1). A time of 0 means: no switching time can be determined. This results in a value range from 0…12,7 seconds or 0…127 seconds.

• MSG_LC_KEY:

  (deprecated, from declared protocol version 0.7 only MSG_LC_STAT is used)

  This message is sent when the node contains local buttons and these have been pressed or when an explicit request was made. This message occurs spontaneously (MSG_SYS_ENABLE and the corresponding feature must be set) and will not be repeated. Followed by 2 bytes: PORT, KSTATE.

  MSG_LC_KEY parameters

  Parameter	Description
  PORT	Button number. Corresponds to PORT0 in the flat port model and to PORTNUM in the type-based one (with PTYPE=15).
  KSTATE	Status of the button: 0: not pressed. 1: pressed.

• MSG_LC_CONFIGX:

  Messages of a port concerning his parameters. Followed by 4 or up to an maximum of 43 parameter bytes.

  MSG_LC_CONFIGX parameters

  Parameter	Description
  PORT[2]	These bytes address the port
  DATA[2…42]	List with 1 to 8 key-value pairs, consisting of parameter type and value. Their encoding corresponds to the MSG_LC_CONFIGX_SET message.

  Hints:

  This message obsoletes MSG_LC_CONFIG. Port configuration with 'CONFIGX…' messages is available and mandatory from declared protocol version 0.6 and further.

  If a port has more than 8 configuration parameters, an P_ENUM BIDIB_PCFG_CONTINUE is added after the last parameter of the first message. This informs the host program about an transmission of an additional MSG_LC_CONFIGX message.

  P_ENUM = BIDIB_PCFG_RECONFIG is only needed when the flat port model is used. It always has to sent in the upstream to announce the active port type to the host – even when the node does not support reconfigurations and the current type is the only available one.

• MSG_LC_CONFIG:

  (deprecated) This message is sent after a configuration or after a query using MSG_LC_CONFIG_GET.

  Followed by 6 parameters, order and coding is equal to MSG_LC_CONFIG_SET.

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.

4.6.10. Features for local macros

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

4.6.11. Downlink: Messages for local macros

There are the following commands to create and manage macros:

• MSG_LC_MACRO_HANDLE:

  Followed by 2 bytes: macro index, operation code. The respective operation will be answered with a MSG_LC_MACRO_STATE.

  Encoding of macro operation code

  Value	Name	Meaning
  0	BIDIB_MACRO_OFF	Macro should be canceled.
  1	BIDIB_MACRO_START	Macro should be started.
  2…0xFB		reserved.
  0xFC (=252)	BIDIB_MACRO_RESTORE	Restore. The defined macro will be loaded from the flash memory (if available, this can be verified by a features query) and overwrites the currently loaded macro. If no permanent memory is available, the macros will be deleted. (same as BIDIB_MACRO_DELETE).
  0xFD (=253)	BIDIB_MACRO_SAVE	Save. The defined macro will be saved into the flash memory (if available, this can be verified by a features query) and is again available after system restart.
  0xFE (=254)	BIDIB_MACRO_DELETE	Deletion of a macro. The contents of the specified macro will be deleted. This operation is identical with the set of all(!) switching states to 255, 255 (END_OF_MACRO). A following command BIDIB_MACRO_SAVE will also delete the content in flash memory.

  Hint:

  Saving a macro can take some time in the node. Depending on the implementation of this node, the node might be not able to answer on request at this time. It is therefore necessary to wait for the confirmation of this command before sending any other commands.

• MSG_LC_MACRO_SET:

  Setting a macro switch point, this defines an individual macro point. Followed by 6 parameters:

  MSG_LC_MACRO_SET parameters

  Parameter	Description
  DATA0	Macro index
  DATA1	Index of the point within the macro
  DATA2	DELAY: delay time in relation to the previous point. Value range 0…250	SYS_TYPE: undelayed invocation of a system function. Value range 251…255
  DATA3	PORT[2]: These bytes address the port	SYS_CMD: System function, e.g. the end of an macro
  DATA4		SYS_ARG[2]: Arguments for the system function. Bytes not used by the respective function are coded with 0, they will be transferred but not evaluated.
  DATA5	PORTSTAT: Switching status according to the table at MSG_LC_OUTPUT

  Setting a macro switch point is answered with a MSG_LC_MACRO message. If a configured port outside of the available port range, the macro is terminated at execution at this point.

  The end of an macro is signaled through setting all parameters to 255, or when the available memory for macros is full.

  DELAY, Delay time: The number which is specified at this point is the time, relative to the previous macro point. A time of 0 means no time gap between the actions (although they are usually executed one after the other because of physical reasons). The time specified here is the number of MAKRO_TICKs, which pass until the command will be executed. The valid range is 0…250.

  The actual waiting time is given by this number, multiplied with the macro execution speed. Times from 20 ms up to over 20 min can be realized in this way.

  For Level 2 macros, the following system functions are defined in the following table (for delay = 255):

  Encoding of system functions for DELAY=255 (macro level 2)

  Value	Name	Function
  255	BIDIB_MSYS_END_OF_MACRO	The macro will be terminated.
  254	BIDIB_MSYS_START_MACRO	The macro specified in SYS_ARG0 will be started. This may also be the current macro, it will start again.
  253	BIDIB_MSYS_STOP_MACRO	The macro specified in SYS_ARG0 will be stopped. "Stop" here means end, not pause. If the target macro is in a critical section, the stop request is executed after the critical section.
  252	BIDIB_MSYS_BEGIN_CRITCAL	The macro is not stopped by a stop request, the current sequence has to be completed (until END_CRITICAL). Example: The motion of an mechanical object can't be stopped on 'halfway'.
  251	BIDIB_MSYS_END_CRITCAL	The macro can be stopped by a stop request (default)
  250	BIDIB_MSYS_FLAG_QUERY1	The flag specified in SYS_ARG0 is queried. If it's not set, the macro execution is paused until the flag (e.g. by another macro) is set.
  249	BIDIB_MSYS_FLAG_SET	The flag specified in SYS_ARG0 will be set. Value range: 0…15
  248	BIDIB_MSYS_FLAG_CLEAR	The flag specified in SYS_ARG0 will be unset. Value range: 0…15
  247	BIDIB_MSYS_INPUT_QUERY1	The input or switch specified in SYS_ARG is queried like with MSG_LC_PORT_QUERY. For the flat port model, the port address is given, for the type-based one only the PORTNUM is coded in SYS_ARG0 (with PTYPE=15). If the switch is open (PORTSTATE=0), the macro execution is paused; when the switch is closed (PORTSTATE=1), the macro execution continues.
  246	BIDIB_MSYS_INPUT_QUERY0	The input or switch specified in SYS_ARG is queried like with MSG_LC_PORT_QUERY. For the flat port model, the port address is given, for the type-based one only the PORTNUM is coded in SYS_ARG0 (with PTYPE=15). If the switch is closed (PORTSTATE=1), the macro execution is paused; when the switch is open (PORTSTATE=0), the macro execution continues.
  245	BIDIB_MSYS_DELAY_RANDOM	The macro execution is delayed by a random time. The time span is randomly chosen from an interval of 0…SYS_ARG0 MACRO_TICKS on every invocation. This for example allows realistic sequences of building lights.
  244	BIDIB_MSYS_DELAY_FIXED	The macro execution is delayed by a fixed time from 0 to 255 MACRO_TICKS. The time is specified at the SYS_ARG0 field.
  243	BIDIB_MSYS_ACC_OKAY_QIN1	The input or switch specified in SYS_ARG is queried like with MSG_LC_PORT_QUERY. For the flat port model, the port address is given, for the type-based one only the PORTNUM is coded in SYS_ARG0 (with PTYPE=15). If the switch is closed (PORTSTATE=1), the associated accessory will get a notify 'position reached and verified by feedback'. If the switch is open (PORTSTATE=0), a feedback error will be reported.
  242	BIDIB_MSYS_ACC_OKAY_QIN0	The input or switch specified in SYS_ARG is queried like with MSG_LC_PORT_QUERY. For the flat port model, the port address is given, for the type-based one only the PORTNUM is coded in SYS_ARG0 (with PTYPE=15). If the switch is open (PORTSTATE=0), the associated accessory will get a notify 'position reached and verified by feedback'. If the switch is closed (PORTSTATE=1), a feedback error will be reported.
  241	BIDIB_MSYS_ACC_OKAY_NF	The associated accessory will get a notify 'position reached' (with the additional info: no Feedback available).
  240	BIDIB_MSYS_SERVOMOVE_QUERY	The servo specified in SYS_ARG is queried. For the flat port model, the port address is given, for the type-based one only the PORTNUM is coded in SYS_ARG0 (with PTYPE=2). If the servo is still moving, the macro execution is paused. If the movement is finished, the macro execution will continue.
  239	BIDIB_MSYS_FLAG_QUERY0	The flag specified in SYS_ARG0 is queried for value 0. If the flag is set, the macro execution is paused until the flag (e.g. by another macro) is cleared.

• MSG_LC_MACRO_GET:

  Query of an macro point, followed by 2 bytes with macro index and switchpoint index. This query will be answered with an MSG_LC_MACRO message.

  MSG_LC_MACRO_GET parameters

  Parameter	Description
  DATA0	Index of the macro in which the switching point is queried.
  DATA1	Index of the switching point within the macro.

  The indices will be counted from 0.

• MSG_LC_MACRO_PARA_SET:

  Puts a general parameter for a macro, this defines the execution parameters of the macro: Macrospeed, execution mode (e.g. repetitive), start condition and so on. Followed by 6 parameters:

  MSG_LC_MACRO_SET_PARA parameters

  Parameter	Description
  DATA0	Macro index
  DATA1	Parameter index
  DATA2	Parameter value (LSB)
  DATA3	Parameter value
  DATA4	Parameter value
  DATA5	Parameter value (MSB)

  Setting of an macro parameter is answered with a MSG_LC_MACRO_PARA message.

  Index values of the parameters:

  Encoding of macro configuration parameters

  Value	Name	Meaning
  1	BIDIB_MACRO_PARA_SLOWDOWN	Speed of the macro. The processing speed will be defined. with this value. The base unit is 20ms. Value range: 1…250 Default setting: 1. Example: At a setting of 5, the macro switchs every 100ms to the next macro tick. So if then 2 is specified in the macro list, this means a time interval of 200ms between the actions in total.
  2	BIDIB_MACRO_PARA_REPEAT	Repetitions of the macro. The macro is repeated as often as indicated here. If this value is set to 0, then the macro will be repeated continuously. Value range: 0…250 Default setting: 1, this means, the macro will be executed one time.
  3	BIDIB_MACRO_PARA_START_CLK	Enable macro start by system clock. DATA2 until DATA5 contains the time as TCODE (see also the explanations at the MSG_SYS_CLOCK command). In addition to the start at a particular model-time, there is also the possibility to define repetitive macro starts, e.g. every hour, or every day at the same hour. This is achieved by specifying a TCODEs which can not be contained in a normal time message. Such TCODEs are trigger conditions, similar to a 'wildcard' and they will be fulfilled at several time points: TCODEx Description 00mmmmmm mmmmmm = Specification of minute: 0…59: defined start time 60: Start every minute 61: Start every half hour (this means at 0,30) 62: Start every quarter hour (this means at 0,15,30,45) 100HHHHH HHHHH = Specification of hour: 0…23: defined start time 24: Start every hour 25: Start every hour, 8:00 until 17:00 01000www www = Week day, 0=Monday, 1=Tuesday, … 6=Sunday. 7: Start every day 110fffff fffff = Clock acceleration factor (not relevant for macro). A macro always starts when the node detects a match at minute, hour and day. If the start should prevented via TCODE, all trigger conditions have to be set to void, i.e. for min/hr/day the data value 0x3F must be specified. So if the trigger must be switched off completely, then 0x3f, 0xbf, 0x7f, 0xff needs to be transmitted. Default setting: 0x3f, 0xbf, 0x7f, 0xff (=off) Examples: TCODE = (0x00 + 15), (0x80 + 24), (0x40 + 7): One start every day, every hour, always at minute 15. TCODE = (0x00 + 00), (0x80 + 18), (0x40 + 7): One start every day at 18:00
  tbd.	tbd.	Enable macrostart via DCC-switch command.
  tbd.	tbd.	Enable macrostart via external input.

  If a node is able to store macros permanently, the macro parameters must be also stored during this process.

• MSG_LC_MACRO_PARA_GET:

  Query of an makro parameter, followed by 2 bytes with macro index und parameter index. This query will be answered with a MSG_LC_MACRO_PARA message.

4.6.12. Uplink: Messages for local macros

• MSG_LC_MACRO_STATE:

  The message is sent as an acknowledgement after the change of state (operation) of a macro. followed by 2 bytes with macro index and status.

  Encoding of macro status

  Value	Name	Meaning
  0	BIDIB_MACRO_OFF	Macro is halted
  1	BIDIB_MACRO_START	Macro will be started
  2	BIDIB_MACRO_RUNNING	Macro is already running
  252	BIDIB_MACRO_RESTORE	Macro has been restored
  253	BIDIB_MACRO_SAVE	Macro has been saved
  254	BIDIB_MACRO_DELETE	Macro has been erased
  255	BIDIB_MACRO_NOTEXIST	Macro is not existing (Macro index to large during call;)

• MSG_LC_MACRO:

  Transmission of a requested macro point, followed by 6 bytes with macro index and switchpoint index and the content of this point. The coding is identical to MSG_LC_MACRO_SET.

• MSG_LC_MACRO_PARA:

  Transmission of a requested macro parameter, followed by 6 bytes with macro index, parameter index and parameter value (data). If the parameter does not exist in the node, then the value 0xFF will be returned for all data bytes.

  MSG_LC_MACRO_PARA parameters

  Parameter	Description
  DATA0	Macro index
  DATA1	Parameter index
  DATA2	Parameter value(LSB)
  DATA3	Parameter value
  DATA4	Parameter value
  DATA5	Parameter value (MSB)

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

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.

• MSG_BM_GET_RANGE:

  This command queries the status of all occupancy detectors in a certain range. Followed by 2 bytes: START, END, which indicate the occupancy bits to transfer.

  The feedback system responds with a MSG_BM_MULTIPLE message, containing all occupancy states from START to (exclusive) END.

  Hints:

  START- and END-values that don't fit to byte boundaries should be rounded down and up respectively.

  An error response is sent if START is outside of the range of available detectors. If END is outside of the range, the response is limited to the available detectors.

  Up to and including specification revision 1.27, START and END values had to be divisible by 8. Host programs should continue to guarantee this.

• MSG_BM_MIRROR_OCC:

  With this command, a single occupancy status is transmitted back to the detector. With activated Secure-ACK, this single occupancy message is transmitted again by the detector, if the state of the detector does not match with the mirror message. If Secure-ACK is not enabled, the detector must ignore this message.

  A single byte with the local detector address (MNUM) is following, like in MSG_BM_OCC.

• MSG_BM_MIRROR_FREE:

  This command returns a single free status back to the detector. With activated Secure-ACK, this single free message is transmitted again by the detector, if the state of the detector does not match with the mirror message. If Secure-ACK is not enabled, the detector must ignore this message.

  A single byte with the local detector address (MNUM) is following, like in MSG_BM_FREE.

• MSG_BM_MIRROR_MULTIPLE:

  With this command, the occupancy states will be transmitted back to the detector byte by byte. With activated Secure-ACK handshake, incorrectly transmitted occupancy states messages will be transmitted again by the detector. If Secure-ACK is not enabled, the detector must ignore this message, if Secure-ACK is activated, the response takes place immediately (with MSG_BM_MULTIPLE).

  Details of base address of this section and length of the message and as well the occupancy states will follow, like in MSG_BM_MULTIPLE.

  Note:

  The acknowledgement should be done bytewise only if the occupancy report was transmitted bytewise. The reason for this is the real-time behaviour: Assuming the occupancy detector transmits multiple bits very rapidly as single messages MSG_BM_OCC / MSG_BM_FREE. If the host would acknowledge the first message by sending back a whole byte in which only a part of the occupancy bits are correct, he would once again get a MSG_BM_MULTIPLE with the correct vector from the occupancy detector node. This would also happen for all the following messages that are still in the queue.

• MSG_BM_GET_CONFIDENCE:

  No parameters following.

  The current 'quality' of the occupancy detection is requested, the node responds with MSG_BM_CONFIDENCE.

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:

• MSG_BM_OCC:

  A single occupancy report (change notification); A byte with the local detector address (MNUM) and optionally two bytes with a BiDiB system timestamp (TIME_L, TIME_H) are following.

  When the FEATURE_BM_TIMESTAMP_ON is enabled and the detector has a valid system time available, it provides a timestamp for the moment of the sensor activation. If this could not be determined precisely, the timestamp should be omitted.

  Hint: the system time is synchronised on the BiDiBus via MSG_LOCAL_SYNC messages in intervals of up to 32 s. A detector needs to have a clock accuracy better than 30ppm to drift off at most 1 ms in this period. If it has a higher inaccuracy (e.g. with an RC oscillator), it must not employ this feature.

  When the FEATURE_BM_SECACK_ON is enabled, the host immediately has to transmit a MSG_BM_MIRROR_OCC for the same section back to the detector. Until this acknowledgement has arrived, the message will be repeated in the set interval multiple times. The event timestamp may be omitted therein if it is no longer available. To avoid flooding the host, the number of repetitions has to be limited; longer outages are handled by the bus interface. If there is still no acknowledgement present by then, an error message with the code BIDIB_ERR_NO_SECACK_BY_HOST is sent.

  Also no vacancy reports for the section should be sent until the occupancy report has been acknowledged; this is especially important for point detectors with short activation times.

• MSG_BM_FREE:

  A single vacancy report (change notification); A byte with the local detector address is following (MNUM). If a track is reported as free, any reported loco addresses on this section will implicitly be voided.

  When the FEATURE_BM_SECACK_ON is enabled, the host immediately has to transmit a MSG_BM_MIRROR_FREE for the same section back to the detector. Until this acknowledgement has arrived, the message will be repeated in the set interval multiple times. To avoid flooding the host, the number of repetitions has to be limited; longer outages are handled by the bus interface. If there is still no acknowledgement present by then, an error message with the code BIDIB_ERR_NO_SECACK_BY_HOST is sent.

• MSG_BM_MULTIPLE:

  This message transmits occupied/free messages of an entire, contiguous range of detector addresses. Base address of this area and the number of messages and the occupancy data itself is following.

  MSG_BM_MULTIPLE parameters

  Parameter	Description
  MNUM	Base address of the reported track section (same like MSG_BM_OCC), this must be an integer multiple of 8.
  SIZE	Number of reported bits, value range 8… 128. Size also takes only multiples of 8.
  DATA[1…16]	Detector data. The LSB of the first byte corresponds to the base address and the MSB of the first byte to the base address + 7, the LSB of the second byte corresponds to the base address + 8 and so on. A set bit indicates an occupied section, an unset bit a vacant one. In case the count of detectors (FEATURE_BM_SIZE) is not a multiple of 8, the end is padded with 0 bits.

  This message is specifically used in the initialization phase or after a protocol error for rapid importing of the occupancy states.

  When the FEATURE_BM_SECACK_ON is enabled, the host immediately has to transmit a MSG_BM_MIRROR_MULTIPLE with the same content back to the detector. Until this acknowledgement has arrived, the message will be repeated in the set interval multiple times. To avoid flooding the host, the number of repetitions has to be limited; longer outages are handled by the bus interface. If there is still no acknowledgement present by then, an error message with the code BIDIB_ERR_NO_SECACK_BY_HOST is sent.

• MSG_BM_CONFIDENCE:

  This message transmits information about the 'reliability' of the current occupancy detection, followed by 3 bytes which describe the status. Depending on the condition of the track signal, the detection of track occupancy can be affected: For example, during a short circuit of the track signal there might be only a 'frozen' or not any valid occupancy detection possible (depending on the internal circuitry).

  If the track power or the whole detection system fails, the appropriate CONFIDENCE-message must be sent before any other occupancy or address messages, so that the host program will be able to interpret them in the right context.

  If the confidence status has changed, the information about loco speed and the possibly derived loco localization might be outdated in some cases.

  MSG_BM_CONFIDENCE parameters

  Parameter	Description
  VOID	0: The occupancy report is derived from the actual situation on the track. <>0: The reported occupancy is invalid, a detection is currently not possible.
  FREEZE	0: The occupancy detection is based on the input track signal or an alternative method of the detector. <>0: The occupancy detection is not up-to-date, but rather the memorized state of an previous situation.
  NOSIGNAL	0: The occupancy detection has been made with a valid input signal (i.e. track signal is present). <>0: A valid input signal from the booster is missing.

  These bytes encode some kind of 'alert levels':

  • ¬VOID ∧ ¬FREEZE ∧ ¬NOSIGNAL: the occupancy detection result is completely OK.
  • ¬VOID ∧ ¬FREEZE ∧ NOSIGNAL: the detection was done using a substitution measurement method (with less accuracy, especially in case of a short circuit), the track signal is missing.
  • ¬VOID ∧ FREEZE ∧ NOSIGNAL: the occupancy report contains a frozen state from before the track signal went off. The occupancy detector will not send any spontaneous messages in this state, though queries are still possible.
  • VOID ∧ ¬FREEZE ∧ NOSIGNAL: there are no occupancy results (yet) from a detection (e.g. right after startup), there is no track signal. The occupancy detector will not send any spontaneous messages in this state, queries are useless.

  Note: With this message it is possible even without booster monitoring to recognise a booster outage, which might be caused by a short circuit, emergency stop or hardware failure.

  It is allowed that a detector module has up to 8 detection areas, in this case, the respective bit VOID, FREEZE and NOSIGNAL should be set in each area. If the detector module provides only one detection area, the LSB must be set, for 2 detection areas, the two lower bits, and so on. Host software does not necessarily need to distinguish between the areas, it can simply extend the scope of the message to the whole node.

  If spontaneous occupancy reporting is enabled, then also changes of the confidence status of the detector will cause spontaneous messages. If a detector has multiple detection areas (which possibly change their state at the same time), the summarisation of temporally close status changes into a single message should already be made within the node.

• MSG_BM_CURRENT:

  Current-message, followed by 2 bytes: MNUM, CURRENT

  MSG_BM_CURRENT parameters

  Parameter	Description
  MNUM	local address of the detector
  CURRENT	Current consumption Encoding of current values Value Meaning 0 no power consumption, track is empty. 1…15 power consumption, in mA. possible range: 1…15mA 16…63 power consumption, value is (date - 12) * 4mA. possible range: 16…204mA 64…127 power consumption, value is (date - 51) * 16mA. possible range: 208…1216mA 128…191 power consumption, value is (date - 108) * 64mA. possible range: 1280…5312mA 192…250 power consumption, value is (date - 171) * 256mA. possible range: 5376…20224mA 251…253 reserved. 254 Overcurrent occurred. 0xFF Only occupancy detection, accurate power consumption unknown.

  MSG_BM_CURRENT is only reported spontaneously and can not be queried. The transmission can be switched on or off by setting the feature FEATURE_BM_CURMEAS_INTERVAL.

4.7.5. Features for bidi detectors

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

(1)

Address data is available when Railcom is enabled in the loco decoder (CV 28).

(2)

Local detectors typically generate more stable detection results for loco feedback and should be preferred. Global dectors are suitable for boosters that supply only a single track (without further occupancy sensors) or only stationary decoders.

4.7.6. Downlink: Messages for bidi detectors

• MSG_BM_ADDR_GET_RANGE:

  Followed by 2 bytes: START, END;

  With this command, the recognized loco addresses will be retransmitted from index START to index END-1. There are a number of (individual) address messages (MSG_BM_ADDRESS). If a section does not contain a loco address, it will be reported with address 0.

  If a section does not exist on the detector, nothing will be transferred. A global detektor can be queried with START=255 and optionally ENDE=0.

  The message is only available when the FEATURE_BM_ADDR_DETECT_ON is set.

• MSG_BM_MIRROR_POSITION:

  With this command, a position report of a decoder will be transmitted back to the detector. When the Secure-ACK handshake is enabled (FEATURE_BM_POSITION_SECACK), the decoder's last position report will be transmitted again if the most recent location for the decoder that is known to the detector does not match the mirrored one.

  If no position information about the decoder is available to the detector, or when Secure-ACK is disabled, the detector will ignore this message.

  Followed by five bytes with the decoder address and location identifier, coded like in MSG_BM_POSITION.

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:

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:

• MSG_BM_ADDRESS:

  With this message, the detection of a loco in a particular section will be reported.

  Followed by 3 or more bytes: MNUM, ADDR_L, ADDR_H, [ADDR_L, ADDR_H], ...

  If only one decoder is present in the section, there is a 3 byte message. If more than one decoder is present in the section, the addresses of the decoder will be transferred in the following byte pairs ADDR_L, ADDR_H. A maximum of 16 addresses can be reported in one section. This limit also applies to global detectors, address detection at those is intended only for small setups (e.g. a programming track).

  MSG_BM_ADDRESS parameters

  Parameter	Description
  MNUM	Local number of the occupancy detector. Value range 0…127
  ADDR[2][1…16]	Addresses of the loco or accessory decoders. Value range is based on the DCC address range, coded as described above

  Information about the behaviour of the node:

  If an address notification is done, and the decoder in this section can't be detected any more, then the node report a MSG_BM_ADDRESS with address 0.

  In case a single decoder out of multiple decoders on this section can't be detected any more, then the node report a MSG_BM_ADDRESS with the remaining addresses.

  When no occupancy is reported on a section (e.g. via MSG_BM_FREE), all address reports are implicitly revoked.

• MSG_BM_ACCESSORY:

  (to be revised)

  With this message, the feedback of an accessory decoder is reported.

• MSG_BM_CV:

  CV-message, followed by 5 bytes: ADDR_L, ADDR_H, CV_L, CV_H, DAT

  MSG_BM_CV parameters

  Parameter	Description
  ADDR[2]	Address of the sending decoder, coded as described above
  CV[2]	CV, value range 0…1023; 0 corresponds to CV1
  DAT	The read datum.

  Hints:

  A node should filter multiple POM answers from a decoder and send only one MSG_BM_CV to the host for each different CV and data content. However, it still may happen that one POM access generates more than one MSG_BM_CV (e.g. when a loco bridges two different detectors).

  POM messages may be triggered by other points of operating (like throttles), a pc program must be aware of unexpected messages.

  If the feedback system is not able to recognize the loco address, then the address field for the loco address must be transmitted with 0xFFFF. The procedure is similar with the CV-address, 0xFFFF will be transmitted instead of the correct CV-address. (This is only a stopgap solution to support extremely simple PoM-feedback assemblies and definitely not recommended!)

• MSG_BM_XPOM:

  CV-message from a POM operation, followed by 10 to 13 bytes: ADDR_L/DID₀, ADDR_H/DID₁, 0/DID₂, 0/DID₃, 0/VID, OPCODE, CV_L, CV_H, CV_X, DATA[1…4]

  These parameters are coded like in MSG_CS_POM, except for the loco address which is coded as described above containing the direction.

  Hint:

  XPOM block read operations are provided with a sequence ID from the command station. The feedback system must match the feedback response to the DCC command by using this sequence ID and it must assign the fields for decoder ID and CV appropriately.

• MSG_BM_SPEED:

  Speed-message, followed by 4 bytes: ADDR_L, ADDR_H, SPEED_L, SPEED_H

  MSG_BM_SPEED parameters

  Parameter	Description
  ADDR[2]	Address of the reporting decoder, coded as described above
  SPEED[2]	Speed in km/h, lowbyte will be transferred first

  FEATURE_BM_ISTSPEED_INTERVAL determines how often the transmission takes place. A setting of at least 200ms is recommended. The bidi detector should average speed messages if they are arriving more frequent than the transmission rate setting. If there is no velocity change, the bidi detector should not transmit anything, this applies especially at zero speed.

  The MSG_BM_SPEED should only be done once per decoder, even if the decoder is currently bridging different sections and therefore recorded in these sections at the same time.

  MSG_BM_SPEED is only reported spontaneously and can not be queried. The transmission can be switched on or off by setting the feature FEATURE_BM_ISTSPEED_INTERVAL.

  MSG_BM_SPEED messages with an address field specifying an extended accessory decoder are sent from stationary measurement devices.

• MSG_BM_DYN_STATE:

  Status message of an decoder followed by 5 or more bytes, beginning with MNUM, ADDR_L, ADDR_H, DYN_NUM.

  MSG_BM_DYN_STATE parameters

  Parameter	Description
  MNUM	Local number of the occupancy detector, value range 0…127; 255
  ADDR[2]	Address type of the reporting decoder, coded as described above
  DYN_NUM	Indentifier of the transmitted state. 0: reserved 1: Signal quality 2: Temperature 3: Container 1 4: Container 2 5: Container 3 6-255: reserved
  VALUE[1…N]	State value, one byte unless specified otherwise. Dyn-num Encoding of value 0: reserved 1: Signal quality, value range 0…100 The ratio of incorrect received packets to total received packets in percent is transmitted. Value 0 means error-free reception (from decoder side). 2: Temperature (signed char). Value Description 0…127 Temperature in degree Celsius units. 128…225 reserved. 226…255 negative temperature (-30°C…-1°C). 3: (Operation-) Energy storage, value range 0…100 Fill level indication of container 1; Driving power (e.g. battery level) 4: Container 2 5: Container 3 6: Distance, consisting of 4 bytes: DISTANCEL, DISTANCEH, TIMEL, TIMEH. DISTANCE indicates the covered distance of a vehicle as measured in mm. The mileage is recorded as a circular counted 16-bit value (overflowing from 65535 to 0). The counter increments if the vehicle is driving forward (towards smokebox door or driver's cab 1). TIME is a system timestamp for the reception of the message from the decoder. 7-255: reserved

  FEATURE_BM_DYN_STATE_INTERVAL sets how frequently the transfer is made (in units of 100ms). A setting of at least 1s is recommended. FEATURE_BM_DYN_STATE_INTERVAL = 0 disables the transmission. The occupancy detector should not transmit status messages from locomotive decoders if they arrive before an expiration of FEATURE_BM_DYN_STATE_INTERVAL.

  MSG_BM_DYN_STATE should take place only once for each (locomotive) decoder, even if this decoder is present in multiple occupancy sections.

  MSG_BM_DYN_STATE is only reported spontaneously and can not be queried. The transmission can be switched on or off by setting the feature FEATURE_BM_DYN_STATE_INTERVAL.

• MSG_BM_RCPLUS:

  Reporting a decoder in the RailcomPlus logon process. A bidi detector sends this message when feedback of one or multiple decoders in an occupancy section was recognised.

  Followed by two or more bytes: MNUM OPCODE DECVID DECUID[4]

  MSG_BM_RCPLUS parameters

  Parameter	Description
  MNUM	local address of the track section, value range 0…127; 255
  OPCODE	Classification of the feedback, see below
  DEC_MUN[4]	Serial number of the decoder. These four bytes (Manufacturer Unique Number) and the DEC_MID constitute the decoder unique ID (DID).
  DEC_MID	Manufacturer/Vendor ID of the decoder

  Encoding of opcode for RailcomPlus detection

  Value				Meaning
  	T	C	P
  RC_PONG	LOCO	OKAY	0	A PING or FIND packet was responded to by exactly one decoder. T states whether a loco or acccessory decoder did respond. C states whether the decoder already knowns the CID of the current system; if no then further inquiries might be necessary, especially a check of the address. P states the orientation of the decoder on the track. Followed by another 5 bytes with the DID of the responding decoder.
  			1
  		NEW	0
  			1
  	ACCESSORY	OKAY	0
  			1
  		NEW	0
  			1
  RC_PING_COLLISION			0	A PING packet was simultaneously responded to by multiple decoders. The response is not collision-free and faulty.
  			1
  RC_FIND_COLLISION			0	A FIND packet was simultaneously responded to by multiple decoders. The response is not collision-free and faulty. Followed by another 5 bytes with the DID of the search command to which was responded.
  			1
  RC_BIND_ACCEPTED	LOCO			A BIND packet was confirmed by the decoder. It is now addressable under the assigned address. Followed by another 7 bytes with the DID of the confirming decoder and the assigned address which is coded as described above to ease the construction of an assignment table in the host.
  	ACCESSORY

  Hints:

  BIND, FIND and PING packets are repeated multiple times back-to-back by the track output device. A detector system may only send a single reporting message per track section.

  PING packets are cyclically repeated by the track output device (in an interval of about 1…2s). A detector system may only send a respective BM_RCPLUS message when the content of the PONG response is different from the previous feedback.

  For FIND packets, the detectors system has to send a BM_RCPLUS message when the content of the FIND has changed (new search range) or when the response(s) of the decoder (PONG) are different from the previous feedback.

• MSG_BM_POSITION:

  Position report. Followed by five bytes: ADDR_L, ADDR_H, TYPE, LOCATION_L, LOCATION_H

  MSG_BM_POSITION parameters

  Parameter	Description
  ADDR[2]	Address of the reporting decoder, coded as described above.
  TYPE	Kind of the position information: 0: locator badge with user-assigned 16-bit identifier 1: Radio area with cell identifer (cf. FEATURE_CELL_NUMBER). 2…255: reserved
  LOCATION[2]	Position information from decoder, lowbyte will be transferred first.

  Position reports are sent when a vehicle decoder announces its position via bidirectional messaging. It usually determines that from locator badges which transmit their identifier (ID, also: address) via infrared or similar communication to the vehicle. It may also get a position identifier when switching between radio cells and report the new connection information to the host. In contrast to occupancy messages, where vehicles are detected by a stationary sensor and a section (MNUM) can have one or more decoder addresses present, here for every decoder address there is one associated location identifier per type.

  MSG_BM_POSITION is only reported spontaneously and can not be queried. The transmission can be switched on or off by setting the FEATURE_BM_POSITION_ON.

  When the FEATURE_BM_POSITION_SECACK is enabled, the host immediately has to transmit a MSG_BM_MIRROR_POSITION with the same content back to the detector. Until this acknowledgement has arrived, the message will be repeated in the set interval multiple times. To avoid flooding the host, the number of repetitions has to be limited; longer outages are handled by the bus interface. If there is still no acknowledgement present by then, an error message with the code BIDIB_ERR_NO_SECACK_BY_HOST is sent.

  It should be minded to report a new position per decoder only when the previous one has been acknowledged.

  MSG_BM_POSITION messages with an address field specifying an extended accessory decoder are sent from stationary receivers that can be used to identify locator badges.

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

4.8.3. Downlink: Messages to the boosters

• MSG_BOOST_ON:

  The intention of this command is to switch on the track power. The next byte (UNICAST) defines if the message shall be distributed as a broadcast or not. The node responds with MSG_BOOST_STAT.

  Encoding of unicast

  Value	Meaning
  0	An interface has to distribute this message as a broadcast to all connected nodes to get all booster switched on synchronously as much as possible. The command applies to the interface node and all all nodes located below the interface that receive the track signal via the bus.
  1	The command applies to the current node only.

  It is needed to be aware that a booster can be switched on by a status change of the DCC generation, if this is not inhibitet by the feature FEATURE_BST_INHIBIT_AUTOSTART.

  The booster will not be switched on if there is no DCC signal available when applying the power supply. Because of this the behaviour of the booster depends on the powering on sequence:

  • Powering on the DCC generator at first, then MSG_BOOST_ON(0): all booster will be switched on (no exception)
  • At first MSG_BOOST_ON(0), then powering on the DCC generator: all booster will be switched on, expect those where the FEATURE_BST_INHIBIT_AUTOSTART is set.
• MSG_BOOST_OFF:

  This command will switch off the track voltage. The next byte (UNICAST) defines if the message shall be distributed as a broadcast or not. The node responds with MSG_BOOST_STAT.

  Encoding of unicast

  Value	Meaning
  0	An interface has to dristribute this message as a broadcast to all connected nodes. The command applies to the interface node and all all nodes located below the interface that receive the track signal via the bus.
  1	The command applies to the current node only.

• MSG_BOOST_QUERY:

  There is no additional data. The result of this command is the status of the booster. Also voltage or current measurement will be provided if it is available.

  The node answers with MSG_BOOST_STAT and optional MSG_BOOST_DIAGNOSTIC.

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?

• MSG_BOOST_STAT:

  This message will be sent after a status change. The reason for a status change can be based on a host command or hardware conditions. A status byte will follow. The MSB of the status byte denotes the power state of the booster, bit 6 denotes the DCC assignment of the booster, further bits are used for more detailed information:

  Encoding of booster state

  Bit	Meaning
  7	Power state 0 Booster is switched off. 1 Booster is switched on.
  6	Bus assignment (DCC) 0 Booster uses the DCC signal from this bus (default). 1 Booster uses different source for DCC (special case, i.e. DCC domain handover).
  5…0	Additional information on booster state.

  Detailed encoding of booster state

  Value	Name	Meaning
  0x00	BIDIB_BST_STATE_OFF	Booster is switched off (because of host command or e.g DCC is dropped out).
  0x01	BIDIB_BST_STATE_SHORT	Booster is switched off (because of short).
  0x02	BIDIB_BST_STATE_OFF_HOT	Booster is switched off (because of overtemperature).
  0x03	BIDIB_BST_STATE_NOPOWER	Booster is switched off (because of missing power supply).
  0x04	BIDIB_BST_STATE_OFF_GO_REQ	Booster is switched off and a request for powering on is available.
  0x05	BIDIB_BST_STATE_OFF_HERE	Booster is switched off (because of local key press).
  0x06	BIDIB_BST_STATE_OFF_NO_DCC	Booster is switched off (due to missing input signal).
  0x80	BIDIB_BST_STATE_ON	Booster is switched on.
  0x81	BIDIB_BST_STATE_ON_LIMIT	Booster is switched on and is running in current limitation.
  0x82	BIDIB_BST_STATE_ON_HOT	Booster is switched on and is in a critical temperature range.
  0x83	BIDIB_BST_STATE_ON_STOP_REQ	Booster is switched on and a request for stop is available.
  0x84	BIDIB_BST_STATE_ON_HERE	Booster is switched on (because of local key press).

  Note: GO or STOP requests can be applied decentralized (e.g. because of distributed emergency keys), the feature 27 (FEATURE_BST_INHIBIT_LOCAL_ONOFF) controls the behaviour in this case:

  • If this feature is missing or the value is equal to 0, the complete track supply system will be stopped with the emergency keys. This means a key press will skip a low pulse on the ack signal at the BiDiBus and therefor the master will stop the track supply. As a result all booster will switch off because of missing DCC signal.
    The booster which skipped the ack pulse announces his state change with BIDIB_BST_STATE_OFF_HERE, all others uses BIDIB_BST_STATE_OFF for the state change. With that the host is able to identify which part of the model railway is the reason for the emergency stop.
  • If the value of the feature is equal to 1, no ack signal will be given at key press. Instead the node will announce the key press with BIDIB_BST_STATE_ON_STOP_REQ. So it will not switch off and sends the stop request to the host. Now the host program is responsible to decide if a softstop or an emergency stop happens or if only parts of the model railway will be switched off.
• MSG_BOOST_DIAGNOSTIC:

  Diagnostic report of a booster as a list, containing for example current report, voltage, temperature.

  The reported values are shown as pairs, consisting an identifier of the message type and the message value.

  DIAG_LIST ::= DIAG_PAIR | DIAG_PAIR DIAG_LIST
  DIAG_PAIR ::= DIAG_ENUM DIAG_VALUE

  Encoding of booster diagnostics

  Name	Code	Meaning
  BIDIB_BST_DIAG_I	0x00	Current value. Value Meaning 0 No current consumption, track is free. 1…15 Current consumption, in mA. Possible range: 1…15mA 16…63 Current consumption, the value is (date - 12) * 4mA. Possible range: 16…204mA 64…127 Current consumption, the value is (date - 51) * 16mA. Possible range: 208…1216mA 128…191 Current consumption, the value is (date - 108) * 64mA. Possible range: 1280…5312mA 192…250 Current consumption, the value is (date - 171) * 256mA. Possible range: 5376…20224mA 251…253 Reserved. 254 Overcurrent occurred. 255 No exact consumption value known.
  BIDIB_BST_DIAG_V	0x01	Voltage value. Value Meaning 0…250 Voltage in units of 100 mV. 251…254 Reserved. 255 No exact voltage value known.
  BIDIB_BST_DIAG_TEMP	0x02	Temperature. Value Meaning 0…127 Temperature in units of degree celsius, signed char 128…225 Reserved. 226…255 negative temperature.

  Hints:

  This messages replaces the previous MSG_BOOST_CURRENT message

  The current value is encoded like the occupancy detector.

  The transmitted fields are optional. If a specific measurement is not available at the node, then he may omit the corresponding field type. However, the message must contain at least one field.

  The periodicity of the diagnostic message will be set with the FEATURE_BST_CURMEAS_INTERVAL feature.

4.9. Distributed Control

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

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