How it Works
Danfoss
Loading...
E
Loading...
Loading...
ECL Portal API
Operating guide
40 pgs1.15 Mb0
Operating guide [da]
40 pgs1.17 Mb0

Danfoss ECL Portal API Operating guide [da]

Download
Betjeningsguide
ECL Portal API Web interface til ECL Portal database
1.0 Indholdsfortegnelse
1.0 Indholdsfortegnelse .............................................................................................................................................................................................................................. 1
2.0 Introduktion ............................................................................................................................................................................................................................................. 2
3.0 Versionstabel ............................................................................................................................................................................................................................................ 2
4.0 Begrebsoversigt ...................................................................................................................................................................................................................................... 2
5.0 Generelt ............................................................................................................................................................................................................................................... 3
6.0 Sikkerhed ............................................................................................................................................................................................................................................... 3
6.1 Oprettelse af tredjepartskode .................................................................................................................................................................................................. 4
6.2 Tildeling af adgang til tredjepart ........................................................................................................................................................................................... 5
7.0 Snitflader ............................................................................................................................................................................................................................................... 6
7.1 API-format ....................................................................................................................................................................................................................................... 7
7.2 Fremtidige versioner ................................................................................................................................................................................................................... 7
7.3 Tidsformater ................................................................................................................................................................................................................................... 7
8.0 Stamdata service (Master Data) ........................................................................................................................................................................................................ 9
8.1 getEclMasterData request parametre ................................................................................................................................................................................... 9
8.2 getEclMasterData response .....................................................................................................................................................................................................10
8.4 Statuskoder for respons ............................................................................................................................................................................................................17
9.0 Aflæsningsservice (Readings) ......................................................................................................................................................................................................... 17
9.1 getReadings Request ................................................................................................................................................................................................................ 18
9.2 getReadings Response ............................................................................................................................................................................................................. 19
10.0 Brug af snitfladen ..............................................................................................................................................................................................................................21
10.1 Udtræk af stamdata ..................................................................................................................................................................................................................23
10.1.9 Udlæs seneste værdi for en eller flere sensorer på tværs af målere tilsluttet ECL regulatoren .......................................................35
10.1.10 Udlæs en periode af historiske data for en eller flere sensorer på én måler tilsluttet ECL regulatoren .....................................35
10.2 Formatforskelle på dataudtræk ............................................................................................................................................................................................39
© Danfoss |2021.01
AQ131886471802da-000301 | 1
Betjeningsguide ECL Portal API
2.0 Introduktion
Dette dokument er en beskrivelse til tredjepart, til brug ved implementering af softwareklienter til udtræk af data fra ECL Comfort 296 / 310 Portal (ECL Portal).
3.0 Versionstabel
Version Dato Ændring
1.00 2013-09-25 Første version
1.10 2013-10-25 Tilføjet afsnit om oprettelse af tredjepartskode, fremtidige version, tidsformater. Tilføjet JSON eksempler for forespørgsler og svar.
1.11 2013-10-29 Tilføjet eksempel om forskel på dataudtræk fra ECL Portal og ECL Portal-API. Tilføjet eksempel om tidsformat i aflæsninger.
1.12 2014-04-01 Tilføjet nogle få uddybende forklaringer og eksempler.
4.0 Begrebsoversigt
API Application Programming Interface. Et interface for udvekling af applicationsspecifik information.
Device En enhed. Typisk brugt i forbindelse med en log-enhed.
ECL Comfort 296/310 En ernvarmeregulatormodel fra Danfoss A/S.
HTTPS HyperText Transfer Protocol. En krypteret protokol til overførsel af information.
Konfigurerbar
indgang
Kunde En person, virksomhed eller kommune som vil have udlæst data fra ECL Portalen
JSON JavaScript Object Notation. Et åbent data format til udveksling af data mellem en server og et internetprogram.
M-bus En kommunikationsprotokol typisk anvendt af varme- og energimålere
Paging Sideinddeling. For at undgå at overføre alt for mange information på én gang inddeles en datamænge i flere
Reading En aflæsning. Log-data udlæst fra web-API’et fra en log-enhed
Request En forespørgsel til web-API’et
Response Svar fra web-API serveren på en forespørgsel
REST Representational State Transfer. En software arkitektur stil, der kan bruges til konstruktion af internettjenester
Serverkode En unik kode udstedt af Danfoss til tredjepart
SSL Secure Sockets Layer. En kryptering til sikker udveksling af information, der bl.a. anvendes på internettet (HTTPS)
Stamdata Grundlæggende data for en ECL Comfort 296 / 310 regulator
Nogle sensorindgange på en ECL Comfort 296 / 310 regulator kan valgfrit konfigureres til at måle temperatur, puls, frekvens, 0-10 V analog signal eller digital ON/OFF
sider, hvor kun én side læses af gangen.
Tredjepartskode En kode oprettet af kunden på ECL Portalen, som kunden udleverer til tredjepart
URL Unifor Resource Locator. En internetadresse
UTC Coordinated Universal Time. En standard for tidskoordinering med udgangspunkt i Greenwich, London.
Tidszoner angives i forhold til UTC.
Web-API Et API tilpasset internettet.
tredjepart Et eksternt firma, som en kunde får til at udvikle software til udlæsning af data fra ECL Portalen til et eksternt
system. Kan være identisk med kunden.
2 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
5.0 Generelt
De data, der er tilgængelige via ECL Portal web-API’et, afhænger af den ECL applikationsnøgle, der sidder i den pågældende ECL Comfort 296 / 310. Dvs. de tilgængelige datasæt er forskellige for hver ECL applikationstype og kan derudover også afhænge af de forskellige eksterne dataopsamlingsapparater, såsom M-bus-målere og konfigurerbare indgange, som ECL regulatorerne kan udstyres med.
ECL Portalen hjemhenter data fra ECL regulatorerne én gang i timen kort efter klokken hel. Den indbyggede ECL-log indeholder applikationsspecifikke signaler såsom målte temperaturer og temperaturreferencer samt eventuelt vindstyrke, tryk eller flow afhængig af den installerede applikation. ECL-loggen indeholder data med 15 minutters mellemrum. Hvis kunden har oprettet konfigurerbare indgange eller tilsluttet M-bus-målere, vil aktuelle værdier for disse også blive hentet én gang i timen.
Hvis det ikke er muligt at hente data fra en ECL regulator pga. kommunikationsfejl eller andet, vil ECL-loggen blive forsøgt hentet ved næste hjemtagning næste time. Den interne ECL-log i ECL regulatoren indeholder data for de seneste 10 dage, så hvis det ikke har været muligt at hente log fra en ECL regulator i 10 dage, vil data gå tabt på ECL portalen og vil dermed ikke være tilgængelig gennem web­API’et.
Så snart data er tilgængelig på ECL Portalen vil de også være tilgængelige gennem ECL Portal web-API’et. Det er ikke muligt at hente data gennem web-API’et, som ikke er tilgængelig på ECL Portalen. Hvis en kunde for eksempel sletter en ECL log eller M-bus-måler på ECL Portalen, vil den heller ikke længere være tilgængelig gennem web-API’et.
Der gemmes ikke data for konfigurerbare indgange og M-bus-målere i ECL regulatoren, så historiske værdier vil ikke blive udlæst ved næste loghentning, når der ikke har været kontakt til ECL Portalen.
Guides for individuelle ECL applikationer kan findes på www.ecl.doc.danfoss.com, hvis det skulle være nødvendigt for tredjepart at have mere specifik viden om de data, der kan trækkes ud af ECL regulatorerne.
En kommunikationsbeskrivelse for ECL regulatorer kan findes her: http://heating.danfoss.com/PCMPDF/VILGV502_ECL_Comfort_210_296_310_Communication.pdf eller ved at google ”ecl communication description” for at finde nyeste version. Kommunikationsbeskrivelsen indeholder bl.a. en generel liste med parametre, som logges af nogle applikationer.
6.0 Sikkerhed
Da der er tale om en ekstern snitflade mod omverdenen, er det særligt vigtigt at sikre, at man ikke kan skaffe sig adgang til andres data.
Første element i sikring af data er identifikation, så man kan validere, hvorvidt den klient, der kalder ECL Portal web-API’et, har ret til at se de data, der efterspørges. I forespørgslerne skal man derfor altid angive:
• Serverkode. Denne udstedes af Danfoss til tredjepart eller kunde, således at åbning for datasnitfladen er en aktiv handling foretaget af Danfoss. Her er tale om en oprettelse ved indgåelse af juridisk aftale.
• ECL serienummer. Anvendes til at identificere en ECL regulator af interesse. Serienummeret kan findes inde i ECL regulatorens menu eller på ECL Portalen
• Tredjepartskode. Oprettes af kunden på ECL Portalen og udleveres til tredjepart
Udover, at tredjepart eller kunden skal have oplyst en serverkode og kende serienummeret, så skal kunden selv knytte tredjepartskoder til ECL regulatoren. På den måde har kunden mulighed for selv at styre, hvilke tredjepart personer og systemer de vil lade trække på dataene ved at tildele dem forskellige tredjepartskoder, som naturligvis også kan inddrages igen enkeltvis.
Dvs., for at få fat i data fra en given ECL regulator, skal man kende dens serienummer, have udstedt en serverkode fra Danfoss og have tildelt sig selv, sit system eller tredjepart en ECL-specifik tredjepartskode.
Ganske som med traditionelle brugernavn/passwordkombinationer vil data kunne komme i de forkerte hænder, hvis kombinationen kompromitteres, da en udefrakommende i så fald vil kunne gøre brug af de samme koder og foretage sine egne forespørgsler. Sikkerheden beror således her på, hvordan kunden og tredjepart beskytter disse oplysninger.
Serverkoder udstedes til kunden/tredjepart enkeltvis og må ikke deles af flere kunder, da den i henhold til den juridiske aftale kan afmeldes ved ophør af aftale eller ved misbrug.
Datakommunikation gennem web-API’et kræver SSL-understøttelse. Hvis en klient sender forespørgsler over HTTP, vil den blive omdirigeret til HTTPS.
AQ131886471802da-000301
© Danfoss | 2021.01 | 3
Betjeningsguide ECL Portal API
6.1 Oprettelse af tredjepartskode
Brug menuen ”Tredjepartskoder”
Tildel et navn til tredjepartskoden for at holde styr på alle koder og marker ”Aktiveret” indstillingen for at gøre koden aktiv.
Koden vil nu være på listen over oprettede koder.
Tryk på linket ”ECL’er” for at komme til siden, hvor koden kan tilde­les specifikke ECL regulatorer.
Man kan her tildele samme kode til flere ECL regulatorer, og man kan tildele flere koder til samme ECL regulator, så man bedre kan styre, hvem der har adgang til hvad.
4 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
6.2 Tildeling af adgang til tredjepart
a) Hvis kunden ikke tidligere har givet den pågældende tredjepart adgang til data for nogle ECL regulatorer, som slutkunden administrerer, så opretter slutkunden en kode til tredjepart under menuen ECL > Tredjepartskoder. b) Slutkunden knytter den relevante ECL regulator til den relevante tredjepartskode. c) Slutkunden oplyser tredjepart om ECL serienummeret og tredjepartskoden.
Med disse 3 informationer (Serverkode, ECL serienummer, tredjepartskode) har tredjepart nu mulighed for at tilgå data for ECL regula­toren via web-API’et.
Her beskrives de konceptuelle snitflader, der vil blive tilgængelige via web-API’et. Med konceptuelle menes, hvad man kan spørge efter, herunder hvilke oplysninger, der kræves for at spørge, samt hvilke informationer man får retur fra sådanne forespørgsler.
Når man henter aflæsninger for en given periode, kan det vise sig, at perioden indeholder et stort antal aflæsninger, som ikke egner sig til at overføre via et http-request af én omgang. Derfor giver det god mening at operere med såkaldt paging. Dvs. at man i sin forespørgsel, ud over at indikere perioden, kan indikere, hvor mange aflæsninger man ønsker at modtage ad gangen. Af det svar man får retur, kan man så se, om man har fået alle aflæsninger med tilbage på ”første side”(/response), eller om man skal hente flere, og hvor mange man kan forvente at skulle hente i alt. På baggrund heraf kan man så spørge om den næste side og så fremdeles. Samtidig definerer systemet en standard sidestørrelse og en maksimal sidestørrelse, således at man ikke behøver at angive en sidestørrelse, og heller ikke risikerer, at en klient beder om et urealistisk stort load af data i én forespørgsel.
Da en ECL regulator kan operere med flere devices (log-enheder), med forskellige log-frekvenser, er det svært at lave en logisk ”sideom­brydning” i det tilfælde, at alle data ikke kan returneres på én gang. Når man henter aflæsninger, er det i forvejen relevant at vide, hvilke devices der er tilgængelige på en ECL regulator, hvilke der er aktive, etc. Der er således brug for at kunne skaffe sig den information, når der skal hentes aflæsninger, men også, såfremt tredjepart ønsker at lagre/synkronisere detaljer om ECL regulatorerne, devices og kanaler – såkaldt stamdata.
Eksempel på tilgængelige devices og kanaler i en ECL Comfort 296 / 310 regulator med en given applikation, der har tilsluttet to var­memålere via m-bus:
AQ131886471802da-000301
© Danfoss | 2021.01 | 5
Betjeningsguide ECL Portal API
7.0 Snitflader
Device type Kanaler Beskrivelse
EclLogDevice S1 Disse kanaler tilhører sensorer og referenceværdier,
der bruges af applikationen
S2
S3
S4
S5
S6
S7
RefS3
RefS4
RefS5
RefS9
RefS10
EclConfigInputDevice S9 Denne indgang benyttes ikke af applikationen og
kan derfor anvendes som konfigurerbar indgang
EclConfigInputDevice S10 Denne indgang benyttes ikke af applikationen og
kan derfor anvendes som konfigurerbar indgang
EclConfigInputDevice S11 Denne indgang benyttes ikke af applikationen og
kan derfor anvendes som konfigurerbar indgang. Kræver ECA 32 modul i ECL Comfort 296 / 310
EclConfigInputDevice S12 Denne indgang benyttes ikke af applikationen og
kan derfor anvendes som konfigurerbar indgang. Kræver ECA 32 modul i ECL Comfort 296 / 310
EclConfigInputDevice S13 Denne indgang benyttes ikke af applikationen og
kan derfor anvendes som konfigurerbar indgang. Kræver ECA 32 modul i ECL Comfort 296 / 310
EclMBusDevice volume_flow Disse kanaler er tilgængelige i den pågældende
varmemåler, der er tilsluttet via m-bus
flow_temperature
volume
EclMBusDevice volume_flow Disse kanaler er tilgængelige i den pågældende
varmemåler, der er tilsluttet via m-bus
flow_temperature
volume
energy
return_temperature
6 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
Der vil af den grund blive foretaget en opdeling i de services web-API’et stiller til rådighed. En service, som opererer med stamdata (masterData), og en service, som opererer med aflæsninger (readings). For at gøre overførslen af aflæsninger så optimal som mulig mht. performance, vil disse kald kun returnere de rå værdier. For at tolke dem (f.eks. mht. enheder m.v.) skal de således holdes op mod stamdata.
7.1 API-format
Web-API’et er et REST (REpresentational State Transfer) API via HTTPS(GET) requests, hvor argumenter udtrækkes som en kombination af URL komponenter og URL query parametre.
Responsformatet vil altid være minimalistisk JSON pga. performance. Senere i dette dokument vises eksempler på requests i det rette format.
Når tredjepart har modtaget serverkode, tredjepartskode og serienummer for en ECL regulator, kan de afprøve web-API’et ved at paste et eksempel fra et senere afsnit ind i en browser såsom Chrome, hvorved de vil få et svar tilbage. JSON Viewer plug-in’et til Notepad++ kan nemt bruges til at formatere den modtagne JSON tekst til et letlæseligt format.
7.2 Fremtidige versioner
Snitfladen er forberedt til, hvis der i fremtiden skulle ske ændringer i formatet ved, at der skal medsendes en snitfladeversion i forespørg­slerne. Versionsindikatoren skal angives på formen:
https://{host}/endpoint/{version}/...
hvor {version} skal erstattes med navnet på versionsformatet. For første version er versionsnavnet ”v1”. Se eksempler i senere afsnit, hvor det bruges. Endpoint kan være enten masterData eller readings, som bliver forklaret i senere afsnit.
Når nye versioner introduceres, vil der blive annonceret en slutdato for den gamle version, således, at tredjepartsfirmaer har en periode, hvor de kan opdatere deres software til den nye version.
Efter slutdatoen vil den gamle version ikke længere være tilgængelig. Når en nye version er tilgængelig, vil det blive annonceret på for­siden af ECL Portalen og/eller nyhedsbrev.
{host} skal erstattes med eclwebapi.danfoss.dk for web-API’et tilknyttet den danske ECL portal på ecl.portal.danfoss.dk. For web-API’et på den internationale ECL Portal skal {host} erstattes med eclwebapi.danfoss.com. Det er ikke muligt at tilgå ECL regulatorer på den danske portal gennem web-API’et til den internationale portal eller omvendt.
7.3 Tidsformater
Tidsstempler i web-API’et følger ISO 8601 standarden. Det vil sige, at tidsstempler som default vil være i UTC og angives som:
2013-04-18T08:53:00.0Z
I responsbeskeder vil tidsstempler altid være i UTC og tredjepartssoftware kan derefter omregne til andre tidszoner efter behov. I stam­data for individuelle ECL regulatorer angives den tidszone, som er blevet angivet under ECL regulatorens data af ejeren/administratoren på ECL Portalen.
Det er muligt at angive tidsstempler i andre tidszoner, når man efterspørger data ved at angive den lokale tidszone. Ovenstående tidsstempel vil dermed udtrykkes som
2013-04-18T10:53:00.0+02:00
”+”-tegnet skal udtrykkes som ”%2B” i forespørgsler og ”-”-tegn skal udtrykkes som ”%2D”
Hvis tiden i ECL regulatoren ikke passer, eller tidszonen på ECL Portalen er forkert, kan tidsstemplerne i de udtrukne data være mis­visende. Aflæsningseksempel for ECL-log udlæst fra ECL Portal-API 2013-10-29 kl. 09:40 dansk normaltid
AQ131886471802da-000301
© Danfoss | 2021.01 | 7
Betjeningsguide ECL Portal API
{ “tracking”: { “serverRequestId”: “0af3a240-0a36-45ae-b8af-9e24f52103eb”, “from”: “2013-10-29T09:40:45.318+01:00”, “direction”: “reverse”, “page”: 1, “pageSize”: 1000, “resultReadings”: 1000, “totalReadings”: 69346, “totalPages”: 70 }, “data”: [{ “externalDeviceId”: “cfbd9943-9e49-4d19-a052-6424de7041e8”, “readings”: [{
“id”: 124280485, “timestamp”: “2013-10-29T07:45:00.0Z”, “receivedTime”: “2013-10-29T08:00:04.55Z”, “manualEntry”: false, “value1”: 192, “value2”: 48.09, “value3”: 90, “value4”: 192, “value5”: 28.5, “value6”: 192, “value7”: 50, “value8”: 192, “value9”: 0, “value10”: 0 }, { “id”: 124280484, “timestamp”: “2013-10-29T07:30:00.0Z”, “receivedTime”: “2013-10-29T08:00:04.52Z”, “manualEntry”: false, “value1”: 192, “value2”: 48.09, “value3”: 90, “value4”: 192, “value5”: 28.5, “value6”: 192, “value7”: 50, “value8”: 192, “value9”: 0, “value10”: 0 } ] }] }
Den første ”from”-parameter er aktuelt tidspunkt for udlæsning, her vist med tidszone +01:00. ”timestamp” er ECL regulatorens tid for den aktuelle sample. ”receivedTime” er ECL Portalens tid på det tidspunkt, hvor den udlæste data fra ECL regulatoren. Da der udlæses data én gang i timen, vil der typisk være 4 samples (én for hvert kvarter) med samme ”receivedTime” værdi, men hvis der har været udfald i datakommunika­tionen, kan der være udlæst mere data på samme tid.
Hvis der ikke er data i databasen for det givne tidspunkt i den givne retning, vil data-feltet i responset være tomt.
Aflæsningseksempel for ECL-log udlæst fra ECL Portal-API’et 2014-04-01 kl. 12:05 dansk sommertid. Her er tiden i ECL regulatoren indstil­let forkert, og der er valgt en forkert tidszone (UTC+02:00 i stedet for UTC+01:00) på ECL Portalen.
8 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
{ “tracking”: { “serverRequestId”: “07c49346-aa90-4e45-9f20-610931d5887e”, “from”: “2014-04-01T12:05:32.430+02:00”, “direction”: “reverse”, “page”: 1, “pageSize”: 1, “resultReadings”: 14 }, “data”: [{ “externalDeviceId”: “5a84dbcc-a9c0-474f-9c12-5db4884fc6ed”, “readings”: [{ “id”: 79779710, “timestamp”: “2012-10-04T02:15:00.0Z”, “receivedTime”: “2014-04-01T10:00:52.293Z”, “manualEntry”: false, “value1”: -1.25, “value2”: -9.46, “value3”: 26.17, “value4”: 26.66, “value5”: -24.21, “value6”: 45.84, “value7”: 17.8, “value8”: 40.24, “value9”: 10, “value10”: 50.83, “value11”: 30, “value12”: 0 }] }] }
Den tilhørende log udlæst som en Excel-fil fra ECL Portalen viser:
Her kan man se, at ECL regulatorens tid ved den seneste sample var 2012-10-04 05:15:00, men i dataene fra web-API’et var tiden 2012-10­04 02:15:00Z. Der er således 3 timers forskel, som kommer fra tidszone (som er +2 timer) og sommertid (+1 time) Ved at sammenligne de tre tider (from, timeStamp og receivedTime) kan man tjekke, om tiden er indstillet korrekt i ECL regulatoren, og om den rigtige tidszone er valgt på ECL Portalen.
8.0 Stamdata service (Master Data)
Her beskrives, hvad stamdata servicen kan anvendes til. Servicen har i denne første version kun én metode. Metoden er getEclMasterData, og henter alle relevante stamdata for en given ECL regulator, herunder tilsluttede målere. Det omfatter også data, som er nødvendige for at tolke de aflæsninger, man kan hente. Neden­stående beskriver det konceptuelle indhold af request og response.
8.1 getEclMasterData request parametre
Parameter Beskrivelse Eksempel
serverCode Del af identifikation jf. afsnit 5 omkring sikkerhed. FirmaA
eclSerial Del af identifikation jf. afsnit 5 omkring sikkerhed. 123456792
eclAccessCode Del af identifikation jf. afsnit 5 omkring sikkerhed. Kode5
clientRequestId Valgfri tekst, som kan bruges til at implementere sporbarhed i tredjepart
systemer, der fungerer asynkront. Kan udelades, men vil ellers typisk være en autogenereret unik ID.
AQ131886471802da-000301
555b7f4d-7e1a-4d76-a4f0­be8fb52b7c80
© Danfoss | 2021.01 | 9
Betjeningsguide ECL Portal API
8.1.1 getEclMasterData request parametre eksempel
Eksempel med version=v1, serverCode=CompanyA, eclSerial=123456792, eclAccessCode= Code5.
https://{host}/masterdata/{version}/{eclSerial}?serverCode={serverCode}&eclAccessCode={eclAccessCode}
https://eclwebapi.danfoss.dk/masterdata/v1/123456792?serverCode=FirmaA&eclAccessCode=Kode5
8.2 getEclMasterData response
Af sporbarhedsmæssige årsager kommer følgende oplysninger retur i svaret fra serveren.
Element Beskrivelse Eksempel
clientRequestId Det ID, som blev sendt med under
selve requestet for at muliggøre sporbarhed hos tredjepart.
serverRequestId Serveren tildeler selv hver request
et unikt ID, da der ikke er krav om at man skal medsende et unikt klient ID på tværs af kunder. Dette ID kan bruges, hvis man er i tvivl om serverens håndtering af et request, da der vil blive logget forskellige statistiske informationer omkring hvert request (se afsnit 5.4 omkring sporbarhed).
8.2.1 getEclMasterData response eksempel
Stamdata er nærmere beskrevet i næste afsnit
{ “tracking”: { “serverRequestId”: “d4b86aa4-f4a0-4ce8-9f14-3c7bd3cc3c80” }, “masterData”: { “application”: “A376.1”, “applicationVersion”: “4.00”, “hardwareModel”: “ECL 296 / 310, 230 V”, “hardwareVersion”: “A”, “softwareBuild”: “7232”, “hardwareProductionTime”: “3.2010”, “firmwareVersion”: “1.48”, “serialNumber”: “123456792 ”, “createdOnPortal”: “2012-09-07T08:16:53.543Z”, “timezone”: “Europe/Copenhagen”, “location”: { “street”: “Solitudevej”, “streetNumber”: “13A”, “city”: “Andeby” }, “name”: “ECL name”, “portalGroup”: “Test ECL controllers”, “devices”: [List of log devices has been moved in this example] } }
555b7f4d-7e1a-4d76-a4f0­be8fb52b7c80
9cd4df10-09cc-4ec7-8b4e­c1180b21d9d9
10 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
8.2.2 Stamdata
Følgende grundlæggende stamdata kommer ligeledes retur med responset for selve ECL regulatoren.
Element Beskrivelse Eksempel
application Hvilken applikation ECL regulatoren
kører
applicationVersion Version af applikationen 4.00
hardwareModel Hardware modelnummer ECL 296 / 310, 230 V
hardwareVersion Hardware version A
softwareBuild * Software build nummer 7232
hardwareProductionTime Hardware produktionstidspunkt 3.2010
firmwareVersion Firmware versionsnummer 1.48
serialNumber Serienummer 123456792
createdOnPortal Dato for hvornår ECL regulatoren
blev oprettet på (først forbundet til) portalen
timezone Tidszone ECL regulatoren er placeret i
(valgt på ECL Portal)
location:Street ** Gade ECL regulatoren er placeret på
(hvis indtastet på ECL Portal)
A376.1
2013-04-18T08:53:00.0Z
Europe/Copenhagen
Solitudevej
location:StreetNumber ** Husnummer ECL regulatoren er
placeret på (hvis indtastet på ECL Portal)
location:Zip ** Postnummer ECL regulatoren er
placeret i (hvis indtastet på ECL Portal)
location:City ** By ECL regulatoren er placeret i (hvis
indtastet på ECL Portal)
location:Country ** Land ECL regulatoren er placeret i (hvis
indtastet på ECL Portal)
name Navn (indtastet på ECL Portal) Varme i kælderen
description ** Beskrivelse (hvis indtastet på ECL
Portal)
portalGroup ** Gruppe anført i EP til at gruppere ECL
regulatorer
*Denne streng var oprindelig ”hardwareBuild”, men er siden rettet til det korrekte ”softwareBuild” ** Disse data medsendes kun i stamdata, hvis de er udfyldt på ECL Portalen
Desuden vil der for hver device på ECL regulatoren returneres følgende oplysninger om selve devicet.
13A
6400
Andeby
Danmark
Kælderen
Gruppe1
AQ131886471802da-000301
© Danfoss | 2021.01 | 11
Betjeningsguide ECL Portal API
Element Beskrivelse Eksempel
type Angiver typen af device. Mulige udfald er ”EclLogDevice”,
”EclConfigInputDevice” og ”EclMBusDevice”
externalDeviceId Eksternt identifikationsnummer for devicet. Skal f.eks. bruges
for at kunne hente aflæsninger for devicet.
name Navn for devicet. For ECL-log er navnet altid ”EclLog”. For andre
typer er navnet valgfrit på ECL Portalen ved oprettelse.
active Angiver, hvorvidt device er i brug. Mulige værdier er
”false”/”true” Kun én ECL-log device kan være aktiv ad gangen, men der kan oprettes flere EclConfigInputDevices eller EclMBusDevices på samme tid. Den aktive ECL-log svarer til den aktuelt valgte portalapplikation
createdOnPortal Oprettelsestidspunkt for device i ISO 8601 format 2013-04-18T08:53:00.0Z
lastRead Sidste aflæsningstidspunkt i ISO 8601 format 2013-04-18T08:53:00.0Z
logAppName Aktuelt valgt portalapplikation. Der er mange forskellige
muligheder, så de vil ikke blive nævnt her. Mulige værdier er:
configInputType
-0-10V ADC
-Digital
-Flow switch
-Pulse
-Frequency Hvis det er en ukendt type returneres ”7” Kun for EclConfigInputDevices
EclLogDevice
c0f6563e-2bd0-4514­9539-db2c0c700d78
EclLog
True
A376.1 example a
0-10V ADC-Pt 1000
configInputDefinedMaxValue*
configInputDefinedMinValue **
configInputCircuitCloseText
configInputCircuitOpenText
configInputSensorId
mbusAddress
mbusSerialNumber
mbusType *** Kun for EclMBusDevices. Type for M-bus-måleren. Består af
channels
* Denne parameter indikerer, hvilken faktisk værdi som 10 V repræsenterer for 0-10 V ADC input ** Denne parameter indikerer, hvilken faktisk værdi som 0 V repræsenterer for 0-10 V ADC input *** Kendte typer er:
Kun for EclConfigInputDevices af typen 0-10 V ADC
Kun for EclConfigInputDevices af typen 0-10 V ADC
Kun for EclConfigInputDevices af typen ”Digital” eller ”Flow switch” for tilstanden ”close”
Kun for EclConfigInputDevices af typen ”Digital” eller ”Flow switch” for tilstanden ”open”
Kun for EclConfigInputDevices. Indikerer hvilken indgang den konfigurerbare indgang er oprettet på
Kun for EclMBusDevices. Adressen på M-bus-netværket.
Kun for EclMBusDevices. Unikt serienummer for M-bus-måleren
fabrikantkode og typekode
Kanalinformation vises i en senere tabel nedenunder
4
2
Signal OK
No signal
S9
15
06120815
KAM-08-0c
12 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
ABB-02-02 ABB meter ABB-06-02 ABB DBM ABB-07-02 ABB OD ACW-09-04 Actaris meter ACW-0b-04 Actaris meter ACW-0b-0c Actaris meter ACW-0f-04 Actaris meter ACW-14-07 Actaris meter AXI-04-04 Axis SKS3 BHG-05-04 Brunata meter BHG-3d-04 Brunata HGQ BHG-3d-0c Brunata meter BHG-3d-16 Brunata meter DEI-14-02 Deif APM 380 DFS-01-04 Danfoss meter DFS-01-0c Danfoss meter DFS-20-04 Danfoss Sonometer 1100 Heat meter DFS-20-0a Danfoss Sonometer 1100 Cooling meter DFS-25-07 Hydrometer Hydrus DFS-2b-04 Danfoss Sonometer 1000 DFS-2b-0c Danfoss meter DFS-2f-04 Danfoss Sonometer 1100 DFS-41-04 Danfoss Sonometer 500 DFS-43-0c Danfoss M-Cal Compact DFS-50-04 Danfoss Infocal 6 DFS-52-04 Danfoss Infocal 8 EMH-00-02 EMH KIZ HYD-20-04 Danfoss Sonometer 1100 Heat meter HYD-20-0a Danfoss Sonometer 1100 Cooling meter HYD-20-0c Hydrometer meter HYD-2b-04 Danfoss Sonometer 1000 HYD-2f-04 Danfoss Sonometer 1100 HYD-2f-0c Hydrometer meter HYD-50-04 Danfoss Infocal 6 HYD-52-04 Danfoss Infocal 8 HYD-95-02 Hydrometer Hydroport INV-40-07 Sensus HRI b1 ITR-18-04 Itron meter KAM-01-02 Kamstrup meter KAM-01-04 Kamstrup meter KAM-01-0c Kamstrup Multical III KAM-02-04 Kamstrup Multical 401 KAM-07-04 Kamstrup meter KAM-07-0c Kamstrup meter KAM-08-04 Kamstrup meter KAM-08-0c Kamstrup Multical 601 KAM-0b-04 Kamstrup Multical 402 KAM-0b-0c Kamstrup meter KAM-0f-04 Kamstrup meter KAM-0f-0c Kamstrup Multical 801 KAM-0f-16 Kamstrup meter KAM-11-04 Kamstrup meter KAM-11-0c Kamstrup meter KAM-15-04 Kamstrup meter KAM-1b-16 Kamstrup Multical 21 KAM-1c-04 Kamstrup Multical 602 LDR-01-02 Unknown meter LSE-10-04 Landis & Staefa electronic meter LUG-02-04 Landis & Gyr LUG-04-04 Landis & Gyr meter REL-41-07 Relay meter
UNKNOWN Label for unknown M-bus meter type SEN-0e-04 Sensus meter SEN-52-07 Sensus meter SVM-30-0c Svensk Värmemätning SVM meter WZG-03-07 Neumann & Co. Wasserzähler meter
AQ131886471802da-000301
© Danfoss | 2021.01 | 13
Betjeningsguide ECL Portal API
Listen med kendte M-bus-målere vil sandsynligvis blive udvidet i fremtiden, efterhånden som flere kommer til.
Desuden vil der for hver enkelt kanal på devicet returneres følgende oplysninger om selve kanalen.
Element Beskrivelse Eksempel
name * Navn på kanalen. Aktuel volumen
readingValueIndex Hvilken af de op til 16 værdier i en
aflæsning, som tilhører denne kanal. Min = 1 og max = 16. Hvis 4, så er værdi-4 i en aflæsning fra denne kanal.
unit Angiver enheden, værdier måles i.
Afhænger af M-bus-måler typen, så nye målere kan indeholde nye værdier. Mulige værdier er:
-watt
-watt_hour
-kilo_watt
-kilo_watt_hour
-mega_watt
-mega_watt_hour
-giga_watt
-giga_watt_hour
-cubic_metre
-litre
-hour
-kelvin
-degree_celsius
-cubic_metre_per_hour
-cubic_metre_per_minute
-litre_per_hour
-litre_per_minute
-joule
-kilo_joule
-mega_joule
-giga_joule
-day
-bar
-pascal
-hertz
-kilo_hertz
-mega_hertz
-giga_hertz
-count
-unknown
-none
-ph
-pcs
-pci
-calorie
-kilo_calorie
-mega_calorie
-giga_calorie
-metre_per_second
-percentage
-relative_humidity
-default
4
watt_hour
14 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
mbusChannelType Anvendes, for m-bus devices, til at
angive kanalens type. Afhænger af M-bus-måler- typen, så nye målere kan indeholde nye værdier. Mulige værdier er:
-ENERGY
-VOLUME
-MASS
-POWER
-VOLUME_FLOW
-VOLUME_FLOW_EXT
-MASS_FLOW
-FLOW_TEMPERATURE
-RETURN_TEMPERATURE
-TEMPERATURE_DIFFERENCE
-EXTERNAL_TEMPERATURE
-PRESSURE
-DATE_TIME
-ON_TIME
-OPERATING_TIME
-VOLTAGE
-CURRENT
-DATE
-STATUS
-SUBUNIT
-TARIF
VOLUME_FLOW
* ) Navnet afhænger bl.a. af devicetypen, som forklaret herunder
For EclConfigInput devices kan navnet indtastes af ejer/administrator på ECL Portalen For EclLog devices afhænger navnet af sensornummeret Sensor 1 hedder S1, sensor 2 hedder S2 osv. Referenceværdi for sensor 2 hedder RefS2, referenceværdi for sensor 3 hedder RefS3 osv. Derudover logger nogle applikationer visse signaler, som ikke kommer direkte fra sensorerne. Disse signaler navngives efter deres PNU/ID. For eksempel logges i A230.1 PNU’en 11098, som er den beregnede vindstyrke. Den får derfor navnet ”11098”. Det er ikke muligt at navngive alle loggede signaler for alle applikationer, så derfor angives simple navne. For EclMBusDevices bliver kanalen navngivet ud fra, hvad M-bus-måleren fortæller, hvad den er. Navnet afhænger derfor af den specifikke målertype, der er anvendt. Mulige navne er:
-power
-return_temperature
-temperature_difference
-voltage
-volume_flow
-volume
-current
-energy
-flow_temperature
-on_time
-operating_time
-status Listen med mulige navne kan udvides i fremtiden, hvis nye M-bus-målere påkræver det.
AQ131886471802da-000301
© Danfoss | 2021.01 | 15
Betjeningsguide ECL Portal API
Eksempel på ECL-log-devices fra stamdata: ECL-log
{ “type”: “EclLogDevice”, “externalDeviceId”: “eff82977-bf82-40ff-a23c-21a0c9a4065b”, “name”: “EclLog”, “active”: true, “createdOnPortal”: “2011-09-07T08:21:16.318Z”, “logAppName”: “A376.1 example a”, “lastRead”: “2013-10-23T08:45:00.0Z”, “channels”: [{ “name”: “RefS4 (13254)”, “readingValueIndex”: 6, “unit”: “degree_celsius” }, { “name”: “S2 (11202)”, “readingValueIndex”: 2, “unit”: “degree_celsius” }, { “name”: “RefS5 (11255)”, “readingValueIndex”: 8, “unit”: “degree_celsius” }, { “name”: “RefS3 (11253)”, “readingValueIndex”: 4, “unit”: “degree_celsius” }, { “name”: “RefS10 (12260)”, “readingValueIndex”: 11, “unit”: “degree_celsius” }, { “name”: “S9 (10209)”, “readingValueIndex”: 13 }, {
“name”: “S4 (10204)”, “readingValueIndex”: 5 }, { “name”: “S10 (10210)”, “readingValueIndex”: 10 }, { “name”: “RefS9 (12259)”, “readingValueIndex”: 14, “unit”: “degree_celsius” }, { “name”: “S1 (11201)”, “readingValueIndex”: 1, “unit”: “degree_celsius” }, { “name”: “S7 (12207)”, “readingValueIndex”: 12, “unit”: “degree_celsius” }, { “name”: “S6 (10206)”, “readingValueIndex”: 9 }, { “name”: “S5 (10205)”, “readingValueIndex”: 7 }, { “name”: “S3 (10203)”, “readingValueIndex”: 3 }] }
Eksempel på ECL log devices fra stamdata: Konfigurerbart input
{ “type”: “EclConfigInputDevice”, “externalDeviceId”: “c4c3e66a-940f-4943-a058-60577ea6fea5”, “name”: “S7”, “active”: true, “createdOnPortal”: “2012-11-09T06:30:38.109Z”, “lastRead”: “2013-10-23T08:57:00.139Z”, “configInputType”: “Pt 1000”, “configInputSensorId”: “S7”, “channels”: [{ “name”: “S7”, “readingValueIndex”: 1, “unit”: “degree_celsius” }] }
16 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
Eksempel på ECL log devices fra stamdata: M-bus-måler
{ “type”: “EclMBusDevice”, “externalDeviceId”: “eda5c8c6-120f-4a7f-ad80-796939458f49”, “name”: “M68”, “active”: true, “createdOnPortal”: “2013-02-20T10:43:35.694Z”, “lastRead”: “2013-08-28T10:00:00.660Z”, “mbusAddress”: “68”, “mbusSerialNumber”: “41681168”, “mbusType”: “DFS-25-07”, “channels”: [{ “name”: “volume_flow”, “readingValueIndex”: 2, “unit”: “cubic_metre_per_hour”, “mbusChannelType”: “VOLUME_FLOW”, “mbusSubUnit”: 0 }, { “name”: “flow_temperature”, “readingValueIndex”: 3, “unit”: “degree_celsius”, “mbusChannelType”: “FLOW_TEMPERATURE”, “mbusSubUnit”: 0 }, { “name”: “volume”, “readingValueIndex”: 1, “unit”: “cubic_metre”, “mbusChannelType”: “VOLUME”, “mbusSubUnit”: 0 }] }
Da en ECL således kan have flere gamle log devices af alle typer, som ikke længere er aktive, bør ejer/administrator sørge for at slette gamle devices på ECL Portalen, hvis der ikke længere er brug for deres dataindhold.
8.4 Statuskoder for respons
Der vil være fejlhåndtering i henhold til http-standarden, dvs. at svaret vil kunne have én af følgende http status-koder (for alle andre end kode 200 vil svaret ikke indeholde data, men typisk en tekst, som uddyber problemet).
• 200 – Alt gik godt
• 400 – Ugyldig forespørgsel, typisk fordi en parameter mangler
• 401 – Uautoriseret – dvs. at server- eller tredjepartskode ikke er korrekte
• 404 – ECL ikke fundet
• 500 – Anden ukendt fejl
9.0 Aflæsningsservice (Readings)
Her beskrives, hvad aflæsningsservicen kan anvendes til.
Servicen har i denne første version kun én metode. Metoden er getReadings og henter aflæsninger for et device for en given periode. For at optimere dataoverførslen, er resultatet holdt så enkelt som muligt, og man vil typisk skulle kende stamdata for ECL regulatoren for at kunne behandle de modtagne værdier. Nedenstående beskriver det konceptuelle indhold af request og response.
AQ131886471802da-000301
© Danfoss | 2021.01 | 17
Betjeningsguide ECL Portal API
9.1 getReadings Request
Parameter Beskrivelse Eksempel
serverCode Del af identifikation, jf. afsnit 5.3 om
sikkerhed.
eclSerial Del af identifikation, jf. afsnit 5.3 om
sikkerhed.
eclAccessCode Del af identifikation, jf. afsnit 5.3 om
sikkerhed.
externalDeviceId Det eksterne identifikationsnummer
for devicet (se stamdata).
Default = ”*”, hvilket betyder, at man er interesseret i data fra samtlige devices for ECL regulatoren. Dette er kun tilladt, når pageSize = 1, så i alle andre tilfælde skal man identificere et specifikt device.
from * Starttidspunkt (inklusive) i ISO 8601
direction Om man ønsker aflæsninger fra
c0f6563e-2bd0-4514-9539­db2c0c700d78
format for udlæsning fra API. Default værdien er det aktuelle tidspunkt.
starttidspunktet og fremefter (forward) eller bagud (reverse). Bemærk, at sorteringen af aflæsningerne i svaret afhænger af dette valg. Default = ”reverse”.
FirmaA
123456792
Kode5
2013-04-18T08:53:00.0Z
forward
page Angiver hvilken side man vil have. Hvis
f.eks. pageSize er 1000, og man angiver at ville have side 2, så springer man de første 1000 aflæsninger over (typisk fordi man har fået dem i et tidligere request). Default = 1. Min = 1.
pageSize Sidestørrelsen, dvs. antallet af
aflæsninger pr. side. Default = 1. Min = 1. Max = 15.000. Bemærk, at hver aflæsning kan have op til 16 værdier, afhængig af antallet af kanaler for devicet.
clientRequestId Valgfri tekst-ID, som kan bruges
til at implementere sporbarhed i tredjeparts- systemer, der fungerer asynkront, da det medsendes i svaret. Kan udelades, men vil ellers typisk være en autogenereret unik ID.
*Har man i øvrigt foretaget et nyligt udtræk af stamdata, så ved man også, hvornår man sidst har fået data (lastRead fra devicet). Eksempel på request efter seneste aflæsning fra et bestemt device
https://{host}/readings/{version}/{eclSerial}?serverCode={serverCode}&eclAccessCode={eclAccessCode}&externalDeviceId={extern alDeviceId}
1
1000
555b7f4d-7e1a-4d76-a4f0­be8fb52b7c80
https://eclwebapi.danfoss.dk/readings/v1/123456792?serverCode=FirmaA&eclAccessCode=Kode5&externalDeviceId= c0f6563e­2bd0-4514-9539-db2c0c700d78
18 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
Eksempel på request efter seneste aflæsning fra alle devices på en ECL regulator.
https://{host}/readings/{version}/{eclSerial}?serverCode={serverCode}&eclAccessCode={eclAccessCode}
Eksempel på request efter data fra en specifik device fra et givet tidspunkt og bagud i tid.
https://{host}/readings/{version}/{eclSerial}?serverCode={serverCode}&eclAccessCode={eclAccessCode}& externalD eviceId={external DeviceId}&from={from}&pageSize={pageSize}&page=1
Eksempel på request efter data fra en specifik device fra et givet tidspunkt og frem i tid.
https://{host}/readings/{version}/{eclSerial}?serverCode={serverCode}&eclAccessCode={eclAccessCode}&externalDeviceId={extern alDeviceId}&direction=forward&from={from}&pageSize={pageSize}&page=1
Hvis der ikke er data i databasen for det givne tidspunkt, vil API’et levere de næstkommende data i den angivne retning (forward/reverse).
9.2 getReadings Response
Som svar på et reading request returneres et tracking objekt og et data object. Tracking object:
Element Beskrivelse Eksempel
clientRequestId Det valgfri tekst-ID, som blev sendt med under selve requestet for at
muliggøre sporbarhed hos tredjepart.
serverRequestId Serveren tildeler selv hver request et unikt ID, da der ikke er krav
om, at man skal medsende et unikt klient ID på tværs af kunder. Dette ID kan bruges, hvis man er i tvivl om serverens håndtering af et request, da der vil blive logget forskellige statistiske informationer om hvert request (se afsnit 5.4 om sporbarhed).
from Gentagelse af request-parameteren eller default værdi, så man har
styr på udgangspunktet
direction Gentagelse af request-parameteren eller defaultværdi, så man har
styr på retningen
page * Gentagelse af request-parameteren eller defaultværdi, så man har
styr på, hvor langt man har ”bladret”.
pageSize Gentagelse af request-parameteren eller defaultværdi, så man har
styr på sidestørrelsen
resultReadings Antal aflæsninger indeholdt i dette svar (denne side – typisk
pageSize med undtagelse af sidste side).
totalReadings ** Antal aflæsninger, der er tilgængelige totalt set, hvis alle sider
bladres igennem
555b7f4d-7e1a-4d76-a4f0­be8fb52b7c80
9cd4df10-09cc-4ec7-8b4e­c1180b21d9d9
2013-04-18T08:53:00.0Z
forward
1
1000
1000
5642
totalPages ** Antal sider i alt for at udlæse alle aflæsningerne 6
*) For at fortsætte til de næste data vil man således anvende samme request-parametre, men forøge page med én for hver læsning. **) Angives kun i svaret for side 1, for ikke at skulle tælle rækkerne igen for hver side. Angives desuden kun hvis externalDeviceId er forskellig fra * (da der alligevel ikke understøttes paging ved forespørgsel på flere devices samtidig).
AQ131886471802da-000301
© Danfoss | 2021.01 | 19
Betjeningsguide ECL Portal API
Data object
Element Beskrivelse Eksempel
externalDeviceId ID, der bruges til at identificere device. Se stam
data.
readings En samling af readings tilhørende devicet Se næste tabel for indhold
Desuden vil der for hver reading være følgende informationer i svaret.
Element Beskrivelse Eksempel
timestamp ECL regulatorens tidsstempling af aflæsningen. 2013-04-18T08:53:00.0Z
receivedTime Hvornår ECL Portalen har logget aflæsningen. 2013-04-18T08:55:32.9Z
manualEntry Kun for EclConfigInput devices af typen ”Pulse”, til hvilke man kan indtaste
værdier manuelt via ECL Portalen.
value1 Værdi 1. Dvs. værdien målt for kanalen, der har readingValueIndex = 1. 41.82
… 15 øvrige value felter som ovenfor, op til value16 som er den sidste
Der er ingen afhængighed af log-frekvensen. Aflæsningerne vil blot blive listet stigende eller faldende (afhængigt af, hvad man har forespurgt) i kronologisk rækkefølge. Dvs., at der teoretisk set kan ske et skifte i log-frekvensen over en periode. Der vil være fejlhåndtering i henhold til http-standarden, dvs. at svaret vil kunne have en af følgende http status-koder (for alle andre end kode 200 vil svaret ikke indeholde data, men typisk en tekst, som uddyber problemet).
• 200 – Alt gik godt
• 400 – Ugyldig forespørgsel, typisk fordi en parameter mangler eller er formateret forkert
• 401 – Uautoriseret – dvs. at server- eller tredjepartskode ikke er korrekte
• 404 – ECL eller device ikke fundet
• 500 – Anden ukendt fejl
c0f6563e-2bd0-4514-9539-db2c0c700d78
False
Eksempel på en reading response
{ “tracking”: { “clientRequestId”: “555b7f4d-7e1a-4d76-a4f0-be8fb52b7c80”, “serverRequestId”: “9cd4df10-09cc-4ec7-8b4e-c1180b21d9d9”, “from”: “2013-04-18T08: 53: 00.0Z”, “direction”: “forward”, “page”: 1, “pageSize”: 1000, “resultReadings”: 1000, “totalReadings”: 5642, “totalPages”: 6 }, “data”: [{ “externalDeviceId”: “c0f6563e-2bd0-4514-9539-db2c0c700d78”, “readings”: [{ “timestamp”: “2013-04-18T08: 53: 00.0Z”, “receivedTime”: “2013-04-18T08: 55: 32.9Z”, “manualEntry”: false, “value1”: 41.82, “value2”: 0.00000042, “value3”: 32800000, “value4”: 12 }, …flere reading fra samme device her…] }, …data fra andre devices her…] }
20 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
10.0 Brug af snitfladen
Her beskrives/eksemplificeres forskellige scenarier for anvendelse af API’et.
API’et kan anvendes til at forespørge data mod en vilkårlig ECL regulator. De konkrete scenarier, som beskrives senere i dette bilag, tager udgangspunkt i følgende setup:
Der er tale om en A367.1 example e, hvortil der er tilknyttet 3 M-bus-baserede varmemålere samt én puls-baseret vandmåler. På ECL Portalen fremstår ECL regulatoren med følgende log-enheder (i web-API-termer kaldet devices) under ECL > Log:
AQ131886471802da-000301
© Danfoss | 2021.01 | 21
Betjeningsguide ECL Portal API
Her findes to ECL-logenheder, fordi der først er blevet skiftet portalapplikation fra eksempel a til eksempel e, da ejeren syntes, at det passede bedre til det aktuelle anlæg. Kun det ene ECL-log er aktivt (True), og det andet indeholder kun gamle data. Alle log-enheder kan udlæses gennem web-api’et. For at udlæse en specifik log-enhed skal man bruge det korrekte externalDeviceId, som kan findes ved at udlæse stamdata, hvor det også angives, hvilke log-enheder der er aktive.
Hver log-enhed/device har et antal kanaler, som der logges værdier for. På portalen kan disse bedst ses som en liste under Graf > Brugerdefineret graf > Opret ny graf, og herunder ses listen, som den tager sig ud for vores eksempel ECL:
22 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
10.1 Udtræk af stamdata
Inden man udtrækker aflæsninger for en ECL regulator, vil det være relevant at hente nyeste stamdata. At hente stamdata for ovenstående ECL regulator sker ved at foretage ét enkelt kald til web-API’et. Det kan ske som en forespørgsel mod REST endpointet, og svaret vil være i JSON format.
AQ131886471802da-000301
© Danfoss | 2021.01 | 23
Betjeningsguide ECL Portal API
Retur kommer, som tidligere nævnt, stamdata for selve ECL regulatoren samt hver af de tilknyttede devices/log-enheder (i dette tilfælde 6 enheder, da der også returneres stamdata for inaktive devices).
Som beskrevet i afsnit 7.1 medsendes serverkode, ECL serienummer, tredjepartskode samt eventuelt et clientRequestId som parametre i forespørgslen. Herunder beskrives, hvilke informationer der er indeholdt i svaret fra web-API’et. Informationer, som omfatter det, man kan se i portalen (jf. screenshots tidligere i dette bilag) samt yderligere detaljer.
Forespørgsel:
https://eclwebapi.danfoss.dk/masterdata/v1/123456792?serverCode=FirmaA&eclAccessCode=Kode5
Af sporbarhedsmæssige årsager kommer følgende request-ID-oplysninger retur i svaret fra serveren. Disse relaterer sig ikke til stamdata registreret i portalen, men alene til den konkrete stamdata-forespørgsel og vil derfor ændre sig for hver forespørgsel.
Element Værdi
clientRequestId 555b7f4d-7e1a-4d76-a4f0-be8fb52b7c80
serverRequestId 9cd4df10-09cc-4ec7-8b4e-c1180b21d9d9
Følgende grundlæggende stamdata kommer retur for selve ECL regulatoren.
Element Eksempel
application A367.1
applicationVersion 1.00
hardwareModel ECL 296 / 310, 230 V
hardwareVersion B
softwareBuild 6884
hardwareProductionTime 51.2010
firmwareVersion 1.46
serialNumber (anonymiseret)
externalEclId cb829044-b117-4ac7-b265-7b4b23e6338c
createdOnPortal 2011-04-18T12:55:32.9Z
timezone Europe/Copenhagen
locationStreet (anonymiseret)
locationStreetNumber 8
locationZip 6400
locationCity Sønderborg
locationCountry Danmark
name (anonymiseret)
Description og portalGroup er ikke udfyldt for denne ECL regulator, så de kommer ikke med. Desuden vil der for hver device/log-enhed på ECL regulatoren returneres en række oplysninger om selve devicet og underliggende kanaler.
24 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
10.1.1 M-Bus, Hoved måler hus
Element Eksempel
type MBusDevice
externalDeviceId 8dbb8b99-96a4-498c-b75b-c7453e1ad6c1
name Hoved måler hus
active true
createdOnPortal 2012-10-22T09:28:07.0Z
lastRead 2013-04-29T09:05:00.0Z
mbusAddress 61
mbusSerialNumber 38925461
mbusType Danfoss Sonometer 1100
AQ131886471802da-000301
© Danfoss | 2021.01 | 25
Betjeningsguide ECL Portal API
Følgende information returneres omkring de 4 kanaler
Element Eksempel
name Energi
readingValueIndex 1
unit Wh
unitKey watt_hour
mbusChannelType ENERGY
Element Eksempel
name Volumen
readingValueIndex 2
unit m³
unitKey cubic_metre
mbusChannelType VOLUME
Element Eksempel
name Returløbstemperatur
readingValueIndex 4
unit °C
unitKey degree_celsius
mbusChannelType RETURN_TEMPERATURE
Element Eksempel
name Fremløbstemperatur
readingValueIndex 3
unit °C
unitKey degree_celsius
mbusChannelType FLOW_TEMPERATURE
10.1.2 M-Bus, Solvarme lille tank
Element Eksempel
type MBusDevice
externalDeviceId c76c6a87-270c-4123-be57-d39f8f551f43
name Solvarme lille tank
active true
26 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
Element Eksempel
createdOnPortal 2012-10-19T13:54:30.0Z
lastRead 2013-04-29T09:05:00.0Z
mbusAddress 2
mbusSerialNumber 34326094
mbusType Danfoss Sonometer 1000
Følgende information returneres vedr. de 6 kanaler:
Element Eksempel
name Energi
readingValueIndex 1
unit Wh
unitKey watt_hours
mbusChannelType ENERGY
Element Eksempel
name Volumen
readingValueIndex 2
unit m³
unitKey cubic_metre
mbusChannelType VOLUME
Element Eksempel
name Fremløbstemperatur
readingValueIndex 5
unit °C
unitKey degree_celsius
mbusChannelType FLOW_TEMPERATURE
Element Eksempel
name Aktuel volumen
readingValueIndex 4
unit m³/h
unitKey cubic_metre_per_hour
mbusChannelType VOLUME_FLOW
AQ131886471802da-000301
© Danfoss | 2021.01 | 27
Betjeningsguide ECL Portal API
Element Eksempel
name Aktuel effekt
readingValueIndex 3
unit W
unitKey watt
mbusChannelType POWER
Element Eksempel
name Returløbstemperatur
readingValueIndex 6
unit °C
unitKey degree_celsius
mbusChannelType RETURN_TEMPERATURE
10.1.3 M-Bus, Solvarme stor tank
Element Eksempel
type MBusDevice
externalDeviceId 64365d4b-b991-4512-b3ea-456ee6c83b33
name Solvarme stor tank
active true
createdOnPortal 2012-10-19T13:53:30.0Z
lastRead 2013-04-29T09:05:00.0Z
mbusAddress 1
mbusSerialNumber 34326095
mbusType Danfoss Sonometer 1000
Følgende information returneres vedr. de 6 kanaler:
Element Eksempel
name Volumen
readingValueIndex 2
unit m³
unitKey cubic_metre
mbusChannelType VOLUME
28 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
Element Eksempel
name Aktuel effekt
readingValueIndex 3
unit W
unitKey watt
mbusChannelType POWER
Element Eksempel
name Returløbstemperatur
readingValueIndex 6
unit °C
unitKey degree_celsius
mbusChannelType RETURN_TEMPERATURE
Element Eksempel
name Energi
readingValueIndex 1
unit Wh
unitKey watt_hours
mbusChannelType ENERGY
Element Eksempel
name Aktuel volumen
readingValueIndex 4
unit m³/h
unitKey cubic_metre_per_hour
mbusChannelType VOLUME_FLOW
Element Eksempel
name Fremløbstemperatur
readingValueIndex 5
unit °C
unitKey degree_celsius
mbusChannelType FLOW_TEMPERATURE
AQ131886471802da-000301
© Danfoss | 2021.01 | 29
Betjeningsguide ECL Portal API
10.1.4 ECL-log, A367.1 eksempel e
Element Eksempel
type EclLogDevice
externalDeviceId 2cc34b74-2c42-4ad1-a6c4-f27876b1c799
name EclLog
active true
createdOnPortal 2011-12-13T07:07:29.0Z
lastRead 2013-04-29T09:00:00.0Z
logAppName A367.1 eksempel e
Følgende information returneres vedr. de 14 kanaler:
Element Eksempel
name Kr 2, returtemperatur
readingValueIndex 10
unit °C
unitKey degree_celsius
Element Eksempel
name Kr 3, tanktemperatur øvre
readingValueIndex 7
unit °C
unitKey degree_celsius
Element Eksempel
name Kr 2, returtemperaturref.
readingValueIndex 11
unit °C
unitKey degree_celsius
Element Eksempel
name Kr 1, Rumtemperatur
readingValueIndex 2
unit °C
unitKey degree_celsius
30 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
Element Eksempel
name Kr 2, fremløbstemperaturref.
readingValueIndex 13
unit °C
unitKey degree_celsius
name Kr 1, fremløbstemperatur
readingValueIndex 3
unit °C
unitKey degree_celsius
name Udetemperatur
readingValueIndex 1
unit °C
unitKey degree_celsius
name Kr 2, fremløbstemperatur
readingValueIndex 12
unit °C
unitKey degree_celsius
name Kr 3, tanktemperatur øvre ref.
readingValueIndex 8
unit °C
unitKey degree_celsius
name Kr 3, tanktemperatur nedre
readingValueIndex 9
unit °C
name Kr 2, Rumtemperatur
readingValueIndex 14
unit °C
unitKey degree_celsius
AQ131886471802da-000301
© Danfoss | 2021.01 | 31
Betjeningsguide ECL Portal API
Element Eksempel
name Kr 1, fremløbstemperaturref.
readingValueIndex 4
unit °C
unitKey degree_celsius
Element Eksempel
name Kr 1, forsyning, returtemperaturref.
readingValueIndex 6
unit °C
unitKey degree_celsius
Element Eksempel
name Kr 1, forsyning, returtemperatur
readingValueIndex 5
unit °C
unitKey degree_celsius
ECL konfigurerbart input, Vand hoved måler
Element Eksempel
type EclConfigInputDevice
externalDeviceId 77df9535-9333-4222-b0a5-b5d6d08da1b3
name Vand hoved måler
active true
createdOnPortal 2013-03-22T06:59:33.0Z
lastRead 2013-04-29T09:06:00.0Z
configInputType Pulse
configInputSensorId S17
Element Eksempel
name Vand hoved måler
readingValueIndex 1
unit m³
unitKey cubic_metre
configSensorId S17
32 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
10.1.5 Udtræk af aflæsninger (readings)
I dette afsnit beskrives brugen af web-API’et for at udtrække aflæsninger.
For at kunne udtrække aflæsninger for en given periode (modsat f.eks. blot seneste aflæsning) forudsætter det, at man kender devicets eksterne ID (som fremgår af stamdataene), og under alle omstændigheder har man behov for at vide, hvilke værdier i en aflæsning, der udgør hvad (hvilken kanal), og hvad enhed den måles i (fremgår ligeledes af stamdata).
Der er således behov for at kende stamdata af den ene eller den anden grund. Om man henter stamdata for en ECL regulator umiddelbart forud for, at der hentes data for den, eller om man anvender cachede stamdata, beror på brugsscenariet i tredjepartsapplikationen. Der vil dog være behov for at hente ajourførte stamdata med mellemrum, da kunden kan foretage ændringer i opsætningen uden at informere tredjepart. Hvis der skal forespørges aflæsninger over flere sider, er det dog ikke nødvendigt at forespørge stamdata for hver side. De følgende scenarier antager, at man har stamdata tilgængelige for ECL regulatoren, på den ene eller den anden måde, forud for hentning af aflæsningsdata.
10.1.6 Udlæs seneste værdier for en eller flere sensorer på en måler tilsluttet ECL regulatoren
At hente seneste aflæsning (som indeholder en værdi for hver sensor/kanal) for en måler/device tilsluttet ECL regulatoren sker ved at foretage ét enkelt kald til web-API’et. Det kan ske med en forespørgsel mod REST-endpointet, og svaret vil være i JSON-format.
Mange af inputparameterene er som udgangspunkt lagt an på udlæsning af seneste værdi, hvorfor man kun behøver at angive få parametre i kaldet. Ud over identifikationsparameterene (serverkode, ECL serienummer og tredjepartskode) behøves alene målerens/ devicets eksterne ID (externalDeviceId) fra stamdataene at blive angivet i kaldet.
AQ131886471802da-000301
© Danfoss | 2021.01 | 33
Betjeningsguide ECL Portal API
10.1.7 Udlæsning af senest målte udendørstemperatur
Udetemperaturen er målt via ECL-loggen, som har externalDeviceId = 2cc34b74-2c42-4ad1-a6c4-f27876b1c799, jf. stamdataene, hvorfor denne værdi sendes med i forespørgslen.
Forespørgsel:
https://eclwebapi.danfoss.dk/readings/v1/123456792?serverCode=FirmaA&eclAccessCode=Kode5&externalDeviceId=2cc34b74­2c42-4ad1-a6c4-f27876b1c799
Retur kommer følgende grunddata:
direction backward
page 1
pageSize 1
resultReadings 1
Desuden kommer følgende aflæsning retur i samme svarmeddelelse:
Element Eksempel
timestamp 2013-04-29T09:00:00.0Z
receivedTime 2013-04-18T09:08:31.0Z
manualEntry False
value1 9.84
value2 192
value3 63.95
value4 65
value5 39.14
value6 65
value7 44.98
value8 50
value9 54
value10 28.48
value11 27.16
value12 32.61
value13 31.53
value14 192
Fordi stamdataene definerer, at det pågældende device har 14 kanaler, vil hver reading for dette device have 14 værdier. Af stamdata kan det desuden ses, at Udetemperatur har readingValueIndex = 1, samt at enheden er °C, dvs. at værdien i °C skal findes som value1 (de øvrige er i dette tilfælde uinteressante), hvilket i dette tilfælde er 9.84.
34 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
10.1.8 Udlæsning af Energi, Volumen, Flow-temperatur og Retur-temperatur for husets hovedmåler
Hovedmåleren for huset er M-bus devicet med externalDeviceId = 8dbb8b99-96a4-498c-b75b-c7453e1ad6c1. Forespørgslen foregår således på samme måde som ovenstående, blot med et andet ID på devicet:
Forespørgsel:
https://eclwebapi.danfoss.dk/readings/v1/123456792?serverCode=FirmaA&eclAccessCode=Kode5&externalDeviceId=8dbb8b99­96a4-498c-b75b-c7453e1ad6c1
Retur kommer følgende grunddata:
Element Eksempel
timestamp 2013-04-29T09:05:00.0Z
receivedTime 2013-04-18T09:08:35.0Z
manualEntry False
value1 1.9378E7
value2 1546.838
value3 61.3
value4 42.4
Det man har udtrykt interesse for her er samtlige 4 værdier, og i henhold til stamdataene er der således kl. 9:05 aflæst:
• Energi (readingValueIndex1): 1.9378E7 Wh
• Volumen (readingValueIndex2): 1546.838 m³
• Fremløbstemperatur (readingValueIndex3): 61.3 °C
• Returløbstemperatur (readingValueIndex4): 42.4 °C
10.1.9 Udlæs seneste værdi for en eller flere sensorer på tværs af målere tilsluttet ECL regulatoren
Udlæsning af seneste værdi på tværs af målere/devices foregår efter præcist det samme princip som for et enkelt device. Forskellen i forespørgslen er, at man angiver * i stedet for et specifikt externalDeviceId. Der er stadig kun tale om en forespørgsel og et svar fra serveren. Forskellen i svarmeddelelsen er, at man så vil modtage ikke blot én aflæsning, men i stedet én aflæsning pr. device, hvilket i vores eksempel vil sige 6 aflæsninger (3 x M-bus, 2 x ECL-log og 1 konfigurerbart input) i samme meddelelse.
Forespørgsel:
https://eclwebapi.danfoss.dk/readings/v1/123456792?serverCode=FirmaA&eclAccessCode=Kode5&externalDeviceId=*
10.1.10 Udlæs en periode af historiske data for en eller flere sensorer på én måler tilsluttet ECL regulatoren
Ganske som ved udlæsning af seneste aflæsning vil aflæsningerne i dette tilfælde også indeholde værdier for samtlige kanaler/sensorer på måleren, såfremt flere kanaler er tilgængelige. Men ved udlæsning af data for en given periode, vil man ikke kunne forespørge på tværs af devices på ECL regulatoren, men altid kun én log-enhed ad gangen. Det er den samme metode, man kalder, blot med flere argumenter, og man kan komme ud for at skulle kalde metoden flere gange for at ”dække” den ønskede periode (afhængig af sidestørrelse, log-frekvens og periodens længde).
AQ131886471802da-000301
© Danfoss | 2021.01 | 35
Betjeningsguide ECL Portal API
Vi tager udgangspunkt i, at man vil hente alle data for vand-hovedmåleren. Det er, jf. stamdataene, et konfigurerbart input modul (af typen puls med externalDeviceId = 77df9535-9333-4222-b0a5-b5d6d08da1b3), som alene har 1 kanal, hvor det målte er pulser omsat til m3. Vi kan ligeledes af stamdataene se, at nyeste data er fra 2013-04-29T09:06:00.0Z, og at den først blev kendt af portalen 2013-03-22T06:59:33.0Z. I dette eksempel antager vi, at en sidestørrelse på 500 egner sig bedst til tredjepartsklienten.
Forespørgsel:
https://eclwebapi.danfoss.dk/readings/v1/123456792?serverCode=FirmaA&eclAccessCode=Kode5&externalDeviceId=77df9535-9333­4222-b0a5-b5d6d08da1b3&direction=forward&from=2013-03-22T00:00:00.0Z&pageSize=500&page=1
Vi forespørger indledningsvist data som følger:
Parameter Eksempel
serverCode CompanyA
eclSerial 123456792
eclAccessCode Code5
externalDeviceId 77df9535-9333-4222-b0a5-b5d6d08da1b3
from * 2013-03-22T00:00:00.0Z
direction forward
page 1
pageSize 500
clientRequestId 355b7f4d-7e1a-4d76-a4f0-be8fb52b7c80
36 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
Retur kommer følgende grunddata:
Element Eksempel
clientRequestId 355b7f4d-7e1a-4d76-a4f0-be8fb52b7c80
serverRequestId 9cd4df10-09cc-4ec7-8b4e-c1180b21d9f9
from 2013-03-22T00:00:00.0Z
direction forward
page 1
pageSize 500
resultReadings 500
totalReadings 915
totalPages 2
Desuden kommer følgende aflæsninger retur i samme svarmeddelelse:
Element Eksempel
timestamp 2013-03-22T07:06:00.0Z
receivedTime 2013-03-22T07:08:24.0Z
manualEntry False
value1 0
… 498 øvrige aflæsninger…
Element Eksempel
timestamp 2013-04-12T02:08:00.0Z
receivedTime 2013-04-12T02:10:12.0Z
manualEntry False
value1 10.05
Vi forespørger herefter endnu en side med data, da det i første svar blev indikeret, at der var 2 sider data tilgængelige:
Forespørgsel:
https://eclwebapi.danfoss.dk/readings/v1/123456792?serverCode=FirmaA&eclAccessCode=Kode5&externalDeviceId=77df9535­9333-4222-b0a5-b5d6d08da1b3&direction=forward&from=2013-03-22T00:00:00.0Z&pageSize=500&page=2
AQ131886471802da-000301
© Danfoss | 2021.01 | 37
Betjeningsguide ECL Portal API
Parameter Eksempel
serverCode FirmaA
eclSerial 123456792
eclAccessCode Kode5
externalDeviceId 77df9535-9333-4222-b0a5-b5d6d08da1b3
from * 2013-03-22T00:00:00.0Z
direction forward
page 2
pageSize 500
clientRequestId 855b7f4d-7e1a-4d76-a4f0-be8fb52b7c80
Retur kommer følgende grunddata:
Element Eksempel
clientRequestId 855b7f4d-7e1a-4d76-a4f0-be8fb52b7c80
serverRequestId 1bd4df10-09cc-4ec7-8b4e-c1180b21d9f9
from 2013-03-22T00:00:00.0Z
direction forward
page 2
pageSize 500
resultReadings 415
Desuden kommer følgende aflæsninger retur i denne anden svarmeddelelse sammen med ovenstående grunddata:
Element Eksempel
timestamp 2013-04-12T03:08:00.0Z
receivedTime 2013-04-12T03:10:31.0Z
manualEntry False
value1 10.05
… 413 øvrige aflæsninger…
Element Eksempel
timestamp 2013-04-29T09:06:00.0Z
receivedTime 2013-04-29T09:08:35.0Z
manualEntry False
value1 15.32
38 | © Danfoss| 2021.01
AQ131886471802da-000301
Betjeningsguide ECL Portal API
10.2 Formatforskelle på dataudtræk
Data udtrukket gennem ECL portalen og downloadet i for eksempel Excel format vil være skaleret til kun at have én decimal, men data udtrukket gennem ECL Portal API’et kan indeholde flere decimaler afhængig af de rådata, der ligger i databasen.
Eksempel på data downloadet via ECL Portalen:
Samme data downloadet via web-API’et:
Bemærk også, at headeren på data er forskellig, jævnfør afsnit 7.2.2 Stamdata.
AQ131886471802da-000301
© Danfoss | 2021.01 | 39
Betjeningsguide ECL Portal API
Bortskaffelsesanvisning
Dette symbol på produktet angiver, at det ikke må bortskaffes som husholdningsaffald. Det skal afleveres til den gældende indsamlingsordning for genbrug af elektrisk og elektronisk udstyr.
• Bortskaf produktet gennem de dertil beregnede kanaler.
• Overhold alle lokale og aktuelt gældende love og bestemmelser.
40 | © Danfoss | DHS-SMDT/DK | 2021.01
*087H9220*
AQ131886471802da-000301
Loading...
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use