🎉 Zigbee for Domoticz — stable9 / 9.1.001 is out!

[pipiche]

Hi everyone,

A new stable release of the Zigbee plugin is available: **9.1.001 (2026.8)**. This is a big one — it lays the technical groundwork for the plugin's future while also fixing a handful of long-standing device issues. Here are the highlights.

🔧 Key change: DomoticzEx is now the primary framework
The plugin now runs on Domoticz's **Extended Framework (DomoticzEx)** by default, replacing the legacy Domoticz API it relied on until now.

[b]Why we made the move:[/b]
- DomoticzEx represents each Zigbee device as a single Domoticz object with multiple "Units" underneath, instead of a flat list of independent Idx-based widgets. This gives a much more natural, grouped representation of multi-endpoint/multi-cluster devices.
- It's the modern, actively developed Domoticz API — this move is what unlocks the reliability work described below (the new supervisor, thread-safety, smarter widget reuse) and is the foundation for features we have planned next.
- Less widget clutter and duplication, especially for devices that previously spread across many separate Idx's.

⚠️[b] Important constraint — please read before upgrading:[/b]
Widgets created under DomoticzEx are **not compatible with the legacy Domoticz framework**. Once your devices have been (re)created under DomoticzEx by this release, **downgrading the plugin to a pre-9.1.001 / legacy-framework version is no longer possible** — Domoticz would not be able to expose those widgets again under the old API.

In practice this means:
- Take a backup (Domoticz database + plugin `Data`/`Conf` folders) **before** upgrading, so you can restore to your current state if needed.
- Treat this as a one-way migration: plan for it rather than upgrading impulsively on a production system.
- If you're not ready to commit to DomoticzEx yet, stay on your current stable8 release until you are.

🛡️ [b]Much more robust in the background[/b]
- A new **HA-grade supervisor** watches over the Zigbee (zigpy) thread, with automatic retry and recovery if something goes wrong — no more silent stalls.
- Serial port drops are now detected and reconnected automatically, with a startup check/retry loop.
- Shutdown is cleaner: zigpy now gets up to 30s to stop gracefully, with a clear "Zigbee transport stopped" status message.
- Widget creation is smarter: it reports precise failure reasons and retries recoverable failures automatically instead of silently giving up.
- Group management and widget creation were refactored — pairing now reuses your existing matching widgets instead of creating duplicates.

Under the hood, several core modules (zigpy thread, `tools.py`) were split into smaller, dedicated pieces and covered by a lot of new unit tests — should make the plugin more reliable and easier to maintain going forward.

🩹 [b]Device fixes[/b]
- **ZLinky**: improved STGE and tariff (OP_TARIF) handling.
- **Tuya**: fixed multi-gang/multi-widget devices picking up the wrong datapoint on some commands.
- **Danfoss**: refactored eTRV handling, new OEM variant supported.
- Fixed ColorControl widget subtype selection.

🐞 [b]Other fixes[/b]
- OTA updates now work correctly with DomoticzEx, plus a couple of OTA bugs squashed (JSON loading, heartbeat handling).
- Fixed a bug requesting configuration reports when Min/Max were both 0x0000.

🧰 [b]New tools[/b]
- `Tools/replace_device.py` — replace a physical device while keeping its Domoticz history.
- `Tools/repair_clustertype.py` — protects your provisioned cluster types from being wiped on re-announcement.


As always, full details are in the [Release Notes](https://github.com/zigbeefordomoticz/Do ... seNotes.md), and questions/feedback are welcome here or on the [Wiki](https://zigbeefordomoticz.github.io/wiki/en-eng/).

Thanks to everyone who reported issues, tested, and contributed to this release! 🙏

[WouterO]

Congrats, pipiche! Great that this development still leads to improvements. Will update when back from holiday.

[waltervl]

Thanks pipiche for all the hard work. I will update soon!

[habahabahaba]

Thank you!
But What about Win users?

[waltervl]

Thanks pipiche for all the hard work. I will update soon!

Just updated, no issues until now!

[Rik60]

Upgraded to stable9, unfortunately not succesfull. After the update and confirm the switch via the command line to stable9 i have the next error; see attachment.
I can't upgrade/ install even the virtual environment is active

Switched back to a backup with version8
Edit: Running Domoticz on a Rpi3 Trixie Domoticz 2026.3

[Houthakker]

I just upgraded to stable9 and everything works just fine for me.
Thanks for your work Pipiche

[Rik60]

To accept te upgrade via --i-understand, i have to execute that command as superuser from the command line, is that normaal? How did other users the upgrade?

[waltervl]

It depends how you installed the plugin and/or running Domoticz, with or without root access.

[Rik60]

New try to upgrade to Stable9. Failing again. Someone has a clou?

[waltervl]

I had to run a specific update to stable 9 script.

Edit: I had to run from Z4D plugin directory

Code: Select all

./tools/plugin-switch-stable9.sh --i-understand

[Rik60]

Yes, i did that. Endded with no errors. The errors come after a Domoticz restart. Trying to upgrade fails during the requirements. The requirements should install the needed files?

[WouterO]

I updated today. Took some reading how to jump to the new stable branch, but I am now successfully and painlessly on 9.1.002. Thank you pipiche.

The reason I am commenting: my cpu-load (on my raspberry pi 4) became significantly less(!) after the update, making me happy (because the cpu warms up slightly less).

[Rik60]

If i try an upgrade i see this error, the upgrade is rejected because of the next errors:

Code: Select all

Flask-A-SQLAlchemy>=3.0.1, witch is not installed
pyopenssl 25.0.0 requeres cryptography<45, >=41.0.5, but you have cryptography 40.0.2 which is incompatible 

But, are they nessesary, must they be on the system and if yes, how to install?

[waltervl]

The install script for stable9 should tackle that all.
So it seems so ething after the switch to stable 9 is failing.

[Fredom]

The install script for stable9 should tackle that all.
So it seems so ething after the switch to stable 9 is failing.

Hi Walter,
Where can I find this script? Unfortunately, nothing I try works for upgrading to version 9.1.

[WouterO]

@Fredom: in Tools folder, I had to run: sudo ./plugin-switch-stable9.sh --i-understand
Then, I could update to stable9 newest version.

[Fredom]

@Fredom: in Tools folder, I had to run: sudo ./plugin-switch-stable9.sh --i-understand
Then, I could update to stable9 newest version.

Hi Wouter,
I've tried various methods, but I keep getting the same error message.

Code: Select all

fredom@raspberrypi:~/domoticz/plugins/Domoticz-Zigbee/Tools $  sudo ./plugin-switch-stable9.sh --i-understand
Checking Domoticz version and stable9 migration notice...
==============================================================================
Traceback (most recent call last):
  File "/home/fredom/domoticz/plugins/Domoticz-Zigbee/Tools/check_stable9_migration.py", line 184, in <module>
    main()
    ~~~~^^
  File "/home/fredom/domoticz/plugins/Domoticz-Zigbee/Tools/check_stable9_migration.py", line 168, in main
    display_migration_notice(version_status)
    ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^
  File "/home/fredom/domoticz/plugins/Domoticz-Zigbee/Tools/check_stable9_migration.py", line 124, in display_migration_notice
    print("English:\n" + english + "\n")
    ~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
UnicodeEncodeError: 'latin-1' codec can't encode character '\u2014' in position 1292: ordinal not in range(256)
Error: Domoticz version requirement not met. Cannot switch to stable9 branch.
fredom@raspberrypi:~/domoticz/plugins/Domoticz-Zigbee/Tools $ 

[Rik60]

Finally succeded to switch to stable9 9.1.002 from stable8 8.1.008. This is what i did:

- From the ui (user interface) updated the plugin
Then from the comman line:
switch to the plugin directory: cd domoticz/plugins/Domoticz-Zigbee
- set owner to pi: sudo chown -R pi:pi .
- go to the tools directory: cd Tools
- from command line executed: bash plugin-switch-stable9.sh --i-understand
This fails now, had to stash: git stash
again: - from command line executed: bash plugin-switch-stable9.sh --i-understand
Ok, switched the stable9 without errors
switched to the ui and updated the plugin -> updated stable9 without errors
Restarted the plugin in the ui
In the domoticz log errors: something to do with domoticz and domoticzex framework, both running on the same time
Rebooted the Rpi
No errors in the log
No Zigbee tab in the main domoticz screen -> Settings -> settings -> save settings
Ah, Zigbee tab in main screen
Can control Zigbee powerplug -> plugin works and actual version is 9.1.002
So, finally succes to switch to Stable9.

I hope that this can help other users.

[BartSr]

Just curious. Any advance compared to z2m?