Resources

Trying to achieve true compatibility is the main objective of this project. We are based on the principles many apps to one piece of hardware and many pieces of hardware to one app. The first makes reference to the fact that a single device can be controlled (through an API or just by running binaries) by different software –which is easy to understand– however not always an app is prepared to handle different devices, even more when they are embedded. That is the purpose of resources. To encapsulate functions of different hardware through abstraction and make it available to different apps so they do not have to worry on the brand or nature of a device in order to demand it a certain task.

Requirements

Instead of establishing a protocol or bold rules for resource discovery (and since almost always it is going to be operated by a human) it has been preferred a database approach, more similar to a programable protocol like MQTT (described in the section 2.7) where actions are performed after the intents or messages there are available. Thus, it has been designed a flexible yet simple mechanism to simplify Remote Procedure Call on different resources that might be on heterogeneous locations. As it can be perceived, it is based on SNMP methods to manage events and measurements, chaining resources within foreign keys in a database.

Implementation

As always, for modularity, this system will be implemented as an app that can be installed or uninstalled from Netbeast router, allowing developers to create their own solutions and stop or launch them. It consists on a SQLite database with a single table for resources (another table shall be appended for subscription). A resource is the group of actions that can be applied on the same topic and application. The same topic (lighting, for example) may have different resources, thus different apps, all with the same methods –actions– (turn on, turn off, change color).

### Actions table

id	app	location	topic	method	hook
1	ABC lights	Living Room	Illumination	set	/api/illumination
2	Thermostat	Bedroom	Temperature	set	/temp
3	Thermostat	Bedroom	Temperature	get	/temp
5	SecuritySystems	Entrance	Presence	get	mqtt://localhost:4444

• Id is a sequentially assigned id for interacting with the database.
• App field will be assigned from the dashboard and refers to the application that offers the resource.
• Location is a non-strict field and it is thought to enhance readability, so the user knows where is the resource. An empty location would let the user to think it is applied throughout the building or room he is in. Wild cards and regex are accepted (like *, % or ?)
• Topic is the what of a resource, intends to verbalize the object of an action. It is mandatory. Synonyms will be treated equally in a way to ease interconnection and reduce the learning curve.
• As with topic, methods are mandatory to be specified. Only a subset of actions are allowed (set, get, toggle, update, delete) and their actions are mapped into HTTP verbs.
  • get → GET
  • set → POST
  • toggle (set the opposite of the current state of a thing), update → UPDATE
  • delete, remove → DELETE
  • Hook path is the complete URL (or relative path from an apps root) to invoke a remote procedure. It could be in HTTP but also implemented in MQTT. The actions are used to understand which method should be applied. It is also mandatory.

If somebody wants to turn off the lights in a certain room, an app can check for a resource, show it to the user and let him decide or apply an action to a determined element. Also, other apps can check for resources and ask to perform a task. When a resource is called as an action, the dashboard applies the methods to hook path, always with application/json content-type. If an error occurs, the hook must be prepared to show a message explaining why it has failed.

Also resources may provide useful information. The response from a hook call must be in json mode and will be handled as is to the calling application. The content is non-standardised so for deeper use of a resource developer guidelines should be proposed, but it is not of our intention to make it more difficult to developers to interact.

As a fact a semantic matching should be applied when querying for a resource and data-fusion will be applied in a non strict way. A node.js wrapper for interacting with resources will be available with custom functions to ask for common resources as temperature, water use, door openings…

Each app can register as many resources as it asks to. All would be removed if the app is uninstalled. Subscription should be done programatically and with user interaction, to ensure that all resources share the name of a room or the type of information.

Events

This model allows subscription to events and actions. Events should be designed as other table that subscribes to topics, locations or ids about other resources, allowing actions to be performed secuentially or programatically as in a smart house is suppose to be done.

### Events table

resource_id	target_id	payload
5	1	ON

• The resource_id field points to an action that has been called subscribing to it.
• Target_id field is the callback and points to

In the table above, when action 5 (presence is detected by SecuritySystems app in the entrance) action 1 is applied (ABClights are turned on) because the payload is sent and understood from the target.

API

The API will be exposed as HTTP RESTful itself, but it will be offered a node.js wrapper written in a promise mode, since it is stateful, and selection of resources may vary in different ways.

A Promise represents a proxy for a value not necessarily known when the promise is created. It allows you to associate handlers to an asynchronous action's eventual success value or failure reason. This lets asynchronous methods return values like synchronous methods: instead of the final value, the asynchronous method returns a promise of having a value at some point in the future. – (developer.mozilla.org n.d.)

Node.js wrapper for the resource API example

var Resource = require(‘nb-resource’)

Resource.get(‘presence’).at(‘Living Room’)
.success(function(presence) {
   if(presence === true) {
      //there are people in the room
      Resource.set(‘lightning’).to(‘ON’).at(‘Living Room’)
      .error(function(err) {
         console.error(err);
      })
   }
})