支持范围
gclight 是同步、带类型标注的 Python SDK。本文对应 0.1.0，包元数据标记为 Alpha，不应视为覆盖所有设备与系统的生产级支持承诺。
- 需要 Python 3.10 或更高版本，以及可访问的串口；上游列出的运行环境为 Windows 与 Ubuntu。
- 不提供蓝牙连接传输；蓝牙 API 仅通过已有串口连接查询或切换设备蓝牙开关。
- SDK 不自动扫描系统串口。关闭 Studio 或其他占用同一串口的程序，使用系统实际分配的端口，如
COM3或/dev/ttyACM0。
只想运行命令而不编写 Python？请使用独立 CLI 下载与快速开始。
用 uv 安装
先按 uv 官方安装指南 安装 uv。在已有 Python 项目中运行：
uv add gclight
没有项目时，可先创建一个：
uv init --python 3.10 mini-demo
cd mini-demo
uv add gclight
以上命令安装可用的包版本；本文 API 以 0.1.0 为准。需要复现该版本时，使用 uv add gclight==0.1.0。
第一次连接：只读取
保存为 read_mini.py，把 COM3 替换为真实端口：
from gclight.v1.mini import Mini
# 构造对象不打开串口，也不执行设备 I/O。
device = Mini("COM3", baudrate=115200, command_timeout=2.0)
# 进入上下文才连接、握手并同步初始状态。
with device:
print(device.info.serial_number)
print(device.info.software_version)
state = device.query_state()
print(state.output_enabled, state.actual_current_ma)
uv run read_mini.py
info 是设备身份快照，state 是本地状态快照；需要主动刷新时调用 query_state()。连接会读取初始状态，不会把已经开启的输出自动关闭。在未连接时读取 info 或未同步时读取 state 会抛出 DeviceDisconnectedError。
读取设备事件
后台读取线程持续接收设备事件。next_event() 从固定容量的本地队列读取一条事件，不会轮询设备，也不会自动开光。设备没有上报时，等待超时是正常结果。
from gclight.v1.mini import (
EventTimeoutError,
ExceptionReport,
Mini,
StatusReport,
TelemetryReport,
)
with Mini("COM3") as device:
try:
event = device.next_event(timeout=1.0)
except EventTimeoutError:
print("1 秒内没有收到设备事件")
else:
if isinstance(event, TelemetryReport):
print(event.current_ma, event.pd_data)
elif isinstance(event, StatusReport):
print(event.output_enabled)
elif isinstance(event, ExceptionReport):
print(f"设备异常位：0x{event.error_bits:04X}")
print(device.event_stats)
将此代码保存为 events.py，通过 uv run events.py 执行。遥测字段可能为 None；队列满时的数据处理方式与异常恢复步骤见 API 参考。
控制输出前
下面的 finally 会尝试显式关光，但串口断开或 SDK 无法确认会话状态时，关光命令也可能失败。必须具备独立的硬件安全停机方式。
from gclight.v1.mini import Mini
with Mini("COM3") as device:
try:
# 同一帧中先设置电流，再请求开启输出。
device.laser_on(current_ma=120.00)
print(device.query_state())
finally:
device.laser_off()
set_current() 只改电流，不切换输出状态；若输出已经开启，修改电流会影响真实输出。电流参数必须非负、有限、至多两位小数，并符合已识别设备的范围。
故障与恢复
- 打不开串口：核对真实端口、USB 数据线、串口驱动与访问权限，关闭占用端口的其他程序。Ubuntu 用户通常需要
dialout组权限，修改组成员后重新登录。 - 握手或协议不兼容：确认设备是当前支持的 Mini，并使用串口协议 v1；不要反复发送控制命令尝试识别未知设备。
- 命令超时或发送失败：设备可能已经执行命令，不能把报错当作“没有开光”。此后 SDK 可能无法确认会话状态，也不会自动重发控制命令。
- 恢复顺序：先按现场安全规程确认输出安全，再
close()、connect()，重新查询状态并由应用决定下一步。不要无条件重放laser_on()。