CIMA documentation

1 Project objectives 1.1 Study of existing needs 1.2 Solution chosen 2 State of the work 2.1 Description 2.1.1 What is inside the CIMA platform 2.1.2 Global architecture schema (deployment diagram) 2.1.2.1 OM2M 2.1.2.1.1 state of the art (synthèse TER + nouvelles contraintes) 2.1.2.1.2 platform choice 2.1.2.2 Discovery layer 2.1.2.2.1 Discovery bundle in OM2M 2.1.2.2.1.1 Detecting new connection 2.1.2.2.1.2 Object Identification(to complete, now just for testing) 2.1.2.2.2 Semantic management of object capabilities 2.1.2.2.2.1 Identification and descritpion of capabilities 2.1.2.2.2.2 Reuse of work from the ASAWoO project 2.1.2.3 Infrastructure controller (NSCL) 2.1.2.3.1 Client notification system 2.1.2.4 Access to an objet via the gateway 2.1.2.4.1 Access via OM2M : DeviceController 2.1.2.4.2 Direct access : port forwarding (to complete, unfinished) 2.1.2.5 Discovery server on the object 2.1.2.5.1 OSGi (Equinox) 2.1.2.5.2 SAJE (unfinished, to complete) 2.1.2.5.3 Capability provider (object specific) 2.1.3 Internal functioning 2.1.3.1 OSGi / OM2M (links to docs) 2.1.3.2 Static diagrams (classes: domaine + implem) 2.1.3.3 Dynamic diagrams (communication) 3 HOW TO USE CIMA 3.1 Installation 3.1.1 Cloud 3.1.2 Gateway 3.1.3 Object : Installation on the object 3.2 Use 3.2.1 Client 3.2.1.1 Connection to the NSCL 3.2.1.1.1 Registering : post on InfrastructureController

1/17 3.2.1.1.2 Notification system : several methods, OM2M­based 3.2.1.2 InfrastructureController API 3.2.2 Creating a server on the object 3.2.2.1 ServerInfos & WotCapabilityExposer APIs 4 Remaining work / perspectives 4.1 Complete / test unfinished parts 4.2 Create a manual configuration interface for new objects 4.3 Implement other servers / CapabilityProviders 4.4 Create a "lightweight server" for resource limited objects 4.5 Manage objects not connected with IP (USB, HDMI...)

1 Project objectives

1.1 Study of existing needs

1.2 Solution chosen

2 State of the work

2.1 Description

2.1.1 What is inside the CIMA platform Layer­platform interoperability Materials Applications (CIMA) is a project to meet needs unmet by existing within the LIRIS platforms to facilitate the reuse of common hardware for many types of applications, it either as part of experiments for research and demonstrations to external partners. This platform will be installed on a dedicated structured framework in several layers machine. Needs expressed by this project will be listed in detail in the section of the state of the art (below). ❏ OASIS : is a platform that relies on a server to retrieve the flow of video cameras and send it to one or more clients through the network in real time. ❏ Voir : is a platform that allows both to create new recognition algorithms and use these algorithms for higher level applications. ❏ UbiWare : is an application level protocol developed for accessing data by exposing the data in REST services, peer to peer. ❏ PupInt : is a platform for the use of various hardware components of interaction (screens, touch screens, ...). Based on the OM2M framework, we developed the CIMA platform that is composed of a gateway part and a cloud part. In cima platform, we have two parts:

2/17 ❏ Gateway part: GSCL: A gateway module runs a M2M application which offers M2M capabilities and act as a bridge between M2M devices and the M2M Access Network. In GSCL we implemented a gateway application (GA) that behaves like a directory of connected objects and must make a discovery service to detect connections of different objects on the local network in different exhibitors information concerning as the identifier, the communication protocol, the uri or the contact address of the object which are then sent to the NSCL, and some additional information to enable clients to contact objects without using the GSCL namely the gateway address and the port of cloud­device communication in the gateway that are sent to a CIMA server running on the gateway and to short­circuit the GSCL. C server: We set up a server in C using sockets which serves as a bridge between the device and the cloud. This server opens two sockets for each device in the gateway as follows: A first socket to read data from the cloud to transfer them to the second socket and the other for transferring the data from the second socket to the cloud. The second socket to read data from the first socket for transferring the device and transfer data from the device to the first socket. Thus, clients who subscribe to the NSCL can directly contact the object without going through the OM2M layer. ❏ Cloud part: NSCL: In this Part we have NA (Network Application) , clients subscribe close to it to receive notifications when the connection or disconnection of a device.

3/17 2.1.2 Global architecture schema (deployment diagram)

2.1.2.1 OM2M

4/17 2.1.2.1.1 state of the art (synthèse TER + nouvelles contraintes) This state of art focused on the application and functional side of open source M2M solutions. The needs expressed by the platform CIMA are as follows:

❏ Connecting an object (sensor, camera, robot) with different types of connectors (ZigBee, Bluetooth, USB, Wifi, Ethernet ...). ❏ Detection and discovery of various functionalities of a connected thanks to a declarative language for describing the object. ❏ Offrir la possibilité : ❏ To access data from the sensors. ❏ To send commands to actuators. ❏ To deploy and execute code on the connected objects. ❏ Allow short­circuited the solution itself in order to avoid a bottleneck for high performance applications. Differents studies criteria we selected were therefore as follows: ❏ Genericity: A solution will be more generic it is agnostic platform, OS agnostic or agnostic language. In summary, the desired solution must be as independent as possible of the specific hardware, operating system on which it is deployed. It must also implement a wide range of protocols (application, network, data link ...) and in the best case able to withstand a wide range of programming languages. ❏ Correspondence with the objectives of the project ASAWoO: To give a guideline in this state of the art online, we integrate our criteria matches the between use cases of the solution and objectives ASAWoO project. ❏ Community: Community revolving around the project is an important criterion. Indeed, motivation, investment provides energy around the project. The community includes both users and professional developers or "hobbyists". To judge that we can measure the activity of a forum, a mailing list, support or documentation. ❏ Licence : The license of the solution must above all be Open Source. The needs expressed do not mention a willingness to use a proprietary and / or under paid license solution. A license to modify at will the source code would be a plus as the needs expressed by the ASAWoO project are unlikely to result in a turnkey solution.

Solutions studied: OM2M:

5/17 “The OM2M project, initiated by LAAS-CNRS, is an open source implementation of the ETSI M2M Standard. It provides a horizontal M2M service platform for developing services independently of the underlying network, with the aim to facilitate the deployment of vertical applications and heterogeneous devices.” “OM2M exposes a RESTfull API providing primitive procedures for machines authentication, resources discovery, applications registration, containers management, synchronous and asynchronous communications, access rights authorization, groups organisation, and re­targeting.” “OM2M is a Java implementation running on top of an OSGi Equinox runtime, making it highly extensible via plugins. It is built as an product using Mave, and Tycho. Each plugin offers specific functionalities, and can be remotely installed, started, stopped, updated, and uninstalled without requiring a reboot.”

DeviceHive DeviceHive is a framework of M2M (Machine to Machine) open source, developed by the company DataArt. The purpose of this framework is to provide the basic building blocks for the low-level communication between connected objects so that developers focus more on the functionality of the client applications. The architecture of the framework is divided into 3 parts: The device part concerns the deployment of code on a connected object. The framework manages NET languages., C / C + +, J2EE, Python, Android and iOS. There is therefore a wide range of implementations but concerns cross-compilations may appear except for Python and J2EE, but connected objects must have a processing power capable of an interpreter or a virtual machine running. At the communication layer, the framework can handle two types of objects: those with a TCP / IP stack with a protocol based on the REST pattern and those that have none with management some binary protocols (USB, ZigBee, Bluetooth, ...). The bridge portion is to bridge the gap between the objects with no TCP / IP stack and the Internet. This part is supposed to aggregate and redistribute messages between the objects and the Cloud. The classic implementation of the gateway is to the translated binary protocol REST protocol and vice versa. The framework handles. NET languages, C + +, Python and J2EE for this part. The gateway does not usually running on a platform high stress, independence with respect to the platform and the OS can be obtained through the use of languages ​that are high portability Java and Python. The client side which is a consuming application web services offered by objects connected. The framework provides a client implementation in JavaScript, iOS and Android so there are no compatibility issues on the client side. The community around DeviceHive still seems to be very small (few comments, few references) difficult to realize the excitement around this project. Since the current community revolving around the project is quite low, the assurance that the project evolves and is maintained in the long term depends largely on society's interests DataArt to continue to contribute to the project. Install a draft ambitious research what ASAWoO on a solution that can not change may represent a significant risk.

RealTimeLogic : 6/17 RealTimeLogic is a M2M (Machine to Machine) framework proposed by the company of the same name created in 2006 in California (USA). It allows you to add an M2M solution to any object with strong constraints, while having minimal software footprint and ensuring secure and real­time communication. This framework finds application in power systems, transportation systems, industrial networks, military and aerospace applications, and consumer electronics. The framework uses a server application may be named Barracuda and easily deployed on a connected object. The framework includes Server Pages technology C (CSP) which is a server side scripting language as is Java Server Pages (JSP) in the Java ecosystem. It uses the C language, specializing in embedded systems, to generate HTML code to provide the user with a Web interface. It also allows you to use Lua Server Pages technology (LSP) which is also a scripting language, but interpreted by a virtual machine with a footprint of 40 KB RAM This language is both fast and has a low learning curve reduces and the time and cost of developing applications. Support for SOAP Web Services is present. It works on wide ranges of embedded systems, Windows, Linux, any OS supporting multi­threading and real­time operating systems such as: MQX, SMX, ThreadX, VxWorks, EBSnet, uCLinux. The bridge part is managed by the application server using the protocol PikeHTTP the SharkSSL stack manages security, a stack of EventHandler protocol for managing server­side events. The client part of the framework is very rich, it is very easy to add a JavaScript implementation M2M customer, it uses JSON, Ajax and XML­RPC for data exchange technologies. Regarding the community, this is the same problem that DeviceHive, it remains quite low and it is difficult to ensure the sustainability of this project.

Allseen Alliance AllSeen Alliance is a non­profit consortium that standardize interoperability and break the current limitations of the Internet of Things aims. This alliance is supported by the Linux Foundation and now has twenty member companies including: Cisco, D­Link, Haier, LG Electronics, Qualcomm, Panasonic and Sharp. The alliance inherits the AllJoyn framework developed by Qualcomm. The framework is initially based on the AllJoyn open source project developed by U.S. company Qualcomm. It will be extended with contributions from members of the consortium companies and the open source community. Services and applications created with Allseen can communicate through several transport layers, including WIFI, Ethernet and Bluetooth. This framework is agnostic to the hardware and the operating system. It is independent of network protocol and provides a layer of abstraction that defines the specific interfaces to the underlying networks batteries and makes it relatively easy to extend. The core of the framework is written in C + +, but several modules connections (bindings) have been developed for writing applications using Java, Objective­C or JavaScript languages. This framework is based on the system D­Bus interprocess communication for the exchange of messages between multiple processes on a local machine. Allseen Alliance encapsulates the implementation of D­Bus and extends the LAN. The whole idea is to create a virtual bus between several applications to communicate seamlessly. This communication leads to several features such as the discovery of objects, discover their abilities and invocations.

7/17

M2M Working Group of the Eclipse Foundation which is responsible for developing a suite of tools to facilitate the development of M2M applications. Many very interesting projects are under development and some are already stable and usable. Among the contributors to these projects include IBM, Sierra Wireless or Eurotech. The various projects are:

Mihini Mihini is a framework that provides a high­level API written in Lua to deploy code on embedded strong constraints (memory, CPU, bandwidth) systems. Mihini very few dependencies if not Linux. It has a small footprint, a few megabytes of memory and RAM are enough to run it. Lua is a scripting language so there are no problems with cross­compilation.

Ponte Ponte is a framework that allows to bridge the gap between end users primarily using HTTP servers and therefore a REST API and connected objects communicating with one another or with the outside world thanks to the MQTT protocol. Ponte allows to use a REST API to subscribe to notifications or publish notifications to a broker MQTT seamlessly. The CoAP protocol support is planned in the near future. The persistence of notifications is done through NoSQL systems like Redis or MongoDB.

Koneki Koneki is not a framework but rather a community developed by Eclispe tool. It consists of two parts: the first is an IDE for developing applications Lua (using Mihini particular), and the second part is a graphic simulator OMA Device Management that helps developers to validate the different use cases mobile.

2.1.2.1.2 platform choice The solution was chosen to respond to our problem is OM2M framework, this solution is the result of a state of the art according to the needs of CIMA platform. The fact that OM2M is an implementation of ETSI M2M Standard and is an eclipse project are reassuring criteria for sustainability of the project and the direction it should take. This solution makes it easy to deploy and execute code on the connected objects because it OSGI­based, and this is an important criterion for the CIMA project. The community is quite dynamic and grows with each passing day, the forum is active, members are patients and teachers. All these reasons we have therefore brought from this solution for our problem.

2.1.2.2 Discovery layer CIMA platform has a discovery protocol service that listens for incoming connections in the network to detect a new device. Once a new device detect CIMA sending a GET request to have their description (uri, protocol, ip, ...)

8/17 2.1.2.2.1 Discovery bundle in OM2M In the current situation, our implementation works in IP, but our architecture is open and extensible to other type of discovery by implementing the bundle service. Device discovered via fr.liris.cima.gscl.discovery bundle of GSCL, this bundle scans the network for the device detection through the doDiscovery method declared in bundle discovery service.

2.1.2.2.1.1 Detecting new connection When a new ip address is detected by arp scan, the discovery service proceeds as follows 1. Send a get request to the identified address :

http://address:8080/infos

2. A device responds by sending its description. (uri, protocol, port, etc ..) 3. The description of the device is aggregated in the GSCL. The device description (address of the gateway, the communication port with clients) to bypass the GSCL to move directly to the device are sent to the infrastructure controller. The address of the device, the device port contact from the gateway and the gateway port contact from the cloud are sent to another part of the gateway.

2.1.2.2.1.2 Object Identification(to complete, now just for testing) OM2M provides management for identification of resource, presently in our implementation the device are not considered as a resource in the OM2M sense, but it is the CIMA­OM2M platform that we build as an resource application of the GSCL, so we set up our own system of identification devices management.

2.1.2.2.2 Semantic management of object capabilities To expose resources we need to add some semantic to describe what is a capability.

2.1.2.2.2.1 Identification and descritpion of capabilities A capability is identified by an URI, a functionality implemented by the capability and a type that define the type of object is used (example : sensor, actuator…). To describe a capability we use OWL language with the ontology described here : http://liris.cnrs.fr/asawoo/DATA/functionality.owl.

2.1.2.2.2.2 Reuse of work from the ASAWoO project As we seen before we reuse in part the ASAWoO capability description for CIMA. In part, because ASAWoO say that the capabilities cannot be exposed, but to run, a device need to expose its capabilities to CIMA (if not CIMA cannot provide the device capabilities). The functionality implemented by the capability is define in a common vocabulary that permit to have an idea on which is provided by a capability if the name is not understandable.

9/17 2.1.2.3 Infrastructure controller (NSCL) The infrastructure controller is a class in the NSCL that implements the OM2M interface IpuService, he manages gateway access from the cloud, it also manages clients subscriptions for states change of gateway: adding, removing device .

2.1.2.3.1 Client notification system The controller infrastructure provides an URI to all clients to subscribe for the special events connection or disconnection of device in the GSCL. It notifies clients the following events: ❏ New device connection : send them as JSON formats all communications information from GSCL. ❏ Device disconnection: send them as JSON format the device ID of the device that is disconnected. ❏ New client: he sent in JSON format all connected devices.

2.1.2.4 Access to an objet via the gateway

2.1.2.4.1 Access via OM2M : DeviceController The DeviceController is a class of the GSCL that implements the IpuService interface and provides access and exchange of data between the cloud (NSCL, Client) and the device. Any request intended for the device through the GSCL goes through him, whether a get or invocation capabilities of the device.

2.1.2.4.2 Direct access : port forwarding (to complete, unfinished) One of the major constraints of the CIMA project is to bypass the solution itself in order to avoid a bottleneck for high performance applications. To satisfy this constraint, we set up a server written in C by using sockets that transmits all data received from the cloud to the device intended.

2.1.2.5 Discovery server on the object We use the middleware application to test CIMA. The middleware application is a part of the ASAWoO project and provide an interesting base to create a communication API between CIMA and a device. We use (in parts) the “capability” definition to say what the device can do. In fact if you want to execute a programme located in the device you have to expose this program on a REST interface and declare that this program is a capacity.

2.1.2.5.1 OSGi (Equinox) All the application work on an OSGI platform. We choose to used Equinox because it is the same platform used by OM2M the CIMA’s framework based.

2.1.2.5.2 SAJE (unfinished, to complete) SAJE is an other part of ASAWoO project that permit to know informations about the device capacity like memory or cpu power…

10/17 ASAWoO want these informations to know where the Avatar parts can be deploy. CIMA want these informations to correctly identify a device and maybe give them to the Client. At the moment we have not finished to adapt the Application to the EV3 brick.

2.1.2.5.3 Capability provider (object specific) A capability provider is a class that provide some capabilities. For example on the EV3 brick we implement the class WheelEngine which provides capabilities for movements using wheels like advance, turn left, turn right or stop. 2.1.3 Internal functioning

2.1.3.1 OSGi / OM2M (links to docs)

2.1.3.2 Static diagrams (classes: domaine + implem)

11/17 12/17

13/17 2.1.3.3 Dynamic diagrams (communication)

3 HOW TO USE CIMA

3.1 Installation

3.1.1 Cloud See install.md 3.1.2 Gateway See install.md

14/17 3.1.3 Object : Installation osgi on the object To install the example on a EV3 mindstorm device you have to download the middleware application and follow instructions in INSTALL.md file : ❏ First compile and install the application :

$ mvn install

❏ Then deploy the application on the brick :

$ ./bin/install_ev3 ./conf/ev3.conf

❏ Finally launch the application on the EV3 :

$ ssh root@ # cd lejos/appliance-ev3/ # ./launch_equinox.sh

3.2 Use

3.2.1 Client

3.2.1.1 Connection to the NSCL NSCL provides to clients an URL to subscribe to be notified when a connection or disconnection of device.

3.2.1.1.1 Registering : post on InfrastructureController

Each client to subscribe has the following information: URL: http://nsclAddress:8080/om2m/nscl/applications/CIMANSCL/devices/subscribers Method: POST Body: client­contact­uri

3.2.1.1.2 Notification system : several methods, OM2M-based: To create a new device, NSCL receives a post request from the GSCL: URL: http://nsclAddress:8080/om2m/nscl/applications/CIMANSCL/devices/ Method: POST Body: obix­data­encoded

And he send notification to each client with information like :

15/17 URL: http://client­contact­uri Method: POST Body: json­device­encoded

When a device is disconnected to the platform, the Infrastructure controller receives from the GSCL a DELETE request like : URL: http://nsclAddress:8080/om2m/nscl/applications/CIMANSCL/devices/ Method: DELETE Body: obix­deviceId­encoded

And he send notification to each client by URL: http://client­contact­uri Method: DELETE Body: json­deviceId­encoded

3.2.1.2 InfrastructureController API

3.2.2 Creating a server on the object To communicate with the gateway, the device have to expose 2 RESTFUL services. First the gateway have to know some informations about the device and the second API is used to discover and call the object’s capabilities.

3.2.2.1 ServerInfos & WotCapabilityExposer APIs To get the device informations CIMA need to contact /infos resource using GET method to know some informations about the device XML formated : ❏ An URI to contact the device, ❏ the protocol to communicate with the device like HTTP, COAP…, ❏ … The second resource is /capabilities which implement a GET and a PUT method : ❏ GET : this method return the capabilities list formated in OWL. ❏ PUT : this method take a parameters in is body encoded in base64 and contain the name of the capability you want to invoke

4 Remaining work / perspectives

4.1 Complete / test unfinished parts

4.2 Create a manual configuration interface for new objects If CIMA cannot get informations from a device we want to provide an interface to manualy give these informations. At the device connection CIMA cannot get the informations, so when a user

16/17 want to access it he is redirected on a formulary which demand complementary information about the unknown device.

4.3 Implement other servers / CapabilityProviders We want to try to implement other servers and capability provider using others languages or technology. It will be useful to give some examples which not use OSGI and java.

4.4 Create a "lightweight server" for resource limited objects Because CIMA want to aggregate a lot of devices we have to consider a case of the device cannot have a server, for instance if he’s highly memory limited and just the native program can run. So to communicate with theses objects we have to deploy a server which can replace the device server.

4.5 Manage objects not connected with IP (USB, HDMI...) The purpose of CIMA is to aggregate a maximum object to simplify the identification and client communications between an object and the client. To do this it must be possible to connect the objects other than by the network. We had time to work on IP, the following is to extend the opportunity to other modes of connections.

17/17