Concept

Simple integrations can be created as discussed in the importer section. You can make more complex integrations that include complex authentication, custom data processing or invokation of other web services. These integrations can be created with JavaScript or by creating a web service that supports a standard API. When the web service is deployed on the Kubernetes cluster it can be used by importers and automations.

JavaScript

Scripts are used for relatively simple integrations that do not require intermediate caching of data or third-party integration libraries. A script has an init function that is called automatically to pass an encrypted secret. The secret may have fields for username, password or an URL. The secret is a JSON object that it created from the fields in the definition of the secret. The script should also support a get function that has an object as a parameter. It should return a JSON object with information about the value of the object. You can optionally define a set function. This takes the object, key and value and does something like calling another web service or sending a message. The scripts are executed an a sandbox environment on Node.js and support the ECMAScript (ECMA-262) language specification. Note that the get and set functions should be marked as async so that they are non-blocking.

class Example {

    init(secret) {
        this.secret = secret
    }

    async get(object){
        let result = await http.get(secret.url)
        return {object: object, temperature: result.t, humidity: result.h}
    }

    async set(object, key, value){
        // do something
    }
}

Webservice

Web services can be created in any framework such a Python, NodeJs, Go or Java. You can use third-party packages and libraries. The service is packaged in a Docker container and a Helm chart is provided for easy installation and upgrades by users. A web service should support the following APIs.

Authorization

This call returns a list of fields that are required by the service for authentication and configuration.

GET
/authorization

curl http://localhost:3090/authorization

Response:

{
    "serialnumber":"Serial number of the device",
    "accesscode":"Access code",
    "password":"Password that you use in the app"
}

With this call you pass the authorization information in a JSON body and an access token is returned. This token should be included in subsequent get or set requests.

POST
/token

curl -X POST -H 'Content-Type: application/json' -i http://localhost:3090/token --data '{"serialnumber":"112","accesscode":"123-1212","password":"secret"}'

Response:

{
    "Authorization":"eyJzZXJpYWxudW1iZXIiOiIxMTIiLCJhY2Nlc3Njb2RlIjoiMTIzLTEyMTIiLCJwYXNzd29yZCI6InNlY3JldCJ9"
}

Read

To get the values of an object use a GET request where the object id is include as a path parameter and the token is included in a header called Authorization:

GET
/:object

curl -X GET -H 'Content-Type: application/json' -H 'Authorization: eyJzZXJpYWxudW1iZXIiOiIxMTIiLCJhY2Nlc3Njb2RlIjoiMTIzLTEyMTIiLCJwYXNzd29yZCI6InNlY3JldCJ9' -i http://localhost:3090/112

Response:

{
    "object": "559911827",
    "thermostat": 15,
    "hot_water_active": 1,
    "outside_temperature": 19,
    "interior_temperature": 20.3,
    "pressure": 1.4,
    "display": "0H-203 Standby"
}

Update

To set the values of an object use a PUT request where the object id is include as a path parameter and keys and values are included as a JSON object in the body:

PUT
/:object

curl -X POST -H 'Content-Type: application/json' -H 'Authorization: eyJzZXJpYWxudW1iZXIiOiIxMTIiLCJhY2Nlc3Njb2RlIjoiMTIzLTEyMTIiLCJwYXNzd29yZCI6InNlY3JldCJ9' -i http://localhost:3090/112 --data '{"thermostat": "19"}'

JavaScript or Web Service

The table below helps you to choose between the standard connector, JavaScript engine or Web service for integrating functionality. For example, if you need to make an HTTP request with basic authentication you can do this with the standard importer in combination with a secret that contains information about the authorization header that is sent with the request. If the integration requires multi pass authentication where a JSON web token is obtained this can be implemented with a script of web service. A script does not allow you to share or store any information between sessions except what is specified in a secret.

Aspect	Standard connector	JavaScript	Web service
Ease of implementation	+	+	-
Ease to making changes	+	+	o
MQTT	+	+	+
HTTP	+	+	+
Use Node.js	+	+	+
Simple authentication	+	+	+
Multi step authentication	-	+	+
Multi step authentication	-	+	+
Caching and data storage	-	-	+
Integration with libraries	-	-	+
Use Python, C, Rust, Go, Java	-	-	+

In the next sections some example integrations with scripts and web services are discussed.