Danfoss ECL Portal API Operating instructions

Danfoss
Brand
Danfoss
Model
ECL Portal API
Type
Operating instructions
© Danfoss |2017.01
VI.HX.I2.02 | 1
ECL Portal API
Web interface for ECL Portal databases
Operating Guide
1.0 Contents
1.0 Contents ..............................................................................................................................................................................................................................................1
2.0 Introduction ........................................................................................................................................................................................................................................2
3.0 Version table .......................................................................................................................................................................................................................................2
4.0 Glossary ..............................................................................................................................................................................................................................................2
5.0 General ..............................................................................................................................................................................................................................................3
6.0 Security ..............................................................................................................................................................................................................................................3
6.1 Creating third party code .....................................................................................................................................................................................................4
6.2 Assigning access to a third party .......................................................................................................................................................................................5
7.0 Interfaces ..............................................................................................................................................................................................................................................6
7.1 API format ................................................................................................................................................................................................................................... 7
7.2 Future versions ..........................................................................................................................................................................................................................7
7.3 Time formats .............................................................................................................................................................................................................................. 7
8.0 Master data service ........................................................................................................................................................................................................................ 9
8.1 getEclMasterData request parameters.............................................................................................................................................................................9
8.1.1 Examples of getEclMasterData request parameters .................................................................................................................................... 10
8.2 getEclMasterData response ...............................................................................................................................................................................................10
8.2.1 Example of getEclMasterData response ............................................................................................................................................................ 10
8.2.2 Master data ...................................................................................................................................................................................................................11
8.3 getEclMasterData response ...............................................................................................................................................................................................11
8.4 Status codes for response ................................................................................................................................................................................................... 17
9.0 Readings ...........................................................................................................................................................................................................................................17
9.1 getReadings Request ............................................................................................................................................................................................................18
9.2 getReadings Response .........................................................................................................................................................................................................19
10.0 Using the interface .......................................................................................................................................................................................................................21
10.1 Extracting master data .......................................................................................................................................................................................................23
10.1.1 M-bus, Main meter house .................................................................................................................................................................................25
10.1.2 M-bus, Solar heating, small tank ....................................................................................................................................................................26
10.1.3 M-bus, Solar heating, large tank .....................................................................................................................................................................28
10.1.4 ECL log, A367.1 example e ................................................................................................................................................................................30
10.1.5 Extracting readings .............................................................................................................................................................................................33
10.1.6 Read the latest values for one or more sensors on a meter connected to the ECL controller .................................................33
10.1.7 Reading the most recently measured outdoor temperature ...............................................................................................................34
10.1.8 Reading of Energy, Volume, Flow temperature and Return temperature for the house’s main meter ................................35
10.1.9 Read the latest value for one or more sensors across meters connected to the ECL controller .............................................35
10.1.10 Read a period of historical data for one or more sensors on one meter connected to the ECL controller .........................35
10.2 Format dierences in data extracted ............................................................................................................................................................................39
2 | © Danfoss| 2017.01
VI.HX.I2.02
Operating guide ECL Portal API
2.0 Introduction
This document is a description for a third party for use when implementing software clients to extract data from the
ECL Comfort 296 / 310 Portal (ECL Portal).
3.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 dierence 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.
4.0 Glossary
API Application Programming Interface. An interface for the sharing of application-specic information.
Device A device. Typically used in connection with a log device.
ECL Comfort 296 / 310 A district heating controller model from Danfoss A/S.
HTTPS HyperText Transfer Protocol. An encrypted protocol used to transfer information.
Congurable input Some sensor inputs on an ECL Comfort 296 / 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 296 / 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.
© Danfoss | 2017.01 | 3
VI.HX.I2.02
Operating guide ECL Portal API
5.0 General
The data that is available via the ECL Portal web API depends on the ECL application key installed in the ECL Comfort 296 / 310 in
question. I.e. the data set available is dierent for each ECL application type and can also depend on the various external data collection
devices, such as M-bus meters and congurable inputs with which ECL controllers can be tted.
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-specic signals such as temperatures measured and temperature references, as well as wind speed, pressure or ow,
depending on the application installed. The ECL log contains data recorded at 15-minute intervals. If the customer has set up
congurable 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 congurable 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 specic
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/VILGV502_ECL_Comfort_210_310_Communication.pdf or by Googling “ecl communication
description” to nd the latest version. The communication description contains, among other things, a general list of parameters that are
logged by some applications.
6.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 rst element in securing data is identication, 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:
• Server code. This is issued by Danfoss to a third party or customer, so that the opening of the data interface is an active process
performed by Danfoss. This involves a setup in connection with the conclusion of a legal contract.
• ECL serial number. Used to identify an ECL controller of interest. The serial number may be found inside the ECL controller’s menu or
at the ECL Portal
• Third party code. Created by the customer in the ECL Portal and issued to a third party.
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-specic 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.
4 | © Danfoss| 2017.01
VI.HX.I2.02
Operating guide ECL Portal API
6.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 specic 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.
© Danfoss | 2017.01 | 5
VI.HX.I2.02
Operating guide ECL Portal API
6.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 noties 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 “rst 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 denes 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 dierent log frequencies, it is dicult 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 296 / 310 controller with a given application, which has connected two
heat meters via M-bus:
6 | © Danfoss| 2017.01
VI.HX.I2.02
Operating guide ECL Portal API
7.0 Interfaces
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
EclCongInputDevice S9 This input is not used by the application and
can
therefore be used as a congurable inpu
t.
EclCongInputDevice S10 This input is not used by the application and
can
therefore be used as a congurable input
.
EclCongInputDevice S11 This input is not used by the application and
can
therefore be used as a congurable input
.
Requires ECA
32 module in ECL Comfort 296 / 310.
EclCongInputDevice S12 This input is not used by the application and
can
therefore be used as a congurable input
.
Requires ECA
32 module in ECL Comfort 296 / 310
.
EclCongInputDevice S13 This input is not used by the application and
can
therefore be used as a congurable input
.
Requires ECA
32 module in ECL Comfort 296 / 310
.
EclMBusDevice volume_ow
These channels are accessible in the relevant
heat
meter, which is connected via M-bus.
ow_temperature
volume
EclMBusDevice volume_ow
These channels are accessible in the relevant
heat
meter, which is connected via M-bus.
ow_temperature
volume
energy
return_temperature
© Danfoss | 2017.01 | 7
VI.HX.I2.02
Operating guide ECL Portal API
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.
7.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.
7.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 specied 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 rst 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.
7.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 specied 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.
8 | © Danfoss| 2017.01
VI.HX.I2.02
Operating guide ECL Portal API
{
“tracking”: {
“serverRequestId”: “0af3a240-0a36-45ae-b8af-9e24f52103eb”,
“from”: “2013-10-29T09:40:45.318+01:00”,
“direction”: “reverse”,
“page”: 1,
“pageSize”: 1000,
“resultReadings”: 1000,
“totalReadings”: 69346,
“totalPages”: 70
},
“data”: [{
“externalDeviceId”: “cfbd9943-9e49-4d19-a052-6424de7041e8”,
“readings”: [{
“id”: 124280485,
“timestamp”: “2013-10-29T07:45:00.0Z”,
“receivedTime”: “2013-10-29T08:00:04.55Z”,
“manualEntry”: false,
“value1”: 192,
“value2”: 48.09,
“value3”: 90,
“value4”: 192,
“value5”: 28.5,
“value6”: 192,
“value7”: 50,
“value8”: 192,
“value9”: 0,
“value10”: 0
},
{
“id”: 124280484,
“timestamp”: “2013-10-29T07:30:00.0Z”,
“receivedTime”: “2013-10-29T08:00:04.52Z”,
“manualEntry”: false,
“value1”: 192,
“value2”: 48.09,
“value3”: 90,
“value4”: 192,
“value5”: 28.5,
“value6”: 192,
“value7”: 50,
“value8”: 192,
“value9”: 0,
“value10”: 0
} ]
}]
}
The rst “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 specied time in the specied direction, the data eld 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.
© Danfoss | 2017.01 | 9
VI.HX.I2.02
Operating guide ECL Portal API
{
“tracking”: {
“serverRequestId”: “07c49346-aa90-4e45-9f20-610931d5887e”,
“from”: “2014-04-01T12:05:32.430+02:00”,
“direction”: “reverse”,
“page”: 1,
“pageSize”: 1,
“resultReadings”: 14
},
“data”: [{
“externalDeviceId”: “5a84dbcc-a9c0-474f-9c12-5db4884fc6ed”,
“readings”: [{
“id”: 79779710,
“timestamp”: “2012-10-04T02:15:00.0Z”,
“receivedTime”: “2014-04-01T10:00:52.293Z”,
“manualEntry”: false,
“value1”: -1.25,
“value2”: -9.46,
“value3”: 26.17,
“value4”: 26.66,
“value5”: -24.21,
“value6”: 45.84,
“value7”: 17.8,
“value8”: 40.24,
“value9”: 10,
“value10”: 50.83,
“value11”: 30,
“value12”: 0
}]
}]
}
The associated log extracted as an Excel le 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 dierence, 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.
8.0 Master data service
This section describes what the master data service can be used for.
In this rst 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.
8.1 getEclMasterData request parameters
Parameter Description Example
serverCode Part of identication cf. section 5 on security. CompanyA
eclSerial Part of identication cf. section 5 on security. 123456792
eclAccessCode Part of identication 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
10 | © Danfoss| 2017.01
VI.HX.I2.02
Operating guide ECL Portal API
8.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
8.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
8.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 296 / 310, 230 V”,
“hardwareVersion”: “A”,
“softwareBuild”: “7232”,
“hardwareProductionTime”: “3.2010”,
“rmwareVersion”: “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]
}
}
© Danfoss | 2017.01 | 11
VI.HX.I2.02
Operating guide ECL Portal API
8.2.2 Master data
The following basic master data is also returned with the response for the actual ECL controller.
8.3 getEclMasterData response
The following information is returned in the response from the server for reasons of traceability.
Element Description Example
application Which application the ECL controller
is running.
A376.1
applicationVersion Version of the application 4.00
hardwareModel Hardware model number ECL 296 / 310, 230 V
hardwareVersion Hardware version A
softwareBuild * Software build number 7232
hardwareProductionTime Hardware production time 3.2010
rmwareVersion Firmware version number 1.48
serialNumber Serial number 123456792
createdOnPortal Date when the ECL controller was
created on (rst 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.
12 | © Danfoss| 2017.01
VI.HX.I2.02
Operating guide ECL Portal API
Element Description Example
type Species the type of device. Possible results are “EclLogDevice”,
“EclCongInputDevice” 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
EclCongInputDevices 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 dierent
possibilities, so they will not be mentioned here.
A376.1 example a
congInputType
Possible values are:
0-10V ADCPt 1000
-0-10V ADC
-Digital
-Flow switch
-Pulse
-Frequency
If it is an unknown type, “7” is returned.
For EclCongInputDevices only.
congInputDenedMaxValue* For EclCongInputDevices of the type 0-10 V ADC only. 4
congInputDenedMinValue ** For EclCongInputDevices of the type 0-10 V ADC only. 2
congInputCircuitCloseText For EclCongInputDevices of the type “Digital” or “Flow switch”
for status “close” only.
Signal OK
congInputCircuitOpenText For EclCongInputDevices of the type “Digital” or “Flow switch”
for status “open” only.
No signal
congInputSensorId For EclCongInputDevices only. Indicates at which input the
congurable 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:
© Danfoss | 2017.01 | 13
VI.HX.I2.02
Operating guide ECL Portal API
ABB-02-02 ABB meter
ABB-06-02 ABB DBM
ABB-07-02 ABB OD
ACW-09-04 Actaris meter
ACW-0b-04 Actaris meter
ACW-0b-0c Actaris meter
ACW-0f-04 Actaris meter
ACW-14-07 Actaris meter
AXI-04-04 Axis SKS3
BHG-05-04 Brunata meter
BHG-3d-04 Brunata HGQ
BHG-3d-0c Brunata meter
BHG-3d-16 Brunata meter
DEI-14-02 Deif APM 380
DFS-01-04 Danfoss meter
DFS-01-0c Danfoss meter
DFS-20-04 Danfoss Sonometer 1100 Heat meter
DFS-20-0a Danfoss Sonometer 1100 Cooling meter
DFS-25-07 Hydrometer Hydrus
DFS-2b-04 Danfoss Sonometer 1000
DFS-2b-0c Danfoss meter
DFS-2f-04 Danfoss Sonometer 1100
DFS-41-04 Danfoss Sonometer 500
DFS-43-0c Danfoss M-Cal Compact
DFS-50-04 Danfoss Infocal 6
DFS-52-04 Danfoss Infocal 8
EMH-00-02 EMH KIZ
HYD-20-04 Danfoss Sonometer 1100 Heat meter
HYD-20-0a Danfoss Sonometer 1100 Cooling meter
HYD-20-0c Hydrometer meter
HYD-2b-04 Danfoss Sonometer 1000
HYD-2f-04 Danfoss Sonometer 1100
HYD-2f-0c Hydrometer meter
HYD-50-04 Danfoss Infocal 6
HYD-52-04 Danfoss Infocal 8
HYD-95-02 Hydrometer Hydroport
INV-40-07 Sensus HRI b1
ITR-18-04 Itron meter
KAM-01-02 Kamstrup meter
KAM-01-04 Kamstrup meter
KAM-01-0c Kamstrup Multical III
KAM-02-04 Kamstrup Multical 401
KAM-07-04 Kamstrup meter
KAM-07-0c Kamstrup meter
KAM-08-04 Kamstrup meter
KAM-08-0c Kamstrup Multical 601
KAM-0b-04 Kamstrup Multical 402
KAM-0b-0c Kamstrup meter
KAM-0f-04 Kamstrup meter
KAM-0f-0c Kamstrup Multical 801
KAM-0f-16 Kamstrup meter
KAM-11-04 Kamstrup meter
KAM-11-0c Kamstrup meter
KAM-15-04 Kamstrup meter
KAM-1b-16 Kamstrup Multical 21
KAM-1c-04 Kamstrup Multical 602
LDR-01-02 Unknown meter
LSE-10-04 Landis & Staefa electronic meter
LUG-02-04 Landis & Gyr
LUG-04-04 Landis & Gyr meter
REL-41-07 Relay meter
UNKNOWN Label for unknown M-bus meter type
SEN-0e-04 Sensus meter
SEN-52-07 Sensus meter
SVM-30-0c Svensk Värmemätning SVM meter
WZG-03-07 Neumann & Co. Wasserzähler meter
14 | © Danfoss| 2017.01
VI.HX.I2.02
Operating guide ECL Portal API
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.
Element Description Example
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 Species 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
© Danfoss | 2017.01 | 15
VI.HX.I2.02
Operating guide ECL Portal API
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 EclCongInput 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 specied.
For EclMBusDevices, the channel is named on the basis of what the M-bus meter says it is.
The name therefore depends on the specic meter type being used.
Possible names are:
-power
-return_temperature
-temperature_dierence
-voltage
-volume_ow
-volume
-current
-energy
-ow_temperature
-on_time
-operating_time
-status
The list of possible names may be extended in future if new M-bus meters make this necessary.
16 | © Danfoss| 2017.01
VI.HX.I2.02
Operating guide ECL Portal API
Examples of ECL log devices from master data: ECL log
{
“type”: “EclLogDevice”,
“externalDeviceId”: “e82977-bf82-40-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: Congurable input
{
“type”: “EclCongInputDevice”,
“externalDeviceId”: “c4c3e66a-940f-4943-a058-60577ea6fea5”,
“name”: “S7”,
“active”: true,
“createdOnPortal”: “2012-11-09T06:30:38.109Z”,
“lastRead”: “2013-10-23T08:57:00.139Z”,
“congInputType”: “Pt 1000”,
“congInputSensorId”: “S7”,
“channels”: [{
“name”: “S7”,
“readingValueIndex”: 1,
“unit”: “degree_celsius”
}]
}
© Danfoss | 2017.01 | 17
VI.HX.I2.02
Operating guide ECL Portal API
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_ow”,
“readingValueIndex”: 2,
“unit”: “cubic_metre_per_hour”,
“mbusChannelType”: “VOLUME_FLOW”,
“mbusSubUnit”: 0
},
{
“name”: “ow_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.
8.4 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 – Bad request, typically because a parameter is missing.
• 401 – Unauthorised, i.e. the server code or third party code is not correct.
• 404 – ECL not found
• 500 – Other unknown error
9.0 Readings
This section describes what the readings service can be used for.
In this rst 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.
18 | © Danfoss| 2017.01
VI.HX.I2.02
Operating guide ECL Portal API
9.1 getReadings Request
Parameter Description Example
serverCode Part of identication cf. section 5.3 on
security.
CompanyA
eclSerial Part of identication cf. section 5.3 on
security.
123456792
eclAccessCode Part of identication 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 specic 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 Species 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 rst 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 specic device.
https://{host}/readings/{version}/{eclSerial}?serverCode={serverCode}&eclAccessCode={eclAccessCode}&externalDeviceId={extern
alDeviceId}
https://eclwebapi.danfoss.dk/readings/v1/123456792?serverCode=FirmaA&eclAccessCode=Kode5&externalDeviceId= c0f6563e-
2bd0-4514-9539-db2c0c700d78
© Danfoss | 2017.01 | 19
VI.HX.I2.02
Operating guide ECL Portal API
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 specic device from a given date and back in time.
https://{host}/readings/{version}/{eclSerial}?serverCode={ser verCode}&eclAccessCode={eclAccessCode}& externalDeviceId={external
DeviceId}&from={from}&pageSize={pageSize}&page=1
Example of request for data from a specic device from a given date and ahead in time.
https://{host}/readings/{version}/{eclSerial}?serverCode={serverCode}&eclAccessCode={eclAccessCode}&externalDeviceId={extern
alDeviceId}&direction=forward&from={from}&pageSize={pageSize}&page=1
If there is no data in the database for the specied time, the API will deliver the next set of data in the specied direction (forward/reverse).
9.2 getReadings Response
As a response to a reading request, one tracking object and one data object are returned.
Tracking object:
Element Description Example
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 specied for the response on page 1, so that the rows for each page are not counted again. Also specied only if externalDeviceId is
dierent from * (as there is no support anyway for paging when submitting requests to several devices simultaneously).
20 | © Danfoss| 2017.01
VI.HX.I2.02
Operating guide ECL Portal API
Data object
Element Description Example
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.
Element Description Example
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 EclCongInput 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 elds 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 – Bad request, typically because a parameter is missing or incorrectly formatted.
• 401 – Unauthorised, i.e. the server code or third party code is not correct.
• 404 – ECL or device not found
• 500 – Other unknown error
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…]
}
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
  • Page 1 1
  • Page 2 2
  • Page 3 3
  • Page 4 4
  • Page 5 5
  • Page 6 6
  • Page 7 7
  • Page 8 8
  • Page 9 9
  • Page 10 10
  • Page 11 11
  • Page 12 12
  • Page 13 13
  • Page 14 14
  • Page 15 15
  • Page 16 16
  • Page 17 17
  • Page 18 18
  • Page 19 19
  • Page 20 20
  • Page 21 21
  • Page 22 22
  • Page 23 23
  • Page 24 24
  • Page 25 25
  • Page 26 26
  • Page 27 27
  • Page 28 28
  • Page 29 29
  • Page 30 30
  • Page 31 31
  • Page 32 32
  • Page 33 33
  • Page 34 34
  • Page 35 35
  • Page 36 36
  • Page 37 37
  • Page 38 38
  • Page 39 39
  • Page 40 40

Danfoss ECL Portal API Operating instructions

Danfoss
Brand
Danfoss
Model
ECL Portal API
Type
Operating instructions
Download PDF
report

Ask a question and I''ll find the answer in the document

Finding information in a document is now easier with AI

Related papers

Other documents