SensiNact/Getting Started

1. sensiNact overview

sensiNact is a horizontal platform dedicated to IoT and in particularly used in various smart city and smart home applications. sensiNact aims at managing IoT protocols and devices heterogeneity and provides synchronous (on demand) and asynchronous (periodic or event based) access to data/actions of IoT devices, as well as access to historic data with generic and easy-to-use API. To achieve these objectives, sensiNact comes with two complementary frameworks:

• sensiNact Gateway interconnects IoT devices using different southbound IoT protocols such as Zigbee, EnOcean, LoRa, XBee, MQTT, XMPP, as well as platforms such as FIWARE and allows access to them with various northbound protocols such as HTTP REST, MQTT, XMPP, JSON RPC and CDMI. The gateway can also host applications and manage them using an application manager module.
• sensiNact Studio proposes an IDE (Integrated Development Environment) based on Eclipse to manage the existing devices, in addition to develop, deploy and manage IoT applications.

[[Image:./images/architecture/architecture.svg|frame|none|alt=sensiNact overview|caption sensiNact overview]]

3. Core concepts

The sensiNact Gateway allows interconnection of different networks to achieve access and communication with embedded devices. It is composed of six functional groups and their relative interfaces:

• The Device Protocol Adapter abstracts the specific connectivity technology of wireless sensor networks. It is composed of the bridges associated to protocol stacks. All the bridges comply with a generic Device Access API used to interact with northbound sensiNact’s services.
• The Smart Object Access and Control implements the core functionalities of sensiNact like discovering devices and resources and, securing communication among devices and consumers of their services.
• The Consumer API is protocol agnostic and exposes services of the Smart Object Access and Control functional to Consumers.
• The Consumer Protocol Adapter consists of a set of protocol bridges, translating the Consumer API interface into specific application protocols.
• The Platform Management functional group includes all the components needed to ease management of devices connected to sensiNact, regardless of their underlying technologies. A Device Management API is used for this purpose. This functional group also contains the components managing cache, resource directory and security services. These management features are exposed by means of the Platform Management API.
• And finally the Manager Protocol Adapter allows adapting the Platform Management API to the specific protocols used by different external management entities.

In terms of connectivity (cf. Figure 3), on the southbound side the sensiNact Gateway allows to cope both with “physical device” protocols and “virtual device” ones, allowing a uniform and transparent access to an XBee network, or an HTTP Restful web service for example. Here's pell-mell a non-exhaustive list of supported protocols:

• EnOcean, concerting energy harvesting wireless sensor technology (ultra-low-power radio technology for free wireless sensors), and protocols in use to interact with those sensors;
• Bluetooth Low Energy, which is a personal area network, low power protocol designed mainly for healthcare or entertainment type of applications;
• MQTT, which is a machine-to-machine protocol, lightweight publish/subscribe messaging transport, useful for connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium;
• ZigBee based protocols (XBee for example);
• CoAP, which is a REST application protocol, designed to be “the HTTP for constrained networks and devices” whose concept originated from the idea that "the Internet Protocol could and should be applied even to the smallest devices," and that low-power devices with limited processing capabilities should be able to participate in the Internet of Things; it is usually used on top of a 6LoWPAN network, but it may travel regular IP networks as well (it is used by the OMA LWM2M protocol, for instance).

On the northbound side the sensiNact Gateway provides both client/server and publish/subscribe access protocols:

• MQTT;
• JSON-RPC (1.0 and 2.0);
• HTTP RESTful;
• CDMI.

[[Image:./images/architecture/gateway_protocol_2.svg|frame|none|alt=sensiNact Paltform architecture|caption sensiNact Paltform architecture]]

The Smart Object Access and Control functional group described above in this section includes a large number of functionalities:

• It handles the communication with the Consumer Protocol Adapter (REST API, JSON RPC, etc.) and IoT (and non-IoT) devices, providing URI mapping, incoming data/messages translation in an internal format and outgoing data/messages translation in Consumer format. Whenever a Consumer tries to access a resource via Consumer API, the requested URI is forwarded to the Resource Manager in order to check if a specific resource descriptor exists or not inside the Resource Directory and to verify its accessibility status. If a resource descriptor doesn’t exist, a message response with error code is returned to the Consumer API. Otherwise, the request is forwarded to the right interface. At the same time whenever response is originated from IoT device (or abstract IoT device), it will be also forwarded to its logical counterpart in order to update the resource representation in the platform.
• It manages the subscription/notification phases towards the Consumer, if it is not handled by the targeted device (service) itself
• It supports Devices and Resource Discovery and Resource Management capabilities, to keep track of IoT Resource descriptions that reflect those resources that are reachable via the platform. These can be both IoT Resources, or resources hosted by legacy devices that are exposed as abstracted IoT Resources. Moreover, resources can be hosted on the platform itself. The Resource Management functionality enables to publish resources in sensiNact, and also for the Consumer to discover what resources are actually available from the platform; sensiNact Service and Resource model allows exposing the resources provided by an individual service. The latter, characterized by a service identifier, represents a concrete physical device or a logical entity not directly bound to any device. Each service exposes resources and could use resources provided by other services. Figure 4 depicts the Service and Resource model.

[[Image:./images/architecture/data_model.svg|frame|none|alt=Generic data model|caption Generic data model]]

The Resource Directory allows storing information, i.e. resource descriptions, about the resources provided by individual devices connected to sensiNact. It also supports looking up resource descriptions, as well as publishing, updating and removing resource descriptions to it.

Discovering and using resources exposed by Services is a favored approach for avoiding using static service interfaces and then increase interoperability. Therefore, sensiNact Services and their exposed resources are registered into Service/Resource repositories. The platform uses the OSGi service registry as Service/Resource repository, where resources are registered as service properties. Clients ask the Service/Resource repository for resources fulfilling a set of specified properties (defined by LDAP filters). In response, the Service/Resource repository sends clients the list of service references that expose the requested and authorized resources. Clients can then access/manipulate the resources exposed by their selected service objects (cf. Figure 5).

Figure 5: Service Oriented Architecture (MacKenzie, 2006). When a service provider starts, it registers/publishes itself into the service broker. When a consumer appears, it looks for the reference to the service provider into the service broker. With this reference, the consumer can interact directly with the provider.

Resources and services can be exposed for remote discovery and access using different communication protocols, such as HTTP REST, JSON-RPC, etc., and advanced features may also be supported (as semantic-based lookup). Resources can be classified as shown in Table , while the access methods are described in Table 2: Resource's access method.

Type	Description
Sensor Data	Sensory data provided by a service. This is real-time information provided, for example, by the SmartObject that measures physical quantities.
Action	Functionality provided by a service. This is mostly an actuation on the physical environment via an actuator SmartObject supporting this functionality (turn on light, open door, etc.) but can also be a request to do a virtual action (play a multimedia on a TV, make a parking space reservation, etc.).
Property	Information representing a SmartObject state variable of the service. This variable is most likely to be modified by an action (turn on light modifies the light state, opening door changes the door state, etc.) but also to intrinsic conditions associated to the working procedure of the service.
State Variable	Property exposed by a service. This is information which is likely to be static (owner, model, vendor, static location, etc.). In some cases, this property can be allowed to be modified.

Table 1: Resources types and description

Type	Description
GET	Get the value attribute of the resource.
SET	Sets a given new value as the data value of the resource.
ACT	Invokes the resource (method execution) with a set of defined parameters.
SUBSCRIBE	Subscribes to the resource with optional condition and periodicity.
UNSUBSCRIBE	Remove an existing subscription.

Table 2: Resource's access method

The access methods that can be associated to a resource depend on the resource type, for example, a GET method can only be associated to resources of type Property, StateVariable and SensorData. A SET method can only be associated to StateVariable and modifiable Property resources. An ACT method can only be associated to an Action resources. SUBSCRIBE and UNSUBSCRIBE methods can be associated to any resources.

---

4. AppManager concepts

The AppManager aims at creating higher level applications based on the resources provided by the sensiNact gateway. The AppManager provides a way to develop event driven applications, i.e., based on the Event-Condition-Actions (ECA) axiom. Thus, the application is only triggered when the required events occur. Then, if all conditions are satisfied, the actions are done. Events are created from sNa sensors and the actions are performed using the sNa actuators available in the environment.

4.1. Data model and JSON format

The AppManager assumes that an application is a set of bound components. Each component processes a single function (e.g., addition, comparison, action). The result of this function is stored in a variable in the current instance of the application. The components using this result as input listen to the corresponding variable. When the variable changes, they are notified and can process their own function leading to a new result.

The component is the atomic element of an application, thus an application can consider a single component to perform an action. It holds the minimal requirements to create an ECA application:

• Events: events that trigger the process of a component. Trigger can be conditioned to a specific event or a specific value of the event (e.g., when the value of the sensor reach a threshold) ;
• Function: function wrapped in the component (e.g., addition, comparison, action). The acquisition of the parameters is realized in the transition block before the function block;
• Parameters: parameters of the function that are not available in the event (e.g., static value, sensors values).
• Output: result of the function that is stored in a variable and that triggers a new event.
• Properties: nonfunctional properties of the component (e.g., register the result as a new resource in sNa).

The AppManager is a sNa service provider, thus it provides an INSTALL and an UNINSTALL resources, enabling a client to install/uninstall an application. These resources are accessible using the different bridges.

A sNa application is described using a JSON file. We developed a specific Architecture Description Language (ADL) to describe the components used in an application and the bindings between the components.

The following JSON code example corresponds to the code of a single component:

{
    "events": [
        {
            "value": "resource1",
            "type": "resource",
            "condition": {
                "operator": ">=",
                "value": 100,
                "type": "integer"
            }
        }
    ],
    "function": "function_name",
    "parameters": [
        {
            "value": "ON",
            "type": "string"
        }
    ],
    "properties": {},
    "output": "output_name"
}

This component specifies that when the resource1 is greater or equals to 100, the function_name is called with the string parameter "ON". The result of the function is stored in the output_name variable and triggers a new event that may be used by others components.

Supported types are:

• Primitives types: integer, boolean, long, double, float, string. This is used to described a static variable;
• Resource type: resource. This is used to refer to a resource. If this is set in the JSON Event section of the JSON, a SUBSCRIBE is done on the resource. If this is done in any JSON Parameters section, a GET is done on the resource and returns the current value;
• Variable type: variable. This is used to refer to the output of a previously processed component;
• Event type: event. This is used to refer to the value of the event that triggers the function. This type is never used in the condition of the JSON Event section.

Here after is a synthesis of the type that can be used in the different parts of the JSON file.

	Primitive types	Resource type	Variable type	Event type
In event type	No	Yes	Yes	No
In event/condition type	Yes	Yes	Yes	No
In parameters type	Yes	Yes	Yes	Yes

The AppManager supports the validation of the JSON files against a JSON schema. Schemas exist in the plugins and may be used by the developers of the applications.

4.2. Architecture

The AppManager is designed to be used as any sNa service provider. Thus it provides an Install and an Uninstall resources, enabling a client to install/uninstall an application. These resources are accessible using different bridges, such as any actuators.

The AppManager architecture is also designed to easily add new functions and to handle the lifecycle of applications in order to perform checks.

4.2.1. Plugins

Plugins enable to add new function to the AppManager. New plugins require to implements the mandatory interfaces Java interface to be found in the OSGi registry and thus be used by the AppManager. The AppManager is currently supporting the following functions.

Plugin	Functions supported
Basic Plugin	various operators (e.g., equals, greater than, lesser than, different), addition, subtraction, division, multiplication, modulo, concatenation, substring, ACT and SET methods on resources
CEP Plugin	after, before, coincides, average, average deviation, count, max, min, median, standard deviation, sum

4.2.2. Lifecycle

The AppManager provides a lifecycle to manage the applications. It enables to process various checks during different steps of the lifecycle of the application (e.g., ADL consistency, resources permissions). The first step is to install the application, i.e., send the ADL of the application. If there is a problem, the AppManager returns an error. Once the application is installed, it can be started and its state changes to “Resolving”. If there is a problem during this step, the application enters in the “Unresolved” state. Otherwise, the application is active until it is stopped or an exception occurs.

<img src="./images/appmanager/lifecycle.svg" height="300"/>

4.2.3. Instances

The AppManager allows multiple instances of the same application to run in parallel. When an event occurs, the InstanceFactory of the application instantiates a new set of components and passes the event to the first component. The number of instances can be set in the application properties. If, there is more events than available instances, events are stored and processed when an instance ends.

4.3. How to use

The AppManager is accessible as any resources in the sensiNact Gateway. Thus, it is accessible using the RESTful Northbound bridge. At start, the AppManager holds only the admin service. To install/uninstall an application, you have to perform an ACT on the INSTALL/UNINSTALL resources in the AdminService of the AppManager.

To send JSON files, it is recommanded to use the sensiNact Studio that will format the JSON ADL from the sNa language.

You can also uses a REST client (e.g., WizTools/REST client) to send JSON files to the AppManager but you need to send a valid JSON file.

---