Comment couper électriquement un périphérique USB bloqué par programme avec uhubctl

Imaginez une situation courante : un modem 4G s'est bloqué sur un serveur distant, un routeur de datcha ou un banc de test. Ou bien une carte Raspberry Pi est passée en mode anormal et un contrôleur d'imprimante 3D ne répond plus aux commandes. Un redémarrage classique de l'OS ne résout rien car l'alimentation continue d'être fournie aux ports USB. La seule option est de se rendre sur place et de débrancher manuellement le câble.

Si vous ne voulez pas travailler en tant qu'« administrateur itinérant », l'utilitaire uhubctl vous sera utile. Vadim Mikhaylov a écrit cet outil en C en 2015, et le projet est toujours actif. L'objectif principal du programme est d'envoyer des commandes USB de bas niveau au contrôleur de hub afin qu'il supprime physiquement la tension VBUS d'un port spécifique.

Comment ça fonctionne et les pièges matériels

uhubctl ne fait pas de miracles à partir de rien. Il fonctionne uniquement avec les hubs dont le fabricant a implémenté la prise en charge matérielle du commutation d'alimentation par port (PPPS). Selon les normes USB 2.0 et USB 3.0, cette spécification existe depuis longtemps, mais les économies réalisées sur les composants d'alimentation font que de nombreux hubs bon marché combinent l'alimentation de tous les ports en une seule ligne.

Néanmoins, il y a suffisamment d'appareils compatibles sur le marché. Le dépôt maintient un tableau détaillé avec des dizaines de modèles vérifiés :

• Hubs intégrés dans les moniteurs Dell, LG, BenQ et Acer.
• Ordinateurs monocarte Raspberry Pi (sur les modèles 3B+ et 4B, vous pouvez désactiver l'alimentation, bien qu'avec quelques nuances).
• Hubs externes d'Anker, D-Link, Rosonway et Plugable.
• Cartes mères Asus et contrôleurs industriels KUNBUS RevPi.

Sous le capot

uhubctl communique avec le hub via la bibliothèque libusb ou directement à travers les interfaces du noyau Linux. Le noyau Linux 6.0 a introduit un mécanisme standard pour désactiver les ports via sysfs. L'utilitaire essaie d'abord cette méthode, et si vous utilisez un système plus ancien ou macOS, il bascule sur libusb.

Il y a une nuance avec USB 3.0. Lorsque vous connectez un hub moderne à un port USB 3.0, le système le voit comme deux appareils logiques séparés : un hub virtuel USB 2.0 et un hub virtuel USB 3.0. Si vous coupez l'alimentation du port sur une seule branche, l'appareil connecté peut simplement basculer vers l'autre vitesse et continuer à fonctionner. uhubctl gère cette routine pour vous et effectue une déconnexion synchrone sur les deux hubs virtuels.

Installation et démarrage rapide

Dans la plupart des distributions Linux, l'utilitaire est déjà disponible dans les dépôts standards :

sudo apt install uhubctl

Pour macOS, l'installation se fait via Homebrew :

brew install uhubctl

Si votre distribution propose une version obsolète, la compilation à partir des sources Git est simple. Vous aurez besoin de libusb-1.0 et make :

git clone https://github.com/mvp/uhubctl
cd uhubctl
make
sudo make install

D'abord, vous devriez exécuter l'utilitaire sans paramètres pour voir la liste des hubs disponibles et des appareils qui y sont connectés :

sudo uhubctl

La commande affichera la topologie du bus, les adresses des hubs au format 1-1 ou 2-3.1, et l'état de chaque port.

Exemples de commandes

Pour couper l'alimentation du deuxième port sur le hub par défaut, exécutez :

sudo uhubctl -a off -p 2

Au lieu de off et on, vous pouvez passer l'action cycle. Elle désactive l'alimentation, attend une courte pause, puis la rallume. C'est adapté pour une réinitialisation matérielle des équipements bloqués :

sudo uhubctl -a cycle -p 2 -d 3

Le paramètre -d 3 définit un délai de 3 secondes avant de restaurer l'alimentation. Si vous devez réinitialiser plusieurs ports à la fois, spécifiez-les séparés par des virgules ou un tiret : -p 1,3,4 ou -p 1-4.

Configuration des droits d'accès dans Linux

Par défaut, travailler directement avec les périphériques USB nécessite les privilèges root. Pour éviter d'exécuter les scripts via sudo, ajoutez des règles udev au fichier /etc/udev/rules.d/52-usb.rules :

SUBSYSTEM=="usb", DRIVER=="hub|usb", MODE="0666" SUBSYSTEM=="usb", DRIVER=="hub|usb", RUN="/bin/sh -c \"chmod -f 666 $sys$devpath/*port*/disable || true\""

Après cela, exécutez sudo udevadm trigger --attr-match=subsystem=usb, et les permissions seront mises à jour.

Cas d'utilisation pratiques

Les développeurs et administrateurs système utilisent uhubctl dans une grande variété de tâches :

• Réinitialisation automatique des modems LTE et routeurs bloqués dans les fermes de surveillance.
• Contrôle des indicateurs LED externes, ventilateurs ou webcams.
• Déconnexion sécurisée des disques durs externes pour éliminer la charge fantôme et économiser l'énergie.
• Intégration avec OctoPrint pour allumer et éteindre à distance une imprimante 3D.
• Tests matériels dans les pipelines CI/CD lorsqu'il faut reconnecter physiquement une carte de débogage au banc de test.

Limitations et spécificités matérielles

Avant d'intégrer l'utilitaire dans vos scripts, vous devriez vérifier les spécificités matérielles de votre système. Par exemple, sur certains modèles de Raspberry Pi, les lignes d'alimentation des quatre ports sont connectées en parallèle. Lorsqu'on essaie de désactiver un port, le système coupera l'alimentation des quatre ports à la fois.

De plus, certains gadgets alimentés par USB continuent de consommer du courant de charge même si les lignes de signal de données sont déconnectées. Dans ce cas, seul le test du hub spécifique avec un multimètre ou une résistance de charge vous aidera.

Si vous construisez un banc de test autonome, une maison intelligente ou gérez des serveurs avec des périphériques connectés, uhubctl est l'un de ces outils compacts qui vous évitent de longs déplacements vers du matériel en panne. Le programme est distribué sous licence GPLv2 et résout sa tâche sans complexité inutile. L'essentiel avant de commencer est de vous assurer que votre hub USB prend en charge la gestion de l'alimentation.