mvp/uhubctl
GitHub: mvp/uhubctl
uhubctl 是一款用于智能 USB 集线器每端口电源控制的命令行工具，支持远程开关指定 USB 端口供电。
Stars: 2716 | Forks: 254
# uhubctl
`uhubctl` 是一个用于在智能 USB 集线器上控制每个端口 USB 供电的实用工具。
智能集线器定义为实现了每端口电源切换的设备。
此代码的最初灵感来自 Niibe Yutaka 编写的 hub-ctrl.c：
https://www.gniibe.org/development/ac-power-control-by-USB-hub
# 兼容的 USB 集线器
以下是已知兼容的 USB 集线器列表：
| 制造商 | 产品 | 端口 | USB | VID:PID | 发布 | EOL |
|:-------------------|:-----------------------------------------------------|:------|:----|:----------|:--------|:-----|
| Acer | BE270U 显示器 ([见](https://tinyurl.com/acer550)) | 4 | 3.0 |`2109:2811`| 2016 | |
| AmazonBasics | HU3641V1 ([RPi 问题](https://goo.gl/CLt46M)) | 4 | 3.0 |`2109:2811`| 2013 | |
| AmazonBasics | HU3770V1 ([RPi 问题](https://goo.gl/CLt46M)) | 7 | 3.0 |`2109:2811`| 2013 | |
| AmazonBasics | HU9003V1EBL, HUC9003V1EBL | 7 | 3.1 |`2109:2817`| 2018 | |
| AmazonBasics | HU9002V1SBL, HU9002V1EBL, HU9002V1ESL, HHU9002V1EZPR01 ([注](https://tinyurl.com/HU9002)) | 10 | 3.1 |`2109:2817`| 2018 | |
| AmazonBasics | HUC9002V1SBL, HUC9002V1EBL, HUC9002V1ESL | 10 | 3.1 |`2109:2817`| 2018 | |
| AmazonBasics | U3-7HUB (仅适用于 1 个充电端口) | 7 | 3.0 |`2109:2813`| 2020 | |
| Anker | AK-68ANHUB-BV7A-0004 ([注](https://git.io/JLnZb)) | 7 | 3.0 |`2109:0812`| 2014 | |
| Apple | Mac Mini M4 (仅 2 个前置端口) | 2 | 3.2 |`05AC:800B`| 2024 | |
| Apple | MacBook Air (2010 年末) | 2 | 2.0 |`1D6B:0002`| 2010 | 2020 |
| Apple | Pro Display XDR MWPE2LL/A (内部 USB 集线器) | 4 | 2.0 |`05AC:9139`| 2019 | |
| Apple | Thunderbolt Display 27" (内部 USB 集线器) | 6 | 2.0 | | 2011 | 2016 |
| Apple | 带数字小键盘的 USB 键盘 (内部 USB 集线器) | 3 | 2.0 | | 2011 | |
| Asus | Z77 Sabertooth 主板 (板载 USB 集线器) | 6 | 2.0 | | 2012 | |
| Asus | Z87-PLUS 主板 (板载 USB 集线器) | 4 | 3.0 | | 2013 | 2016 |
| Aukey | CB-C59 | 4 | 3.0 |`2109:2813`| 2017 | |
| B+B SmartWorx | UHR204 | 4 | 2.0 |`0856:DB00`| 2013 | |
| B+B SmartWorx | USH304 | 4 | 3.0 |`04B4:6506`| 2017 | 2019 |
| Basler | 2000036234 | 4 | 3.0 |`0451:8046`| 2016 | |
| Belkin | F5U101 | 4 | 2.0 |`0451:2046`| 2005 | 2010 |
| Belkin | F5U238UKCRL-MOB | 4 | 2.0 |`0409:0059`| 2004 | 2010 |
| BenQ | PD2700U 4K 显示器 (仅在 USB2 模式下有效) | 4 | 3.0 |`05E3:0610`| 2018 | |
| BenQ | PD3220U | 4 | 3.1 |`05E3:0610`| 2019 | |
| Bytecc | BT-UH340 ([警告](https://tinyurl.com/BT-UH340-1)) | 4 | 3.0 |`2109:8110`| 2010 | |
| Centech | CT-USB4HUB ReTRY HUB ([注](https://github.com/mvp/uhubctl/issues/630)) | 4 | 3.0 |`0424:2744`| 2017 | |
| Circuitco | Beagleboard-xM (内部 USB 集线器) | 4 | 2.0 |`0424:9514`| 2010 | |
| Club3D | CSV-3242HD 双显示扩展坞 | 4 | 3.0 |`2109:2811`| 2015 | |
| Coolgear | USBG-12U2ML | 12 | 2.0 |`05E3:0607`| 2015 | |
| Cypress | CY4608 HX2VL ([注](https://tinyurl.com/CY4608-1)) | 4 | 2.0 |`04B4:6570`| 2012 | |
| D-Link | DUB-2332 rev A1 | 3 | 3.0 | | 2022 | |
| D-Link | DUB-H4 rev D,E (黑色)。注意：不支持 rev A,C,F | 4 | 2.0 |`05E3:0608`| 2012 | |
| D-Link | DUB-H7 rev A (银色) | 7 | 2.0 |`2001:F103`| 2005 | 2010 |
| D-Link | DUB-H7 rev D,E (黑色)。不支持 rev B,C,F,G | 7 | 2.0 |`05E3:0608`| 2012 | |
| Dell | DA300 USB-C 移动适配器 | 2 | 3.0 |`2109:2820`| 2018 | |
| Dell | P2416D 24" QHD 显示器 ([注](https://git.io/JUAu8))| 4 | 2.0 | | 2017 | |
| Dell | S2719DGF 27" WQHD 电竞显示器 | 5 | 3.0 |`0424:5734`| 2018 | |
| Dell | UltraSharp 1704FPT 17" LCD 显示器 | 4 | 2.0 |`0424:A700`| 2005 | 2015 |
| Dell | UltraSharp U2415 24" LCD 显示器 | 5 | 3.0 | | 2014 | |
| Dell | UltraSharp U3419W 34" 曲面显示器 | 6 | 3.0 | | 2020 | |
| Dell | Wyse 3040 ([需要 -f](https://tinyurl.com/wyse3k))| 6 | 3.0 | | 2017 | |
| Delock | 62537 | 4 | 3.0 | | 2017 | 2021 |
| Delock | 87445 ([注](https://git.io/Jsuz5)) | 4 | 2.0 |`05E3:0608`| 2009 | 2013 |
| Elecom | U2H-G4S | 4 | 2.0 | | 2006 | 2011 |
| Gigabyte | G27Q 显示器 ([见](http://tinyurl.com/G27Q551)) | 4 | 3.0 |`2109:0817`| 2020 | |
| GlobalScale | ESPRESSObin SBUD102 V5 | 1 | 3.0 |`1D6B:0003`| 2017 | |
| Hardkernel | ODROID-C4 ([注](https://git.io/JG0mP)) | 4 | 3.0 | | 2020 | |
| Hawking Technology | UH214 | 4 | 2.0 | | 2003 | 2008 |
| Hewlett Packard | USB-C Dock G5 5TW10AA | 5 | 3.0 |`03F0:076B`| 2019 | |
| Hewlett Packard | P5Q58UT | 3 | 3.0 | | 2019 | |
| IBM | SK-8815 USB 键盘 | 3 | 1.1 |`04B3:301A`| 2004 | |
| Inateck | HB2025A ([仅限 USB2](https://tinyurl.com/HB2025A-1)) | 4 | 3.1 |`2109:2822`| 2021 | |
| IOI | U3H415E1 | 4 | 3.0 | | 2012 | |
| j5create | JUH377 ([注](https://tinyurl.com/JUH377)) | 7 | 3.0 | | 2016 | |
| j5create | JUH470 ([注](https://tinyurl.com/JUH470)) | 3 | 3.0 |`05E3:0610`| 2014 | |
| Juiced Systems | 6HUB-01 | 7 | 3.0 |`0BDA:0411`| 2014 | 2018 |
| KUNBUS GmbH | RevPi Connect (+) / S / SE | 2 | 2.0 |`0424:9514`| 2018 | |
| KUNBUS GmbH | RevPi Connect 4 | 2 | 3.0 | | 2022 | |
| KUNBUS GmbH | RevPi Core 3 / S / SE | 2 | 2.0 |`0424:9514`| 2017 | |
| LG Electronics | 27MD5KL-B 显示器 | 4 | 3.0 |`043E:9A60`| 2019 | |
| LG Electronics | 27GL850-B 显示器 | 4 | 3.0 |`0451:8142`| 2019 | |
| LG Electronics | 27UK850-W 显示器 | 2 | 3.0 | | 2018 | |
| LG Electronics | 27UN83A-W 显示器 | 2 | 3.0 |`0451:8142`| 2020 | |
| LG Electronics | 38WK95C-W 显示器 | 4 | 3.0 |`0451:8142`| 2018 | |
| Lenovo | ThinkPad Mini Dock Series 3 (433710U) | 6 | 2.0 |`17EF:100A`| 6 | |
| Lenovo | ThinkPad Ultra 扩展坞 (40A20090EU) | 6 | 2.0 |`17EF:100F`| 2015 | |
| Lenovo | ThinkPad Ultra 扩展坞 (40AJ0135EU) | 7 | 3.1 |`17EF:3070`| 2018 | |
| Lenovo | ThinkPad X200 Ultrabase 42X4963 | 3 | 2.0 |`17EF:1005`| 2008 | 2011 |
| Lenovo | ThinkPad X6 Ultrabase 42W3107 | 4 | 2.0 |`17EF:1000`| 2006 | 2009 |
| Lenovo | ThinkPlus 4合1 USB-C 集线器 4X90W86497 | 3 | 3.0 | | 2021 | |
| Lenovo | ThinkVision T24i-10 显示器 | 4 | 2.0 |`17EF:0610`| 2018 | |
| Lenovo | USB-C 转 4 口 USB-A 集线器 ([仅限 USB2](https://github.com/mvp/uhubctl/issues/625)) | 4 | 2.0 |`17EF:103A`| 2020 | |
| Lindy | USB 串口转换器 4 端口 | 4 | 1.1 |`058F:9254`| 2008 | |
| Linksys | USB2HUB4 ([注](https://git.io/JYiDZ)) | 4 | 2.0 | | 2004 | 2010 |
| Maplin | A08CQ ([仅限红色端口](https://tinyurl.com/gh635)) | 7 | 2.0 |`0409:0059`| 2008 | 2011 |
| Metadot | Das Keyboard 4 | 2 | 3.0 | | 2014 | |
| Microchip | EVB9512 | 2 | 2.0 | | 2009 | |
| Microchip | EVB-USB2517 | 7 | 2.0 | | 2008 | |
| Microchip | EVB-USB2534BC | 4 | 2.0 | | 2013 | |
| Microchip | EVB-USB5807 | 7 | 3.0 | | 2016 | |
| Moxa | Uport-407 | 7 | 2.0 |`110A:0407`| 2009 | |
| NVidia | Jetson Nano B01 ([详情](https://git.io/JJaFR)) | 4 | 3.0 | | 2019 | |
| NVidia | Jetson Xavier NX ([详情](https://tinyurl.com/Xavier-NX)) | 4 | 3.0 | | 2020 | |
| Phidgets | HUB0003_0 | 7 | 2.0 |`1A40:0201`| 2017 | |
| Philips | 346B1C UltraWide 34" 曲面显示器 | 4 | 3.0 |`05E3:0610`| 2019 | |
| Plugable | USB3-HUB7BC | 7 | 3.0 |`2109:0813`| 2015 | |
| Plugable | USB3-HUB7C (仅适用于 2 个充电端口) | 7 | 3.0 |`2109:0813`| 2015 | |
| Plugable | USBC-HUB7BC (适用于 6/7 端口，最右边的除外) | 7 | 3.0 |`2109:0817`| 2021 | |
| Plugable | USB3-HUB10-C2 (仅适用于 2 个充电端口) | 10 | 3.0 | | 2014 | |
| Port Inc | NWUSB01 | 4 | 1.1 |`0451:1446`| 1999 | 2003 |
| Raspberry Pi | B+, 2B, 3B ([见下文](#raspberry-pi-b2b3b)) | 4 | 2.0 | | 2011 | |
| Raspberry Pi | 3B+ ([见下文](#raspberry-pi-3b)) | 4 | 2.0 |`0424:2514`| 2018 | |
| Raspberry Pi | 4B ([见下文](#raspberry-pi-4b)) | 4 | 3.0 |`2109:3431`| 2019 | |
| Raspberry Pi | 5 ([见下文](#raspberry-pi-5)) | 4 | 3.0 |`1D6B:0002`| 2023 | |
| Renesas | uPD720202 PCIe USB 3.0 主机控制器 | 2 | 3.0 | | 2013 | |
| Rosewill | RHUB-210 | 4 | 2.0 |`0409:005A`| 2011 | 2014 |
| Rosonway | RSH-518C ([注](https://tinyurl.com/RSH518)) | 7 | 3.0 |`2109:0817`| 2021 | |
| Rosonway | RSH-A10 ([见](https://tinyurl.com/2ppyyaj8)) | 10 | 3.0 |`0BDA:0411`| 2020 | |
| Rosonway | RSH-A13 ([警告](https://tinyurl.com/RSH-A13)) | 13 | 3.1 |`2109:2822`| 2021 | |
| Rosonway | RSH-A16 ([注](https://git.io/JTawg), [警告](https://tinyurl.com/RSH-A16)) | 16 | 3.0 |`0bda:0411`| 2020 | |
| Rosonway | RSH-A37S | 7 | 3.0 |`2109:2822`| 2021 | |
| Rosonway | RSH-A104 ([仅限 USB2](https://tinyurl.com/RSH-A104)) | 4 | 3.1 |`2109:2822`| 2022 | |
| Rosonway | RSH-ST07C ([仅 4 个](https://tinyurl.com/4pjnujrn)) | 7 | 3.0 |`2109:2822`| 2023 | |
| Rosonway | RSH-ST10C-6 ([注](https://tinyurl.com/428vpa2f)) | 10 | 3.1 |`0BDA:0423`| 2024 | |
| Sanwa Supply | USB-HUB14GPH | 4 | 1.1 | | 2001 | 2003 |
| Satechi | Mac Mini 集线器 (M1/M2) | 4 | 3.0 |`2109:2817`| 2023 | |
| Seagate | Backup Plus Hub STEL8000100 | 2 | 3.0 |`0BC2:AB44`| 2016 | |
| Seeed Studio | reTerminal CM4104032 | 2 | 2.0 |`0424:2514`| 2021 | |
| StarTech | DKT30CSDHPD3 USB-C 旅行坞 | 3 | 3.0 |`2109:2817`| 2018 | |
| StarTech | HB30A4AIB ([警告](https://tinyurl.com/ycxravwk)) | 4 | 3.0 |`2109:2817`| 2018 | |
| StarTech | HB31C2A2CB ([注](https://github.com/mvp/uhubctl/issues/601)) | 5 | 3.0 |`14B0:013D`| 2020 | |
| StarTech | HB31C3A1CPD3 ([注](https://github.com/mvp/uhubctl/issues/656)) | 5 | 3.1 |`14B0:013A`| 2019 | |
| Sunix | SHB4200MA | 4 | 2.0 |`0409:0058`| 2006 | 2009 |
| System Talks | Sugoi USB2-HUB4X ([警告](https://github.com/mvp/uhubctl/issues/636))|4|2.0| | 2007 | |
| Targus | ACH155 (端口 3 控制所有端口) | 4 | 3.0 | | 2022 | |
| Targus | PA095UZ | 2 | 2.0 | | 2004 | |
| Targus | PAUH212/PAUH212U | 7 | 2.0 | | 2004 | 2009 |
| Texas Instruments | TUSB4041PAPEVM | 4 | 2.1 |`0451:8142`| 2015 | |
| UUGear | MEGA4 (适用于 Raspberry Pi 4B) | 4 | 3.0 |`2109:0817`| 2021 | |
| VirtualHere | USB3 4 端口集线器 ([注](https://tinyurl.com/vhusb)) | 4 | 3.0 | | 2024 | |
此表格并不完整。
如果您的集线器能在 `uhubctl` 下正常工作，但未在上方列出，请在 https://github.com/mvp/uhubctl/issues 提交新问题进行报告，以便我们将其添加到支持列表中。在您的报告中，请提供准确的产品型号，附上 `uhubctl` 的输出，并请按照下方常见问题解答中的说明测试 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`
- :warning: MacOS 26+ [需要](https://github.com/libusb/libusb/pull/1700) 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 可能不是最新版本，甚至可能远远落后于当前版本。如果[最新发布的](https://github.com/mvp/uhubctl/releases) uhubctl 版本比您的包管理器提供的版本新，您可能需要按照下文的说明从源代码编译并安装。
# 编译
此实用工具已经过测试，可以在 Linux（Ubuntu/Debian/Raspbian、Redhat/EPEL/Fedora/CentOS、Arch Linux、Gent、openSUSE、Buildroot）、FreeBSD、NetBSD、SunOS 和 MacOS 上编译和运行。
虽然 `uhubctl` 可以在 Windows 上编译，但 USB 电源切换在 Windows 上不起作用，因为 `libusb` 使用的是 `winusb.sys` 驱动程序，根据微软的说法，该驱动程序不支持[必要的 USB 控制请求](https://web.archive.org/web/20210225235523/https://social.msdn.microsoft.com/Forums/sqlserver/en-US/f680b63f-ca4f-4e52-baa9-9e64f8eee101/how-to-send-an-quotusb-control-requestquot-to-an-usbhub?forum=wdk)。
如果 `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
```
请注意，在某些操作系统（例如 FreeBSD/NetBSD）上，您需要使用 `gmake` 来进行构建。
# 用法
列出所有支持的集线器：
```
uhubctl
```
您可以像这样控制 USB 端口的电源：
```
uhubctl -a off -p 2
```
这表示在默认智能集线器上操作，并关闭（`-a off` 或 `-a 0`）端口 2（`-p 2`）的电源。支持的操作有 `off`/`on`/`cycle`/`toggle`（或 `0`/`1`/`2`/`3`）。
`cycle` 表示关闭电源，等待一段延迟（可通过 `-d` 配置）然后再重新打开。
端口可以是以逗号分隔的列表，并且可以使用 `-` 表示范围，例如 `2`，或 `2,4`，或 `2-5`，或 `1-2,5-8`。
如果您连接了多个智能 USB 集线器，您应该使用 `-l`（位置）参数选择要控制的具体集线器。
要查找集线器位置，只需运行不带任何参数的 `uhubctl`。
集线器位置看起来像 `b-x.y.z`，其中 `b` 是 USB 总线号，而 `x`、`y`、`z`... 是链路中所有集线器的端口号，从给定 USB 总线的根集线器开始。
此地址是半稳定的——如果您将 USB 设备插拔（或关闭/打开）到同一物理 USB 端口中，它不会改变（此方法也用于 Linux 内核中）。
# Linux USB 权限
在 Linux 上，您应该配置 `udev` USB 权限（否则您将必须使用 `sudo uhubctl` 以 root 身份运行它）。
从 Linux 内核 6.0 开始，有一个标准的接口来打开或关闭 USB 集线器端口，`uhubctl` 会尝试使用它（而不是 `libusb`）来设置端口状态。这就是为什么对于 6.0+ 内核会有额外的规则。在运行较旧内核版本的系统上保留这些规则并无害处。
要修复 USB 权限，首先运行 `sudo uhubctl` 并记下您需要控制的所有集线器的 `vid:pid`。然后，将如下所示的 udev 规则添加到文件 `/etc/udev/rules.d/52-usb.rules` 中（将 `2001` 替换为您的集线器供应商 ID，或完全移除 `ATTR{idVendor}` 过滤器以允许任何 USB 集线器访问）：
```
SUBSYSTEM=="usb", DRIVER=="hub|usb", MODE="0666", ATTR{idVendor}=="2001"
# Linux 6.0 或更高版本（在较旧的 Linux 内核中存在此 block 也是可以的）：
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，您需要添加这两行（或移除 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 内核中存在此 block 也是可以的）：
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
```
为了您的方便，[这里](https://github.com/mvp/uhubctl/blob/master/udev/rules.d/52-usb.rules)提供了可以直接使用的 udev 规则。
# 常见问题解答
#### _什么是 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. 如果上述测试成功，请在 https://github.com/mvp/uhubctl/issues 提交新问题以报告您的集线器，
以便我们将其添加到支持的设备列表中。
请勿报告不受支持的集线器，除非它是某个已列出的受支持型号的不同硬件版本。
#### _在 Linux 上，端口断电后 USB 设备未被移除_
USB 端口断电后，udev 无法获取任何事件，因此它会保留设备文件。但是，尝试访问设备文件会导致 IO 错误。
这是 Linux 内核[问题](https://tinyurl.com/ym7yvuzw)，在 uhubctl 2.5.0 中针对 Linux 内核 6.0 或更高版本的系统已[修复](https://github.com/mvp/uhubctl/pull/450)。
如果您仍在使用 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 内核[问题](https://tinyurl.com/ym7yvuzw)，在 uhubctl 2.5.0 中针对 Linux 内核 6.0 或更高版本的系统已[修复](https://github.com/mvp/uhubctl/pull/450)。
如果您仍在使用 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 端口集线器，但我只连接了一个 7 端口集线器_
许多集线器制造商使用基本的 4 端口 USB 芯片构建其 USB 集线器。
例如，要制作 7 端口集线器，他们会将两个 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` 控制：
uhubctl -l 1-1 -p 2 -a 0
尝试控制端口 `3`、`4`、`5` 不会起任何作用。
端口 `1` 控制以太网+WiFi 的电源。
##### Raspberry Pi 3B+
* 主集线器 `1-1`，所有 4 个端口均为联动控制，均由端口 `2` 控制（也会关闭次级集线器端口）。
端口 `1` 连接下方的集线器 `1-1.1`，端口 `2` 和 `3` 接到外部，端口 `4` 未接线。
uhubctl -l 1-1 -p 2 -a 0
* 次级集线器 `1-1.1`（与主集线器菊花链连接）：3 个端口，
端口 `1` 用于以太网+WiFi，端口 `2` 和 `3` 接到外部。
##### Raspberry Pi 4B
* USB2 集线器 `1`，1 个端口，仅连接下方的集线器 `1-1`。
* USB2 集线器 `1-1`，4 个端口联动，与下方的 USB3 集线器 `2` 双重对应：
uhubctl -l 1-1 -a 0
* USB3 集线器 `2`，4 个端口联动，与上方的 USB2 集线器 `1-1` 双重对应：
uhubctl -l 2 -a 0
* USB2 集线器 `3`，1 个端口，OTG 控制器。[不支持](https://git.io/JUc5Q)电源切换。
##### Raspberry Pi 5
Raspberry Pi 5 有两个 USB2 端口和两个 USB3 端口（共 4 个）。
这些端口以非常奇怪的配置连接到 4 个不同的 USB 集线器 `1`、`2`、`3`、`4`
（但根据操作系统和硬件修订版的不同，目标集线器可能是 `2`、`3`、`4`、`5`）。
如果 USB3 设备连接到蓝色插座，它将在 USB3 集线器 `2` 或 `4` 上被检测到。
如果 USB2 设备连接到任何插座，或 USB3 设备连接到黑色插座，
它将在 USB2 集线器 `1` 或 `3` 上被检测到。
无论 USB2/USB3 连接类型如何，蓝色插座始终是端口 `1`，黑色插座始终是端口 `2`。
4 个板载 USB 集线器中的每一个都宣称支持每端口电源切换，但事实并非如此。
实际上，尽管属于 4 个不同的逻辑 USB 集线器，Raspberry Pi 5 的所有 4 个端口都联动在一个组中。
要关闭 VBUS 电源，必须禁用所有板载集线器和端口，使用以下命令：
```
uhubctl -l 2 -a 0
uhubctl -l 4 -a 0
```
要重新打开它：
```
uhubctl -l 2 -a 1
uhubctl -l 4 -a 1
```
请注意，只有在所有端口都关闭的情况下，VBUS 电源才会断开
启用任何一个端口都会恢复所有 4 个端口的 VBUS。
# 使用 uhubctl 的知名项目
| 项目 | 描述 |
|:---------------------------------------------------------|:--------------------------------------------------------|
| [摩斯密码 USB 灯](https://git.io/fj1F4) | 用 USB 灯闪烁摩斯密码信息 |
| [网络摄像头 USB 灯](https://git.io/fj1FB) | 网络摄像头开启/关闭时开启/关闭 LED 灯 |
| [影院灯箱](https://goo.gl/fjCvkz) | 从 iOS 家庭应用开启/关闭影院灯箱 |
| [构建状态灯](https://goo.gl/3GA82o) | 在 10 分钟内创建一个构建状态灯 |
| [Buildenlights](https://git.io/fj1FC) | 将 GitLab/GitHub 项目构建状态显示为绿灯/红灯 |
| [气象站](https://goo.gl/3b1FzC) | 气象站死机时将其重置 |
| [sysmoQMOD](https://tinyurl.com/sysmoQMOD) | 必要时重置蜂窝调制解调器 |
| [雾霾传感器](https://tinyurl.com/smogsensor) | 基于 Raspberry Pi 的雾霾传感器断电重启 |
| [糟糕集群 (Terrible Cluster)](https://goo.gl/XjiXFu) | 根据需要开启/关闭 Raspberry Pi 集群节点 |
| [理想音乐服务器](https://tinyurl.com/ideal-m-srv) | 关闭未使用的 USB 端口以提高音频质量 |
| [无幻象负载的 USB 驱动器](https://goo.gl/qfrmGK) | 仅在需要时为 USB 驱动器供电以节省电量 |
| [USB 驱动器数据恢复](https://goo.gl/4MddLr) | 从出现故障的 USB 硬盘恢复数据 |
| [控制 3D 打印机电源](https://git.io/fh5Tr) | 用于 USB 电源控制的 OctoPrint Web 插件 |
| [Raspberry Pi 的 USB 风扇](https://tinyurl.com/fan-rpi) | 控制 USB 风扇以避免 Raspberry Pi 过热 |
| [Raspberry Pi 重启路由器](https://tinyurl.com/rpi-rtr)| 如果互联网无法工作则自动重启路由器 |
| [语音控制 USB 灯](https://tinyurl.com/usblmp)| 使用 Siri 和 Raspberry Pi 对 USB 灯进行语音控制 |
| [控制 USB LED 灯带](https://tinyurl.com/usbleds) | 控制 USB 供电的 LED 灯带 |
| [用 Raspberry Pi 酿造啤酒](https://git.io/JtbLd) | 使用 Raspberry Pi 的自动啤酒酿造系统 |
| [网络摄像头工作中指示牌](https://tinyurl.com/uonair) | 摄像头在使用时自动点亮指示牌 |
| [DIY PPPS](https://git.io/J3lHs) | 在您的 USB 集线器中焊接电线以支持 uhubctl |
| [开源 PPPS 集线器](https://tinyurl.com/yckhystt) | uhubctl 兼容集线器的开源硬件项目 |
| [uhubctl 的 Python 封装](https://github.com/nbuchwitz/python3-uhubctl) | 在 Python 中使用 uhubctl 的模块 |
| [labgrid](https://github.com/labgrid-project/labgrid) | 在硬件上测试嵌入式 Linux 的框架 |
| [热成像相机](https://tinyurl.com/5asne8hw) | 必要时开启/关闭机器人的热成像相机 |
# 版权
版权所有 (C) 2009-2025 Vadim Mikhailov
此文件可以在 GNU 通用公共许可证第 2 版的条款和条件下分发。
标签：USB, 客户端加密, 电源管理, 硬件控制, 系统工具, 运维工具