Developer API Doel Technologie Domein Authenticatie REST API Websockets API Lijsten 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', "wamp", {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)