Base API message class
Virtually all Plegma API messages inherit from this
ApiMsg abstract class:
This base class contains just the sequence number of the message:
SeqNo: the unique Id of this particular message.
- it is mandatory for the Cloud to set this to a unique, monotonically increasing number in every message towards Nodes, so that you can identify lost messages (after all, embedded Nodes are allowed to have their own sleep schedules)
- While it is not mandatory for Nodes to set this field in the messages they send to the Cloud, it is advised, so that cloud code can perform rejection of duplicate messages.
However, even if you implement sequence numbering for messages, you can bypass it for individual messages by setting
SeqNoto 0 for these messages. Those messages will always be handled by the cloud, without checking sequence numbers.
Suffixes in all Plegma API messages provide information about the kind of message. In message and with a singular exception, all messages are blocking ones and expect a response, even if the latter is a generic “ack”-type one.
- Req means that the sender (either the node or the cloud server) sends actionable data and expects an answer in the form of an Rsp message.
- Rsp means that the message is a response to a preceding message, either containing actual data or acting as an Acknowledge message.
- Get is a call to action. It contains no actionable information itself but contains a request for the receiver to send something back. The sender blocks until the reply is received.
- Set is either the reply to a previous Get-type message, or a new message that directly sends new information. The latter case still expects an ACK which is usually a
- Msg is an asynchronous message originating at any time from the Node or from the Cloud that does not expect an answer. There are precious few of those, currently limited to status-updated events
As mentioned, synchronous request-type messages require responses, and sometimes those are generic ACK-type response that offer little more than confirmation of whether a message was successfully parsed. For those there is the
IsSuccess: basic boolean (ok or not) feedbck on received message
StatusCode: generic integer, the meaning of which, if any, depends on actual message exchange
Message: human readable text containing status for received message