Installationsguide. ECL Portal API Web interface til ECL Portal database. 1.0 Indholdsfortegnelse

Transkript

1 Web interface til ECL Portal database 1.0 Indholdsfortegnelse 1.0 Indholdsfortegnelse Introduktion Versionstabel Begrebsoversigt Generelt Sikkerhed Oprettelse af tredjepartskode Tildeling af adgang til tredjepart Snitflader API-format Fremtidige versioner Tidsformater Stamdata service (Master Data) geteclmasterdata request parametre geteclmasterdata request parametre eksempel geteclmasterdata response geteclmasterdata response eksempel Stamdata Statuskoder for respons Aflæsningsservice (Readings) getreadings Request getreadings Response Brug af snitfladen Udtræk af stamdata M-Bus, Hoved måler hus M-Bus, Solvarme lille tank M-Bus, Solvarme stor tank ECL-log, A367.1 eksempel e Udtræk af aflæsninger (readings) Udlæs seneste værdier for en eller flere sensorer på en måler tilsluttet ECL regulatoren Udlæsning af senest målte udendørstemperatur Udlæsning af Energi, Volumen, Flow-temperatur og Retur-temperatur for husets hovedmåler Udlæs seneste værdi for en eller flere sensorer på tværs af målere tilsluttet ECL regulatoren Udlæs en periode af historiske data for en eller flere sensorer på én måler tilsluttet ECL regulatoren Formatforskelle på dataudtræk Danfoss District Energy VI.HX.I1.01 DEN-SMT/DK 1

2 1.0 Introduktion Dette dokument er en beskrivelse til tredjepart, til brug ved implementering af softwareklienter til udtræk af data fra ECL Comfort 310 Portal (ECL Portal). 2.0 Versionstabel Version Dato Ændring Første version Tilføjet afsnit om oprettelse af tredjepartskode, fremtidige version, tidsformater. Tilføjet JSON eksempler for forespørgsler og svar Tilføjet eksempel om forskel på dataudtræk fra ECL Portal og ECL Portal-API. Tilføjet eksempel om tidsformat i aflæsninger Tilføjet nogle få uddybende forklaringer og eksempler. 3.0 Begrebsoversigt API Device ECL Comfort 310 HTTPS Konfigurerbar indgang Kunde JSON M-bus Paging Reading Request Response REST Serverkode SSL Stamdata Tredjepartskode URL UTC Web-API tredjepart Application Programming Interface. Et interface for udvekling af applicationsspecifik information. En enhed. Typisk brugt i forbindelse med en log-enhed. En fjernvarmeregulatormodel fra Danfoss A/S. HyperText Transfer Protocol. En krypteret protokol til overførsel af information. Nogle sensorindgange på en ECL Comfort 310 regulator kan valgfrit konfigureres til at måle temperatur, puls, frekvens, 0-10 V analog signal eller digital ON/OFF En person, virksomhed eller kommune som vil have udlæst data fra ECL Portalen JavaScript Object Notation. Et åbent data format til udveksling af data mellem en server og et internetprogram. En kommunikationsprotokol typisk anvendt af varme- og energimålere Sideinddeling. For at undgå at overføre alt for mange information på én gang inddeles en datamænge i flere sider, hvor kun én side læses af gangen. En aflæsning. Log-data udlæst fra web-api et fra en log-enhed En forespørgsel til web-api et Svar fra web-api serveren på en forespørgsel Representational State Transfer. En software arkitektur stil, der kan bruges til konstruktion af internettjenester En unik kode udstedt af Danfoss til tredjepart Secure Sockets Layer. En kryptering til sikker udveksling af information, der bl.a. anvendes på internettet (HTTPS) Grundlæggende data for en ECL Comfort 310 regulator En kode oprettet af kunden på ECL Portalen, som kunden udleverer til tredjepart Unifor Resource Locator. En internetadresse Coordinated Universal Time. En standard for tidskoordinering med udgangspunkt i Greenwich, London. Tidszoner angives i forhold til UTC. Et API tilpasset internettet. 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 DEN-SMT/DK VI.HX.I1.01 Danfoss District Energy

3 4.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 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å 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: 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. 5.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. Danfoss District Energy VI.HX.I1.01 DEN-SMT/DK 3

4 5.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 tildeles 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 DEN-SMT/DK VI.HX.I1.01 Danfoss District Energy

5 5.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 regulatoren 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 sideombrydning 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. på tilgængelige devices og kanaler i en ECL Comfort 310 regulator med en given applikation, der har tilsluttet to varmemålere via m-bus: Danfoss District Energy VI.HX.I1.01 DEN-SMT/DK 5

6 6.0 Snitflader Device type Kanaler Beskrivelse EclLogDevice S1 Disse kanaler tilhører sensorer og referenceværdier, der bruges af S2 applikationen 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 310 EclConfigInputDevice S12 Denne indgang benyttes ikke af applikationen og kan derfor anvendes som konfigurerbar indgang. Kræver ECA 32 modul i ECL Comfort 310 EclConfigInputDevice S13 Denne indgang benyttes ikke af applikationen og kan derfor anvendes som konfigurerbar indgang. Kræver ECA 32 modul i ECL Comfort 310 EclMBusDevice volume_flow Disse kanaler er tilgængelige i den pågældende varmemåler, der er tilsluttet flow_temperature via m-bus volume EclMBusDevice volume_flow Disse kanaler er tilgængelige i den pågældende varmemåler, der er tilsluttet flow_temperature via m-bus volume energy return_temperature 6 DEN-SMT/DK VI.HX.I1.01 Danfoss District Energy

7 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. 6.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. 6.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ørgslerne. Versionsindikatoren skal angives på formen: 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å forsiden 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. 6.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: T08:53:00.0Z I responsbeskeder vil tidsstempler altid være i UTC og tredjepartssoftware kan derefter omregne til andre tidszoner efter behov. I stamdata 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 T10:53: :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 misvisende. Aflæsningseksempel for ECL-log udlæst fra ECL Portal-API kl. 09:40 dansk normaltid Danfoss District Energy VI.HX.I1.01 DEN-SMT/DK 7

8 tracking : serverrequestid : 0af3a240-0a36-45ae-b8af-9e24f52103eb, from : T09:40: :00, direction : reverse, page : 1, pagesize : 1000, resultreadings : 1000, totalreadings : 69346, totalpages : 70 data : [ externaldeviceid : cfbd9943-9e49-4d19-a de7041e8, readings : [ id : , timestamp : T07:45:00.0Z, receivedtime : T08: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 : , timestamp : T07:30:00.0Z, receivedtime : T08: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 datakommunikationen, 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 kl. 12:05 dansk sommertid. Her er tiden i ECL regulatoren indstillet forkert, og der er valgt en forkert tidszone (UTC+02:00 i stedet for UTC+01:00) på ECL Portalen. 8 DEN-SMT/DK VI.HX.I1.01 Danfoss District Energy

9 } tracking : serverrequestid : 07c49346-aa90-4e45-9f d5887e, from : T12:05: :00, direction : reverse, page : 1, pagesize : 1, resultreadings : 14 data : [ externaldeviceid : 5a84dbcc-a9c0-474f-9c12-5db4884fc6ed, readings : [ id : , timestamp : T02:15:00.0Z, receivedtime : T10:00:52.293Z, manualentry : false, value1 : -1.25, value2 : -9.46, value3 : 26.17, value4 : 26.66, value5 : , 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 :15:00, men i dataene fra web-api et var tiden :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. 7.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. Nedenstående beskriver det konceptuelle indhold af request og response. 7.1 geteclmasterdata request parametre Parameter Beskrivelse servercode Del af identifikation jf. afsnit 5 omkring sikkerhed. FirmaA eclserial Del af identifikation jf. afsnit 5 omkring sikkerhed 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. 555b7f4d-7e1a-4d76-a4f0- be8fb52b7c80 Danfoss District Energy VI.HX.I1.01 DEN-SMT/DK 9

10 7.1.1 geteclmasterdata request parametre eksempel med version=v1, servercode=firmaa, eclserial= , eclaccesscode= Kode geteclmasterdata response Af sporbarhedsmæssige årsager kommer følgende oplysninger retur i svaret fra serveren. Beskrivelse clientrequestid serverrequestid Det ID, som blev sendt med under selve requestet for at muliggøre sporbarhed hos tredjepart. 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). 555b7f4d-7e1a-4d76-a4f0- be8fb52b7c80 9cd4df10-09cc-4ec7-8b4ec1180b21d9d 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 310, 230 V, hardwareversion : A, softwarebuild : 7232, hardwareproductiontime : , firmwareversion : 1.48, serialnumber : , createdonportal : T08:16:53.543Z, timezone : Europe/Copenhagen, location : street : Solitudevej, streetnumber : 13A, city : Andeby : ECL, portalgroup : Test ECL regulatorer, devices : [ List of log devices has been moved in this example] } } 10 DEN-SMT/DK VI.HX.I1.01 Danfoss District Energy

11 7.2.2 Stamdata Følgende grundlæggende stamdata kommer ligeledes retur med responset for selve ECL regulatoren. Beskrivelse application Hvilken applikation ECL regulatoren kører A376.1 applicationversion Version af applikationen 4.00 hardwaremodel Hardware modelnummer ECL 310, 230 V hardwareversion Hardware version A softwarebuild * Software build nummer 7232 hardwareproductiontime Hardware produktionstidspunkt firmwareversion Firmware versionsnummer 1.48 serialnumber Serienummer createdonportal timezone location:street ** location:streetnumber ** location:zip ** location:city ** location:country ** Dato for hvornår ECL regulatoren blev oprettet på (først forbundet til) portalen Tidszone ECL regulatoren er placeret i (valgt på ECL Portal) Gade ECL regulatoren er placeret på (hvis indtastet på ECL Portal) Husnummer ECL regulatoren er placeret på (hvis indtastet på ECL Portal) Postnummer ECL regulatoren er placeret i (hvis indtastet på ECL Portal) By ECL regulatoren er placeret i (hvis indtastet på ECL Portal) Land ECL regulatoren er placeret i (hvis indtastet på ECL Portal) T08:53:00.0Z Europe/Copenhagen Solitudevej 13A 6400 Andeby Danmark Navn (indtastet på ECL Portal) Varme i kælderen description ** portalgroup ** Beskrivelse (hvis indtastet på ECL Portal) Gruppe anført i EP til at gruppere ECL regulatorer Kælderen Gruppe1 *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. Danfoss District Energy VI.HX.I1.01 DEN-SMT/DK 11

12 Beskrivelse type externaldeviceid active Angiver typen af device. Mulige udfald er EclLogDevice, EclConfigInputDevice og EclMBusDevice Eksternt identifikationsnummer for devicet. Skal f.eks. bruges for at kunne hente aflæsninger for devicet. Navn for devicet. For ECL-log er navnet altid EclLog. For andre typer er navnet valgfrit på ECL Portalen ved oprettelse. 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 EclLogDevice c0f6563e-2bd db2c0c700d78 EclLog True createdonportal Oprettelsestidspunkt for device i ISO 8601 format T08:53:00.0Z lastread Sidste aflæsningstidspunkt i ISO 8601 format T08:53:00.0Z logappname Aktuelt valgt portalapplikation. Der er mange forskellige muligheder, så de vil ikke blive nævnt her. A376.1 example a configinputtype Mulige værdier er: 0-10V ADC -Pt V ADC -Digital -Flow switch -Pulse -Frequency Hvis det er en ukendt type returneres 7 Kun for EclConfigInputDevices configinputdefinedmaxvalue* Kun for EclConfigInputDevices af typen 0-10 V ADC 4 configinputdefinedminvalue ** Kun for EclConfigInputDevices af typen 0-10 V ADC 2 configinputcircuitclosetext configinputcircuitopentext configinputsensorid 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å Signal OK No signal S9 mbusaddress Kun for EclMBusDevices. Adressen på M-bus-netværket. 15 mbusserialnumber Kun for EclMBusDevices. Unikt serienummer for M-bus-måleren mbustype *** channels Kun for EclMBusDevices. Type for M-bus-måleren. Består af fabrikantkode og typekode Kanalinformation vises i en senere tabel nedenunder KAM-08-0c * 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: 12 DEN-SMT/DK VI.HX.I1.01 Danfoss District Energy

13 ABB ABB meter ABB ABB DBM ABB ABB OD ACW Actaris meter ACW-0b-04 Actaris meter ACW-0b-0c Actaris meter ACW-0f-04 Actaris meter ACW Actaris meter AXI Axis SKS3 BHG Brunata meter BHG-3d-04 Brunata HGQ BHG-3d-0c Brunata meter BHG-3d-16 Brunata meter DEI Deif APM 380 DFS Danfoss meter DFS-01-0c Danfoss meter DFS Danfoss Sonometer 1100 Heat meter DFS-20-0a Danfoss Sonometer 1100 Cooling meter DFS Hydrometer Hydrus DFS-2b-04 Danfoss Sonometer 1000 DFS-2b-0c Danfoss meter DFS-2f-04 Danfoss Sonometer 1100 DFS Danfoss Sonometer 500 DFS-43-0c Danfoss M-Cal Compact DFS Danfoss Infocal 6 DFS Danfoss Infocal 8 EMH EMH KIZ HYD 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 Danfoss Infocal 6 HYD Danfoss Infocal 8 HYD Hydrometer Hydroport INV Sensus HRI b1 ITR Itron meter KAM Kamstrup meter KAM Kamstrup meter KAM-01-0c Kamstrup Multical III KAM Kamstrup Multical 401 KAM Kamstrup meter KAM-07-0c Kamstrup meter KAM 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 Kamstrup meter KAM-11-0c Kamstrup meter KAM Kamstrup meter KAM-1b-16 Kamstrup Multical 21 KAM-1c-04 Kamstrup Multical 602 LDR Unknown meter LSE Landis & Staefa electronic meter LUG Landis & Gyr LUG Landis & Gyr meter REL Relay meter UNKNOWN Label for unknown M-bus meter type SEN-0e-04 Sensus meter SEN Sensus meter SVM-30-0c Svensk Värmemätning SVM meter WZG Neumann & Co. Wasserzähler meter Danfoss District Energy VI.HX.I1.01 DEN-SMT/DK 13

14 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. Beskrivelse * 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. 4 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 watt_hour 14 DEN-SMT/DK VI.HX.I1.01 Danfoss District Energy

15 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 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. Danfoss District Energy VI.HX.I1.01 DEN-SMT/DK 15

16 på ECL-log-devices fra stamdata: ECL-log type : EclLogDevice, externaldeviceid : eff82977-bf82-40ff-a23c-21a0c9a4065b, : EclLog, active : true, createdonportal : T08:21:16.318Z, logappname : A376.1 example a, lastread : T08:45:00.0Z, channels : [ : RefS4 (13254), readingvalueindex : 6, unit : degree_celsius : S2 (11202), readingvalueindex : 2, unit : degree_celsius : RefS5 (11255), readingvalueindex : 8, unit : degree_celsius : RefS3 (11253), readingvalueindex : 4, unit : degree_celsius : RefS10 (12260), readingvalueindex : 11, unit : degree_celsius : S9 (10209), readingvalueindex : 13 }] } : S4 (10204), readingvalueindex : 5 : S10 (10210), readingvalueindex : 10 : RefS9 (12259), readingvalueindex : 14, unit : degree_celsius : S1 (11201), readingvalueindex : 1, unit : degree_celsius : S7 (12207), readingvalueindex : 12, unit : degree_celsius : S6 (10206), readingvalueindex : 9 : S5 (10205), readingvalueindex : 7 : S3 (10203), readingvalueindex : 3 på ECL log devices fra stamdata: Konfigurerbart input type : EclConfigInputDevice, externaldeviceid : c4c3e66a-940f-4943-a ea6fea5, : S7, active : true, createdonportal : T06:30:38.109Z, lastread : T08:57:00.139Z, configinputtype : Pt 1000, configinputsensorid : S7, channels : [ : S7, readingvalueindex : 1, unit : degree_celsius }] } 16 DEN-SMT/DK VI.HX.I1.01 Danfoss District Energy

17 på ECL log devices fra stamdata: M-bus-måler type : EclMBusDevice, externaldeviceid : eda5c8c6-120f-4a7f-ad f49, : M68, active : true, createdonportal : T10:43:35.694Z, lastread : T10:00:00.660Z, mbusaddress : 68, mbusserialnumber : , mbustype : DFS-25-07, channels : [ : volume_flow, readingvalueindex : 2, unit : cubic_metre_per_hour, mbuschanneltype : VOLUME_FLOW, mbussubunit : 0 : flow_temperature, readingvalueindex : 3, unit : degree_celsius, mbuschanneltype : FLOW_TEMPERATURE, mbussubunit : 0 : 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. 7.3 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 8.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. Danfoss District Energy VI.HX.I1.01 DEN-SMT/DK 17

18 8.1 getreadings Request Parameter Beskrivelse servercode eclserial eclaccesscode externaldeviceid 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. Del af identifikation, jf. afsnit 5.3 om sikkerhed. Del af identifikation, jf. afsnit 5.3 om sikkerhed. Del af identifikation, jf. afsnit 5.3 om sikkerhed. Det eksterne identifikationsnummer for devicet (se stamdata). c0f6563e-2bd db2c0c700d78 FirmaA Kode5 from * Starttidspunkt (inklusive) i ISO 8601 format for udlæsning fra API. Default værdien er det aktuelle tidspunkt T08:53:00.0Z direction page pagesize clientrequestid Om man ønsker aflæsninger fra starttidspunktet og fremefter (forward) eller bagud (reverse). Bemærk, at sorteringen af aflæsningerne i svaret afhænger af dette valg. Default = reverse. 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. Sidestørrelsen, dvs. antallet af aflæsninger pr. side. Default = 1. Min = 1. Max = Bemærk, at hver aflæsning kan have op til 16 værdier, afhængig af antallet af kanaler for devicet. 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. forward b7f4d-7e1a-4d76-a4f0- be8fb52b7c80 *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). på request efter seneste aflæsning fra et bestemt device naldeviceid} c0f6563e- 2bd db2c0c700d78 18 DEN-SMT/DK VI.HX.I1.01 Danfoss District Energy

19 på request efter seneste aflæsning fra alle devices på en ECL regulator på request efter data fra en specifik device fra et givet tidspunkt og bagud i tid externaldeviceid=exter naldeviceid}&from=from}&pagesize=pagesize}&page=1 på request efter data fra en specifik device fra et givet tidspunkt og frem i tid 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) 8.2 getreadings Response Som svar på et reading request returneres et tracking objekt og et data object. Tracking object: Beskrivelse clientrequestid serverrequestid from direction page * pagesize resultreadings totalreadings ** Det valgfri tekst-id, som blev sendt med under selve requestet for at muliggøre sporbarhed hos tredjepart. 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). Gentagelse af request-parameteren eller default værdi, så man har styr på udgangspunktet Gentagelse af request-parameteren eller defaultværdi, så man har styr på retningen Gentagelse af request-parameteren eller defaultværdi, så man har styr på, hvor langt man har bladret. Gentagelse af request-parameteren eller defaultværdi, så man har styr på sidestørrelsen Antal aflæsninger indeholdt i dette svar (denne side typisk pagesize med undtagelse af sidste side). Antal aflæsninger, der er tilgængelige totalt set, hvis alle sider bladres igennem 555b7f4d-7e1a-4d76-a4f0- be8fb52b7c80 9cd4df10-09cc-4ec7-8b4ec1180b21d9d T08:53:00.0Z forward 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). Danfoss District Energy VI.HX.I1.01 DEN-SMT/DK 19

20 Data object Beskrivelse externaldeviceid ID, der bruges til at identificere device. Se stam data. c0f6563e-2bd db2c0c700d78 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. Beskrivelse timestamp ECL regulatorens tidsstempling af aflæsningen T08:53:00.0Z receivedtime Hvornår ECL Portalen har logget aflæsningen T08:55:32.9Z manualentry Kun for EclConfigInput devices af typen Pulse, til hvilke man kan indtaste værdier manuelt via ECL Portalen. False value1 Værdi 1. Dvs. værdien målt for kanalen, der har readingvalueindex = ø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 på en reading response tracking : clientrequestid : 555b7f4d-7e1a-4d76-a4f0-be8fb52b7c80, serverrequestid : 9cd4df10-09cc-4ec7-8b4e-c1180b21d9d9, from : T08: 53: 00.0Z, direction : forward, page : 1, pagesize : 1000, resultreadings : 1000, totalreadings : 5642, totalpages : 6 data : [ externaldeviceid : c0f6563e-2bd db2c0c700d78, readings : [ timestamp : T08: 53: 00.0Z, receivedtime : T08: 55: 32.9Z, manualentry : false, value1 : 41.82, value2 : , value3 : , value4 : 12 flere reading fra samme device her ] data fra andre devices her ] } 20 DEN-SMT/DK VI.HX.I1.01 Danfoss District Energy

21 9.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: Danfoss District Energy VI.HX.I1.01 DEN-SMT/DK 21

22 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 DEN-SMT/DK VI.HX.I1.01 Danfoss District Energy