netBiDiB

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.

This document describes the transport over a network connection, using the TCP/IP stack.

Note: Data transmitted over a public network is always vulnerable to manipulation. The unencrypted transmission of data to the model railroad is only allowed in a secure, local environment. A remote control of the model railroad via netBiDiB over the internet is grossly negligent.

1.1. Objective

Common model railway bus systems like (CAN, BiDiBus, Xpressnet® or Loconet®) are suitable as field busses for the robust wiring inside the layout structure. Contemporary end user devices however lack the necessary hardware interfaces for a direct installation. A connection to current computer technology is usually achieved through USB adaptors and is thereby restricted to stationary PCs, the use of mobile devices (smartphones, tablets, laptops) or remote computers is only made possible by workarounds.

On these grounds, the following embedding of the BiDiB protocol in the ubiquitous IP stack was devised. It enables the utilisation of the commonplace home network infrastructure to attach the model railroad control system. The network connection represents a segment of the tree structure of a BiDiB system.

  • Plug & Play without configuration
  • reliable and error-free transmission
  • unlimited transfer rate

1.2. Revisions

This document describes revision 0.1 of netBiDiB, updated December 13th 2017.

1.3. Glossary

The following terms will be used in this document:

Internet Protocol (IP): A protocol for relaying data packets in and between networks. It can use different data links like Ethernet or Wifi.
IP address: A 32 (for IPv4) or 128 bit number (for IPv6) for identifying and locating a computer.
Port: A 16 bit number to distinguish multiple connections or services using the same transport protocol.
Transmission Control Protocol (TCP): A reliable, connection-oriented, packet-switched transport protocol for a data stream.
User Datagram Protokoll (UDP): A minimal, connectionless transport protocol for individual data packets.
Server: The communication participant in TCP that accepts connections.
Client: The communication participant in TCP that actively opens connections.
netBiDiB device (participant): A physical or logical instance (i.e. an assembly or a running program) that can participate as server or client in a netBiDiB system.
Host: The central instance of a BiDiB system which controls the connected nodes, normally a PC program.
Node: A participant of the BiDiB system, normally a hardware device.
Businterface (Interface): The body on the bus at which the nodes register themselves.
Descriptor: An information structure for identification and description of a network participant, consisting at least of a Unique-ID, a product name and a name chosen by the user.

2. Network

2.1. Architecture

The communication between two parties is connection-oriented. A bus level with multiple BiDiB nodes is formed by a central instance at which the nodes register: the (bus) interface (might be integrated with a host program) which maintains an individual connection to each node.

At the same time a node can be connected to multiple interface parties, however it will be logged onto at most one of them.

Network participants are distinguished into two groups:

  • Server accept incoming connections. They announce their presence to other parties in the network.
  • Clients do open connections to one or multiple servers on their own.

This classification is only important for the connection establishment according to the client-server-model and does not imply the participant's role in a BiDiB sytem. That is determined not until the logon of the node at the interface, when the two parties commit into a directional control relation.

To guarantee interoperability, it is however specified that

  • a participant in an interface role (e.g. a host program) acts as a client and
  • a participant in a node role acts as a server.

Beyond that, a party may act both as client and server on the same port. This enables both parties in P2P manner to open a TCP connection and close it when no longer needed.

A program that implements multiple independent participants with different roles should use different ports for them.

2.2. Connection establishment

In principle, a netBiDiB connection can be divided into the following aspects:

  1. Discovery: Detection and Recognition of netBiDiB devices

    The purpose of discovery is to find BiDiB nodes and learn about their BiDiB capabilities, network address and port for the subsequent steps. Due to the necessity of broadcast messages in the network, UDP is used for this. Discovery helps with the user-friendly design of the connection establishment.

  2. Link establishment: Opening the connection

    A communication channel between two netBiDiB devices is opened by establishing a TCP connection. At first the identities of the involved devices are exchanged so that the client becomes visible to the server as well.

    Such a connection where the remote party is identified is called a link.

    A link can be severed by terminating the connection.

  3. Pairing: Familiarising the participants with each other

    This serves to establish trust between BiDiB host programs (or in general interfaces) and nodes, and prevents undesired connections to unauthorised devices. In the pairing process, other netBiDiB devices in the network are designated and remembered as potential partners. This mutual trust does not indicate an actual control relation, a netBiDiB device can trust many other devices at the same time.

    A link on which both parties trust each other is called paired.

    The pairing procedure is necessary only once during the initial operation.

  4. Logon: Arranging the control relation

    The node logs onto the interface and becomes controllable through the host. Prerequisite for that is a successful prior pairing.

    The control relation between two participants can be broken up by either side, independent from the link.

2.4. Participants

A netBiDiB device must meet the following requirements to be considered as conforming to the standard:

  • Support for the protocol to establish a link and logon a node, as described below
  • Own identification as a netBiDiB device with UID, product name and user name
  • Remembering the trust to at least one other participant
  • Display of the connection status and respectively a pairing process
  • Interaction facility for triggering/accepting/denying a pairing
  • Interaction facility for breaking up the control relation (or more)
  • Interaction facility for revoking the trust to individual (or all) remembered participants

A device acting as client must also facilitate the opening of at least on connection. The server hostname or IP address and port of the server must be arbitrarily selectable, for instance by means of a configuration entry or direct input. Beyond that, a facility to choose from the servers found via discovery is optional but preferable.

A device with a graphical user interface must show product and user name when displaying other participants.

A single button suffices as the interaction facility, especially on participants without a graphical interface. A short button press shall trigger or respectively accept a pairing, and at the same time break an existing control relation. A long button press shall void the trust to all remembered participants.

3. Protocol

3.1. Discovery

This chapter is not yet finalised..

3.1.1. UDP transport

The User Datagram Protocol (see RFC 768) is a minimal, connectionless network protocol for transmitting individual data telegrams. Those so-called datagrams contain source and destination port for identifying the responsible service, a length field, a checksum and the user data. The datagrams are embedded in packets of the Internet Protocol, which convey source and destination address.

A UDP datagram for BiDiB is in principle constructed as follows:

DATAGRAM ::= SOURCE_PORT  DEST_PORT  LENGTH  CHECKSUM  MESSAGE_SEQ
SOURCE_PORT ::= 0x0000 | 0xC000 … 0xFFFF
DEST_PORT ::= 0xC000 … 0xFFFF
LENGTH ::= 0x0008 … 0xFFFF
CHECKSUM ::= 0x0000 … 0xFFFF
MESSAGE_SEQ ::= ε | MESSAGE  MESSAGE_SEQ

The first message in the datagram must be a MSG_LOCAL_PROTOCOL_SIGNATURE containing a string with the prefix "BiDiB". Packets not satisfying this must be dropped.

The following clauses apply to packets of BiDiB discovery:

  • There is no guarantee in the network that UDP packets are received in the same order they were sent, even if that is usually the case (especially in local networks). Therefore all messages of a discovery broadcast must be sent together in a single datagram.
  • A dynamic source port shall be chosen so that a sending program can receive responses on that port. In AVAILABLE broadcasts, which are not answered, 0 might be used as well.
  • Messages in the discvery process do not use sequence numbers, MNUM is coded as 0.

For broadcast packets, additionally the following clauses apply:

  • As the destination port, 62875 from the Dynamic Ports Range is used.
  • As the destination address, 255.255.255.255 (IPv4: limited broadcast) resp. ff02::1 (IPv6: link-local all nodes address) is used.

To receive BiDiB discovery broadcasts the socket option SO_REUSEADDR must be used, so that other applications on the same computer can receive them as well.

3.1.2. Procedure

Discovery is a convenience function that allows the integration of network devices without a configuration dialog. Where it does not work, the manual input of network interface, IP address and port is necessary.

To achieve this, a client sends a discover datagram with the following content as a BiDiB-UDP broadcast:

MSG_LOCAL_PROTOCOL_SIGNATURE "BiDiB…"
MSG_LOCAL_DISCOVER

A server announces its service with BiDiB-UDP announcement datagrams. They are sent as broadcasts at startup of the server and in a regular interval of about 5 seconds. When receiving a BiDiB datagram with a MSG_LOCAL_DISCOVER, a announcement datagram is sent as unicast back to the sender (source IP address and port).

Their content consist of at least one message with the UID of the server, followed by at least one message with connection options:

MSG_LOCAL_PROTOCOL_SIGNATURE  "BiDiB…"
MSG_LOCAL_LINK  DESCRIPTOR_UID  0x…
[ MSG_LOCAL_LINK  DESCRIPTOR_P_VERSION  0  7
  MSG_LOCAL_LINK  DESCRIPTOR_PROD_STRING  "Typ"
  MSG_LOCAL_LINK  DESCRIPTOR_USER_STRING  "Name" ]
MSG_LOCAL_ANNOUNCE  SERVER_TCP_NODE  tcp_port
[…]

Sending the complete descriptor is optional.

A client begins with the DISCOVER step automatically at program startup or when a new connection is supposed to be added. When a client receives an announcement of a server that it already trusts, it should establish a connection automatically. Connections to unknown servers should only be established when the user requests that.

3.2. Connection

3.2.1. TCP transport

The Transmission Control Protocol (see RFC 793 and more) transfers a bidirectional, byte-oriented, and reliable data stream between two end points. It guarantees the correct serving of data in the given order and is therefore suited also for transmission over susceptible channels like Wifi. Additionally it does get blocked less often than UDP by firewalls in their standard configuration. BiDiB uses TCP for the transmission of control messages between nodes.

The end points are identified by their IP address and port number. For BiDiB, port numbers from the dynamic port range (49152-65535) are used, those are dynamically assigned to programs by the operating system. The serverside port shall be user-adjustable as well, by default 62875 is used.

The data stream is structured as follows:

STREAM ::= EMITTER  MESSAGE_SEQ
MESSAGE_SEQ ::= ε | MESSAGE  MESSAGE_SEQ
EMITTER ::= 0x08  0x00  0x00  MSG_LOCAL_PROTOCOL_SIGNATURE  'B'  'i'  'D'  'i'  'B'

The data stream consist of a sequence of BiDiB message. They are classified into local messages and normal messages directed at the logged-on node. Normal messages are interpreted by the node not before it has successfully been logged on.

EMITTER denotes the first message, which must be a MSG_LOCAL_PROTOCOL_SIGNATURE containing a string with the prefix "BiDiB". This allows the recognition of inadvertent data streams alien to the protocol. When the check fails, the connection is immediately closed. MSG_LOCAL_PROTOCOL_SIGNATURE may (and shall) be repeated during the transmission to tag the TCP packets.

During the data transmission, the maximum answer volume of 48 bytes per destination node must be considered and occasionally the flow must be throttled per node. For messages to the logged-on node (address 0) as well as for the upstream the TCP flow control is used for constraining.

To achieve minimal latency, participants should use the socket option TCP_NODELAY.

3.2.2. Link establishment

A client enables the user to direct TCP connections to arbitrary addresses and ports. When a client supports discovery, it automatically opens connections to known servers as soon as they become visible.

Every participant comes with a descriptor, which contains the Unique-ID for identification and most importantly the product name and user name for the userfriendly display as well as further useful details for choosing a link. A host should use its program name as the product name and a string chosen by the user as the user name, for example the file name of the layout plan file or the computer name. As the Unique-ID a host should randomly generate a serial number and store in the plan file, no class bits are set.

After opening the TCP connection, both participants begin by sending their descriptor:

MSG_LOCAL_PROTOCOL_SIGNATURE  "BiDiB"
MSG_LOCAL_LINK  DESCRIPTOR_UID  0x...
MSG_LOCAL_LINK  DESCRIPTOR_P_VERSION  0  7
MSG_LOCAL_LINK  DESCRIPTOR_PROD_STRING  "Typ"
MSG_LOCAL_LINK  DESCRIPTOR_USER_STRING  "Name"

The reception of the DESCRIPTOR_UID is acknowledged by the remote end with a MSG_LOCAL_LINK and a status, coding whether it already trusts the Unique-ID (STATUS_PAIRED) or not (STATUS_UNPAIRED).

The link is established as soon as both parties have received the pairing status. If both parties sent STATUS_PAIRED, the link counts as paired and a node logon may now happen.

3.2.3. Pairing

If the participants do not yet trust each other, an explicit pairing must be carried out by the user. In doing so he confirms at both devices that the link is legitimate. Only after that any control exertion is allowed.

Such a confirmation may in principle happen by any means, e.g. by adding a configuration entry. To fashion the pairing in a userfriendly manner, BiDiB also provides a handshake facility in the protocol. With that it is possible to conduct a pairing by a simple button press even without a graphical user interface.

The handshake is structured symmetrically. It can be initiated by each of the participants with a PAIRING_REQUEST. When receiving such a proposal from a still untrusted remote party, a participant signals this to the user, then waits for a confirmation through the user for a while, and sends a PAIRING_REQUEST itself when the pairing is explicitly accepted.

A request is responded to with a pairing status for approval (STATUS_PAIRED) or rejection (STATUS_UNPAIRED), either immediately as predetermined behaviour or after a user interaction.

When the request was accepted, on receiving STATUS_PAIRED both participants memorise the new partner as trustable, so that the pairing does not need to be repeated when connecting the next time. The link now counts as paired and a logon may take place.

By sending MSG_LOCAL_LINK STATUS_UNPAIRED the trust can be revoked at any time. Controlling the node is no longer possible then.

3.2.4. Logon

On a paired link, the node may now register itself with the bus interface. If there are multiple options available, the node selects one of them. In particular after starting the node, it should wait some time after the initial announcement to allow all interested clients to establish a link. The node shall prefer the one interface which it was logged onto at last (for some time), so that a layout operation can be resumed with the same host program that had been active at closing hour. Also it shall favour those links which most recently have received a PAIRING_REQUEST.

For registration, the node sends a MSG_LOCAL_LOGON with its Unique-ID. The interface may either accept the logon (MSG_LOCAL_LOGON_ACK) or deny it (MSG_LOCAL_LOGON_REJECTED), in the latter case the node may try other established links to logon.

If the logon was accepted, the node now logged on and can be controlled. The interface may now insert the node in its node table (and possibly signal it to its host by MSG_NODE_NEW), the host can begin with MSG_SYS_GET_MAGIC and the typical protocol initialisation.

The logon may be withdrawn from either side at any time, by the interface through MSG_LOCAL_LOGON_REJECTED or by the node through MSG_LOCAL_LOGOFF.

3.3. Examples

A typical start sequence does for example look as follows (where both participants already know each other):

  Host (Client) 0x0D 933C8A6C                                             Node (Server) 0x0D 0278456B
Discovery:
MSG_LOCAL_PROTOCOL_SIGNATURE  "BiDiB"                              UDP>
MSG_LOCAL_DISCOVER                                                 UDP>
                                                                        <UDP  MSG_LOCAL_PROTOCOL_SIGNATURE  "BiDiB"
                                                                        <UDP  MSG_LOCAL_LINK  DESCRIPTOR_UID  0xC000 0D 0278456B
                                                                        <UDP  MSG_LOCAL_ANNOUNCE  SERVER_TCP_NODE  0xF5  0x9B
Connection (on port 0xF59B / 628759):
                                                               SYN TCP>
                                                                        <TCP SYN/ACK
                                                               ACK TCP>
Both participants send EMITTER as the first message
MSG_LOCAL_PROTOCOL_SIGNATURE  "BiDiB"                              TCP> <TCP  MSG_LOCAL_PROTOCOL_SIGNATURE  "BiDiB"
and begin (independently) to send parts of their descriptors (in arbitrary order):
MSG_LOCAL_LINK  DESCRIPTOR_UID  0x00000D933C8A6C                   TCP> <TCP  MSG_LOCAL_LINK  DESCRIPTOR_PROD_STRING  "Raspi-Ethernet-Hub"
                                                                        <TCP  MSG_LOCAL_LINK  DESCRIPTOR_USER_STRING  "Tradefair-Layout-Master"
                                                                        <TCP  MSG_LOCAL_LINK  DESCRIPTOR_P_VERSION  0  6
                                                                        <TCP  MSG_LOCAL_LINK  DESCRIPTOR_UID  0xC0000D0278456B
Receival of the UIDs establishes the link and is respectively acknowledged with the pairing status:
MSG_LOCAL_LINK  STATUS_PAIRED  0x00000D933C8A6C  0xC0000D0278456B  TCP>
                                                                        <TCP  MSG_LOCAL_LINK  STATUS_PAIRED  0xC0000D0278456B 0x00000D933C8A6C
(the host continues to send its descriptor here)
MSG_LOCAL_LINK  DESCRIPTOR_P_VERSION  0  7                         TCP>
MSG_LOCAL_LINK  DESCRIPTOR_PROD_STRING  "Wizard"                   TCP>
MSG_LOCAL_LINK  DESCRIPTOR_USER_STRING  "Richard"                  TCP>
The node now logs on:
                                                                        <TCP  MSG_LOCAL_LOGON  0xC0000D0278456B
MSG_LOCAL_LOGON_ACK  0x00  0xC0000D0278456B                        TCP>
MSG_SYS_GET_MAGIC                                                  TCP>
                                                                        <TCP  MSG_SYS_MAGIC  0xAFFE
MSG_SYS_GET_P_VERSION                                              TCP>
MSG_NODETAB_GETALL                                                 TCP>
MSG_FEATURE_GETALL                                                 TCP>

Remarkable is the different order and the disarrangement at the MSG_LOCAL_LINK messages in the example. The only restriction is that the pairing status (STATUS_PAIRED or STATUS_UNPAIRED) is sent only after sending the own and receiving the remote UID. Parts of the descriptor - apart from the UID - may also be sent anytime on an already established link, for instance when the name of the participant changes.

If the participants do not trust each other, a pairing by the user is necessary and the connection may begin as following:

  Host (Client) 0x0D 933C8A6C                                             Node (Server) 0x0D 0278456B
                                                                 SYN TCP>
                                                                          <TCP SYN/ACK
                                                                 ACK TCP>
Both participants begin:
MSG_LOCAL_PROTOCOL_SIGNATURE  "BiDiB"                                TCP> <TCP  MSG_LOCAL_PROTOCOL_SIGNATURE  "BiDiB"
MSG_LOCAL_LINK  DESCRIPTOR_UID  0x00000D933C8A6C                     TCP> <TCP  MSG_LOCAL_LINK  DESCRIPTOR_PROD_STRING  "Raspi-Ethernet-Hub"
MSG_LOCAL_LINK  DESCRIPTOR_PROD_STRING  "Wizard"                     TCP> <TCP  MSG_LOCAL_LINK  DESCRIPTOR_USER_STRING  "Tradefair-Layout-Master"
                                                                          <TCP  MSG_LOCAL_LINK  DESCRIPTOR_P_VERSION  0  6
                                                                          <TCP  MSG_LOCAL_LINK  DESCRIPTOR_UID  0xC0000D0278456B
The reception of the UIDs establishes the link and is acknowledged respectively with the pairing status:
MSG_LOCAL_LINK  STATUS_UNPAIRED  0x00000D933C8A6C  0xC0000D0278456B  TCP>
MSG_LOCAL_LINK  DESCRIPTOR_P_VERSION  0  7                           TCP>
MSG_LOCAL_LINK  DESCRIPTOR_USER_STRING  "Richard"                    TCP> <TCP  MSG_LOCAL_LINK  STATUS_UNPAIRED  0xC0000D0278456B 0x00000D933C8A6C
The link is now unpaired (an UNPAIRED from only side would suffice for this as well).

[User triggers pairing on the host]
MSG_LOCAL_LINK  PAIRING_REQUEST  0x00000D933C8A6C  0xC0000D0278456B  TCP>
The node signals the arrived request and waits.                                                                              [Timeout at the node]
                                                                          <TCP  MSG_LOCAL_LINK  STATUS_UNPAIRED  0xC0000D0278456B 0x00000D933C8A6C
The request has not been accepted in the given time frame, the link is still unpaired.
[User triggers pairing on the host] (again)
MSG_LOCAL_LINK  PAIRING_REQUEST  0x00000D933C8A6C  0xC0000D0278456B  TCP>
                                                                                                               [User triggers pairing on the node]
                                                                          <TCP  MSG_LOCAL_LINK  PAIRING_REQUEST  0xC0000D0278456B 0x00000D933C8A6C
With the activated pairing, the received pairing requests are respectively acknowledged:
MSG_LOCAL_LINK  STATUS_PAIRED  0x00000D933C8A6C  0xC0000D0278456B    TCP> <TCP  MSG_LOCAL_LINK  STATUS_PAIRED  0xC0000D0278456B 0x00000D933C8A6C
The link is now paired and the node logs on:
                                                                          <TCP  MSG_LOCAL_LOGON  0xC0000D0278456B
MSG_LOCAL_LOGON_ACK  0x00  0xC0000D0278456B                          TCP>
MSG_SYS_GET_MAGIC                                                    TCP>

The order of the two messages at the acceptance of the pairing is arbitrary. Just as possible is:

                                                                         …
MSG_LOCAL_LINK  PAIRING_REQUEST  0x00000D933C8A6C  0xC0000D0278456B  TCP>
                                                                          <TCP  MSG_LOCAL_LINK  STATUS_PAIRED  0xC0000D0278456B 0x00000D933C8A6C
                                                                          <TCP  MSG_LOCAL_LINK  PAIRING_REQUEST  0xC0000D0278456B 0x00000D933C8A6C
MSG_LOCAL_LINK  STATUS_PAIRED  0x00000D933C8A6C  0xC0000D0278456B    TCP>

The acceptance of the pairing may also happen without a second PAIRING_REQUEST when a participant already knows the other. For the first participant nothing changes thereby.

4. Local messages

Local messages serve to negotiate the transport connection. They are structurally identical to normal BiDiB messages, but are not routed forward to other bus participants. Local messages are not considered for the sequencing. Their MSG_ADDR_STACK is empty, MSG_ADDR and MSG_NUM are coded as 0x00.

  • MSG_LOCAL_PROTOCOL_SIGNATURE:

    This message signifies the kind of the data stream. Its data content is a byte string that must begin with the 5 ASCII characters 'B' 'i' 'D' 'i' 'B'.

    More characters after 'BiDiB' are allowed and welcome to brand the sender for debugging purposes. Those further characters have no significance and must not be evaluated.

    The message does not cause an answer, but the receiver must verify the string 'BiDiB'. If the test fails, the TCP connection is closed, apparently alien data was received.

  • MSG_LOCAL_LINK:

    This message establishes and acknowledges a link and changes its status. Followed by an OPCODE and depending on that further data bytes. It can be sent from both ends of the connection and at any time.

    Encoding of opcode for link administration
    ValueNameMeaning
    0xFF BIDIB_LINK_DESCRIPTOR_UID The sender establishes his side of the (potentially new) link.
    Followed by 7 bytes with the Unique-ID of the sender.
    The receiver responds with STATUS_PAIRED or STATUS_UNPAIRED.
    0x00 BIDIB_LINK_DESCRIPTOR_PROD_STRING The sender announces its product name, corresponding to the string 0 in namespace 0 (see MSG_STRING).
    Followed by one byte SIZE (0…24) and correspondly many CHARs.
    0x01 BIDIB_LINK_DESCRIPTOR_USER_STRING The sender announces its user name, corresponding to the string 1 in namespace 0 (see MSG_STRING).
    Followed by one byte SIZE (0…24) and correspondingly many CHARs.
    0x80 BIDIB_LINK_DESCRIPTOR_P_VERSION The sender announces its supported protocol version.
    Followed by 2 bytes, coded as in MSG_SYS_P_VERSION.
    0xFC BIDIB_LINK_PAIRING_REQUEST The sender initiates a pairing or counters the handshake. Prerequisite is an already established link (i.e. having exchanged the UIDs). Sending a message with this opcode is only allowed as a consequence of an explicit user interaction.
    Followed by 14 bytes with the Unique-ID of the sender and the Unique-ID of the intended receiver.
    The receiver responds (possibly delayed) with STATUS_PAIRED or STATUS_UNPAIRED.
    0xFD BIDIB_LINK_STATUS_UNPAIRED The sender denies his trust.
    Followed by 14 bytes with the Unique-ID of the sender and the Unique-ID of the intended receiver.
    Both sender and receiver set their link status to unpaired. A verification of the Unique-IDs is not necessary for that.
    0xFE BIDIB_LINK_STATUS_PAIRED The sender offers his trust. Prerequisite is an already established link (i.e. having exchanged the UIDs).
    Followed by 14 bytes with the Unique-ID of the sender and the Unique-ID of the intended receiver.
    When the receiver trusts the sender, he remembers his partner and sets his link status to paired. A verification of the Unique-IDs is possible but optional.
  • MSG_LOCAL_LOGON:

    With this message the node initiates his registration, it wants to get controlled by the host. Prerequisite is a paired link. The bus interface responds with MSG_LOCAL_LOGON_ACK or MSG_LOCAL_LOGON_REJECTED. Followed by 7 bytes:

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

    Hint: The class bits of the registering Unique-ID do not necessarily need to match those of the Unique-ID used for establishing the link.

  • MSG_LOCAL_LOGON_ACK:

    With this message an interface accepts a LOGON. The host can now begin with MSG_SYS_MAGIC reading in the node. Prerequisite is a paired link. Followed by 8 bytes:

    MSG_LOCAL_LOGON_ACK parameters
    ParameterDescription
    NODE The local BiDiB address under which the interface logged in the node, or 0 if the interface does not represent its own bus level (e.g. in the host program).
    UID[7] The Unique-ID of the node.

    Hint: NODE is not needed for any routing, the interface handles that by means of the TCP connection. It is only destined for debugging in the node.

    Only when the received Unique-ID is confirmed by the node to be identical to its internal Unique-ID, the logon is valid.

  • MSG_LOCAL_LOGON_REJECTED:

    With this message an interface rejects a LOGON or breaks up an existing control relation. Followed by 7 bytes:

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

    With this message a node logs off from the interface and is no longer subject to control by the host. It only interprets local messages thereafter. Followed by 7 bytes:

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

    With this message a client asks all servers in the network to announce their services. Followed by no data.

    A server responds with MSG_LOCAL_LINK DESCRIPTOR UID and one or more MSG_LOCAL_ANNOUNCE.

  • MSG_LOCAL_ANNOUNCE:

    With this message a server announces its services to all clients in the network. Followed by an OPCODE and depending on that further data:

    Encoding of opcode for service announcements
    ValueNameDescription
    0x00 BIDIB_ANNOUNCEMENT_SERVER_TCP_NODE The participant provides a BiDiB TCP server. Followed by 2 bytes (TCP_PORTH and TCP_PORTL, in network byte order!) with the port number of the server. The IP address of the server is the source address of the UDP packet.
  • MSG_LOCAL_SYNC:

    This message is regularly sent by the interface for synchronisation of the BiDiB system time. The message encodes the point in time of sending once as a BiDiB system timestamp and once as a timestamp with the system clock time of the computer running the interface. The netBiDiB participant synchronise their clocks through the Network Time Protocol (NTP, see RFC 5905), the interface then only provides the offset between UTC and BiDiB system time with the MSG_LOCAL_SYNC.

    MSG_LOCAL_SYNC parameters
    ParameterDescription
    TIMEL BiDiB system timestamp, 16-bit little endian.
    TIMEH
    UTC[8] Milliseconds since 1 January 1970 00:00:00 UTC (Unix epoch), 64 bit little endian.

    By means of the reference to a NTP-synchronised clock the negative impact of variable network latency and TCP flow control is avoided. Nevertheless a node shall drop the message when its system clock time deviates from the transferred value by more than one second.

    When a node has no NTP synchronisation available, it must construe the BiDiB system timestamp as its best, for example by taking into account the typical network latency (which usually is below 5 ms in local networks).