Protocol Capture
A detailed Wireshark capture of the communication between the user interfaces and the Gateway is described below, the goal is help people interested in the development of new user interfaces for Souliss with a simplified guide. This doesn't cover all the available functional codes, but gives an overview of the most used.
You can found a complete description of the protocols used in Souliss in these two pages:
The Wireshark file capture can be downloaded at this link. Please note that this doesn't cover the communication between nodes.
The Ping is a communication check that can be used to verify the functionality of the communication channel, this shall not be confused with the ICMP Ping, because is relevant the MaCaco protocol.
The capture shows the complete frame that is build as a MaCaco frame transported over vNet that in case of communication between an user interface and the Gateway is then encapsulated into an UDP frame. The Gateway is listening on UDP port 230, in the example the user interface send and then listed on port 23000 but any port can be used for the scope.
The string highlighted in blue is the vNet frame with MaCaco as payload, the first two bytes are the lengths of the whole frame, those are two because the packed is stripped two times. In this example the first value is 0x0C that once stripped gives a frame of 0x0B bytes.
The 0x17 is the vNet port used to transport MaCaco and is actually the only one used in the MaCaco implementation, following two bytes are the addresses of the vNet transportation: 0x0058 is the destination (Gateway) vNet address and the 0x43A2 is the source (User Interface) vNet address. The vNet addresses reserved for the user interfaces are in the range 0x0100 - 0x64FF (details here).
Starting from this point, the other bytes are MaCaco ones, the first byte is the functional code 0x08 that is the ping one. All functional codes and relevant frame structure are described in the MaCaco wiki page.
Note that all the other frames are different only for the MaCaco frame, because the transportation is always IP based for this type of communication.
The Database Structure contains the information required to build the structure of the user interface database, this contains number of nodes and slots as per Data Structure.
The nodes provide upon Typical Request the list of the Typicals that are then used to complete the database information. These data inform the user interface of all the functionality available for each node.
For each node is returned a dedicated frame with the relevant node ID.
The node Healthy provide a quick overview of the networking state, a network in a good state should have values above 80%. These values are used by the gateway to poll data from peers using dynamical intervals. A network in a good state is completely event-based and a rate of polling comes only if there are missing answers due to a bad communication channel.
The communication between the user interfaces and the gateway is on event base, so once started the connection the user interface shall subscribe data with a State Request and then wait for updates.
Each user interface can make a single subscription and every new subscription override the previous one, so that all node of interest (generally all node of the network) shall be subscribed with a unique subscription request. The subscribed nodes reply with a subscription answer that contains the node data, every change in those data is automatically transmitted to all subscribers.
Note that the user interface subscribe the gateway node, the gateway then subscribe the relevant node in the network, this gives an abstraction from the user interface point of view that doesn't need to know how to route the frames to each node.
The subscription is stored at runtime only, so your node should periodically renew the subscription at a low enough rate to keep an event based communication.
The Data Poll can be used to quickly refresh data from a single or multiple node without overriding the previous subscription. This shall be used if the user request a refresh of the data.
This method shall be linked to a manual action of the user, because once requested a data, the gateway assume that your subscription link has failed to provide data and then force all existing subscription to provide data. Using this method in the wrong way will let the communication behave as a polling.
The Force allow the user interface to write into an arbitrary node, this is generally used to send command. Commands available depends on node Typicals.
As state before once subscribed a node, data communication became asynchronous and new data update can came at any time. The user interface shall keep its UDP socket in listening state for all time.
