Base API message class

ApiMsg

Virtually all Plegma API messages inherit from this ApiMsg abstract class:

    
namespace Yodiwo.API.Plegma
{
  public abstract class ApiMsg
  {
    public int SeqNo;
  }
}
    

    
package com.yodiwo.PlegmaApi;

public abstract class ApiMsg {
    public int SeqNo;
}
    

    
typedef struct Yodiwo_API_Plegma_ApiMsg
{
  int32_t SeqNo;
} Yodiwo_API_Plegma_ApiMsg_t;
    

    
@interface APIMsg : JSONModel

@property (nonatomic) NSInteger SeqNo;

@end
    

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 SeqNo to 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 GenericRsp message.
• 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

GenericRsp

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 GenericRsp message:

    
package com.yodiwo.PlegmaApi;

public abstract class ApiMsg {
    public int SeqNo;
}
    

    
    public class GenericRsp extends ApiMsg {
    {
        public Boolean IsSuccess;
        public int StatusCode;
        public String Message;
    
        public GenericRsp() {
        }
    } 
   

• 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