info@ipesoft.com
+421 907 703 854
Obchodná 9076/3D
010 08 Žilina
Slovensko
SK
10.9.2024
Komunikácia - Danfoss cloud
Komunikácia - Danfoss cloud
Firma Danfoss ponúka inteligentný systém vykurovania. Patria doň rôzne zariadenia, napríklad bezdrôtová termostatická radiátorová hlavica alebo ovládanie podlahového vykurovania Danfoss Icon.
Tieto zariadenia komunikujú prostredníctvom Zigbee rozhranias centrálnou jednotkou Danfoss Ally Gateway, ktorá slúži na komunikácius Danfoss Cloudom.
Pomocou mobilnej aplikácie Danfoss Ally sa vykonáva registrácia zariadení (priradenie k užívateľovej -e-mailovej adrese) a ich ručné ovládanie. Pre väčšie inštalácie je k dispozícii webový portál https://allypro.northeurope.cloudapp.azure.com, na ktorom je možné vytvoriť viacero lokalít a v každej lokalite niekoľko budov (objektov). Jednotlivé budovy môžu mať viacero poschodí a pre každé poschodie je možné zadefinovať plán poschodia a rozmiestniť jednotlivé zariadenia, sledovať ich stav a ovládať ich.
No dobre ... ale čo ak chceme čítať prevádzkové informácie z D2000? A prípadne aj nastavovať žiadanú teplotu a iné parametre - ručne, na základe časových kanálov alebo v prípade hotela na základe informácie o príchode hosťa?
V tomto prípade je k dispozícii rozhranie Danfoss Ally API. Pomocou HTTPS dotazov je možné získať aktuálne informácie o zaregistrovaných zariadeniach a tiež nastavovať žiadané hodnoty.
Keďže sa jedná v zásade o spracovanie JSON správ prijatých pomocou utility curl (v prípade ovládania o ich generovanie a posielanie), komunikáciu sme implementovali ako ESL skript – v prípade záujmu je možné ho stiahnuť priamo z našeho webu.
Aby sme mohli k zariadeniam pristupovať, tak každý užívateľský účet, ku ktorému sú priradené Danfoss zariadenia v mobilnej aplikácii Danfoss Ally, musí byť zaregistrovaný na vývojárskom portáli https://developer.danfoss.com. Následne musí byť pod účtom vytvorená „aplikácia“ (napr. nazvaná D2000) a do nej pridané rozhranie "Danfoss Ally API". Aplikácii je priradená dvojica kľúčov "Consumer Key" a "Consumer Secret". Tieto je nutné skopírovať a vytvoriť reťazec Consumer Key:Consumer Secret a previesť ho na BASE64 napr. pomocou https://www.base64encode.org.
Výsledný kľúč je potrebné uložiť do štruktúrovanej premennej SV.Danfoss_Credentials – D2000 teda podporuje prácu s viacerými užívateľskými účtami. Kľúč použije D2000 na získanie tokenu z Danfoss cloudu (z adresy https://api.danfoss.com/oauth2/token). Token slúži na autorizáciu pri práci so zariadeniami Danfoss, ktoré sú priradené ku konkrétnemu účtu. Platnosť tokenu je aktuálne 1 hodina, takže pred uplynutím platnosti tokenu musí D2000 získať nový token – opäť pri tom použije kľúč.
Aktuálne dokáže D2000 pracovať s tromi typmi zariadení, každý typ sa ukladá do vlastnej štruktúrovanej premennej:
• SV.Danfoss_Ally_Gateway - zariadenia typu "Danfoss Ally™ Gateway"
• SV.Danfoss_Ally_Radiator_Thermostat - zariadenia typu "Danfoss Ally™ Radiator Thermostat"
• SV.Danfoss_Icon_RT - zariadenia typu "Icon RT" (Room Thermostat)
• SV.Danfoss_Icon_Zigbee_Module - zariadenia typu "Icon Zigbee Module"
• SV.Danfoss_Zigbee_Repeater - zariadenia typu "Danfoss Zigbee Repeater"
Tieto štruktúry sa automaticky zväčšia a naplnia sa zariadeniami načítanými z Danfoss cloudu.
Skript E.Danfoss_Cloud po stiahnutí zoznamu zariadení a ich hodnôt (z adresy https://api.danfoss.com/ally/devices) pre každé zariadenie v zozname prechádza štruktúrovanú premennú SV.Danfoss_DeviceType. V nej sú napojené hore uvedené tri štruktúry a obsahuje aj identifikátory typov zariadení.
V prvom stĺpci Device_type sú typy zariadení (identické ako v JSON správe), v druhom stĺpci Structure sú jednotlivé štruktúry. Tretí stĺpec Transform popisuje transformácie a typy hodnôt. Napríklad položka online je Boolean, status.mode je Text, status.battery_percentage je číslo násobené 1 (M1), status.temp_set je číslo násobené 10 (M10). Ďalšie transformácie je možné pridať podľa potreby.
Keď je teda identifikovaná cieľová štruktúra pre konkrétny typ zariadenia, je možné ju napĺňať. Poďme sa pozrieť na obsah JSON-u pre jedno zariadenie:
Vidíme niekoľko položiek na najvyššej úrovni (id, name, device_type, online). Tie sú spoločné pre všetky typy zariadení. Špecifické hodnoty sú ale v rámci poľa status a jedná sa o dvojice code – value.
Preto sme parsovanie navrhli tak, aby položkám najvyššej úrovne JSON zodpovedali stĺpce štruktúrovanej premennej s rovnakým názvom (id, name, device_type, online) a špecifickým položkám JSON stĺpce štruktúrovanej premennej s názvom status.<code>, napr. status.switch, status.temp_set. Jednoduchým pridaním ďalších stĺpcov s požadovanou syntaxou (napr. status.fault) je možné dosiahnuť spracovanie ďalších položiek.
Po prečítaní položky z JSON správy je táto ešte transformovaná (viď pole Transform popísané vyššie). V prípade položiek typu Text, Boolean a Integer (M1) sa jedná o jednoduché filtrovanie (hodnota sa priradí do štruktúry iba ak sa zmenila), v prípade M10 sa hodnota ešte vydelí desiatimi. Termostaty a iné zariadenia, ktoré sú napájané batériou a optimalizované na nízku spotrebu energie, zrejme nepoužívajú reálne čísla a reprezentujú všetky hodnoty ako celé čísla.
V JSON správe si môžete všimnúť aj textové hodnoty položky value, napr. {"code":"mode","value":"manual"}
{"code":"SetpointChangeSource","value":"Schedule"}
Pre takéto položky môžme v budúcnosti (keď získame od Danfossu špecifikáciu všetkých možných hodnôt) vytvoriť nový typ konverzie mapujúci textové hodnoty na číselník (napr. manual -> 0, auto -> 1).
Pokiaľ štruktúra neobsahuje konkrétne zariadenie, je hľadaný prázdny riadok (riadok s prázdnym id) a využitý tento. Pokiaľ prázdny riadok nie je nájdený, štruktúra je zväčšená (o 10 riadkov). Tento mechanizmus sa využije najmä pri prvom spustení a potom výnimočne - pri pridávaní nových zariadení alebo ich výmene.
Aby nedochádzalo k neustálemu zväčšovaniu štruktúrovaných premenných, odporúčame vopred zmeniť rozmer jednotlivých štruktúrovaných premenných podľa počtu zariadení, prípadne aj s rezervou.
V prvom stĺpci štruktúrovaných premenných pre jednotlivé typy zariadení (s názvom idCred) je číslo riadku štruktúry SV.Danfoss_Credentials, tj. je zrejmé, k akému užívateľskému účtu konkrétne zariadenie patrí. To môže byť potrebné jednak z aplikačných dôvodov, ale je to nevyhnutné aj pri ovládaní.
Ovládanie je realizované cez adresu https://api.danfoss.com/ally/devices/<device_id>/commands pomocou POST príkazu, ktorý obsahuje JSON text. Príklad je v skripte E.Danfoss_TestWrite – nastavenie žiadanej teploty pre prvý termostat v štruktúre SV.Danfoss_Ally_Radiator_Thermostat.
Vidieť, že zápis realizuje RPC (remote procedure call) CommandDevice v skripte E.Danfoss_Cloud. Tiež je vidieť, že nastavovanú hodnotu je nutné transformovať (v príklade násobené desiatimi). Táto funkcionalita by sa dala do budúcna automatizovať (na základe stĺpca Transform štruktúry SV.Danfoss_DeviceTypes).
Záver
Komunikačný protokol Danfoss Cloud implementovaný formou ESL skriptu je voľne dostupný pre použitie v D2000. Do budúcna predpokladáme jeho rozširovanie a pridávanie ďalších typov zariadení podľa požiadaviek zákazníkov. Skript E.Danfoss_Cloud môže zároveň záujemcom poslúžiť na študijné účely – obsahuje ukážky práce s externou utilitou (curl), parsovania JSON súborov a práce so štruktúrovanými premennými.
11.4.2024, Ing. Peter Humaj, www.ipesoft.com
Iné blogy