IoT and Miniservice framework

Push technology notification is the "natural way" to make your IoT device a real time device. The basic features of the Miniservice infrastructure do not allow you to react immediatelly to a status change. This is because the pooling mechanism used by the device makes asyncronous the communication between the miniservices kernel and the device firmware.

In order to create a syncronous communication between the Miniservices kernel and your device we need to use a "proxy" approach. It means that we need to put something in the middle able to facilitate the communication between the central infrastructure and all devices distributed across the internet.

---

---

Such approach is possible thanks to a specific server component named "push server".
The Miniservice infrastructure makes you available a push server that can be used to syncronise your device with the infrastructure. It is named Push Notifier

The Push Notifier component can be used both by the Miniservice infrastructure at every status change or by you whenever you need to push a message to one of your devices.
The syncronization process is very easy:

1) Your device connects to the server opening a socket on a specific port (Those parameters are returned at configuration level)
2) Your device registers itself with the push server passing it the required information. Once the registration is completed, your device remains in wait state listening to the socket
3) If there is a status change (or if you want to send a message to one of your devices) and the Miniservice kernel requires to send to your device a push message, it finds your socket in the list of open sockets and sends you a new configuration xml string
4) Once your device receives the string, parses it and do the right action.
5) Your device continues to stay tuned on the opened socket in order to receive new notifications

The push server is responsible for polling the connection to leave it open (very often routers in the middle could close a connection when no data are registered on the layer2)
The push server is responsible to clean the device list when a socket is closed by the client (you switch off the device or the connection goes down)

It is important to note that, in any case, the "async way" of doing things is still available and can be used in case of failure of the connection to the notifier server.

During the configuration procedure of an IoT device, an xml containing the PushNotifier server for that specific device is returned (if such feature is available for the devType):

                <xml version="1.0" encoding="UTF-8" ?>
            -<IoTConfiguration>
                -<ConfAry>
        <TimeStamp>06/11/2018 08:10:37</TimeStamp>
                -<ConfValue>
        <ConsoleIP />







        <SSID />







        <PWD />







        <VariableName>PushNotifierServer</VariableName>
        <Type>String</Type>
        <Value>buonevacanze.ddns.net</Value>
        <Description>Absolute address of the Push Server</Description>
                </ConfValue>
                -<ConfValue>
        <ConsoleIP />







        <SSID />







        <PWD />







        <VariableName>PushNotifierPort</VariableName>
        <Type>String</Type>
        <Value>8888</Value>
        <Description>listener port of the Push Server</Description>
                </ConfValue>
                    ...
                    ...
            
        

The Variable PushNotifierServer is the one you need to use to resolve the ipaddress of the server. The port is the port used by the server to listen for calls from any device. Note that for security and balancing reasons, these values may change very often. This allow us to create an infrastructure scalable, robust and secure. For this reason, please, always read such parameters at startup or your device could not be reachable by the central infrastructure (or by you) if registered on a wrong server

Once resolved the ip address, your device needs to open a socket to PushNotifierServer using PushNotifierPort. Once the connection has been estabilished you will be able to raise the command needed to register your device on the server.
In the following example we are registering the device 84KM that is a devType 2 (geoReference device) into the device list of the server. EOC command is needed by the server to understand that the command is ended.

                <ADDCLIENT>84KM</ADDCLIENT><DEVTYPE>2</DEVTYPE><EOC>
            
        

Every time the server receives a message trough the open socket it answers with an "ACK" string or with a "NAK" (in angular brackets) based on the action result. If your registration is successfull you will receive an ACK message. In case of problems you will receive a NAK one.

Once successfully registered you can put your device in listening mode on the socket. It will be responsability of the server to:

1) Clean the list in case of socket issue or in case you reopen the connection
2) Pool the socket in order to maintain the connection alive
3) Push you with a notification message in case the central infrastructure needs to communicate with your device

At a certain DET (Device Execution Time) you could receive a configuration string exactly like the one you normally ask using the api function GetIoTConfig.
This configuration string is the push notification message your device was expecting from the PushServer.
My suggestion is to move this string directly to the function your device uses to parse configuration items and execute the command you usually execute for that configuration string.
Once the command has been executed you will be able to return in listening mode

In order to avoid any problem due to connection lost, I would suggest to continue to pool asyncronously with the infrastructure requiring a configuration string at every interval. If the configuration string returned is different from the previous one, then a communication error could have caused a socket disconnection. In this case, my suggestion, is to open again the socket connection to the push server and register again your device.

It is clear that the PushServer is strictly connected with the Miniservices infrastructure but can be used also for different pourpose. More in general it can be used to pass strings of text to any "registered" object. The only thing you need is an access to the infrastructure and a generic device created into the framework. With those information you will be able to register your device but also to send them notifications using the push technology.
To send a push notification you can use the PUSHCOMMAND message. This command can be used to send a string of text to a specific device. The device ID is included in the first node and an authorization token is needed in order "to inform" the server that you have the rights to wake up a specific device.

To receive a valid token to use with this request you need to invoke the SDK function named "Authenticator" to retrieve a valid token to pass to the pushnotifier server. The token will authorise the push server to send the message (you pass into the command string) to the final device selected as destination.

Following an example:

                <PUSHCLIENT>84KM</PUSHCLIENT><TOKEN>ygsetirt8e8c87rf788c78dfbfdfc8fg8gd</TOKEN>This is a test message. it can be XML or anything else<EOC>
            
        

In this example we are asking the server to wake up the device 84KM pushing to it the message: "This is a test message. it can be XML or anything else" Obviously the token is a valid one returned by the infrastructure when requested. If the push notification is properly sent the system will answer with an ACK. In case of problems or if the token is not valid, the system, will return a NAK.

The message sent to your device cannot exceed 200 chars. In this case a NAK answer will be returned from the server.
This value is enough to transmit to yur object a command that can be a simple request to perform a polling followed by some parameters that you want your device to configure internally