跳到主要内容
版本:v3.3.0

OnBoard™ IoT Security Programming CLI - v3.0.5

1. 修订记录​

版本更新时间备注
v1.0.02025/05/12初始版本
v3.0.02026/01/22增加了以下九个命令:
  • 登出 Edge Service
  • 查询登录类型
  • 查询批次列表
  • 绑定批次
  • 推送烧录事件
  • 解压烧录脚本
  • 查看日志配置
  • 开启日志收集
  • 关闭日志收集

删除了以下三个命令:
  • 查询 Identity U-Safe 信息
  • 查询工具版本
  • 下载工具更新包

修改了以下两个命令:
  • 登录 Edge Service 命令新增了 --stationId 参数
  • 查询批次信息命令的输出(output)中新增了 scriptUrl 字段
v3.0.12026/03/13登录 Edge Service 命令中的 --stationId 参数由必填改为可选
v3.0.22026/03/17在查询烧录脚本命令章节新增烧录脚本下载说明,并更新相应的命令示例
v3.0.32026/06/02
  • 增加了下载大型固件命令
  • 登录 Edge Service 命令新增了 --stationVersion 参数
v3.0.42026/09/19
  • 新增 PPCLI(Programming Process Control CLI)及 Telink 专用烧录接口,并补充 UI(Programming Station 客户端)调用说明;
  • 补充从登录、批次准备、烧录脚本准备到设备烧录的完整调用流程;
  • 补充烧录过程中的进程启动、输出读取、结果判定及异常处理说明;
  • 更新相关命令参数及烧录流程说明。
v3.0.52026/09/22新增“执行批次 APDU 操作”命令,包括参数、调用示例、HTTP 映射、返回结果及错误码说明。

2. 概述​

OnBoard™ IoT Security (OBIS) Programming CLI 是专为 OBIS 打造的命令行工具,专门用于设备烧录。它功能全面,你可以通过它登录 Edge Service,查询 Identity U-Safe 列表,查询和推送批次数据,推送烧录结果,以及查询和下载烧录脚本。

本文将介绍 OBIS Programming CLI 的常用命令,并提供各命令的参数说明与使用示例,帮助你高效完成设备烧录及相关操作。本文同时介绍 UI(Programming Station 客户端)通过 PPCLI(Programming Process Control CLI)或专用烧录接口启动设备烧录的接入方式,以及从登录、批次准备、烧录脚本准备到设备烧录及结果处理的完整调用流程。

备注

更多信息请参考:

  • [烧录脚本自定义修改指南]
  • 烧录接口调用时序图

3. OBIS Programming CLI 语法​

obiscli [命令] [子命令] [参数]

信息

命令行参数中包含空格的字符串必须使用双引号 " 括起来,否则命令解析可能失败。

  • 正确示例:--chipVendor="Test Labs"
  • 错误示例:--chipVendor=Test Labs

4. OBIS Programming CLI 命令​

4.1 查询工具帮助​

用于查询命令行工具的使用说明及可用参数信息。

4.1.1 参数​

--help

4.1.2 示例​

obiscli.exe --help
positional arguments:
OBIS CLI Tool Command
login Login to OBIS Local Service.
logout logout to OBIS Local Service.
usafe OBIS usafe commands.
batch OBIS batch commands.
script OBIS batch commands.
obisexe OBIS commands.
logCollect OBIS batch commands.
addPath add sys Path.

options:
-h, --help show this help message and exit
-v, --version Displays version information.
-r, --release Displays release information.

4.2 登录 Edge Service​

用于登录 Edge Service。

4.2.1 命令​

login

4.2.2 参数​

参数类型是否必填说明
--ipstring是Programming Station 客户端 IP,默认值:127.0.0.1
--portstring是Programming Station 客户端端口,默认值:32333
--stationIdstring否烧录站 ID
--stationVersionstring否Programming Station 客户端版本
--factorytypestring否工厂类型,默认值:本地
--passwordstring否登录密码,仅在启用密码登录时需要填写
--usafesnstring否U-Safe Serial Number(序列号)

4.2.3 示例​

# 无密码登录:
obiscli login --ip=192.168.40.100 --port=32333 --stationId 81045379
# u-safe 登录:
obiscli login --ip=192.168.40.100 --port=32333 --usafesn=00003F00AB013668 --stationId 81045379
# 密码登录:
obiscli login --ip=192.168.40.100 --port=32333 --password=12345678 --stationId 81045379
或
obiscli login --ip=192.168.40.100 --port=32333 --password=12345678
输出:
{
"stationid": "94221070",
"token": "b69a9fe7-9df4-4bdc-819e-9b84a7bc0b23",
"tokenexpire": "unlimited"
}

4.3 登出 Edge Service​

用于登出 Edge Service。

4.3.1 命令​

logout

4.3.2 示例​

# 登出
obiscli logout

4.4 查询登录类型​

用于查询登录 Edge Service 的类型。

4.4.1 命令​

login

4.4.2 子命令​

queryType

4.4.3 参数​

参数类型是否必填说明
--ipstring是Programming Station 客户端 IP,默认值:127.0.0.1
--portstring是Programming Station 客户端端口,默认值:32333
--stationIdstring是烧录站 ID

4.4.4 示例​

obiscli login queryType --ip=192.168.40.205 --port=32333 --stationId=97123586

输出:(1 无密码、 2 密码登录、3 U-safe登录)
{
"loginType": 3
}

4.5 查询登录选项​

用于查询登录 Edge Service 的具体选项。

4.5.1 命令​

login

4.5.2 子命令​

queryoptions

4.5.3 参数​

参数类型是否必填说明
--ipstring是Programming Station 客户端 IP,默认值:127.0.0.1
--portstring是Programming Station 客户端端口,默认值:32333
--usafesnstring是U-Safe Serial Number(序列号)
--factoryTypestring否工厂类型,默认值:本地
--stationIdstring否烧录站 ID

4.5.4 示例​

obiscli login queryoptions --factoryType=local --ip=192.168.40.100 --port=32333 --usafesn=00003F00AB013668

4.6 查询 Identity U-Safe 列表​

用于列出已插入本地设备的 Identity U-Safe。

4.6.1 命令​

usafe

4.6.2 子命令​

list

4.6.3 示例​

obiscli usafe list
输出:
{
"usafelist": [
{
"usafesn": "0001BC00B86DA2BB"
}
]
}

4.7 查询批次信息​

用于查询待烧录设备对应批次的信息。

4.7.1 命令​

batch

4.7.2 子命令​

query

4.7.3 示例​

obiscli batch query

输出:
{
"batches": [
{
"batchId": "7346273795440640",
"batchName": "UI-jason-0925",
"chips": [
{
"chipPart": "QPG6200",
"chipVendor": "Qorvo",
"objectid": "4bb81efb504248fe813c83a4ed4602ac"
}
],
"env": "test",
"extData": "VID : 0xFFF2 PID : 0x8001",
"mark": "",
"notes": "",
"orderNo": "",
"produced": 0,
"productName": "pn",
"toBeProduced": 100,
"total": 100,
"version": "UI-test-0925",
"region": "",
"assignStation": null,
"scriptName": "Qorvo-UI-test-0925.zip",
"scriptUrl": "http://127.0.0.1:32333/api/iot-factory-edge-service/download?fileId=1971056408956178434&fileName=1ab0f4bf62f79dba4bb4d126ed91518a.zip"
}
]
}

4.8 查询批次列表​

用于查询工厂订单号对应的批次列表。

4.8.1 命令​

batch

4.8.2 子命令​

queryList

4.8.3 参数​

参数类型是否必填说明
--orderNumberstring是工厂订单号

4.8.4 示例​

obiscli batch query

输出:
obiscli batch queryList --orderNumber "LDS-19990101-1030BTC"

输出:
[
{
"batchId": "8725582734950400",
"batchName": "Test-Order-5"
}
]

4.9 绑定批次​

用于绑定批次到烧录站。

4.9.1 命令​

batch

4.9.2 子命令​

assign

4.9.3 参数​

参数类型是否必填说明
--batchIdstring是批次 ID

4.9.4 示例​

obiscli batch assign --batchId 7176076344164352

输出:
{
"batches": [
{
"batchId": "7346273795440640",
"batchName": "UI-jason-0925",
"chips": [
{
"chipPart": "QPG6200",
"chipVendor": "Qorvo",
"objectid": "4bb81efb504248fe813c83a4ed4602ac"
}
],
"env": "test",
"extData": "VID : 0xFFF2 PID : 0x8001",
"mark": "",
"notes": "",
"orderNo": "",
"produced": 0,
"productName": "pn",
"toBeProduced": 100,
"total": 100,
"version": "UI-test-0925",
"region": "",
"assignStation": null,
"scriptName": "Qorvo-UI-test-0925.zip",
"scriptUrl": "http://127.0.0.1:32333/api/iot-factory-edge-service/download?fileId=1971056408956178434&fileName=1ab0f4bf62f79dba4bb4d126ed91518a.zip"
}
]
}

4.10 查询批次完整数据​

用于查询待烧录到设备的完整数据。该命令通常由 PPCLI 或厂商烧录脚本调用,UI 无需直接调用。

4.10.1 命令​

batch

4.10.2 子命令​

getfulldata

4.10.3 示例​

obiscli batch getfulldata

4.11 查询批次固定数据​

用于查询待烧录到设备的固定数据。该命令通常由 PPCLI 或厂商烧录脚本调用,UI 无需直接调用。

4.11.1 命令​

batch

4.11.2 子命令​

getFixData

4.11.3 示例​

obiscli batch getFixData

4.12 查询批次变化的数据​

用于查询待烧录到设备中的变化数据。该命令通常由 PPCLI 或厂商烧录脚本调用,UI 无需直接调用。

4.12.1 命令​

batch

4.12.2 子命令​

getChangingData

4.12.3 示例​

obiscli batch getChangingData

输出:
{
"batchId": "7115488079380480",
"batchName": "V1.8.5 Dual Button 0906 MP",
"bundles": [
{
"type": "dataBundle",
"section": "Matter configuration",
"items": [
{
"itemId": "e8bbfea5a22d4a61b9598aa91768da59",
"key": "matterCommissioningParameter",
"objectId": "bf8e0546d8c94df9ab8b1515ce8549a0",
"parentId": "5782007674044416",
"fieldType": "MatterCommissioningParameter",
"attribute": {
"iterations": 10000,
"saltLength": 32,
"commissioningFlows": "0",
"discoverableMode": "2",
"vid": "117C",
"pid": "8001",
"salt": "tfuoTUAvBYS7SNuKPZFCZ9A3TyZcFP96/13hD7IazAc=",
"verifier": "JKIVX20r6RPyUGGr0ah2bmfBYnjwSBTVPPpMb4pI6WsEIfzUR/y1CHKGTUwAx0lOksfqsX+Pok4I67rwhdyD9d5wH1YdmHZWiUDh/0zQ5JpxwcEyYvVRDAviOPK4wRLuTQ==",
"manualCode": "06092517162",
"qrcode": "MT:EX7A0-C714OGWX2MM00",
"passcode": "28126717",
"uniqueid": "7DdztBdDed9qR8JS0AjJhQ==",
"discriminator": "900",
"enableRotatingDeviceId": true
}
}
]
},
{
"type": "dataBundle",
"section": "Factory data",
"items": [
{
"itemId": "5916073910c24104b32d39b4942fa276",
"key": "manufacturingDate",
"objectId": "27fb6209dca147b9be9f4e0ab3051135",
"parentId": "5782007674044416",
"fieldType": "String",
"attribute": {
"value": "20250925"
}
}
]
}
],
"uuid": "8a21200d-0be4-4ce6-8cdf-a0b02c33ba50"
}

4.13 推送批次数据​

用于推送需要上传到 Edge Service 的数据。该命令通常由 PPCLI 或厂商烧录脚本调用,UI 无需直接调用。

4.13.1 命令​

batch

4.13.2 子命令​

putdata

4.13.3 参数​

参数类型是否必填说明
--batchIdstring是批次 ID
--chipVendorstring是芯片供应商名称,例如:Silicon Labs
--chipPartstring是芯片型号
--datajson是推送数据
--uuidstring是通用唯一识别码

4.13.4 示例​

obiscli batch putdata --uuid=24a1c3da-459a-429b-a717-29989f926d43 --batchId=4808741360762880 --chipVendor="Silicon Labs" --chipPart=EFR32MG24B210F1536IM48 --data="{\"bundles\": [{\"items\": [{\"key\": \"dacTemplate\", \"response\": [{\"csr\": \"MIHmMIGNAgEAMCsxKTAnBgNVBAMMIERBQyA1SFNmblpxVSBNdmlkOjE0NDEgTXBpZDowMTIzMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXeJ5k1UtgF7YJDRm37XvHu47mTqIag4lCixpNGOMHtyOXFFpd25H4+deESQj5V3E4bRT/FNF1JjcucbEgaIR+KAAMAoGCCqGSM49BAMCA0gAMEUCIQDeR2rM9FOdCg1GTJyAOpQR2FtARVwIw3nEjXv9t7mg6wIgBcvUbH1G8NAlB/I7rOY48b/Fgnf5UkEOMx/7eekcU0k=\"}]}], \"section\": \"section\"}]}"

4.14 执行批次 APDU 操作​

用于在需要 APDU(Application Protocol Data Unit,应用协议数据单元)交互的烧录流程中,通过平台服务执行 APDU 操作。该命令通常由 PPCLI 或厂商烧录脚本调用,UI 无需直接调用。

4.14.1 命令​

batch

4.14.2 子命令​

executeApdu

4.14.3 参数​

参数类型是否必填说明
--batchIdstring是当前烧录批次 ID,应与本次设备数据所属批次一致。
--uuidstring是本次设备数据或烧录记录的 uuid,应使用当前烧录流程中获取的标识,不能使用烧录器 serialno 替代。
--datastring否JSON 对象格式的额外请求字段,解析后合并到请求体顶层。例如 programmingTraceId 以及服务端协议要求的命令响应数据。具体字段、类型及各阶段是否需要传入,以实际服务端协议为准。
提示
  • --batchId 和 --uuid 在当前参数解析器中未设置为必填参数,但命令不会从当前绑定批次或数据缓存中自动补全。调用时应传入有效的 batchId 和 uuid;省略时,请求中的对应值为 null,最终业务校验由服务端完成。
  • 调用前应已成功登录,并获取当前批次及本次设备数据的相关标识。服务地址及会话 token 由 OBIS Programming CLI 从本地配置读取,无需在本命令中重复传入登录参数。
  • --data 应为有效的 JSON 对象,不能传入文件路径、普通字符串或数组。当前实现将其中的字段直接合并到请求体顶层,不会额外增加 data 层;同名字段会覆盖原有值,因此不应在 --data 中重复传入 batchId 或 uuid。
  • 本命令不支持 --chipVendor、--chipPart 或 --serialno 参数。
  • 是否需要多次调用 executeApdu、如何提交上一轮命令响应以及如何判断 APDU 流程结束,由具体服务端协议确定。

4.14.4 示例​

不包含额外请求字段时:

obiscli batch executeApdu --batchId="<BATCH_ID>" --uuid="<UUID>"

需要传入 programmingTraceId 时,其他业务字段按服务端协议补充:

obiscli batch executeApdu --batchId="<BATCH_ID>" --uuid="<UUID>" --data="{\"programmingTraceId\":\"<PROGRAMMING_TRACE_ID>\"}"

以上两个示例展示不同的参数形式,不表示必须连续执行两次。--data 的具体使用方式及其中包含的业务字段,以实际服务端协议为准。

上述 --data 中的 \" 转义适用于 Windows cmd.exe 示例。应用程序通过进程 API 调用时,应直接在参数数组中传入 JSON 字符串,无需额外添加供 Shell 使用的引号或转义。

4.14.5 HTTP 映射​

OBIS Programming CLI 将 executeApdu 请求发送至以下接口:

项目说明
MethodPOST
Path/api/iot-factory-edge-service/executeApdu
Content-Typeapplication/json
Sessionx-snbps-session 使用当前登录 token
Request IDx-snbps-request-id 由 OBIS Programming CLI 自动生成
Timestampx-snbps-timestamp 由 OBIS Programming CLI 自动生成

本地模式使用已保存的 IP 和 port;云端模式使用已保存的 host,并在配置存在时自动加入 factoryId。

例如,包含 programmingTraceId 的命令对应的请求体如下:

{
"uuid": "<UUID>",
"batchId": "<BATCH_ID>",
"programmingTraceId": "<PROGRAMMING_TRACE_ID>"
}

4.14.6 返回结果与退出码​

OBIS Programming CLI 解析 HTTP 响应后,当 respCode 为字符串 "8000" 且 respData 不为 null 时,将 respData 本身格式化为 JSON 输出,并以退出码 0 结束。

CLI 不会同时输出外层的 respCode 和 respMsg。respData 的具体业务结构由服务端定义,当前 CLI 未规定固定字段。

退出码说明
0本次接口调用成功。调用脚本仍需根据业务协议处理返回数据,不能仅据此判断整个设备烧录流程已经完成
1--data 不是有效的 JSON 文本
45HTTP 客户端调用失败,CLI 输出 executeApdu failed: Network error
46成功响应中的 respData 缺失或为 null。当前实现不会仅因空对象 {} 或空数组 [] 返回该错误
服务端 respCode 转换后的整数值当 respCode 不为 "8000" 时,CLI 输出 respMsg,并以对应的业务错误码退出
200出现未捕获异常,例如响应无法解析,或业务错误码无法转换为整数

APDU 步骤完成后,PPCLI 或厂商烧录脚本继续按照原烧录流程执行后续操作,并通过 batch putresult 上报最终烧录结果。executeApdu 不替代 batch putresult。

4.15 推送烧录结果​

用于推送烧录结果到 Edge Service。该命令通常由 PPCLI 或厂商烧录脚本调用,UI 无需直接调用。

4.15.1 命令​

batch

4.15.2 子命令​

putresult

4.15.3 参数​

参数类型是否必填说明
--batchIdstring是批次 ID
--changeKeysstring是如果不使用服务数据,请输入 key。支持的 key 请参考可查询键列表 (queryKeys V2)
--resultstring是烧录结果
--uuidstring是通用唯一识别码

4.15.4 示例​

obiscli batch putresult --batchId=4808741360762880 --uuid=24a1c3da-459a-429b-a717-29989f926d43 --result=success --changeKeys=''

4.16 推送烧录事件​

用于推送烧录事件到 Edge Service。

4.16.1 命令​

batch

4.16.2 子命令​

uploadEvent

4.16.3 参数​

参数类型是否必填说明
--batchIdstring是批次 ID
--uuidstring是设备唯一标识符
--eventstring否烧录事件

4.16.4 示例​

obiscli batch uploadEvent --batchId=4808741360762880 --uuid=24a1c3da-459a-429b-a717-29989f926d43 --event "{\"uuid\":\"24a1c3da-459a-429b-a717-29989f926d43\", \"events\": [{\"eventName\": \"Generate Trace ID\", \"timestamp\": \"2026-01-09T09:46:02.672Z\", \"source\": \"script\", \"priority\": \"1\", \"status\": \"success\", \"content\": \"\"}, {\"eventName\": \"Fetch Batch Dynamic Data\", \"timestamp\": \"2026-01-09T09:46:04.538Z\", \"source\": \"script\", \"priority\": \"1\", \"status\": \"success\", \"content\": \"\"}, {\"eventName\": \"Fetch Device ID\", \"timestamp\": \"2026-01-09T09:46:07.340Z\", \"source\": \"script\", \"priority\": \"1\", \"status\": \"success\", \"content\": \"\"}, {\"eventName\": \"Fetch CSR\", \"timestamp\": \"2026-01-09T09:46:27.433Z\", \"source\": \"script\", \"priority\": \"1\", \"status\": \"success\", \"content\": \"\"}, {\"eventName\": \"Program Factory Data\", \"timestamp\": \"2026-01-09T09:46:33.631Z\", \"source\": \"script\", \"priority\": \"1\", \"status\": \"success\", \"content\": \"\"}, {\"eventName\": \"Report Programming Result\", \"timestamp\": \"2026-01-09T09:46:35.726Z\", \"source\": \"script\", \"priority\": \"1\", \"status\": \"failure\", \"content\": \"['[ERROR][ppcli]1200000486:Command failed with exception: 2\\n result.exit_code:2 retry_times:1.']\"}]}"

4.17 查询烧录脚本​

提示

建议直接使用查询批次信息命令(batch query)获取待烧录设备对应的批次信息,从中获取脚本下载链接,然后执行下载烧录脚本命令(script download)进行下载。

用于检查待烧录批次是否存在对应的烧录脚本。

4.17.1 命令​

script

4.17.2 子命令​

query

4.17.3 参数​

参数类型是否必填说明
--batchIdstring是批次 ID
--chipPartstring否芯片型号
--chipVendorstring否芯片供应商名称,例如:Silicon Labs
--productIdstring否产品 ID

4.17.4 示例​

提示

当 scriptExist 为 false 时,需要执行下载烧录脚本命令(script download)下载脚本;若为 true,则无需再次下载。

obiscli script query --batchId=4808741360762880 --chipVendor="Silicon Labs" --chipPart=EFR32MG24B210F1536IM48
输出:
{
"scriptExist": bool,
"path": ...
}

4.18 下载烧录脚本​

用于下载烧录脚本。

4.18.1 命令​

script

4.18.2 子命令​

download

4.18.3 参数​

参数类型是否必填说明
--urlstring是烧录脚本的下载链接
--extractFolderstring否烧录脚本下载后的解压路径
--savePathstring否烧录脚本下载后的保存路径

4.18.4 示例​

obiscli script download --url="http://192.168.40.171:8005/api/iot-factory-edge-service/download?fileId=1866310684527935298&fileName=0d232bf966e516f4bf2a75e1880e59ee.zip" --savePath="C:\\Users\\Administrator\\AppData\\Roaming\\SNB\\chipVendorCmd" --extractFolder="C:\\Users\\Administrator\\AppData\\Roaming\\SNB\\chipVendorCmd"

4.19 解压烧录脚本​

用于解压烧录脚本。

4.19.1 命令​

script

4.19.2 子命令​

extract

4.19.3 参数​

参数类型是否必填说明
--extractFolderstring否文件的解压路径
--zipFilestring否压缩文件的路径,文件格式必须是 .zip

4.19.4 示例​

obiscli script extract --zipFile="C:\\Users\\Administrator\\AppData\\Roaming\\SNB\\chipVendorCmd\\Silicon Labs.zip" --extractFolder="C:\\Users\\Administrator\\AppData\\Roaming\\SNB\\chipVendorCmd"

4.20 日志配置​

用于配置日志收集的相关参数。

4.20.1 命令​

logCollect

4.20.2 子命令​

config

4.20.3 参数​

参数类型是否必填说明
--logLevelstring否日志级别控制
--collectLogPathstring否日志文件的存放目录,默认值:C:\Users\<User Name>\AppData\SNB
--collectLogSuffixstring否日志文件的后缀,默认值:.log
--mqttIpstring否MQTT Broker(服务器)的 IP
--mqttPasswordstring否连接 MQTT Broker 用户对应的密码
--mqttPortstring否MQTT Broker 的端口号
--mqttUserstring否连接 MQTT Broker 的用户名

4.20.4 示例​

obiscli logCollect config --logLevel=INFO

4.21 查看日志配置​

用于查看日志收集的相关参数。

4.21.1 命令​

logCollect

4.21.2 子命令​

showConfig

4.21.3 示例​

obiscli logCollect showConfig
输出:
{
"DEFAULT": {
"log_level": "INFO",
"log_file_path": "C:\\Users\\Administrator\\AppData\\Roaming\\iot-log-collecter\\collecter.log",
"log_rotation": "2 hour",
"log_retention": "1 days",
"send_times_save_status": "1",
"collect_log_path": "C:\\Users\\Administrator\\AppData\\Roaming\\SNB",
"collect_log_suffix": "[\".log\"]",
"send_log_mode": "1",
"source_type": "\"PS\" # ps:programming station es:edge service"
},
"MQTT": {
"broker": "192.168.40.144",
"port": "32222",
"user": "snowball",
"password": "vX4hR9tV7iE8pO9d",
"connect_crt": "",
"connect_key": "",
"topic_pub": "ekuiper/factory_log",
"qos": "1",
"first_reconnect_delay": "1",
"reconnect_rate": "2",
"max_reconnect_count": "12",
"max_reconnect_delay": "60"
},
"FACTORY": {
"factory_id": "3101175633149952",
"partner_code": "TF031A0A02B",
"programming_station_id": "94221073"
}
}

4.22 开启日志收集​

用于开始日志收集。

4.22.1 命令​

logCollect

4.22.2 子命令​

start

4.22.3 示例​

obiscli logCollect start
输出:
iot-log-collect.exe run successfully.

4.23 关闭日志收集​

用于停止日志收集。

4.23.1 命令​

logCollect

4.23.2 子命令​

stop

4.23.3 示例​

obiscli logCollect stop
输出:
iot-log-collecter.exe stop successfully.

4.24 下载大型固件​

用于下载大型固件文件。

4.24.1 命令​

downloadFw

4.24.2 参数​

参数类型是否必填说明
--urlstring是固件文件的下载链接
--savePathstring否固件文件下载后的保存路径

4.24.3 示例​

obiscli downloadFw --url <URL> --savePath <Path>
输出:
{
"downloadResult": "download firmware success."
}

5. PPCLI 烧录接口​

5.1 概述​

PPCLI(Programming Process Control CLI)用于控制设备烧录流程。UI(Programming Station 客户端)接入设备烧录时,先通过 OBIS Programming CLI 完成登录、批次绑定及烧录脚本准备,再通过烧录脚本包提供的 PPCLI(Programming Process Control CLI)入口查询烧录器并启动设备烧录。

烧录过程中所需的批次数据获取、证书请求、按需执行的 APDU 交互及烧录结果上报,由 PPCLI 或厂商烧录脚本通过 OBIS Programming CLI 完成,UI 通常无需直接调用相关接口。

5.2 Python PPCLI​

适用于烧录脚本包中包含 ppcli.py 及对应 Python 运行环境的场景。ppcli.py 为 PPCLI 入口,process.py 为其调用的厂商烧录实现。UI 应通过 ppcli.py 启动烧录,不应直接执行 process.py;具体入口以烧录脚本包说明为准。

5.2.1 使用前提​

调用 Python PPCLI 前,应满足以下条件:

  • 已登录 Edge Service,并完成当前批次绑定;
  • 已下载并准备与当前批次、芯片型号匹配的烧录脚本包,且相关依赖文件完整;
  • 将子进程的工作目录(cwd)设置为烧录脚本包的实际入口目录,即包含 ppcli.py 的目录,而非 ZIP 下载目录或 UI 安装目录;后续相对路径均以该目录为基准;
  • 当前进程及其子进程能够通过 PATH 找到正确版本的 obiscli.exe,并与前序 OBIS Programming CLI 使用相同的 Windows 用户及配置环境,以共享登录会话和当前批次绑定信息;仅 UI 使用 OBIS CLI 的绝对路径,不能保证 PPCLI 内部调用的 obiscli.exe 能够被正确找到;
  • 烧录器驱动已正确安装并连接,目标设备已上电;
  • --type、--speed、芯片供应商及芯片型号等参数应与实际烧录脚本包保持一致。

5.2.2 查询烧录器​

用于查询当前可用的烧录器。

5.2.2.1 命令​

adapter

5.2.2.2 子命令​

list

5.2.2.3 参数​
参数类型是否必填说明
--chipVendorstring是交付包识别的芯片供应商名称,通常来自批次 chips[].chipVendor;必要时按烧录脚本包约定进行映射。大小写及空格不能自行假设可互换。
--typestring是烧录器类型,具体取值以烧录脚本包配置为准
5.2.2.4 示例​
提示

--type=1 为当前示例使用的值,具体取值以实际烧录脚本包为准。

".\python-3.12.9-embed-amd64\python.exe" ".\ppcli.py" adapter list --chipVendor="<CHIP_VENDOR>" --type=1
输出:
{
"adapterList": [
{
"serialno": "<SERIALNO>"
}
]
}

查询成功后,从 adapterList 中选择目标烧录器,并将其 serialno 原样传入 program 命令。

serialno 按字符串处理。如果返回值包含前导零,例如 0008,应保留完整字符串。如果 adapterList 为空,则不应启动设备烧录;返回结果缺少必要字段或无法按约定格式解析时,应按烧录器查询失败处理。不能仅根据进程退出码为 0 判断存在可用烧录器。

5.2.3 启动烧录​

用于通过指定烧录器启动设备烧录。

5.2.3.1 命令​

program

5.2.3.2 参数​
参数是否必填类型说明
--serialnostring是来自本烧录脚本包 adapter list 返回的烧录器/通道选择标识,应保留原始字符串;不能使用 batchId、stationId、芯片 UID 或 uuid 替代
--typestring是按烧录脚本包约定填写,并与 adapter list 使用的类型保持一致;示例中的 1 具体含义由烧录脚本包定义
--chipVendorstring否当前批次所选芯片的供应商;UI 调用时应传入;如烧录脚本包使用厂商别名,应根据配置完成映射
--chipPartstring否当前批次所选芯片型号,通常来自 chips[].chipPart;UI 调用时应传入
--speedstring否烧录通信速率;示例为 115200,具体单位、有效范围及缺省行为以烧录脚本包说明为准,不统一解释为所有厂商的 UART 波特率或调试时钟
--extInfostring否厂商扩展参数;仅在烧录脚本包有明确约定时传入,无明确约定时省略,不应直接传入任意批次 JSON
5.2.3.3 示例​

当前核对的 Python PPCLI 中,--serialno 和 --type 为必填参数;其他上述参数在语法上可省略。但厂商实现可能依赖芯片供应商和芯片型号,因此 UI 调用时应传入 --chipVendor 和 --chipPart。program 无需传入 batchId,当前批次通过前序 obiscli batch assign 命令完成绑定。

".\python-3.12.9-embed-amd64\python.exe" ".\ppcli.py" program --chipVendor="<CHIP_VENDOR>" --chipPart="<CHIP_PART>" --serialno="<SERIALNO>" --speed=115200 --type=1
提示

--chipVendor、--chipPart 和 --type 的具体取值应以实际 Python PPCLI 烧录脚本包约定为准,不应直接使用 Telink 专用烧录接口示例中的 TELINK 或 telinkevk。

如烧录脚本包明确要求传入厂商扩展参数,可增加 --extInfo="<EXT_INFO>"。

5.2.4 参数检查​

可使用以下命令检查实际 Python PPCLI 包支持的参数:

".\python-3.12.9-embed-amd64\python.exe" ".\ppcli.py" adapter list --help
".\python-3.12.9-embed-amd64\python.exe" ".\ppcli.py" program --help
提示

--help 仅用于查看命令及参数定义,不执行设备烧录。

5.2.5 PPCLI 内部调用​

用于说明启动设备烧录后,PPCLI 与 OBIS Programming CLI 之间的调用关系。UI 主要负责准备运行环境、选择烧录器、启动 program 并处理输出。启动烧录后,PPCLI 根据当前批次及芯片配置执行具体烧录流程,主要包括:

  1. 调用 obiscli batch getChangingData 获取当前设备的变化数据及烧录标识;
  2. 固定数据未缓存时,调用 obiscli batch getFixData 获取并缓存固定数据,再与变化数据合并;
  3. 调用 process.py 中的厂商烧录逻辑,根据芯片及批次配置完成设备访问、证书及 Factory Data 处理、固件写入和验证等操作;
  4. 根据烧录流程需要,通过 obiscli batch putdata 与 Edge Service 进行数据交互,该调用可能发生在烧录过程中,例如提交 CSR 并获取 DAC;需要 APDU 交互时,可通过 obiscli batch executeApdu 执行相应的 APDU 烧录步骤;
  5. 烧录完成后,根据执行结果通过 obiscli batch putresult 上报 success 或 failure。前置数据获取失败、缺少有效 uuid 或 batchId,或流程异常中断时,可能无法完成结果上报。

UI 无需重复获取设备变化数据、申请 DAC 或上报同一烧录结果,上述操作由 PPCLI 或烧录脚本统一完成。

部分 Telink 烧录脚本包使用专用可执行程序直接查询烧录器并启动设备烧录。UI 应根据实际交付的烧录脚本包选择对应的烧录入口。

Python PPCLI 与 Telink 专用可执行程序属于两种不同的接入方式,二者选择其一,无需依次执行。如果 Python PPCLI 内部已调用 Telink 烧录工具,UI 仅需调用外层 PPCLI,避免对同一设备重复启动烧录。

5.3.1 查询烧录器​

用于通过 Telink 专用烧录程序查询当前可用的烧录器。

5.3.1.1 命令​

adapter

5.3.1.2 子命令​

list

5.3.1.3 参数​
参数类型是否必填说明
--chipVendorstring是芯片供应商标识,本示例使用 TELINK,不应直接替换为 Python PPCLI 使用的厂商名称
--typestring是烧录器类型,本示例使用 telinkevk,不应与 Python PPCLI 示例中的 --type=1 混用
5.3.1.4 示例​
".\Cmd\_download\_tool.exe" adapter list --chipVendor="TELINK" --type=telinkevk

上述路径表示 Cmd 目录下 _download 子目录中的 _tool.exe,不表示名为 Cmd_download_tool.exe 的单个文件。 可执行程序路径应以实际交付的烧录脚本包为准。例如,如果实际交付包中的可执行程序位于根目录,可使用:

".\Cmd_download_tool.exe" adapter list --chipVendor="TELINK" --type=telinkevk

不同烧录脚本包可能使用不同的目录结构,UI 应根据烧录脚本包配置确定可执行程序路径及工作目录,不应硬编码固定路径,也不应在目标文件不存在时自动猜测替代程序。

5.3.2 启动烧录​

用于通过指定的 Telink 烧录器启动设备烧录。

5.3.2.1 命令​

program

5.3.2.2 参数​
参数类型是否必填说明
--serialnostring是目标烧录器的设备 ID,由同一 Telink 专用程序的 adapter list 命令查询获得,应保留返回的原始字符串
5.3.2.3 示例​
".\Cmd\_download\_tool.exe" program --serialno="<SERIALNO>"

如果实际交付包中的可执行程序位于根目录,可使用:

".\Cmd_download_tool.exe" program --serialno="<SERIALNO>"

Telink 专用烧录接口的 program 命令不使用 Python PPCLI 示例中的 --chipVendor、--chipPart、--speed 和 --type 参数,不应将这些参数直接追加到 Telink 专用烧录命令中。其他烧录配置以实际 Telink 烧录脚本包说明为准。

Telink 专用烧录接口的返回结果、进度格式、超时及退出码以对应版本的烧录脚本包为准。

6. 设备烧录执行流程​

6.1 总体调用流程​

用于说明 UI 从登录 Edge Service、准备批次和烧录脚本,到调用 PPCLI 完成设备烧录的总体流程。

截图展示了总体调用流程

阶段调用方 → 接收方命令/处理后续动作的前提
1UI → OBIS CLIlogin queryType;U-Safe 登录方式下,按需执行 usafe list获取登录类型及所需身份信息
2UI → OBIS CLIlogin登录成功,并保存客户端所需的 stationid
3UI → OBIS CLIbatch query;或按订单执行 batch queryList获取完整批次信息,并确定 batchId、芯片及烧录脚本;仅包含 ID 的批次列表不能替代完整批次信息
4UI → OBIS CLIbatch assign批次绑定成功,后续启动的设备烧录使用当前绑定批次
5UI优先读取 batch query 返回的脚本 URL、名称及版本/摘要;必要时执行 script query确定复用匹配的本地烧录脚本包或重新下载
6UI → OBIS CLIscript download烧录脚本下载、解压及初始化完成,并定位实际入口目录;本地缓存命中且脚本包已准备完成时可跳过下载
7(准备)UI → PPCLI / 包入口adapter list成功查询可用烧录器,并选择目标 serialno
7UI → PPCLI / 包入口program实时接收烧录输出并等待进程结束,根据执行结果处理烧录成功、失败或结果上报异常
结束UI → OBIS CLI按需执行 batch query 刷新批次统计;会话结束时执行 logout所有通道的烧录及结果上报完成后再结束当前登录会话

第 5 步优先使用 batch query 返回的烧录脚本信息,不要求 UI 固定调用 script query;仅在实际流程需要补充查询时调用。批次返回结构随版本可能存在外层封装,应按实际使用的 OBIS Programming CLI 版本解析,不应根据 HTTP 原始响应直接假定 CLI 的 JSON 结构。

6.2 烧录阶段调用流程​

用于说明总体调用流程中阶段 7 的设备烧录过程,包括 UI 启动烧录、烧录数据获取、设备烧录及结果上报。

提示
  • getChangingData 和 getFixData为 OBIS Programming CLI 命令,分别用于获取设备变化数据和固定数据;对应的 HTTP 接口分别为 getProgrammingData 和 getMetadata,CLI 命令名与 HTTP 接口名不应混用;
  • 固定数据已缓存时,可跳过 getFixData;
  • 设备擦除、Device ID 获取、CSR/DAC 处理、Factory Data 写入、固件烧录及复位等具体步骤,由芯片及批次配置决定;
  • 非 Matter 设备或不采用设备端生成 CSR 的流程,不一定包含 CSR/DAC 处理;
  • putdata 用于烧录过程中的数据及请求/响应交互,例如 CSR/DAC 请求;对应 HTTP 接口 uploadRequestData;
  • putresult 用于上报最终烧录结果,对应 HTTP 接口 programmingResult;putdata 与 putresult 用途不同,不能互相替代。

图中展示 Python PPCLI 的典型调用流程;Telink 专用烧录接口的内部处理流程以实际交付版本为准。

截图展示了烧录阶段调用流程

6.3 完整命令示例​

用于说明从登录 Edge Service 到完成设备烧录的基本命令调用顺序。以下示例使用 Python PPCLI,Windows 命令采用 cmd.exe 语法。实际参数应根据现场环境、批次及烧录脚本包配置填写。执行过程中,应确认当前步骤执行成功后再执行下一步。Python PPCLI 与 Telink 专用烧录接口为两种不同的烧录入口,应根据实际烧录脚本包选择其中一种。

REM 1. 查询登录方式;U-Safe 登录时按需执行 obiscli usafe list
obiscli login queryType --ip="<EDGE_IP>" --port=32333

REM 2. 根据 queryType 返回的登录方式登录;以下为无密码登录示例
REM 密码登录增加 --password="<PASSWORD>";U-Safe 登录增加 --usafesn="<USAFE_SN>"
obiscli login --ip="<EDGE_IP>" --port=32333 --stationVersion="<UI_VERSION>"

REM 3. 查询批次,并获取 batchId、chips、scriptUrl 等信息
obiscli batch query

REM 4. 绑定当前批次
obiscli batch assign --batchId="<BATCH_ID>"

REM 5. 从批次查询结果中获取 scriptUrl,并检查本地是否已有匹配且准备完成的烧录脚本包

REM 6. 本地不存在可用烧录脚本包时下载
obiscli script download --url="<SCRIPT_URL>"

REM 根据下载结果定位实际入口目录,并切换工作目录
cd /d "<SCRIPT_ENTRY_DIRECTORY>"

REM 7(准备). 查询烧录器并选择 SERIALNO
".\python-3.12.9-embed-amd64\python.exe" ".\ppcli.py" adapter list --chipVendor="<CHIP_VENDOR>" --type=1

REM 7. 启动设备烧录
".\python-3.12.9-embed-amd64\python.exe" ".\ppcli.py" program --chipVendor="<CHIP_VENDOR>" --chipPart="<CHIP_PART>" --serialno="<SERIALNO>" --speed=115200 --type=1

REM program 执行完成后查看返回码;UI 应直接获取子进程返回码,不依赖此 echo
echo %ERRORLEVEL%

REM 按需刷新批次统计
obiscli batch query

REM 所有通道烧录及结果上报完成后登出
obiscli logout

使用 Telink 专用烧录接口时,仅替换阶段 7 的烧录器查询和设备烧录命令:

REM 7(准备). 查询 Telink 烧录器并选择 SERIALNO
".\Cmd\_download\_tool.exe" adapter list --chipVendor="TELINK" --type=telinkevk

REM 7. 启动设备烧录
".\Cmd\_download\_tool.exe" program --serialno="<SERIALNO>"

登录、批次绑定及烧录脚本准备流程保持不变。Telink 专用烧录程序的可执行文件路径和工作目录应以实际交付的烧录脚本包为准。

6.4 烧录脚本下载与入口目录​

用于说明 UI 下载烧录脚本后定位实际烧录入口的处理方式。

仅传入 --url 时,script download 使用默认缓存目录,并可通过返回结果中的 scriptExist 和 path 判断脚本是否已存在及其所在位置。

如果同时指定 --savePath 和 --extractFolder,UI 不应假定命令输出一定包含烧录程序的实际入口路径。应根据指定的解压目录及烧录脚本包结构定位实际入口,并确认入口程序及相关依赖文件存在。

--savePath 表示下载文件的保存目录。烧录脚本 ZIP 包内部可能包含一级或多级子目录,因此下载目录不一定等于实际烧录入口目录。

烧录脚本启动前,还应完成对应烧录脚本包要求的初始化及依赖检查。

6.5 UI 进程与结果处理​

用于说明 UI 调用 PPCLI 或 Telink 专用烧录程序时的进程启动、输出读取及结果处理要求。

项目接入要求
进程启动分别设置 executable(可执行文件路径)、args[](命令参数)和 cwd(工作目录)。优先使用绝对可执行文件路径,并设置 shell=false,直接启动目标进程。args[] 中的参数值无需额外添加供 Shell 使用的引号。
参数来源芯片厂商和型号来自当前选择的批次;serialno 来自当前烧录入口的 adapter list 返回结果;type、speed 及入口路径根据烧录脚本包配置确定。
输出读取异步持续读取 stdout 和 stderr,直到进程结束且输出读取完成,避免因仅处理单一输出流导致缓冲区阻塞。Python PPCLI 通常使用 UTF-8 编码,旧版 EXE 的输出编码以实际版本为准
枚举输出按烧录脚本包约定解析 adapter list 完整返回结果,并处理空列表、字段缺失、异常输出及非零退出码。对于多行 JSON 输出,应按完整结果解析,不应逐行作为独立 JSON 处理。
烧录输出烧录输出可能包含日志和事件信息,不应将整个 stdout 固定按单一 JSON 解析。当前核对的 Python PPCLI 可输出 [Progress]:<数值>%、[Finish]. 等进度或完成信息,失败时可能输出 {"errMsg":"..."};其他烧录脚本包的输出格式可能不同。
成功判定等待烧录进程正常结束,并根据退出码及烧录脚本包约定的最终结果判断执行状态。进度达到 100% 或输出 [Finish]. 仅用于表示烧录进度或流程完成,不应据此提前释放烧录通道,也不能单独作为平台结果上报成功的依据。
结果上报应确认烧录脚本是否将 putresult 上报失败反映到最终执行状态;如果未反映,应单独核对平台记录。批次统计变化不能单独作为某一 uuid 已成功上报的依据
失败、超时或取消保留 serialno、烧录脚本版本、退出码、stdout、stderr 及已获取的 uuid。超时或进程终止不得标记为烧录成功。重新烧录前,应确认设备状态及上一次烧录结果,避免重复获取烧录数据或申请证书。
并发处理一个活动烧录任务对应一个 serialno。实际并发能力取决于烧录脚本包、驱动及服务能力。共享同一 OBIS 登录会话时,烧录过程中不应切换当前批次或执行 logout,也不应替换正在执行的烧录脚本包。

6.5.1 UI 进程调用示例​

以下示例用于说明 Python PPCLI 模式下 UI 启动烧录进程时的参数组织方式,不是新增的 CLI 参数或固定接口格式:

  • executable:Python 可执行文件路径;
  • args:传递给 Python PPCLI 的命令及参数;
  • cwd:烧录脚本的实际入口目录;
  • shell:示例设置为 false,表示直接启动目标进程,不通过 Shell 执行整条命令。
{
"executable": "<入口目录>\\python-3.12.9-embed-amd64\\python.exe",
"args": [
"<入口目录>\\ppcli.py",
"program",
"--chipVendor=<CHIP_VENDOR>",
"--chipPart=<CHIP_PART>",
"--serialno=<SERIALNO>",
"--speed=115200",
"--type=1"
],
"cwd": "<入口目录>",
"shell": false
}

6.6 接入验证​

用于说明 UI 完成烧录接口接入后建议验证的主要场景。

验证项验证内容
正常流程验证登录、批次查询与绑定、脚本准备、烧录器查询、单设备烧录、进程退出状态及平台记录确认和登出流程
参数与路径验证包含空格的目录或芯片供应商名称能够正常处理;serialno 的前导零保持不变;实际可执行文件、工作目录及 type 映射正确。
设备异常验证无设备、设备拔出、serialno 错误及设备占用等场景下,UI 能够正确结束任务并保留错误信息。
平台异常验证设备数据获取失败、证书请求失败及烧录结果上报失败等场景能够正确区分,且不会仅根据烧录进度达到 100% 判断烧录成功。
连续/并发烧录验证脚本缓存命中及重新下载均能正常启动;多通道烧录时 serialno、uuid 互不混淆;烧录任务执行期间不改变共享批次或退出当前会话。
Footer Icon
Download Icon下载用户手册