# Python SDK 快速开始

本页只介绍如何通过 Python 控制 SmartUSBHub。第一次使用硬件时，请先在
[选择产品与使用指南](products/index.md)中确认手上的产品，阅读对应使用指南中的接口、供电和安全说明。

如果不需要编写程序，可改用 [Control Pannel](software/control-pannel.md) 直接通过图形界面控制设备。

## 1. 准备

- Python 3.9 或更高版本。
- 使用 USB 线将设备的“指令控制”接口连接到电脑。
- 如需控制下游 USB 设备，按照对应产品使用指南完成上行数据口、辅助供电和下游设备连接。

系统识别成功后，通常会出现以下串口：

| 系统 | 常见串口名称 |
| --- | --- |
| Windows | `COMx` |
| Linux | `/dev/ttyACM*` |
| macOS | `/dev/cu.usbmodem*` |

## 2. 安装 Python SDK

通过 pip 安装：

```shell
python3 -m pip install smartusbhub
```

开发者也可以从源码安装：

```shell
git clone https://github.com/mixedsignal-labs/smartusbhub.git
cd smartusbhub
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
```

## 3. 运行第一个控制程序

下面的程序会自动发现设备，读取产品名称和通道列表，然后开启第一个通道：

```python
from smartusbhub import SmartUSBHub

hub = SmartUSBHub.scan_and_connect()
if hub is None:
    raise RuntimeError("未找到 SmartUSBHub，请检查 USB 连接和串口权限")

try:
    channels = list(hub.get_channels())
    print("产品：", hub.get_product_name())
    print("通道：", channels)
    hub.set_channel_power(channels[0], state=1)
finally:
    hub.disconnect()
```

如果使用源码仓库，还可以直接运行随附示例：

```shell
python examples/power_control_example.py
```

## 4. 下一步

- [Python 示例程序](software/examples.md)：电源循环、数据线控制、测量和多设备控制。
- [Python SDK 使用指南](software/python-library.md)：安装选项、设备发现和完整功能说明。
- [Python API 参考](api/python.rst)：类、方法和参数参考。
- [选择产品与使用指南](products/index.md)：按产品图片和标签打开对应使用指南和技术规格书。