BiDiB, a universal control set for model railways

The German version is the definitive specification. Any discrepancies between this translation and the original are unintentional.
BiDiB - Bidirectional Bus - Logo

Content

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.4. Firmware-Updates

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

4.4.1. Procedure of firmware updates

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

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

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

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

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

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

Target memory areas:

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

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

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

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

4.4.3. Downlink: Messages for firmware updates

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

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

  • 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
    ValueNameMeaning
    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
    ParameterDescription
    STATUS Process state
    Encoding of firmware update operation status
    ValueNameMeaning
    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:
    ValueMeaning
    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:
    ValueNameMeaning
    1BIDIB_FW_UPDATE_ERROR_NO_DESTTarget memory area not available.
    2BIDIB_FW_UPDATE_ERROR_RECORDEror at record (e.g. invalid characters).
    3BIDIB_FW_UPDATE_ERROR_ADDRRecord ouside of memory.
    4BIDIB_FW_UPDATE_ERROR_CHECKSUMChecksum error at hex-record.
    5BIDIB_FW_UPDATE_ERROR_SIZERecord too large;.
    6BIDIB_FW_UPDATE_ERROR_APPCRCCRC error at application, firmware not started.