Riferimento Zigbee
Questa pagina descrive come appare ZiggyMeter in una rete Zigbee: endpoint, cluster e attributi. Per sapere come collegarsi a una rete, vedi Configurazione Zigbee.
Informazioni su Zigbee
Zigbee è un protocollo wireless a rete mesh e a basso consumo per dispositivi IoT, basato su IEEE 802.15.4 a 2,4 GHz. I messaggi passano attraverso router alimentati da rete, ed è questo che lo fa funzionare in quadri elettrici e scantinati dove un collegamento Wi-Fi diretto non arriverebbe.
ZiggyMeter si collega come dispositivo finale (End Device): non instrada traffico per altri e dorme tra una lettura e l'altra.
Requisiti
- Un coordinatore Zigbee — un adattatore USB o un hub che crea e gestisce la rete
- Software che comprenda i cluster della Zigbee Cluster Library v8
Tutti i cluster esposti da ZiggyMeter sono standard. Non ci sono cluster proprietari del produttore, quindi la maggior parte delle integrazioni funziona subito senza un driver dedicato.
Endpoint
Endpoint 1 — dispositivo
Identificazione del dispositivo e stato di base. Attivare o disattivare l'interruttore On/Off attiva o disattiva il Wi-Fi.
Cluster di ingresso
| ID cluster | Nome |
|---|---|
0x0000 | Basic |
0x0001 | Power Configuration |
0x0003 | Identify |
0x0006 | On/Off |
0x0402 | Temperature Measurement |
Cluster di uscita
| ID cluster | Nome |
|---|---|
0x0003 | Identify |
0x0019 | OTA Upgrade |
Endpoint 2 — contatore
Dati del contatore. Attivare l'interruttore On/Off avvia una lettura del contatore.
Cluster di ingresso
| ID cluster | Nome |
|---|---|
0x0006 | On/Off |
0x0702 | Simple Metering |
0x0B04 | Electrical Measurement |
Nessun cluster di uscita.
Cluster Metering (0x0702)
Due attributi, entrambi standard. Non servono comandi proprietari.
| ID attributo | Nome |
|---|---|
0x0000 | Energia totale prelevata dalla rete |
0x0001 | Energia totale immessa in rete |
Energia totale immessa in rete viene aggiornata solo se il contatore fornisce quel valore.
Cluster Electrical Measurement (0x0B04)
Parametri elettrici. Il cluster dichiara l'intero insieme di attributi qui sotto, ma solo tre di essi — Active power (0x050B), RMS current (0x0508) e RMS voltage (0x0505) — possono essere alimentati da un valore del contatore e riportati al coordinatore. Vedi Destinazioni disponibili.
Quali di questi vengano effettivamente aggiornati dipende poi dal contatore: un contatore monofase, ovviamente, non compila mai le fasi B e C.
Alcune integrazioni Zigbee non mostrano tutti gli attributi anche quando il dispositivo li aggiorna correttamente. Controlla i valori grezzi dei cluster negli strumenti del coordinatore prima di concludere che il dispositivo non stia trasmettendo.
| ID attributo | Nome |
|---|---|
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) |
Come i valori del contatore diventano attributi
Il contatore fornisce codici OBIS; Zigbee utilizza attributi di cluster. ZiggyMeter mantiene una tabella di mappatura tra i due.
Ogni voce di mappatura è un codice OBIS più un ID di mappatura: quattro byte in esadecimale, di cui i primi due indicano il cluster e gli ultimi due l'attributo.
| OBIS | ID di mappatura | Cluster / attributo | Significato |
|---|---|---|---|
1-0:1.8.0 | 07020000 | 0x0702 / 0x0000 | Energia totale prelevata dalla rete |
1-0:2.8.0 | 07020001 | 0x0702 / 0x0001 | Energia totale immessa in rete |
1-0:1.7.0 | 0b04050b | 0x0B04 / 0x050B | Potenza attiva, fase A |
1-0:11.7.0 | 0b040508 | 0x0B04 / 0x0508 | Corrente efficace, fase A |
1-0:12.7.0 | 0b040505 | 0x0B04 / 0x0505 | Tensione efficace, fase A |
Modificala quando il tuo contatore usa un codice non coperto dai valori predefiniti — per esempio un contatore che riporta la tensione con un codice specifico del modello, per cui il valore compare nella lettura ma non raggiunge mai il coordinatore.
Modificare una mappatura
Si fa dall'interfaccia web. Apri Contatore → Letture e fai doppio clic sulla cella Mapping della riga da modificare; la cella diventa un elenco a discesa con le destinazioni Zigbee disponibili. Scegline una e viene salvata subito: non c'è un passaggio di salvataggio separato.
INFO
Si possono mappare solo i codici OBIS che compaiono in una lettura, perché la tabella è la lettura. Se la riga che cerchi non c'è, leggi prima il contatore.
Destinazioni disponibili
L'elenco a discesa offre sei scelte, e nessun'altra. Solo a queste cinque coppie cluster/attributo si può assegnare un codice OBIS — gli altri attributi elencati sopra esistono nei cluster ma non sono destinazioni di mappatura.
| Voce dell'elenco | ID di mappatura | Cluster / attributo |
|---|---|---|
| Unassigned | 00000000 | — (il valore viene letto ma non pubblicato via Zigbee) |
| 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
Ogni destinazione può essere usata da un solo codice OBIS alla volta. Assegnare una destinazione già occupata da un'altra riga la sposta: l'altra riga torna automaticamente su Unassigned. Se stai riorganizzando più righe, controlla la tabella dopo ogni modifica.
Il confronto avviene sul codice OBIS completo, tariffa inclusa (1-0:15.8.0*101). L'API accetta anche il confronto sul codice breve (15.8.0).
Modifica tramite API
/api/v1/zigbee/map legge e scrive la stessa tabella, utile per configurare in modo identico più dispositivi. È un'alternativa all'interfaccia web, non il percorso normale: una POST sostituisce l'intera tabella e non applica per te la regola «una destinazione, un codice».
Firmware via radio
L'endpoint 1 include il cluster standard OTA Upgrade (0x0019), quindi qualsiasi coordinatore che supporti Zigbee OTA può aggiornare il dispositivo. Sono pubblicati file di indice pronti per Zigbee2MQTT e per zigpy/ZHA: