Share USB devices on ZVM

Insight & Feedback
7

Here is a guide how I managed to pass it through with Sonnof usb.
Tutorial: Pass Through a USB Device to an HAOS VM on ZimasaOS/ZVM + Zigbee2MQTT Configuration

  1. Set or Verify the Root Password (ZimasaOS)

    1. Use the Official ZimasaOS Method
      • Follow ZimasaOS instructions to create or change the root password.
      • Do not rely on standard Linux commands if ZimasaOS uses a different mechanism.
    2. Confirm Root Privileges
      • Make sure you can log in as root or otherwise escalate privileges. Editing libvirt configurations for VMs typically requires root access.

    Note: Because ZimasaOS might differ from standard Linux distributions, always check its documentation for the correct procedure.

  2. Identify Your USB Device

    1. Plug In Your USB Device
      • For example, a Sonoff Zigbee 3.0 USB Dongle Plus V2 or another Zigbee/Z-Wave stick.
    2. Open a Terminal with root privileges.
    3. Run:
      lsusb
      Identify your device’s Vendor ID (VID) and Product ID (PID).
      Example output:
      Bus 001 Device 004: ID 1a86:55d4 QinHeng Electronics
      Here, 0x1a86 is the VID, and 0x55d4 is the PID. (Yours may differ.)

  3. Edit the HAOS VM’s XML Configuration

    1. Get Your VM Name or UUID

      • For instance, if your HAOS VM has a UUID like 8958ddf3.

    2. Open the VM’s XML (using ZimasaOS’s recommended method or virsh if available):
      virsh edit 8017ddf9
      This opens the VM’s XML in a text editor.

    3. Add a Section Within
      For example:

      • Replace 0x1a86 and 0x55d4 with the actual VID/PID of your device.
      • Make sure this goes inside the block and below an existing <controller type=‘usb’ …> line if there is one.

    4. Save your changes and exit the editor.

  4. Restart the HAOS VM

    1. Shut Down the VM (if it’s running):
      virsh shutdown 8017ddf9
    2. Start it again:
      virsh start 8017ddf9
    3. Verify it’s running:
      virsh list --all
      The VM named 8017ddf9 should show a status of running.

  5. Verify the USB Device in Home Assistant OS

    1. Open Home Assistant (HAOS).
    2. Go to Settings → System → Hardware (newer HA versions) or Supervisor → System → Host → Hardware (older versions).
    3. Look for a serial or USB device:
      • You might see something like /dev/ttyACM0.
      • Or a by-id path:
        /dev/serial/by-id/usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2_20231102103652-if00
        The by-id path is more stable and preferred for Zigbee2MQTT.

  6. Configure Zigbee2MQTT

    1. Open Zigbee2MQTT Configuration in Home Assistant.

      • This may be in the Add-on configuration or a YAML config file (e.g., /share/zigbee2mqtt/configuration.yaml).

    2. Set the port to your USB device’s path. For example:

      serial:
      port: >-
      /dev/serial/by-id/usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2_20231102103652-if00

      or as a single line:

      serial:
      port: “/dev/serial/by-id/usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2_20231102103652-if00”

      This path can be found under Settings → System → Hardware in HAOS or (on older versions) Supervisor → System → Host → Hardware.

    3. Save your Zigbee2MQTT configuration.

    4. Restart Zigbee2MQTT (and possibly Home Assistant) so that the changes take effect.

    5. Check Zigbee2MQTT logs to verify it successfully connected to the USB dongle.

Summary

  1. Set (or verify) your ZimasaOS root password using the official method.
  2. Identify your USB device’s Vendor/Product IDs with lsusb.
  3. Add a entry to the HAOS VM’s XML to pass the USB device through.
  4. Restart the VM to apply changes.
  5. Confirm the new USB device is recognized in HAOS by checking hardware listings and logs.
  6. Configure Zigbee2MQTT by pointing serial.port to /dev/serial/by-id/… (recommended for stability).

With these steps, your HAOS VM will see the USB Zigbee dongle, and Zigbee2MQTT can communicate with it, enabling you to integrate and automate all your Zigbee devices in Home Assistant. Enjoy!

1 Like