German
English
BiDiB
Protocol
BiDiB, a universal control set for model railways
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:
- 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.
- The node sends a 'ready' message, which contains a indication that he is ready to receive the firmware.
- The host sends a message that indicates the type and the destination memory of the following firmware. e.g. contents of flash-memory.
- The node acknowledges receipt and indicates that he expect the data set.
- 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.
- 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.
- Lastly, the host sends a message that the last line has been transferred and any last fragments needs to be written into the memory.
- 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
| Number | Name | Meaning |
|---|---|---|
| 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:
| Placeholder | Substitution |
|---|---|
| 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. |
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
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: EEPROM0x03 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 ERRORAfter a successfull execution, this byte indicates the minimum time that the host needs to be wait until the next packet can be sent:
In case of an error (STAT_ERROR) this byte encodes the cause: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. 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.