SensiNact/Bridge REST

Description

Application that is wired to a sensor information have two ways of fetching the actual sensor information: actively or passevely. In the first case the application is responsable for fetching the information at its convenience. The second option is to subcribe to the sensor, and a third-part application will be responsable for notifying when a new data is available.

Even though those are different approaches, usually application are built by combining those two. The first for initialize the values and the latter to later modification on the first value received.

Eavesdropping Resource state change on Sensinact BUS

If you re willing to see your modification being propagated into sensinact bus, you can activate the _android_ profile in sensiNact, using the command _sensinact -c_ and checking the box _android-imu_, then restart your sensinact.

This will activate an URL on http://localhost:8080/android/debug.html, in which you will see all the resources that the state is changing.

ACT on a device

Assuming you have a provide names _fan_ with a service _switch_ and a resource _turn_on_ and turn_off, both resource are resource action that present the action of turnning on or off a fan.

You can use RESTful API to perform this call, example:

Request

URL: http://localhost:8080/sensinact/providers/fan/services/switch/resources/turn_on/ACT

Method: POST

Headers: ["Content-Type:application/json"]

Body: EMPTY

Response

{

   "triggered": [
       {
           "name": "status",
           "type": "string",
           "value": "ON",
           "timestamp": 1548329494996
       }
   ],
   "response": {
       "task": "ACT",
       "start": 1548329494996,
       "end": 1548329494996,
       "uri": "/fan/switch/turn_on",
       "status": "EXECUTED"
   },
   "type": "ACT_RESPONSE",
   "uri": "/fan/switch/turn_on",
   "statusCode": 200

}

You can perform the same action in order to turn off the fan.

Subscription

Request

URL: http://localhost:8090/sensinact/providers/light/services/switch/resources/status/SUBSCRIBE

Method: POST

Headers: ["Content-Type:application/json"]

Body: {"callback":"http://localhost:8099/festival/back/info"}

It is important that the `callback` URL value, do not finish by a slash `/`, otherwise the callback will be called with a double slash `//`. `http://localhost:8099/festival/back/info//status8249578811484645003210`, this is an example of the address that will be receive the POST http call in response to sensor value update (duo to the subscription).

Response

{
 "response": {
   "subscriptionId": "status8249578811484645003210"
 },
 "type": "SUBSCRIBE_RESPONSE",
 "uri": "/light/switch/status",
 "statusCode": 200
}

Callback notification

The callback notification is done by a POST HTTP call from the gateway to the callback. An example of callback fired would be:

URL: http://localhost:8099/festival/back/info/status8249578811484645003210

Method: POST

Headers: ["Content-Type:application/json"]

Body: {"notification":{"name":"state","type":"boolean","value":false,"timestamp":1484670944989},"type":"ATTRIBUTE_VALUE_UPDATED","uri":"/button/switch/state/value"}

Unsubscription

Request

URL: http://localhost:8090/sensinact/providers/light/services/switch/resources/status/SUBSCRIBE

Method: POST

Headers: ["Content-Type:application/json"]

Body: {"usid":"status8249578811484582198073"}

Response

{
 "response": {
   "message": "unsubscription done"
 },
 "type": "UNSUBSCRIBE_RESPONSE",
 "uri": "/light/switch/status",
 "statusCode": 200
}

Remarks or improvements

• Replace usid by subscriptionId key in Unsubscription call to keep it coherent, they refer to the same element the sensiNact's internal callback ID ;
• Allows the user to specify how he wants to receive the callback, the method type (GET/POST) ;
• Option to list all subscriptions ;
• Option to remove subscription ;
• Allow user to specify if he wants this callback to be called with a specific id that he can identity. Avoiding the callback receiver to keep a local list mapping its objects to the sensiNact id ;
• Allow user to specify other notification channels, e.g. Websocket ;
• Remove the callback in sensiNact gateway if the callback is not reachable, otherwise it can be considered as a memory leakage.