Add Zigbee Dongle to Home Assistant VM (Raspberry Pi 5)

October 12, 2025 (Last Modified: October 13, 2025)

Introduction

This guide shows how to pass through the SONOFF Zigbee 3.0 USB Dongle Plus to a Home Assistant OS (HAOS) virtual machine running on Raspberry Pi 5 using KVM/libvirt. This allows you to use Zigbee devices directly within your virtualized Home Assistant setup.

Why Pass Through USB Devices to Virtual Machines?

When running Home Assistant OS (HAOS) in a virtualized environment on Raspberry Pi 5, smart home automation requires direct hardware access for wireless communication protocols like Zigbee that depend on dedicated USB dongles.

Our technology stack includes the Raspberry Pi 5 hardware layer, Raspberry Pi OS host, QEMU/KVM hypervisor, libvirt management daemon, and HAOS guest OS. By default, the guest VM cannot directly access USB devices connected to the host system due to hypervisor isolation.

USB passthrough solves this by “passing” a physical USB device from the host directly to the virtual machine, essential for Zigbee coordinators like the SONOFF Zigbee 3.0 USB Dongle Plus.

If setting up a new HAOS VM with the dongle already connected, you can include passthrough during virt-install using --hostdev 003.002. However, when adding hardware to an existing setup, you’ll need to modify the running VM configuration using libvirt’s XML system.

Prerequisites

Raspberry Pi 5 with HAOS VM already running (see Installing HAOS in KVM)
SONOFF Zigbee 3.0 USB Dongle Plus
Basic command line knowledge

Step 1: Verify Dongle Detection on Host

First, check if your SONOFF Zigbee 3.0 USB Dongle Plus is recognized by the Raspberry Pi 5:

sudo lsusb

You should see output similar to:

Bus 003 Device 002: ID 10c4:ea60 Silicon Labs CP210x UART Bridge

The dongle appears as a Silicon Labs CP210x UART Bridge, which is normal for this device.

Step 2: Add USB Passthrough to Existing VM

Since your HAOS VM is already running, you’ll need to edit the VM configuration.

Option A: If creating a new VM (for reference)

If you were creating a new VM and had the dongle connected from the start, you could add this parameter to virt-install:

--hostdev 003.002

Option B: Adding to existing running VM

List your virtual machines:

sudo virsh list --all

Expected output:

 Id   Name   State
----------------------
 3    haos   running

Edit the HAOS VM configuration:

sudo virsh edit haos

Inside the <devices> section, add this USB hostdev block:

<hostdev mode='subsystem' type='usb' managed='yes'>
  <source>
    <vendor id='0x10c4'/>
    <product id='0xea60'/>
  </source>
</hostdev>

Save and exit the editor.

Step 3: Restart the VM

Shutdown and restart your HAOS VM to apply the changes:

sudo virsh shutdown haos

Wait for the VM to fully shutdown, then start it again:

sudo virsh start haos

Step 4: Verify Passthrough in HAOS

Access the Home Assistant terminal and verify the dongle is now visible inside the VM:

sudo lsusb

You should now see output like:

Bus 001 Device 001: ID 1d6b:0002 Linux 6.12.43-haos xhci-hcd xHCI Host Controller
Bus 001 Device 002: ID 10c4:ea60 Itead Sonoff Zigbee 3.0 USB Dongle Plus V2
Bus 002 Device 001: ID 1d6b:0003 Linux 6.12.43-haos xhci-hcd xHCI Host Controller

Notice the dongle now shows as “Itead Sonoff Zigbee 3.0 USB Dongle Plus V2” inside the VM.

Step 5: Configure Zigbee Integration in Home Assistant

Navigate to your Home Assistant web interface and go to Settings → Devices & Services → Integrations.

You should see the Sonoff Zigbee dongle automatically discovered:

Zigbee Discovery

Click on the discovered integration to set it up.

Step 6: Add Zigbee Devices

Once the Zigbee integration is configured:

Put your Zigbee devices in pairing mode
In Home Assistant, go to the Zigbee integration
Click the “Add Device” button to start pairing

Adding Zigbee Devices

Troubleshooting

Dongle not detected in VM: Ensure the VM was fully shutdown before restarting
Permission issues: Verify your user is in the libvirt and kvm groups
Device conflicts: Make sure no other processes on the host are using the dongle

Summary

You’ve successfully passed through the SONOFF Zigbee 3.0 USB Dongle Plus to your HAOS VM running on Raspberry Pi 5. The dongle is now available for Zigbee device management directly within Home Assistant, providing full smart home integration capabilities in your virtualized environment.

Update: Adding Bluetooth USB Dongle to HAOS VM

Note: The Raspberry Pi 5’s built-in Bluetooth cannot be easily passed through to a KVM virtual machine, as it is connected via UART/SDIO rather than USB. For Bluetooth functionality within your Home Assistant VM, you must add a USB Bluetooth dongle (such as the TP-Link UB500 or Archer T2UB Nano) to your host.

Passing Through a USB Bluetooth Dongle

The steps for adding a Bluetooth dongle are almost identical to those for Zigbee:

Verify Dongle Detection on Host

Plug your Bluetooth dongle into the RPi5 and confirm detection:

sudo lsusb

Example output:

Bus 001 Device 002: ID 2357:0604 TP-Link TP-Link Bluetooth USB Adapter

Edit VM Configuration

Edit your HAOS VM definition:

sudo virsh edit haos

In the <devices> section, add:

   <hostdev mode='subsystem' type='usb' managed='yes'>
     <source>
       <vendor id='0x2357'/>
       <product id='0x0604'/>
     </source>
   </hostdev>

Restart Your HAOS VM

Shutdown and start the VM to apply changes:

sudo virsh shutdown haos
sudo virsh start haos

Verify in Home Assistant OS

In the HAOS terminal: bluetoothctl list or hciconfig You should see a USB Bluetooth controller (e.g., hci0: Type: Primary Bus: USB).

In the Home Assistant web UI, the Bluetooth integration will automatically appear and the adapter will be ready to use.

Now your Home Assistant VM supports Bluetooth devices using a simple USB dongle passthrough!

Installing Home Assistant OS (HAOS) in KVM on Raspberry Pi 5