Merge branch 'pyleco-additions' into pyleco-state

Author: BenediktBurger

control_protocol.md

@@ -16,6 +16,7 @@ The transport layer ensures that a message arrives at its destination.
 
 Each {ref}`Coordinator <components.md#coordinator>` shall offer one {ref}`ROUTER <appendix.md#router-sockets>` socket, bound to an address.
 The address consists of a host (this can be the host name, an IP address of the device, or "\*" for all IP addresses of the device) and a port number, for example `*:12345` for all IP addresses at the port `12345`.
+The default port number is 12300.
 
 {ref}`Components <components.md#components>` shall have one DEALER socket connecting to one Coordinator's ROUTER socket.
 
@@ -58,6 +59,9 @@ A message consists of 4 or more frames.
 2. The receiver Full name or Component name, as appropriate.
 3. The sender Full name.
 4. A content header (abbreviated with "H" in examples).
+   1. UUIDv7 as a `conversation id`
+   2. A three byte `message id`
+   3. A one byte `message type`. A value of `0` means "not defined", a value of `1` means JSON encoded.
 5. Message content: The optional payload, which can be 0 or more frames.
 
 
@@ -304,11 +308,14 @@ sequenceDiagram
 Note that the DEALER socket responds with the local Directory and Coordinator addresses to the received Acknowledgment.
 :::
 
+If a not signed in Coordinator tries to sign out from a second one, the latter one does ignore that message.
+If a Coordinator tries to sign out, but the message arrives via a different identity, the sign-out is rejected.
 
 ##### Coordinator updates
 
 Each Coordinator shall keep an up-to-date global {ref}`control_protocol.md#directory` with the Full names of all Components in the Network.
 For this, whenever a Component signs in to or out from its Coordinator, the Coordinator shall notify all the other Coordinators regarding this event.
+For that, the Coordinators sends the other ones the full directory, i.e. all Components and Coordinators connected to the Coordinator.
 The other Coordinators shall update their global Directory according to this message (add or remove an entry).
 
 :::{note}

data_protocol.md

@@ -0,0 +1,58 @@
+# Data protocol
+
+The data protocol transmits messages from `publishers` to `subscribers` via a `proxy server` in a broadcasting fashion.
+
+## Transport layer
+
+The transport layer ensures that a message arrives at its destination.
+
+### Socket configuration
+
+A `proxy server` is the transmitting station, it shall offer an XSUBSCRIBER and an XPUBLISHER socket.
+The two sockets shall be connected, e.g. via the `zmq.proxy_server` method.
+Each of both sockets shall be bound to its own address.
+
+A `Publisher` is a Component, which sends data messages via the data protocol.
+It shall have a PUBLISHER socket connecting to the proxy server's XSUBSCRIBER socket.
+
+A `Subscriber` is a Component, which wants to reveice data messages via the data protocol.
+It shall have a SUBSCRIBER socket connecting to the proxy server's XPUBLISHER socket.
+It should subscribe to the {ref}`Topics <data_protocol.md#topic>` it wants to receive.
+
+:::{note}
+Subscribing to a topic in zmq means to subscribe to all topics which **start** with the given topic name!
+:::
+
+#### Recommended configuration
+
+It is recommended to have a single program with two proxy servers.
+The first one transfers any data and binds its XSUBSCRIBER to port number 11100 and binds its XPUBLISHER to 11099.
+The second one transfers log entries and binds to 11098 and 11097, respectively.
+
+
+## Message format
+
+A Data Protocol Message consists in three or more frames ([#62](https://github.com/pymeasure/leco-protocol/issues/62)):
+1. {ref}`data_protocol.md#topic`
+2. {ref}`data_protocol.md#header`
+3. One or more data frames, the first one is the {ref}`data_protocol.md#content`
+
+### Topic
+
+The topic is the full name of the sending Component. ([#60](https://github.com/pymeasure/leco-protocol/issues/60))
+
+### Header
+
+Similar to the {ref}`control protocol header<control_protocol.md#message_composition>`, the header consists in
+1. UUIDv7
+2. a one byte `message_type` (`0` not defined, `1` JSON, `>127` user defined)
+
+### Content
+
+#### Log message content
+
+For log messages, the content is a JSON encoded list of:
+- `record.asctime`: Timestamp formatted as `'%Y-%m-%d %H:%M:%S'`
+- `record.levelname`: Logger level name
+- `record.name`: Logger name
+- `record.text` (including traceback)

index.rst

@@ -16,6 +16,7 @@
    messages
    network-structure
    control_protocol
+   data_protocol
    glossary
    Hello_world
    appendix