USB Passthrough in Proxmox: Z-Wave- en Zigbee-dongles koppelen aan Home Assistant

Deze guide behandelt USB passthrough Proxmox Home Assistant configuratie voor Zigbee en Z-Wave dongles in je HAOS VM.

Deze guide gaat ervan uit dat je al een werkende HAOS VM in Proxmox hebt draaien. Heb je dat nog niet, begin dan eerst met SHH-TUT003: Proxmox + HAOS VM setup guide en kom daarna hier terug.

De fysieke antenne van je smarthome

Waarom dit relevant is: het cloudafhankelijkheidsprobleem

Als je een Tuya- of eWeLink-slimme lamp hebt, reist elk aan/uit-commando van je telefoon naar een server in Shenzhen en terug voordat de lamp reageert. Die omweg is afhankelijk van je internetverbinding, de uptime van de leverancier en hun bereidheid om netjes met jouw data om te gaan.

Zigbee en Z-Wave werken anders. Ze zijn versleuteld, lokaal en mesh-native. Je apparaten communiceren rechtstreeks met een coördinator in je woning, zonder enige cloudbetrokkenheid.

De echte test: Trek nu de ethernetkabel uit je router. Met deze setup werken je lampen gewoon nog. Dat is het doel.

Als je een kant-en-klare Home Assistant-oplossing als alternatief wilt verkennen, bekijk dan onze AVATTO HA 70 Review voor een budgetvriendelijke optie.

Vereisten en minimale hardware

Softwarevereisten

• Werkende Proxmox-installatie met een al uitgerold Home Assistant OS (HAOS) VM — zie SHH-TUT003
• VM ID voorbeeld: 201
• Proxmox web-UI bereikbaar via https://[SERVER-IP]:8006

Benodigde hardware

De dual-chip-kanttekening: Één USB-stekker, twee radio’s. De CP2105-chip presenteert zich aan Linux als twee afzonderlijke seriële poorten: ttyUSB0 en ttyUSB1. Dit is de bron van de meeste verwarring op Reddit. Methode 2 lost dat volledig op.

Het ene accessoire dat je écht nodig hebt

Je hebt een USB-verlengkabel van minimaal 1 meter nodig. Dit is geen optie.

Waarom dit belangrijk is: USB 3.0-poorten en NVMe SSD’s stralen RF-ruis uit op de 2,4GHz-band — precies de frequentie die Zigbee gebruikt. Zonder fysieke afstand tussen je dongle en het serverchassis wordt je meshbereik flink aangetast. Dit is de nummer één klacht op r/homeassistant, en het antwoord is altijd hetzelfde: gebruik een verlengkabel. Gebruik specifiek een USB 2.0-verlengkabel, geen USB 3.0.

Methode 1: De snelle start (beginnerstraject — bare metal)

Belangrijke kanttekening vooraf: Deze guide is geschreven voor gebruikers die HAOS als VM in Proxmox draaien. Het onderstaande gedeelte beschrijft het eenvoudigere bare-metal-traject uitsluitend ter referentie. Deze guide behandelt geen Raspberry Pi-opstellingen. De vereiste opstelling zoals beschreven in de vereisten is een draaiende Proxmox-server met een HAOS VM (zie SHH-TUT003).

Waarom dit traject eenvoudiger is

Als je HAOS rechtstreeks op bare-metal hardware draait zonder hypervisor, zit er geen virtualisatielaag tussen de hardware en Home Assistant. De Linux-kernel in HAOS detecteert USB-seriële apparaten van nature bij het opstarten. Er is geen passthrough-configuratie nodig.

Fysieke installatie

1. Sluit de dongle aan op een USB-poort van je machine. Gebruik de verlengkabel hoe dan ook.
2. Herstart de machine. Ga naar Settings → Devices & Services. De hardware wordt direct herkend door de basisinstallatie.

Integraties toevoegen

1. Ga naar Settings → Devices & Services → Add Integration.
2. Zoek naar ZHA. Selecteer de poort die eindigt op if01-port0 (ttyUSB1 — Standard Com Port). Dit is je Zigbee-radio.
3. Zoek naar Z-Wave. Home Assistant installeert automatisch de Z-Wave JS Supervisor Add-on. Selecteer de poort die eindigt op if00-port0 (ttyUSB0 — Enhanced Com Port). Dit is je Z-Wave-radio.

Het beginnerstraject stopt hier. Draai je Proxmox, ga dan verder met Methode 2. De bovenstaande stappen zijn niet van toepassing op een VM — het USB-apparaat is eigendom van het Proxmox host-OS, niet van Home Assistant rechtstreeks.

Methode 2: De professionele opstelling (gevorderd traject — Proxmox USB Passthrough)

Doelgroep: HAOS draait als VM in Proxmox. De USB-dongle is fysiek aangesloten op de Proxmox-host en moet expliciet aan de VM worden doorgegeven. De VM kan het apparaat niet zien totdat je dit doet.

Stap 1: Fysieke voorbereiding

1. Sluit de dongle via de verlengkabel aan op een USB 2.0-poort van de Proxmox-host.
2. Identificeer de juiste poort visueel: USB 2.0-poorten zijn zwart. USB 3.0-poorten zijn blauw.

Sluit de dongle niet zonder verlengkabel rechtstreeks aan op het serverchassis. USB 3.0-interferentie gecombineerd met nul fysieke afstand leidt tot een onbetrouwbaar Zigbee-mesh. Dit staat gedocumenteerd in de Proxmox-forums en wordt voortdurend herhaald op r/homeassistant. De kabel is de oplossing.

Stap 2: Het apparaat identificeren op de Proxmox-host

Maak via SSH verbinding met je Proxmox-host, of open het tabblad Shell in de Proxmox web-UI voor je node. Voer het volgende commando uit:

lsusb

Zoek in de uitvoer naar een regel die er ongeveer zo uitziet:

Bus 001 Device 003: ID 10c4:ea71 Silicon Labs CP2105 Dual USB-to-UART Bridge Controller

Noteer het Vendor ID (10c4) en het Device ID (ea71). Die heb je nodig in de volgende stap. Zie je je apparaat hier helemaal niet staan, stop dan en ga eerst naar de sectie Probleemoplossing voordat je verdergaat.

Stap 3: USB Passthrough instellen in de Proxmox web-UI

1. Open de Proxmox web-UI en selecteer je HAOS VM (bijv. VM 201).
2. Ga naar Hardware → Add → USB Device.
3. Cruciale keuze: Selecteer “Use USB Vendor/Device ID”. Selecteer NIET “Use USB Port”.
4. Kies je dongle uit het dropdown-menu. Die verschijnt als iets als Silicon Labs CP2105.
5. Klik op Add.

Waarom Vendor/Device ID en niet Port? Proxmox kan interne USB-poortnummers na een herstart opnieuw toewijzen. Als je “Use USB Port” gebruikt, verliest de VM het apparaat zodra de poortnummering verschuift. Vendor/Device ID is een hardware-vingerafdruk die aan de chip zelf is gekoppeld, niet aan welke fysieke poort die bezet. Het overleeft herstarts, poortwisselingen en serververplaatsingen. Je configureert het eenmalig en hoeft er nooit meer naar om te kijken. Dit is het directe antwoord op de meest voorkomende Reddit-klacht in deze categorie: “mijn Zigbee-stick verdween na een herstart.”

Stap 4: De HAOS VM herstarten

Herstart de HAOS VM vanuit de Proxmox web-UI door je VM te selecteren en op de knop Reboot te klikken.

Belangrijk: De herstart moet worden geïnitieerd op Proxmox-niveau om ervoor te zorgen dat het USB-apparaat bij het opstarten correct opnieuw aan de VM wordt gekoppeld.

Stap 5: Detectie binnen de VM valideren

1. Ga in Home Assistant naar Settings → Devices & Services.
2. Controleer of de hardware zichtbaar is. Voor een dual-chip stick zie je twee seriële poortingangen die overeenkomen met:

/dev/ttyUSB0 — CP2105 Enhanced Com Port   (→ Z-Wave)
/dev/ttyUSB1 — CP2105 Standard Com Port   (→ Zigbee / ZHA)

Controleer voor nauwkeurigere identificatie de stabiele by-id-paden. Deze strings zijn uniek voor jouw specifieke dongle en veranderen niet:

/dev/serial/by-id/usb-Silicon_Labs_CP2105_..._if00-port0   → Z-Wave JS
/dev/serial/by-id/usb-Silicon_Labs_CP2105_..._if01-port0   → ZHA (Zigbee)

De regel om te onthouden: if00 is Z-Wave. if01 is Zigbee. Dit is consistent gedrag voor de CP2105-chip.

Stap 6: De ZHA-integratie instellen (Zigbee)

1. Ga naar Settings → Devices & Services → Add Integration.
2. Zoek naar en selecteer ZHA.
3. Kies bij de poortselectie de vermelding die eindigt op if01-port0 (ttyUSB1 — Standard Com Port). Dit is je Zigbee-radio.
4. Doorloop de installatiewizard. ZHA initialiseert de Zigbee-coördinator.

Stap 7: De Z-Wave JS-integratie instellen

1. Ga naar Settings → Devices & Services → Add Integration.
2. Zoek naar en selecteer Z-Wave.
3. Home Assistant installeert automatisch de Z-Wave JS Supervisor Add-on. Geef dit de tijd om te voltooien.
4. Kies bij de poortselectie de vermelding die eindigt op if00-port0 (ttyUSB0 — Enhanced Com Port). Dit is je Z-Wave-radio.

Maak direct een back-up van je beveiligingssleutels. Z-Wave JS genereert beveiligingssleutels tijdens de installatie. Als je deze sleutels kwijtraakt, moet elk gekoppeld apparaat worden gereset naar fabrieksinstellingen en opnieuw worden gekoppeld. Sla ze op in een wachtwoordmanager zodra ze verschijnen.

Configuratie en validatie: controleren of alles werkt

De integratiestatuscontrole

Ga naar Settings → Devices & Services. Onder de sectie Configured moeten zowel ZHA als Z-Wave een groene statusindicator tonen, wat bevestigt dat beide radio’s actief zijn en communiceren.

Afrondingschecklist

[ ] USB passthrough geconfigureerd via Vendor/Device ID (niet Port)
[ ] HAOS VM herstart op Proxmox-niveau
[ ] ZHA-integratie actief — Zigbee-coördinator online (poort: if01-port0 / ttyUSB1)
[ ] Z-Wave JS Add-on geïnstalleerd en actief (poort: if00-port0 / ttyUSB0)
[ ] Z-Wave-beveiligingssleutels opgeslagen in wachtwoordmanager
[ ] Dongle aangesloten via USB 2.0-verlengkabel (minimaal 1 meter), weg van het serverchassis

De keerzijde: eigenaardigheden en eerlijke beperkingen

Het naamgevingsprobleem bij dual-chip

Linux wijst ttyUSB0 en ttyUSB1 dynamisch toe bij het opstarten. De volgorde is niet gegarandeerd voor alle hardwarecombinaties. De CP2105-chip is in de praktijk consistent — if00 mapt naar Z-Wave en if01 naar Zigbee — maar dit is chipspecifiek gedrag, geen universele Linux-regel.

Als je de verkeerde poort voor ZHA selecteert, crasht de integratie direct. ZHA ontvangt Z-Wave-protocolresponsen die het niet kan verwerken en kan niet initialiseren. De oplossing is eenvoudig: verwijder de kapotte integratie, voeg hem opnieuw toe en gebruik de /dev/serial/by-id/-string om de juiste poort te bevestigen voordat je opslaat.

Als je een single-radio dongle gebruikt (alleen Zigbee of alleen Z-Wave), verdwijnt deze complexiteit volledig. Je ziet één ttyUSB-vermelding en hebt één integratie te configureren. De dual-chip stick is krachtig, maar vereist precisie bij de eerste installatie.

Dit is eenmalig configuratiewerk

Zodra de Vendor/Device ID-passthrough is ingesteld en beide integraties correct zijn geconfigureerd, is de opstelling volledig persistent. Je kunt de dongle naar een andere fysieke USB-poort op het serverchassis verplaatsen en Proxmox vindt hem nog steeds via de hardware-vingerafdruk. De VM merkt er niets van.

Het nauwkeurige werk op dag één elimineert 100% van de Reddit-posts die beginnen met “mijn Zigbee-stick verdween na een herstart.”

Probleemoplossing voor veelvoorkomende fouten

Probleem: Slecht bereik of apparaten die willekeurig offline gaan

Oorzaak: USB 3.0 RF-interferentie op de 2,4GHz-band.

Oplossing: Verplaats de dongle naar een USB 2.0-poort en voeg een verlengkabel van minimaal 1 meter toe. Gebruik dit commando op de Proxmox-host om te controleren welke USB-versie je poort gebruikt:

lsusb -t
# Zoek naar "480M" in de uitvoer — dit geeft USB 2.0-snelheid aan
# "5000M" geeft USB 3.0 aan — verplaats de dongle naar een andere poort

Probleem: Dongle verdwijnt na herstart van de server

Oorzaak: Passthrough was geconfigureerd met “Use USB Port” in plaats van “Use USB Vendor/Device ID.” Wanneer Proxmox na een herstart interne USB-poortnummers opnieuw toewijst, verliest de VM de apparaatreferentie volledig.

Oplossing: Ga naar de Proxmox web-UI, selecteer je VM, open het tabblad Hardware, zoek de USB-apparaatvermelding, klik op bewerken en schakel de methode over naar Vendor/Device ID. Sla de wijziging op en herstart de VM vanuit Proxmox.

Probleem: Verkeerde ttyUSB geselecteerd, integratie crasht

Oorzaak: ZHA was gericht op de Z-Wave-poort, of Z-Wave JS was gericht op de Zigbee-poort.

Oplossing: Verwijder de kapotte integratie. Voer voordat je hem opnieuw toevoegt dit commando uit in de Home Assistant-terminal of via SSH om de juiste poorttoewijzing te bevestigen:

ls -la /dev/serial/by-id/
# "if00" in de string → gebruik deze poort voor Z-Wave JS (ttyUSB0 - Enhanced Com Port)
# "if01" in de string → gebruik deze poort voor ZHA (ttyUSB1 - Standard Com Port)

Probleem: Dongle niet zichtbaar in de Proxmox USB-apparatenlijst

Oorzaak: Het apparaat wordt niet herkend door het Proxmox host-OS, of er is een stroomprobleem met een USB-hub of poort.

Stappenplan voor oplossing:

1. Voer lsusb uit op de Proxmox-host. Bevestig dat het apparaat op OS-niveau zichtbaar is voordat je passthrough probeert.
2. Probeer een andere fysieke USB-poort op de server.
3. Verwijder tijdelijk de verlengkabel om te isoleren of de kabel zelf defect is.
4. Controleer het kernellog op USB-foutmeldingen:

dmesg | grep -i usb | tail -20

Zoek naar regels met “disconnect,” “error,” of “unable to enumerate.” Die wijzen je naar een hardware- of stroomleveringsprobleem in plaats van een configuratieprobleem.

Conclusie en vervolgstappen

Wat je hebt gebouwd

• Een lokaal Zigbee-meshnetwerk, actief en gecoördineerd door ZHA in je HAOS VM, zonder enige cloudafhankelijkheid.
• Een lokaal Z-Wave-meshnetwerk, beheerd door Z-Wave JS.
• Een smarthome-opstelling die een volledige internetstoring overleeft zonder ook maar één automatisering te verliezen.

De privacywinst

De Tuya- en eWeLink-cloudketen is nu permanent verbroken voor elk apparaat dat je aan deze netwerken toevoegt. Geen enkel pakket van je lichtschakelaar raakt ooit nog een server in Shenzhen. Elke schakelactie, elke sensorwaarde, elke automatisering draait volledig binnen je eigen woning.

Als je deze aanpak wilt uitbreiden naar andere delen van je infrastructuur, is onze guide over het opzetten van een zelfgehoste Docker- en Portainer-omgeving op Proxmox LXC een logische vervolgstap voor het draaien van aanvullende lokale diensten naast Home Assistant.

Definitieve afrondingschecklist

[x] USB Passthrough geconfigureerd via Vendor/Device ID
[x] ZHA-integratie actief — Zigbee-netwerk online (if01-port0 / ttyUSB1)
[x] Z-Wave JS Add-on geïnstalleerd en geconfigureerd (if00-port0 / ttyUSB0)
[x] Beveiligingssleutels opgeslagen in wachtwoordmanager
[x] Verlengkabel aanwezig (minimaal 1 meter, USB 2.0) — RF-interferentie gemitigeerd