Communication

• Summary

Serial connection

• Specification

BiDiBus

• Specification
• Background information

Network

• Specification
• Background information

netBiDiB

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. TCP transport
    • 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 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 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 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 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 participant 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. 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 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 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 accounce 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    <servicename>._bidib._tcp.local.   shared   TTL=75min (4500s)
   _node._sub._bidib._tcp.local.   PTR    <servicename>._bidib._tcp.local.   shared   TTL=75min (4500s)
<servicename>._bidib._tcp.local.   SRV    <hostname>.local.:<BiDiB-Port>     unique   TTL=75min (4500s)
<servicename>._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  7
  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. 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 ::= 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

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.

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

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_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  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"
                                                                          <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  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 correspondly 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.
  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 node 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).