Cluster API

Cluster is any server with compatible input API where Homebase can send measured data from its sensors.

There are several usefull API endpoints on provisioning which can be used by any registered cluster. For example cluster can pair any Homebase, ask for detailed information about paired Homebase or get Homebase’s secret used for data encryption.

Each Homebase can be paired only with one cluster. As soon as Homebase is paired and asks provisioning for configuration, the provisioning server sends cluster’s IP address and port. After this initial boot request, Homebase will connect to cluster and starts sending data.

To pair some Homebase, the cluster has to issue pair request to provisioning. This is done only once (for example when customer register himself and his Homebase’s serial number, the application will issue pair request for this Homebase).

Cluster Registration

Cluster can be registered in provisioning only by administrator (Energomonitor).

Each cluster in provisioning consists of IP addresses, human-readable description and authorization secret. For example:

 Description          Servers                       Secret
-------------   -------------------      ------------------------------
Dev Cluster A   MQTT 127.0.0.1:1883      mKKXFYdCjTsg74yyabTH4Mtt7Az4yD
Dev Cluster B   MQTT 192.168.3.54:1883   74yyabTH4Mtt7Az4yDYdCjTsgmKKXF

When Homebase is paired to Dev Cluster B, it sends measured data from sensors to MQTT server on address 192.168.3.53 and port 1883.

Authorization

Each API request from cluster to provisioning has to contain custom HTTP header X-EmClusterAuth. This header should contain valid secret key assigned to cluster. For example

X-EmClusterAuth: mKKXFYdCjTsg74yyabTH4Mtt7Az4yD

This secret key is generated by provisioning and is unique for each cluster.

Resources

All API endpoints described below has address: https://provisioning.energomonitor.com/api/... and has to contain authorization header. For example to pair Homebase with serial number 1234567890ABCDEF the URL is:

> POST /api/device/1234567890ABCDEF/pair/ HTTP/1.1
> Host: provisioning.energomonitor.com
> X-EmClusterAuth: mKKXFYdCjTsg74yyabTH4Mtt7Az4yD

GET /device/{SN}/

Returns detailed informations about Homebase with serial number {SN}. The response is JSON dictionary with keys device, alive, last_boot, upgrade, firmwares and cluster. For example:

{
    "alive": true,
    "cluster": {
        "title": "EM Dev Cluster",
        "enabled": true,
        "id": 1,
        "servers": {
            "http": ["127.0.0.124", 80],
            "mqtt": ["127.0.0.123", 1883]
        }
    },
    "device": {
        "partner": "pap",
        "sn": "DAB812C545369257",
        "type": "EWG3F"
    },
    "firmwares": {
        "avr": {
            "tags": ["MQTT", "10k buffer", "flash"],
            "version": "9.1 MQ1284P"
        },
        "bl": {
            "version": "tftp"
        },
        "msp": {
            "version": null
        }
    },
    "last_boot": "2016-06-14T13:45:53.955Z",
    "upgrade": "2016-06-05T19:17:13.407Z"
}

GET /device/{SN}/pair/

Check if Homebase with {SN} is paired to any cluster. The response is JSON dictionary with keys paired, your_device and detail.

Key paired is true if Homebase is paired to any cluster, false otherwise. Key your_device is true if Homebase is paired to authorized cluster (the one who issued this request). The last key detail contains human readable description.

{
    "detail": "Device DAB812C545369257 IS paired to some cluster.",
    "paired": true,
    "your_device": false
}

POST /device/{SN}/pair/

Pair (register) Homebase with serial number {SN} to authorized cluster. If pairing was successfull, the response has HTTP status code 200. If pairing failed (for example because Homebase is already paired) the status code is 304.

POST /device/{SN}/unpair/

Unpair (unregister) Homebase with serial number {SN} from cluster. The HTTP status 200 is returned if Homebase was unpaired, 304 otherwise.

GET /device/{SN}/secret/

Returns secret key for Homebase with given serial number. This secret is stored in non-volatile memory of each Homebase and does not change. JSON dictionary in response contains keys secret and detail. The key secret is HEX string of 256 bytes (thus 512 characters).

{
    "detail": "OK",
    "secret": "6ae644a6675d56c4.......382b"
}

This string has to be decoded to byte array before it can be used. For example in Python, the code can be:

> secret = '6ae644a6675d56c40e4574f..........382b'
> print len(secret)
512
> secret_decoded = secret.decode('hex')
> print len(secret_decoded)
256
> print secret_decoded
'j\xe6D\xa6g]V\xc4\x0eEt\xf2\xe1\x8d\xd5!......2&r{W8+'