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.26 of BiDiB, updated aug 15, 2016.

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 any 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 any other data will follow.

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

  • MSG_SYS_ENABLE:

    No any 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 of the Unique-ID. No any other data will follow.

    The corresponding node responds with its Unique-ID.

    (The UniqueID of a node is stored in the node table of its interface, this command can be used for monitoring.

  • MSG_SYS_GET_SW_VERSION:

    Query of the node's installed software version(s). No any 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 any 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.

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. Interfaces inherit this message automatically to all following sub nodes.

    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, is it possible to read the maximum message length from the interface, which the sub structure can transport. The node responds with a MSG_PKT_CAPACITY message. Nodes without interface answer with the length of their internal 'adhoc' processing depth, i.e. the maximum number of bytes that may occur between two frame markers (normally 64). For throughput optimization, it is allowed to accumulate messages up to this PKT_CAPACITY limit withing a sequence.

  • 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_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 UniqueID. Only if the node has verified that the received UniqueID and the internal UniqueID 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_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 UniqueID. 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 UniqueID was recognized on the bus.

    Simultaneously with the MSG_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. This clock runs typically accelerated compared with the real time. Followed by 4 bytes (TCODE0, TCODE1, TCODE2, TCODE3) with the time specification. 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.
    TCODE3110ffffffffff = Clock acceleration factor, fffff=0 means clock is stopped.

    The data consist a 2-bit field (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_LOGON_ACKMSG_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 UniqueID 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.

  • 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.
    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. Followed by one byte with the MSG_NUM of the last message with the correct sequence. However, the node processes the received messages and the current sequence number is taking 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, 2 nodes with identical Unique-ID present.
    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 but his ID is already present in the node table.
    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.
    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.

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 hardware identifier of the node, consisting of 7 bytes

    If a node has no any 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, the interface report the maximum message length of its local structure (e.g. 64 at BiDiBus) to the host. Followed by a length specification, containing 1 byte, value range 0…127. (MSB is reserved for length-extension) Nodes without interface transmits 0.

  • 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_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 UniqueID. 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.

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

    Query all feature settings. No byte will follow. The response consists a message, MSG_FEATURE_COUNT, which specifies the number of existing features. If this number is 0, the node has no any features. The node resets the internal counter for MSG_FEATURE_GETNEXT queries.

  • 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 have been sent, which 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 (which can be fetched with a series of MSG_FEATURE_GETNEXT). This allows the host to check if all feature has been arrived after an MSG_FEATURE_GETALL query.

4.3. Messages for user configuration

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

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

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

4.3.1. Downlink: Messages for user configuration
  • 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 any 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 responds with a MSG_VENDOR message, this includes V_NAME and V_VALUE as well.

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

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

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

    This message type is used to control string variables inside a node. There are different name_spaces and in each name_space strings, addressed with a string_id.

    This command is followed by the data denoting the used name_space, the string_id, the string_size and the string itself.

    The node answer with a MSG_STRING. This function is only available in specific node, if FEATURE_STRING_SIZE exists and has a value > 0.

    MSG_STRING_SET parameters
    ParameterDescription
    NAME_SPACE denotes the addressed name space inside the node, range 0…255
    • 0: Node general
    • 1…255: reserved
    STRING_ID denotes the addressed string inside the given name space.
    Name space 0:
    • STRING_ID = 0: product name, readonly (stored by manufacturer).
    • STRING_ID = 1: Username, read/write, set by user.
    • STRING_ID = 2…n: reserved
    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.
    Hints:
    The feature FEATURE_STRING_SIZE defines the maximum length of strings inside the node. The valid range is 8 to 24. If FEATURE_STRING_SIZE doesn't exist (or is 0), the node can't handle strings.
    If a string message is answered with size = 0, this string does not exist on this node.
    User definable strings (i.e. username) 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 in name space 0 is a user-configurable nickname for the node, i.e. Station-Sigs-left
  • MSG_STRING_GET:

    Query of a string variable inside a node. Two bytes are following, denoting name space and string id.

    The node answer with a MSG_STRING. This function is only available in specific node, if FEATURE_STRING_SIZE exists and has a value > 0.

    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 for the answer to MSG_STRING_SET or MSG_STRING_GET.

    Followed by the data denoting the used name_space, the string_id, the string_size and the string itself. For details see MSG_STRING_SET.