De P1 meter beschikt over een lokale API om data op te vragen die op dat moment gemeten wordt. Je kunt deze API benaderen zolang je verbonden bent met hetzelfde (Wi-Fi) netwerk als de P1 meter. Deze API is bedoeld om je P1 meter aan een eigen automatisering, domotica of grafieken systeem te koppelen. Het is niet mogelijk om data geschiedenis op te halen met de lokale API. 



Voorwaarden

1. Licentie:
De HomeWizard P1 meter API wordt in licentie gegeven, niet verkocht. HomeWizard verleent de gebruiker een niet-exclusieve licentie (zonder recht op sublicentie) om slechts één exemplaar van de HomeWizard P1 meter API te gebruiken voor persoonlijk, niet-commercieel gebruik.
2. Gebruik: De gebruiker mag niet direct of indirect de HomeWizard P1 meter API gebruiken om een product, systeem of software te verkopen, leasen, uitlenen of inkomsten te genereren.
3. Support:
Het gebruik van de P1 meter API wordt officieel ondersteund door HomeWizard, maar HomeWizard kan geen klantenservice leveren met betrekking tot de implementatie van de API in uw eigen of applicaties van derden.


Firmware versie

Op gebruik te maken van deze API moet de betreffende HomWizard P1 Meter minimaal van versie 2.11 voorzien zijn. Meer informatie over de versie raadpleeg ; Firmware update


Type aanvraag

De P1 meter ondersteunt 2 methodes om data op te opvragen. Je kunt de data gestructureerd als JSON opvragen onder data of je kan de ruwe data vanuit de slimme meter opvragen onder telegram.De API biedt toegang tot de meest recente update die is aangeboden door de slimme meter. 


Frequentie van gegevensupdate

De snelheid hiervan is afhankelijk van de SMR versie van jouw slimme meter. Bij SMR 5.0 is dit elke seconde voor stroom en elke 5 minuten voor gas. Bij lager dan SMR 5.0 is dit elke 10 seconden voor stroom en elke 60 minuten voor gas. Je vindt de SMR versie van jouw slimme meter op je slimme meter of via de API. Er is geen limiet op het aantal requests op de lokale API, echter adviseren wij om niet vaker data op te halen dan elke 500ms.


Discovery

De energy producten zijn middels middels 'mDNS' te vinden. Dit maakt het voor een integratie makkelijk om een product te vinden zonder dat hiervoor toegang tot de router nodig is, om het IP adres te achterhalen. Deze technologie wordt vaak ook bij naam genoemd als 'Bonjour' of 'Zeroconf', als is de techniek hierachter niet exact hetzelfde.


⚠️ Het is belangrijk dat mDNS is ingeschakeld op de router.


De energy producten zijn te vinden op het domein _hwenergy._tcp. Om dit gebruik te testen is in 'terminal/powershell' het volgende commando te gebruiken. Er zijn ook apps beschikbaar zoals Discovery voor iPhone of Service Browser voor Android.


$ HASS dns-sd -Z _hwenergy._tcp
Browsing for _hwenergy._tcp
DATE: ---Thu 17 Dec 2020---
15:56:48.755  ...STARTING...

To direct clients to browse a different domain, substitute that domain in place of '@'
lb._dns-sd._udp                  PTR     @
_hwenergy._tcp                   PTR     p1meter-AABBCC._hwenergy._tcp
p1meter-AABBCC._hwenergy._tcp    SRV     0 0 80 p1meter-AABBCC.local. ; Replace with unicast FQDN of target host
p1meter-AABBCC._hwenergy._tcp    TXT     "api_enabled=1" "path=/api/v1" "serial=<001122AABBCC>" "product_name=P1 meter" "product_type=HWE-P1"

Domain naam resolving

Computers die gebruik kunnen maken van mDNS's domain name resolving, kunnen contact maken met het product via de domain naam: http://p1meter-AABBCC.local/api. Waarbij 'AABBCC' gelijk is aan de laatste 6 tekens van het serienummer. De URL is voor elk apparaat type anders.

  • P1 meter: p1meter-<last_6_serial>.local

Discovery TXT records

Elk mDNS verzoek krijgt een set datapunten mee. Hiermee kan enkele basisinformatie van het product ontdekt worden. De beschikbare datapunten zijn:

  • path (altijd '/api/v1/') Geeft het 'endpoint' aan voor de API. Controleer dit datapunt voordat andere datapunten uitgelezen worden, om zo goed om te kunnen gaan met eventuele toekomstige veranderingen.
  • api_enabled (0 = uitgeschakeld, 1 = ingeschakeld) Geeft aan dat API ingeschakeld is. Dit moet ingeschakeld worden in de app ⚠️ In de P1 meter is deze standaard ingeschakeld. ⚠️ De API is nog in interne beta voor de kWh meter en kan nog niet worden ingeschakeld in de app.
  • product_name (string) Leesbare naam van product, zoals 'P1 meter'. Dit staat niet gelijk aan de naam zoals ingevuld in de app. Deze naam is niet beschikbaar binnen het product.
  • product_type (string) Het product type. Kan gebruikt worden om onderscheid te maken tussen verschillende producten. Op dit moment wordt ondersteund:
  • HWE-P1 (P1 meter))
  • serial (string, 12 karakters) Unieke hexadecimale reeks dat gebruikt kan worden om de verschillende apparaten mee te onderscheiden.

Rest API


Apparaatinformatie opvragen van het product

GET http://{IP address}/api/

Voorbeeldreactie van P1 meter

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

product_type: [String] (constant) Het producttype

product_name: [String] (constant) Naam van product

serial: [String] Serial ID van product

firmware_version: [String] Huidige firmware versie. Er is geen garantie dat dit altijd een 'nummer' is.

api_version: [String] Verwijst naar huidige API versie




Data opvragen van de P1 meter

Met deze HTTP GET data request kun je de data opvragen van een P1 meter.


http://{IP address}/api/v1/data


In bovenstaande request dient bij {IP address} het lokale IP adres ingevuld te worden van de P1 meter waar je data van wilt opvragen. Vervolgens krijg je de onderstaande waardes terug in JSON.

Voorbeeld van een P1 meter data response


HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 476

{
    "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.514,
    "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
}



smr_version: [Number] De SMR versie van de meter
meter_model: [String] Het merk en type indicatie van de slimme meter
wifi_ssid: [String] Het Wi-Fi netwerk waarmee de P1 meter is verbonden
wifi_strength: [Number] De sterkte van het Wi-Fi signaal in %
total_power_import_t1_kwh: [Number] De stroom afname meterstand voor tarief 1 in kWh
total_power_import_t2_kwh: [Number] De stroom afname meterstand voor tarief 2 in kWh
total_power_export_t1_kwh: [Number] De stroom teruglevering meterstand voor tarief 1 in kWh
total_power_export_t2_kwh: [Number] De stroom teruglevering meterstand voor tarief 2 in kWh
active_power_w: [Number] Het huidig gebruik van alle fases gecombineerd in Watt
active_power_l1_w: [Number] Het huidig gebruik voor fase 1 in Watt (indien van toepassing)
active_power_l2_w: [Number] Het huidig gebruik voor fase 2 in Watt (indien van toepassing)
active_power_l3_w: [Number] Het huidig gebruik voor fase 3 in Watt (indien van toepassing)
total_gas_m3: [Number] De gas meterstand in m3
gas_timestamp: [Number] De datum en tijd van de meest recente gas meterstand gestructureerd als YYMMDDhhmmss.



Ruwe data opvragen van de slimme meter (telegram)

Met de API is de meest recente telegram van de slimme meter op te vragen. Deze ruwe data wordt verzonden zonder aanpassingen door de P1 meter.

Deze aanvraag keert ruwe data terug van de slimme meter zonder aanpassingen.


http://{IP address}/api/v1/telegram


In bovenstaande request dient bij {IP address} het lokale IP adres ingevuld te worden van de P1 meter waar je data van wilt opvragen. Vervolgens krijg je via de P1 meter de ruwe telegram van de slimme meter terug.

Onderstaand een voorbeeld van een telegram response. Hoe je deze data moet interpreteren vind je in de officiële P1 companion standaard van Netbeheer Nederland.


/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

Foutafhandeling

Wanneer een ongeldig verzoek gemaakt wordt, zal de API reageren met een foutmelding. De reactiecode zal reageren met een andere waarden dan 200 OK. In dit geval zal in de reactie een 'error' object aanwezig zijn.

Foutmeldingcodes

2 - BODY_CONTAINS_INVALID_JSON (JSON data in verzoek kan niet juist verwerkt worden)

7 - INVALID_VALUE_FOR_PARAMETER (Waarde van verzoek is ongeldig)

8 - PARAMETER_IS_NOT_MODIFIABLE (Waarde kan niet aangepast worden)

201 - REQUEST_TO_LONG (Inhoud van verzoek te lang)

202 - API_DISABLED (API uitgeschakeld in app)

901 - INTERNAL_ERROR (Interne fout)

Voorbeeld 1 - Opvragen of zenden van data bij uitgeschakelde API

GET http://{IP address}/api/v1/data

Voorbeeldreactie

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: <length>

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

Voorbeeld 2 - Ongebruikte of onbekende API endpoint

Wanneer een verzoek wordt gedaan bij een endpoint die niet bestaat, zal het product reageren met de statuscode '404'. Er zal geen JSON meegezonden worden.

GET http://{IP address}/api/niet-bestaande-url

Voorbeeldreactie

HTTP/1.1 404 Not Found
Content-Type: text/html
Content-Length: <length>

This URI does not exists