Communication

• Summary

Serial connection

• Specification

BiDiBus

• Specification
• Background information

Network

• Specification
• Background information

netBiDiB and webBiDiB

Content

• 1. General
  • 1.1. Objective
  • 1.2. Revision status
  • 1.3. Glossary
• 2. Network
  • 2.1. Architecture
  • 2.2. Connection establishment
  • 2.3. Participants
• 3. Protocol
  • 3.1. Discovery
    • 3.1.1. DNS Service Discovery
    • 3.1.2. BiDiB-specific custom-built Discovery
      • 3.1.2.1. UDP-Transport
      • 3.1.2.2. Procedure
  • 3.2. Connection
    • 3.2.1. Transport
      • 3.2.1.1. TCP-Transport (netBiDiB)
      • 3.2.1.2. WS-Transport (webBiDiB)
    • 3.2.2. Link establishment
    • 3.2.3. Pairing
    • 3.2.4. Logon
  • 3.3. Examples
• 4. Local messages

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/webBiDiB 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. Revision status

This document describes revision 0.2 of netBiDiB, updated December ??th 2020.

1.3. Glossary

The following terms will be used in this document:

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 on to 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 system. 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 fundamentally:

• a netBiDiB participant in an interface role (e.g. a host program) acts as a client
• a netBiDiB participant in a node role (e.g. a switch control device) acts as a server
• a webBiDiB participant in an interface role (e.g. a host program) acts as a server
• a webBiDiB participant in a node role (e.g. a guest handheld controller) acts as a client

Beyond that, a netBiDiB participant may act both as client and server on the same port regardless of its role. This enables both parties in P2P manner to open a TCP connection and close it when no longer needed. It is permitted for instance that a handheld (netBiDiB participant with node role) additionally acts as a client, or that a host program (netBiDiB participant with interface role) additionally acts as a server and implements a guest node.

Naturally, it is necessary for such a connection to work that both sides implement the respective extra feature, otherwise only the unidirectional connection establishment in the obligatory direction is possible. We therefore recommend that controllers and other host program implement both client and server support.

A participant that supports connections in an unusual direction must announce its role(s) via its descriptor and must recognise and handle any problematic connections (node-node or interface-interface) that may arise.

A program that implements multiple independent participants with different roles can use different ports for them. Alternatively, it may function as client and server at once on the same port, and assume its role dynamically depending on the remote participant. In some constellations the role allocation should not be determined automatically but be chosen by the user, which may take place in conjunction with the pairing process.

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 netBiDiB servers 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 or webBiDiB devices is opened by establishing a 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 or webBiDiB devices in the network are designated and remembered as potential partners. This mutual trust does not indicate an actual control relation, a BiDiB 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 on to 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.3. Participants

A netBiDiB or webBiDiB 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 participant with UID, product name and participant name
• Declaration of the supported protocols (netBiDiB, webBiDiB) and roles (node, interface) in the product description and documentation
• 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 destination server hostname or IP address and port of the server must be arbitrarily selectable. Beyond that, a facility to choose from the servers found via discovery is optional but preferable.

A device acting as a server must document the used (standard) port in its product description, ideally it is configurable and is displayed in the user interface together with the bound IP addresses.

A device with a graphical user interface must show product and participant 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

Discovery is a convenience function for netBiDiB that allows the automatic 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.

A client begins the discovery automatically when the application starts or when a new connection is being set up. When a client detects a netBiDiB server that it already trusts, it should automatically open a connection to establish a link, however without already performing the node logon. Connections to unknown servers should only be opened when the user requests this.

A netBiDiB server can be announced through different service discovery protocols on the network, even multiple ones at the same time. The usage of DNS-SD via mDNS is recommended.

3.1.1. DNS Service Discovery

A netBiDiB server can be found in the Domain Name System (RFC 1034). The discovery of all services under a domain that support the netBiDiB protocol is facilitated by the DNS Service Discovery (RFC 6763). With the assigned Service Name bidib, it uses the service type _bidib._tcp.

Every service instance in the DNS represents one netBiDiB participant. It has a resource record of type SRV, which refers to the host name and port of the participant (RFC 2782), and a resource record of type TXT, which contains further attributes of the service as key-value pairs. For netBiDiB participants the following keys are defined:

• uid: a 7 byte long binary value (deprecated), or a 14 byte long hexadecimal string value (1), with the Unique-ID of the participant
• prod: string value (2) is the product name of the the participant, cf. DESCRIPTOR_PROD_STRING
• user: string value (2) is the participant name, cf. DESCRIPTOR_USER_STRING
• node: boolean attribute. The existence (with no, empty, or arbitrary value) signifies that the participant will assume the node role and respond to a logon request.
• interface: boolean attribute. The existence (with no, empty, or arbitrary value) signifies that the participant will assume the interface role and is prepared to accept the logon of a node.
• bidib (deprecated): the value "node" has the same meaning as the existence of a node key, the value "interface" has the same meaning as the existence of a interface key.

(1)

A service should preferably be announced using the 14-byte-string, as many mDNS libraries represent TXT values exclusively as null-terminated strings. Clients that have no problems with binary data should also accept the older 7-byte format.

(2)

Product name and participant name are encoded as UTF-8 in the TXT record, not as ISO 8859-1 like in MSG_STRING oder MSG_LOCAL_LINK. This too is with regard to mDNS libraries that cannot employ a different character set.

Two subtypes of _bidib._tcp are used to simplify the discovery of participants according to their role: _node._sub._bidib._tcp and _interface._sub._bidib._tcp. Participants that have the respective boolean flag are also announced for the respective subtype.

In local networks, Multicast DNS (RFC 6762) is used to announce and search for the respective resource records under the domain .local.. It does not only support one-shot queries, but also continuous monitoring without having to resort to polling.

    _services._dns-sd._udp.local.   PTR    _bidib._tcp.local.                  shared   TTL=75min (4500s)
               _bidib._tcp.local.   PTR    <service name>._bidib._tcp.local.   shared   TTL=75min (4500s)
    _node._sub._bidib._tcp.local.   PTR    <service name>._bidib._tcp.local.   shared   TTL=75min (4500s)
<service name>._bidib._tcp.local.   SRV    <hostname>.local.:<BiDiB-Port>      unique   TTL=75min (4500s)
<service name>._bidib._tcp.local.   TXT    node,uid=…,user=…,prod=…            unique   TTL=75min (4500s)
                <hostname>.local.   A      <IPv4 address>                      unique   TTL=2min (120s)
                <hostname>.local.   AAAA   <IPv6 address>                      unique   TTL=2min (120s)

DATAGRAM ::= SOURCE_PORT  DEST_PORT  LENGTH  CHECKSUM  UDP_DATA
SOURCE_PORT ::= 0x0000 | 0xC000 … 0xFFFF
DEST_PORT ::= 0xC000 … 0xFFFF
LENGTH ::= 0x0008 … 0xFFFF
CHECKSUM ::= 0x0000 … 0xFFFF

UDP_DATA ::= EMITTER  MESSAGE_SEQ
MESSAGE_SEQ ::= ε | MESSAGE  MESSAGE_SEQ
EMITTER ::= EMITTER_LENGTH  0x00  0x00  MSG_LOCAL_PROTOCOL_SIGNATURE  'B'  'i'  'D'  'i'  'B'  EMITTER_SUFFIX
EMITTER_LENGTH ::= 0x08 | … | 0x7F
EMITTER_SUFFIX ::= ε | ANY_BYTE  EMITTER_SUFFIX

MSG_LOCAL_PROTOCOL_SIGNATURE "BiDiB…"
MSG_LOCAL_DISCOVER

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

3.2. Connection

3.2.1. Transport

The network communication between two participants necessitates the use of a transport protocol that guarantees a stable data transmission. 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 or host respectively. Normal messages are interpreted by the node not before it has successfully been logged on.

The choice of the transport protocol falls to TCP for netBiDiB, and to the WebSocket protocol for webBiDiB.
TCP is the preferred standard. WebSockets can be used by participants implemented as web applications, where direct communication via TCP is not possible.

To establish a connection, both sides must use the same transport protocol. The protocols that a participant implements must therefore be clearly stated in its product description as support of netBiDiB and webBiDiB respectively.

3.2.1.1. TCP-Transport (netBiDiB)

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 delivery of data in the given order and is therefore suited also for transmission over interference-prone channels like Wifi. Additionally it does get blocked less often than UDP by firewalls in their standard configuration. netBiDiB uses TCP for the transmission of control messages between nodes.

The end points are identified by their IP address and port number. For netBiDiB, port numbers from the dynamic port range (49152-65535) are used, those are dynamically assigned to programs by the operating system. The server-side port should be adjustable by the user just like the participant name, by default 62875 is used.

The byte data stream is structured as follows:

STREAM ::= EMITTER  MESSAGE_SEQ
MESSAGE_SEQ ::= ε | MESSAGE  MESSAGE_SEQ
EMITTER ::= EMITTER_LENGTH  0x00  0x00  MSG_LOCAL_PROTOCOL_SIGNATURE  'B'  'i'  'D'  'i'  'B'  EMITTER_SUFFIX
EMITTER_LENGTH ::= 0x08 | … | 0x7F
EMITTER_SUFFIX ::= ε | ANY_BYTE  EMITTER_SUFFIX

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.

Dropped (half-open) TCP connections are detected by the absence of ACKs. For this, TCP-Keepalive should be enabled with a suitable timeout. Where not supported by the used TCP implementation, a participant may regularly send MSG_LOCAL_PROTOCOL_SIGNATURE instead of the keepalive packets.

3.2.1.2. WS-Transport (webBiDiB)

The Websocket protocol (see RFC 6455) is a TCP-based network protocol that was designed to enable opening a message-oriented bidirectional connection from a web application to a server. The data exchange begins with a HTTP-compatible header and then switches to individual frames, in which text data, binary data, ping or pong messages as well as further control messages can be transmitted. webBiDiB uses Websockets for the transmission of BiDiB messages between web based participants, as the security model for browser-based code does not allow creation of plain TCP connections.

A server endpoint is identified by an URL, consisting of scheme (ws or wss), host (name or IP address), port number, path and query string. A webBiDiB client must enable the user to enter an arbitrary URL to establish a connection. The server-side port should be adjustable by the user just like the participant name. By default the port 62873 and neither path nor query are used, thus ws://[host]:62873/.

A webBiDiB server shall accept clients with any arbitrary Origin header. Where this is restricted by a deny or allow list, the list must be configurable by the user. The server must use the combination of the Origin header value and the sent Unique-ID for identification of the client participant. This ensures that no malicious code executed in the browser can circumvent the pairing mechanism.

The WebSocket subprotocol "bidib" has been registered for webBiDiB, both client and server must set this in the header when establishing the connection. For compatibility reasons, a MSG_LOCAL_PROTOCOL_SIGNATURE must be sent as the first message in the overall message stream, just like in the TCP-Transport (netBiDiB).

A webBiDiB WebSocket uses exclusively messages of type "binary", no text messages, for transport of BiDiB messages. Text messages should be ignored by the recipient, closing the WebSocket with reason 1003 is permissible as well. Every WebSocket binary message represents a webBiDiB packet, its data content is structured as follows:

WS_BIN_DATA ::= MESSAGE_SEQ
MESSAGE_SEQ ::= ε | MESSAGE  MESSAGE_SEQ

The total BiDiB message stream consists of all BiDiB messages contained in the packets, which might be none (in exceptional cases), one or multiple per packet. Bundling is recommended, though the length should be constrained so that a fragmentation of the WebSocket messages into multiple frames is avoided.

The flow control relies on the behaviour of the underlying TCP connection. To detect connection losses, ping and pong frames may be used. Where those are not supported, empty WebSocket messages can be sent, which likewise ultimately leads to a timeout and the connection being closed with status 1006.

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 individual participant name for the userfriendly display. Further optional details, for instance the implemented protocol version and the supported roles, may help with choosing a link. A host should use its program name as the product name and a string chosen by the user as the participant 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 or WS 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  8
MSG_LOCAL_LINK  DESCRIPTOR_PROD_STRING  "Typ"
MSG_LOCAL_LINK  DESCRIPTOR_USER_STRING  "Name"
MSG_LOCAL_LINK  DESCRIPTOR_ROLE  1/2

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). On a webBiDiB link, the bond of trust to the client participant is attached not only to its Unique-ID but also to the value of the Origin header!

DESCRIPTOR_ROLE declares the role(s) that a participant may take on. The value 1 stands for the interface role, 2 for the node role, and 3 describes a participant that can take on both roles (e.g. hubs or software that can function as host or as guest). When a participant sends no DESCRIPTOR_ROLE before its pairing state, the node role is assumed for a netBiDiB server or webBiDiB client, and the interface role is assumed for a netBiDiB client or webBiDiB server. If not at least one node and one interface participate in a connection, it should be closed with an error message.

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.

Every request is responded to with a pairing status for approval (STATUS_PAIRED) or rejection (STATUS_UNPAIRED), either after the user interaction or a timeout, optionally even immediately for pre-existing trust.

When two PAIRING_REQUESTs have been exchanged on a link within a certain timespan, both participants send STATUS_PAIRED and the pairing has been successful. On receiving STATUS_PAIRED, both participants memorise the new partner as trustable, so that the pairing process 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 the node is already logged on to another interface, it will indicate this to the joining bus interface through a MSG_LOCAL_LOGOFF. When 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 on to 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 - in exceptional cases - by the node through MSG_LOCAL_LOGOFF. Such a logoff may be triggered by the user, e.g. to make the node available to other programs. A revocation of the pairing or the closing of the TCP connection imply an immediate logoff as well.

A user may also let an interface at which the node is not logged on at the time try to take control over the node. For such a logon request, another STATUS_PAIRED is sent to the node. If the node is not logged on to an interface (any more) - after a release through MSG_LOCAL_LOGOFF or because no interface accepted the logon at initial startup - it will conduct a logon.

When there are paired links to multiple bus interfaces, these may inform the user about the status of the node as well. To this end, when the node does a LOGOFF or gets a LOGON_ACK, it will send a NODE_AVAILABLE or NODE_UNAVAILABLE respectively to each of the other interfaces. This is particularly relevant for nodes that have no display themselves.

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 / 62875):
                                                               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  18  "Raspi-Ethernet-Hub"
                                                                        <TCP  MSG_LOCAL_LINK  DESCRIPTOR_USER_STRING  23  "Tradefair-Layout-Master"
                                                                        <TCP  MSG_LOCAL_LINK  DESCRIPTOR_P_VERSION  0  6
                                                                        <TCP  MSG_LOCAL_LINK  DESCRIPTOR_ROLE  2
                                                                        <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  8                         TCP>
MSG_LOCAL_LINK  DESCRIPTOR_PROD_STRING  6  "Wizard"                TCP>
MSG_LOCAL_LINK  DESCRIPTOR_USER_STRING  7  "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  18  "Raspi-Ethernet-Hub"
MSG_LOCAL_LINK  DESCRIPTOR_PROD_STRING  6  "Wizard"                  TCP> <TCP  MSG_LOCAL_LINK  DESCRIPTOR_USER_STRING  23  "Tradefair-Layout-Master"
MSG_LOCAL_LINK  DESCRIPTOR_ROLE  3                                   TCP> <TCP  MSG_LOCAL_LINK  DESCRIPTOR_P_VERSION  0  6
                                                                          <TCP  MSG_LOCAL_LINK  DESCRIPTOR_ROLE  2
                                                                          <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  8                           TCP>
MSG_LOCAL_LINK  DESCRIPTOR_USER_STRING  7  "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 even happen before the second PAIRING_REQUEST when a participant already knows the other. For pairing with participants that have no graphical display and ability to choose a particular connection the second PAIRING_REQUEST, also triggered by the user, is still essential.

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

  Value	Name	Meaning
  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 correspondingly many CHARs.
  0x01	BIDIB_LINK_DESCRIPTOR_USER_STRING	The sender announces its participant name, corresponding to the string 1 in namespace 0 (see MSG_STRING, "user's node name"). Followed by one byte SIZE (0…24) and correspondingly many CHARs.
  0x7F	BIDIB_LINK_DESCRIPTOR_ROLE	The sender announces the role(s) it supports. Followed by one byte with a bit field: Bit 0 refers to the interface role, i.e. the participant can accept logons from nodes when the bit is set. Bit 1 refers to the node role, i.e. the participant can and will logon to an interface when the bit is set. Bit 2-7: reserved, coded as 0 and ignored during evaluation.
  0x80	BIDIB_LINK_DESCRIPTOR_P_VERSION	The sender announces its supported protocol version. Followed by 2 bytes, coded as in MSG_SYS_P_VERSION.
  0x81	BIDIB_LINK_NODE_UNAVAILABLE	The sender announces to already be logged on to a different interface as a node. Followed by 2 or more bytes, PROD_STRING_SIZE PROD_STRING[SIZE] USER_STRING_SIZE USER_STRING[SIZE], with the values from the descriptor of the interface that is currently controlling the node. The message occurs while the node is logged off, its sole purpose is informing the user to grant them a better overview of the system state. It is not a guarantee that a future logon request will be declined.
  0x82	BIDIB_LINK_NODE_AVAILABLE	The sender announces that it is currently not logged on to an interface (any more) as a node. Followed by no byte. This solely serves to inform the user about the status of the node. It is not a guarantee that a future logon request will be accepted.
  0xFC	BIDIB_LINK_PAIRING_REQUEST	The sender initiates a pairing or counters the request. 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. After a reply (handshake via two PAIRING_REQUESTs) within a certain timespan, the participants set trust in each other. 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 states to distrust the receiver; he denies his trust or withdraws it. 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 states to trust the receiver; he 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 as well, he remembers his partner and sets his link status to paired. A verification of the Unique-IDs is possible but optional. If a node receives a STATUS_PAIRED on a paired link, it represents a logon request by the interface. The node starts a logon with MSG_LOCAL_LOGON, or declines the request with a MSG_LOCAL_LOGOFF if it already is logged on to a different interface.

• MSG_LOCAL_LOGON:

  With this message the node initiates his registration, it wants to get controlled by the host and will now also accept non-local message. Prerequisite is a paired link. Followed by 7 bytes:

  MSG_LOCAL_LOGON parameters

  Parameter	Description
  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.

  The bus interface responds with MSG_LOCAL_LOGON_ACK or MSG_LOCAL_LOGON_REJECTED.

  If the node does not receive a MSG_LOCAL_LOGON_ACK, it needs to abort the logon via MSG_LOCAL_LOGOFF before it may try logging on to other connected interfaces.

  When a participant without the interface role receives a mistaken MSG_LOCAL_LOGON from another node, it should respond with MSG_LOCAL_LOGON_REJECTED.

• 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, the node may now send non-local messages. Prerequisite is a paired link. Followed by 8 bytes:

  MSG_LOCAL_LOGON_ACK parameters

  Parameter	Description
  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, as in the MSG_LOCAL_LOGON.

  Note: 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.

  When the node has established paired links with further interfaces, it shall send each of them a MSG_LOCAL_LINK with BIDIB_LINK_NODE_UNAVAILABLE and the names from the descriptor of the accepting interface.

• MSG_LOCAL_LOGON_REJECTED:

  With this message an interface rejects a LOGON or breaks up an existing control relation. The interface henceforth sends only local messages. Followed by 7 bytes:

  MSG_LOCAL_LOGON_REJECTED parameters

  Parameter	Description
  UID[7]	The Unique-ID of the affected node.

  The node acknowledges this with a mit MSG_LOCAL_LOGOFF. When the node has established paired links with further interfaces, it shall send a MSG_LOCAL_LINK with BIDIB_LINK_NODE_AVAILABLE to each of them.

• 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 sends and interprets local messages thereafter. The message is also used to decline logon requests (STATUS_PAIRED) of the interface. Followed by 7 bytes:

  MSG_LOCAL_LOGOFF parameters

  Parameter	Description
  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

  Value	Name	Description
  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

  Parameter	Description
  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).