homewizard energy api

HomeWizard Energy API

HomeWizard

Oct 13, 2021

TERMS AND CONDITIONS

1 API Introduction 3

2 Terms and conditions 5

3 First steps 73.1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.2 API endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83.3 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.5 Versioning and updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

i


With the HomeWizard Energy platform, you can get insights in your energy usage. Use the HomeWizard Wi-Fi P1meter to access real-time data directly from your smart meter, the HomeWizard Wi-Fi Energy Socket to get energyinsights from all your devices and the HomeWizard Wi-Fi kWh meter to measure devices such as solar panels. Withthe open API you can integrate the data directly into your system of choice.

TERMS AND CONDITIONS 1

https://www.homewizard.nl/p1-meter

https://www.homewizard.nl/p1-meter

https://www.homewizard.nl/energy-socket

https://www.homewizard.nl/kwh-meter


2 TERMS AND CONDITIONS

CHAPTER

ONE

API INTRODUCTION

The HomeWizard Wi-Fi P1 meter, Wi-Fi Energy Socket and the Wi-Fi kWh meter (‘device’) have a local API to retrievethe most recent measurements or control the device. You can access this API as long as you are connected to the same(Wi-Fi) network as the device and the API is enabled in the HomeWizard Energy app. This API is intended to connectyour device to your own automation, home automation or graphing system. It is not possible to retrieve data historywith the local API, as this is not stored on the device itself.

3


4 Chapter 1. API Introduction

CHAPTER

TWO

TERMS AND CONDITIONS

1. License: The HomeWizard Energy API is licensed, not sold. HomeWizard grants the user a non-exclusivelicense (with no right to sub-license) to the HomeWizard Energy API for personal, non-commercial use.

2. Usage The user may not directly or indirectly use the HomeWizard Energy API to sell, lease, loan or generate arevenue from a product, system or software using the API

3. Support: The usage of the HomeWizard Energy API is officially supported by HomeWizard, however Home-Wizard can not supply customer service regarding the implementation of the API in your own or third partyapplications.

5


6 Chapter 2. Terms and conditions

CHAPTER

THREE

FIRST STEPS

To understand the basics of the API, you can read the Getting Started guide. Read API endpoints to know all about thedatapoints that are available.

More advanced topics: Error handling | Discovery | Versioning and updates

3.1 Getting Started

3.1.1 Connect your device to Wi-Fi

You have to do this with the HomeWizard Energy app. Make sure to connect your energy device with the same networkas the device that makes use of the API.

3.1.2 Enabling the API

To access the data from an Energy device, you have to enable the API. You can do this in the HomeWizard Energy app(version 1.5.0 or higher). Go to Settings > Meters > Your meter, and turn on Local API.

3.1.3 Getting the data

After Enabling the API , you can try to read some data from your device.

1. Find the IP addres of your meter (you can do this programmatically with Discovery).

2. In your internet browser, open http://{IP_ADDRESS}/api/v1/data.

3. If everything is set up correctly, you should now see some text. This is the most recent measurement formattedas JSON. You can use a tool such as JSON Parser Online to get a structured version of the result.

To understand each value, please read API endpoints.

7

https://www.homewizard.nl/energy

https://www.homewizard.nl/energy

https://en.wikipedia.org/wiki/JSON

http://json.parser.online.fr


3.1.4 Supported devices

The supported devices are listed below. The device type is used as identifier within the API.

Device Device typeWi-Fi P1 meter HWE-P1Wi-Fi Energy Socket HWE-SKTWi-Fi kWh meter (1 phase) SDM230-wifiWi-Fi kWh meter (3 phase) SDM630-wifi

3.1.5 Data update frequency

The /api/v1/data endpoint always returns the most recent measurement. The update frequency depends on the deviceand, in case of the HWE-P1, the smart meter that it is connected to. With a SMR 5.0 meter, this is every second forpower and every 5 minutes for gas. If the smart meter version is lower than SMR 5.0, this is every 10 seconds for powerand every 60 minutes for gas. You can find the SMR version of your smart meter on the smart meter itself or via the/api/v1/data endpoint. There is no limit to the time between each request on the local API, however, we advise not toretrieve data more often than every 500ms.

3.2 API endpoints

3.2.1 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 theAPI. You can validate your support based on the combination of product_type and api_version. Datapoints inthis endpoint that are currently available won’t change, but make sure your application can accept new datapoints forfuture updates.

Data Type Descriptionproduct_type string The product type, see Supported devices. Make sure your application can handle other

values for future products.prod-uct_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_versionstring The current firmware version. Make sure your application can handle other version formats.

See Versioning and updatesapi_version string The current api version, currently ‘v1’

Example

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

<Response>HTTP/1.1 200 OKContent-Type: application/json

(continues on next page)

8 Chapter 3. First steps


(continued from previous page)

Content-Length: <length>

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

}

3.2.2 Recent measurement (/api/v1/data)

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

3.2. API endpoints 9


Datapoints

Data Type Available for Descriptionsmr_version Num-

berHWE-P1 The SMR version of the meter

me-ter_model

String HWE-P1 The brand and type of the meter

wifi_ssid String HWE-P1, HWE-SKT, SDM230-wifi,SDM630-wifi

The Wi-Fi network that the meter is connected to

wifi_strength Num-ber

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

The strength of the Wi-Fi signal in %

to-tal_power_import_t1_kwh

Num-ber


The power usage meter reading for tariff 1 in kWh

to-tal_power_import_t2_kwh

Num-ber

HWE-P1 The power usage meter reading for tariff 2 in kWh

to-tal_power_export_t1_kwh

Num-ber


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

to-tal_power_export_t2_kwh

Num-ber

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

ac-tive_power_w

Num-ber


The total active usage in Watts

ac-tive_power_l1_w

Num-ber


The active usage for fase 1 in Watts

ac-tive_power_l2_w

Num-ber,op-tional

HWE-P1, SDM630-wifi

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

ac-tive_power_l3_w

Num-ber,op-tional

HWE-P1, SDM630-wifi

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

to-tal_gas_m3

Num-ber,op-tional

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

gas_timestamp Num-ber,op-tional

HWE-P1 The most recent gas update time stamp structured as YYM-MDDhhmmss. (HWE-P1 returns ‘null’ when no gas meteris connected)



Examples

HWE-P1

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

<Response>HTTP/1.1 200 OKContent-Type: application/jsonContent-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

}

SDM230-wifi



{"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


<Response>(continues on next page)




HTTP/1.1 200 OKContent-Type: application/jsonContent-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

}

3.2.3 P1 telegram (/api/v1/telegram)

The /api/v1/telegram endpoint returns the most recent, valid telegram that was given by the P1 meter, thereforethis 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 Errorhandling)

Example

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

<Response>HTTP/1.1 200 OKContent-Type: text/plainContent-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

3.2.4 State (/api/v1/state)

The /api/v1/state endpoint returns the actual state of the Energy Socket. This endpoint is only available for theHWE-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 Descriptionpower_on bool The state of the switch. Returns true when the relay is in the ‘on’ stateswitch_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>(continues on next page)




HTTP/1.1 200 OKContent-Type: application/jsonContent-Length: <length>

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

}

Turn on socket

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

}


{"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.1Content-Type: application/jsonContent-Length: <length>{"switch_lock": true

}


{"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 completestate 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.1Content-Type: application/jsonContent-Length: <length>{"power_on": false,"switch_lock": false,"brightness": 127

}


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

}

3.3 Discovery

The energy devices can be automaticly discovered on your network, the method used for this is Multicast DNS (mDNS),but is sometimes called Zeroconf or Bonjour. Your application can use this technology to discover the device(s)without the user having to enter the IP address.

3.3.1 Example scan

The device can be found on the _hwenergy._tcp domain.

$ dns-sd -B _hwenergy._tcp .Browsing for _hwenergy._tcpDATE: ---Wed 13 Oct 2021---14:51:03.565 ...STARTING...Timestamp A/R Flags if Domain Service Type Instance Name14:51:03.566 Add 3 7 local. _hwenergy._tcp. energysocket-AABBCC14:51:03.566 Add 3 7 local. _hwenergy._tcp. energysocket-DDEEFF14:51:03.566 Add 3 7 local. _hwenergy._tcp. energysocket-00112214:51:03.566 Add 3 7 local. _hwenergy._tcp. p1meter-33445514:51:03.566 Add 3 7 local. _hwenergy._tcp. energymeter-667788

The hostname is formatted as <product-name>-<last 6 characters of serial>, so devices with serialAABBCCDDEEFF the hostname is as following:

3.3. Discovery 15

https://www.ionos.com/digitalguide/server/know-how/multicast-dns/


Device Example hostnameP1 meter p1meter-DDEEFFEnergy Socket energysocket-DDEEFFkWh meter (single phase) kwhmeter-DDEEFFkWh meter (three phase) kwhmeter-DDEEFF

3.3.2 TXT records

A discovery response contains some extra data that can be used to improve the setup in your application.

Data Descriptionapi_enabled ‘0’ or ‘1’, reflects if the API is enabled (1 means enabled)path Fixed to ‘/api/v1’. Can be used to validate that your application supports this device and API versionserial Serial, also the MAC address. Consists of 12 hexadecimal valuesprod-uct_name

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

prod-uct_code

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

3.4 Error handling

When you perform an invalid request or something went wrong, the API will respond with an error message. You haveto check if the HTTP status code returns 200 OK before parsing the result. If you use an endpoint that returns JSON,you also will receive an object with some error information.

3.4.1 Error codes

The predefined error codes are as follows:

Code Description2 BODY_CONTAINS_INVALID_JSON7 INVALID_VALUE_FOR_PARAMETER8 PARAMETER_IS_NOT_MODIFIABLE201 REQUEST_TO_LONG202 API_DISABLED901 INTERNAL_ERROR

3.4.2 Example response

API was disabled

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

<Response>HTTP/1.1 400 Bad Request





Content-Type: application/jsonContent-Length: <length>

{"error": {"id": 202,"description": "API not enabled"

}}

Invalid JSON

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

}


{"error": {"id": 2,"description": "Body contains invalid json"

}}

Invalid value

<Request>PUT http://{IP address}/api/v1/state HTTP/1.1Content-Type: application/jsonContent-Length: <length>{"brightness": 500

}


{"error": {"id": 7,"description": "brightness value limited to 0-255"

}}

3.4. Error handling 17


Turn off socket when switch-lock is enabled

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

}


{"error": {"id": 8,"description": "power_on cannot be turned off when switch_lock is on"

}}

3.5 Versioning and updates

3.5.1 Firmware updates

The energy devices are updated automaticly when a new version is available. The versioning scheme is X.YY (eg.2.03).

3.5.2 API version

The API is currently fixed to version v1. The version is updated when the a new version contains (possible) breakingchanges. The version will be unchanged when non breaking changes, such as new features, new endpoints or stabilityimprovements are introduced.


homewizard energy api

Documents