Come configurare il passthrough USB Zigbee su Proxmox

Prerequisiti & Hardware Necessario

• Host Proxmox VE funzionante con una VM Home Assistant OS già avviata.
• Coordinatore Zigbee USB compatibile con ZHA o Zigbee2MQTT.
• Prolunga USB schermata, consigliata per allontanare il dongle dalle interferenze USB 3 e dal mini PC.
• Accesso amministrativo alla shell Proxmox o all’interfaccia web.
• Backup della configurazione Zigbee prima di modificare la VM.

Il coordinatore Zigbee è hardware radio. Proxmox VE è l’hypervisor. Home Assistant OS è il software guest che userà il dispositivo USB tramite passthrough. Non installare il dongle direttamente in un container se la VM Home Assistant è il sistema che deve gestirlo.

Il passthrough USB non richiede PCI passthrough o IOMMU per un singolo dongle, ma il dispositivo fisico deve restare collegato al nodo Proxmox che esegue la VM.

Procedura passo-passo

1. Arresta la VM Home Assistant da Proxmox o da Home Assistant e collega il coordinatore Zigbee direttamente al nodo Proxmox.
2. Apri la shell del nodo e identifica il dispositivo USB con lsusb.
3. Annota il valore VID:PID restituito da lsusb, ad esempio 10c4:ea60. Non usare questo esempio se il tuo dongle mostra un ID diverso.
4. Controlla anche la topologia fisica con lsusb -t e, se necessario, individua il percorso della porta.
5. Apri la VM nella GUI Proxmox, seleziona Hardware → Add → USB Device e scegli il dongle tramite Vendor/Device ID. Evita di selezionare una chiavetta usata per boot o storage.
6. In alternativa, dalla shell usa qm set 100 --usb0 host=VID:PID, sostituendo 100 con il VMID e VID:PID con il valore reale.
7. Controlla la configurazione della VM con qm config 100 e verifica che sia presente una riga usb0.
8. Avvia la VM con qm start 100 e attendi il completamento dell’avvio di Home Assistant OS.
9. In Home Assistant apri Impostazioni → Dispositivi e servizi, aggiungi o apri ZHA e seleziona il coordinatore USB rilevato.
10. Se usi Zigbee2MQTT, apri la configurazione dell’add-on e seleziona la porta seriale mostrata dal sistema guest, quindi riavvia solo l’add-on.

Configurazione con la GUI

Il metodo GUI è preferibile al primo tentativo perché mostra il nome del dispositivo. Per una configurazione stabile usa l’identificazione Vendor/Device ID quando esiste un solo dongle uguale; il passthrough per porta fisica può dipendere dalla topologia USB.

Configurazione della porta seriale

Non inventare il nome della porta. In ZHA usa il dispositivo seriale effettivamente rilevato. In Zigbee2MQTT controlla il log dell’add-on per individuare se il dispositivo è esposto come /dev/ttyUSB0 o /dev/ttyACM0. Il nome può cambiare se sostituisci il coordinatore.

Verifica del funzionamento

Il passthrough è corretto quando la VM si avvia anche con il dongle collegato, ZHA o Zigbee2MQTT rileva il coordinatore e i dispositivi Zigbee esistenti restano associati alla rete.

Controlla la VM dal nodo Proxmox:

qm config 100
qm status 100
lsusb

In Home Assistant verifica che il coordinatore sia disponibile e che un sensore già associato aggiorni i propri valori. Non avviare contemporaneamente due applicazioni che usano lo stesso coordinatore.

Riavvia completamente la VM, non solo l’add-on, e ripeti il controllo. Il dispositivo deve essere nuovamente presente senza aggiungerlo una seconda volta.

Problemi comuni

FAQ essenziali

Devo abilitare VT-d o IOMMU?

Non per il passthrough di un singolo dispositivo USB a una VM. VT-d/IOMMU è rilevante per altri tipi di passthrough, come controller PCIe o GPU.

Posso passare lo stesso dongle a due VM?

No. Un dispositivo USB fisico deve essere assegnato a una sola VM o applicazione alla volta.