GC-Light CLI 命令参考｜吉熙半导体

GCLight CLI开发者文档

本文以 CLI 0.1.0 源码为准，底层使用 gclight==0.1.0。先按快速开始下载独立文件，或用 uv 运行源码。以下 gcli 表示程序入口：独立文件需替换为对应平台的文件路径，源码方式需替换为 uv run gcli。

命令结构与公共参数

gcli --version
gcli version
gcli --help
gcli mini --help
gcli mini status --help

--version 与 version 都输出 CLI 和 SDK 版本文本。未指定子命令时，gcli 与 gcli mini 显示帮助并返回 0。mini bluetooth 必须再指定 get、enable 或 disable。

连接参数是 mini 的公共参数，必须写在 mini 后、具体操作前。info、state、status、控制及事件命令都要求显式端口；discover 改用子命令后的候选端口位置参数：

参数	默认值	约束
`-p PORT`、`--port PORT`	无；除 `discover` 外必填	显式串口，如 `COM3`、`/dev/ttyACM0` 或 `/dev/cu.usbmodem1101`。
`--baudrate N`	`115200`	正整数。
`--command-timeout SECONDS`	`2.0`	正有限秒数，设备命令等待时限，不是整个进程的总时限。

正确结构如 gcli mini -p COM3 --command-timeout 3 state。旧结构 gcli mini state --port COM3 不再接受，会以解析错误退出。命令自身的参数仍放在具体操作后，例如 status 的字段或 laser-on 的 --current-ma。每个设备操作建立自己的串口会话，在结束时关闭；多个 CLI 调用不是一个持久连接。

发现与只读查询

命令	行为与输出
`mini [--baudrate N] [--command-timeout SECONDS] discover PORT [PORT ...]`	至少一个候选端口；不要求 `-p/--port`。输出 `devices` 数组，元素含 `port`、`serial_number`、`software_version`。
`mini -p PORT info`	返回 `protocol_version`、`serial_number`、`software_version`。
`mini -p PORT state`	查询并返回 `timestamp_ms`、`output_enabled`、`actual_current_ma`、`source`。
`mini -p PORT status [FIELD ...]`	查询指定字段；省略字段时查询下表全部七项。字段不可重复。返回 `timestamp_ms`、`values`、`raw_fields`。
`mini -p PORT bluetooth get`	返回 `{"enabled": true}` 或 `{"enabled": false}`。通过串口查询，不建立蓝牙连接。

gcli mini discover COM3 COM4
gcli mini -p COM3 info
gcli mini -p COM3 state
gcli mini -p COM3 status actual-current actual-voltage temperature-1
gcli mini -p COM3 bluetooth get

discover 只探测提供的候选端口，重复名称只探测一次；无法打开或识别的候选会被跳过，探测连接会关闭。因此 {"devices":[]} 也可以返回退出码 0，它不证明系统没有设备或端口权限正常。

status 字段

命令行名称使用连字符；返回的 values JSON 键使用下划线。例如参数 actual-current 对应键 actual_current。

CLI 字段	JSON 键	含义
`output-state`	`output_state`	输出开关，布尔值
`actual-current`	`actual_current`	实际电流，mA
`actual-voltage`	`actual_voltage`	实际电压，mV
`temperature-1`	`temperature_1`	温度，°C
`pd-data`	`pd_data`	由设备配置转换的 PD 数值，不假定光功率单位
`current-setting`	`current_setting`	设定电流，mA
`bluetooth-state`	`bluetooth_state`	蓝牙开关，布尔值

控制命令

命令	行为
`mini -p PORT laser-on --current-ma VALUE`	必须提供电流；SDK 在同一个协议帧内先设置电流，再请求开启输出。
`mini -p PORT laser-off`	显式请求关闭输出。
`mini -p PORT set-current --current-ma VALUE`	只设置电流，不改变输出开关。
`mini -p PORT bluetooth enable`	通过串口开启设备蓝牙开关，不建立蓝牙传输。
`mini -p PORT bluetooth disable`	通过串口关闭设备蓝牙开关。

--current-ma 必须是非负有限数；SDK 还限制至多两位小数及设备配置允许的电流范围。参数解析通过不代表设备一定接受。

# 仅在完成安全确认后执行；第一条命令可能产生真实激光输出。
gcli mini -p COM3 laser-on --current-ma 120.00
# 显式关光；上一条进程结束不代表已经关闭输出。
gcli mini -p COM3 laser-off
gcli mini -p COM3 state

上述是独立命令，不是故障安全序列。超时、进程中断或线缆故障可能阻止后续关光；必须具备独立硬件停机手段并确认实际输出安全。不要为失败的 laser-on 编写无条件重试。

控制成功返回对象的顶层包含 success 与 receipt；回执包含 timestamp_ms 和 outcomes。设备拒绝会作为运行错误退出，不会返回一个成功执行的 success:false 结果来代替错误。

设备事件：设置数量和超时

gcli mini -p COM3 events --count 3 --event-timeout 2

参数	默认值	含义
`--count N`	`1`	正整数，收齐 N 条事件后结束。
`--event-timeout SECONDS`	无，即无限等待	每条事件的等待时限，非负有限秒数；`0` 表示不等待。

此命令不会轮询、开光或启动遥测。没有设备上报时可能超时；不指定 --event-timeout 时，即使设置 --count 也可能永久等待。每次等待各自计时，不是整个命令共享一个 2 秒时限。

所有事件收齐后才输出一次 {"events":[...],"stats":{...}}，不是 JSON Lines 流。任何一次等待失败都会以退出码 1 结束，不会输出已经收集的部分事件。

事件可能是遥测（如 current_ma、pd_data，字段可能为 null）、状态（output_enabled）或异常报告（error_bits）。每条事件都有 timestamp_ms 和 raw_fields，JSON 不包含单独的事件类型字段。stats 包含 dropped_telemetry_count 和 coalesced_state_count。SDK 内部事件队列容量有限；应用读取速度跟不上设备上报速度时，遥测可能被丢弃，状态事件可能被合并，因此 events 不保证返回每一条设备上报。若队列已满且无法保存异常报告，SDK 可能关闭连接并返回错误。

stdout、stderr 与退出码

设备操作成功：stdout 输出一行紧凑 JSON，以换行结束；无需也没有 --json 参数。脚本不应依赖字段顺序。
版本与帮助：stdout 输出普通文本，不是 JSON。
运行错误：stderr 输出 gcli: error: ... 文本，不是 JSON；包括 SDK、操作系统及运行时参数值错误。
解析错误：缺少参数、未知命令、无效字段名等由参数解析器向 stderr 输出用法与错误文本。

退出码	含义
`0`	成功，包括版本、帮助及没有匹配设备的发现结果。
`1`	被处理的运行错误，例如串口失败、设备拒绝、命令/事件超时、重复 status 字段，或 SDK 电流范围校验失败。
`2`	命令行解析失败，例如缺少 `-p/--port`、把连接参数错误地放到子命令后、非法 `--count` 或未知字段名。

脚本必须先检查退出码，再解析 stdout。不要合并 stderr 到 stdout 后直接当 JSON 读取；未处理异常或外部信号也可能有不同的终止表现。PowerShell 使用 $LASTEXITCODE，POSIX shell 使用 $?。

如果无法确认设备是否执行了命令，先保证硬件安全，再用新的调用查询状态。CLI 不会自动重发控制命令。需要更细致的错误处理、长连接或按事件类型处理时，请使用 Python SDK API。