BiDiB, a universal control set for model railways

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

General messages

BiDiB - Bidirectional Bus - Logo

Content

General

The intention of BiDiB protocol is to control a model railway. It allows the control of locomotives, accessories and safe transmission of feedback information from the model railway to the controlling computer.

BiDiB can be transported over different transmission media, framing and protection of messages is guaranteed.

The used terms and the basic principles will be explained in the general part of the protocol description. Hints for usage and the license can be found there too.

This section of the protocol description explains only a part of the messages.

Current revision status

This document describes revision 1.29 of BiDiB, updated June 21, 2023.

The revision history can be found at the general section.

4.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 (TIMEL, TIMEH) 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 (TCODE0, TCODE1, TCODE2, TCODE3) with the time value. The coding of these bytes is the same as the coding of the corresponding DCC command.

    Structure of model time
    FieldEncodingMeaning
    TCODE000mmmmmmmmmmmm = Minute indication, value range 0…59.
    TCODE1100HHHHHHHHHH = Hour indication, value range 0…23.
    TCODE201000wwwwww = Weekday, 0=Monday, 1=Tuesday, ... 6=Sunday.
    TCODE311ffffffffffff = 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, MAGICL, MAGICH 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
    MAGICLMAGICHDescription
    0xFE0xAFBIDIB_SYS_MAGIC = Regular BiDiB Node
    0x0D0xB0BIDIB_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
    DownstreamUpstream
    MSG_SYS_GET_MAGICMSG_SYS_MAGIC
    MSG_SYS_GET_P_VERSIONMSG_SYS_P_VERSION
    MSG_SYS_GET_SW_VERSIONMSG_SYS_SW_VERSION
    MSG_SYS_IDENTIFYMSG_SYS_IDENTIFY_STATE
    MSG_FW_UPDATE_OPMSG_FW_UPDATE_STAT
    MSG_SYS_RESET 
    MSG_LOCAL_LOGON_ACKMSG_LOCAL_LOGON
    MSG_SYS_GET_UNIQUE_IDMSG_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
    ParameterDescription
    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
    ValueNameMeaning
    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:
    0Short circuit
    1Bus interrupted, missing termination resistors
    2too many termination resistors
    3Logon failure, inconsistencies in the node table.
    4Logon failure, too many nodes in this level.
    5Bus failure, Overrun occurred at the bus master (usually a result of a programming error).
    6Bus 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
    ParameterDescription
    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.

Listing of general purpose features
NumberNameMeaning
112 FEATURE_CELL_NUMBER (logical) reference mark of this node (used for wireless systems)
0: single system.
1…n: area mark of this emitter.
113 FEATURE_RF_CHANNEL used RF channel
0…83: channel number in 2.4GHz band
84…255: reserved
250 FEATURE_STRING_NAMESPACES_AVAILABLE Availability of string namespaces as a bitfield:
  • Bit 0 - Namespace 0. Set when FEATURE_STRING_SIZE > 0.
  • Bit 1 - Namespace 1. Set when FEATURE_STRING_DEBUG available and writable.
  • Bit 2 - Namespace 2. Set when the node has accessory text output.
  • Bit 3…7 - reserved, to be set to 0.
If feature FEATURE_STRING_NAMESPACES_AVAILABLE isn't present, the availability of namespaces 0 and 1 is implied only through FEATURE_STRING_SIZE resp. FEATURE_STRING_DEBUG.
251 FEATURE_STRING_DEBUG Usage of string namespace 1. Range: 0 (off), 1 (mode for 7 text streams); Default 0.
252 FEATURE_STRING_SIZE Maximum number of chars for string variables in namespace 0. Range: 0; 8…24
(If the feature FEATURE_STRING_SIZE is missing or its value is 0, the node can't handle the corresponding messages.)
253 FEATURE_RELEVANT_PID_BITS Number of significant bits for the product ID (contained in the Unique ID). Range: 1…31.
Default 16. (If the feature FEATURE_RELEVANT_PID_BITS is missing, the default 16 bits for product ID and 16 bits for serial number is used.
4.2.1. Downlink: Messages for querying and setting of feature settings
  • 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.

Examples for MSG_VENDOR_:
MSG_VENDOR_GET 0x01 0x38 (=1 '8'): CV 8 (vendor ID at normal decoders) will be read: 1 is the length of the string, which consists only the ASCII-character for 8.
MSG_VENDOR_SET 9 'T'H'R'E'S'H'O'L'D' 3 '2'5'5': The message begins with the identifier MSG_VENDOR_SET, followed by a length byte of 9 and the parameter name 'THRESHOLD', further followed by another length byte (3) and the parameter value (255).
DCC-Mapping:
The so called DCC-Mapping uses vendor messages as well, which we explain in detail in support part chapter DCC-Mapping.
  • 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
    ParameterDescription
    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.