Zigbee-Referenz
Diese Seite beschreibt, wie ZiggyMeter in einem Zigbee-Netz aussieht: Endpunkte, Cluster und Attribute. Wie Sie einem Netz beitreten, steht unter Zigbee einrichten.
Über Zigbee
Zigbee ist ein stromsparendes drahtloses Mesh-Protokoll für IoT-Geräte, das auf IEEE 802.15.4 bei 2,4 GHz läuft. Nachrichten springen über netzbetriebene Router weiter, und genau das lässt es in Zählerschränken und Kellern funktionieren, wo eine direkte WLAN-Verbindung versagen würde.
ZiggyMeter tritt als End Device bei: Es leitet nichts für andere weiter und schläft zwischen den Auslesungen.
Voraussetzungen
- Ein Zigbee-Koordinator — ein USB-Adapter oder Hub, der das Netz aufbaut und verwaltet
- Software, die Cluster der Zigbee Cluster Library v8 versteht
Alle Cluster, die ZiggyMeter bereitstellt, sind Standard. Es gibt keine herstellerspezifischen Cluster, sodass die meisten Integrationen ohne eigenen Device-Handler sofort funktionieren.
Endpunkte
Endpunkt 1 — Gerät
Geräteidentifikation und grundlegender Status. Das Umschalten des On/Off-Schalters aktiviert oder deaktiviert das WLAN.
Eingangscluster
| Cluster-ID | Name |
|---|---|
0x0000 | Basic |
0x0001 | Power Configuration |
0x0003 | Identify |
0x0006 | On/Off |
0x0402 | Temperature Measurement |
Ausgangscluster
| Cluster-ID | Name |
|---|---|
0x0003 | Identify |
0x0019 | OTA Upgrade |
Endpunkt 2 — Zähler
Zählerdaten. Das Umschalten des On/Off-Schalters löst eine Zählerauslesung aus.
Eingangscluster
| Cluster-ID | Name |
|---|---|
0x0006 | On/Off |
0x0702 | Simple Metering |
0x0B04 | Electrical Measurement |
Keine Ausgangscluster.
Metering-Cluster (0x0702)
Zwei Attribute, beide Standard. Herstellereigene Befehle sind nicht nötig.
| Attribut-ID | Name |
|---|---|
0x0000 | Current Summation Delivered |
0x0001 | Current Summation Received |
Current Summation Received wird nur aktualisiert, wenn der Zähler diesen Wert liefert.
Cluster Electrical Measurement (0x0B04)
Elektrische Kenngrößen. Der Cluster deklariert den vollständigen Attributsatz unten, aber nur drei davon — Active power (0x050B), RMS current (0x0508) und RMS voltage (0x0505) — lassen sich aus einem Zählerwert speisen und an einen Koordinator melden. Siehe Verfügbare Ziele.
Welche davon tatsächlich aktualisiert werden, hängt dann vom Zähler ab: Ein einphasiger Zähler füllt naturgemäß nie die Phasen B und C.
Manche Zigbee-Integrationen zeigen nicht jedes Attribut an, selbst wenn das Gerät es korrekt aktualisiert. Prüfen Sie die rohen Cluster-Werte in den Werkzeugen Ihres Koordinators, bevor Sie schließen, dass das Gerät nichts meldet.
| Attribut-ID | Name |
|---|---|
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) |
Wie aus Zählerwerten Attribute werden
Der Zähler liefert OBIS-Codes, Zigbee verwendet Cluster-Attribute. ZiggyMeter führt eine Zuordnungstabelle zwischen beiden.
Jeder Eintrag besteht aus einem OBIS-Code und einer Zuordnungs-ID: vier Byte hexadezimal, wobei die ersten zwei den Cluster und die letzten zwei das Attribut angeben.
| OBIS | Zuordnungs-ID | Cluster / Attribut | Bedeutung |
|---|---|---|---|
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 | Wirkleistung, Phase A |
1-0:11.7.0 | 0b040508 | 0x0B04 / 0x0508 | Effektivstrom, Phase A |
1-0:12.7.0 | 0b040505 | 0x0B04 / 0x0505 | Effektivspannung, Phase A |
Ändern Sie sie, wenn Ihr Zähler einen Code verwendet, den die Voreinstellungen nicht abdecken — etwa ein Zähler, der seine Spannung unter einem modellspezifischen Code meldet, sodass der Wert zwar in der Auslesung erscheint, aber nie bei Ihrem Koordinator ankommt.
Eine Zuordnung ändern
Das tun Sie im Webinterface. Öffnen Sie Zähler → Auslesung und doppelklicken Sie auf die Zelle Zuordnung in der Zeile, die Sie ändern wollen; die Zelle wird zu einer Auswahlliste der verfügbaren Zigbee-Ziele. Wählen Sie eines, und es ist sofort gespeichert — ein eigener Speicherschritt entfällt.
INFO
Nur OBIS-Codes, die in einer Auslesung erscheinen, lassen sich zuordnen, denn die Tabelle ist die Auslesung. Fehlt die gewünschte Zeile, lesen Sie zuerst den Zähler aus.
Verfügbare Ziele
Die Auswahlliste bietet sechs Einträge, mehr nicht. Nur diesen fünf Cluster/Attribut-Paaren lässt sich ein OBIS-Code zuweisen — die übrigen oben aufgeführten Attribute existieren zwar auf den Clustern, sind aber keine Zuordnungsziele.
| Eintrag in der Auswahlliste | Zuordnungs-ID | Cluster / Attribut |
|---|---|---|
| Nicht zugewiesen | 00000000 | — (der Wert wird gelesen, aber nicht über Zigbee veröffentlicht) |
| 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
Jedes Ziel kann immer nur von einem OBIS-Code belegt werden. Weisen Sie ein Ziel zu, das bereits eine andere Zeile hält, wandert es: Die andere Zeile wird automatisch auf Nicht zugewiesen zurückgesetzt. Prüfen Sie die Tabelle nach einer Änderung, wenn Sie mehrere Zeilen umstellen.
Verglichen wird der vollständige OBIS-Code einschließlich Tarif (1-0:15.8.0*101). Die API akzeptiert zusätzlich den Vergleich mit dem kurzen Code (15.8.0).
Bearbeiten über die API
/api/v1/zigbee/map liest und schreibt dieselbe Tabelle, was nützlich ist, um mehrere Geräte identisch einzurichten. Es ist eine Alternative zum Webinterface, nicht der normale Weg — ein POST ersetzt die gesamte Tabelle und wendet die Regel „ein Ziel, ein Code“ nicht für Sie an.
Firmware über die Luft
Endpunkt 1 trägt den standardmäßigen Cluster OTA Upgrade (0x0019), sodass jeder Koordinator mit Zigbee-OTA-Unterstützung das Gerät aktualisieren kann. Fertige Indexdateien werden für Zigbee2MQTT und für zigpy/ZHA veröffentlicht: