Come Disattivare Programmativamente l'Alimentazione di un Dispositivo USB Bloccato Usando uhubctl

Immaginiamo una situazione comune: un modem 4G si è bloccato su un server remoto, un router in dacia o un banco di test. Oppure una scheda Raspberry Pi è passata a una modalità anomala e un controller di stampante 3D ha smesso di rispondere ai comandi. Un normale riavvio del sistema operativo non aiuta perché l'alimentazione continua a essere fornita alle porte USB. L'unica opzione è recarsi sul posto e scollegare manualmente il cavo.

Se non vuoi fare l'amministratore itinerante, l'utility uhubctl ti sarà utile. Vadim Mikhaylov ha scritto questo strumento in C nel 2015 e il progetto è ancora attivo. Lo scopo principale del programma è inviare comandi USB di basso livello al controller dell'hub in modo che rimuova fisicamente la tensione VBUS da una porta specifica.

Come Funziona e il Problema Hardware

uhubctl non compie miracoli dal nulla. Funziona solo con hub in cui il produttore ha implementato il supporto hardware per il power switching per porta (PPPS). Secondo gli standard USB 2.0 e USB 3.0, questa specifica esiste da tempo, ma il risparmio sui componenti di alimentazione fa sì che molti hub economici combinino l'alimentazione di tutte le porte in una singola linea.

Ciononostante, ci sono abbastanza dispositivi compatibili sul mercato. Il repository mantiene una tabella dettagliata con decine di modelli verificati:

• Hub integrati nei monitor Dell, LG, BenQ e Acer.
• Computer a scheda singola Raspberry Pi (sui modelli 3B+ e 4B, è possibile disattivare l'alimentazione, sebbene con alcune sfumature).
• Hub esterni di Anker, D-Link, Rosonway e Plugable.
• Schede madri Asus e controller industriali KUNBUS RevPi.

Sotto il Cofano

uhubctl comunica con l'hub tramite la libreria libusb o direttamente attraverso le interfacce del kernel Linux. Il kernel Linux 6.0 ha introdotto un meccanismo standard per la disattivazione delle porte tramite sysfs. L'utility prova prima questo, e se stai eseguendo un sistema più vecchio o macOS, passa a libusb.

C'è una sfumatura con USB 3.0. Quando colleghi un hub moderno a una porta USB 3.0, il sistema lo vede come due dispositivi logici separati: un hub virtuale USB 2.0 e un hub virtuale USB 3.0. Se disattivi l'alimentazione alla porta solo su un ramo, il dispositivo collegato potrebbe semplicemente passare all'altra velocità e continuare a funzionare. uhubctl gestisce questa routine automaticamente e esegue una disconnessione sincrona su entrambi gli hub virtuali.

Installazione e Avvio Rapido

Nella maggior parte delle distribuzioni Linux, l'utility è già disponibile nei repository standard:

sudo apt install uhubctl

Per macOS, l'installazione avviene tramite Homebrew:

brew install uhubctl

Se la tua distribuzione ha una versione obsoleta, compilare dai sorgenti Git è semplice. Avrai bisogno di libusb-1.0 e make:

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

Prima di tutto, dovresti eseguire l'utility senza parametri per vedere un elenco degli hub disponibili e dei dispositivi collegati:

sudo uhubctl

Il comando mostrerà la topologia del bus, gli indirizzi degli hub nel formato 1-1 o 2-3.1 e lo stato di ciascuna porta.

Esempi di Comandi

Per disattivare l'alimentazione alla seconda porta sull'hub predefinito, esegui:

sudo uhubctl -a off -p 2

Al posto di off e on, puoi passare l'azione cycle. Disattiva l'alimentazione, attende una breve pausa e la riaccende. Questo è adatto per un hard reset di apparecchiature bloccate:

sudo uhubctl -a cycle -p 2 -d 3

Il parametro -d 3 imposta un ritardo di 3 secondi prima di ripristinare l'alimentazione. Se devi resettare diverse porte contemporaneamente, specificale separate da virgole o un trattino: -p 1,3,4 o -p 1-4.

Configurazione dei Diritti di Accesso in Linux

Di default, lavorare direttamente con i dispositivi USB richiede privilegi di root. Per evitare di eseguire script tramite sudo, aggiungi regole udev al file /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\""

Dopo di che, esegui sudo udevadm trigger --attr-match=subsystem=usb e i permessi si aggiorneranno.

Casi d'Uso Pratici

Gli sviluppatori e gli amministratori di sistema usano uhubctl in una vasta gamma di attività:

• Reset automatico di modem LTE e router bloccati nelle farm di monitoraggio.
• Controllo di indicatori LED esterni, ventole o webcam.
• Scollegamento sicuro di hard disk esterni per eliminare il carico fantasma e risparmiare energia.
• Integrazione con OctoPrint per accendere e spegnere da remoto una stampante 3D.
• Test hardware nelle pipeline CI/CD quando è necessario riconnettere fisicamente una scheda di debug al banco di test.

Limitazioni e Specifiche Hardware

Prima di integrare l'utility nei tuoi script, dovresti verificare le specifiche hardware del tuo sistema. Ad esempio, su alcuni modelli Raspberry Pi, le linee di alimentazione di tutte e quattro le porte sono collegate in parallelo. Quando si tenta di spegnere una porta, il sistema disattiverà l'alimentazione a tutte e quattro contemporaneamente.

Inoltre, alcuni gadget alimentati tramite USB continuano ad assorbire corrente di ricarica anche se le linee del segnale dati sono scollegate. In questo caso, solo testare l'hub specifico con un multimetro o una resistenza di carico ti aiuterà.

Se stai costruendo un banco di test autonomo, una casa intelligente o gestendo server con periferiche collegate, uhubctl è uno di quegli strumenti compatti che ti salvano da lunghi viaggi verso hardware bloccato. Il programma è distribuito sotto la licenza GPLv2 e risolve il suo compito senza complessità superflua. La cosa principale prima di iniziare è assicurarti che il tuo hub USB supporti la gestione dell'alimentazione.