Uma partilha Samba não consegue passar um adaptador Zigbee físico para o HAOS
O problema original diz respeito a um dispositivo série USB, não a uma pasta. Uma partilha Samba pode disponibilizar ficheiros a uma máquina virtual, mas não consegue fazer com que um rádio ConBee, Sonoff, Nortek ou semelhante apareça como hardware USB convidado. A solução comunitária funcional liga o dispositivo USB do anfitrião ao convidado ZVM através do libvirt.
Este continua a ser um procedimento alternativo através da linha de comandos, e não um seletor USB do ZVM confirmado. Faça uma cópia de segurança do XML da máquina virtual e encerre o Home Assistant OS antes de editar o hardware persistente. Uma edição XML malformada ou a ausência do dongle pode impedir o arranque do convidado, por isso mantenha uma cópia que permita restaurar a configuração anterior.
Identifique o dongle sem copiar os IDs de outro utilizador
Ligue-se ao ZimaOS através do SSH suportado e do método de obtenção de privilégios e, em seguida, execute lsusb. Encontre o par de fabricante e produto do dongle, como 1a86:55d4 no exemplo. Os IDs do seu ConBee, Sonoff ou Nortek serão diferentes.
Desligue e volte a ligar o dongle uma vez se a lista não for clara. A correspondência por fabricante e produto também pode ser ambígua quando estão ligados dois adaptadores idênticos. O formato de dispositivo do anfitrião do libvirt explica a correspondência por VID/PID e endereços USB mais específicos.
Registe o nome libvirt exato ou o UUID da VM com virsh list --all. Não utilize um ID de exemplo da discussão. Exporte a definição atual com virsh dumpxml VM_NAME antes de a alterar.
Adicione um bloco hostdev dentro da secção de dispositivos do convidado
Com o convidado desligado, abra a respetiva definição utilizando virsh edit VM_NAME. Dentro do elemento <devices> existente, adicione <hostdev mode='subsystem' type='usb' managed='yes'><source><vendor id='0xVID'/><product id='0xPID'/></source></hostdev>, substituindo VID e PID pelos valores do seu anfitrião.
Adicione uma secção hostdev completa por cada dispositivo físico. Não crie um segundo contentor <devices> e não cole o bloco depois da etiqueta de fecho </devices>. Guarde e, em seguida, volte a inspecionar o XML antes de iniciar a VM.
Inicie o convidado e verifique virsh list --all. Se falhar, leia o primeiro erro do libvirt. Restaure o XML guardado em vez de acumular mais alterações. Um resultado “device not found” aponta para a enumeração ou correspondência no anfitrião; um erro de análise XML aponta para a localização ou sintaxe.
Verifique o dispositivo no HAOS antes de mexer no Zigbee2MQTT
No Home Assistant, abra Definições → Sistema → Hardware e procure o novo dispositivo USB ou série. Os nomes das interfaces, como /dev/ttyACM0, podem mudar; quando o HAOS disponibilizar uma entrada /dev/serial/by-id/..., utilize essa identidade estável no Zigbee2MQTT.
Só depois de o HAOS detetar o dispositivo deverá definir serial.port no Zigbee2MQTT. Reinicie o suplemento e consulte o respetivo registo para confirmar uma ligação bem-sucedida ao adaptador. Se o HAOS detetar o dongle, mas o Zigbee2MQTT não conseguir abri-lo, o passo de passagem já está a funcionar e a falha passou a estar relacionada com o tipo de adaptador, a configuração série ou o acesso do suplemento.
Reinicie o HAOS e, em seguida, reinicie o ZimaOS para testar a persistência. Confirme que o mesmo caminho by-id volta a aparecer e que o Zigbee2MQTT estabelece novamente a ligação. As alterações de recursos do ZVM podem substituir o XML manual em algumas versões, por isso volte a verificar o XML depois de alterar o CPU, a memória, os discos ou atualizar a plataforma.
Perguntas frequentes
Onde está armazenado o ficheiro XML?
Não precisa de localizar manualmente nenhum ficheiro. Utilize virsh edit VM_NAME para editar a definição de domínio registada e virsh dumpxml para criar uma cópia de segurança.
É possível passar vários dispositivos USB para a mesma VM?
Sim, a discussão mostra um bloco hostdev por dispositivo. Cada um tem de corresponder ao hardware pretendido sem ambiguidades.
Porque mudou o caminho USB depois do reinício?
Os nomes abreviados dos dispositivos podem mudar quando o Linux enumera o hardware. Prefira o caminho by-id do HAOS depois da passagem, mas volte a verificar o XML se o dispositivo desaparecer por completo.
Os comandos específicos do HAOS e o exemplo XML posterior encontram-se na discussão sobre a partilha de USB no ZVM.
