Как программно обесточить зависшую USB-периферию с помощью uhubctl

Представьте стандартную ситуацию: у вас на удаленном сервере, дачном роутере или тестовом стенде завис 4G-модем. Или плата Raspberry Pi переключилась в нештатный режим, а контроллер 3D-принтера перестал отвечать на команды. Обычная перезагрузка операционной системы не помогает, потому что питание на USB-портах продолжает подаваться. Единственный вариант — ехать на объект и дергать кабель руками.

Если у вас нет желания работать «пешим администратором», пригодится утилита uhubctl. Вадим Михайлов написал этот инструмент на C еще в 2015 году, и проект активен до сих пор. Основная задача программы — отправлять низкоуровневые USB-команды контроллеру хаба, чтобы тот физически снял напряжение VBUS с конкретного порта.

Как это работает и в чем подвох с железом

uhubctl не делает чудес из ничего. Она работает только с теми хабами, где производитель заложил аппаратную поддержку управления питанием отдельных портов (Per-Port Power Switching, или PPPS). По стандартам USB 2.0 и USB 3.0 эта спецификация существует давно, но экономия на элементах питания приводит к тому, что многие дешевые хабы объединяют питание всех портов в одну линию.

Тем не менее, совместимых устройств на рынке достаточно. В репозитории ведут подробную таблицу, где собраны десятки проверенных моделей:

• Встроенные хабы в мониторах Dell, LG, BenQ и Acer.
• Одноплатники Raspberry Pi (на моделях 3B+ и 4B отключать питание можно, хотя со своими нюансами).
• Внешние хабы марок Anker, D-Link, Rosonway, Plugable.
• Материнские платы Asus и промышленные контроллеры KUNBUS RevPi.

Что под капотом

uhubctl обращается к хабу через библиотеку libusb или напрямую через интерфейсы ядра Linux. В ядре Linux 6.0 появился штатный механизм отключения портов через sysfs. Утилита сначала пробует его, а если работает на более старой системе или под macOS, переключается на libusb.

Есть один нюанс с USB 3.0. Когда вы подключаете современный хаб к порту USB 3.0, система видит его как два отдельных логических устройства: виртуальный USB 2.0 хаб и виртуальный USB 3.0 хаб. Если обесточить порт только на одной ветке, подключенное устройство может просто переключиться на другую скорость и продолжить работать. uhubctl берет эту рутину на себя и делает синхронное отключение на обоих виртуальных хабах.

Установка и быстрый старт

В большинстве дистрибутивов Linux утилита уже есть в стандартных репозиториях:

sudo apt install uhubctl

Для macOS установка идет через Homebrew:

brew install uhubctl

Если в дистрибутиве лежит устаревшая версия, собрать исходники из Git не составит труда. Понадобятся libusb-1.0 и make:

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

Первым делом стоит запустить утилиту без параметров, чтобы увидеть список доступных хабов и подключенных к ним устройств:

sudo uhubctl

Команда выведет топологию шины, адреса хабов в формате 1-1 или 2-3.1 и состояние каждого порта.

Примеры команд

Чтобы обесточить второй порт на хабе по умолчанию, выполните:

sudo uhubctl -a off -p 2

Вместо off и on можно передать действие cycle. Оно отключает питание, выдерживает небольшую паузу и включает его обратно. Это подходит для жесткого сброса зависшего оборудования:

sudo uhubctl -a cycle -p 2 -d 3

Параметр -d 3 задает задержку в 3 секунды перед повторной подачей питания. Если нужно сбросить сразу несколько портов, укажите их через запятую или дефис: -p 1,3,4 или -p 1-4.

Настройка прав доступа в Linux

По умолчанию для работы с USB-устройствами напрямую требуются права root. Чтобы не запускать скрипты через sudo, добавьте правила udev в файл /etc/udev/rules.d/52-usb.rules:

После этого выполните sudo udevadm trigger --attr-match=subsystem=usb, и права обновятся.

Практические сценарии использования

Разработчики и системные администраторы применяют uhubctl в самых разных задачах:

• Автоматический сброс зависших LTE-модемов и роутеров в фермах мониторинга.
• Управление внешними светодиодными индикаторами, вентиляторами или веб-камерами.
• Безопасное отключение внешних жестких дисков для исключения фантомной нагрузки и экономии энергии.
• Интеграция с OctoPrint для дистанционного включения и выключения 3D-принтера.
• Аппаратное тестирование в CI/CD пайплайнах, когда нужно физически переподключить отладочную плату к тестовому стенду.

Ограничения и особенности оборудования

Перед тем как встраивать утилиту в свои скрипты, стоит проверить аппаратные особенности вашей системы. Например, на некоторых моделях Raspberry Pi линии питания всех четырех портов соединены параллельно. При попытке выключить один порт система обесточит сразу все четыре.

Кроме того, некоторые питаемые от USB гаджеты продолжают брать ток для зарядки аккумулятора, даже если сигнальные линии данных отключены. В таком случае поможет только проверка конкретного хаба с помощью мультиметра или нагрузочного резистора.

Если вы строите автономный стенд, умный дом или управляете серверами с подключенной периферией, uhubctl — один из тех компактных инструментов, которые спасают от долгих поездок к застрявшему железу. Программа распространяется под лицензией GPLv2 и решает свою задачу без лишней сложности. Главное перед стартом — убедиться, что ваш USB-хаб поддерживает управление питанием.