BiDiB, Communication over serial interfaces

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

Content

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

The following description shows how to use a serial link, i.e. RS232 or virtual COM-Port via USB.

2. Serial connection

2.1. Transmission parameter

Communication is made by a serial port with a variable baud rate from 19200 Baud, 115200 Baud or 1MBaud. Further parameters are 8 Data bits, 1 Stop bit, no Parity. (commonly known as "8N1"). The used baud rate must be determined from host during start-up by querying the system ID. Prefered baud rate is 1MBaud. Therefore, the host needs to test a maximum of 3 baud rate settings.

(Note for the baud rate: 1MBaud is working well on common USB-Uarts (i.e. FTDI) and on all modern microcontrollers. On older microcontrollers a suitable crystal (i.e. 16MHz) is necessary for 1MBaud)

CTS and RTS will be used. On both sides (Host and Interface) FiFo's have to be used in the design. After CTS-off up to 8 bytes can be still transferred.

When powering up and connecting to the BiDiB system, the node starts with a MSG_LOCAL_LOGON, although the message may get lost due to the initialisation of the serial interface. There is no data communication after that. First, the system ID of the interface has to be read successfully (to check for the correct baud rate) and the transfer of spontaneous messages has to be enabled at the interface.

2.2. Framing, Data integrity

The serial data package looks like the following:

PACKET ::= MAGIC  MESSAGE_SEQ  CRC  [MAGIC]
MESSAGE_SEQ ::= ε | MESSAGE  MESSAGE_SEQ
MAGIC ::= 0xFE

A serial PACKET always starts with a special character ([MAGIC]=0xFE) and can contain one or more messages (MESSAGE). The whole package is protected by CRC (Cyclic Redundancy Check) to recognize data errors during transmission. MAGIC-characters within messages will be 'escaped'. For this, a ESCAPE character (=0xFD) will be insert and the following character will be XOR-linked with 0x20. The ESCAPE character itself will ve also escaped within the transmission. This means: Instead of MAGIC, an ESCAPE-character (=0xFD) followed by an MAGIC ^ 0x20 = 0xDE will be send. Instead of ESCAPE-character 0xFD + 0xDD will be send. Escaping is made at the complete coded PACKET including CRC (CRC is calculated over the whole message without MAGIC).

The MESSAGE is addressed from the host to a certain node. Inside the package, MESSAGES for different nodes can be integrated

CRC means the CRC8-Byte; On the transmitter side, the polynom x8 + x5 + x4 + 1 will be generated over the message, starting at the first byte from the message, Init=0, none inverted. On receiver side, the CRC with the same polynom will be generated over the whole message including CRC. The result must be 0.

Every data package is followed by an MAGIC, this can be also the start of the next package at the same time. If there is no package left for transmit, the MAGIC will be transmitted anyway. The receiver recognize that the message ends up, based on the MAGIC-character, and starts the CRC-check.

It's not allowed to transmit more characters then the maximum length capacity (MSG_PKT_CAPACITY) between 2 MAGIC-characters Escaping will be not counted in this case.

Under certain circumstances the MESSAGE field could be empty, in this case MAGIC 0x00 MAGIC (0x00 is an empty CRC) or MAGIC MAGIC will be transmitted.

2.3. Link Establish and Control

On principle, any local BiDiB link is established at the beginning and checked for loss of connection during operation. To establish the connection, MSG_LOCAL_LOGON and MSG_LOCAL_LOGOFF are used, for monitoring MSG_LOCAL_PING may be used.

Hint: Since a serial link is point-to-point connection, a link can also be established through a direct start with MSG_SYS_GET_MAGIC by the host.

Rules for link control:

  • If a node doesn't receive a message within 5s, it shall assume loss of connection. It doesn't matter in this context whether the message is directed to the node itself or a subnode. A host should not leave gaps larger than 4s between two messages.
  • If there are no other messages to be transported, MSG_LOCAL_PING (and the corresponding MSG_LOCAL_PONG) can and should be used as 'keep alive' messages.
  • A host can actively terminate the connection with the message MSG_LOCAL_LOGON_REJECTED.
  • MSG_LOCAL_LOGOFF from a node signals that the node is going to terminate the connection, e.g. due to a restart.
  • Resumption is possible at any time and should start with MSG_SYS_GET_MAGIC and the transmission of the system time.

2.4. Local Messages

The general rules for local messages apply.

Logon/Logoff

  • MSG_LOCAL_LOGON:

    Link establish is started with this message from the node. 7 bytes are following:

    MSG_LOCAL_LOGON parameters
    ParameterDescription
    UID[7] The Unique-ID of the node.

    Note: this logon message is sent once. If the serial port is not open at this time, this message may be (and will be) lost. However, this message is still sensible i.e. after local operation and resume of computer control.

    The interfaces answers either with MSG_LOCAL_LOGON_ACK or MSG_LOCAL_LOGON_REJECTED or starts operation by a query of the MAGIC number.

  • MSG_LOCAL_LOGON_ACK:

    This messages is send (downstram) by the interface to acknowledge the logon. Followed by 8 bytes:

    MSG_LOCAL_LOGON_ACK parameters
    ParameterDescription
    NODE The local BiDiB address which is used to register the node. NODE is given as 0 if there is no separate address level for this connection.
    UID[7] Unique-ID of the node.

    Note: NODE is not used for signal routing (we have a direct serial link here), however it is useful for debugging (and keeps MSG_LOCAL_LOGON_ACK the same in different link physics).

    MSG_LOCAL_LOGON_ACK is only valid if UID matches the Unique-ID of the node. (Again, since it's a direct connection, this is not really necessary, however it is the same message in all implementaions.)

  • MSG_LOCAL_LOGON_REJECTED:

    A logon is rejected or active terminated by the host. 7 bytes are following:

    MSG_LOCAL_LOGON_REJECTED parameters
    ParameterDescription
    UID[7] The Unique-ID of the affected node.

    The node answers with MSG_LOCAL_LOGOFF. MSG_LOCAL_LOGON_REJECTED announces the termination of control. The node may take over control of underlying node i.e. to enable 'layout control without PC'.

  • MSG_LOCAL_LOGOFF:

    This message is used to terminate the session from the node. Control is no longer possible. 7 bytes are following:

    MSG_LOCAL_LOGON parameters
    ParameterDescription
    UID[7] The Unique-ID of the node.

    Link Control

    • MSG_LOCAL_PING:

      No parameter. The node answers with a MSG_LOCAL_PONG.

    Synchronisation

    • MSG_LOCAL_SYNC:

      The system time is transmitted via MSG_LOCAL_SYNC messages if desired by the host. They are constantly sent in intervals of less than 32,3 s (which, assuming a 30ppm quartz in the node, yields a maximum drift of 1 ms during that timespan). The timestamp contained in the message refers to the end of the previous MAGIC character. This point in time often can be queried from the driver after declaring MAGIC as an event character.

      There is no answer from the node.

    Avatarmode (Optional, only for tightly coupled systems)

    Since the serial link may be the only connection between a host and a node, the host may establish an avatar mode. In avatar mode, this serial connect is not visisble outside the connection. To ease this mode, data exchange between avatar and node can be done with local messages.

    • MSG_LOCAL_BIDIB_DOWN:

      wrapper message (from host to node), the wrapped BiDiB message is following. The node answers with a MSG_LOCAL_BIDIB_UP.

      Hints:
      Avatar messages are not mandatory, nor at host nor at node.
      If used, following messages should be considered for wrapping:
      MSG_SYS_GET_MAGIC,MSG_SYS_GET_P_VERSION, MSG_SYS_GET_UNIQUE_ID, MSG_SYS_GET_SW_VERSION, MSG_SYS_PING, MSG_GET_PKT_CAPACITY, MSG_STRING_SET, MSG_STRING_GET.
  •