Virtual Zigbee Bridge – expose Home Assistant entities as Zigbee devices

Share your Projects!
1

Hi everyone,

I have been working on an open-source hardware and firmware project that allows selected Home Assistant entities to appear as ordinary Zigbee devices on another Zigbee network.

The main use case is connecting Home Assistant to a Zigbee gateway that does not provide a suitable local API or native Home Assistant integration.

Instead of integrating the other gateway into Home Assistant, the project works in the opposite direction:

Home Assistant → Virtual Zigbee Bridge → another Zigbee coordinator

The external gateway therefore sees the selected Home Assistant entities as regular Zigbee devices.

Current hardware

The prototype consists of:

  • Waveshare ESP32-P4-POE-ETH for Ethernet, the web interface and Home Assistant communication
  • Waveshare ESP32-H2-Zero-M acting as the Zigbee radio and Zigbee router
  • A UART connection between the two boards

The ESP32-P4 communicates with Home Assistant through its API and WebSocket interface. It synchronizes the configured entities and their states with the ESP32-H2, which exposes them as Zigbee endpoints.

Current functionality

The current MVP supports:

  • Mapping Home Assistant switch entities to Zigbee Mains Power Outlet devices
  • Mapping Home Assistant light entities to Zigbee On/Off Light devices
  • Home Assistant state changes reported to the Zigbee network
  • Zigbee On/Off commands forwarded back to Home Assistant
  • Explicit Zigbee pairing from the web interface
  • Guided first-run configuration
  • Entity mapping and device-state monitoring
  • Ethernet connectivity
  • English and Czech web interface
  • Signed stable and beta OTA update channels
  • Updating the ESP32-H2 firmware through the ESP32-P4 web interface

I am currently testing it with a Somfy TaHoma Switch , where the mapped Home Assistant entities can be discovered and controlled as ordinary Zigbee devices.

Planned functionality

The configuration model already includes sensor and binary_sensor entities, but native Zigbee measurement and IAS endpoint support is not active yet.

Other planned features include:

  • Temperature and other sensor measurements
  • Binary sensors
  • Light brightness
  • Color temperature
  • RGB color control
  • Testing with additional Zigbee coordinators and gateways
  • A more integrated hardware design

Why I built it

Some smart-home gateways can control Zigbee devices but offer limited integration options for external systems.

This bridge makes it possible to expose Home Assistant entities using standard Zigbee clusters, without requiring the target gateway to understand Home Assistant, MQTT or a custom cloud API.

Potential use cases include:

  • Making Home Assistant devices available in otherwise closed smart-home ecosystems
  • Reusing Home Assistant templates and virtual entities on another gateway
  • Connecting custom or unsupported devices indirectly
  • Testing how gateways handle different Zigbee device types
  • Bridging selected functionality between independent smart-home systems

Project status

The project is currently an early working prototype rather than a finished consumer product. The firmware, web interface, documentation and build instructions are available under the MIT license.

GitHub:

I would be very interested in feedback from the Home Assistant and Zigbee communities, especially regarding:

  • Other Zigbee gateways or coordinators worth testing
  • The most useful entity types to implement next
  • Compatibility issues with different Zigbee stacks
  • Real-world scenarios where this type of bridge would be useful

Contributions, testing and technical feedback are welcome.

2

Welcome to the forums!

I had to read that 3 times to grasp what you were attempting, and I still don’t understand why you went in that direction. For the same price as your hardware & much less hassle, you could have simply bought a supported adapter, fired up Z2M and called it a day.

Somfy blinds are supported in Z2M, so you could simply ditch the Tahoma switch and have full support for all zigbee clusters.

3

The situation is that I don’t want to expose Home Assistant to the internet. However, I already have a Somfy TaHoma system that can be controlled remotely over the internet, and I also have devices such as Shelly units that I don’t want to connect to the Shelly Cloud.

So I was looking for a way to combine these two requirements, and I came up with the idea of creating a virtual Zigbee device connected to TaHoma, which I can then control remotely through TaHoma.

4

So basically you are exposing your devices to the internet through a proprietary, closed source home automation platform rather than Home Assistant. I don’t get why that is better than using HA with Z2M like Shadowfist suggested.

5

You don’t have to. Exposing HA to the internet is optional & even if you decided to do that, there are ways of securing the connection. Same goes for the Shellies - they offer full local control via MQTT.

Not going to comment on the security of a for-profit company which might decide to start selling your data to an ad vendor, start charging monthly subsriptions or simply close up shop. All these things have happened in the past & will continue to happen.

Yes, but again, why? With all due respect, you vibe coded your way into something which only supports 2 zigbee clusters and which will be a headache to expand & keep stable, let alone maintain in the long term.

You could simply have brought in the Somfy devices into HA and had a single home automation platform and a single zigbee mesh. Now you have 2 automation platforms & 2 separate zigbee meshes masquerading as one. Chances are, now that your Tahoma Switch detected other zigbee devices, it’ll try to route through them & destroy your zigbee mesh.

I really don’t mean to sound harsh since you’re new here, but the direction you decided to take feels like the opposite of what HA aims to accomplish. I’m no fanboy & generally disagree with the direction HA is heading, but I can’t deny the product is awesome at accomplishing its main purpose - getting rid of closed-loop systems in favour of one central place where practically every product is supported.

6

I don’t feel the need to justify myself. It solved a problem for me, and I fully understand your point of view. I just thought it might help someone else too. There’s nothing more behind it, and I’m sorry if it upset you in any way.

7

No hard feelings & I’m not upset in any way. I just wanted to make it clear so that if any future newbies came across this thread, they won’t get the incorrect assumption that this is their only option.

8

The idea of a $10 ESP32 Zigbee module is exciting. I did not know this existed. I often wondered if there was a way to put Arduino projects on my Zigbee network. Could your bridge be more generalized that way?

9

Isn’t that something which should work out of the box with the Hue simulator?

10

Yes, that should be possible. The ESP32-H2 could act as a standalone Zigbee coprocessor connected to almost any Arduino-compatible board over a 3.3 V UART.

The current firmware already uses this architecture: the H2 runs the ESP Zigbee stack independently, while the host configures endpoints, sends state updates, starts pairing, and receives Zigbee commands through a framed UART protocol with sequence numbers and CRC protection. The default connection runs at 460800 baud, although 115200 would be more suitable for slower boards such as an Arduino Uno.

At present, however, the protocol is tailored to this bridge rather than being a general-purpose Zigbee modem. It currently exposes:

  • On/off switches as mains power outlets
  • On/off lights
  • Pairing, leaving, rejoining, scanning, diagnostics, and firmware updates
  • State updates from the host and commands from the Zigbee network

Sensor configurations are recognized but not yet exposed as active Zigbee endpoints. Brightness, color temperature, RGB, and other clusters would also need to be implemented.

Generalizing it would mainly involve creating a small Arduino library that handles UART framing, CRC, endpoint configuration, pairing, and state synchronization. The H2 would handle all Zigbee details, while the Arduino would only read its hardware, report values, and react to commands.

The H2 firmware must initially be flashed with the complete factory image because it requires dedicated Zigbee storage partitions. It currently operates as a Zigbee router, so it expects continuous power rather than battery operation. A 5 V Arduino would also require appropriate logic-level conversion.

11

The question is whether you should use something like this instead of an Arduino: ESP32-C6-DevKitC-1 - ESP32-C6 - — esp-dev-kits latest documentation depending on how many pins are needed.

12

You can simply use a SMLight SLZB-06 set up as a Zigbee Hub and receive in HA over MQTT.

13

To give a bit more background, I have been using Somfy home automation for quite some time. It uses Somfy’s proprietary protocol (Somfy IO) rather than Zigbee, and my wife has become used to controlling everything through the TaHoma app.

At the same time, I am gradually moving the whole house over to Home Assistant and integrating all new devices there. The problem is that whenever I added another device directly to Home Assistant, my wife lost the ability to control it from the single app she was already familiar with.

That is why I came up with this solution. The idea is that I can expose virtually any Home Assistant entity as a Zigbee device and therefore make it controllable from TaHoma as well.

Right now, I am primarily working with Shelly devices for lighting control. The house originally used latching relays, so replacing and integrating that part was relatively straightforward.

Another advantage is that Home Assistant can remain accessible only from the internal network. I do not have to explain why something stops working when her phone is not connected to the home Wi-Fi, because TaHoma handles remote access for me.

And I built everything using parts I already had lying around. I know it’s not ideal, but sometimes the end justifies the means.

14

Thanks! I’ve been using ZigStar LilyZig - ZigStar with Zigbee2MQTT for a couple of years now.

15

Give her a dashboard designed for her by you in the Home Assistant companion app.

16

But then HA needs to be exposed to internet, right?

17

Well, duh. So is the Somfy Hub.

It’s no wonder I’ve never heard of Somfy:

somfy
somfy339×377 17 KB

18

But Somfy does not have access to the infrastructure.

19

It depends on how you configure remote-access for Home Assistant.

There are various ways to provide remote-access to Home Assistant. Easiest is via Nabu Casa’s Home Assistant Cloud service (see Remote Access).

I use a VPN (Virtual Private Network) via the free tier of Tailscale. There’s no URL exposed to the public Internet.

FWIW, Somfy use a third-party service to implement remote-access: Overkiz IoT Platform.

Home Assistant’s Somfy integration uses the Overkiz integration to access Somfy devices. I could not find details about how Overkiz implements the connection from a device (i.e. Somfy Tahoma Switch) and Overkiz’s cloud infrastructure.

Overkiz provides an API that allows for access to your Somfy devices. That’s what Home Assistant’s Somfy/Overkiz integration uses and what your Somfy app uses.

20

So do I, and that’s fine for me, but for practical reasons, it’s a no-go for my wife.