软件Software

SmartUSBHub Python SDK SmartUSBHub Python SDK

基于 USB CDC 的开源 Python 库；Windows 10/11、macOS 和 Linux 使用系统内置驱动。 An open-source Python library that controls SmartUSBHub devices over USB CDC. Windows 10/11, macOS and Linux use built-in drivers.

GitHub → PyPI

这是为旧链接保留的 API 概览。请前往最新 Python SDK 文档查看完整且持续更新的参考资料。 This API overview remains available for legacy links. Visit the current Python SDK documentation for the complete, maintained reference.

安装Installation

通过 pip 安装，所需 Python 依赖会自动安装： Install via pip; the required Python dependency is installed automatically:

pip install smartusbhub

Python 3.9+

Windows

macOS

Linux

依赖Dependencies

pyserial
标准库：threading, time Standard library: threading, time

pyserial 为唯一第三方依赖，pip 安装时自动处理。 pyserial is the only third-party dependency and is installed automatically.

API 参考API reference

连接Connection

SmartUSBHub.scan_and_connect() → SmartUSBHub | None

自动扫描串口并连接第一个 SmartUSBHub。成功时返回已连接实例；未找到设备时返回 None，使用前必须检查。 Scans serial ports and connects to the first SmartUSBHub. Returns a connected instance on success or None when no device is found; always check before use.

通道Channels

hub.get_channels() → tuple[int, ...]

返回当前连接设备的实际通道编号列表。请始终使用此方法，不要硬编码通道数量。 Returns the actual channel numbers of the connected device. Always use this method instead of hard-coding channel counts.

channels = hub.get_channels()
# HBP_USB2_7CH → (1, 2, 3, 4, 5, 6, 7)
# HBP_USB2_4CH → (1, 2, 3, 4)

电源控制Power control

hub.set_channel_power(*channels: int, state: bool) → bool

开关一个或多个通道的电源输出。通道编号从 1 开始，state 必须作为关键字参数传入；设备确认成功返回 True，否则返回 False。 Enables or disables power on one or more 1-indexed channels. state is keyword-only; returns True when acknowledged, otherwise False.

# Turn on power for channel 1
hub.set_channel_power(1, state=True)

# Turn off power for every channel
for ch in hub.get_channels():
    hub.set_channel_power(ch, state=False)

数据线控制Data-line control

hub.set_channel_usb2_dataline(*channels: int, state: bool) → bool

控制一个或多个通道的 USB 2.0 D+/D− 数据线，state 必须作为关键字参数传入。仅适用于带 USB 2.0 数据线开关的型号。 Controls USB 2.0 D+/D− data lines on one or more channels. state is keyword-only. Available only on models with a USB 2.0 data-line switch.

# Disconnect channel 2 data while keeping power on
hub.set_channel_usb2_dataline(2, state=False)

# Reconnect data; the attached device will re-enumerate
hub.set_channel_usb2_dataline(2, state=True)

电压/电流测量Voltage/current measurement

支持型号：HBP_USB2_4CH、HBP_USB2_7CH_ADV Supported models: HBP_USB2_4CH and HBP_USB2_7CH_ADV

hub.get_channel_measurements(*channels: int) → dict[int, dict] | None

批量读取指定通道的电压和电流。返回值以通道号为键，每路数据包含 voltage（mV）、current（mA）、fresh、stale 和 valid；超时返回 None。 Batch-reads voltage and current for selected channels. The result is keyed by channel; each reading contains voltage (mV), current (mA), fresh, stale and valid. Returns None on timeout.

# Read once
measurements = hub.get_channel_measurements(1)
if measurements:
    m = measurements[1]
    print(f"Voltage: {m['voltage']} mV, current: {m['current']} mA")

# Poll periodically; actual rate depends on device, firmware and serial latency
import time
while True:
    measurements = hub.get_channel_measurements(1)
    if measurements:
        m = measurements[1]
        print(m["voltage"], m["current"])
    time.sleep(0.2)

使用示例Examples

设备断电重启Power cycle a device

import time
from smartusbhub import SmartUSBHub

hub = SmartUSBHub.scan_and_connect()
if hub is None:
    raise RuntimeError("SmartUSBHub not found")

hub.set_channel_power(1, state=False)
time.sleep(1)
hub.set_channel_power(1, state=True)
hub.disconnect()

强制设备重新枚举Force re-enumeration

import time
from smartusbhub import SmartUSBHub

hub = SmartUSBHub.scan_and_connect()
if hub is None:
    raise RuntimeError("SmartUSBHub not found")

# Disconnect and reconnect the data lines
hub.set_channel_usb2_dataline(2, state=False)
time.sleep(0.5)
hub.set_channel_usb2_dataline(2, state=True)
hub.disconnect()

读取所有通道电流Read all channel currents

from smartusbhub import SmartUSBHub

hub = SmartUSBHub.scan_and_connect()
if hub is None:
    raise RuntimeError("SmartUSBHub not found")

measurements = hub.get_channel_measurements(*hub.get_channels())
if measurements:
    for ch, m in measurements.items():
        print(f"ch{ch}: {m['current']} mA")
hub.disconnect()

关闭所有通道Turn off all channels

from smartusbhub import SmartUSBHub

hub = SmartUSBHub.scan_and_connect()
if hub is None:
    raise RuntimeError("SmartUSBHub not found")

channels = hub.get_channels()
hub.set_channel_power(*channels, state=False)
hub.disconnect()

print("All channels are off")

平台支持Platform support

操作系统Operating system	驱动要求Driver	备注Notes
Windows 10 / 11	无需安装None required	内置 CDC 驱动Built-in CDC driver
macOS 12+	无需安装None required	内置 CDC ACM 驱动Built-in CDC ACM driver
Linux (Ubuntu 20.04+)	无需安装None required	可能需要将用户加入 dialout 组： You may need to add your user to the dialout group: `sudo usermod -aG dialout $USER`