# ZDYZ UT70 Python SDK

**Repository Path**: johnzchgrd/zdyz-ut70-python-sdk

## Basic Information

- **Project Name**: ZDYZ UT70 Python SDK
- **Description**: 【非官方】正点原子UT70 Python SDK
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-22
- **Last Updated**: 2026-10-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UT70 Lab

正点原子 ALIENTEK UT70 USB 测试仪的 Python SDK 与桌面测量工作台。

通过 USB HID 直接连接设备，提供实时采集、波形观察、CSV 录制、离线数据下载和快充协议控制。SDK 可独立安装；桌面界面使用 PySide6 与 pyqtgraph。

![UT70 Lab 桌面工作台，图中为模拟数据](docs/assets/ut70-lab.png)

## 开始使用

需要 Python 3.10+。电脑连接 UT70 按键一侧的 **Micro-USB HID 接口**，连接前关闭占用设备的其他上位机。

```powershell
uv sync --locked --extra gui
uv run ut70-gui
```

Windows 下也可双击仓库中的 `launch_gui.cmd`。使用独立桌面发行包时，解压完整目录后运行 `UT70Lab.exe`，无需安装 Python。

点击“连接设备”开始测量。“演示”使用明确标识的模拟数据，方便在没有设备时体验界面。

使用 pip 安装源码：

```powershell
python -m pip install ".[gui]"
python -m ut70.gui
```

提供源码、wheel 和本地桌面构建。项目版本由 Git 标签在构建时生成，可运行 `ut70 --version` 查看已安装版本。

## 桌面工作台

- 电压、电流、功率与能量仪表，D+/D− 电压、电阻和采集状态。
- 自由勾选六种监测量波形，各自独立纵轴；缩放、拖动、悬停读数和当前视区统计。
- Shift 框选区间，浮窗分析均值、方差、RMS、分位数和直方图，可移动、复制统计。
- 一键逐点 CSV 录制，记忆默认目录和文件名前后缀，冻结波形时采集与录制继续。
- 数据分析工作区，支持最近录制、实时快照、SDK / 中文 CSV、设备离线记录，以及按视区导出。
- 六档采样速率、设备屏幕设置、快充请求和异步能力反馈。
- 截图、会话日志、键盘快捷键，正常退出时保存文件并按选项恢复设备设置。
- 随 GUI 启动的本地 MCP 服务，按类记忆 agent 权限，默认仅开放设备读取与监控。
- 原创矢量应用图标，覆盖窗口、任务栏和多尺寸 Windows EXE 资源。

操作说明见 [桌面使用指南](docs/gui.md)。

进入 **Agent / MCP** 复制本地服务配置，即可让 agent 读取和监控 USB 表。协议诱骗、自动检测、设备设置和记录删除默认关闭，可在 GUI 中单独授权。接入方式与完整工具列表见 [MCP 使用指南](docs/mcp.md)。

## Python SDK

仅需 SDK 时安装基础包，不需要 Qt：

```powershell
python -m pip install .
python -m ut70 list
python -m ut70 info
python -m ut70 read --count 5
```

```python
from ut70 import UT70, SampleRate

with UT70() as meter:
    print(meter.get_version().firmware_version)
    original_rate = meter.get_sample_rate()
    try:
        meter.set_sample_rate(SampleRate.SPS_1000)
        meter.clear_measurements()
        for sample in meter.stream(count=1000):
            print(sample.voltage, sample.current, sample.power)
        print(meter.totals)
    finally:
        meter.set_sample_rate(original_rate)
```

`UT70()` 构造时不打开设备。`open()` / `with` 查询当前上传速率，采样缓冲、异步事件和主机电量累计均有独立语义；显式修改的设备设置由调用者管理。

```powershell
ut70 read --duration 10 --csv samples.csv
ut70 records
ut70 download 0 offline.csv
ut70 download 0 first-10.csv --points 10
```

CLI 创建新 CSV，已有文件不会被覆盖。更多内容见 [API 文档](docs/api.md)、[HID 协议参考](docs/protocol.md) 和 [Python 示例](examples/)。

## 功能与设备兼容性

| 功能 | 验证范围 |
| --- | --- |
| 枚举、连接、PING、版本、序列号 | Windows 真机与模拟传输 |
| V/I、D+/D−、功率、电阻、Ah/Wh | 5V 真机无负载及带负载采集；负电流有协议测试 |
| GUI 一键录制、多通道与区间分析 | 带负载真机录制、CSV 核对；鼠标交互与文件工作流自动化测试 |
| 4 / 10 / 50 / 200 / 500 / 1000 SPS | 六档真机验证，500/1000 SPS 每包五个点 |
| 屏幕查询与切换 | 基本测量、波形真机验证 |
| 离线元信息、前缀/整组下载、CSV | 完整记录真机验证，包含校验和与包序号回绕 |
| QC2 / FCP / AFC 请求 | 5V 命令及能力回复已验证，当前电源未报告可用电压 |
| PD / QC3 / SCP / PPS、自动检测、离线删除 | 参数及传输测试，实际设备效果尚未验证 |
| GUI 本地 MCP 服务 | 官方客户端 HTTP 交互与权限测试；Windows 真机读取、监控、记录元信息及前缀下载 |

实测平台为 Windows x64、Python 3.14、UT70 固件 3.5 / 硬件 2.4，USB-A 5V 输入，包含无负载与约 0.5 A 负载。其他系统和固件尚未进行硬件验证。跨平台测试配置见 [CI](.github/workflows/ci.yml)。

快充请求会改变电源电压，输入/输出端近似并联，请确保接线和负载能承受目标电压。写入成功不代表协议协商成功，应结合设备反馈和实际读数确认。固件升级、校准和 EEPROM 写入不在当前 API 范围内。

## 开发

```powershell
uv sync --locked --extra dev --extra gui --extra desktop-build
uv run pytest -m "not hardware"
uv run ruff check src tests tools examples
uv run ruff format --check src tests tools examples
uv run mypy
uv run python -m build
uv run python tools/build_desktop.py
```

使用 `src` 布局、类型标记 `py.typed`、PEP 517 构建与锁定依赖。硬件测试需显式设置 `UT70_HARDWARE=1`，详见 [开发指南](CONTRIBUTING.md)。

项目代码采用 [MIT](LICENSE) 许可证。桌面分发的第三方组件遵循各自许可证，见 [第三方依赖说明](THIRD_PARTY_NOTICES.md)。UT70、ALIENTEK 和正点原子名称归各自权利人所有；本项目为独立项目。