BiDiB, a universal control set for model railways
- 4.7. Occupancy Detection
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.
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 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.
- 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, following RCN 211, the distinction between short and long doesn't exist in the protocol.
|0||FEATURE_BM_SIZE||Number of occupancy feedback channels. The number of feedback bit's will be queried from the node. For detectors with an unknown number of inputs (e.g. S88-Bus Interface bridge), this variable can be writable. Value range: 0…128.|
|1||FEATURE_BM_ON||0: The node does not provide occupancy detection.|
1: The node provides occupancy detection (spontaneously). This occurs automatically during a occupancy state change.
|2||FEATURE_BM_SECACK_AVAILABLE||0: No Secure-ACK.|
1: The detector supports the Secure-ACK method for occupancy messages
|3||FEATURE_BM_SECACK_ON||If this feature is unequal to 0, then Secure-ACK is enabled. This value specifies the retransmition intervall in units of 10ms. A setting of 20 – corresponding to 200ms – is recommended.|
|4||FEATURE_BM_CURMEAS_AVAILABLE||0: no current measurement values|
1: The detector is able to provide current values (from a track section).
|5||FEATURE_BM_CURMEAS_INTERVAL||If this feature is unequal to 0, current measurement is enabled.|
This value specifies the sampling intervall of the current measurement in units of 10ms. A setting of 200 – corresponding to 2s – is recommended.
|6||FEATURE_BM_DC_MEAS_AVAILABLE||0: No substitution measurement available. (see also MSG_BM_CONFIDENCE)|
1: Substitution measurement: The detector is able to provide occupancy states even when the track power is off
|7||FEATURE_BM_DC_MEAS_ON||1: The detector will provide occupancy states even when the track power is off|
|8||FEATURE_BM_ADDR_DETECT_AVAILABLE||1: The detector is able to provide recognized loco address datas (if enabled in the decoder)|
|9||FEATURE_BM_ADDR_DETECT_ON||1: The detector provides the address data|
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.
This command transmits the status of all occupancy detectors in a certain area followed by 2 bytes: START, END which indicates the transferred detector bits. START and END must be divisible by 8.
The feedback system responds with all occupancy states from START to (exclusive) END. The answer should preferably use MSG_BM_MULTIPLE.
- 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.
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 from 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. (see MSG_BM_MULTIPLE)
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 is following (MNUM).(see MSG_BM_OCC)
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 is following (MNUM).(see MSG_BM_OCC)
- Note for the BM_MIRROR_* commands:
- The acknowledgement of occupancy messages should be done with the same type of command as the occupancy detection: If the occupancy detection is byte by byte, the acknowledgement should also be byte by byte, respectively for single messages. The reason for this is the real-time behaviour: Assuming the occupancy detector transmits multiple bits very rapid by MSG_BM_OCC / MSG_BM_FREE. If the host acknowledges the first message and sends back a byte, where only a part of the occupancy bits are correct, then he gets a MSG_BM_MULTIPLE from the occupancy detector node, which displays to the correct vector. This happens also for all following MSG_BM_* messages that are still in the queue.
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, this section will not be transferred.
No parameters following.
The current 'quality' of the occupancy detection is requested, the node responds with MSG_BM_CONFIDENCE.
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:
A single occupancy report (change notification); A byte with the local detector address is following (MNUM).
A single vacancy report (change notification); A byte with the local detector address is following (MNUM). If a track is reported as free, a possibly reported loco is also disappeared on this section.
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[0…N] Detector data: 1…16 bytes, wherein the LSB of the first byte corresponds with the base address and the MSB of the first byte corresponds to the base address + 7, LSB of the second byte corresponds with the base address + 8 and so on.
This message is specifically used in the initialization phase or after a protocol error for rapid importing of the occupancy states.
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.
With this message, the detection of a loco in a particular section will be reported.
Followed by 3 or more bytes: MNUM, ADDRL, ADDRH, [ADDRL, ADDRH], ...
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 address pairs ADDRL, ADDRH. A maximum of 16 addresses can be reported in one section.
MSG_BM_ADDRESS parameters Parameter Description MNUM Local number of the occupancy detector. Value range 0…127 ADDRL, ADDRH Address of the loco or accessory. Value Range is based on the DCC-value range. Coded like at bidi detectors.
- 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.
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.
Bidirectional messaging (railcom) of decoders can be detected and evaluated in different nodes like occupancy detectors or boosters. These may announce the following features:
|10||FEATURE_BM_ADDR_AND_DIR||1: The detector provides direction data, i.e. the basic ability for that. *)|
|11||FEATURE_BM_ISTSPEED_AVAILABLE||1: The detector is able to report speed values from the decoder|
|12||FEATURE_BM_ISTSPEED_INTERVAL||If this feature is unequal to 0, speed messages will be forwarded. This value specifies the speed message intervall in units of 10ms. A setting of 50 – corresponding to 500ms is recommended.|
|13||FEATURE_BM_CV_AVAILABLE||1: The detector is able to read CV-responses from decoders.|
|14||FEATURE_BM_CV_ON||0: The detector does not forward CV-responses from the decoder|
1: The detector forwards CV-responses from the decoder
|28||FEATURE_BM_DYN_STATE_INTERVAL||0: The detector does not forward DYN-responses from the loco decoder|
1…255: The detector forwards DYN-responses from the loco decoder; Interval in units of 100ms
|29||FEATURE_BM_RCPLUS_AVAILABLE||0: The detector does not support RailcomPlus decoder responses|
1: The detector forwards RailcomPlus decoder responses by occupancy section.
2: The detector forwards RailcomPlus decoder responses globally (MNUM=255)
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:
|0||no address recognized.|
|1…10239||loco or accessory decoder address; To distinguish the two MSBs will be used.
- Hints about orientation:
- The direction in the MSB is only valid if the corresponding feature setting (FEATURE_BM_ADDR_AND_DIR) announces the transfer of the direction. If this feature is disabled, the direction bits shall be set to 0, and must not be evaluated.
- The direction bit is set if the loco is connected with its left side (when looking in direction of chimney or driver's cab 1) to the track side with the detector. If the loco is wired with colors according to NEM, this side has a black color (right side is red).
Nodes that support bidi detection use the following BiDiB messages to forward the respective feedback:
(to be revised)
With this message, the feedback of an accessory decoder is reported.
CV-message, followed by 5 bytes: ADDRL, ADDRH, CVL, CVH, DAT
MSG_BM_CV parameters Parameter Description ADDR 2 byte, address of the sending decoder, coded as described above CV 2 bytes, CV, Value range 0…1023; 0 corresponds to CV1 DAT The read datum.
- 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!)
CV-message from a POM operation, followed by 10 to 13 bytes: ADDRL/DID0, ADDRH/DID1, 0/DID2, 0/DID3, 0/VID, OPCODE, CVL, CVH, CVX, 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.
- 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.
Speed-message, followed by 4 bytes: ADDRL, ADDRH, SPEEDL, SPEEDH
MSG_BM_SPEED parameters Parameter Description ADDR 2 byte, address of the reporting decoder, coded as described above SPEED 2 Bytes, 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.
Status message of an decoder followed by 5 bytes: MNUM, ADDRL, ADDRH, DYN_NUM, VALUE
MSG_BM_DYN_STATE parameters Parameter Description MNUM Local number of the occupancy detector, value range 0…127; 255 ADDR 2 bytes, address type of the reporting decoder, coded as described above DYN_NUM 1 byte, indicates the transmitted state. 0: reserved 1: Signal quality 2: Temperature 3: Container 1 4: Container 2 5: Container 3 6-255: reserved VALUE 1 Byte, state value. 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-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.
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
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 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.
- 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.