Zigbee2MQTT 2.11: estensioni esterne JS disabilitate per default

Con la versione 2.11.0, rilasciata oggi, Zigbee2MQTT introduce un cambio di comportamento importante: le estensioni esterne e i converter JS personalizzati sono ora disabilitati per default nelle nuove installazioni. La decisione è dettata da ragioni di sicurezza, come spiego più avanti.

Se hai un’installazione esistente e stai aggiornando, la tua configurazione rimane intatta. Il team ha scelto di non impattare chi è già operativo, ma è importante capire cosa è cambiato — perché questa impostazione diventerà lo standard definitivo con Zigbee2MQTT 3.0.

Cosa sono le estensioni esterne e i converter JS

Zigbee2MQTT supporta due tipi di codice JavaScript personalizzato che gli utenti possono aggiungere alla propria installazione, per estendere le funzionalità o rendere compatibili dispositivi e componenti che non lo sono nativamente.

Le estensioni esterne

Le estensioni esterne (external extensions) sono classi JavaScript salvate nella cartella data/external_extensions/. Permettono di estendere il comportamento interno di Zigbee2MQTT: intercettare messaggi MQTT, reagire a eventi Zigbee, aggiungere logica personalizzata in integrazioni o componenti che non ne dispongono. Funzionano esattamente come le funzionalità native, ma sono scritte e gestite direttamente dall’utente.

La documentazione ufficiale è disponibile su zigbee2mqtt.io — External extensions.

I converter esterni

I converter esterni (external converters) sono file JavaScript che insegnano a Zigbee2MQTT come comunicare con un dispositivo non ancora presente nel database ufficiale. Se hai un sensore o un attuatore Zigbee non riconosciuto automaticamente dalla tua installazione di Home Assistant, il converter personalizzato è la soluzione classica per renderlo operativo senza aspettare il supporto ufficiale.

La documentazione ufficiale è disponibile su zigbee2mqtt.io — External converters.

Entrambi eseguono codice JS arbitrario all’interno del processo principale di Zigbee2MQTT. Ed è esattamente questo il motivo del cambio introdotto con la 2.11.

Cosa cambia con la versione 2.11

Con la 2.11.0 viene introdotto il parametro enable_external_js nella sezione advanced del configuration.yaml. Il comportamento dipende dal tipo di installazione:

Se aggiorni da una versione precedente, le tue estensioni e i tuoi converter continuano a funzionare esattamente come prima. Il cambio è progettato per non essere un breaking change sull’esistente — almeno fino alla 3.0.

La mia esperienza con l’aggiornamento

Ho aggiornato stamattina, 3 giugno, appena la notifica è comparsa nell’addon di Home Assistant. Riavvio, log pulito, nessun avviso. I miei 26 dispositivi — lampadine Innr, prese Wolf, sensori Aqara, due termostati e il radar mmWave — erano tutti presenti e funzionanti al primo caricamento del frontend Windfront.

Qui sotto la schermata del mio frontend subito dopo l’aggiornamento: versione 2.11.0 confermata, zigbee-herdsman-converters 26.61.1, coordinatore EmberZNet attivo.

Il mio configuration.yaml di Zigbee2MQTT — con i dati sensibili oscurati — ha questa struttura:

version: 5
mqtt:
base_topic: zigbee2mqtt
server: mqtt://core-mosquitto:1883
user: addons
password: "**************"
serial:
port: /dev/ttyUSB0
adapter: ember
baudrate: 115200
rtscts: false
advanced:
log_level: info
channel: 20
network_key: [REDACTED]
pan_id: XXXXX
ext_pan_id: [REDACTED]
frontend:
enabled: true
package: zigbee2mqtt-windfront
port: 8099
homeassistant:
enabled: true
devices:
'0xa4c138f790af06f1':
  friendly_name: Innr n. 3 lumen 800
  state_action: false
'0xa4c138a8a6dcca56':
  friendly_name: Innr n. 4 lumen 800
  state_action: false
'0x00124b002f892023':
  friendly_name: Presa Elettrica n. 1 Sonoff
'0xa4c13849ee028be9':
  friendly_name: Innr n. 5 lumen 800
  transition: 0.5
'0x00158d0002a3747e':
  friendly_name: Cubo n. 1 Aqara
'0x00158d00029bf5d4':
  friendly_name: Cubo n. 2 Aqara
'0x540f57fffefdc6f8':
  friendly_name: Presa Elettrica n. 2 Wolf
  measurement_poll_interval: -1
'0x00158d0003fa66b4':
  friendly_name: Pulsante n. 2 Aqara Soggiorno
'0x84ba20fffe77b7fa':
  friendly_name: Presa Elettrica n. 4 Wolf
  measurement_poll_interval: -1
'0x540f57fffe8971b2':
  friendly_name: Presa Elettrica n. 5 Wolf
  measurement_poll_interval: -1
'0xa4c138540731c093':
  friendly_name: Dimmer n. 1
'0xa4c138a0e9efdbb1':
  friendly_name: Presa Elettrica n. 3 Girier
  measurement_poll_interval: -1
'0x540f57fffef92d2b':
  friendly_name: Presa Elettrica n. 6 Wolf
'0xe406bffffe38eac1':
  friendly_name: Pulsante n. 3 Moes Cucina
'0xa4c1382aedb29806':
  friendly_name: Dimmer n. 2
'0xa4c1380a031cae28':
  friendly_name: Innr n. 2 lumen 1000
  color_sync: false
  state_action: false
'0xa4c138ac1637334f':
  friendly_name: Innr n. 1 lumen 1000
  transition: 0.5
  color_sync: false
  state_action: false
'0xa4c1386490a99f48':
  friendly_name: Pulsante n. 5 Letto
'0x84ba20fffed47cfc':
  friendly_name: Temperatura n. 1 Sonoff
'0x00158d00027895fb':
  friendly_name: Temperatura n. 2 Aqara
'0xa4c138e9e1c7c89d':
  friendly_name: Radar n. 1
'0xa4c138dccb4cb231':
  friendly_name: Portone Varco
'0x00158d0003fa667c':
  friendly_name: Pulsante n. 4 Aqara Cucina
'0x54ef441000703b39':
  friendly_name: Termostato Aqara
'0x3c2ef5fffebad64b':
  friendly_name: Termostato Sonoff
'0x00158d008bbe7678':
  friendly_name: Temperatura n. 3 Aqara
groups:
'1':
  friendly_name: Soggiorno Luci Gruppo
'2':
  friendly_name: Cucina Innr Gruppo da Mqtt
  transition: 1
  devices:
    - 11871832728660806000
    - 11871832389730486000
ota:
default_maximum_data_size: 50
image_block_response_delay: 1000
disable_automatic_update_check: true
update_check_interval: 10080

Come vedi, nella sezione advanced non compare nessun enable_external_js — e questo conferma che la mia è un’installazione esistente aggiornata: il parametro non è necessario finché non arriva la 3.0.

Io non uso estensioni esterne né converter personalizzati perché, sinceramente, non ne ho mai avuto bisogno. La community di Zigbee2MQTT è enorme e i dispositivi supportati sono migliaia. Prima di acquistare qualsiasi cosa faccio sempre una ricerca su cosa è già compatibile e acquisto di conseguenza: niente dispositivi non supportati, solo roba già nel database ufficiale. C’è una lista su zigbee2mqtt.io/supported-devices che copre praticamente tutto quello di cui hai bisogno.

Se sei nella mia stessa condizione — nessun converter o estensione personalizzata — non devi fare assolutamente nulla. Puoi aggiornare con serenità.

Come verificare se sei impattato

Apri il tuo configuration.yaml di Zigbee2MQTT — attenzione, non quello di Home Assistant, sono due file distinti. Su Home Assistant OS si trova in /config/zigbee2mqtt/configuration.yaml; sulle installazioni standalone è nella cartella data/. Cerca la sezione advanced e controlla se hai una voce external_converters: oppure file nella cartella data/external_extensions/.

Scenario 1 — Nessun converter, nessuna estensione: non devi fare nulla. Aggiorna e riavvia.

Scenario 2 — Hai converter o estensioni attive: dopo l’aggiornamento alla 2.11 continuano a funzionare perché la tua è un’installazione esistente. Per blindare il comportamento in vista di Z2M 3.0, aggiungi esplicitamente il parametro nella sezione advanced:

advanced:
enable_external_js: true

Salva e riavvia Zigbee2MQTT. Verifica nel log di avvio che le estensioni vengano caricate correttamente.

Scenario 3 — Nuova installazione da zero con Z2M 2.11: le estensioni JS sono disabilitate per default. Se ne hai bisogno, aggiungi enable_external_js: true nella sezione advanced prima del primo avvio — oppure aggiungilo in seguito e riavvia.

Perché questa scelta: sicurezza by default

Tutto questo aggiornamento è dettato da ragioni di sicurezza. I file JavaScript girano con i privilegi del processo principale di Zigbee2MQTT: se l’installazione non è adeguatamente protetta da accessi esterni o da codice malevolo, un file JS compromesso può causare danni significativi all’intera installazione domotica.

La logica quindi è che chi non ha bisogno di queste funzionalità — e sono la maggior parte di noi — può tenere il sistema chiuso e non autorizzare l’esecuzione di estensioni e converter JavaScript. Meno superficie di attacco, meno rischio.

Il team ha scelto un approccio graduale: il cambio è opt-in per le nuove installazioni già dalla 2.11, ma diventerà il default anche per le installazioni esistenti a partire dalla 3.0. C’è tutto il tempo per adeguarsi senza sorprese.

Le altre novità della 2.11.0

L’aggiornamento alla 2.11.0 non si limita alle estensioni JS: porta anche un numero significativo di nuovi dispositivi supportati. Tra i 49 aggiunti, quelli più interessanti per il pubblico italiano:

• Aqara aggiunge il supporto alle azioni statiche per il sensore DWZTCGQ11LM e migliora la gestione della valvola W600 con lo stato di funzionamento ricavato dalla posizione.
• SONOFF porta il TRV-ZBT (valvola termostatica Zigbee), lo SNZB-03PR2 (sensore PIR con rilevamento presenza), lo SNZB-09P (sirena) e il MINI-ZB1GSP (mini smart switch con energy monitoring).
• Shelly debutta nel database ufficiale con i nuovi modelli Zigbee: BLU DoorWindow ZB, BLU Motion ZB e lo Shelly EM Gen4.

Il changelog completo è disponibile su GitHub — Release 2.11.0.

Come aggiornare Zigbee2MQTT alla 2.11

docker pull koenkk/zigbee2mqtt:latest
docker stop zigbee2mqtt
docker rm zigbee2mqtt
# Rilancia il container con il tuo comando docker run abituale

cd /opt/zigbee2mqtt
npm run stop
git pull
npm ci
npm run build
npm run start

Dopo il riavvio, controlla il log: se vedi un avviso relativo alle estensioni JS, torna alla sezione Come verificare se sei impattato e segui le istruzioni per il tuo scenario.

Conclusione

Ricordiamo che Zigbee2MQTT è un progetto open source mantenuto da Koen Koenkk e dalla community. Se lo usi quotidianamente, considera di supportare il progetto su GitHub.

Ricordiamo inoltre di aggiornare e tenere sempre il sistema aggiornato. Prima però di procedere con qualsiasi aggiornamento, fai sempre un backup completo dell’intero sistema.