Download - Installation Guide ECL Portal API Web interface for ECL ...heating.danfoss.com/PCMPDF/VIHXI102_ECL_Portal_API.pdf · Installation Guide ECL Portal API Web interface for ECL Portal

Installation Guide

ECL Portal APIWeb interface for ECL Portal databases

1Danfoss District Energy VI.HX.I1.02 DEN-SMT/DK

1.0 Table of Contents ..................................................................................................................................................................................................................11.0 Introduction ...........................................................................................................................................................................................................................22.0 Version table ...........................................................................................................................................................................................................................23.0 Glossary ...................................................................................................................................................................................................................................24.0 General ...................................................................................................................................................................................................................................35.0 Security ...................................................................................................................................................................................................................................3

5.1 Creating third party code ...............................................................................................................................................................................................45.2 Assigning access to a third party ...............................................................................................................................................................................5

6.0 Interfaces .................................................................................................................................................................................................................................66.1 API format ............................................................................................................................................................................................................................76.2 Future versions ..................................................................................................................................................................................................................76.3 Time formats ......................................................................................................................................................................................................................7

7.0 Master data service .............................................................................................................................................................................................................97.1 getEclMasterData request parameters .....................................................................................................................................................................9

7.1.1 Examples of getEclMasterData request parameters ............................................................................................................................ 107.2 getEclMasterData response ....................................................................................................................................................................................... 10

7.2.1 Example of getEclMasterData response .................................................................................................................................................... 107.2.2 Master data ........................................................................................................................................................................................................ 11

7.3 Status codes for response ........................................................................................................................................................................................... 178.0 Readings ................................................................................................................................................................................................................................ 17

8.1 getReadings Request ................................................................................................................................................................................................... 188.2 getReadings Response ................................................................................................................................................................................................ 19

9.0 Using the interface ............................................................................................................................................................................................................ 219.1 Extracting master data .................................................................................................................................................................................................. 23

9.1.1 M-bus, Main meter house ............................................................................................................................................................................... 259.1.2 M-bus, Solar heating, small tank .................................................................................................................................................................. 269.1.3 M-bus, Solar heating, large tank .................................................................................................................................................................. 289.1.4 ECL log, A367.1 example e ............................................................................................................................................................................. 309.1.5 Extracting readings ........................................................................................................................................................................................... 339.1.6 Read the latest values for one or more sensors on a meter connected to the ECL controller............................................... 339.1.7 Reading the most recently measured outdoor temperature ............................................................................................................ 349.1.8 Reading of Energy, Volume, Flow temperature and Return temperature for the house’s main meter .............................. 359.1.9 Read the latest value for one or more sensors across meters connected to the ECL controller. .......................................... 359.1.10 Read a period of historical data for one or more sensors on one meter connected to the ECL controller. ................... 35

9.2 Format differences in data extracted ....................................................................................................................................................................... 39

1.0 Table of Contents

Installation Guide ECL Portal API

2 DEN-SMT/DK VI.HX.I1.02 Danfoss District Energy

1.0 Introduction

This document is a description for a third party for use when implementing software clients to extract data from the ECL Comfort 310 Portal (ECL Portal).

2.0 Version table

Version Date Change

1.00 25/09/2013 First version.

1.10 25/10/2013 Section added about the creation of third party code, future version, time formats. JSON examples added for requests and responses.

1.11 29/10/2013 Example added of difference in data extraction from ECL Portal and ECL Portal API.Example added of time format in readings.

1.12 01/04/2014 A few detailed explanations and examples added.

3.0 Glossary

API Application Programming Interface. An interface for the sharing of application-specific information.

Device A device. Typically used in connection with a log device.

ECL Comfort 310 A district heating controller model from Danfoss A/S.

HTTPS HyperText Transfer Protocol. An encrypted protocol used to transfer information.

Configurable input.

Some sensor inputs on an ECL Comfort 310 controller can be adjusted as an option to measure temperature, pulse, frequency, 0-10 V analogue signal or digital ON/OFF

Customer A person, company or municipality that wants data extracted from the ECL Portal.

JSON JavaScript Object Notation. An open data format for sharing data between a server and an Internet program.

M-bus A communication protocol typically used by heat and energy meters.

Paging Division into pages. In order to avoid too much information being transferred at one time, a volume of data is divided into a number of pages, only one of which is read at a time.

Reading A reading. Log data extracted from the web API from a log device.

Request A request to the web API.

Response Response from the web API server to a request.

REST Representational State Transfer. A software architecture style that can be used to design Internet services.

Server code A unique code issued by Danfoss to a third party.

SSL Secure Sockets Layer. Encryption for the secure sharing of information used, for example on the Internet (HTTPS).

Master data Base data for an ECL Comfort 310 controller.

Third party code A code created by the customer in the ECL Portal, which the customer issues to a third party.

URL Uniform Resource Locator. An Internet address.

UTC Coordinated Universal Time. A standard for coordinated time based in Greenwich, London. Time zones are expressed with reference to UTC.

Web API An API adapted for the Internet.

Third party An external company engaged by a customer to develop software to extract data from the ECL Portal to an external system. Can be the customer.



4.0 General

The data that is available via the ECL Portal web API depends on the ECL application key installed in the ECL Comfort 310 in question. I.e. the data set available is different for each ECL application type and can also depend on the various external data collection devices, such as M-bus meters and configurable inputs with which ECL controllers can be fitted.

The ECL Portal retrieves data from the ECL controllers once an hour just after the top of the hour. The integrated ECL Log contains application-specific signals such as temperatures measured and temperature references, as well as wind speed, pressure or flow, depending on the application installed. The ECL log contains data recorded at 15-minute intervals. If the customer has set up configurable inputs or connected M-bus meters, the current values of these will also be retrieved once an hour.

If it is not possible to retrieve data from an ECL controller because of a communication error or for some other reason, an attempt will be made to retrieve the ECL log when the next collection takes place one hour later. The internal ECL log in the ECL controller contains data for the last ten days, so if it has not been possible to retrieve the log from an ECL controller for ten days, data will be lost from the ECL portal and will thus not be available through the web API.

As soon as data is available on the ECL Portal, it will also be available through the ECL Portal web API. It is not possible to retrieve data through the web API that is not available on the ECL Portal. If, for example, a customer deletes an ECL log or M-bus meter on the ECL Portal, it will no longer be available through the web API either.

Data is not saved for configurable inputs and M-bus meters in the ECL controller, so historical values will not be read when the logs are next retrieved if there has been no contact with the ECL Portal.

Guides for individual ECL applications are available at www.ecl.doc.danfoss.com, if it is necessary for a third party to have more specific knowledge of the data that can be extracted from the ECL controllers.

A description of communication for ECL controllers may be found here:http://heating.danfoss.com/PCMPDF/VILGV402_ECL_Comfort_210_310_Communication.pdf or by Googling “ecl communication description” to find the latest version. The communication description contains, among other things, a general list of parameters that are logged by some applications.

5.0 Security

As this is an external interface from the ECL Portal server to the outside world, it is particularly important to make sure that it is not possible to gain access to other parties’ data.

The first element in securing data is identification, so that you can validate whether the client that is calling the ECL Portal web API is authorised to view the data being requested. You must therefore always specify the following in requests:• Servercode.ThisisissuedbyDanfosstoathirdpartyorcustomer,sothattheopeningofthedatainterfaceisanactiveprocessperformed by Danfoss. This involves a setup in connection with the conclusion of a legal contract. • ECLserialnumber.UsedtoidentifyanECLcontrollerofinterest.TheserialnumbermaybefoundinsidetheECLcontroller’smenuorat the ECL Portal• Thirdpartycode.CreatedbythecustomerintheECLPortalandissuedtoathirdparty.

Not only must the third party or customer have stated a server code and know the serial number, but the customer himself must link third party codes to the ECL controller. This provides the customer with the possibility of controlling which third party people and systems they wish to allow to extract the data by assigning them various third party codes, which can of course also be revoked individually.

This means that in order to obtain data from a given ECL controller, you must know its serial number, have a server code issued from Danfoss and have assigned yourself, your system or third party an ECL-specific third party code.

Just as with traditional user name/password combinations, data will only be able to fall into the wrong hands if the combination is compromised, as in such an eventuality an external party would only be able to use the same codes and perform his own requests. Security is thus dependent in this scenario on how the customer and the third party protect this information.

Server codes are issued to the customer/third party individually and may not be shared by a number of customers, as under the legal contract such party may be cancelled when the contract expires or in the event of abuse.

Data communication through the web API requires SSL support. If a client sends requests via HTTP, it will be redirected to HTTPS.



5.1 Creating third party code

Use the “Third party codes” menu.

Give a name to the third party code in order to keep track of all codes, and select the setting “Enabled” to render the code active.

The code will now appear in the list of codes created.

Click on the “ECLs” link to go to the page where the code can be assigned to specific ECL controllers.

You can assign the same code here to several ECL controllers, and you can assign several codes to the same ECL controller, so that you can better control who has access to what.



5.2 Assigning access to a third party

a) If the customer has not previously provided the third party in question with access to data for some ECL controllers administered by the end customers, the end customer sets up a code for the third party under the menu item ECL > Third party codes.

b) The end customer links the relevant ECL controller to the relevant third party code. c) The end customer notifies the third party of the ECL serial number and the third party code.

With these three pieces of information (server code, ECL serial number, third party code), the third party now has the ability to access data for the ECL controller via the web API.

The conceptual interfaces that will be accessible via the web API are described here. Conceptual means what you can request, including which items of information are required in order to request, as well as which items of information you receive in return from such requests.

When you retrieve readings for a given period, it may be the case that the period includes a large number of readings, which is not suitable for transfer via an HTTP request in one action. It is therefore a good idea to operate using what is known as paging, i.e. when you make your request, in addition to indicating the period, you can indicate how many readings you wish to receive at a time. From the responses you receive in return, you can then see whether you have received all readings on the “first page” (/response) or whether you have to retrieve more, and how many you can expect to have to retrieve in total. On the basis of this you can then request the next page, and so on. At the same time, the system defines a default page size and a maximum page size, so you do not need to specify a page size, and nor do you run the risk that a client will ask for an unrealistically large load of data in one single request.

As an ECL controller can operate with several log devices and at different log frequencies, it is difficult to create a logical “page break” in the event that not all data can be returned at one time. When you retrieve readings, it is good to know in advance which devices are accessible on an ECL controller, which ones are active, etc. There is thus a need to be able to obtain this information when readings are to be retrieved, but also if a third party wishes to store/synchronise details of the ECL controllers, devices and channels – what is known as master data.

Examples of accessible devices and channels in an ECL Comfort 310 controller with a given application, which has connected two heat meters via M-bus:



Device type Channels Description

EclLogDevice S1 These channels belong to sensors and reference values used by the application.

S2

S3

S4

S5

S6

S7

RefS3

RefS4

RefS5

RefS9

RefS10

EclConfigInputDevice S9 This input is not used by the application and can therefore be used as a configurable input.

EclConfigInputDevice S10 This input is not used by the application and can therefore be used as a configurable input.

EclConfigInputDevice S11 This input is not used by the application and can therefore be used as a configurable input. Requires ECA 32 module in ECL Comfort 310.



EclMBusDevice volume_flow These channels are accessible in the relevant heat meter, which is connected via M-bus.

flow_temperature

volume

EclMBusDevice volume_flow These channels are accessible in the relevant heat meter, which is connected via M-bus.

flow_temperature

volume

energy

return_temperature

6.0 Interfaces



For this reason, there will be a division of the services that the web API makes available. One service that operates with master data and one service that operates with readings. To make the transfer of readings as optimal as possible in terms of performance, these calls will only return the raw values. In order to interpret them (e.g. in terms of units, etc.), they must then be aligned with master data.

6.1 API format

The web API is a REST (REpresentational State Transfer) API via HTTPS(GET) requests, in which the argument is extracted as a combination of URL components and URL query parameters.

The response format will always be minimalist JSON due to performance. Later in this document there are examples of requests in the correct format.

When the third party has received the server code, third party code and serial number for an ECL controller, they can test the web API by pasting an example from a later section into a browser such as Chrome, after which they will receive a response. The JSON Viewer plug-in for Notepad++ can easily be used to format the JSON text received into an easily readable format.

6.2 Future versions

The interface is prepared for any changes in the future in the format, as an interface version must accompany the requests. The version indicator must be specified in the following form:

https://{host}/endpoint/{version}/...

in which {version} must be replaced by the name of the version format. The version name for the first version is “v1”. See examples where this is used in a later section. The endpoint can be either master data or readings, as described in subsequent sections.

When new versions are introduced, an end date will be announced for the old version, so that third party companies have a period during which they can update their software to the new version.

The old version will no longer be available after the end date. When a new version is available, this will be announced on the front page of the ECL Portal and/or the newsletter.

{host} must be replaced by eclwebapi.danfoss.dk for the web API linked to the Danish ECL Portal at ecl.portal.danfoss.dk.For the web API on the international ECL Portal, {host} must be replaced by eclwebapi.danfoss.com.It is not possible to access ECL controllers at the Danish portal through the web API for the international portal, or vice versa.

6.3 Time formats

Time stamps in the web API follow the ISO 8601 standard. This means that time stamps will be in UTC by default and will appear as:

2013-04-18T08:53:00.0Z

Time stamps in response messages will always be in UTC, and third party software may then convert to other time zones as required. In master data for individual ECL controllers, the time zone stated is the one that was specified under the ECL controller’s data by the owner/administrator on the ECL Portal.

It is possible to specify time stamps in other time zones, when you request data by specifying the local time zone. The above time stamp will then be expressed as

2013-04-18T10:53:00.0+02:00

The “+” symbol must be expressed as “%2B” in requests and the “-” symbol must be expressed as “%2D”

If the time in the ECL controller does not match, or the time zone in the ECL Portal is incorrect, the time stamps in the data extracted may be misleading.

Sample reading for ECL log taken from the ECL Portal API on 29/10/2013 at 09:40 Danish standard time.



{“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 } ]}]}

The first “from” parameter is the current reading time, here shown with the time zone +01:00.“timestamp” is the ECL controller’s time for the sample in question.“receivedTime” is the time in the ECL Portal at the point in time when it extracted data from the ECL controller. As data is extracted once an hour, there will typically be four samples (one for each quarter of an hour) with the same “receivedTime” value, although if there has been a failure in data communication, more data may have been extracted at the same time.

If there is no data in the database for the specified time in the specified direction, the data field in the response will be empty.

Sample reading for ECL log extracted from the ECL Portal API on 01/01/2014 at 12:05 Danish Summer Time. The time in the ECL controller has been wrongly set here, and an incorrect time zone has been selected (UTC+02:00 instead of UTC+01:00) in the ECL Portal.



{ “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 }] }]}

The associated log extracted as an Excel file from the ECL Portal shows:

You can see here that the ECL controller’s time at the last sample was 2012-10-04 05:15:00, while the time in the data from the web API was 2012-10-04 02:15:00Z. There is thus a three-hour difference, which comes from the time zone (which is +2 hours) and summer time (+1 hour)By comparing the three times (from, timeStamp and receivedTime), you can check whether the time has been set correctly in the ECL controller, and whether the correct time zone has been selected in the ECL Portal.

7.0 Master data service

This section describes what the master data service can be used for. In this first version, the service has only one method. The method is getEclMasterData, and it retrieves all relevant master data for a given ECL controller, including connected meters. It also includes data that is necessary to interpret the readings that can be retrieved. Below is a description of the conceptual content of request and response.

7.1 getEclMasterData request parameters

Parameter Description Example

serverCode Part of identification cf. section 5 on security. CompanyA

eclSerial Part of identification cf. section 5 on security. 123456792

eclAccessCode Part of identification cf. section 5 on security. Code5

clientRequestId Optional text that can be used to implement traceability in third party systems that function asynchronously. Can be omitted, but would otherwise typically be an auto-generated unique ID.

555b7f4d-7e1a-4d76-a4f0-be8fb52b7c80

Date Outdoor temperature Kr 1, room temperature Kr 1, flow temperature Kr 2, domestic water temperaturetemperature



7.1.1 Examples of getEclMasterData request parameters

Examples with 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

7.2 getEclMasterData response

The following information is returned in the response from the server for reasons of traceability.

Element Description Example

clientRequestId The ID that was sent during the actual request in order to permit traceability in the third party.

555b7f4d-7e1a-4d76-a4f0-be8fb52b7c80

serverRequestId The server itself assigns a unique ID to each request, as there is no requirement that you must send a unique client ID across customers. This ID can be used if you are in any doubt about the server’s handling of a request, as various pieces of statistical information will be logged about each request (see section 5.4 on traceability).

9cd4df10-09cc-4ec7-8b4e-c1180b21d9d9

7.2.1 Example of getEclMasterData response

Master data is described in greater detail in the next section.

{“tracking”: { “serverRequestId”: “d4b86aa4-f4a0-4ce8-9f14-3c7bd3cc3c80”},“masterData”: { “application”: “A376.1”, “applicationVersion”: “4.00”, “hardwareModel”: “ECL 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] }}



7.2.2 Master data

The following basic master data is also returned with the response for the actual ECL controller.


application Which application the ECL controller is running.

A376.1

applicationVersion Version of the application 4.00

hardwareModel Hardware model number ECL 310, 230 V

hardwareVersion Hardware version A

softwareBuild * Software build number 7232

hardwareProductionTime Hardware production time 3.2010

firmwareVersion Firmware version number 1.48

serialNumber Serial number 123456792

createdOnPortal Date when the ECL controller was created on (first linked to) the portal

2013-04-18T08:53:00.0Z

timezone Time zone in which ECL controller is located (selected on ECL Portal)

Europe/Copenhagen

location:Street ** Street in which ECL controller is located (if entered on ECL Portal)

Solitudevej

location:StreetNumber ** House number at which ECL controller is located (if entered on ECL Portal)

13A

location:Zip ** Postcode at which ECL controller is located (if entered on ECL Portal)

6400

location:City ** Town/city in which ECL controller is located (if entered on ECL Portal)

Andeby

location:Country ** Country in which ECL controller is located (if entered on ECL Portal)

Denmark

name Name (entered on ECL Portal) Heating in basement

description ** Description (if entered on ECL Portal) Basement

portalGroup ** Group set up in EP to group ECL controllers

Group1

* This string was originally “hardwareBuild”, but has since been corrected to “softwareBuild”.** This data is only sent with master data if it has been entered in the ECL Portal.

Furthermore, for every device on the ECL controller, the following information about the actual device will be returned.




type Specifies the type of device. Possible results are “EclLogDevice”, “EclConfigInputDevice” and “EclMBusDevice”.

EclLogDevice

externalDeviceId External ID number for the device. Must be used, for example, to be able to retrieve readings for the device.

c0f6563e-2bd0-4514-9539-db2c0c700d78

name Name of the device. For an ECL log, the name is always “EclLog”. For other types, any name can be used when created on the ECL Portal.

EclLog

active Denotes whether the device is in use. Possible values are “false”/“true”.Only one ECL log device may be active at a time, although several EclConfigInputDevices or EclMBusDevices can be created at the same time. The active ECL log corresponds to the portal application currently selected.

True

createdOnPortal Creation time for device in ISO 8601 format. 2013-04-18T08:53:00.0Z

lastRead Time last read in ISO 8601 format. 2013-04-18T08:53:00.0Z

logAppName Portal application currently selected. There are many different possibilities, so they will not be mentioned here.

A376.1 example a

configInputType Possible values are: 0-10V ADC

-Pt 1000

-0-10V ADC

-Digital

-Flow switch

-Pulse

-Frequency

If it is an unknown type, “7” is returned.

For EclConfigInputDevices only.

configInputDefinedMaxValue* For EclConfigInputDevices of the type 0-10 V ADC only. 4

configInputDefinedMinValue ** For EclConfigInputDevices of the type 0-10 V ADC only. 2

configInputCircuitCloseText For EclConfigInputDevices of the type “Digital” or “Flow switch” for status “close” only.

Signal OK

configInputCircuitOpenText For EclConfigInputDevices of the type “Digital” or “Flow switch” for status “open” only.

No signal

configInputSensorId For EclConfigInputDevices only. Indicates at which input the configurable input has been created.

S9

mbusAddress For EclMBusDevices only. The address of the M-bus network. 15

mbusSerialNumber For EclMBusDevices only. Unique serial number for the M-bus meter. 06120815

mbusType *** For EclMBusDevices only. Type of M-bus meter. Consists of manufacturer code and type code.

KAM-08-0c

channels Channel information is shown in a later table below.

* This parameter indicates which actual value 10 V represents for 0-10 V ADC input.** This parameter indicates which actual value 0 V represents for 0-10 V ADC input.*** Known types are:



ABB-02-02 ABB meterABB-06-02 ABB DBMABB-07-02 ABB ODACW-09-04 Actaris meterACW-0b-04 Actaris meterACW-0b-0c Actaris meterACW-0f-04 Actaris meterACW-14-07 Actaris meterAXI-04-04 Axis SKS3BHG-05-04 Brunata meterBHG-3d-04 Brunata HGQBHG-3d-0c Brunata meterBHG-3d-16 Brunata meterDEI-14-02 Deif APM 380DFS-01-04 Danfoss meterDFS-01-0c Danfoss meterDFS-20-04 Danfoss Sonometer 1100 Heat meter DFS-20-0a Danfoss Sonometer 1100 Cooling meter DFS-25-07 Hydrometer HydrusDFS-2b-04 Danfoss Sonometer 1000DFS-2b-0c Danfoss meterDFS-2f-04 Danfoss Sonometer 1100DFS-41-04 Danfoss Sonometer 500DFS-43-0c Danfoss M-Cal CompactDFS-50-04 Danfoss Infocal 6DFS-52-04 Danfoss Infocal 8EMH-00-02 EMH KIZHYD-20-04 Danfoss Sonometer 1100 Heat meter HYD-20-0a Danfoss Sonometer 1100 Cooling meter HYD-20-0c Hydrometer meterHYD-2b-04 Danfoss Sonometer 1000HYD-2f-04 Danfoss Sonometer 1100HYD-2f-0c Hydrometer meterHYD-50-04 Danfoss Infocal 6HYD-52-04 Danfoss Infocal 8HYD-95-02 Hydrometer HydroportINV-40-07 Sensus HRI b1ITR-18-04 Itron meterKAM-01-02 Kamstrup meterKAM-01-04 Kamstrup meterKAM-01-0c Kamstrup Multical IIIKAM-02-04 Kamstrup Multical 401KAM-07-04 Kamstrup meterKAM-07-0c Kamstrup meterKAM-08-04 Kamstrup meterKAM-08-0c Kamstrup Multical 601KAM-0b-04 Kamstrup Multical 402KAM-0b-0c Kamstrup meterKAM-0f-04 Kamstrup meterKAM-0f-0c Kamstrup Multical 801KAM-0f-16 Kamstrup meterKAM-11-04 Kamstrup meterKAM-11-0c Kamstrup meterKAM-15-04 Kamstrup meterKAM-1b-16 Kamstrup Multical 21KAM-1c-04 Kamstrup Multical 602LDR-01-02 Unknown meterLSE-10-04 Landis & Staefa electronic meterLUG-02-04 Landis & GyrLUG-04-04 Landis & Gyr meterREL-41-07 Relay meterUNKNOWN Label for unknown M-bus meter typeSEN-0e-04 Sensus meterSEN-52-07 Sensus meterSVM-30-0c Svensk Värmemätning SVM meterWZG-03-07 Neumann & Co. Wasserzähler meter



The list of known M-bus meters will probably be extended in future, as more are added.

Furthermore, for every single channel on the device, the following information about the actual channel will be returned.


name * Name of channel. Current volume.

readingValueIndex Which of the up to 16 values in a reading belong to this channel. Min. = 1 and max. = 16. If 4, the value is -4 in a reading from this channel.

4

unit Specifies the unit in which values are measured. Depends on the M-bus meter type, so new meters may contain new values. Possible values are: -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



mbusChannelType Used for M-bus devices to specify the channel type. Depends on the M-bus meter type, so new meters may contain new values. Possible values are:-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-TARIFF

VOLUME_FLOW

* ) The name depends on factors including the device type, as explained below.

For EclConfigInput devices, the name can be entered by the owner/administrator of the ECL Portal.For EclLog devices, the name depends on the sensor number. Sensor 1 is called S1, sensor 2 is called S2, etc. The reference value for sensor 2 is RefS2, the reference value for Sensor 3 is RefS3, etc. Furthermore, some applications log certain signals that do not come directly from the sensors. These signals are named after their PNU/ID. For example, the PNU 11098, which is the calculated wind strength, is logged in A230.1.

It is therefore named “11098”. It is not possible to name all logged signals for all applications, which is why simple names should be specified.

For EclMBusDevices, the channel is named on the basis of what the M-bus meter says it is. The name therefore depends on the specific meter type being used. Possible names are: -power -return_temperature -temperature_difference -voltage -volume_flow -volume -current -energy -flow_temperature -on_time -operating_time -statusThe list of possible names may be extended in future if new M-bus meters make this necessary.



Examples of ECL log devices from master data: 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}]}

Examples of ECL log devices from master data: Configurable 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”}]}



Examples of ECL log devices from master data: M-bus meter

{“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}]}

As an ECL can have several old log devices of all types, which are no longer active, the owner/administrator should make sure that old devices on the ECL Portal are deleted if there is no longer any use for their data content.

7.3 Status codes for response

Errors will be responded to in accordance with the HTTP standard, i.e. the response must be able to have one of the following HTTP status codes (for all codes other than code 200, the response will not contain data, but typically a text explaining the problem in detail). • 200–OK• 400–Badrequest,typicallybecauseaparameterismissing.• 401–Unauthorised,i.e.theservercodeorthirdpartycodeisnotcorrect.• 404–ECLnotfound• 500–Otherunknownerror

8.0 Readings

This section describes what the readings service can be used for.

In this first version, the service has only one method. The method is getReadings and it retrieves readings for a device for a given period. In order to optimise data transfer, the result is kept as simple as possible, and you will typically have to know the master data for the ECL controller in order to be able to process the values received. Below is a description of the conceptual content of request and response.



8.1 getReadings Request

Parameter Description Example

serverCode Part of identification cf. section 5.3 on security.

CompanyA

eclSerial Part of identification cf. section 5.3 on security.

123456792

eclAccessCode Part of identification cf. section 5.3 on security.

Code5

externalDeviceId The external ID number for the device (see master data).

Default = “*”, which means that you are interested in data from all devices for the ECL controller. This is all permitted when pageSize = 1, in all other cases you must identify a specific device.

c0f6563e-2bd0-4514-9539-db2c0c700d78

from * Start time (inclusive) in ISO 8601 format for reading from API. The default value is the current time.

2013-04-18T08:53:00.0Z

direction If you want readings from the start time and thereafter (forward) or before (reverse). Please note that the sort results of readings in the response depend on this selection. Default = “reverse”.

forward

page Specifies which page you want to have. If, for example, pageSize is 1000 and you state that you want to have page 2, you will typically skip the first 1000 readings (typically because you have received them in a previous request). Default = 1. Min = 1.

1

pageSize The page size, i.e. the number of readings per page. Default = 1. Min = 1. Max = 15,000. Please note that each reading can have up to 16 values, depending on the number of channels for the device.

1000

clientRequestId Optional text ID that can be used to implement traceability in third party systems that function asynchronously, as this is sent with the response. Can be omitted, but would otherwise typically be an auto-generated unique ID.

555b7f4d-7e1a-4d76-a4f0-be8fb52b7c80

* If you have performed a recent extraction of master data, you will also know when you last received data (lastRead from the device).

Example of request following the last reading from a specific device.

https://{host}/readings/{version}/{eclSerial}?serverCode={serverCode}&eclAccessCode={eclAccessCode}&externalDeviceId={externalDeviceId}

https://eclwebapi.danfoss.dk/readings/v1/123456792?serverCode=FirmaA&eclAccessCode=Kode5&externalDeviceId= c0f6563e-2bd0-4514-9539-db2c0c700d78



Example of request following the last reading from all devices on an ECL controller.

https://{host}/readings/{version}/{eclSerial}?serverCode={serverCode}&eclAccessCode={eclAccessCode}

Example of request for data from a specific device from a given date and back in time.

https://{host}/readings/{version}/{eclSerial}?serverCode={serverCode}&eclAccessCode={eclAccessCode}& externalDeviceId={externalDeviceId}&from={from}&pageSize={pageSize}&page=1

Example of request for data from a specific device from a given date and ahead in time.

https://{host}/readings/{version}/{eclSerial}?serverCode={serverCode}&eclAccessCode={eclAccessCode}&externalDeviceId={externalDeviceId}&direction=forward&from={from}&pageSize={pageSize}&page=1

If there is no data in the database for the specified time, the API will deliver the next set of data in the specified direction (forward/reverse).

8.2 getReadings Response

As a response to a reading request, one tracking object and one data object are returned.Tracking object:


clientRequestId The optional text ID that was sent during the actual request in order to permit traceability in the third party.

555b7f4d-7e1a-4d76-a4f0-be8fb52b7c80

serverRequestId The server itself assigns a unique ID to each request, as there is no requirement that you must send a unique client ID across customers. This ID can be used if you are in any doubt about the server’s handling of a request, as various pieces of statistical information will be logged about each request (see section 5.4 on traceability).

9cd4df10-09cc-4ec7-8b4e-c1180b21d9d9

from Repeat of the request parameter or default value, so that you can check the starting point.

2013-04-18T08:53:00.0Z

direction Repeat of the request parameter or default value, so that you can check the direction.

forward

page * Repeat of the request parameter or default value, so that you can check how far you have “browsed”.

1

pageSize Repeat of the request parameter or default value, so that you can check the page size.

1000

resultReadings The number of readings contained in this response (this page – typically pageSize except the last page).

1000

totalReadings ** The total number of readings available if you browse through all pages. 5642

totalPages ** The total number of pages needed to read all readings. 6

*) To continue to the next set of data, you will thus use the same request parameters, but increase the page by one for each reading. **) Only specified for the response on page 1, so that the rows for each page are not counted again. Also specified only if externalDeviceId is different from * (as there is no support anyway for paging when submitting requests to several devices simultaneously).



Data object


externalDeviceId ID used to identify the device. See master data. c0f6563e-2bd0-4514-9539-db2c0c700d78

readings A compilation of readings belonging to the device. See next table for contents

For each reading, the following information will also be contained in the response.


timestamp The ECL controller’s time stamp for the reading. 2013-04-18T08:53:00.0Z

receivedTime When the ECP Portal logged the reading. 2013-04-18T08:55:32.9Z

manualEntry Only for EclConfigInput devices of the “Pulse” type, for which you can enter values manually via the ECL Portal.

False

value1 Value 1, i.e. the value measured for the channel that has readingValueIndex = 1. 41.82

… 15 Other value fields as above, up to value16, which is the last one.

There is no dependency on the log frequency. The readings will only be listed ascending or descending (depending on what you have requested) in chronological order. I.e. there can in theory be a change in the log frequency over a period.

Errors will be responded to in accordance with the HTTP standard, i.e. the response must be able to have one of the following HTTP status codes (for all codes other than code 200, the response will not contain data, but typically a text explaining the problem in detail). • 200–OK• 400–Badrequest,typicallybecauseaparameterismissingorincorrectlyformatted.• 401–Unauthorised,i.e.theservercodeorthirdpartycodeisnotcorrect.• 404–ECLordevicenotfound• 500–Otherunknownerror

Example of a 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 }, …more readings from the same device here…]},…data from other devices here…]}



9.0 Using the interface

This section describes/provides examples of different scenarios for using the API.

The API can be used to request data from any ECL controller. The actual scenarios described later in this document are based on the following setup:

This is an A367.1 example e, to which 3 M-bus-based heat meters have been linked together with one pulse-based water meter. On the ECL Portal, the ECL controller appears with the following log units (referred to in web API terms as devices) under ECL > Log:

example e

Main water meter (S17)



There are two ECL log devices here, because first of all the port application has been changed from example a to example e, as the user felt that this was more suitable for the system in question. Only one ECL log is active (True), and the other only contains old data. All log devices can be read through the web API. To read a specific log device, you must use the correct externalDeviceId, which can be found by reading master data, which also specifies which log devices are active.

Each log device has a number of channels for which values are logged. These can best be viewed on the Portal as a list under Graph > User-defined graph > Create new graph; the list is shown below, as based on our example ECL:



9.1 Extracting master data

Before you extract the readings for an ECL controller, it will be relevant to retrieve the latest master data. Retrieving the master data for the above ECL controller takes place by making one single call to the web API. This can take the form of a request to the REST endpoint, and the response will be in JSON format.



As mentioned earlier, master data is returned for the actual ECL controller together with each of the linked devices/log devices (in this instance 6 devices, as master data is also returned for inactive devices).

As described in section 7.1, the server code, ECL serial number, third party code and possibly a clientRequestId are sent as parameters in the request. This includes a description of which information is contained in the response from the web API. Information that includes what can be seen in the portal (cf. screenshots earlier on in this document) and additional details.

Request:

https://eclwebapi.danfoss.dk/masterdata/v1/123456792?serverCode=FirmaA&eclAccessCode=Kode5

For reasons of traceability, the following request ID information is returned in the response from the server. This does not relate to master data registered on the portal, but only to the actual master data request, and will therefore be different for each request.

Element Value

clientRequestId 555b7f4d-7e1a-4d76-a4f0-be8fb52b7c80

serverRequestId 9cd4df10-09cc-4ec7-8b4e-c1180b21d9d9

The following basic master data is returned for the actual ECL controller.

Element Example

application A367.1

applicationVersion 1.00

hardwareModel ECL 310, 230 V

hardwareVersion B

softwareBuild 6884

hardwareProductionTime 51.2010

firmwareVersion 1.46

serialNumber (rendered anonymous)

externalEclId cb829044-b117-4ac7-b265-7b4b23e6338c

createdOnPortal 2011-04-18T12:55:32.9Z

timezone Europe/Copenhagen

locationStreet (rendered anonymous)

locationStreetNumber 8

locationZip 6400

locationCity Sønderborg

locationCountry Denmark

name (rendered anonymous)

Description and portalGroup are not entered for this ECL controller, so they will not be included. Furthermore, for every device/log device on the ECL controller, a number of items of information about the actual device and underlying channels will be returned.



9.1.1 M-bus, Main meter house

Element Example

type MBusDevice

externalDeviceId 8dbb8b99-96a4-498c-b75b-c7453e1ad6c1

name Main meter house

active true


lastRead 2013-04-29T09:05:00.0Z

mbusAddress 61

mbusSerialNumber 38925461

mbusType Danfoss Sonometer 1100



The following information is returned about the 4 channels.

Element Example

name Energy

readingValueIndex 1

unit Wh

unitKey watt_hour

mbusChannelType ENERGY

Element Example

name Volume

readingValueIndex 2

unit m³

unitKey cubic_metre

mbusChannelType VOLUME

Element Example

name Return flow temperature

readingValueIndex 4

unit °C

unitKey degree_celsius

mbusChannelType RETURN_TEMPERATURE

Element Example

name Flow temperature

readingValueIndex 3

unit °C


mbusChannelType FLOW_TEMPERATURE

9.1.2 M-bus, Solar heating, small tank

Element Example

type MBusDevice

externalDeviceId c76c6a87-270c-4123-be57-d39f8f551f43

name Solar heating, small tank

active true



Element Example


lastRead 2013-04-29T09:05:00.0Z

mbusAddress 2



The following information is returned about the 6 channels:

Element Example

name Energy

readingValueIndex 1

unit Wh

unitKey watt_hours


Element Example

name Volume

readingValueIndex 2

unit m³

unitKey cubic_metre


Element Example


readingValueIndex 5

unit °C



Element Example

name Current volume.

readingValueIndex 4

unit m³/h

unitKey cubic_metre_per_hour

mbusChannelType VOLUME_FLOW



Element Example

name Current output

readingValueIndex 3

unit W

unitKey watt

mbusChannelType POWER

Element Example


readingValueIndex 6

unit °C



9.1.3 M-bus, Solar heating, large tank

Element Example

type MBusDevice

externalDeviceId 64365d4b-b991-4512-b3ea-456ee6c83b33

name Solar heating, large tank

active true


lastRead 2013-04-29T09:05:00.0Z

mbusAddress 1




Element Example

name Volume

readingValueIndex 2

unit m³

unitKey cubic_metre




Element Example

name Current output

readingValueIndex 3

unit W

unitKey watt

mbusChannelType POWER

Element Example


readingValueIndex 6

unit °C



Element Example

name Energy

readingValueIndex 1

unit Wh

unitKey watt_hours


Element Example

name Current volume.

readingValueIndex 4

unit m³/h

unitKey cubic_metre_per_hour

mbusChannelType VOLUME_FLOW

Element Example


readingValueIndex 5

unit °C





9.1.4 ECL log, A367.1 example e

Element Example

type EclLogDevice

externalDeviceId 2cc34b74-2c42-4ad1-a6c4-f27876b1c799

name EclLog

active true


lastRead 2013-04-29T09:00:00.0Z

logAppName A367.1 example e


Element Example

name Kr 2, return temperature

readingValueIndex 10

unit °C


Element Example

name Kr 3, upper tank temperature

readingValueIndex 7

unit °C


Element Example

name Kr 2, return temperature ref.


unit °C


Element Example

name Kr 1, room temperature

readingValueIndex 2

unit °C




Element Example

name Kr 2, flow temperature ref.


unit °C


Element Example

name Kr 1, flow temperature

readingValueIndex 3

unit °C


Element Example

name Outdoor temperature

readingValueIndex 1

unit °C


Element Example

name Kr 2, flow temperature


unit °C


Element Example

name Kr 3, upper tank temperature ref.

readingValueIndex 8

unit °C


Element Example

name Kr 3, lower tank temperature

readingValueIndex 9

unit °C

Element Example

name Kr 2, room temperature


unit °C




Element Example

name Kr 1, flow temperature ref.

readingValueIndex 4

unit °C


Element Example

name Kr 1, supply, return temperature ref.

readingValueIndex 6

unit °C


Element Example

name Kr 1, supply, return temperature

readingValueIndex 5

unit °C


ECL configurable input, Main water meter

Element Example

type EclConfigInputDevice

externalDeviceId 77df9535-9333-4222-b0a5-b5d6d08da1b3

name Main water meter

active true


lastRead 2013-04-29T09:06:00.0Z

configInputType Pulse

configInputSensorId S17

Element Example

name Main water meter

readingValueIndex 1

unit m³

unitKey cubic_metre

configSensorId S17



9.1.5 Extracting readings

This section describes the use of the web API to extract readings.

In order to be able to extract readings for a given period (rather than, for example, just the last reading), it is a requirement that you know the device’s external ID (which is contained in the master data), and under all circumstances you need to know which values in a reading represent what (which channel), and in which unit it is measured (also contained in the master data).

There is thus a need to know the master data for one reason or another. Whether you retrieve master data for an ECL controller immediately before retrieving data for it, or you use cached master data, depends on the user scenario in the third party application. There will, however, be a need to retrieve updated master data at intervals, as the customer may make changes to the setup without informing the third party. However, if readings are to be requested over several pages, it is not necessary to request master data for each page. The following scenarios assume that you have master data available for the ECL controller, in one way or another, before retrieving the data for the readings.

9.1.6 Read the latest values for one or more sensors on a meter connected to the ECL controller

Retrieving the latest reading (which contains one value for each sensor/channel) for a meter/device connected to the ECL controller takes place by making one single call to the web API. This can take the form of a request to the REST endpoint, and the response will be in JSON format.

Many of the input parameters are essentially set up to read the latest value, which is why you only need to define a few parameters in the call. In addition to the identification parameters (server code, ECL serial number and third party code), only the meter’s/device’s external ID (externalDeviceId) from the master data needs to be specified in the call.



9.1.7 Reading the most recently measured outdoor temperature

The outdoor temperature is measured via the ECL log, which has the externalDeviceId = 2cc34b74-2c42-4ad1-a6c4-f27876b1c799, cf. the master data, which is why this value is included in the request.

Request:

https://eclwebapi.danfoss.dk/readings/v1/123456792?serverCode=FirmaA&eclAccessCode=Kode5&externalDeviceId=2cc34b74-2c42-4ad1-a6c4-f27876b1c799

The following master data is returned:

direction backward

page 1

pageSize 1

resultReadings 1

The following reading is also returned in the same response message:

Element Example

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

Because the master data defines that the device in question has 14 channels, each reading for this device will have 14 values. It can also be seen from the master data that the outdoor temperature has readingValueIndex = 1, and that the unit is °C, i.e. that the value in °C must exist as value1 (the others are not of interest in this case), which in this case is 9.84.



9.1.8 Reading of Energy, Volume, Flow temperature and Return temperature for the house’s main meter

The main meter for the house is the M-bus device with externalDeviceId = 8dbb8b99-96a4-498c-b75b-c7453e1ad6c1. The request thus takes place in the same way as above, although with a different ID for the device:

Request:

https://eclwebapi.danfoss.dk/readings/v1/123456792?serverCode=FirmaA&eclAccessCode=Kode5&externalDeviceId=8dbb8b99-96a4-498c-b75b-c7453e1ad6c1


Element Example

timestamp 2013-04-29T09:05:00.0Z


manualEntry False

value1 1.9378E7

value2 1546.838

value3 61.3

value4 42.4

Interest has been expressed here in all 4 values, and according to the master data the following was read at 9:05: • Energy(readingValueIndex1):1.9378E7Wh• Volume(readingValueIndex2):1546.838m³• Flowtemperature(readingValueIndex3):61.3°C• Returnflowtemperature(readingValueIndex4):42.4°C

9.1.9 Read the latest value for one or more sensors across meters connected to the ECL controller.

Reading of the latest value across meters/devices takes place according to exactly the same principle as for one single device. The difference in the request is that you enter * instead of a specific externalDeviceId. There will still be just one request and one response from the server. The difference in the response message is that you will receive not just one reading, but instead one reading per device, which in our example will mean 6 readings (3 x M-bus, 2 x ECL log and 1 configurable input) in same message.

Request:

https://eclwebapi.danfoss.dk/readings/v1/123456792?serverCode=FirmaA&eclAccessCode=Kode5&externalDeviceId=*

9.1.10 Read a period of historical data for one or more sensors on one meter connected to the ECL controller.

Just as when reading the last reading, the readings in this case also include values for all channels/sensors on the meter, if several channels are available. But when reading data for a given period, it will not be possible to request across devices on the ECL controller, but always only one log device at a time. It is the same method being called, but with several arguments, and you may have to call the method several times in order to “cover” the desired period (depending on page size, log frequency and the length of the period).



Our starting point is that we want to retrieve all data for the main water meter. There is, cf. the master data, a configurable input module (of the pulse type with externalDeviceId = 77df9535-9333-4222-b0a5-b5d6d08da1b3), that has only 1 channel, where pulses are measures converted into m3. We can also see from the master data that the latest data is from 2013-04-29T09:06:00.0Z, and that it was first sensed by the portal at 2013-03-22T06:59:33.0Z. In this example we assume that a page size of 500 is most suitable for the third party client.

Request:

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

We start by requesting data as follows:

Parameter Example

serverCode CompanyA

eclSerial 123456792

eclAccessCode Code5


from * 2013-03-22T00:00:00.0Z

direction forward

page 1

pageSize 500





Element Example


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

The following readings are also returned in the same response message:

Element Example

timestamp 2013-03-22T07:06:00.0Z


manualEntry False

value1 0

… 498 other readings…

Element Example

timestamp 2013-04-12T02:08:00.0Z


manualEntry False

value1 10.05

We then request one more page of data, as the first response indicated that there were 2 pages of data available:

Request:

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



Parameter Example

serverCode CompanyA

eclSerial 123456792

eclAccessCode Code5


from * 2013-03-22T00:00:00.0Z

direction forward

page 2

pageSize 500



Element Example


serverRequestId 1bd4df10-09cc-4ec7-8b4e-c1180b21d9f9

from 2013-03-22T00:00:00.0Z

direction forward

page 2

pageSize 500

resultReadings 415

The following readings are also returned in this second response message, together with the above master data:

Element Example

timestamp 2013-04-12T03:08:00.0Z


manualEntry False

value1 10.05

… 413 other readings…

Element Example

timestamp 2013-04-29T09:06:00.0Z


manualEntry False

value1 15.32



9.2 Format differences in data extracted

Data extracted through the ECL Portal and the download in, for example, Excel format will be scaled to have only one decimal place, but data extracted through the ECL Portal API can contain a number of decimals depending on the raw data contained in the database.

Example of data download via the ECL Portal:

The same data downloaded via the web API:

Also note that the header for the data is different, cf. section 7.2.2 Master data.