Info
Content

Developer API

Doel

De API van de NXT server is gecreëerd om integraties vanuit andere systemen mogelijk te maken.

Technologie

  • REST API: voor het uitlezen van de installatie en het sturen van acties
  • WebSockets: voor het ontvangen van real-time push status updates
Activeren

De API is standaard uitgeschakeld.

Om de API te activeren, log je in op de NXT als administrator en ga je naar de 'Algemene instellingen'. Onder 'API' kan je de API activeren en de geheime gedeelde sleutel terugvinden voor het coderen van de JWT (JSON Web Token), nodig om verbinding te maken met de API.

Domein

De API is zowel lokaal (http://dobiss.local of http://[ip-adres]) bereikbaar als via de cloud naam van je NXT server (https://[mijndomein].mydobiss.com).

Indien je via de cloud werkt, is het gebruik van een beveiligde verbinding verplicht (HTTPS en WSS).

Authenticatie

De authenticatie gebeurt door het uitwisselen van een JWT (JSON Web Token) die gecodeerd moet worden met de gedeelde geheime sleutel die je terugvindt in de instellingen van je NXT server.

Door de geldigheid van de JWT te beperken in de tijd, kan je ervoor zorgen dat - zelfs al wordt de JWT onderschept - hij slechts beperkte tijd gebruikt zal kunnen worden. Zodra de geldigheid van de JWT verstreken is, zal de toegang geweigerd worden.

Het is uiteraard belangrijk om de geheime gedeelde sleutel (JWT secret key) nooit te delen of zichtbaar te maken.

Voorbeelden: Node.js

REST API

var jwt = require('jsonwebtoken');
var secret = 'sdfsljdflsjefolz496879846879sf7z6e8f4z9';
var token = jwt.sign({name:'my_application'}, secret, {expiresIn: "24h" });

var https = require('https');
var options = {
  host: 'my_domain.mydobiss.com',
  path: '/api/local/discover',
  headers: {'Authorization': 'Bearer ' + token }
};

callback = function(response) {
  var str = '';
  //another chunk of data has been received, so append it to `str`
  response.on('data', function (chunk) {
    str += chunk;
  });

  //the whole response has been received, so we just print it out here
  response.on('end', function () {
    console.log(str);
  });
}

https.request(options, callback).end();

WebSockets API

const WebSocket = require('ws');
var jwt = require('jsonwebtoken');
var secret = 'sdfsljdflsjefolz496879846879sf7z6e8f4z9/8e7f6z8e74f';
var token = jwt.sign({name:'my_application'}, secret, {expiresIn: "24h" });

const ws = new WebSocket('wss://my_domain.mydobiss.com/sockets/api', {headers : { "Authorization": "Bearer " + token}});

REST API

GET /api/local/discover

Geeft de lijst terug van alle uitgangen, scenario's, automatisaties, logische condities, temperatuurzones, audio zones en vlaggen.
De uitgangen zijn ingedeeld in logische groepen (cfr. touch layout), alle andere zijn gegroepeerd per type.

Request
  • Header: JWT in HTTP Authorization header
  • Body: leeg
Response

Structuur

  • groups: array of objects => alle groepen in uw domotica systeem
    • group: object
      • id
      • name
    • subjects: array of objects => alle elementen die deel uitmaken van deze groep
      • name
      • address
      • channel
      • type : zie lijst van mogelijke types
      • tags
      • icons_id
      • dimmable: true or false
  • temp_calendars: array of objects => de kalenders die gedefinieerd werden in de temperatuurzones
    • id
    • name
  • audio_sources: object => de verschillende audio bronnen per zone
    • audio zone id: object
      • source id => source name

Voorbeeld

{
    "groups": [
        {
            "group": {
                "id": 0,
                "name": "No group"
            },
            "subjects": [
                {
                    "name": "Input  1.10",
                    "address": "1",
                    "channel": "9",
                    "type": "1",
                    "tags": "1.10",
                    "icons_id": "100",
                    "dimmable": false
                }
            ]
        },
        {
            "group": {
                "id": "1",
                "name": "Gelijkvloers",
                "icons_id": "0",
                "color": null,
                "image": null,
                "weight": "0"
            },
            "subjects": [
                {
                    "name": "Eetkamer",
                    "address": "4",
                    "channel": "0",
                    "type": "16",
                    "tags": "4.1",
                    "icons_id": "0",
                    "dimmable": true
                },
                {
                    "name": "Living",
                    "address": "4",
                    "channel": "1",
                    "type": "16",
                    "tags": "4.2",
                    "icons_id": "0",
                    "dimmable": true
                }
            ]
        },
        {
            "group": {
                "id": 201,
                "name": "Scenarios"
            },
            "subjects": [
                {
                    "name": "Paniek",
                    "address": 201,
                    "channel": "2",
                    "type": 201,
                    "tags": "2",
                    "icons_id": 201,
                    "dimmable": false
                },
                {
                    "name": "Woning verlaten",
                    "address": 201,
                    "channel": "1",
                    "type": 201,
                    "tags": "1",
                    "icons_id": 201,
                    "dimmable": false
                }
            ]
        },
        {
            "group": {
                "id": 202,
                "name": "Automations"
            },
            "subjects": [
                {
                    "name": "Afwezigheid",
                    "address": 202,
                    "channel": "2",
                    "type": 202,
                    "tags": "2",
                    "icons_id": 202,
                    "dimmable": false
                },
                {
                    "name": "Gordijnen",
                    "address": 202,
                    "channel": "3",
                    "type": 202,
                    "tags": "3",
                    "icons_id": 202,
                    "dimmable": false
                }
            ]
        },
        {
            "group": {
                "id": 203,
                "name": "Logical conditions"
            },
            "subjects": [
                {
                    "name": "Afwezigheid AAN",
                    "address": 203,
                    "channel": "1",
                    "type": 203,
                    "tags": "1",
                    "icons_id": 203,
                    "dimmable": false
                },
                {
                    "name": "Donker buiten",
                    "address": 203,
                    "channel": "2",
                    "type": 203,
                    "tags": "2",
                    "icons_id": 203,
                    "dimmable": false
                }
            ]
        },
        {
            "group": {
                "id": 204,
                "name": "Temperature"
            },
            "subjects": [
                {
                    "name": "All zones",
                    "address": 204,
                    "channel": 255,
                    "type": 204,
                    "tags": "*",
                    "icons_id": 204
                },
                {
                    "name": "Badkamer",
                    "address": 204,
                    "channel": "4",
                    "type": 204,
                    "tags": "4",
                    "icons_id": 204,
                    "dimmable": false
                },
                {
                    "name": "Living",
                    "address": 204,
                    "channel": "3",
                    "type": 204,
                    "tags": "3",
                    "icons_id": 204,
                    "dimmable": false
                }
            ]
        },
        {
            "group": {
                "id": 205,
                "name": "Audio"
            },
            "subjects": [
                {
                    "name": "Keuken",
                    "address": 205,
                    "channel": "4",
                    "type": 205,
                    "tags": "4",
                    "icons_id": 205,
                    "dimmable": false
                },
                {
                    "name": "Living",
                    "address": 205,
                    "channel": "3",
                    "type": 205,
                    "tags": "3",
                    "icons_id": 205,
                    "dimmable": false
                }
            ]
        },
        {
            "group": {
                "id": 206,
                "name": "Flags"
            },
            "subjects": [
                {
                    "name": "Alarm",
                    "address": 206,
                    "channel": "2",
                    "type": 206,
                    "tags": "2",
                    "icons_id": 206,
                    "dimmable": false
                }
            ]
        }
    ],
    "temp_calendars": [
        {
            "id": "1",
            "enabled": null,
            "name": "Thuis",
            "created": "2007-01-01 02:41:59"
        },
        {
            "id": "2",
            "enabled": null,
            "name": "Minimum",
            "created": "2007-01-06 01:39:05"
        }
    ],
    "audio_sources": {
        "4": {
            "1": "Radio 1",
            "2": "Studio Brussel"
        },
        "3": {
            "1": "Radio 1",
            "2": "Studio Brussel"
        }
    }
}
GET /api/local/status

Geeft de status terug van het volledige systeem, 1 module of 1 uitgang.

Request
  • Header: JWT in HTTP Authorization header
  • Body: leeg of een Json object met de module of uitgang waarvan de status opgevraagd wordt
{
     "address"   : OPTIONEEL, adres van de module of het NXT actie adres (>200),
     "channel"   : OPTIONEEL, module uitgang (start bij 0) of NXT uitgang nummer (start op 1)
}
Response

Structuur

De gevraagde status als een array (zie Websockets API) of een waarde (indien address en channel meegestuurd werden).

POST /api/local/action

Om een actie uit te voeren in je DOBISS domotica systeem, post je de actie als een Json object in de body van je request naar dit eindpunt.

Request
  • Header: JWT in HTTP Authorization header
  • Body: Json object met de actie die uitgevoerd moet worden
{
     "address"   : VERPLICHT, adres van de module of het NXT actie adres (>200),
     "channel"   : VERPLICHT, module uitgang (start bij 0) of NXT uitgang nummer (start op 1),
     "action"    : VERPLICHT, actie id (0 = uit, 1 = aan, 2 = schakelen) // zie lijst van acties
     "option1"   : dimmer: waarde (0-100) / audio: volume (0-100) / temperatuur: stel temperatuur (0 = 5.0°C - 250 = 30.0°C) in of kalender (ID)
     "option2"   : dimmer: soft start/stop (0-254) / audio: bron / temperatuur: periode (0xFE = altijd / 0 = tot volgende actie / X = X x 15 minuten)
     "delayon"   : 
     	{
     	   "value" : 0..120	,	1..90	,	120/150/180..900	,	960/720/780..1440
           "unit"  : "s"	, 	"min"	,	"min"				,	"min"
        }
     "delayoff"  :
        {
           "value" : 0..120	,	1..90	,	120/150/180..900	,	960/720/780..1440
           "unit"  : "s"	, 	"min"	,	"min"				,	"min"
        }
     "condition" : 
        {   
           "id"    : ID van de logische conditie die nagekeken moet worden voor de uitvoering,
           "operator": 'true' or 'false'
     }
}
Response

Status van het element na het uitvoeren van de actie (bij vertraagd uitvoeren van de actie, zal deze status niet kloppen).

{
    "new_status": 0
}

Websockets API

Eenmaal verbonden met de Websockets API, zal deze elke status update in real-time doorsturen naar alle verbonden clients (push).
Structuur

De status bestaat uit 2 delen:

1. Status van alle verbonden uitgangsmodules (relais, dimmers, enz)

Per module een array met de status voor elk kanaal

{
  "2":[0,0,0,0,0,0,0,0,0,0,0,0],
  "3":[0,0,0,0,0,0,0,0,0,0,0,0]
}

2. Status van alle NXT elementen (temperatuur, audio, vlaggen, enz)

Een object met als "key" het kanaal en als "value" de status van dit element (dit kan een getal of een object zijn.

{
  "202":{"2":"0","3":"1","8":"1","5":"1","4":"0","7":"0","9":"0","1":"1","6":"0","10":"0"},
  "0":{"0":255,"1":255,"2":255,"10":0,"11":0,"12":0,"13":0,"14":0,"15":0,"16":0,"17":0,"18":0,"19":0,"20":0,"21":0,"22":0,"23":0,"30":0},
  "205":{
    "1":{"status":0,"volume":13,"source":0,"extra":"","system":"sonos"},
    "2":{"status":0,"volume":29,"source":3,"extra":"","system":"sonos"}
  },
  "204":{
    "4":{"status":0,"temp":"25.9","asked":"15.0","time":-30,"calendar":"2","cooling_status":null,"cooling_asked":null,"cooling_time":null},
    "3":{"status":0,"temp":"26.7","asked":"15.0","time":-30,"calendar":"2","cooling_status":null,"cooling_asked":null,"cooling_time":null}
  },
  "206":{"1":"0","2":0,"3":"0","4":0,"5":"0","6":"0","7":"0","8":"0","9":"0","10":"0","11":"0","12":"0"}
}

Soms worden deze 2 delen samen doorgestuurd, maar meestal worden ze apart verstuurd.

Lijsten

Subject types
0 NXT server DO5520
1 Inputmodule DO5480
4 DALI module DO5460
8 Relaismodule DO5411 / DO5475
16 Universele dimmodule DO5450
24 0-10V module DO5470
     
201 Scenario's  
202 Automatisaties  
203 Logische condities  
204 Temperatuur  
205 Audio  
206 Vlaggen  
207 RGB sturing  
208 Meldingen Status: enkel als de melding geactiveerd is, zal ze uitgestuurd worden als ze gebruikt wordt in een knop, scenario of automatisatie
209
 Energie
0 Actuele data
1 Totale data vandaag tot nu
2 Totale data gisteren
3 Data vandaag (meting op het kwartier)
4 Data gisteren (meting op het kwartier)
5 Data voorbije 30 dagen (per dag)
6 Data voorbije 2 jaar (per maand)
210
 Zigbee uitgangen  
211 Zigbee sensoren/drukknoppen  
213 Airco  
Acties
0

Uit
1 Aan
2 Schakelen aan/uit
3 Start dimmen
4 Stop dimmen
5 Knipperen en AAN (delayOn = interval / delayOff = totale duur)
6 Knipperen en UIT (delayOn = interval / delayOff = totale duur)
7 Knipperen en starttoestand (delayOn = interval / delayOff = totale duur)
8 -
9 Aan via PIR
10 Aan (ms)
104 Skip bron (alleen voor audio)
110 Activeer kalender (alleen voor temperatuur)
Back to top