Referentie Zigbee
Deze pagina beschrijft hoe ZiggyMeter er in een Zigbee-netwerk uitziet: endpoints, clusters en attributen. Hoe u aan een netwerk deelneemt, staat bij Zigbee instellen.
Over Zigbee
Zigbee is een energiezuinig draadloos meshprotocol voor IoT-apparaten, gebaseerd op IEEE 802.15.4 op 2,4 GHz. Berichten springen via routers op netvoeding, en juist daardoor werkt het in meterkasten en kelders waar een directe Wi-Fi-verbinding het niet zou redden.
ZiggyMeter neemt deel als end device: het routeert niet voor anderen en het slaapt tussen uitlezingen.
Vereisten
- Een Zigbee-coördinator — een USB-adapter of hub die het netwerk aanmaakt en beheert
- Software die clusters uit Zigbee Cluster Library v8 begrijpt
Alle clusters die ZiggyMeter aanbiedt zijn standaard. Er zijn geen clusters die specifiek zijn voor de fabrikant, dus de meeste integraties werken direct, zonder eigen device handler.
Endpoints
Endpoint 1 — apparaat
Identificatie van het apparaat en basisstatus. De schakelaar On/Off omzetten zet Wi-Fi aan of uit.
Ingangsclusters
| Cluster-ID | Naam |
|---|---|
0x0000 | Basic |
0x0001 | Power Configuration |
0x0003 | Identify |
0x0006 | On/Off |
0x0402 | Temperature Measurement |
Uitgangsclusters
| Cluster-ID | Naam |
|---|---|
0x0003 | Identify |
0x0019 | OTA Upgrade |
Endpoint 2 — meter
Metergegevens. De schakelaar On/Off omzetten start een uitlezing van de meter.
Ingangsclusters
| Cluster-ID | Naam |
|---|---|
0x0006 | On/Off |
0x0702 | Simple Metering |
0x0B04 | Electrical Measurement |
Geen uitgangsclusters.
Cluster Metering (0x0702)
Twee attributen, allebei standaard. Eigen commando's zijn niet nodig.
| Attribuut-ID | Naam |
|---|---|
0x0000 | Current Summation Delivered |
0x0001 | Current Summation Received |
Current Summation Received wordt alleen bijgewerkt als de meter die waarde levert.
Cluster Electrical Measurement (0x0B04)
Elektrische parameters. Het cluster declareert de hele verzameling attributen hieronder, maar slechts drie ervan — Active power (0x050B), RMS current (0x0508) en RMS voltage (0x0505) — kunnen met een meterwaarde worden gevuld en aan een coördinator worden gemeld. Zie Beschikbare doelen.
Welke daarvan werkelijk worden bijgewerkt, hangt vervolgens af van de meter: een eenfasige meter vult uiteraard nooit fase B en C in.
Sommige Zigbee-integraties tonen niet elk attribuut, ook wanneer het apparaat het correct bijwerkt. Bekijk de ruwe clusterwaarden in de gereedschappen van uw coördinator voordat u concludeert dat het apparaat niets meldt.
| Attribuut-ID | Naam |
|---|---|
0x0300 | AC frequency |
0x0304 | Total active power |
0x0305 | Total reactive power |
0x0306 | Total apparent power |
0x0501 | Line current (phase A) |
0x0502 | Active current (phase A) |
0x0503 | Reactive current (phase A) |
0x0505 | RMS voltage (phase A) |
0x0508 | RMS current (phase A) |
0x050B | Active power (phase A) |
0x050E | Reactive power (phase A) |
0x050F | Apparent power (phase A) |
0x0901 | Line current (phase B) |
0x0902 | Active current (phase B) |
0x0903 | Reactive current (phase B) |
0x0905 | RMS voltage (phase B) |
0x0908 | RMS current (phase B) |
0x090B | Active power (phase B) |
0x090E | Reactive power (phase B) |
0x090F | Apparent power (phase B) |
0x0A01 | Line current (phase C) |
0x0A02 | Active current (phase C) |
0x0A03 | Reactive current (phase C) |
0x0A05 | RMS voltage (phase C) |
0x0A08 | RMS current (phase C) |
0x0A0B | Active power (phase C) |
0x0A0E | Reactive power (phase C) |
0x0A0F | Apparent power (phase C) |
Hoe meterwaarden attributen worden
De meter gebruikt OBIS-codes, Zigbee clusterattributen. ZiggyMeter houdt daartussen een toewijzingstabel bij.
Elk item in die tabel is een OBIS-code plus een toewijzings-ID: vier bytes hexadecimaal, waarbij de eerste twee het cluster zijn en de laatste twee het attribuut.
| OBIS | Toewijzings-ID | Cluster / attribuut | Betekenis |
|---|---|---|---|
1-0:1.8.0 | 07020000 | 0x0702 / 0x0000 | Current summation delivered |
1-0:2.8.0 | 07020001 | 0x0702 / 0x0001 | Current summation received |
1-0:1.7.0 | 0b04050b | 0x0B04 / 0x050B | Active power, fase A |
1-0:11.7.0 | 0b040508 | 0x0B04 / 0x0508 | RMS current, fase A |
1-0:12.7.0 | 0b040505 | 0x0B04 / 0x0505 | RMS voltage, fase A |
Wijzig de tabel wanneer uw meter een code gebruikt die de standaardwaarden niet dekken — bijvoorbeeld een meter die zijn spanning onder een modelgebonden code meldt, waardoor de waarde wel in een uitlezing staat maar nooit bij uw coördinator komt.
Een toewijzing wijzigen
Doe dat in de webinterface. Open Meter → Readings en dubbelklik op het veld Mapping in de rij die u wilt wijzigen; het veld wordt een keuzelijst met de beschikbare Zigbee-doelen. Kies er een en het wordt meteen opgeslagen — er is geen aparte stap om op te slaan.
INFO
Alleen OBIS-codes die in een uitlezing voorkomen kunnen worden toegewezen, want de tabel is de uitlezing. Staat de gewenste rij er niet bij, lees dan eerst de meter uit.
Beschikbare doelen
De keuzelijst biedt zes mogelijkheden, en niet meer. Alleen deze vijf paren van cluster en attribuut kunnen aan een OBIS-code worden toegewezen — de overige attributen hierboven bestaan wel op de clusters, maar zijn geen doel voor toewijzing.
| Keuze in de lijst | Toewijzings-ID | Cluster / attribuut |
|---|---|---|
| Unassigned | 00000000 | — (de waarde wordt uitgelezen, maar niet via Zigbee gepubliceerd) |
| Summation Delivered [kWh] | 07020000 | 0x0702 / 0x0000 |
| Summation Received [kWh] | 07020001 | 0x0702 / 0x0001 |
| Active Power [kW] | 0b04050b | 0x0B04 / 0x050B |
| Current RMS [A] | 0b040508 | 0x0B04 / 0x0508 |
| Voltage RMS [V] | 0b040505 | 0x0B04 / 0x0505 |
WARNING
Elk doel kan maar door één OBIS-code tegelijk worden gebruikt. Wijst u een doel toe dat een andere rij al heeft, dan verhuist het: die andere rij gaat automatisch terug naar Unassigned. Controleer de tabel na een wijziging als u meerdere rijen omzet.
Er wordt vergeleken op de volledige OBIS-code, inclusief tarief (1-0:15.8.0*101). De API accepteert ook een vergelijking op de korte code (15.8.0).
Bewerken via de API
/api/v1/zigbee/map leest en schrijft dezelfde tabel, wat handig is om meerdere apparaten identiek in te richten. Het is een alternatief voor de webinterface, niet de normale route — een POST vervangt de hele tabel en past de regel “één doel, één code” niet voor u toe.
Firmware draadloos
Endpoint 1 biedt het standaardcluster OTA Upgrade (0x0019), dus elke coördinator met ondersteuning voor Zigbee OTA kan het apparaat bijwerken. Er zijn kant-en-klare indexbestanden gepubliceerd voor Zigbee2MQTT en voor zigpy/ZHA: