Python SDK API 参考｜吉熙半导体

GCLight Python SDK开发者文档

本文对应 gclight==0.1.0（Alpha）。公开设备 API、模型与异常从 gclight.v1.mini 导入；当前只支持通过串口使用 Mini 协议 v1。安装步骤见快速开始。

连接与发现

from gclight.v1.mini import Mini, discover_minis

device = Mini("COM3", baudrate=115200, command_timeout=2.0)
report = device.connect()
try:
    print(report.info.serial_number)
    print(device.query_state())
finally:
    device.close()

# 仅探测明确给出的候选端口，不枚举系统串口。
for found in discover_minis(["COM3", "COM4"], command_timeout=2.0):
    print(found.port, found.serial_number, found.software_version)

接口	行为
`Mini(port, *, baudrate=115200, command_timeout=2.0, transport=None)`	构造时不执行 I/O；`port` 必须是非空字符串。默认使用串口；也可以通过 `transport` 传入自定义传输实现，但 SDK 没有内置蓝牙传输。
`connect() -> ConnectionReport`	打开指定端口、握手、识别设备并同步输出状态与实际电流。返回 `info`、`connected_at_ms`、会话 `state`。
`close() -> None`	结束会话并关闭传输，不是 `laser_off()`。
`with Mini(port) as device`	进入时 `connect()`，离开时 `close()`。
`discover_minis(candidates, *, baudrate=115200, command_timeout=2.0)`	仅探测传入候选端口，关闭每次探测连接，返回 `DiscoveredMini` 元组。没有匹配不等于系统上没有设备。

command_timeout 是正有限秒数，不是整个程序的总时限。重复连接已连接的对象会报错；恢复时先关闭，再连接。

身份、状态与查询

接口	返回值与行为
`device.info`	`DeviceInfo`：`protocol_version`、`serial_number`、`software_version`。
`device.state`	本地 `MiniState` 快照：`timestamp_ms`、`output_enabled`、`actual_current_ma`、`source`。不是每次访问都查询设备。
`query_state()`	主动查询输出状态和实际电流，更新并返回 `MiniState`。
`query_status(fields)`	接受非空、无重复的 `MiniQuery` 元组；返回 `MiniStatusSnapshot`，其 `values` 以枚举为键。
`query_bluetooth_enabled()`	返回设备蓝牙开关 `bool`；仍通过串口查询。

state 中的实际电流来自连接时读取的初始状态或 query_state() 查询结果；设备上报的状态事件可能只更新输出开关，不要把该快照当作完整的实时遥测。source 表示最近一次更新的来源，遥测数据通过事件 API 读取。

from gclight.v1.mini import Mini, MiniQuery

with Mini("COM3") as device:
    snapshot = device.query_status((
        MiniQuery.ACTUAL_CURRENT,
        MiniQuery.TEMPERATURE_1,
    ))
    print(snapshot.values[MiniQuery.ACTUAL_CURRENT])
    print(snapshot.values[MiniQuery.TEMPERATURE_1])

`MiniQuery`	值
`OUTPUT_STATE`	输出开关，`bool`
`ACTUAL_CURRENT`	实际电流，mA
`ACTUAL_VOLTAGE`	实际电压，mV
`TEMPERATURE_1`	温度，°C
`PD_DATA`	由设备配置转换的 PD 数值，不应擅自解释为光功率单位
`CURRENT_SETTING`	设定电流，mA
`BLUETOOTH_STATE`	蓝牙开关，`bool`

控制与回执

方法	行为
`laser_on(*, current_ma)`	必须显式传入电流；SDK 在同一个协议帧内先设置电流，再请求开光。
`laser_off()`	显式请求关闭输出。
`set_current(current_ma)`	仅设定电流，不切换输出开关。
`set_bluetooth_enabled(enabled)`	`enabled` 必须为 `bool`；通过串口切换设备蓝牙开关，不建立蓝牙连接。
`run_self_test()`	发起设备自检并等待结果，使用 10 秒命令等待时限，返回 `SelfTestResult(timestamp_ms, success)`；不是只读查询。

前四个方法返回 CommandReceipt，包括 timestamp_ms、outcomes 和计算属性 success；每个 CommandOutcome 包含 command_type、success 与各字段结果。设备拒绝命令会抛出 CommandRejectedError，不能仅等到一个 success=False 的返回值。

电流参数接受 int / float，拒绝 bool、负数、NaN、无穷及超过两位小数的值；还需符合已识别设备配置的电流范围。不要在应用中假设所有型号共用一个上限。

设备事件与队列容量

next_event(timeout=None) -> DeviceEvent：从本地事件队列读取一条事件。None 一直等待，0 不等待，非负有限数字表示最多等待多少秒。超时抛出 EventTimeoutError，与设备命令超时无关。
iter_events()：持续读取事件并一直等待，不提供超时参数。如需限制等待次数或时长，请在固定次数的循环中调用 next_event(timeout=...)。
event_stats：返回 dropped_telemetry_count 和 coalesced_state_count。事件写入速度超过应用读取速度时，队列满后可能丢弃遥测或合并状态。事件 API 不保证保留每一条设备上报。

事件类型	字段
`TelemetryReport`	`timestamp_ms`，以及可为 `None` 的 `current_ma`、`voltage_mv`、`pd_data`、`temperature_1_celsius`、`current_setting_ma`。
`StatusReport`	`timestamp_ms`、`output_enabled`。
`ExceptionReport`	`timestamp_ms`、`error_bits`。这是设备报告的异常信息，不是 Python 抛出的异常。

这些报告还保留 raw_fields。如果队列已满且无法保存异常报告，SDK 可能会抛出 EventBufferOverflowError。不要忽略该错误；应停止正常控制流程，检查事件读取速度和设备安全状态，再重新连接。

异常与恢复

设备库异常的公共基类为 GCLightError；参数校验还可能抛出 Python 的 ValueError 或 TypeError。

异常	应对
`ConnectionError` / `HandshakeError`	检查端口、占用、驱动和线缆；连接失败后先 `close()` 再重试。
`UnsupportedDeviceError` / `UnsupportedProtocolVersionError`	核对支持的 Mini 与协议 v1，不绕过识别。
`DeviceDisconnectedError` / `TransportError`	检查连接与设备安全。首次发送失败会抛出 `TransportError`；之后 SDK 可能拒绝新命令，因为它无法确认会话状态。
`CommandRejectedError`	检查设备拒绝的命令与字段；不能假设同一个协议帧中的所有操作都没有执行。
`DeviceBusyError`	同一会话已有待处理命令；不要在同一会话中并发发送命令。
`CommandTimeoutError` / `SessionDesynchronizedError`	设备是否执行命令可能无法确认；先保证硬件安全，再关闭、重连并查询状态。不要自动重发控制命令。
`ProtocolError`（含 `FrameError`、`CrcError`、`TlvError`、`MessageValidationError`）	检查协议或数据错误，关闭并重新连接；不要假设当前会话还能继续使用。
`EventTimeoutError`	本地事件等待到期；可继续等待，不需要仅因此重连。
`EventBufferOverflowError`	事件队列已满，部分事件没有保留；确认数据缺口与设备安全状态后再重连。

命令超时、发送失败或命令结果解析错误后，SDK 可能无法确认当前会话状态。此时不能继续发送命令，但只要连接尚未终止，仍可通过事件 API 读取设备上报。恢复顺序必须是 close()、connect()、query_state()。SDK 不会自动重试或重发控制命令。会话状态异常时，关光命令也可能失败，因此软件清理不能替代硬件安全保障。

相关页面：SDK 快速开始 · CLI 命令参考。