Collaborative Open Market to Place Objects at your Service

(1)

FP7-317862—COMPOSE Collaborative Open Market to Place Objects at your Service

Collaborative Open Market to Place

Objects at your Service

D2.4.1

Prototype of the object actuation specification and

components

Project Acronym COMPOSE

Project Title Collaborative Open Market to Place Objects at your Service

Project Number 317862

Work Package WP2 Objects as a Service

Lead Beneficiary BSC

Editor David Carrera BSC

Reviewer Charalampos Doukas CREATE-NET

Reviewer Lukasz Radziwonowicz FOKUS

Dissemination Level PU

Contractual Delivery Date 30/04/2014

Actual Delivery Date 30/04/2014

(2)

Abstract

Object actuation is one of the challenges of the Internet of Things. COMPOSE provides a rich platform to develop IoT-based services that focuses mainly on object data manipulation, but that does not forget about actuation.

This document describes how actuation is tackled in this initial prototype of the COMPOSE platform. Several client libraries are developed to provide capabilities to interact with the platform: from relatively powerful smart phones (mainly Android at this stage) to really lightweight devices such as the Arduino are covered at this point.

The communication between the platform and devices can be driven through a REST API or through a MQTT transport in the current version of servIoTicy. MQTT has been chosen because of its convenience for low-power IoT devices. Therefore, MQTT has been chosen as the transport to deliver actuation requests to the devices, defining a topic structure and a data model for initiating actuations on devices. The MQTT transport can be optionally used to interact with the platform and completely avoid the use of the REST API by small devices. The document is accompanied by two videos that show how the platform is leveraged to deliver actions, first using the COMPOSE MobileSDK on an Android device, and later in an Arduino device using the client library developed in the scope of the project. Additionally, the servioticy virtual appliance is enabled with some sample code for emulation of actuation requests dispatching.

(3)

Document History

Version Date Comments

V0.1 08/04/2014 Initial draft by BSC, U-HOPPER and CREATE-NET

V0.2 14/04/2014 Refined version

V0.3 21/04/2014 Changed structure

V0.4 27/04/2014 Added demos

V0.5 29/04/2014 Complete draft, revisions merged

(4)

FP7-317862—COMPOSE Collaborative Open Market to Place Objects at your Service 4.1 Android SDK ... 20 4.1.1 Installation ... 21 4.1.2 Example Usage ... 21 4.2 Titanium COMPOSE SDK ... 23 4.2.1 Installation ... 23 4.2.2 Example Usage ... 24 4.3 JavaScript COMPOSE SDK ... 27 4.4 NodeJS COMPOSE SDK ... 28

5 COMPOSE Client Library for the Arduino ... 29

5.1 Installation ... 29

5.1.1 Usage ... 29

6 High level Architecture of the actuation dispatcher ... 31

6.1 Components ... 32

6.2 Kestrel... 32

6.3 Storm ... 32

6.4 Apollo (message Broker for MQTT and WS/STOMP) ... 32

6.5 MQTT/REST Bridge ... 32

7 Data Models and actuation API design ... 34

7.1 Actuation API design ... 34

7.2 Get Actuations ... 35

7.3 Launch Actuation... 35

7.4 Get Actuation Status ... 36

7.5 Update Actuation Status ... 36

7.6 Data Models ... 37

7.6.1 Data Model for MQTT bridging ... 37

(6)

7.7 Storage ... 39

8 Future Directions ... 41

8.1 Automatic deployment ... 41

8.2 More protocols ... 41

8.3 Integration: next steps ... 41

8.3.1 Runtime: CloudFoundry (WP4) ... 41

(7)

List of Figures

Figure 1: COMPOSE platform architecture – the data processing plane ... 31

Figure 2: Actuations API design ... 34

Figure 3: Get all actuations sequence diagram ... 35

Figure 4: Initiate an actuation sequence diagram ... 35

Figure 5: Check actuation status sequence diagram ... 36

Figure 6: Send actuation status update sequence diagram ... 36

Figure 7: Actuations data bucket ... 39

List of Tables

Table 1: Service Object creation data model ... 37

Table 2: Service Object creation data model ... 37

Table 3: Example of use of the “actions” element ... 39

(8)

Acronyms

Acronym Meaning

COMPOSE Collaborative Open Market to Place Objects at your Service

SO Service Objects

JSON JavaScript Object Notation

(9)

1 Introduction

In this deliverable we will focus on defining the Work Package 2 prototype of the Object actuation, and provides details about the architecture, implementation and deployment of the prototype.

In a nutshell, we will start from the summary of all the online resources provided by the Work Package related to this deliverable. We continue with an overview of the architecture used and the different elements and open source resources developed. We also describe the design and the implementation of the different components developed. Finally we explain the source code organization and present an example of use of the prototype, which demonstrates how an online application can use the prototype to overlay data on top of an online map. Finally, future directions are discussed.

2 Summary of online resources delivered

The following are the online resources delivered from WP2. Those are freely accessible and available and includes source code, documentation, a testing environment a running instance and a demo.

2.1 COMPOSE Mobile SDK

This is a set of libraries that should support the development of applications based on COMPOSE. The libraries target the main community of developers, including (i) mobile applications developers (Android and Titanium SDK) (ii) web developers (iii) NodeJs developers.

Titanium is a cross-platform development environment, which allows developers to write mobile applications JavaScript and translate them into hybrid native and JavaScript code for both iOS and Android. This is deemed as strategic for COMPOSE, since (i) there is a growing community of developers, (ii) Titanium also hosts a libraries market place that can be used to promote the SDK to a wide community (iii) it allows to easily target both Android and iOS applications.

Finally, we target web developers in general, including mobile Web Developers and backend developers relying on NodeJS. NodeJS is gaining tractions among web application developers

Disclaimer: Parts of this document are shared across D2.2.1, D2.3.2 and D2.4.1 because the

components used for implementing the Object Registry and Data Repository (D2.2.1), the Object Composition components (D2.3.2) and the Object Actuation components (D2.4.1) are closely interrelated. Also some of the online resources are explained in each deliverable (like the online portal, service and virtual appliance). As we assume each deliverable must be self-contained, we have decided to include all relevant documentation in all of them.

(10)

thanks to its ability to dynamically support complex applications and its simplicity due to JavaScript, which is the programming language used to develop applications in NodeJS.

2.2 COMPOSE Client Library for the Arduino

The COMPOSE Client Library for the Arduino is a sketch that can be imported into any project and provides functionality for easily storing sensor data on a Service Object (SO) created through servIoTicy, as well as to process and implement actuation requests.

2.3 servIoTicy portal

Servioticy is the project that comprehends the data processing platform in COMPOSE. It is an self-contained project that works by itself, and that integrates with other components developed in COMPOSE. The projects portal can be found at: servioticy.com

There can be found documentation, tutorials, references to the online resources, demos, videos and a form to request access to the online instance of the project.

In the servIoTicy portal can be found most of the different aspects related with WP2. There are sections related to the project documentation, the API reference, links to the sample online demo and a link to the all-in-one Virtual Appliance among others.

The servIoTicy portal is the linked space where WP2 centralized all the online resources used in the project. Can be found links to the end user API reference (http://docs.servioticy.com/), the GitHub sources (https://github.com/servioticy/servioticy) and more. The available contents will be presented in the following sections.

2.4 Source Code on GitHub

We use GitHub (http://www.github.com) as our web-based hosting service for the software development using the Git revision control system. All the source code involved in the implementation of the data processing infrastructure is released under the Apache License. The code related to the data processing platform can be found at: https://github.com/servioticy and https://github.com/compose-eu/servioticy

The COMPOSE Mobile SDK (client libraries developed at CREATE-NET and U-HOPPER) can be found at: https://github.com/compose-eu/MobileSDK

The COMPOSE Library for the Arduino is being released at https://github.com/compose-eu/COMPOSE_client_libraries

2.5 Virtual Appliance

Another offered resource is a virtual machine image with all servioticy software parts installed, configured and running in it. The purpose of this is to ease the processes of try and evaluate the whole platform without the need of installing each component.

Its properties:

(11)

• Guest properties:

o OS: Ubuntu 12.04.4 LTS

o Network configuration: 2 DHCP interfaces (eth0 NAT for external routing, eth1 internal bridge for communication with the host)

o User: servioticy o Password: servioticy

o Root access: use “sudo su” and provide the pasword of the servioticy user Changes in v0.3 (released 22/April/2014):

• Added support for actuations (see actuation section in the API documentation) through MQTT

• The action requests will be published under the topic “SO id/actions” in real time • Actions can be updated and their status can be checked

• Added demo files for simulating actuations (located in demo/actuation) Changes in v0.2 (released 15/April/2014):

• Added MQTT subscriptions (see example in this page) • The updates will be published under the topic

“API_TOKEN/SO_id/streams/streamID/updates” in real time • Added demo files for simulating MQTT subscriptions (located in

demo/mqtt_subscription) – uses the same SO than the map demo Features in v0.1 (released 07/April/2014):

• Pre-created API user: • username: servioticy o API token: M2JhMmRkMDEtZTAwZi00ODM5LThmYTktOGU4NjNjYmJmMjc5N2Uz NzYwNWItNTc2ZS00MGVlLTgyNTMtNTgzMmJhZjA0ZmIy • Ports: o API: 8080

o MQTT: 1883 (user: compose, password: shines)

o Coucbhase Admin Console: 8091 (user: admin / password: password) o ElasticSearch console: 9200 (<vm>:9200/_plugin/head/)

o Demo application: http://<vm>:8090 • servIoTicy platform:

o Couchbase 2.2 Enterprise

o STORM 0.9.1-incubating (running in jar mode, not distributed) o Kestrel 2.9.2-2.4.1

o Jetty 8.1.11.v20130520 o ElasticSearch 1.0.1

(12)

o Java(TM) SE Runtime Environment (build 1.7.0_51-b13) - Oracle o User management DB: Flask and SQLite

o Apache Apollo 1.7 o NodeJS v0.6.12 • Protocols:

o HTTP: REST interface available at http://docs.servioticy.com o MQTT: Payload format described in 2.2.1 deliverable • Start/Stop servioticy:

o startAll.sh - starts all services o stopAll.sh - stops all services

• User management: (files located in folder `scripts`) o Create a new user: create_user.sh <username>

o Check api token for a user: get_api_token.sh <username> o List all existing users and api tokens: get_all_tokens.sh o Clear all users from de DB: clear_usersDB.sh

• Pre-loaded (fake) data:

o Temperature and location sensor - ID:

1396461657731411aa73c28444ecf9a8c803e62312fd1 o Fake positions in a map

o Provided scripts to generate new values, get all existing values, get latest value and clear all SO data (located at /home/servioticy/demo/map/utils)

• Demos:

o Demo map with heatmap features (requires Internet access on the client browser)

o Script to start the demo: /home/servioticy/demo/map/start.sh o Script to stop the demo: /home/servioticy/demo/map/stop.sh o HTTP server: <VM ip>:8090

2.6 Online Documentation

Under servIoTicy portal we have located the documentation section (http://www.servioticy.com/?page_id=27). This section provides documentation related to the API Installation; a simple Service Object lifecycle complete example (creation, getting, putting data into it, etc...), a Service Object use data model explanation and more.

As we have explained before, all the sources showed in the documentation are provided via GitHub Gist (https://gist.github.com/). Every time a Gist is modified, automatically, the documentation shows the last version.

(13)

2.7 Interactive API documentation

The Apiary platform (http://www.apiary.io) as a RESTful API documentation engine. Under http://docs.servioticy.com/ can be found every API path fully documented (URL-pattern, http request, response, etc...)

Apiary uses the API Blueprint (http://apiblueprint.org/) as the description document format. API Blueprint is a documentation-oriented API description language. API Blueprint is developed for designing Web APIs and its comprehensive documentation, but also for quick prototyping and collaboration. API Blueprint is a pure Markdown language.

2.8 Online Service

An online servIoTicy service has been deployed. The API is available at api.servioticy.com and registration is open to external participants under request at:

http://www.servioticy.com/?page_id=73

The online service can also be reached through other protocols, such as MQTT and WebSockets at URL api.servioticy.com:1833. More details about support for other protocols can be found in D2.4.1.

2.9 Demos

2.9.1 Actuation Dispatching

Brief demonstration of the capabilities of COMPOSE to deliver actuation requests with parameters to devices using the Service Objects abstraction and the public servioticy service. For such purpose, MQTT is leveraged as the transport between the platform and the devices.

2.9.2 COMPOSE Mobile SDK

The demo showcases the use of the Titanium mobile SDK for the delivery of messages over MQTT to/from the COMPOSE data platform (serviocity). This includes both the delivery of messages as well as the handling of actuations messages/commands.

2.9.3 COMPOSE Client Library for the Arduino

The demo shows the use of the COMPOSE Client Library for the Arduino to implement actuations on lightweight devices, based on the Arduino in this case. The demo starts with an actuation being initiated from a REST Client towards the COMPOSE data processing platform (servIoTicy), which is placed on an MQTT topic to which the Arduino is subscribed. When the actuation, blinking a led, is started, the led on the device blinks, until the actuation to stop blinking is sent afterwards.

(14)

3 Demos

The actuation demos are three: the first part is about actuation dispatching, from external invokers to the WebObjects and physical devices through MQTT; the second part is about using the MobileSDK to receive notifications in the form of actuations through the platform, and closely related to the project Pilots; finally the third demo is about the use of the COMPOSE Library for the Arduino, where actions (LED blinking) are forwarded to an Arduino device. A video with the demos has been recorded and delivered complementary to this document. It can be also seen at: http://youtu.be/d0R5qYdLEQs

3.1 Actuation dispatching

The first demo is provided though the servIoTicy virtual appliance. It consists of two pieces of code: the first one is a python script to invoke actuations on a registered ServiceObject. In particular the actuation is “reboot”. A listener code is also provided, which is in charge to subscribe to a MQTT topic and receive the invocation when it is launched. This demo showcases the use of the actuation dispatcher to deliver actuation invocations to the devices using MQTT as a transport.

More details about the Virtual Appliance and its contents can be found at: http://www.servioticy.com/?page_id=317

3.2 Mobile SDK

The demo showcase the use of the Titanium mobile SDK for the delivery of messages over MQTT to/from the COMPOSE data platform (serviocity). This includes both the delivery of messages as well as the handling of actuations messages/commands.

The demo implements a shared shopping list use case, which supports customers during their shopping experience through a mobile application. A Service Object is associated to each customer in the store. A position update is send to the backend while the customer moves inside the store and updates the corresponding Service Object status. This can be used to, e.g., deliver location-based content.

(15)

Each customer also runs a shared shopping list service, which synchronizes the shopping list across the various family members. A Service Object also models such shopping list. Actuations messages are used to synchronize the shopping list across all devices registered to a given Service Object.

(16)

Finally, a Service Objects is also registered for each product in the store. Customers can dynamically retrieve the accompanying information associated to each product through the COMPOSE platform. This includes detailed information on the product (e.g., ingredients, provenance information, etc.) as well as associated services (e.g., social sharing, couponing, etc.).

A second demonstration has been also developed using the same Mobile SDK for the case of the Smart Territory Pilot. The demo implements the location visualisation of users inside slopes and ski areas, in addition to contextual information about the slopes (such as POIs or slope information). The smartphone in this case acts both as a sensor and information aggregator for the COMPOSE platform. The information about slope data and the contextual information are stored in appropriate Service Objects (SOs) in servIoTicy platform. User’s location is provided by the mobile framework used (retrieved either from the GPS sensor or from location estimate through the cellular network) and pushed into a servIoTicy SO that has been created for each user of the application.

When a user is located inside a ski area, a geolocation query is performed for a) retrieving the SOs with coordinates close to the user that contain slope information and b) retrieving user SOs with coordinates close to the user. For the latter only the coordinates are used to display user icons on the map. Information updates towards COMPOSE and retrieval is performed using the Mobile SDK.

(17)

For demo purposes the locations of users (both the user with the active application and other users inside the ski area) have been simulated by pushing virtual coordinates through a web interface. The interface utilises the JavaScript client to push virtual coordinates for users to SOs.

3.3 COMPOSE Arduino Client Library

The demo shows the use of the COMPOSE Client Library for the Arduino to implement actuations on lightweight devices, based on the Arduino in this case. The demo starts with an actuation being initiated from a REST Client towards the COMPOSE data processing platform (servIoTicy), which is placed on an MQTT topic to which the Arduino is subscribed. For the REST Client, NodeRED interface has been used. Three input nodes named after RED, GREEN and BLUE, generate a HTTP request towards servIoTicy that contains the respective colour as an actuation parameter. When the node is clicked, the connected RGB LED on an Arduino device changes to the appropriate colour. The Arduino is connected with the Internet and servIoTicy using an Ethernet interface and using MQTT is subscribed to the actuations of a custom SO created for the demo purpose.

(18)

3.4 What is being demonstrated?

The demo shows the following features of the platform:

• Usage of MQTT to receive actuations (notifications) and data subscriptions through the servIoTicy platform

(19)

• Interaction between the COMPOSE Mobile SDK running on an Android device and the servIoTicy platform.

• Interaction between the COMPOSE Library for the Arduino device and the servIoTicy platform.

• Usage of MQTT as the transport to interact with the platform (requests/responses) instead of the REST API.

• servIoTicy ability to dispatch actuation requests to the devices using MQTT

The demos are supported by two videos that show the interaction of the devices with the platform.

(20)

4 COMPOSE Mobile SDK

In this section, we will report on the work done for developing the initial version of COMPOSE Mobile SDK. This is a set of libraries that should support the development of applications based on COMPOSE. The libraries target the main community of developers, including (i) mobile applications developers (ii) web developers (iii) NodeJs developers. For the first category, we decided to target Android developers, since they are considered as early adopters of novel technologies and frameworks. In a later stage, we will consider whether to also include a version of the SDK for iOS developers.

In order to address both platforms, we also developed a version of the mobile SDK for Titanium developers. Titanium is a cross-platform development environment, which allows developers to write mobile applications JavaScript and translate them into hybrid native and JavaScript code for both iOS and Android. This is deemed as strategic for COMPOSE, since (i) there is a growing community of developers, (ii) Titanium also hosts a libraries market place that can be used to promote the SDK to a wide community (iii) it allows to easily target both Android and iOS applications.

Finally, we target web developers in general, including mobile Web Developers and backend developers relying on NodeJS. NodeJS is gaining tractions among web application developers thanks to its ability to dynamically support complex applications and its simplicity due to JavaScript, which is the programming language used to develop applications in NodeJS.

In the remaining of this section, we will describe the Mobile SDK for each one of the considered platforms.

4.1 Android SDK

Beyond the generic SDK that is being developed using the Titanium platform (see Section 4.2) we are implemented COMPOSE libraries (SDKs) for native smartphone environments, i.e. for Android and iOS. Currently an initial version of the Android SDK has been developed and released on Github (https://github.com/compose-eu/MobileSDK/tree/master/Native). The SDK abstracts all the complexity of:

• Composing the JSON message that contains the information to be stored in a Service Object

• Making the HTTP REST request in the background so that the application does not hang until the request is submitted

• Running a service in the background that accepts incoming data (e.g., notifications) over COMPOSE subscription channels.

(21)

4.1.1 Installation

Import the COMPOSE Library (Android->Library->COMPOSE_Android.jar) into your Android project.

Edit the AndroidManifest.xml file and add the following: -- before the application tag:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.INTERNET" />

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <uses-permission android:name="android.permission.READ_PHONE_STATE"/>

-- inside the application tag: <service android:enabled="true" android:name="org.compose.mobilesdk.android.COMPOSESubService"> <intent-filter> <action android:name="org.compose.mobilesdk.android.COMPOSESubService" /> </intent-filter> </service>

4.1.2 Example Usage

To use the library you need to create a COMPOSEsdk object: COMPOSEsdk compose;

set the following variables accordingly:

private String COMPOSE_API_TOKEN = "YOUR_API_TOKEN"; private String stream_name = "STREAM_NAME";

private String SO_ID = "SERVICE_OBJECT_ID";

and instantiate the COMPOSEsdk object:

compose = new COMPOSEsdk(this, COMPOSE_API_TOKEN);

To store channel data you can use the SO_channel data objects:

SO_channel chn1 = new SO_channel("This is channel's name","this is current value"); compose.addSO_channel(chn1);

(22)

By default, the library will use the Servioticy endpoints (api.servioticy.com) for storing data. To modify these, use the following methods:

compose.setRESTServer(string_server_url, 8010); compose.setMQTTServer(string_mqtt_broker, 1383); compose.setMQTTCredentials("compose", "shines");

To update the SO, simply invoke the updateSO_REST or updateSO_MQTT method: try {

compose.updateSO_REST(stream_name, SO_ID); } catch (Exception e) {

e.printStackTrace(); }

To subscribe to notifications you need to add and register a BroadcastReceiver that will provide you with access to incoming data from the subscription channel:

private BroadcastReceiver mMessageReceiver = new BroadcastReceiver() { @Override

public void onReceive(Context context, Intent intent) { Bundle data = intent.getExtras();

//do something with the data:

System.out.println(data.getString("DATA")); }

};

and the register the BroadcastReceiver inside the onCreate() method of your Activity: LocalBroadcastManager.getInstance(this).registerReceiver(mMessageReceiver, new IntentFilter("COMPOSE"));

In addition to this, you need to also subscribe to a specific SO topic for notifications: compose.subscribe_MQTT(true, "TOPIC/to");

(23)

4.2 Titanium COMPOSE SDK

We developed a COMPOSE SDK library for Appcelerator Titanium1, which is a cross-platform development environment that allows developers to write applications in JavaScript language and translate them into hybrid native and JavaScript code for iOS and Android devices. Such cross-platform environments are gaining traction thanks to their ability to speed-up the development of applications. Furthermore, there is an extensive community of Titanium developers, and a Titanium Marketplace where to find specific modules and libraries. This is expected to support COMPOSE to reach out a sufficiently wide community of developers, and to support them in the creation of IoT-based mobile applications.

4.2.1 Installation

In order to install COMPOSE Titanium SDK it is necessary to 1. download COMPOSE Titanium SDK zip file and unzip it

2. Move the directory eu.compose.sdk.titanium.mqtt under the directory Titanium/modules/android of the Titanium local installation in case of Android development. A similar library should be moved to Titanium/modules/ios in the case of iOS application development. This is a necessary step in order to use MQTT messaging functionalities, which require also a native library to be installed in the device.

3. Place the COMPOSE Titanium library inapp/lib/(for Alloy) orResources/

Once completed this steps, developers are ready to create COMPOSE-powered mobile applications utilizing the Titanium IDE. In order to do this, it is necessary to create a new project in Titanium and modify the project manifesto by adding the following configuration:

<module platform="android">it.uhopper.mqtt</module> </modules>

This second step is necessary in order to notify the application that an MQTT module is also available for messaging purposes.

Once completed this second step, the project is configured to use COMPOSE mobile SDK and developers can start using all the functionalities enabled by the SDK in order to easily interact with COMPOSE backend, creating Service Objects, and dynamically pushing data or receiving actuation messages.

1

(24)

4.2.2 Example Usage

In the following, we will show how to use the basic functionalities of the SDK. This includes an initial configuration to interact with the COMPOSE backend, and the various functionalities to easily interacting with COMPOSE Service Objects for delivering data, as well as receiving actuation messages.

Initial Configuration

The first step consists in setting up the basic configuration for interacting with COMPOSE. This includes (i) the inclusion of the COMPOSE SDK library (ii) the specification of the Developer API Key, as well as the COMPOSE endpoint.

There can be a minimal configuration, where only the developer key is specified. In this case, it is assumed that the library already knows the specific COMPOSE end-point where to connect. In this case, it is assumed http as the default communication medium. This means that the application will be able to deliver messages to the COMPOSE backend by means of REST calls. In this case, no specific actuations functionalities will be supported.

Alternatively, a more comprehensive configuration can be included. In this case, it is possible to specify the developer API key, as well as the specific COMPOSE endpoint where to connect. In addition it is possible to include different ways of communicating with the backend, choosing among HTTP, WebSockets and MQTT. In the case of WebSockets and MQTT it will also be possible to handle actuation messages.

// include compose io library

var compose = require("compose.io");

// simple setup

compose.setup("<apiKey>");

// detailed setup compose.setup({

apiKey: "api key",

url: "http://api.servioticy.com",

transport: "websocket", // or `mqtt` or `http`, the library will try to take the best one based on the platform

websocket: { // has to match with the transport above

url: "custom WS bridge", port: 8081,

secure: false, // eg `ws` vs `wss` }

});

The API key to be inserted, will be received after the developer registered to the COMPOSE Marketplace through the developers dashboard that is currently being developed in WP6 (details can be found in Deliverable D6.2.1).

(25)

Interacting with Service Objects

After the initialization, developers can start interacting with Service Objects. A Service Object (SO) needs to be firstly registered to the COMPOSE marketplace. Also in this case, the dashboard that is currently being developed in WP6 (details can be found in Deliverable D6.2.1) can be used. At the end of the registration, the system release an Service Object ID that can be used to interact with that given Service Object.

Alternatively, it is possible to create a Service Object directly from the mobile SDK through the developer API key. In this case, the Service Object is created. After the creation, a Service Object ID is returned that can be used to access directly that SO instance.

In the following code snippet, we show how to load a Service Object. In this case, it is assumed that the SO has already been registered to the platform and a SO key is available. In this case, the SO is initially loaded. After the completion of this operation, it is possible to access the various streams of data (e.g., location in this specific example) associated with the SO and start pushing or receiving data. Titanium logging functionalities can be used to debug the proper operations of the SDK2. The model of the SO follows the specification provided in deliverable D2.1. (Design of the object virtualization specification).

// Load by ServiceObject ID

compose.load("ServiceObject Id").then(function(so) {

// this === so, the ServiceObject instance // data will come from any other SO

so.on('data', function(data) {

console.log("New data received for " + this.name); console.log(data);

});

var stream = so.getStream("location"); stream.push({

latitude: 11.123, longitude: 45.321

}).then(function() {

console.log("This callback is optional"); });

}); });

In this second example, a new Service Object is created directly from the mobile SDK. In this case, the complete specification needs to be provided according to D2.1. (Design of the object virtualization specification). This includes a name, description, the definition of the streams and the associated channels. Once created, it possible to start receiving data from the SO.

2

(26)

// create a Service Object compose.create({

name: "Example SO", description: "an example SO", streams: {

"stream_example": {

name: "A stream sample", channels: { myname: { type: "String" } } } } }).then(function() {

this.getStream("stream_example").pull().then(function(data) { console.log("Data for stream " + this.name, data); });

})

Specific SO definitions can be specified directly in the code, or can be read from a definition folder, which contains the json model of the SO. This is expected the sharing and reuse of SO models among developers and applications. In general, a SO model can be defined for each data stream to be collected through a smartphone. Examples include location, accelerometers, etc. In the following example, we will show how to read the model associated to a smartphone.

// Read a definition, e.g., smartphone.json, from definitions/ folder compose.read("smartphone").then(function(smartphoneDefinition) {

// this is the json-based SO representation

console.log("Loaded Json");

console.log(

smartphoneDefinition.toJson() );

return smartphoneDefinition.create()

}).then(function(smartphone) {

// smartphone is the newly service object

console.log("My id is " + smartphone.id); });

(27)

Networking in the COMPOSE SDK

The library completely hides to developers the details of the communication protocol used to communicating between the smartphone and the COMPOSE backend. In particular, currently HTTP, WebSockets and MQTT are supported.

HTTP allows to use REST requests to deliver data to the COMPOSE backend. Each request comes with the developer KEY and the SO KEY. Or alternatively, can be used to create SO. However, no actuations can be supported through HTTP. This is due to the fact that COMPOSE has no way to deliver call backs to the specific SO.

MQTT is also implemented. MQTT allows to create bi-directional streams between Service Objects and COMPOSE. One direction is being used to deliver data from the Smartphone to the COMPOSE backend. The opposite direction is used to receive notifications messages.

WebSockets offer similar functionalities to MQTT. Also in this case, a bi-direction channel is opened between the smartphone and the COMPOSE backend. At the reception of messages, a specific handler is used for interaction with actuation messages. The specific logic of the Handlers will be specified by developers 3.

4.3 JavaScript COMPOSE SDK

The same library also works for native JavaScript. This will allow developers of web-based applications to easily augment their applications with data originating from COMPOSE Service Objects.

In order to use the library, it is necessary to include the following JavaScript library in the web application being developed:

Once this library is loaded, it is necessary to initialize it with the proper COMPOSE Developer API key, in order to access the main COMPOSE functionalities. The following code snippet shows how to initializing the library .

Compose.ready(function() { Compose.setup("<api key"); Compose.list().then(function(data) { console.log(data); }).catch(function(error) { 3

In a future release of the SDK some default handlers will be provided to, e.g., dynamically modify the configuration of the smartphone.

(28)

console.log(error); });

});

The library supports either require.js for CommonJS spec support. A configuration like this is necessary at the moment (but further improvement could allow to make this automatic) require.config({ paths: { "compose": 'compose.io/index', "utils/List": 'compose.io/utils/List', "bluebird": 'compose.io/vendors/bluebird/browser/bluebird', "client": 'compose.io/client', "WebObject": 'compose.io/WebObject', "ServiceObject": 'compose.io/ServiceObject', "platforms/mqtt/browser": "compose.io/platforms/mqtt/browser", "platforms/websocket/browser": "compose.io/platforms/websocket/browser", "platforms/http/browser": "compose.io/platforms/http/browser" } });

4.4 NodeJS COMPOSE SDK

The same library can also be used to NodeJS. Being developed entirely in JavaScript, the same library can be loaded into NodeJS and used utilizing the same initialization/configuration steps described in Sec. 4.3. The library, once stable, will be installable directly with npm (the Node Package Manager) or from the git repository with a simple command like this:

npm i compose.io

At this point is possible to use the library in NodeJS by including it with the following statement:

(29)

5 COMPOSE Client Library for the Arduino

The COMPOSE Client Library for the Arduino is a sketch that can be imported into any project and provides functionality for easily storing sensor data on a Service Object (SO) created through servIoTicy, as well as to process and implement actuation requests.

5.1 Installation

Simply import the Compose.ino sketch inside your current sketch (Sketch->Add file->Compose.ino)

5.1.1 Usage

You need to be a user of Serviocity with a valid API token (Authorisation key). You need to have created a SO on Servioticy and know the SO ID. Suppose that your SO has the following structure:

{

"name": "Arduino",

"description": "My Arduino Analog Sensor", "streams": { "ArduinoSensor": { "channels": { "temperature": { "type": "float", "unit": "celcius" }, "user": { "type": "string", "unit": "" }, "location": { "type": "string", "unit": "" } }, "type": "sensor" } }, "customFields": {}, "actions": [], "properties": [] }

(30)

To store data you need to do something like:

//Initialise the client object for connectivity: EthernetClient client;

...

void setup() {

...

//Set the Authorisation key from COMPOSE: setAuthkey("YOUR_KEY_GOES_HERE");

//as an example, read an analog pin input: String value = String(analogRead(A0));

//Populate the channels with data setChannelData("temperature", value); setChannelData("user", "arduino"); setChannelData("location", "universe");

//Store the data into the SO, defining the stream name and the Service Object ID:

submitSO("ArduinoSensor",

"1395851631319a3fe402338134ca498cfef5d00fd8ace"); }

It is important to note that it is needed to always name the connection client object as 'client' (e.g., EthernectClient client;)

Other examples are provided in the online repository:

(31)

6 High level Architecture of the actuation dispatcher

The COMPOSE platform leverages different components to implement the logic of Service Objects and Subscriptions. In particular it will consist of a web Front-End (RESTful API) and a data Back-End (CouchBase [4]) in which both the SO data and metadata will be stored, being the former the SO data repository and the latter the SO registry. As the system will be oriented to IoT stream processing, the central data ingestion component will be a scalable stream ingestion topology (STORM [5]) that will process incoming SUs in real time while dispatching subscriptions and queries. For advanced text-based search, the data back-end will be connected with a search engine platform (ElasticSearch [3]). For semantic search, the RDF registry developed in the scope of WP3.1 will be leveraged. Figure 1 illustrates the main components of the data processing plane in the COMPOSE platform architecture.

Figure 1: COMPOSE platform architecture – the data processing plane

SOs logic will be implemented throughout all of these components. The API will be implemented as part of the Front-End, but most of the SOs logic will be deployed as part of the stream processing topology. So the different stages of the SOs will be mapped to different stages of the stream processing topology. Subscription dispatching will be another of these stages and will forward SUs to other internal or external entities. Across the stream processing topology, the platform will keep track of all the data manipulations that take place in the data path That will contribute to maintain the data provenance information chain in COMPOSE. C o u c h B a s e Task Descriptor DATA E la s ti c S e a rc h Kestrel STORM P ro c e s s S u b s c ri p ti o n s S e rv ic e O b je c ts A P I (Da ta a n d M a n a g e m e n t o p s ) O b je c ts , F ro n t – E n d & C o n s u m e rs Historic (past) Real Time (future) Subscribers MQTT HTTP RDF-store queries (JSON-LD)

Front-End Stream-Processing Topology Back-End

Br o k e r (M Q T T , W S )

(32)

Actuations will be ingested by the API and subsequently processed by the stream processing engine, along with Sensor Update processing and subscription dispatching. Actuations are a particular case as they are not associated to sensor updates being sent to the platform. Additionally, actuations have been designed to maintain state. A final consideration about actuations is that they require communication between the platform and the physical devices that is initiated at the platform. For such purpose, MQTT has been taken in this firsst prototype as the transport layer for actuations. Additionally, the same transport has been used to extend the platform and provide a bridging service between MQTT-based devices and the REST API offered in COMPOSE. All these features are described in this document.

6.1 Components

6.2 Kestrel

Kestrel is a scalable distributed message queue system. Each server handles a set of reliable, ordered message queues. When you put a cluster of these servers together, with no cross communication, and pick a server at random whenever you do a set or get, you end up with a reliable, loosely ordered message queue. It is used as the entry point of Actuation Requests to Storm.

6.3 Storm

Storm is a distributed real-time computation system. Similar to how Hadoop provides a set of general primitives for doing batch processing, Storm provides a set of general primitives for doing real-time computation.

To define a workflow in Storm, a topology of “Bolts” must be defined. A “Bolt” is the atomic parallel computation unit. This topology is static, and the only way to modify it is stopping the topology and deploying the modified one.

Actuations are initiated from an individual bolt implemented for such purpose, using a client MQTT library to deliver the action request to the device through the MQTT broker.

6.4 Apollo (message Broker for MQTT and WS/STOMP)

Apache Apollo is the next generation of Apache ActiveMQ, which is a widely used multi-protocol message broker. In COMPOSE, Apollo has been taken in this prototype as the broker between the platform and the MQTT-based clients. MQTT is one of the protocols supported off-the-shelf by Apollo, and is a protocol well-known for being good for low-power devices commonly found in IoT ecosystems.

6.5 MQTT/REST Bridge

To allow external devices to interact with the platform using MQTT as the transport protocol, this prototype implements a NodeJS based bridge that links the REST API and the platform

(33)

MQTT end-point. Therefore, clients can use MQTT to send requests to the platform using a specially designed message format (in which a meta-data header and a request payload is specified), and receive responses using the same channel. The bridge is implemented to support synchronous and asynchronous (data subscriptions) communications between the devices and the platform.

(34)

7 Data Models and actuation API design

7.1 Actuation API design

The actuation API is part of the Service Objects API, which is designed after the following resource diagram.

Figure 2: Actuations API design

Actuations are imitated through the Service Object resource they belong to using a POST method. After being initiated, they are identified by an actuationID, which can be later used to check the actuation status (if updates took place) and to send status updates from the devices.

(35)

7.2 Get Actuations

This operation can be invoked to list the set of actuations that can be initiated on an object.

Figure 3: Get all actuations sequence diagram

7.3 Launch Actuation

This operation can be invoked to initiate an actuation on a remote object.

(36)

7.4 Get Actuation Status

This operation can be invoked to check the status of a previously initiated actuation.

Figure 5: Check actuation status sequence diagram

7.5 Update Actuation Status

This method can be used by the devices to update the status of the actuations

(37)

7.6 Data Models

7.6.1 Data Model for MQTT bridging

REST API is mapped on top of MQTT using the following structure:

{

“meta”: {

“authorization”: “API_TOKEN HERE”, “method”: “PUT/GET/POST”,

“url”: “/full/path/to/destination” },

“body”: {

<STRUCTURE OF THE JSON DOCUMENT YOU SHOULD SEND TO THE REST API> }

}

Table 1: Service Object creation data model An example of how to push data to the platform:

{

“meta”: {

“authorization”: “API_TOKEN HERE”, “method”: “PUT”, “url”: “/13944639303973f5530eab507412d88bef305089a7720/streams/weather” }, “body”: { “lastUpdate”: 1199192932, "channels": { "location": { "current-value": "40.12,-71.34", "unit": "degrees" }, "temperature": { "current-value": 33, "unit": "degrees" } } } }

(38)

An example of how to subscribe to a data stream:

We would POST the following JSON document to the URL:

http://api.servioticy.com/SOid/streams/streamID/subscriptions

Note that the filed “destination” is here the API_TOKEN of the subscriber. Example topic: “M2JhMmRkMDEtZTAwZi00ODM5LThmYTktOGU4NjNjYmJmMjc5N2UzNzYwNWItNTc2ZS00MG VlLTgyNTMtNTgzMmJhZjA0ZmIy/1396461657731411aa73c28444ecf9a8c803e62312fd1/streams/lo cation/updates” { "callback": "pubsub", "destination": "M2JhMmRkMDEtZTAwZi00ODM5LThmYTktOGU4NjNjYmJmMjc5N2UzNzYwNWItNTc2ZS00MGVl LTgyNTMtNTgzMmJhZjA0ZmIy", }

7.6.2 Data Model for Actuations

Invocation: POST “SO/actions” in the REST API, using the body to pass parameters to the device. The body, along with other meta-information, will be passed will be exposed as a JSON document under the “SO id/actions” topic using MQTT.

Coordinated actuation:

SOs will act as simple or composite actuators in COMPOSE. In the scope of object composition, an actuation can be defined as a set of actuations performed through a set actuators, following a pre-defined order. In COMPOSE, basic actuation is driven through SOs. When a SO gets an action invoked through the SO actions API, the action is initiated to on the corresponding WO, which will act as a proxy for the physical actuator. Therefore, if a user needs to be able to manually request the execution of a composite action, it is necessary to create a CSO that includes the desired action, so that the composite action can be properly triggered.

Table 3 shows an example of an action named “reboot devices” that, when invoked, would call in turn the action “reboot” on all the devices that are members of the group “group1”. Note that that some of the members of the group could be also CSOs, each one initiating a coordinated actuation on other entities of the COMPOSE platform.

"actions":[ {

"name":"reboot devices",

(39)

"group": “group1”, "action": "reboot",

} ]

Table 3: Example of use of the “actions” element

7.7 Storage

Information relative to actuations that have been initiated is stored in CouchBase in a dedicated data bucket named “actuations”. This bucket is kept indexed by ElasticSearch for easy retrieving of documents as needed.

Figure 7: Actuations data bucket

The index used in ElasticSearch to map the content of the subscriptions documents is listed in Table 4.

(40)

FP7-317862—COMPOSE Collaborative Open Market to Place Objects at your Service { "mappings": { "couchbaseCheckpoint": { "_source": { "includes": [ "doc.*" ] }, "dynamic_templates": [ { "store_no_index": { "match": "*", "mapping": { "store": "no", "index": "no", "include_in_all": false } } } ] }, "_default_": { "_source": { "includes": [ "meta.*" ] }, "properties": { "doc": { "properties": { "callback": { "type": "string" }, "source": { "type": "string" }, "destination": { "type": "string" }, "stream": { "type": "string" }, "customFields": { "properties": { "groupId": { "type": "string" } } } } }, "meta": { "properties": { "id": { "type": "string" } } } } } } }

(41)

8 Future Directions

8.1 Automatic deployment

Automatic deployment of Service Objects based on the Web Object ability to discover self-properties will be explored in the future. Identifying potential actuations on the device and registering and exposing them in an automatic way is one of the targets that WP2 will face in the future.

8.2 More protocols

Through the use cases developed in COMPOSE it is expected to provide bridges for some other transports, beyond REST and MQTT. WebSockets + STOMP are implicitly available thanks to the use of the Apollo Broker, and would only require to map the data models described in this document to communicate between the platform and the objects, either to manage data or to initiate actuations.

8.3 Integration: next steps

8.3.1 Runtime: CloudFoundry (WP4)

The scripts for integration of the servIoTicy platform into CloudFoundry have been initiated and are currently under development. Some successful tests have taken place within BSC premises. The integration has been performed using the Universal Broker developed in WP4. Further testing is still required, but no major issues are expected in this front. The current use of Apollo as the MQTT broker is experimental, and other options are under consideration.

8.3.2 Security Components (WP5)

An initial integration with the Identity Management component already took place at the REST API, but the use of an MQTT broker is a challenging issue that will have to be addressed. Therefore, a plan for integration of the different security components being developed in WP5 has been defined, and will be executed over the next months.

Collaborative Open Market to Place Objects at your Service