Connect your device

Jun 3, 2015 |

As described in the introduction to the previous tutorial (Registration and authentication mechanism), the glue.things dashboard supports the development process with features for device and data management, aggregation and manipulation of device data streams and distributed deployment of data stream mashups.

In particular developers can connect devices to glue.things to make them available on the Web. Supported protocols are HTTP/TCP, STOMP/TCP, STOMP/WS, MQTT and CoAP. Glue.things REST API provides communication features (pushing, retrieving and composing data). Glue.things supports JSON-based data models for device updates and the description of the processing model. Web communication protocol provides features for creation and management of pub/sub subscriptions, invocations and status check of actuations. These features are available for developers via client libraries. For a more intuitive registration of devices, the dashboard supports device templates. Devices can be registered via a Web form in a few steps.

Then glue.things integrates a mashup tool to aggregate, manipulate, and mashup data streams from connected devices and developers have also the option to define condition statements, triggers and actions for these mashups of data streams. So through device virtualization, connected devices are centrally managed and accessible from anywhere on the Internet (based on the real-time communication networks Meshblu and PubNub).

Developers can remotely maintain, control and interact with connected devices regardless of their location. Furthermore, developers have the option to monitor the output of connected devices, set offsets, select threshold limits for data streams and modify the data visualization.

Following a schema about the process in order to create a Smart Object on glue.things platform:

Presentation1

So, after the login, in the glue.things dashboard Device Manager main page, select “ Add new device” as shown in the following picture:

into_dev_gluething_platform_2

Once a device is connected, developers will retrieve real-time updates of the device data stream.

Moreover, in parallel, through glue.things platform, you are able to create as well as a smart device on servIoTicy Paltform.

add_smart_object

In “Sensor Type” field you can select a preselected choice:

  • GPS-Sensor
  • Gyroscope

or select “Custom Template” option in order to insert your specific smart device, as described in the following picture:

custom_template

In this way you can create, via glue.things user interface, a Smart Object (also called Service Object) and create the description of the data related to this object (the streams). A Smart Object is the virtual representation of real object or device inside the COMPOSE platform.

The servIoTicy API is a generic service for managing and processing IoT data streams. The “Smart Object” definition document (JSON) has the following attributes. For each stream, the definition document describes:

  • `name`: a string representing a human readable name of the data stream (e.g. location, temperature, etc…)
  • `description`: textual description of the `stream`
  • `channels`: a series of channels for the `stream` (`latitude` and `longitude` for example, so in this case you have to create 2 channels)
  • `unit`: a string describing the nature of the units used for representing the data
  • `type`: data type associated to this channel (may be `number`, `string`, `boolean` or `geo_point`)

For more info about “Actuation(s)” field check the related tutorial chapter “HOW TO USE ACTUATION

Following an example in order to explain how to add and use a “Smart Object” on gluethings platform.

As described in the Registration and authentication mechanism tutorial, after your registration on gluethings paltform you get 2 tokens:

  • glue.things token is the token for the authentication in the glue.things platform
  • user token (access token) is the token that the users get when they login through the IDM system into glue.things platform. Moreover this token will be used by any developers that want to get data from the servIoTicy platform.

In our example we use a Tessel1 physical device, performing light intensity measurement, in order to create a related “Smart Object” on glue.things platform. Click on the “Add New Device” button, in order to start the “Smart Object” creation procedure.

2

For “Actuation(s)”:

3

For more technical developer info check this link about Smart Object Descriptor (JSON file) and about  Create and Manage a Smart Object. Moreover here you can find also an example of  the JSON Smart Object descriptor that could be created for a Cell Phone with accelerometer, GPS and temperature sensors. It would provide raw data for the accelerometer (stream “accelerometer”) and geo-located data for the temperature (stream “located-temperature”).

Here you can find also the APIs related to Smart Object definition.

Your physical device has been “virtualized” through the JSON file and a related smart Smart Object has been created on servIoTicy platform (available in a JSON file format) and in parallel  also on glue.things platform (available through user interface dashboard). A Smart Object is the basic building block for working with data in servIoTicy. It is the virtual counterpart of a physical device (either directly connected to the web or accessible through a gateway). It can be used to publish data generated by the device, to retrieve data stored in servIoTicy, or even to initiate actuations on the devices.

All the details of the Smart Object descriptor format can be found in this section, but here you have a simple working example, related to the previuos Smart Object, to start with!

{
    "name": "Tessel1 Light Sensor",
    "description": "Tessel board performing light intensity measurement",
    "streams": {
        "sensors": {
            "channels": {
                "light": {
                    "type": "number",
                    "unit": "lumen"
                }
            },
            "description": "light measurement",
            "type": "sensor"
        }
    },
    "customFields": {},
    "actions": [{"name": "light","description": "trigger light measurement"}],
    "properties": [] }

On the glue.things Device Manager dashboard you can find your Smart Object just created.

4

N.B. You could create the Smart Object outside glue.things platform using servIoTicy API, but in this case the new “virtual device” will not be registered in glue.things. So it doesn’t appear in the list of smart object above.

Now you can select it, in order to use it. Moreover, simultaneously to the Smart Object creation, a “Smart Object ID” has been created by the servIoTicy platform and it is available also on the glue.things platform. Indeed this ID establishes a unique relation between the physical device and the “virtual” Smart Object on servIoTicy platform. The ID has to be taken into account in order to push/get data from this object.

5

This ID must be used by the physical device in order to send data collected to the servIoTicy related Smart Object or from everyone that want to get data from this specific Smart Object. Moreover an API token, linked to the Smart Object, has been generated. Through this token the physical device is authorized to put data in the related Smart Object on servIoTicy. For more technical developer info (e.g. APIs) on how the data operations are managed, have a look here: Pushing and consuming data documentation.

In this way, servIoTicy can accept the data received from the physical device and forward these data to all associated stream’s subscribers. It can in any case perform a http “get” request on the servIoTicy server (using the above-mentioned token and ID) in order to retrieve the data linked to a specific smart object.

Following an example how to push data on the device and the related data shown in the glue.things dashboard, even under the example mentioned above.

var http = require('http');
var SERVIOTICY_HOST = "api.servioticy.com";
var SERVIOTICY_PORT = 9090;

var pushData = function(api_token, deviceid, streamid, data){

// Configure HTTP Request headers
var headers = {
'Authorization': api_token,
'Content-Type' : 'application/json',
'charset' : 'UTF-8'
};

// Configure HTTP Request options
var options = {
'host': SERVIOTICY_HOST,
'port': SERVIOTICY_PORT,
'path': "/"+deviceid+"/streams/"+streamid,
'method': 'PUT',
'headers': headers
};

// Define HTTP Request callback
var http_req = http.request(options,
function(res) {
res.setEncoding('utf8');
res.on('data', function (response) {
console.log(response);
});
});

// Set HTTP Request body
http_req.write(data);

// Minimal error management
http_req.on('error', function(e) {
console.error(e);
});

// Perform HTTP Request
http_req.end();
};

var device_id = "<DEVICE ID>"; // id of the destination device
var stream_id = "sensors"; // name of the destination stream
var api_token = "<API TOKEN>" ;// API token associated to destination device
var data= {
"channels":{
"light":{
"current-value": 1.23456,
"unit": "lumen"
}
},
"lastUpdate": 1444223009
};
data = JSON.stringify(data); // The update we want to submit

pushData (api_token, device_id, stream_id, data);

Smart Objects are exposed through a RESTful API that uses HTTP as a transport and that acts as the Smart Object front-end. This basically implies that Smart Objects can be identified unambiguously using uniques URIs. The API provides resource actuations through the four main HTTP operations: GET (retrieve), POST (create), PUT (update) and DELETE. The following table summarizes the COMPOSE Smart Objects API. In the table, <soId> represents the unique ID associated to each Smart Object registered in the platform (as described before about Smart Object ID).

table

 

Posted in: Basic tutorials, Tutorials

Comments are closed.