uhubctl

uhubctl は、スマートUSBハブのポートごとのUSB電源を制御するユーティリティです。 スマートハブとは、ポートごとの電源切り替えを実装しているハブを指します。

このコードの元のアイデアは、Niibe Yutaka による hub-ctrl.c に触発されました： https://www.gniibe.org/development/ac-power-control-by-USB-hub

互換性のあるUSBハブ

ポートごとの電源切り替えを正しくサポートしているUSBハブは多くないことに注意してください。 一部の製品はもう製造されておらず、見つけるのが難しい場合があります。

以下は、互換性が確認されているUSBハブのリストです：

この表は決して完全なものではありません。 あなたのハブが uhubctl で動作し、上記にリストされていない場合は、 新しい Issue を https://github.com/mvp/uhubctl/issues で報告してください。 報告の際は、正確な製品モデルと uhubctl の出力を提供し、 FAQ に記載されている VBUS オフのサポートをテストしてください。

最近のマザーボードの多くには、この機能をサポートする内蔵ルートハブが組み込まれていることに注意してください。外部ハブを購入する必要はないかもしれません。

USB 3.0 の二重性に関する注意

USB 3.0 ハブを USB3 アップストリームポートに接続すると、2つの独立した仮想ハブ (USB2 と USB3) として検出され、USB デバイスはその機能と接続速度に応じて USB2 または USB3 の仮想ハブに接続されます。 このようなハブの電源を制御するには、電源のオフ/オンを有効にするために、両方の USB2 および USB3 仮想ハブの電源をオフ/オンする必要があります。uhubctl はこれを自動的に行おうとします（この動作は -e オプションで無効にできます）。

残念ながら、ほとんどのハブはデータ USB 接続を切断しますが、一部のハブはポートへの VBUS を切断しない場合があります。そのため、接続された電話が uhubctl で電源オフにされたポートから充電を続ける可能性があります。

インストール

Linux および MacOS では、uhubctl は標準のパッケージマネージャで利用可能で、以下のコマンドでインストールできます：

• MacOS: brew install uhubctl または sudo port install uhubctl
  • ⚠️ MacOS 26+ では libusb 1.0.30 以降が必要です！
• 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

ただし、標準のパッケージマネージャからインストールされた uhubctl は、必ずしも最新バージョンであるとは限らず、現在のバージョンから大幅に遅れている場合もあります。最新の公開 uhubctl バージョンがパッケージマネージャが提供するものより新しい場合、以下に説明するようにソースからコンパイルしてインストールする必要があるかもしれません。

コンパイル

このユーティリティは、Linux (Ubuntu/Debian/Raspbian, Redhat/EPEL/Fedora/CentOS, Arch Linux, Gentoo, openSUSE, Buildroot), FreeBSD, NetBSD, SunOS および MacOS でコンパイルおよび動作することが確認されています。

uhubctl は Windows でもコンパイルできますが、libusb が winusb.sys ドライバを使用しているため、USB 電源の切り替えは Windows では機能しません。Microsoft によると、このドライバは必要な USB 制御要求をサポートしていません。これは、libusb が Windows で異なるドライバをサポートし始めれば修正される可能性があります。

pkgconf（または pkg-config）ユーティリティがインストールされていることを強くお勧めします（通常はデフォルトでインストールされています）。

まず、ライブラリ libusb-1.0（バージョン 1.0.13 以降が必要、1.0.23 以降を推奨）をインストールする必要があります：

• 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、または sudo port install libusb-devel pkgconf
• FreeBSD: pkg install gmake pkgconf（libusb はデフォルトで含まれています）
• NetBSD: sudo pkgin install libusb1 gmake pkgconf
• Windows: 未定？

uhubctl のソースを取得してコンパイルするには：

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

これにより uhubctl バイナリが生成されます。 以下のコマンドでシステムに /usr/sbin/uhubctl としてインストールできます：

sudo make install

一部の OS（例：FreeBSD/NetBSD）では、ビルドに gmake を使用する必要があることに注意してください。

使い方

⚠️ Linux では、sudo を使用するか、以下で説明するように USB パーミッションを設定してください！

サポートされているすべてのハブを一覧表示するには：

uhubctl

USB ポートの電源を次のように制御できます：

uhubctl -a off -p 2

これは、デフォルトのスマートハブで動作し、ポート2 (-p 2) の電源をオフ (-a off、または -a 0) にします。 サポートされているアクションは off/on/cycle/toggle（または 0/1/2/3）です。 cycle は電源をオフにし、一定の遅延（-d で設定可能）を待ってから再びオンにします。 ポートはカンマ区切りリストで指定でき、範囲には - を使用できます（例：2、2,4、、）。> ⚠️ 内蔵USBポートをオフにすると、キーボードやマウスが切断される可能性があるため、どのポートをオフにするか注意してください！

複数のスマートUSBハブが接続されている場合、-l（ロケーション）パラメータを使用して制御する特定のハブを選択する必要があります。 ハブのロケーションを確認するには、パラメータなしでuhubctlを実行するだけです。 ハブのロケーションはb-x.y.zのようになります。ここでbはUSBバス番号、x、y、z... はルートハブから始まるチェーン内のすべてのハブのポート番号です。 このアドレスは半安定です。同じ物理USBポートにUSBデバイスを抜き差し（またはオフ/オン）しても変化しません（この方法はLinuxカーネルでも使用されています）。

Linux USB権限

Linuxでは、udev USB権限を設定する必要があります（そうしないと、sudo uhubctlを使用してrootとして実行する必要があります）。

Linuxカーネル6.0以降では、USBハブポートをオン/オフする標準インターフェースがあり、uhubctlは（libusbの代わりに）それを使用してポートステータスを設定しようとします。 そのため、6.0+カーネルには追加のルールがあります。これらのルールを古いカーネルバージョンのシステムに持っていても問題はありません。

USB権限を修正するには、最初にsudo uhubctlを実行し、制御する必要があるハブのvid:pidをすべてメモします。 次に、ファイル/etc/udev/rules.d/52-usb.rulesに以下のようなudevルールを追加します （2001をハブのベンダーIDに置き換えるか、ATTR{idVendor}フィルターを完全に削除して任意のUSBハブアクセスを許可します）：

SUBSYSTEM=="usb", DRIVER=="hub|usb", MODE="0666", ATTR{idVendor}=="2001"
# Linux 6.0以降（古いLinuxカーネルの場合でもこのブロックがあっても問題ありません）：
SUBSYSTEM=="usb", DRIVER=="hub|usb", \
  RUN="/bin/sh -c \"chmod -f 666 $sys$devpath/*port*/disable || true\""

USB3ハブの場合、一部のハブは同じチップのUSB2とUSB3コンポーネントで異なるベンダーIDを使用するため、uhubctlが適切に動作するには両方に権限が必要です。 例えば、Raspberry Pi 4Bの場合、次の2行を追加する必要があります（またはidVendorフィルターを削除します）：

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

広いオープンモード0666が気に入らない場合は、次のようにグループでアクセスを制限できます：

SUBSYSTEM=="usb", DRIVER=="hub|usb", MODE="0664", GROUP="dialout"
# Linux 6.0以降（古いLinuxカーネルの場合でもこのブロックがあっても問題ありません）：
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\""

そして、許可されたユーザーをdialoutグループに追加します：

sudo usermod -a -G dialout $USER

udevルールの変更を有効にするには、再起動するか、次を実行します：

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

すぐに使用できるudevルールはこちらにあります。

FAQ

USBポートごとの電力切替とは何ですか？

USB 2.0仕様によると、USBハブは電力切替なし、一括（全ポート同時）電力切替、またはポートごと（個別）の電力切替をアドバタイズできます。 デフォルトではuhubctlはポートごとの電力切替をサポートするUSBハブのみを検出しますが（-fオプションでサポートされていないハブでの動作を強制できます）。 ハードウェアがサポートする電力切替の種類はsudo lsusb -vで確認できます：

電力切替なし：

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

一括電力切替：

wHubCharacteristic 0x0008
  Ganged power switching
  Per-port overcurrent protection

ポートごと電力切替：

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

USBハブがuhubctlでサポートされているか確認するには？

1. sudo uhubctlを実行します。ハブがリストにない場合、サポートされていません。 または、sudo lsusb -vを実行し、Per-port power switchingを確認します。lsusb出力にそのような行がない場合、ハブはサポートされていません。
2. VBUS（電圧）オフサポートを確認する：電話、USBライト、またはUSBファンをハブのUSBポートに接続します。 uhubctlを使用してそのポートの電源をオフにし、電話の充電が停止するか、USBライトが消えるか、USBファンが回転を停止するかを確認します。 VBUSがオフにならない場合、ハブメーカーは実際に電源を切る回路を含めていません。そのようなハブはUSBデータ接続を切断するのには機能しますが、電源をオフにすることはできず、サポート対象デバイスとは見なされません。
3. 上記のテストが成功した場合、新しいIssue（https://github.com/mvp/uhubctl/issues）を開いてハブを報告してください。サポートされているデバイスのリストに追加できるようにします。 すでにリストされているサポートモデルの異なるハードウェアリビジョンでない限り、サポートされていないハブは報告しないでください。

Linuxでポート電源ダウン後、USBデバイスが削除されない

USBポートの電源をオフにしても、udevはイベントを受け取らないため、デバイスファイルを残します。 ただし、デバイスファイルにアクセスしようとするとIOエラーが発生します。

これはLinuxカーネルの問題であり、Linuxカーネル6.0以降のシステムではuhubctl 2.5.0以降で修正されています。

まだLinux 5.x以前を使用している場合、次の回避策を使用できます：

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

udevによってデバイスファイルは削除されますが、USBデバイスはlsusbに表示されたままになります。 パス/sys/bus/usb/devices/${location}.${port}は、そのポートでデバイスが検出された場合にのみ存在します。 電源を再びオンにすると、デバイスは適切に再列挙されるはずです（再度udevadmを呼び出す必要はありません）。

Linuxで数秒後に電源が再び入る

カーネル内の一部のデバイスドライバーは、USBデバイスがオフにされることに驚き、自動的に電源を再投入しようとします。

これはLinuxカーネルの問題であり、Linuxカーネル6.0以降のシステムではuhubctl 2.5.0以降で修正されています。

まだLinux 5.x以前を使用している場合：

-r Nオプションを使用できます。Nは10から1000の数値で、uhubctlが短時間に何度も電源をオフにしようと試み、これを抑制します。

uhubctlで電源をオフにする前に、該当デバイスのUSB認証を無効にすると効果的です：

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

デバイスがUSBマスストレージの場合、uhubctlを呼び出す前にudisksctlを呼び出すと効果的です：

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

複数の4ポートハブが検出されるが、実際には1つの7ポートハブしか接続していない

多くのハブメーカーは、基本的な4ポートUSBチップを使用してUSBハブを構築します。 例えば、7ポートハブを作るには、2つの4ポートハブをデイジーチェーン接続します。1ポートはデイジーチェーンに失われるため、4+4-1=7ポートハブになります。同様に、10ポートハブは3つの4ポートハブをデイジーチェーン接続して作られ、4+4+4-2=10の使用可能ポートになります。

内部ハブをデイジーチェーン接続するために使用されるポートの電力状態を変更しようとしてはなりません。そうすると内部ハブ回路が混乱し、予測不能な動作を引き起こします。

Raspberry Piで指定したポートだけでなく、すべてのポートの電源がオフになる

これはRaspberry Piのハードウェア設計の制限です。 回避策として、上記のサポートリストから外部USBハブを購入し、Raspberry Piの任意のUSBポートに接続して、そのポートの電源を個別に制御できます。 また、Raspberry Pi専用に設計されたサポートハブ（例：UUGear MEGA4）もあります。

参考までに、サポートされているRaspberry Piモデルの内部USBトポロジーは次のとおりです：

Raspberry Pi B+,2B,3B

• シングルハブ1-1、ポート2-5は一括制御、すべてポート2で制御：

  root@kitploit:~

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

  ポート3、4、5を制御しようとしても何も起こりません。 ポート1はEthernet+WiFiの電源を制御します。

Raspberry Pi 3B+

• メインハブ1-1、全4ポート一括制御、すべてポート2で制御（下位ハブのポートもオフになります）。 ポート1は以下のハブ1-1.1に接続、ポート2と3は外部に配線、ポート4は未配線。

  root@kitploit:~

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

• セカンダリハブ1-1.1（メインにデイジーチェーン）：3ポート、 ポート1はEthernet+WiFi用、ポート2と3は外部に配線。

Raspberry Pi 4B

⚠️ VL805ファームウェアが00137adより古い場合（sudo rpi-eeprom-updateで確認）、 RPi 4Bで電力切替を機能させるにはファームウェアを更新する必要があります。

• USB2ハブ1、1ポート、以下のハブ1-1のみ接続。

• USB2ハブ1-1、4ポート一括制御、以下のUSB3ハブ2と対：

  root@kitploit:~

  uhubctl -l 1-1 -a 0
  

• USB3ハブ2、4ポート一括制御、上のUSB2ハブ1-1と対：

  root@kitploit:~

  uhubctl -l 2 -a 0
  

• USB2ハブ3、1ポート、OTGコントローラー。電力切替はサポートされていません。

Raspberry Pi 5

Raspberry Pi 5には2つのUSB2ポートと2つのUSB3ポート（合計4）があります。 これらのポートは、本当に奇妙な構成で4つの異なるUSBハブ1、2、3、4に接続されています （ただし、OSとHWリビジョンによって、注目すべきハブは2、3、4、5の場合があります）。 USB3デバイスが青色ソケットに接続されている場合、USB3ハブ2または4で検出されます。 USB2デバイスが任意のソケットに接続されている場合、またはUSB3デバイスが黒色ソケットに接続されている場合、USB2ハブ1または3で検出されます。 USB2/USB3接続タイプに関係なく、青色ソケットは常にポート1、黒色ソケットは常にポート2です。

4つのオンボードUSBハブはそれぞれポートごとの電力切替をサポートしているとアドバタイズしますが、これは真実ではありません。 実際には、Raspberry Pi 5の4つのポートはすべて1つのグループに一括制御されており、4つの異なる論理USBハブに属しているにもかかわらず、です。

VBUS電源をオフにするには、すべてのオンボードハブとポートで無効にする必要があります： ``` uhubctl -l 2 -a 0 uhubctl -l 4 -a 0

再び有効にするには：   ```
uhubctl -l 2 -a 1
uhubctl -l 4 -a 1

Note that VBUS power goes down only if all ports are off - enabling any single port enables VBUS back for all 4 ports.

uhubctlを使用している注目すべきプロジェクト

著作権

著作権 (C) 2009-2026 Vadim Mikhailov

このファイルは、GNU General Public License バージョン2の条項と条件の下で配布できます。