usbipd-win — USB no WSL2

O WSL2 roda numa VM e não enxerga dispositivos USB do Windows por padrão. O usbipd-win compartilha um dispositivo USB do Windows com o WSL via protocolo USB/IP. Uso típico: gravar/monitorar placas como a ESP32 C3 Supermini (Tenstar Robot) com o ESP-IDF rodando dentro do WSL.

---

O que é o BUSID

Identificador da porta USB física onde o dispositivo está conectado no Windows, no formato X-Y (ex: 1-4, 2-1). É ele que diz ao usbipd qual dispositivo encaminhar.

• Depende da porta física: trocou a placa de porta → BUSID muda → precisa de bind de novo.
• Não confundir com VID:PID, que identifica o modelo do dispositivo (fabricante:produto) e não muda.

---

Passo a passo

1. Instalar (uma vez) — PowerShell

winget install --exact dorssel.usbipd-win

Alternativa: instalar o .msi das releases.

Abra um novo terminal depois de instalar

O instalador adiciona o usbipd ao PATH, mas terminais já abertos não veem a mudança e continuam dando The term 'usbipd' is not recognized.... Feche e abra o PowerShell de novo.

2. Identificar o BUSID — PowerShell

usbipd list

Exemplo de saída:

Connected:
BUSID  VID:PID    DEVICE                                                   STATE
1-3    046d:c52b  Logitech USB Input Device                                Not shared
1-4    303a:1001  USB Serial Device (COM5), USB JTAG/serial debug unit      Not shared
2-1    8087:0026  Intel(R) Wireless Bluetooth(R)                           Not shared

Como achar o dispositivo certo:

• Pelo VID:PID. ESP32-C3/S3/C6 com USB nativo (USB Serial/JTAG) = 303a:1001 (303a = Espressif). Placas com conversor USB-serial aparecem com o VID do conversor: CH340 = 1a86:7523, CP2102 = 10c4:ea60.
• Se ficar em dúvida: rode usbipd list com a placa desconectada e depois conectada. A linha nova é ela.

3. Bind — PowerShell como Administrador (uma vez por dispositivo/porta)

usbipd bind --busid 1-4

O bind marca o dispositivo como compartilhável (STATE vira Shared). Isso persiste entre reboots. Só precisa de admin nesse passo.

4. Attach — PowerShell (a cada sessão / reconexão)

usbipd attach --wsl --busid 1-4

STATE vira Attached. Enquanto estiver attached, o Windows perde acesso ao dispositivo (a COM some do Windows).

Para reconectar automaticamente (útil porque gravar o firmware reseta o chip e re-enumera o USB):

usbipd attach --wsl --busid 1-4 --auto-attach

Esse comando fica rodando no terminal; feche com Ctrl+C para parar.

5. Usar no Linux (WSL)

lsusb                  # deve listar o dispositivo (ex: 303a:1001 Espressif USB JTAG/serial debug unit)
ls /dev/ttyACM* /dev/ttyUSB*

• USB nativo (USB Serial/JTAG, CDC-ACM) → /dev/ttyACM0
• Conversor CH340/CP2102 → /dev/ttyUSB0

Se der erro de permissão ao abrir a porta:

sudo usermod -aG dialout $USER   # depois sair e entrar de novo no WSL (wsl --shutdown)

Exemplo com ESP-IDF:

idf.py -p /dev/ttyACM0 flash monitor

6. Devolver o dispositivo ao Windows — PowerShell

usbipd detach --busid 1-4      # volta pro Windows, mantém o bind
usbipd unbind --busid 1-4      # (opcional, admin) remove o compartilhamento

---

Resumo rápido

Onde	Comando	Quando
PowerShell	winget install usbipd	uma vez
PowerShell	usbipd list	achar o BUSID
PowerShell (Admin)	usbipd bind --busid <BUSID>	uma vez por dispositivo/porta
PowerShell	usbipd attach --wsl --busid <BUSID>	a cada sessão
WSL	ls /dev/ttyACM*	conferir a porta
PowerShell	usbipd detach --busid <BUSID>	devolver ao Windows

---

Usado em

• Firmware ESP32 - Bomba de Poco