uhubctl

uhubctl ist ein Dienstprogramm zur Steuerung der USB-Stromversorgung pro Port an intelligenten USB-Hubs. Ein intelligenter Hub ist definiert als einer, der die Stromschaltung pro Port implementiert.

Die ursprüngliche Idee für diesen Code wurde von hub-ctrl.c von Niibe Yutaka inspiriert: https://www.gniibe.org/development/ac-power-control-by-USB-hub

Kompatible USB-Hubs

Beachten Sie, dass nicht viele USB-Hubs die Stromschaltung pro Port korrekt unterstützen. Einige von ihnen werden nicht mehr hergestellt und sind schwer zu finden.

Dies ist eine Liste bekannter kompatibler USB-Hubs:

Diese Tabelle ist bei weitem nicht vollständig. Wenn Ihr Hub mit uhubctl funktioniert, aber oben nicht aufgeführt ist, melden Sie ihn bitte, indem Sie ein neues Issue unter https://github.com/mvp/uhubctl/issues eröffnen, damit wir ihn zur unterstützten Tabelle hinzufügen können. Geben Sie in Ihrem Bericht bitte das genaue Produktmodell an und fügen Sie die Ausgabe von uhubctl hinzu. Bitte testen Sie auch die VBUS-Off-Unterstützung wie unten in den FAQ beschrieben.

Beachten Sie, dass einige moderne Mainboards über integrierte Root-Hubs verfügen, die dieses Feature unterstützen – Sie müssen möglicherweise nicht einmal einen externen Hub kaufen.

Hinweis zur USB-3.0-Dualität

Wenn Sie einen USB-3.0-Hub an einem USB3-Upstream-Port angeschlossen haben, wird er als 2 unabhängige virtuelle Hubs erkannt: USB2 und USB3. Ihre USB-Geräte werden je nach ihren Fähigkeiten und der Verbindungsgeschwindigkeit mit dem virtuellen USB2- oder USB3-Hub verbunden. Um die Stromversorgung solcher Hubs zu steuern, ist es erforderlich, die Stromversorgung an beiden virtuellen Hubs USB2 und USB3 aus-/einzuschalten, damit die Änderungen wirksam werden. uhubctl versucht, dies automatisch zu tun (sofern Sie dieses Verhalten nicht mit der Option -e deaktivieren).

Leider unterbrechen die meisten Hubs zwar die USB-Datenverbindung, aber einige schalten VBUS zum Port möglicherweise weiterhin nicht ab. Das bedeutet, dass ein angeschlossenes Telefon weiterhin über einen Port geladen werden kann, der von uhubctl ausgeschaltet wurde.

Installation

Für Linux und MacOS ist uhubctl in den Standard-Paketmanagern verfügbar und kann mit den folgenden Befehlen installiert werden:

• MacOS: brew install uhubctl oder sudo port install uhubctl
  • ⚠️ MacOS 26+ erfordert libusb 1.0.30 oder später!
• Ubuntu/Debian/Raspbian: sudo apt install uhubctl
• Redhat/EPEL/Fedora/CentOS: sudo yum install uhubctl
• OpenSUSE: sudo zypper install uhubctl
• FreeBSD: cd /usr/ports/sysutils/uhubctl && sudo make install

Allerdings ist die aus einem Standard-Paketmanager installierte Version von uhubctl möglicherweise nicht unbedingt die neueste Version oder hinkt der aktuellen Version sogar stark hinterher. Wenn die zuletzt veröffentlichte Version von uhubctl neuer ist als die, die Ihr Paketmanager anbietet, müssen Sie die Software möglicherweise wie unten beschrieben aus dem Quellcode kompilieren und installieren.

Kompilieren

Dieses Dienstprogramm wurde getestet und kompiliert und funktioniert unter Linux (Ubuntu/Debian/Raspbian, Redhat/EPEL/Fedora/CentOS, Arch Linux, Gentoo, openSUSE, Buildroot), FreeBSD, NetBSD, SunOS und MacOS.

Während uhubctl unter Windows kompiliert, funktioniert die USB-Stromschaltung unter Windows nicht, da libusb den Treiber winusb.sys verwendet, der laut Microsoft notwendige USB-Control-Requests nicht unterstützt. Dies könnte behoben werden, wenn libusb unter Windows einen anderen Treiber unterstützt.

Beachten Sie, dass dringend empfohlen wird, das Dienstprogramm pkgconf (oder pkg-config) installiert zu haben (oft ist es standardmäßig installiert).

Zuerst müssen Sie die Bibliothek libusb-1.0 installieren (Version 1.0.13 oder später ist erforderlich, 1.0.23 oder später wird empfohlen):

• Ubuntu: sudo apt-get install libusb-1.0-0-dev pkgconf
• Redhat: sudo yum install libusb1-devel pkgconf
• OpenSUSE: sudo zypper install libusb-1_0-devel pkgconf
• MacOS: brew install libusb pkgconf oder sudo port install libusb-devel pkgconf
• FreeBSD: pkg install gmake pkgconf (libusb ist standardmäßig enthalten)
• NetBSD: sudo pkgin install libusb1 gmake pkgconf
• Windows: TBD?

Um den uhubctl-Quellcode zu holen und zu kompilieren:

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

Dadurch sollte die Binärdatei uhubctl erzeugt werden. Sie können sie mit folgendem Befehl als /usr/sbin/uhubctl auf Ihrem System installieren:

sudo make install

Beachten Sie, dass Sie auf einigen Betriebssystemen (z. B. FreeBSD/NetBSD) zum Bauen stattdessen gmake verwenden müssen.

Verwendung

⚠️ Verwenden Sie unter Linux sudo oder konfigurieren Sie die USB-Berechtigungen wie unten beschrieben!

Um alle unterstützten Hubs aufzulisten:

uhubctl

Sie können die Stromversorgung eines USB-Ports (oder mehrerer Ports) wie folgt steuern:

uhubctl -a off -p 2

Das bedeutet, dass auf dem standardmäßigen Smart-Hub gearbeitet wird und die Stromversorgung an Port 2 (-p 2) ausgeschaltet wird (-a off oder -a 0). Unterstützte Aktionen sind off/on/cycle/toggle (oder 0/1/2/3). cycle bedeutet, die Stromversorgung auszuschalten, eine Verzögerung abzuwarten (mit -d konfigurierbar) und sie wieder einzuschalten. Ports können als kommagetrennte Liste angegeben werden und dürfen - für Bereiche verwenden, z. B. 2 oder oder oder .> ⚠️ Das Abschalten integrierter USB-Ports kann Ihre Tastatur oder Maus abschalten, seien Sie also vorsichtig, welche Ports Sie abschalten!

Wenn Sie mehr als einen intelligenten USB-Hub angeschlossen haben, sollten Sie den zu steuernden Hub mit dem Parameter -l (Standort) auswählen. Um Hub-Standorte zu finden, führen Sie einfach uhubctl ohne Parameter aus. Hub-Standorte sehen aus wie b-x.y.z, wobei b die USB-Busnummer ist und x, y, z... die Portnummern für alle Hubs in der Kette sind, beginnend mit dem Root-Hub für einen bestimmten USB-Bus. Diese Adresse ist teilstabil - sie ändert sich nicht, wenn Sie ein USB-Gerät in denselben physischen USB-Port ein-/ausstecken (oder ein-/ausschalten) (diese Methode wird auch im Linux-Kernel verwendet).

Linux-USB-Berechtigungen

Unter Linux sollten Sie die udev-USB-Berechtigungen konfigurieren (andernfalls müssen Sie es als Root mit sudo uhubctl ausführen).

Ab Linux-Kernel 6.0 gibt es eine Standardschnittstelle, um USB-Hub-Ports ein- oder auszuschalten, und uhubctl wird versuchen, diese (anstelle von libusb) zu verwenden, um den Portstatus zu setzen. Deshalb gibt es zusätzliche Regeln für 6.0+-Kernel. Es schadet nicht, diese Regeln auf Systemen mit älteren Kernelversionen zu haben.

Um USB-Berechtigungen zu korrigieren, führen Sie zuerst sudo uhubctl aus und notieren Sie alle vid:pid für die Hubs, die Sie steuern müssen. Fügen Sie dann udev-Regeln wie unten gezeigt zur Datei /etc/udev/rules.d/52-usb.rules hinzu (ersetzen Sie 2001 durch Ihre Hub-Anbieter-ID oder entfernen Sie den Filter ATTR{idVendor} vollständig, um Zugriff auf jeden USB-Hub zu erlauben):

SUBSYSTEM=="usb", DRIVER=="hub|usb", MODE="0666", ATTR{idVendor}=="2001"
# Linux 6.0 or later (its ok to have this block present for older Linux kernels):
SUBSYSTEM=="usb", DRIVER=="hub|usb", \
  RUN="/bin/sh -c \"chmod -f 666 $sys$devpath/*port*/disable || true\""

Beachten Sie, dass bei USB3-Hubs einige Hubs unterschiedliche Anbieter-IDs für USB2- bzw. USB3-Komponenten desselben Chips verwenden, und beide benötigen Berechtigungen, damit uhubctl ordnungsgemäß funktioniert. Z. B. müssen Sie für Raspberry Pi 4B diese 2 Zeilen hinzufügen (oder den idVendor-Filter entfernen):

SUBSYSTEM=="usb", DRIVER=="hub|usb", MODE="0666", ATTR{idVendor}=="2109"
SUBSYSTEM=="usb", DRIVER=="hub|usb", MODE="0666", ATTR{idVendor}=="1d6b"

Wenn Ihnen der weit geöffnete Modus 0666 nicht gefällt, können Sie den Zugriff per Gruppe wie folgt einschränken:

SUBSYSTEM=="usb", DRIVER=="hub|usb", MODE="0664", GROUP="dialout"
# Linux 6.0 or later (its ok to have this block present for older Linux kernels):
SUBSYSTEM=="usb", DRIVER=="hub|usb", \
  RUN+="/bin/sh -c \"chown -f root:dialout $sys$devpath/*port*/disable || true\"" \
  RUN+="/bin/sh -c \"chmod -f 660 $sys$devpath/*port*/disable || true\""

und fügen Sie dann erlaubte Benutzer zur Gruppe dialout hinzu:

sudo usermod -a -G dialout $USER

Damit Ihre udev-Regeländerungen wirksam werden, starten Sie neu oder führen Sie aus:

sudo udevadm trigger --attr-match=subsystem=usb

Zu Ihrer Bequemlichkeit ist eine gebrauchsfertige udev-Regel hier bereitgestellt.

FAQ

Was ist die USB-Stromumschaltung pro Port?

Gemäß der USB-2.0-Spezifikation können USB-Hubs keine Stromumschaltung, gemeinsame Stromumschaltung (alle Ports gleichzeitig) oder Stromumschaltung pro Port (einzeln) anbieten. Beachten Sie, dass uhubctl standardmäßig nur USB-Hubs erkennt, die die Stromumschaltung pro Port unterstützen (Sie können es jedoch mit der Option -f zwingen, den Betrieb auf nicht unterstützten Hubs zu versuchen). Sie können herausfinden, welche Art von Stromumschaltung Ihre Hardware unterstützt, indem Sie sudo lsusb -v verwenden:

No power switching:

wHubCharacteristic 0x000a
  No power switching (usb 1.0)
  Per-port overcurrent protection

Ganged power switching:

wHubCharacteristic 0x0008
  Ganged power switching
  Per-port overcurrent protection

Per-port power switching:

wHubCharacteristic 0x0009
  Per-port power switching
  Per-port overcurrent protection

Wie überprüfe ich, ob mein USB-Hub von uhubctl unterstützt wird?

1. Führen Sie sudo uhubctl aus. Wenn Ihr Hub nicht aufgelistet ist, wird er nicht unterstützt. Alternativ können Sie sudo lsusb -v ausführen und nach Per-port power switching suchen - wenn Sie eine solche Zeile in der lsusb-Ausgabe nicht sehen können, wird der Hub nicht unterstützt.
2. Prüfen Sie die Unterstützung für das Abschalten von VBUS (Spannung): Stecken Sie ein Telefon, ein USB-Licht oder einen USB-Lüfter in einen USB-Port Ihres Hubs. Versuchen Sie, mit uhubctl den Strom an diesem Port auszuschalten, und prüfen Sie, ob das Telefon aufhört zu laden, das USB-Licht aufhört zu leuchten oder der USB-Lüfter aufhört, sich zu drehen. Wenn VBUS nicht abgeschaltet wird, hat Ihr Hub-Hersteller keine Schaltung eingebaut, um den Strom tatsächlich zu unterbrechen. Ein solcher Hub würde immer noch funktionieren, um die USB-Datenverbindung zu unterbrechen, aber er kann den Strom nicht abschalten, und wir betrachten dies nicht als unterstütztes Gerät.
3. Wenn die obigen Tests erfolgreich waren, melden Sie Ihren Hub bitte, indem Sie ein neues Issue unter https://github.com/mvp/uhubctl/issues eröffnen, damit wir ihn zur Liste der unterstützten Geräte hinzufügen können. Bitte melden Sie keine nicht unterstützten Hubs, es sei denn, es handelt sich um eine andere Hardware-Revision eines bereits aufgeführten unterstützten Modells.

USB-Geräte werden unter Linux nach dem Abschalten des Ports nicht entfernt

Nach dem Abschalten eines USB-Ports empfängt udev kein Ereignis, sodass es die Gerätedateien behält. Der Versuch, auf die Gerätedateien zuzugreifen, führt jedoch zu einem E/A-Fehler.

Dies ist ein Problem des Linux-Kernels und wurde seit uhubctl 2.5.0 für Systeme mit Linux-Kernel 6.0 oder später behoben.

Wenn Sie noch Linux 5.x oder älter verwenden, können Sie diesen Workaround für dieses Problem verwenden:

sudo uhubctl -a off -l ${location} -p ${port}
sudo udevadm trigger --action=remove /sys/bus/usb/devices/${location}.${port}/

Die Gerätedatei wird von udev entfernt, aber das USB-Gerät bleibt in lsusb sichtbar. Beachten Sie, dass der Pfad /sys/bus/usb/devices/${location}.${port} nur existiert, wenn ein Gerät an diesem Port erkannt wurde. Wenn Sie den Strom wieder einschalten, sollte das Gerät ordnungsgemäß neu enumeriert werden (kein erneuter Aufruf von udevadm erforderlich).

Strom kommt unter Linux nach einigen Sekunden wieder

Einige Gerätetreiber im Kernel sind überrascht, wenn ein USB-Gerät abgeschaltet wird, und versuchen automatisch, es wieder einzuschalten.

Dies ist ein Problem des Linux-Kernels und wurde seit uhubctl 2.5.0 für Systeme mit Linux-Kernel 6.0 oder später behoben.

Wenn Sie noch Linux 5.x oder älter verwenden:

Sie können die Option -r N verwenden, wobei N eine Zahl zwischen 10 und 1000 ist, um dies zu beheben - uhubctl versucht dann, den Strom viele Male in schneller Folge abzuschalten, und das sollte das unterdrücken.

Das Deaktivieren der USB-Autorisierung für das betreffende Gerät vor dem Abschalten des Stroms mit uhubctl sollte helfen:

echo 0 > sudo tee /sys/bus/usb/devices/${location}.${port}/authorized

Wenn Ihr Gerät ein USB-Massenspeicher ist, sollte auch der Aufruf von udisksctl vor dem Aufruf von uhubctl helfen:

sudo udisksctl power-off --block-device /dev/disk/...`
sudo uhubctl -a off ...

Mehrere 4-Port-Hubs werden erkannt, aber ich habe nur einen 7-Port-Hub angeschlossen

Viele Hub-Hersteller bauen ihre USB-Hubs mit einfachen 4-Port-USB-Chips. Um beispielsweise einen 7-Port-Hub herzustellen, verdrahten sie zwei 4-Port-Hubs in Reihe (Daisy-Chain) - 1 Port geht durch die Verkettung verloren, sodass ein 4+4-1=7-Port-Hub entsteht. Ebenso könnte ein 10-Port-Hub aus 3 in Reihe geschalteten 4-Port-Hubs aufgebaut sein, was 4+4+4-2=10 nutzbare Ports ergibt.

Beachten Sie, dass Sie niemals versuchen sollten, den Stromzustand von Ports zu ändern, die zur Verkettung interner Hubs verwendet werden. Andernfalls wird die interne Hub-Schaltung gestört und ein unvorhersehbares Verhalten verursacht.

Raspberry Pi schaltet den Strom auf allen Ports ab, nicht nur auf dem von mir angegebenen

Das ist eine Einschränkung des Hardware-Designs des Raspberry Pi. Als Workaround können Sie einen beliebigen externen USB-Hub aus der obigen Liste unterstützter Geräte kaufen, ihn an einen beliebigen USB-Port des Raspberry Pi anschließen und den Strom an dessen Ports unabhängig steuern. Es gibt auch unterstützte Hubs, die speziell für den Raspberry Pi entwickelt wurden, z. B. UUGear MEGA4.

Zur Referenz: Unterstützte Raspberry-Pi-Modelle haben die folgende interne USB-Topologie:

Raspberry Pi B+,2B,3B

• Ein einzelner Hub 1-1, Ports 2-5 zusammengefasst, alle von Port 2 gesteuert:

  root@kitploit:~

  uhubctl -l 1-1 -p 2 -a 0
  

  Der Versuch, die Ports 3,4,5 zu steuern, bewirkt nichts. Port 1 steuert die Stromversorgung für Ethernet+WiFi.

Raspberry Pi 3B+

• Haupt-Hub 1-1, alle 4 Ports zusammengefasst, alle von Port 2 gesteuert (schaltet auch die Ports des Sekundär-Hubs ab). Port 1 verbindet den Hub 1-1.1 unten, die Ports 2 und 3 sind nach außen geführt, Port 4 ist nicht verdrahtet.

  root@kitploit:~

  uhubctl -l 1-1 -p 2 -a 0
  

• Sekundär-Hub 1-1.1 (mit dem Haupt-Hub verkettet): 3 Ports, Port 1 wird für Ethernet+WiFi verwendet, und die Ports 2 und 3 sind nach außen geführt.

Raspberry Pi 4B

⚠️ Wenn Ihre VL805-Firmware älter als 00137ad ist (prüfen Sie mit sudo rpi-eeprom-update), müssen Sie die Firmware aktualisieren, damit die Stromumschaltung auf dem RPi 4B funktioniert.

• USB2-Hub 1, 1 Port, verbindet nur den Hub 1-1 unten.

• USB2-Hub 1-1, 4 Ports zusammengefasst, Gegenstück zum USB3-Hub 2 unten:

  root@kitploit:~

  uhubctl -l 1-1 -a 0
  

• USB3-Hub 2, 4 Ports zusammengefasst, Gegenstück zum USB2-Hub 1-1 oben:

  root@kitploit:~

  uhubctl -l 2 -a 0
  

• USB2-Hub 3, 1 Port, OTG-Controller. Die Stromumschaltung wird nicht unterstützt.

Raspberry Pi 5

Der Raspberry Pi 5 hat zwei USB2-Ports und zwei USB3-Ports (insgesamt 4). Diese Ports sind in einer wirklich seltsamen Konfiguration mit 4 verschiedenen USB-Hubs 1,2,3,4 verbunden (abhängig von Betriebssystem und Hardware-Revision können die betreffenden Hubs jedoch 2,3,4,5 sein). Wenn ein USB3-Gerät an eine blaue Buchse angeschlossen ist, wird es am USB3-Hub 2 oder 4 erkannt. Wenn ein USB2-Gerät an eine beliebige Buchse oder ein USB3-Gerät an eine schwarze Buchse angeschlossen ist, wird es am USB2-Hub 1 oder 3 erkannt. Unabhängig vom USB2/USB3-Verbindungstyp sind blaue Buchsen immer Port 1, und schwarze Buchsen immer Port 2.

Jeder der 4 integrierten USB-Hubs wirbt damit, die Stromumschaltung pro Port zu unterstützen, aber das stimmt nicht. In Wirklichkeit sind beim Raspberry Pi 5 alle 4 Ports in einer Gruppe zusammengefasst, obwohl sie zu 4 verschiedenen logischen USB-Hubs gehören.

Um die VBUS-Stromversorgung abzuschalten, muss sie über alle integrierten Hubs und Ports hinweg deaktiviert werden mit: ``` uhubctl -l 2 -a 0 uhubctl -l 4 -a 0

Um es wieder zu aktivieren:   ```
uhubctl -l 2 -a 1
uhubctl -l 4 -a 1

Hinweis: Die VBUS-Stromversorgung wird nur abgeschaltet, wenn alle Ports aus sind - das Einschalten eines einzelnen Ports aktiviert VBUS für alle 4 Ports wieder.

Bemerkenswerte Projekte, die uhubctl verwenden

Urheberrecht

Copyright (C) 2009-2026 Vadim Mikhailov

Diese Datei darf unter den Bedingungen der GNU General Public License Version 2 verbreitet werden.