Using SIDE to access real time data

In this article we are gonna talk about how we can access the real time metric data and gateway GPS location using SIDE.
(If you do not know what is SIDE then, read this article first, System Integrator Development Environment ). 

Real time metrics

All metrics collect by RuBAN, can be access by simple subscribing to an MQTT topic, "/ruban/devices/data/json/<deviceId>".
Using SIDE, this can be done by simple using the mqtt input node. 
In the Fig1, you can see a simple flow that subscribes to the real time metrics stream, in this case we are subscribing to metrics being collected by any device (that is why the Topic end with #).
To subscribe to the metrics generated only by a given device, you should use the deviceId instead of # (later we explain how can you discover what is the deviceId of a given device). 

Fig1 - How to subscribe to the real time metrics stream

The content of the messages received, is a JSON with the following format:

{
   "tags": {
                 "deviceId": <Integer that is the device ID of the device where the metric was originated>
               },
    "timespamp": <Integer that represents the date, number of milliseconds since 1970, when the metric was generated>,
    "name": <A string that identifies what metric it is with the following format, "MetricEnterpriseId_MetricElementId>,
    "value": <The metric value>
} 

Bellow is an example:

{"tags":{"deviceId":285},"timestamp":1435838197561,"name":"43040_100","value":42}

This message tell us that we are receive the value, 42, for the metric, 43040_100 (the memory usage, in percentage, of the device) on the device with ID, 285.
As you told before, if you want to only subscribe to the metrics originated by a given device then, you need to know its deviceID.
There is a RuBAN rest API that give us information about the devices connected to ruban, sending a GET to http://<rubanServerIP>:58000/eem/api/v1/devices/devices.
The reply is a JSON like this one:

{
    "status": "success",
    "totalRecords": 1,
    "records": [{
        "id": 285,
        "description": "LynxDarva1",
        "telnetStatus": "SCANNING",
        "name": "LynxDarva1",
        "deploymentStatus": 1,
        "heartbeatStatus": "SCANNING",
        "snmpStatus": "SCANNING",
        "serialNumber": "LynxDarva1",
        "isShadowRouter": false,
        "ipAddress": "10.0.3.2"
    }]
}

From this response, given your device serial number, you can get with is is deviceId (in this case, its 285).
In the metric message that we had shown before, the metric name was 43040_100. How to give a meaning to it?
For this we have two choices, consult the metric configuration on the RuBAN UI or, in a programmatic way, we can invoke a rest API.
So, doing a GET on http://<rubanServerIP>:58000/eem/ipfix/informationelements/?enterpriseId=43040&elementId=100 we can retrieve info about the metric with name, "43040_100".
The response is the following JSON:

{

    "fields": [
       {
          "name":"Memory",
          "dataType":"signed32",
          "dataTypeSemantics":"quantity",
          "elementId":"100",
          "enterpriseId":"43040",
          "units":"%",
          "group":"networkStats",
          "description":"Memory usage of edge device "
        }
      ]
}

We have created an example flow, Fig2, that uses what we had talk before to, receive the real time metrics, processing only them for some devices, getting information about the device and metric so that we can then create a user friendly message.
To use this flow, copy the contents of this file, realtimeMetricsFlow.txt to SIDE.
 

Fig2 - Flow example on how to the real time metrics stream

In the previous flow, we are listening to the metrics originated in any device and then, we filter them, "Filter by DeviceId" and "Filter by Metric" nodes. Edit this nodes in order to change what are the devices and metrics to filter by.
You can test this flow without the need to have metrics being publish by triggering the "Testing" node.
 

Real time device position

As with the metrics, the real time position of a device is also published to a mqtt topc.
So, in order to access the real time position of the devices connected to RuBAN, simple subscribing to an MQTT topic, "/ruban/gps/<deviceId>".
In Fig3, you can see a simple flow that subscribes to the real time position stream, in this case we are subscribing to the position of device (that is why the Topic end with #).
To subscribe to the position of only a given device, you should use the deviceId instead of #. 

Fig3 - How to subscribe to the real time position stream

The content of the messages received, is a JSON with the following format:

{
    "timespamp": <Integer that represents the date, number of milliseconds since 1970, when the position was generated>,
    "serialNumber": <The device serial number>,
    "longitude": <Longitude in Decimal Degrees>,
     "latitude": <Latitudein Decimal Degrees>,
     "deviceId": <The device ID> 
} 

Bellow is an example:

{"timestamp":1435839165056,"serialNumber":"LynxDarva1","longitude":-6.2432295,"latitude":53.349128,"deviceId":285}

We have created an example flow, Fig4. 
This flow, uses the real time position information to trigger a message when it moves by a given distance.
To use this flow, copy the contents of this file, realtimeLocationFlow.txt to SIDE.

Fig4 - Flow example on how to the real time metrics stream

In the previous flow, we are listening to the metrics originated in any device and then, we filter them, "Filter by DeviceId". Edit this nodes in order to change what are the devices to use for filter.
You can test this flow without the need to have devices publishing its position by triggering the "Generate Test msg" node. 

Related Articles

• System Integrator Development Environment