Jak programowo odciąć zasilanie zablokowanego urządzenia USB za pomocą uhubctl

Wyobraź sobie typową sytuację: modem 4G zawiesił się na serwerze zdalnym, routerze dacza lub stanowisku testowym. Albo płyta Raspberry Pi przeszła w tryb awaryjny, a kontroler drukarki 3D przestał reagować na polecenia. Zwykły restart systemu operacyjnego nie pomoże, ponieważ zasilanie nadal jest dostarczane do portów USB. Jedyną opcją jest dojazd na miejsce i ręczne odłączenie kabla.

Jeśli nie chcesz pracować jako „administrator wędrowny", przyda ci się narzędzie uhubctl. Vadim Mikhaylov napisał to narzędzie w C w 2015 roku, a projekt nadal jest aktywny. Głównym celem programu jest wysyłanie niskopoziomowych poleceń USB do kontrolera huba, aby fizycznie usunąć napięcie VBUS z określonego portu.

Jak to działa i haczyk sprzętowy

uhubctl nie czyni cudów z niczego. Działa tylko z hubami, w których producent zaimplementował sprzętowe wsparcie dla przełączania zasilania dla poszczególnych portów (PPPS). Zgodnie ze standardami USB 2.0 i USB 3.0, ta specyfikacja istnieje od dawna, ale oszczędzanie na komponentach zasilania oznacza, że wiele tanich hubów łączy zasilanie wszystkich portów w jedną linię.

Jednak na rynku jest wystarczająco dużo kompatybilnych urządzeń. Repozytorium prowadzi szczegółową tabelę z dziesiątkami zweryfikowanych modeli:

• Wbudowane huby w monitorach Dell, LG, BenQ i Acer.
• Komputery jednopłytkowe Raspberry Pi (na modelach 3B+ i 4B można wyłączyć zasilanie, choć z pewnymi niuansami).
• Zewnętrzne huby firm Anker, D-Link, Rosonway i Plugable.
• Płyty główne Asus i przemysłowe kontrolery KUNBUS RevPi.

Pod maską

uhubctl komunikuje się z hubem za pomocą biblioteki libusb lub bezpośrednio przez interfejsy jądra Linux. Jądro Linux 6.0 wprowadziło standardowy mechanizm wyłączania portów przez sysfs. Narzędzie najpierw próbuje tego, a jeśli używasz starszego systemu lub macOS, przełącza się na libusb.

Jest jeden niuans dotyczący USB 3.0. Gdy podłączysz nowoczesny hub do portu USB 3.0, system widzi go jako dwa oddzielne urządzenia logiczne: wirtualny hub USB 2.0 i wirtualny hub USB 3.0. Jeśli odetniesz zasilanie portu tylko w jednej gałęzi, podłączone urządzenie może po prostu przełączyć się na inną prędkość i kontynuować pracę. uhubctl obsługuje tę rutinę za ciebie i wykonuje synchroniczne odłączenie na obu wirtualnych hubach.

Instalacja i szybki start

W większości dystrybucji Linuksa narzędzie jest już dostępne w standardowych repozytoriach:

sudo apt install uhubctl

W przypadku macOS instalacja odbywa się przez Homebrew:

brew install uhubctl

Jeśli twoja dystrybucja ma przestarzałą wersję, kompilacja ze źródeł Git jest prosta. Będziesz potrzebować libusb-1.0 i make:

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

Najpierw powinieneś uruchomić narzędzie bez parametrów, aby zobaczyć listę dostępnych hubów i podłączonych do nich urządzeń:

sudo uhubctl

Polecenie wyświetli topologię magistrali, adresy hubów w formacie 1-1 lub 2-3.1 oraz stan każdego portu.

Przykłady poleceń

Aby odciąć zasilanie od drugiego portu domyślnego huba, uruchom:

sudo uhubctl -a off -p 2

Zamiast akcji off i on, możesz użyć akcji cycle. Wyłącza zasilanie, czeka chwilę i ponownie je włącza. Jest to odpowiednie do twardego resetu zamrożonego sprzętu:

sudo uhubctl -a cycle -p 2 -d 3

Parametr -d 3 ustawia 3-sekundowe opóźnienie przed przywróceniem zasilania. Jeśli musisz zresetować kilka portów jednocześnie, podaj je rozdzielone przecinkami lub myślnikiem: -p 1,3,4 lub -p 1-4.

Konfiguracja praw dostępu w Linuksie

Domyślnie bezpośrednia praca z urządzeniami USB wymaga uprawnień root. Aby uniknąć uruchamiania skryptów przez sudo, dodaj reguły udev do pliku /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\""

Następnie uruchom sudo udevadm trigger --attr-match=subsystem=usb, a uprawnienia zostaną zaktualizowane.

Praktyczne przypadki użycia

Deweloperzy i administratorzy systemów używają uhubctl w różnorodnych zadaniach:

• Automatyczny reset zamrożonych modemów LTE i routerów w farmach monitoringu.
• Sterowanie zewnętrznymi wskaźnikami LED, wentylatorami lub kamerami internetowymi.
• Bezpieczne odłączanie zewnętrznych dysków twardych w celu wyeliminowania pasożytniczego obciążenia i oszczędzania energii.
• Integracja z OctoPrint umożliwia zdalne włączanie i wyłączanie drukarki 3D.
• Testowanie sprzętu w potokach CI/CD, gdy trzeba fizycznie ponownie podłączyć płytkę debugową do stanowiska testowego.

Ograniczenia i specyfika sprzętowa

Przed osadzeniem narzędzia w skryptach powinieneś sprawdzić specyfikę sprzętową swojego systemu. Na przykład w niektórych modelach Raspberry Pi linie zasilania wszystkich czterech portów są połączone równolegle. Próbując wyłączyć jeden port, system odetnie zasilanie wszystkim czterem jednocześnie.

Dodatkowo niektóre gadżety zasilane przez USB nadal pobierają prąd ładowania nawet po odłączeniu linii sygnałowych danych. W takim przypadku pomoże tylko przetestowanie konkretnego huba miernikiem lub opornikiem obciążenia.

Jeśli budujesz autonomiczne stanowisko testowe, inteligentny dom lub zarządzasz serwerami z podłączonymi urządzeniami peryferyjnymi, uhubctl jest jednym z tych kompaktowych narzędzi, które uchronią cię przed długimi wyjazdami do odizolowanego sprzętu. Program jest rozpowszechniany na licencji GPLv2 i rozwiązuje swoje zadanie bez zbędnej złożoności. Najważniejsze przed rozpoczęciem to upewnienie się, że twój hub USB obsługuje zarządzanie zasilaniem.