sensiNact (aka. BUTLER Smart Gateway)

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 Platform 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.
  • Tags: , , , , , , , , , , , , , , ,
  • Latest update: May 30, 2016
  • Developed by: CEA-LETI
  • Contact name: Levent Gurgen, Christophe Munilla, Rémi Druilhe, Etienne Gandrille, Jander Botelho do NascimentoBo
  • Contact email: [email protected]
  • Relations:
    • BUTLER Integrated System Architecture (more details)
      • Relation type: Re-use relationship
      • Validation: The sensiNact Platform is a key component of the BUTLER Integrated System Architecture. This Library implements the model described in the BUTLER Architecture.
      • Completeness of the relation: 100%
    • BUTLER Smart Office Trial (more details)
      • Relation type: Re-use relationship
      • Validation: The gateway is partially used in the trial (inno and iHL deployments)
      • Completeness of the relation: 66%
      • BUTLER Smart Parking Trial (more details)
        • Relation type: Re-use relationship
        • Validation: The Smart Parking trial uses a lightweight version of the BUTLER Smart Gateway. However, both of them are perfectly capable of running transparently with the underlying parking technology and, in fact, they can work together, both of them at the same time. So, in this particular field trial, the reason for TST to develop an additional gateway relies in the requirement of having a portable trial, which also offers the ability to integrate an NFC module to showcase the suitability of this technology in this kind of trial.
        • Completeness of the relation: 50%
        • BUTLER Smart Health Trial (more details)
          • Relation type: Re-use relationship
          • Validation: The BUTLER Gateway was used in conjunction with the fall detection device, in order to identify the real position of two particular events when they occured indoor: fall events and “panic button” events (when the participant wearing the fall detection device pressed the panic button). As the fall device only detected GPS coordinates (i.e., outdoor positions), ZIGPOS devices worn by participants indicated the indoor position (x, y and z coordinates), so that they could be detected in case of fall or panic situation. With the help of the Behaviour User Manager, the position was semantically translated to make it legible on the Smart Mobile Application. The ZIGPOS SmartObject Service of the BUTLER Gateway offered good precision, with real time updates of participants’ position, which only had to wear very small indoor location devices. The deployment of the beacons was very fast, in unobtrusive locations, and covering an appreciable area with a small number of them.
          • Completeness of the relation: 100%
          • BUTLER Smart Transport Trial (more details)
            • Relation type: Re-use relationship
            • Validation: On the lower layer, the SmartGateway incorporates the ZIGPOS coordinator which is responsible with the coordination of the mobile and anchor devices performing positioning. Consequently, at an upper layer, it provides real-time positioning services and exposes relative-coordinate resources associated with each SmartDevice. For this reason, any other BUTLER compliant component such as SmartServer or SmartMobile can GET, SET or SUBSCRIBE to the positioning services. The SET function, in particular, is allowed only for the anchor devices and serves usually to mark the fixed positions when the kit is deployed into a different space. The ZIGPOS coordinator integration in the gateway was implemented by extending the platform api, device-api and device-impl respectively.
            • Completeness of the relation: 100%
          • Intellectual property rights (IPR)

            @BUTLER

            sensiNact (aka. BUTLER Smart Gateway) will be released as Open Source.

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 Platform 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.

architecture


Getting started

Install and start sensiNact Platform

This section explains how to install and start sensiNact Platform under the Linux operating system.

Requirements

sensiNact Platform requires at least Java 6.0 but some features from third party libraries may require Java 7.0.

sensiNact Platform may requires the access to USB port. To ease the recognition of the USB connector by sensiNact Platform, it is required to install the UDEV rules.

Install from binary packages

Retrieve the binary package from the download page (not available for now) and install it using the dpkg tool (make sure to have the rights to install the package).

sudo dpkg -i <package.deb>

sensiNact is now installed into /opt/sensinact.

Install from sources

Clone the GIT repository (not public for now).

Enter inside the newly created folder of sensinact and compile it using Maven 3:

mvn clean install

The sensiNact distribution has been created inside the repository

sensinact
> distribution > release > target > sensinact.

Launch sensiNact Platform

Once installed, enter into the sensiNact directory. You can now configure the modules you need using the following command:

./sensinact -c

Some modules require to activate others modules to run. For example, each modules using the USB require the USB module to activated. In a near futur, we plan to automate the activation of dependencies modules accordingly to the modules activated by the user.

Once, you finished the configuration of the modules, you can start sensiNact using the following command.

./sensinact

If the user is not part of the dialout Linux group, you need to launch sensiNact using sudo.

Install sensiNact Studio

There are TWO ways to install sensiNact Studio on your computer, depending on what you want to do with the Studio.

  • If you are a sensiNact end user, you may be interested in the latest stable release of sensiNact Studio.
  • If you are a sensiNact core developper, you will need to install the studio from it sources. It will gives you access to the Studio development branch, with the latest features and the ability to debug the Studio using the source code.

For end users: sensiNact Studio latest release

Install Eclipse Mars

You MUST add Sensinact APT repository in your sources.list in order to have access to this installer, check on the download page (not available for now) how to do it.

Install Eclipse Mars using the installer typing the command below.

sudo apt-get install sensinact-studio-eclipse

Now you can launch Eclipse Mars simply by typing sensinact-studio

Install sensiNact Plugin

In eclipse add the three Update Sites below:

Look and install the feature named “Sensinact” and click in Install.

Update Sensinact Studio

Just access the Eclipse menu Help > Check for Updates, if there is a new version of sensiNact Studio, it will be installed.

For sensiNact developpers: installation from sources

Install plugin dependencies
  1. Eclipse download and start-up:
    1. Download Eclipse Mars Package “Eclipse IDE for Java and DSL developers”;
    2. Extract the archive to the directory of your choice;
    3. Run the eclipse executable.
  2. EMF transaction installation
    1. Go to Help/Install new software
    2. Work with: http://download.eclipse.org/releases/mars (already existing);
    3. Take a coffee ! Eclipse is getting up to date information and this takes time ;
    4. Select Modeling / EMF Model Transaction SDK;
    5. Install.
  3. Restlet installation
    1. Go to Help/Install new software
    2. Work with: http://p2.restlet.com/2.2/ (to be added);
    3. Select Restlet Core and inside Standards support : Restlet Extension – JSON;
    4. Install.
  4. Nebula installation
    1. Go to Help/Install new software;
    2. http://download.eclipse.org/technology/nebula/snapshot;
    3. Select Nebula Release Individual Widgets.
    4. Install.
Clone and Import Studio project
  1. Clone the sensiNact Studio project (not publicly available)
  2. Projects import in the studio
    1. File > Import…;
    2. General > Existing Projects into Workspace;
    3. Select root directory –> the studio repository;
    4. Check all the projects;
    5. Click on finish.
  3. First Studio Execution
    1. Run / Run configurations…;
    2. Double click on “Eclipse Application” to create a new runner;
    3. Run.

Core concepts

The sensiNact Platform 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 Platform 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 Platform provides both client/server and publish/subscribe access protocols:

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

gateway_archi

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.

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.

component

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.

data_model

event_model

parameter_model

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.

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.

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

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.

lifecycle

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.

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.


Using the Studio

Configure the Studio

First of all, launch the Studio by clicking its icon or by using the following command line in a terminal:

sensinact-studio

Once the Studio is launched, you should obtain something like this:

start-0

On the left, in the Device Navigator view, click on Add Gateway.

start-1

In the new window, provide the name of your choice, the address of the gateway, the port of the gateway and then, click on OK.

start-2

Finally, select the gateway in the Device Navigator view and then click on Connect gateway to connect to the gateway.

start-3

In the Device Navigator view, the gateway should appear and list the available devices connected on the gateway.

start-4

Create an application

Once the Studio has been configured, you can create an application. Click on the Project Explorer view on the left side of the Studio.

app-0

Right click on the window and select the menu New -> Project…. Then create a new project: select General -> Project.

app-1

Provide a name for the project (for example: iotweek_hackathon) and click finish.

app-2

In the newly created project, create a sNa file: right click on the newly created project, then New -> File and finally provide a name for your application (be careful to use an unique name for your application in order to avoid conflict with others applications from others participants). End the name of the file with the extension .sna. Finally click on Finish.

app-3

You may have a popup window asking: “Do you want to add the Xtext nature to the project ?”. Answer Yes.

The Studio should have opened a text view, with the name of your file, in the bottom of the main window. You can now write your application.

app-4

To ease the development of an application, the Studio provides an auto-completion feature using the Ctrl + Space key combo.

Now, we will explain the structure of an application. A sensiNact application is based on the Event-Condition-Action axiom. First your define the resources you are going to use in your application. To do this, you use the resource keyword followed by a custom name for reusing your resource later in your application. Next, you associate your custom name with the URL of the real resource. For example, you can have something like that:

resource myCustomeName1=[nameOfTheGateway/device/service/resource1]
resource myCustomeName2=[nameOfTheGateway/device/service/resource2]

Next, you define on which event the application will be triggered. You use the on keyword followed by the resource the application will listen for events. You end your sentence by the
subscribe()
keyword. For example:

on myCustomResource1.subscribe()

Then, you define the condition that will enable to perform the actions. You use the if keyword followed by a condition and ended by the do keyword. For example:

if myCustomName1.get() == true do

You can also use the else if do or the else do keywords to create more complex applications.

And finally, you perform the action using the act() keyword. You can perform multiple actions in the same condition, simply separate them using a comma.

myCustomName2.act()

Each sNa application ends with the end if keyword. Save your work, your first application has been created.

At the end, your sNa application should look like the following example (running on a local gateway):


resource button=[iotweek/button/switch/state] // The button sensor
resource ON=[iotweek/light/switch/turn_on]  // The ON actuator of the light
resource OFF=[iotweek/light/switch/turn_off]    // The OFF actuator of the light

on button.subscribe()           // The button that will trigger the application

if button.get() == true do      // The condition to satisfy to perform the action
    ON.act()                // Turning on the light
else do 
    OFF.act()               // Turning off the light
end if

This example turn on a light when the button is pressed the first time (returning true value) and switch off the light when the button is pressed a second time (returning false value).

app-5

Deploy and start an application

To deploy an application, you just have to be connected to the gateway (follow the Configure Studio section). In the Project Explorer view, right click on the file you just created and fulfilled with your sNa application and select Deploy IoT application.

deploy-0

This will send your application into the gateway and install it. A window should pop, notifying you that the application has been successfully installed.

Returns to the Device Navigator view and roll out the AppManager device. Your application should be there. Roll out your application and double click the START button.

deploy-1

Your application is now started, thus when the event is sent, the action is performed.

Service level

This documentation is the first complete release of the BUTLER Gateway. It will be updated and complemented until the end of the project (sept 2014) and supported beyond the end of the project as an open source project.

Technology Readiness Level

6 - technology demonstrated in relevant environment

Reuse Readiness Levels

5 - Reuse is practical; the software could be reused by most users with reasonable cost and risk

RESTful-HTTP Bridge

Also available using the Swagger Interface.

Accessing Resources from BUTLER Smart Objects

Get the list of service providers

HTTP METHOD GET
Signature: /providers
Path Parameters: NONE
Data Parameters: NONE
Request Example: {http://host:port}/sensinact/providers
Response Example: [{"ID": "TV-01"},{"ID": "TV-02"},{"ID": "SmartPlug-0"}]

Get the description of a given service provider

HTTP METHOD GET
Signature: /providers/{providerID}
Path Parameters: {providerID}: the id of the service provider to be consulted
Data Parameters: NONE
Request Example: {http://host:port}/sensinact/providers/SmartPlug_0
Response Example: {"name":"SmartPlug_0","services":["admin","power_SmartPlug-0"]}

Get the list of services provided by a given device

HTTP METHOD GET
Signature: /providers/{providerID}/services
Path Parameters: {providerID}: the id of the service provider to be consulted
Data Parameters: NONE
Request Example: {http://host:port}/sensinact/providers/SmartPlug_0/services
Response Example: [{"ID": "admin"},{"ID": "power_SmartPlug-0"}]

Get the description of a given service provided by a specified service provider

HTTP METHOD GET
Signature: /providers/{providerID}/services/{serviceID}
Path Parameters: {providerID}: the id of the provider to be consulted{serviceID}: the id of the service to be consulted
Data Parameters: NONE
Request Example: {http://host:port}/sensinact/providers/SmartPlug-0/services/power_SmartPlug-0
Response Example: {"name":"power_SmartPlug-0","resources":[{"name":"location","type":"PROPERTY"},{"name": "dim","type":"PROPERTY"},{"name": "energy","type":"SENSOR"},{"name": "power", "type":"ACTION"},{"name": "status","type":"STATEVARIABLE"}]

Get the list of the resources exposed by a given service provided by a specified service provider

HTTP METHOD GET
Signature: /providers/{providerID}/services/{serviceID}/resources
Path Parameters: {providerID}: the id of the service provider to be consulted{serviceID}: the id of the service to be consulted
Data Parameters: NONE
Request Example: {http://host:port}/sensinact/providers/SmartPlug-0/services/power_SmartPlug-0/resources
Response Example: [{"ID": "dim"},{"ID": "energy"},{"ID": "power"},{"ID": "status"}]

Get the description of a given resource exposed by a specified service of a specified service provider

HTTP METHOD GET
Signature: /providers/{providerID}/services/{serviceID}/resources/{resourceName}
Path Parameters: {providerID}: the id of the service provider to be consulted{serviceID}: the id of the service to be consulted{resourceName}: the name of the resource to be consulted
Data Parameters: NONE
Request Example: {http://host:port}/sensinact/providers/SmartPlug-0/services/power_SmartPlug-0/resources/status
Response Example: {"accessMethods":[{"name":"GET","parameters":[]},{"name":"GET","parameters":[{"name":"attributeName","constraints":[],"type":"string","fixed":false}]},{"name":"SET","parameters":[{"name":"attributeName","constraints":[],"type":"string","fixed":false},{"name":"value","constraints":[],"type":"java.lang.Object","fixed":false}]},{"name":"SET","parameters":[{"name":"value","constraints":[],"type":"java.lang.Object","fixed":false}]},{"name":"SUBSCRIBE","parameters":[{"name":"attributeName","constraints":[],"type":"string","fixed":false},{"name":"listener","constraints":[],"type":"fr.cea.sna.gateway.core.model.message.Recipient","fixed":false},{"name":"conditions","constraints":[],"type":"java.util.Set","fixed":false}]},{"name":"SUBSCRIBE","parameters":[{"name":"listener","constraints":[],"type":"fr.cea.sna.gateway.core.model.message.Recipient","fixed":false},{"name":"conditions","constraints":[],"type":"java.util.Set","fixed":false}]},{"name":"SUBSCRIBE","parameters":[{"name":"listener","constraints":[],"type":"fr.cea.sna.gateway.core.model.message.Recipient","fixed":false}]},{"name":"SUBSCRIBE","parameters":[{"name":"attributeName","constraints":[],"type":"string","fixed":false},{"name":"listener","constraints":[],"type":"fr.cea.sna.gateway.core.model.message.Recipient","fixed":false}]},{"name":"SUBSCRIBE","parameters":[{"name":"subscriptionId","constraints":[],"type":"string","fixed":false}]},{"name":"UNSUBSCRIBE","parameters":[{"name":"attributeName","constraints":[],"type":"string","fixed":false},{"name":"subscriptionId","constraints":[],"type":"string","fixed":false}]}],"name":"status","attributes":[{"name":"value","type":"boolean","metadata":[{"name":"modifiable","value":"UPDATABLE","type":"fr.cea.sna.gateway.core.Modifiable"},{"name":"friendlyName","value":"status","type":"string"}]}],"type":"SENSOR"}

Get the data of a given data resource (PropertyResource, StateVariableResource, SensorDataResource) exposed by a specified service of a specified service provider

HTTP METHOD GET
Signature: /providers/{providerID}/services/{serviceID}/resources/{resourceName}/GET
Path Parameters: {providerID}: the id of the service provider to be consulted{serviceID}: the id of the service to be consulted{resourceName}: the name of the resource to be get
Data Parameters: NONE
Request Example: {http://host:port}/sensinact/providers/SmartPlug-0/services/power_SmartPlug-0/resources/status/GET
Response Example: {"response":{"timestamp":1463986920000,"name":"status","value":true,"type":"boolean"},"statusCode":200,"uri":"/SmartPlug-0/power_SmartPlug-0/status"}

Modify the data of a given data resource (ModifiablePropertyResource, StateVariableResource, SensorDataResource) exposed by a specified service of a specified service provider

HTTP METHOD POST
Signature: /providers/{providerID}/services/{serviceID}/resources/{resourceName}/SET
Path Parameters: {prvoiderID}: the id of the service provider to be consulted{serviceID}: the id of the service to be consulted{resourceName}: the name of the resource to be set
Data Parameters: JSON data associated to the resource specifying the new data value and metadata
Request Example: {http://host:port}/sensinact/providers/SmartPlug-0/services/power_SmartPlug-0/resources/status/SET
Data Parameters Example: {"value":0}
Response Example: {"name": "status","type": "class java.lang.Integer","value": 0}

Invoke the given action resource exposed by a specified service of a specified service provider

HTTP METHOD POST
Signature: /providers/{providerID}/services/{serviceID}/resources/{resourceName}/ACT
Path Parameters: {providerID}: the id of the service provider to be consulted{serviceID}: the id of the service to be consulted{resourceName}: the name of the resource to be invoked
Data Parameters: JSON data specifying the input parameters
Request Example: {http://host:port}/sensinact/providers/TV-01/services/PlayerService_TV-01/resources/play/ACT
Data Parameters Example: { "parameters": [ {"name":"current-media-id","type":"java.lang.String","value":"movie.mov"} ] }
Response Example: { "message": "Playing the given media movie.mov","modified resources": ["current-media","state" ],"status": "SUCCESS" }

Subscribe to a resource exposed by a specified service of a specified service provider

HTTP METHOD POST
Signature: /providers/{providerID}/services/{serviceID}/resources/{resourceName}/SUBSCRIBE
Path Parameters: {providerID}: the id of the service provider to be consulted{serviceID}: the id of the service to be consulted{resourceName}: the name of the resource to be invoked
Data Parameters: JSON data specifying the input parameters
Request Example: {http://host:port}/sensinact/providers/TV-01/services/PlayerService_TV-01/resources/play/ACT
Data Parameters Example: { "callback": "http://host:port/callback"}
Response Example: { "response": { "subscriptionId": "string" }, "statusCode": 0, "uri": "string" }

Unsubscribe to a resource exposed by a specified service of a specified service provider

HTTP METHOD POST
Signature: /providers/{providerID}/services/{serviceID}/resources/{resourceName}/UNSUBSCRIBE
Path Parameters: {providerID}: the id of the service provider to be consulted{serviceID}: the id of the service to be consulted{resourceName}: the name of the resource to be invoked
Data Parameters: JSON data specifying the input parameters
Request Example: {http://host:port}/sensinact/providers/TV-01/services/PlayerService_TV-01/resources/play/ACT
Data Parameters Example: { "usid": "callbackId"}
Response Example: { "statusCode": 0, "uri": "string" }

Example of sNa applications

Switching ON/OFF a light

resource ON=[local/PhilipsHue-2/power/turn_on]
resource OFF=[local/PhilipsHue-2/power/turn_off]
resource button=[local/0xfeff3651/a/contact]

on button.subscribe()

if button.get() == true do
  ON.act()
else do 
  OFF.act()
end if

Notify KODI on contact

resource NOTIF=[local/Kodi_OpenELEC/gui/gui.shownotification]
resource contact=[local/0x008b46e8/window/contact]

on contact.subscribe()

if contact.get() == true do
  NOTIF.act("Title", "Message", "info", 10000)
end if

Change color using remote controller

resource GREEN=[local/PhilipsHue-2/color/turn_green]
resource RED=[local/PhilipsHue-2/color/turn_red]
resource BLUE=[local/PhilipsHue-2/color/turn_blue]
resource OFF=[local/PhilipsHue-2/color/turn_off]
resource controller=[local/Kodi_OpenELEC/remote-control/buttonpressed]

on controller.subscribe()

if controller.get() == 59 do
  GREEN.act()
else if controller.get() == 142 do
  RED.act()
else if controller.get() == 143 do
  BLUE.act()
else do
  OFF.act()
end if