API endpoints

Basic information (/api)

The /api endpoint allows you to get basic information from the device.

Note

Your application can use this endpoint to see if your integration is designed to work with this version of the API. You can validate your support based on the combination of product_type and api_version. Datapoints in this endpoint that are currently available won’t change, but make sure your application can accept new datapoints for future updates.

Data

Type

Description

product_type

string

The product type, see Supported devices. Make sure your application can handle other values for future products.

product_name

string

A fixed, user-friendly name. This name is not the same that is set by the user in the app.

serial

string

Serial, also the MAC address. Consists of 12 hexadecimal values.

firmware_version

string

The current firmware version. Make sure your application can handle other version formats. See Versioning and updates

api_version

string

The current api version, currently ‘v1’

Example

<Request>
GET http://{IP address}/api HTTP/1.1

<Response>
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <length>

{
    "product_type": "HWE-P1",
    "product_name": "P1 Meter",
    "serial": "3c39e7aabbcc",
    "firmware_version": "2.11",
    "api_version": "v1"
}

Recent measurement (/api/v1/data)

The /api/v1/data endpoint allows you to get the most recent measurement from the device.

Datapoints

Data

Type

Available for

Description

smr_version

Number

HWE-P1

The DSMR version of the smart meter

meter_model

String

HWE-P1

The brand indification the smart meter

wifi_ssid

String

HWE-P1
HWE-WTR
SDM630-wifi
SDM230-wifi

The Wi-Fi network that the meter is connected to

wifi_strength

Number

HWE-P1
HWE-WTR
SDM630-wifi
SDM230-wifi

The strength of the Wi-Fi signal in %

total_power_import_t1_kwh

Number

HWE-P1
SDM230-wifi
SDM630-wifi

The power usage meter reading for tariff 1 in kWh

total_power_import_t2_kwh

Number

HWE-P1

The power usage meter reading for tariff 2 in kWh

total_power_export_t1_kwh

Number

HWE-P1
HWE-SKT
SDM230-wifi
SDM630-wifi

The power feed-in meter reading for tariff 1 in kWh

total_power_export_t2_kwh

Number

HWE-P1

The power feed-in meter reading for tariff 2 in kWh

active_power_w

Number

HWE-P1
HWE-SKT
SDM230-wifi
SDM630-wifi

The total active usage in Watts

active_power_l1_w

Number

HWE-P1
HWE-SKT
SDM230-wifi
SDM630-wifi

The active usage for fase 1 in Watts

active_power_l2_w

Number, optional

HWE-P1
SDM630-wifi

The active usage for fase 2 in Watts (HWE-P1 returns ‘null’ when connection is single-phase)

active_power_l3_w

Number, optional

HWE-P1
SDM630-wifi

The active usage for fase 3 in Watts (HWE-P1 returns ‘null’ when connection is single-phase)

total_gas_m3

Number, optional

HWE-P1

The gas meter reading in m3 (HWE-P1 returns ‘null’ when no gas meter is connected)

gas_timestamp

Number, optional

HWE-P1

The most recent gas update time stamp structured as YYMMDDhhmmss. (HWE-P1 returns ‘null’ when no gas meter is connected)

active_liter_lpm

Number

HWE-WTR

Active water usage in liters per minute

total_liter_m3

Number

HWE-WTR

Total water usage in cubic meters since installation

Examples

HWE-P1

<Request>
GET http://{IP address}/api/v1/data HTTP/1.1

<Response>
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <length>

{
   "smr_version": 50,
   "meter_model": "ISKRA  2M550T-101",
   "wifi_ssid": "My Wi-Fi",
   "wifi_strength": 100,
   "total_power_import_t1_kwh": 10830.511,
   "total_power_import_t2_kwh": 2948.827,
   "total_power_export_t1_kwh": 1285.951,
   "total_power_export_t2_kwh": 2876.51,
   "active_power_w": -543,
   "active_power_l1_w": -676,
   "active_power_l2_w": 133,
   "active_power_l3_w": 0,
   "total_gas_m3": 2569.646,
   "gas_timestamp": 210606140010
}

HWE-SKT

<Request>
GET http://{IP address}/api/v1/data HTTP/1.1

<Response>
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <length>

{
   "wifi_ssid": "My Wi-Fi",
   "wifi_strength": 100,
   "total_power_import_t1_kwh": 30.511,
   "total_power_export_t1_kwh": 85.951,
   "active_power_w": 543,
   "active_power_l1_w": 676,
}

HWE-WTR

Note

The API for the watermeter can only be used when the watermeter is powered over USB. To save energy, the watermeter only connects to Wi-Fi a couple of times per day when powered with batteries.

<Request>
GET http://{IP address}/api/v1/data HTTP/1.1

<Response>
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <length>

{
   "wifi_ssid": "My Wi-Fi",
   "wifi_strength": 100,
   "total_liter_m3": 123.456,
   "active_liter_lpm": 7.2
}

SDM230-wifi

<Request>
GET http://{IP address}/api/v1/data HTTP/1.1

<Response>
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <length>

{
   "wifi_ssid": "My Wi-Fi",
   "wifi_strength": 100,
   "total_power_import_t1_kwh": 10830,
   "total_power_export_t1_kwh": 1285.951,
   "active_power_w": 640,
   "active_power_l1_w": 640
}

SDM630-wifi

<Request>
GET http://{IP address}/api/v1/data HTTP/1.1

<Response>
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <length>

{
   "wifi_ssid": "My Wi-Fi",
   "wifi_strength": 100,
   "total_power_import_t1_kwh": 10830.511,
   "total_power_export_t1_kwh": 1285.951,
   "active_power_w": -543,
   "active_power_l1_w": -676,
   "active_power_l2_w": 133,
   "active_power_l3_w": 0
}

P1 telegram (/api/v1/telegram)

The /api/v1/telegram endpoint returns the most recent, valid telegram that was given by the P1 meter, therefore this endpoint is only available for the HWE-P1.

  • The telegram validated with its CRC, but not parsed in any form.

  • Note that this endpoint returns plain text instead of formatted JSON, even when an error occours (see Error handling)

Example

<Request>
GET http://{IP address}/api/v1/telegram

<Response>
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: <length>

/ISK5\\\\2M550T-10111-

3:0.2.8(50)
0-0:1.0.0(181106140429W)
0-0:96.1.1(31333631353032362020202020202020)
1-0:1.8.1(10830.511*kWh)
1-0:1.8.2(002948.827*kWh)
1-0:2.8.1(001285.951*kWh)
1-0:2.8.2(002876.514*kWh)
0-0:96.14.0(0002)
1-0:1.7.0(21.100*kW)
1-0:2.7.0(00.000*kW)
0-0:96.7.21(00006)
0-0:96.7.9(00003)
1-0:99.97.0(1)(0-0:96.7.19)(180529135630S)(0000002451*s)
1-0:32.32.0(00003)
1-0:52.32.0(00002)
1-0:72.32.0(00002)
1-0:32.36.0(00001)
1-0:52.36.0(00001)
1-0:72.36.0(00001)
0-0:96.13.0()
1-0:32.7.0(236.0*V)
1-0:52.7.0(232.6*V)
1-0:72.7.0(235.1*V)
1-0:31.7.0(002*A)
1-0:51.7.0(000*A)
1-0:71.7.0(000*A)
1-0:21.7.0(00.000*kW)
1-0:41.7.0(00.033*kW)
1-0:61.7.0(00.132*kW)
1-0:22.7.0(00.676*kW)
1-0:42.7.0(00.000*kW)
1-0:62.7.0(00.000*kW)
0-1:24.1.0(003)
0-1:96.1.0(4730303339303031373030343630313137)
0-1:24.2.1(210606140010W)(02569.646*m3)
!1F28

State (/api/v1/state)

The /api/v1/state endpoint returns the actual state of the Energy Socket. This endpoint is only available for the HWE-SKT.

This endpoint accepts GET and PUT requests.

  • With GET you will receive the actual state

  • With PUT you can control the state.

Parameters

Data

Type

Description

power_on

bool

The state of the switch. Returns true when the relay is in the ‘on’ state

switch_lock

bool

When set to true, the socket cannot be turned off.

brightness

number

Brightness of LED ring when socket is ‘on’. Value from 0 (0%) to 255 (100%)

Examples

Get actual state

This response tells that the socket is ‘on’, switch-lock is ‘off’ and the brightness of the LED ring is set to maximum.

<Request>
GET http://{IP address}/api/v1/state HTTP/1.1

<Response>
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <length>

{
   "power_on": true,
   "switch_lock": false,
   "brightness": 255
}

Turn on socket

<Request>
PUT http://{IP address}/api/v1/state HTTP/1.1
Content-Type: application/json
Content-Length: <length>
{
   "power_on": true
}

<Response>
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <length>

{
   "power_on": true
}

Turn on switch-lock

After enabling switch_lock, the socket is ‘on’ and cannot be turned off until switch_lock is disabled.

<Request>
PUT http://{IP address}/api/v1/state HTTP/1.1
Content-Type: application/json
Content-Length: <length>
{
   "switch_lock": true
}

<Response>
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <length>

{
   "switch_lock": true
}

Set multiple parameters

You can configure multiple parameters at the same time. In this example.

  • Socket is turned off.

  • Switch-lock is turned off.

  • Brightness is set to 127 (50%).

The order of a combined request does not matter: If switch-lock was on, the socket will still turn off. The complete state has to make sense; It is not possible to set power_on to false and switch_lock to true. See (see Error handling) for more details.

<Request>
PUT http://{IP address}/api/v1/state HTTP/1.1
Content-Type: application/json
Content-Length: <length>
{
   "power_on": false,
   "switch_lock": false,
   "brightness": 127
}

<Response>
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <length>

{
    "switch_lock": false,
    "power_on": false,
    "brightness": 127
}