Collaborative Open Market to Place Objects at your Service

Transcription

1 Collaborative Open Market to Place Objects at your Service D2.4.1 Prototype of the object actuation specification and components Project Acronym Project Title COMPOSE Project Number 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 Version V1.0 D2.4.1 Prototype of the object actuation specification and components Page 1 of 41

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. D2.4.1 Prototype of the object actuation specification and components Page 2 of 41

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 V1.0 30/04/2014 Final Version D2.4.1 Prototype of the object actuation specification and components Page 3 of 41

4 Table of Contents Abstract... 2 List of Figures... 7 List of Tables... 7 Acronyms Introduction Summary of online resources delivered COMPOSE Mobile SDK COMPOSE Client Library for the Arduino servioticy portal Source Code on GitHub Virtual Appliance Online Documentation Interactive API documentation Online Service Demos Actuation Dispatching COMPOSE Mobile SDK COMPOSE Client Library for the Arduino Demos Actuation dispatching Mobile SDK COMPOSE Arduino Client Library What is being demonstrated? COMPOSE Mobile SDK D2.4.1 Prototype of the object actuation specification and components Page 4 of 41

5 4.1 Android SDK Installation Example Usage Titanium COMPOSE SDK Installation Example Usage JavaScript COMPOSE SDK NodeJS COMPOSE SDK COMPOSE Client Library for the Arduino Installation Usage High level Architecture of the actuation dispatcher Components Kestrel Storm Apollo (message Broker for MQTT and WS/STOMP) MQTT/REST Bridge Data Models and actuation API design Actuation API design Get Actuations Launch Actuation Get Actuation Status Update Actuation Status Data Models Data Model for MQTT bridging Data Model for Actuations D2.4.1 Prototype of the object actuation specification and components Page 5 of 41

6 7.7 Storage Future Directions Automatic deployment More protocols Integration: next steps Runtime: CloudFoundry (WP4) Security Components (WP5) D2.4.1 Prototype of the object actuation specification and components Page 6 of 41

7 List of Figures Figure 1: COMPOSE platform architecture the data processing plane Figure 2: Actuations API design Figure 3: Get all actuations sequence diagram Figure 4: Initiate an actuation sequence diagram Figure 5: Check actuation status sequence diagram Figure 6: Send actuation status update sequence diagram Figure 7: Actuations data bucket List of Tables Table 1: Service Object creation data model Table 2: Service Object creation data model Table 3: Example of use of the actions element Table 4: ElasticSearch Index for Subscriptions bucket D2.4.1 Prototype of the object actuation specification and components Page 7 of 41

8 Acronyms Acronym COMPOSE SO JSON SU Meaning Service Objects JavaScript Object Notation Sensor Update D2.4.1 Prototype of the object actuation specification and components Page 8 of 41

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. 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. 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 D2.4.1 Prototype of the object actuation specification and components Page 9 of 41

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 ( the GitHub sources ( and more. The available contents will be presented in the following sections. 2.4 Source Code on GitHub We use GitHub ( 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: and The COMPOSE Mobile SDK (client libraries developed at CREATE-NET and U-HOPPER) can be found at: The COMPOSE Library for the Arduino is being released at 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: VM format: Virtual Box VDI D2.4.1 Prototype of the object actuation specification and components Page 10 of 41

11 Guest properties: o OS: Ubuntu 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 Ports: o API token: M2JhMmRkMDEtZTAwZi00ODM5LThmYTktOGU4NjNjYmJmMjc5N2Uz NzYwNWItNTc2ZS00MGVlLTgyNTMtNTgzMmJhZjA0ZmIy 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: servioticy platform: o Couchbase 2.2 Enterprise o STORM incubating (running in jar mode, not distributed) o Kestrel o Jetty v o ElasticSearch D2.4.1 Prototype of the object actuation specification and components Page 11 of 41

12 Protocols: 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 v o HTTP: REST interface available at o MQTT: Payload format described in 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: Demos: o Temperature and location sensor - ID: aa73c28444ecf9a8c803e62312fd1 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) 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>: Online Documentation Under servioticy portal we have located the documentation section ( 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 ( Every time a Gist is modified, automatically, the documentation shows the last version. D2.4.1 Prototype of the object actuation specification and components Page 12 of 41

13 2.7 Interactive API documentation The Apiary platform ( as a RESTful API documentation engine. Under can be found every API path fully documented (URL-pattern, http request, response, etc...) Apiary uses the API Blueprint ( 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: 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 D Demos 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 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 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. D2.4.1 Prototype of the object actuation specification and components Page 13 of 41

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: 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: 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. D2.4.1 Prototype of the object actuation specification and components Page 14 of 41

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. D2.4.1 Prototype of the object actuation specification and components Page 15 of 41

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. D2.4.1 Prototype of the object actuation specification and components Page 16 of 41

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. D2.4.1 Prototype of the object actuation specification and components Page 17 of 41

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 D2.4.1 Prototype of the object actuation specification and components Page 18 of 41

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. D2.4.1 Prototype of the object actuation specification and components Page 19 of 41

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 ( 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. Currently only MQTT is implemented as a subscription channel. D2.4.1 Prototype of the object actuation specification and components Page 20 of 41

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> 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); D2.4.1 Prototype of the object actuation specification and components Page 21 of 41

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() 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"); D2.4.1 Prototype of the object actuation specification and components Page 22 of 41

23 4.2 Titanium COMPOSE SDK We developed a COMPOSE SDK library for Appcelerator Titanium 1, 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 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 in app/lib/ (for Alloy) or Resources/ 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: <modules> <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 D2.4.1 Prototype of the object actuation specification and components Page 23 of 41

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: " 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). D2.4.1 Prototype of the object actuation specification and components Page 24 of 41

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 SDK 2. 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: , longitude: ).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 We will provide a specific logging functionality in future releases of the COMPOSE SDK D2.4.1 Prototype of the object actuation specification and components Page 25 of 41

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); ); D2.4.1 Prototype of the object actuation specification and components Page 26 of 41

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 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: <script src="js/compose.io/index.js"></script> 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. D2.4.1 Prototype of the object actuation specification and components Page 27 of 41

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 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: var compose = require('compose.io'); D2.4.1 Prototype of the object actuation specification and components Page 28 of 41

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) 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": [] D2.4.1 Prototype of the object actuation specification and components Page 29 of 41

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", " a3fe ca498cfef5d00fd8ace"); 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: D2.4.1 Prototype of the object actuation specification and components Page 30 of 41

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. Broker (MQTT, WS) Subscribers Objects, Front End & Consumers Service Objects API (Data and Management ops) Task Descriptor DATA Kestrel Process STORM CouchBase ElasticSearch Subscriptions MQTT Real Time (future) RDF-store queries (JSON-LD) HTTP Historic (past) Front-End Stream-Processing Topology Back-End 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. D2.4.1 Prototype of the object actuation specification and components Page 31 of 41

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 multiprotocol 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 offthe-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 D2.4.1 Prototype of the object actuation specification and components Page 32 of 41

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. D2.4.1 Prototype of the object actuation specification and components Page 33 of 41

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. D2.4.1 Prototype of the object actuation specification and components Page 34 of 41

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. Figure 4: Initiate an actuation sequence diagram D2.4.1 Prototype of the object actuation specification and components Page 35 of 41

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 Figure 6: Send actuation status update sequence diagram D2.4.1 Prototype of the object actuation specification and components Page 36 of 41

37 7.6 Data Models 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 : / f5530eab507412d88bef305089a7720/streams/weather, body : { lastupdate : , "channels": { "location": { "current-value": "40.12,-71.34", "unit": "degrees", "temperature": { "current-value": 33, "unit": "degrees" Table 2: Service Object creation data model D2.4.1 Prototype of the object actuation specification and components Page 37 of 41

38 An example of how to subscribe to a data stream: We would POST the following JSON document to the URL: Note that the filed destination is here the API_TOKEN of the subscriber. Example topic: M2JhMmRkMDEtZTAwZi00ODM5LThmYTktOGU4NjNjYmJmMjc5N2UzNzYwNWItNTc2ZS00MG VlLTgyNTMtNTgzMmJhZjA0ZmIy/ aa73c28444ecf9a8c803e62312fd1/streams/lo cation/updates { "callback": "pubsub", "destination": "M2JhMmRkMDEtZTAwZi00ODM5LThmYTktOGU4NjNjYmJmMjc5N2UzNzYwNWItNTc2ZS00MGVl LTgyNTMtNTgzMmJhZjA0ZmIy", 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", "description":"reboots the devices in the group", D2.4.1 Prototype of the object actuation specification and components Page 38 of 41