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.

Occupancy Detection

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.7. Occupancy Detection

4.7.1. Detection and protection

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.
'Alive'-Control
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.

4.7.2. Features for occupancy detectors
Listing of features for the occupancy-detection class
NumberNameMeaning
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.
2FEATURE_BM_SECACK_AVAILABLE 0: No Secure-ACK.
1: The detector supports the Secure-ACK method for occupancy messages
3FEATURE_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.
4FEATURE_BM_CURMEAS_AVAILABLE 0: no current measurement values
1: The detector is able to provide current values (from a track section).
5FEATURE_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.
6FEATURE_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
7FEATURE_BM_DC_MEAS_ON 1: The detector will provide occupancy states even when the track power is off
8FEATURE_BM_ADDR_DETECT_AVAILABLE 1: The detector is able to provide recognized loco address datas (if enabled in the decoder)
9FEATURE_BM_ADDR_DETECT_ON 1: The detector provides the address data
4.7.3. Downlink: Messages for occupancy detectors

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.

  • MSG_BM_GET_RANGE:

    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.

    Hint:
    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.
  • MSG_BM_MIRROR_MULTIPLE:

    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)

  • MSG_BM_MIRROR_OCC:

    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)

  • MSG_BM_MIRROR_FREE:

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

    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.

  • MSG_BM_GET_CONFIDENCE:

    No parameters following.

    The current 'quality' of the occupancy detection is requested, the node responds with MSG_BM_CONFIDENCE.

4.7.4. Uplink: Messages for occupancy detectors

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:

  • MSG_BM_OCC:

    A single occupancy report (change notification); A byte with the local detector address is following (MNUM).

  • MSG_BM_FREE:

    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.

  • MSG_BM_MULTIPLE:

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

  • MSG_BM_CONFIDENCE:

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

  • MSG_BM_ADDRESS:

    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
    ParameterDescription
    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.
  • MSG_BM_CURRENT:

    Current-message, followed by 2 bytes: MNUM, CURRENT

    MSG_BM_CURRENT parameters
    ParameterDescription
    MNUM local address of the detector
    CURRENT Current consumption
    Encoding of current values
    ValueMeaning
    0no power consumption, track is empty.
    1…15power consumption, in mA. possible range: 1…15mA
    16…63power consumption, value is (date - 12) * 4mA. possible range: 16…204mA
    64…127power consumption, value is (date - 51) * 16mA. possible range: 208…1216mA
    128…191power consumption, value is (date - 108) * 64mA. possible range: 1280…5312mA
    192…250power consumption, value is (date - 171) * 256mA. possible range: 5376…20224mA
    251…253reserved.
    254Overcurrent occurred.
    0xFFOnly 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.

4.7.5. Features for bidi detectors

Bidirectional messaging (railcom) of decoders can be detected and evaluated in different nodes like occupancy detectors or boosters. These may announce the following features:

Listing of features for bidi detectors
NumberNameMeaning
10FEATURE_BM_ADDR_AND_DIR 1: The detector provides direction data, i.e. the basic ability for that. *)
11FEATURE_BM_ISTSPEED_AVAILABLE 1: The detector is able to report speed values from the decoder
12FEATURE_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.
13FEATURE_BM_CV_AVAILABLE 1: The detector is able to read CV-responses from decoders.
14FEATURE_BM_CV_ON 0: The detector does not forward CV-responses from the decoder
1: The detector forwards CV-responses from the decoder
28FEATURE_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)
4.7.6. Uplink: Messages for bidi detectors

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:

Encoding of addresses
ValueMeaning
0 no address recognized.
1…10239 loco or accessory decoder address; To distinguish the two MSBs will be used.
Bit 15,14Bits 13…0
00Loco address, orientation (enrailment direction) forward
10Loco address, orientation (enrailment direction) reverse
01Accessory address
11Extended accessory address
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:

  • MSG_BM_ACCESSORY:

    (to be revised)

    With this message, the feedback of an accessory decoder is reported.

  • MSG_BM_CV:

    CV-message, followed by 5 bytes: ADDRL, ADDRH, CVL, CVH, DAT

    MSG_BM_CV parameters
    ParameterDescription
    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.
    Hints:
    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!)
  • MSG_BM_XPOM:

    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.

    Hint:
    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.
  • MSG_BM_SPEED:

    Speed-message, followed by 4 bytes: ADDRL, ADDRH, SPEEDL, SPEEDH

    MSG_BM_SPEED parameters
    ParameterDescription
    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.

  • MSG_BM_DYN_STATE:

    Status message of an decoder followed by 5 bytes: MNUM, ADDRL, ADDRH, DYN_NUM, VALUE

    MSG_BM_DYN_STATE parameters
    ParameterDescription
    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-numEncoding 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).
    ValueDescription
    0…127Temperature in degree Celsius units.
    128…225reserved.
    226…255negative 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.

  • MSG_BM_RCPLUS:

    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[4]

    MSG_BM_RCPLUS parameters
    ParameterDescription
    MNUM local address of the track section, value range 0…127; 255
    OPCODE Classification of the feedback, see below
    DEC_MUN[4] 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
    ValueMeaning
    TCP
    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.
    ACCESSORY
    Hints:
    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.