Zo schakel je programmatisch de stroom uit van een vastgelopen USB-apparaat met uhubctl

Stel je een veelvoorkomende situatie voor: een 4G-modem is vastgelopen op een externe server, een datsja-router of een testbank. Of een Raspberry Pi-bord is overgeschakeld naar een abnormale modus en een 3D-printercontroller reageert niet meer op commando's. Een normale OS-herstart helpt niet omdat er stroom naar de USB-poorten blijft. De enige optie is om naar de locatie te rijden en de kabel handmatig los te koppelen.

Als je niet als "rondlopende beheerder" wilt werken, komt het hulpprogramma uhubctl goed van pas. Vadim Mikhaylov schreef dit hulpprogramma in 2015 in C, en het project is nog steeds actief. Het hoofddoel van het programma is het verzenden van low-level USB-commando's naar de hub-controller, zodat deze fysiek de VBUS-spanning van een specifieke poort verwijdert.

Hoe het werkt en de hardwarevalkuil

uhubctl voert geen mirakels uit uit het niets. Het werkt alleen met hubs waarvan de fabrikant hardware-ondersteuning heeft geïmplementeerd voor per-poort stroomomschakeling (PPPS). Volgens de USB 2.0- en USB 3.0-standaarden bestaat deze specificatie al lang, maar kostenbesparing op stroomcomponenten betekent dat veel goedkope hubs de stroom van alle poorten combineren in één enkele lijn.

Toch zijn er genoeg compatibele apparaten op de markt. De repository onderhoudt een gedetailleerde tabel met tientallen geverifieerde modellen:

• Ingebouwde hubs in Dell-, LG-, BenQ- en Acer-monitoren.
• Raspberry Pi single-board computers (op modellen 3B+ en 4B kun je de stroom uitschakelen, zij het met enkele nuances).
• Externe hubs van Anker, D-Link, Rosonway en Plugable.
• Asus-moederbord en KUNBUS RevPi industriële controllers.

Onder de motorkap

uhubctl communiceert met de hub via de libusb-bibliotheek of rechtstreeks via Linux-kernelinterfaces. Linux-kernel 6.0 introduceerde een standaardmechanisme voor het uitschakelen van poorten via sysfs. Het hulpprogramma probeert dit eerst, en als je een ouder systeem of macOS gebruikt, schakelt het over naar libusb.

Er is één nuance bij USB 3.0. Wanneer je een moderne hub aansluit op een USB 3.0-poort, ziet het systeem deze als twee afzonderlijke logische apparaten: een virtuele USB 2.0-hub en een virtuele USB 3.0-hub. Als je de stroom naar de poort alleen op één tak uitschakelt, kan het aangesloten apparaat gewoon overschakelen naar de andere snelheid en gewoon doorgaan. uhubctl handelt deze routine voor je af en voert een synchrone ontkoppeling uit op beide virtuele hubs.

Installatie en snelstart

In de meeste Linux-distributies is het hulpprogramma al beschikbaar in de standaard repositories:

Voor macOS gaat de installatie via Homebrew:

Als je distributie een verouderde versie heeft, is compileren vanaf Git-bronnen eenvoudig. Je hebt en nodig:

Eerst moet je het hulpprogramma zonder parameters uitvoeren om een lijst met beschikbare hubs en apparaten die erop zijn aangesloten te zien:

Het commando toont de bus-topologie, hub-adressen in - of -formaat, en de status van elke poort.

Commando-voorbeelden

Om de stroom naar de tweede poort op de standaard hub uit te schakelen, voer je uit:

In plaats van en kun je de -actie doorgeven. Het schakelt de stroom uit, wacht even en schakelt deze weer in. Dit is geschikt voor een harde reset van vastgelopen apparatuur:

De -parameter stelt een vertraging van 3 seconden in voordat de stroom wordt hersteld. Als je meerdere poorten tegelijk moet resetten, geef je ze gescheiden door komma's of een streepje op: of .

Toegangsrechten configureren in Linux

Standaard vereist direct werken met USB-apparaten root-privileges. Om te voorkomen dat je scripts via uitvoert, voeg je udev-regels toe aan het -bestand:

Voer daarna uit, en de machtigingen worden bijgewerkt.

Praktische gebruiksscenario's

Ontwikkelaars en systeembeheerders gebruiken uhubctl in een grote verscheidenheid aan taken:

• Automatisch resetten van vastgelopen LTE-modems en routers in monitoringfarms.
• Besturing van externe LED-indicatoren, ventilatoren of webcams.
• Veilig loskoppelen van externe harde schijven om fantoombelasting te elimineren en energie te besparen.
• Integratie met OctoPrint voor het op afstand in- en uitschakelen van een 3D-printer.
• Hardwaretesten in CI/CD-pipelines wanneer je een debugbord fysiek opnieuw moet aansluiten op de testbank.

Beperkingen en hardwarespecificaties

Voordat je het hulpprogramma in je scripts integreert, moet je de hardwarespecificaties van je systeem controleren. Op sommige Raspberry Pi-modellen zijn bijvoorbeeld de stroomlijnen van alle vier de poorten parallel geschakeld. Bij het uitschakelen van één poort schakelt het systeem de stroom naar alle vier tegelijk uit.

Bovendien blijven sommige USB-gevoede gadgets laadstroom trekken, zelfs als de datalijnen zijn losgekoppeld. In dit geval helpt alleen het testen van de specifieke hub met een multimeter of belastingsweerstand.

Als je een autonome testbank, een smart home of servers met aangesloten randapparatuur bouwt, is uhubctl een van die compacte hulpprogramma's die je lange reizen naar gestrande hardware besparen. Het programma wordt gedistribueerd onder de GPLv2-licentie en lost zijn taak op zonder onnodige complexiteit. Het belangrijkste voor het starten is om ervoor te zorgen dat je USB-hub stroombeheer ondersteunt.