Python API

本页是 SmartUSBHub Python 控制库的 API 文档入口。

模块

通过 UART 串行链路控制 Smart USB Hub 的高级驱动。

The SmartUSBHub class provides robust per-port control of power and data connections, voltage/current monitoring, configuration of default states, and factory reset. It is intended for automated test systems and hardware development workflows.

线缆协议

三种帧格式共用同一个串行通道，并通过帧起始字节（SOF）区分：

• V1（6 字节）：0x55 0x5A CMD CHANNEL VALUE CHECKSUM，其中 CHECKSUM = (CMD + CHANNEL + VALUE) & 0xFF。用于大多数 set/get 命令。CHANNEL 是位掩码（bit0 = 通道 1，bit1 = 通道 2，依此类推）。

• V2（7 字节）：0x55 0x5A CMD CHANNEL VALUE0 VALUE1 CHECKSUM。用于 16 位负载（电压/电流），以及默认电源/数据线命令中的 enable/value 成对参数。

• V3 (>=10 bytes): 0x55 0xAB 0xCD 0xEF SOF magic, followed by CMD, FLAGS, a little-endian 16-bit LENGTH, a little-endian 16-bit CRC16 (poly 0x8005, init 0xFFFF, computed with the CRC field zeroed), and a variable-length payload. Used for batch measurements, measurement streaming and unsolicited device debug logs (CMD_DEBUG_LOG). Frames whose FLAGS carry V3_FLAG_STREAM are unsolicited notifications and are not acknowledged by the host.

权威命令参考请以发布包随附的产品文档为准。

SmartUSBHub

class smartusbhub.SmartUSBHub(port)

基类：object

通过 UART 控制工业级 Smart USB Hub 的高级接口。

Provides per-port control of power and data connections, voltage/current monitoring, default-state configuration and factory reset. Suitable for automated test systems and hardware development.

实例可作为上下文管理器使用，退出时会自动断开设备：

with SmartUSBHub(port) as hub:
hub.set_channel_power(1, state=1)

close()

关闭连接。等同于 disconnect。

register_disconnect_callback(callback)

注册设备意外断开时调用的回调函数。

参数:

callback – 断开连接时执行的零参数可调用对象。

register_log_callback(callback)

Register a callback invoked for each device debug-log line.

Firmware built with DEBUG_PRINTF routes its debug_printf() output into unsolicited V3 CMD_DEBUG_LOG stream frames; this callback receives the decoded text (one call per frame). Pass None to clear it.

Even without a callback, each line is emitted on this module’s logger at INFO level.

参数:

callback – Callable receiving the log text (str), or None.

register_callback(cmd, callback)

注册收到某个命令 ACK 时调用的回调函数。

参数:

• cmd – 要绑定回调的命令码。

• callback – 收到 ACK 时调用的可调用对象，参数为 (channel, value)。

static get_product_info(product_type_id)

按产品类型 ID 查询能力记录。

参数:

product_type_id – 产品类型 ID（见 PRODUCT_TYPE_TABLE）。

返回:

产品信息字典；如果 ID 未知则返回 None。

classmethod scan_available_ports()

扫描 USB VID/PID 与 Smart USB Hub 匹配的串口。

返回:

匹配的端口设备名称列表。

classmethod scan_and_connect(exclude_ports=None, device_address=None)

扫描 Smart USB Hub 设备并连接第一个有效设备。

参数:

• exclude_ports – 要跳过的端口集合；默认跳过已连接端口。

• device_address – 如果提供该参数，则只连接上报此地址的设备。注意：地址默认值为 0，多个设备可能共享同一地址；优先按端口选择。见 scan_and_connect_by_address。

返回:

已连接的 SmartUSBHub 实例；如果未找到则返回 None。

classmethod scan_and_connect_by_address(device_address)

按设备地址连接 Smart USB Hub。

警告

地址默认值为 0，多个设备可能共享同一地址，因此这种选择方式并不可靠。建议优先通过 scan_and_connect 按端口连接，或先分配不同地址。

参数:

device_address – 要匹配的设备地址（0x0000 - 0xFFFF）。

返回:

已连接的 SmartUSBHub 实例；如果未找到匹配设备则返回 None。

classmethod auto_connect(exclude_ports=None, feature_filter=None)

扫描并连接第一个可用设备，跳过忙碌设备。

不同于 scan_and_connect，忙碌或连接失败的端口会被跳过，并自动尝试下一个候选端口。

参数:

• exclude_ports – 要跳过的端口集合；默认跳过已连接端口。

• feature_filter – 如果提供该参数，则只连接支持此功能的设备（有效名称见 _check_feature_support）。

返回:

已连接的 SmartUSBHub 实例；如果没有可用设备则返回 None。

disconnect()

断开设备连接并停止接收线程。

该方法幂等，可安全多次调用（例如上下文管理器退出和 atexit 清理都会调用）。它会释放端口的进程内锁和跨进程锁。

is_connected()

报告串口当前是否处于打开状态。

返回:

已连接返回 True，否则返回 False。

get_channels()

返回当前连接产品的所有有效通道号（从 1 开始）。

优先使用缓存的最大通道数；不可用时回退到 CMD_GET_MAX_CHANNELS，最后回退到产品能力表。

返回:

形如 (1, 2, 3, 4) 的元组。

抛出:

RuntimeError – 无法解析通道数量时抛出。

get_device_info()

读取并缓存 Hub 的身份信息和配置。

Critical items (versions, operate mode, …) are retried for up to ~10 s each to tolerate a device that is still initializing. Optional items not supported by older firmware are treated as unavailable.

返回:

描述 Hub 的字典（id、address、versions、product、mode 等）。

set_operate_mode(mode)

设置设备工作模式。

参数:

mode – OPERATE_MODE_NORMAL（0）或 OPERATE_MODE_INTERLOCK（1）。

返回:

收到确认返回 True，否则返回 False。

get_operate_mode()

查询当前工作模式。

返回:

0（普通模式）、1（互锁模式）；无响应时返回 None。

set_channel_power(*channels, state)

设置一个或多个通道的电源状态。

参数:

• channels – 要更新的通道号（从 1 开始）。

• state – 1 表示上电，0 表示断电。

返回:

收到确认返回 True，否则返回 False。

get_channel_power_status(*channels)

查询一个或多个通道的电源状态。

参数:

channels – 要查询的通道。

返回:

单通道时返回该通道电源状态；多通道时返回 {channel: state} 字典；超时时返回 None。

get_channel_oc_status()

查询各通道过流状态。

返回:

返回 {channel: {“active”: bool, “latch”: bool}}；超时时返回 None。active 是实时 FLAG# 状态，latch 是清除前保持的锁存状态。

clear_channel_oc_latch(*channels)

清除一个或多个通道的过流锁存状态。

参数:

channels – 要清除的通道；不传参数则清除所有通道。

返回:

收到确认返回 True，否则返回 False。

set_channel_power_interlock(channel)

为某个通道设置互锁模式，或释放所有通道。

参数:

channel – 要互锁的通道；传 None 表示关闭所有通道。

返回:

收到确认返回 True，否则返回 False。

get_channel_voltage(channel)

读取单个通道的电压。

参数:

channel – 要查询的通道。

返回:

电压值，单位 mV；超时时返回 None。

抛出:

• FeatureNotSupportedError – 设备型号不支持 ADC 监测时抛出。

• ValueError – 传入列表/元组而不是单个通道时抛出。

get_channel_current(channel)

读取单个通道的电流。

参数:

channel – 要查询的通道。

返回:

电流值，单位 mA；超时时返回 None。

抛出:

• FeatureNotSupportedError – 设备型号不支持 ADC 监测时抛出。

• ValueError – 传入列表/元组而不是单个通道时抛出。

get_channel_measurements(*channels)

通过一次 V3 请求读取多个通道的电压/电流。

参数:

channels – 要查询的通道；省略时查询所有通道。

返回:

返回 {channel: {“voltage”, “current”, “fresh”, “stale”, “valid”}}；超时时返回 None。

抛出:

FeatureNotSupportedError – 设备型号不支持 ADC 监测时抛出。

get_stream_channel_measurements(*channels, timeout=None, wait_new_sample=True)

等待下一帧 V3 测量流并返回读数。

不会发送请求；设备必须已经通过 set_channel_measurement_stream 启用流模式。

参数:

• channels – 要包含的通道；省略时包含所有通道。

• timeout – 等待超时时间，单位秒；默认使用 self.com_timeout。

• wait_new_sample – 为 True 时等待新的采样 tick；为 False 时即使 tick 相同也接受下一帧流数据。

返回:

各通道读数字典（包含 sample_tick/sample_period_ms）；无数据时返回 None。

set_channel_measurement_stream(*channels, enabled=True, wait_ack=True)

启用或禁用 V3 测量流。

流帧是设备主动发送的 V3 通知，主机不会对其确认。

参数:

• channels – 要流式输出的通道；省略时包含所有通道。

• enabled – True 表示启用流模式，False 表示禁用。

• wait_ack – 为 True 时等待命令 ACK 后再返回。

返回:

成功时返回 True（或 wait_ack 为 False 时直接返回 True）；超时时返回 False。

get_latest_measurements(*channels)

非阻塞返回最近一次收到的测量数据。

返回后台接收线程缓存的最新数据。需要先通过 set_channel_measurement_stream 启动流模式。

参数:

channels – 要包含的通道；省略时包含所有通道。

返回:

各通道读数字典；如果尚未收到数据则返回 None。

set_channel_usb2_dataline(*channels, state)

设置一个或多个通道的 USB2.0 数据线状态。

参数:

• channels – 要更新的通道。

• state – 1 表示连接数据线，0 表示断开。

返回:

收到确认返回 True，否则返回 False。

set_channel_dataline(*channels, state)

Backward-compatible alias for the V1 API name.

Older releases exposed USB2 data-line control as set_channel_dataline. Keep that spelling available while the newer API uses set_channel_usb2_dataline for clarity.

get_channel_usb2_dataline_status(*channels)

查询一个或多个通道的 USB2.0 数据线状态。

参数:

channels – 要查询的通道；省略时返回所有已知通道。

返回:

返回请求通道的 {channel: state} 字典；超时时返回 None。

get_channel_dataline_status(*channels)

Backward-compatible alias for the V1 API name.

Older releases exposed USB2 data-line status as get_channel_dataline_status. Keep that spelling available while the newer API uses get_channel_usb2_dataline_status for clarity.

set_button_control(enable)

启用或禁用 Hub 物理按键。

参数:

enable (bool) – True 表示启用按键，False 表示禁用。

返回:

收到确认返回 True，否则返回 False。

get_button_control_status()

查询 Hub 物理按键是否启用。

返回:

启用时返回 1，禁用时返回 0；无响应时返回 None。

set_default_power_status(*channels, enable, status=None)

设置一个或多个通道的上电默认电源状态。

参数:

• channels – 要配置的通道。

• enable – 1 表示应用默认电源状态，0 表示禁用默认状态。

• status – 启用时的默认状态：1 表示 ON，0 表示 OFF（默认 0）。

返回:

收到确认返回 True，否则返回 False。

get_default_power_status(*channels)

查询一个或多个通道的默认电源配置。

参数:

channels – 要查询的通道。

返回:

返回 {channel: {“enabled”, “value”}}；无响应时返回 None。

set_default_dataline_status(*channels, enable, status=None)

设置一个或多个通道的上电默认数据线状态。

参数:

• channels – 要配置的通道。

• enable – 1 表示应用默认数据线状态，0 表示禁用默认状态。

• status – 启用时的默认状态：1 表示连接，0 表示断开（默认 0）。

返回:

收到确认返回 True，否则返回 False。

get_default_dataline_status(*channels)

查询一个或多个通道的默认数据线配置。

参数:

channels – 要查询的通道。

返回:

返回 {channel: {“enabled”, “value”}}；无响应时返回 None。

set_auto_restore(enable)

启用或禁用自动恢复功能。

参数:

enable (bool) – True 表示启用自动恢复，False 表示禁用。

返回:

收到确认返回 True，否则返回 False。

get_auto_restore_status()

查询自动恢复是否启用。

返回:

启用时返回 1，禁用时返回 0；无响应时返回 None。

set_device_address(address)

设置 16 位设备地址。

参数:

address (int) – 地址范围为 0x0000 - 0xFFFF。

返回:

收到确认返回 True，否则返回 False。

抛出:

ValueError – 地址超出范围时抛出。

get_device_address()

查询当前设备地址。

返回:

16 位设备地址；无响应时返回 None。

reboot_mcu()

重启设备 MCU。

MCU 会在确认后约 100 ms 重启，因此连接会丢失，通常需要随后重新连接设备。

返回:

重启命令收到确认时返回 True，否则返回 False。

factory_reset()

将设备恢复到出厂设置。

返回:

收到确认返回 True，否则返回 False。

identify_device()

Blink the device status LED quickly for a few seconds.

返回:

收到确认返回 True，否则返回 False。

set_device_alias(alias)

Store a custom device alias in the device.

Empty aliases clear the custom alias. Alias is UTF-8, up to 31 bytes.

返回:

收到确认返回 True，否则返回 False。

get_device_alias()

Query the custom device alias.

返回:

Alias string, “” when unset, or None if no response.

set_channel_name(channel, name)

Store a custom channel display name in the device.

Empty names clear the custom name and make the device fall back to CHn. Names are stored as UTF-8, up to 15 bytes.

返回:

收到确认返回 True，否则返回 False。

get_channel_name(channel)

Query a channel display name from the device.

返回:

Stored name, default CHn, or None if no response.

get_channel_names(*channels)

Query display names for one or more channels.

get_firmware_version()

查询固件版本。

返回:

固件版本；无响应时返回 None。

get_firmware_version_major()

Return the cached firmware major version, querying the device if needed.

Older firmware replies only with the minor version byte; those devices are treated as major version 1 for backward compatibility.

get_firmware_version_string()

Return a display string such as V2.1 for the cached firmware.

Format is V<major>.<minor> (minor is NOT zero-padded), e.g. major=2 minor=1 -> V2.1. (Older builds padded the minor to two digits, which rendered as the confusing V2.01.)

get_hardware_version()

查询硬件版本。

返回:

硬件版本；无响应时返回 None。

get_product_type()

查询产品类型 ID。

可选命令：旧版固件可能不会响应，此时返回 None（记录为 debug 日志，不作为错误）。

返回:

产品类型 ID；不支持或无响应时返回 None。

get_product_name()

获取已连接设备的产品名称。

返回:

产品名称（例如 “HBP_USB2_4CH”）、”Unknown(…)” 字符串；如果产品类型不可用则返回 None。

get_max_channels()

查询最大通道数量。

可选命令：旧版固件可能不会响应，此时返回 None（记录为 debug 日志，不作为错误）。

返回:

最大通道数量；不支持或无响应时返回 None。

get_serial_no()

查询设备序列号。

返回:

序列号字符串（不可用时为 “N/A”）；无响应时返回 None。

异常

class smartusbhub.SmartUSBHubError

基类：Exception

本库抛出的所有错误的基类。

捕获该异常即可处理任何 SmartUSBHub 专有失败，无需区分具体子类型。

class smartusbhub.PortBusyError

基类：SmartUSBHubError, ValueError

串口已被另一个实例或进程占用时抛出。

同时继承 ValueError，以兼容过去捕获端口忙碌时 ValueError 的调用方。

class smartusbhub.DeviceConnectionError

基类：SmartUSBHubError

设备在连接初始化期间无响应时抛出。

通常表示该端口不是 SmartUSBHub，或设备无响应。

class smartusbhub.FeatureNotSupportedError

基类：SmartUSBHubError, ValueError

已连接产品型号不支持请求的功能时抛出。

同时继承 ValueError 以保持向后兼容。

辅助函数

smartusbhub.synchronized(method)

使用实例锁串行化访问 SmartUSBHub 方法的装饰器。

当 ENABLE_SYNC_LOCK 为 True 时，被包装方法在整个执行期间持有 self.lock；为 False 时不加锁运行。

参数:

method – 要包装的实例方法。

返回:

包装后的方法。

如果本页构建时无法导入依赖，请先安装 smartusbhub_ng/requirements.txt。