Solmuhub

Solmuhub is the Node.js implementation of the IoT Hub. It is currently build upon the loopback, which is a Node.js REST API framework, to generate the the REST API.

IoT Hubs provides fine-grained access control to IoT devices, data and other resources such as IoT Hub containers to enable remote execution of code (e.g., distributed analytics, edge/fog computing, etc.).

Resources are exposed via the REST API of the hub which enables interactions with other hubs.

Installation

Build

  1. npm install (Install all the dependencies)
  2. npm run-script build (Compile the client side files with Gulp)
    • Not mandatory, the client side build is called before npm start
  3. npm start to start the hub
    • If it is the first time you run the hub, you will be asked to enter admin credentials. The admin user will be created in database.
    • If you run the hub in development environment and if you specified an admin user either with a file or via the assistant, you will be logged in automatically and the access token will be printed in the console. You have to use the access token for authentify yourself for each request. You can use the token either in the Authorization HTTP header or in the access_token URL parameter.

Configuration

As Solmuhub is build upon loopback, the configuration of the Hub follows the same structure as any loopback application. The folder server contains a number of files that are used to configure the IoT Hub application:

Concept


[
  {
    "title": "apples",
    "count": [12000, 20000],
    "description": {"text": "...", "sensitive": false}
  },
  {
    "title": "oranges",
    "count": [17500, null],
    "description": {"text": "...", "sensitive": false}
  }
]

The IoT Hub includes a few key components that needs to be manipulated to use the hub (models are described in the model documentation):

Client-side documentation

The documentation of the hub API is available on the client side via the URL: /doc. The documentation shows all the possible REST URL that are accessible for a hub.

Data

One of key strength of the IoT Hub is that IoT developers and users only manipulate abstraction of IoT devices and the data that they produce to perform operations.

The built-in data models of the IoT Hub are available in the server/schemas folder. They are currently 5 models supported by the IoT Hub natively. But you can also add you own models to expand your IoT Hub implementation. We use json-schema to define our data formats.

  1. string: Basic string data
  2. number: Basic number format (equivalent to Javascript number)
  3. boolean: Basic boolean format
  4. integer: Basic integer format
  5. temperature: Temperature data format
    • Temperature data include a field for value of type Number and a unitfield of type String. Unit must be of know types ("cel", "far", "kel")
    • Example of a valid temperature data: { "value"=40.3, "unit"="cel"}
    • Examples of invalid temperature data: { "value"=40.3},{ "value"=40.3, "unit"="unknown unit"}

The number of IoT Hub data formats supported natively by Solmuhub will be significantly in the future to cover most usually IoT devices and data types.

Creating a feed

There are three types of feeds: Atomic, Composed or Executable. You can manage them via a REST API. Let's create your first feed, in this case a composed feed:

POST http://localhost:3000/api/feeds/composed
Body:
{
    "name": "aFeed"
}

You can see that we get in response a JSON object with some properties. One of these is the feed's id that we have to use to identify the feed in future requests.

Now let's create a field that we will attach to this feed. A field must have a type. Let's say we want to store temperature values, so we have to use the type root/temperature.

POST http://localhost:3000/api/feeds/composed/[YOUR FEED ID]/fields
Body:
{
    "name": "aField",
    "type": "root/temperature",
    "required": true
}

Sending data to a feed

Now your composed feed is created and has a field attached to it, but you still can't send data to it. You must first validate it. Validating a feed creates the background data collection that will keep all the data you will send to it. Let's validate your feed.

POST http://localhost:3000/api/feeds/composed/[YOUR FEED ID]/validate

Now you can begin to send data to your feed, but you may ask which format you have to use. The field types define data format following the JSON Schema standard. To get the format to use with your feed, just ask it directly:

GET http://localhost:3000/api/feeds/composed/[YOUR FEED ID]/data-format
Response:
{
    "aField": {
        "format": {...},
        "required": true
    }
}

As you can see, the format for each field is given in JSON Schema. Now you can send your temperature data to the feed:

POST http://localhost:3000/api/feeds/composed/[YOUR FEED ID]/data
Body:
{
    "aField": {
        "unit": "cel",
        "value": 4.2
    }
}

Example of integration

Integration of IoT Hub with Geo2Tag platform