Como Desligar Programaticamente a Alimentação de um Dispositivo USB Travado Usando uhubctl

Imagine uma situação comum: um modem 4G travou em um servidor remoto, um roteador de casa de campo ou uma bancada de testes. Ou uma placa Raspberry Pi mudou para um modo anormal, e um controlador de impressora 3D parou de responder aos comandos. Uma reinicialização normal do SO não ajuda porque a energia continua sendo fornecida às portas USB. A única opção é ir até o local e desconectar manualmente o cabo.

Se você não quer trabalhar como um "administrador ambulante", o utilitário uhubctl será útil. Vadim Mikhaylov escreveu esta ferramenta em C em 2015, e o projeto ainda está ativo. O objetivo principal do programa é enviar comandos USB de baixo nível para o controlador do hub, para que ele remova fisicamente a tensão VBUS de uma porta específica.

Como Funciona e o Detalhe com o Hardware

uhubctl não faz milagres do nada. Ele só funciona com hubs onde o fabricante implementou suporte de hardware para comutação de energia por porta (PPPS). De acordo com os padrões USB 2.0 e USB 3.0, esta especificação existe há muito tempo, mas a redução de custos nos componentes de energia significa que muitos hubs baratos combinam a energia de todas as portas em uma única linha.

No entanto, há dispositivos compatíveis suficientes no mercado. O repositório mantém uma tabela detalhada com dezenas de modelos verificados:

• Hubs integrados em monitores Dell, LG, BenQ e Acer.
• Computadores de placa única Raspberry Pi (nos modelos 3B+ e 4B, você pode desativar a energia, embora com algumas nuances).
• Hubs externos da Anker, D-Link, Rosonway e Plugable.
• Placas-mãe Asus e controladores industriais KUNBUS RevPi.

Por Trás dos Panos

uhubctl se comunica com o hub através da biblioteca libusb ou diretamente através das interfaces do kernel Linux. O kernel Linux 6.0 introduziu um mecanismo padrão para desativar portas através do sysfs. O utilitário tenta isso primeiro, e se você estiver executando um sistema mais antigo ou macOS, ele alterna para a libusb.

Há uma nuance com USB 3.0. Quando você conecta um hub moderno a uma porta USB 3.0, o sistema o vê como dois dispositivos lógicos separados: um hub virtual USB 2.0 e um hub virtual USB 3.0. Se você cortar a energia da porta apenas em um ramo, o dispositivo conectado pode simplesmente mudar para a outra velocidade e continuar funcionando. uhubctl lida com essa rotina para você e executa uma desconexão síncrona em ambos os hubs virtuais.

Instalação e Início Rápido

Na maioria das distribuições Linux, o utilitário já está disponível nos repositórios padrão:

Para macOS, a instalação é feita através do Homebrew:

Se sua distribuição tiver uma versão desatualizada, compilar a partir das fontes Git é direto. Você precisará de libusb-1.0 e make:

Primeiro, você deve executar o utilitário sem parâmetros para ver uma lista de hubs disponíveis e dispositivos conectados a eles:

O comando produzirá a topologia do barramento, endereços de hubs no formato 1-1 ou 2-3.1 e o estado de cada porta.

Exemplos de Comandos

Para cortar a energia da segunda porta no hub padrão, execute:

Em vez de off e on, você pode passar a ação cycle. Ela desativa a energia, espera uma pequena pausa e a religa. Isso é adequado para uma reinicialização forçada de equipamentos travados:

O parâmetro -d 3 define um atraso de 3 segundos antes de restaurar a energia. Se você precisar redefinir várias portas de uma vez, especifique-as separadas por vírgulas ou um hífen: -p 1,3,4 ou -p 1-4.

Configurando Direitos de Acesso no Linux

Por padrão, trabalhar diretamente com dispositivos USB requer privilégios de root. Para evitar executar scripts através de sudo, adicione regras udev ao arquivo /etc/udev/rules.d/52-usb.rules:

Depois disso, execute sudo udevadm trigger --attr-match=subsystem=usb, e as permissões serão atualizadas.

Casos de Uso Práticos

Desenvolvedores e administradores de sistemas usam uhubctl em uma grande variedade de tarefas:

• Reinicialização automática de modems LTE e roteadores travados em farms de monitoramento.
• Controle de indicadores LED externos, ventiladores ou webcams.
• Desconexão segura de discos rígidos externos para eliminar carga fantasma e economizar energia.
• Integração com OctoPrint para ligar e desligar remotamente uma impressora 3D.
• Teste de hardware em pipelines CI/CD quando você precisa fisicamente reconectar uma placa de depuração à bancada de testes.

Limitações e Especificações de Hardware

Antes de incorporar o utilitário em seus scripts, você deve verificar as especificações de hardware do seu sistema. Por exemplo, em alguns modelos de Raspberry Pi, as linhas de energia das quatro portas são conectadas em paralelo. Ao tentar desligar uma porta, o sistema cortará a energia de todas as quatro de uma vez.

Além disso, alguns gadgets alimentados por USB continuam consumindo corrente de carregamento mesmo se as linhas de sinal de dados forem desconectadas. Neste caso, apenas testar o hub específico com um multímetro ou resistor de carga ajudará.

Se você está construindo uma bancada de testes autônoma, uma casa inteligente ou gerenciando servidores com periféricos conectados, uhubctl é uma daquelas ferramentas compactas que o poupam de longas viagens até hardware encravado. O programa é distribuído sob a licença GPLv2 e resolve sua tarefa sem complexidade desnecessária. O principal antes de começar é garantir que seu hub USB suporta gerenciamento de energia.