README.md

PWMP - Shared types

This crate contains the actual message definitions, de/serialization and other methods to interact with messages.

Message structure

A "message" is a simple enum that can be one of two variants:

• Request
  • Server requested a resource from the client (node) or vice-versa.
• Response
  • Contains the resource requested by the other party.

Requests and responses contain deeper level variants.

graph TD;
    Message-->Request
    Message-->Response

    Request-.->Ping
    Request-.->Hello
    Request-.->PostResults
    Request-.->PostStats
    Request-.->Bye
    Request-.->GetSetting
    Request-.->GetSettings

    Response-.->Pong
    Response-.->Ok
    Response-.->Reject
    Response-.->Setting
    Response-.->Settings

Loading

Introduction message (Hello)

The Hello message is the first message sent by the client (node) to the server. It contains the MAC address of the client. The server will respond with an Ok message if the client is authorized to communicate with the server.

Message structure:

graph LR;
    Hello-->MAC

Loading

Settings request meeting (GetSettings)

The GetSettings message is sent by the client (node) to the server to request the settings for the node. The server will respond with a Settings message.

Message structure:

graph LR;
    GetSettings-->SN[Setting names...]

Loading

Settings response message (Settings)

The Settings message is sent by the server to the client (node) as a response to a GetSettings message. It contains the settings for the node.

Message structure:

graph LR;
    Settings-->SV[Setting values...]

Loading

The setting values are in the same order as requested in the GetSettings message.

Results posting message (PostResults)

The PostResults message is sent by the client (node) to the server to post measurement results of the node. The server will respond with an Ok message if the results were successfully received.

Message structure:

graph LR;
    PostResults-->Temperature
    PostResults-->Humidity
    PostResults-->AP[Air Pressure]

Loading

Statistics posting message (PostStats)

The PostStats message is sent by the client (node) to the server to post statistics of the node. The server will respond with an Ok message if the statistics were successfully received.

Message structure:

graph LR;
    PostStats-->V[Battery Voltage]
    PostStats-->SSID[WiFi ESSID]
    PostStats-->RSSI[WiFi RSSI]

Loading

Example communication sequence

sequenceDiagram
    Node->>Server: Hello (incl. MAC address)
    Server->>Node: Ok
    Node->>Server: GetSettings [...]
    Server->>Node: Settings [...]
    Node->>Server: PostResults [temperature, humidity, ...]
    Server->>Node: Ok
    Node->>Server: PostStats (node statistics)
    Server->>Node: Ok
    Node->>Server: Bye

Loading

If the node's MAC address is not in the database, it's not authorized to communicate with the server.

sequenceDiagram
    Node->>Server: Hello (incl. MAC address)
    Server->>Node: Reject

Loading

It's also possible to configure the server to abruptly close the socket if the device is unauthorized, instead of sending a Reject response.

Message rules

The node shall only send one PostResults message, duplicates will be rejected and the socket will be abruptly closed. The communication between nodes and the server should be exactly as specified in the diagram above. No more messages should be exchanged.

When the client (node) is done communicating with the server, it shall always:

1. Send a Bye request to the server.
2. Wait until the server closes the connection.

The client library will guarantee the last two two requirements, but not the first one.

Usage of Box<T> types

Message variants use Box<>-ed types for optimizing the size of messages. Boxed types do not have a capacity property, making them up to 8 bytes smaller than their non-boxed counterparts.