EdgeComputer 新手教程

← 返回使用指南
适用平台：OpenHarmony 标准系统（ZhihongOS）
云平台：https://zhihongos.cn/iot

章节	内容
一、开始之前	学什么、怎么读这份文档
二、连接开发板	hdc 连接、确认服务在跑
三、快速连云	30 分钟让网关上云
四、加载插件与查看数据	接插件、板端和云端看上报
五、端云协同原理	网关、子设备、数据怎么走
六、功能一览	服务、CLI、插件框架
七、JetLinks 配置	控制台建产品、建实例
八、命令手册	子命令与参数说明
九、插件开发	内置插件、Modbus、自定义开发
十、常见问题	连不上、看不到数据怎么办
十一、附录	命令速查、相关文档

一、开始之前

1.1 这份文档帮你做什么

EdgeComputer 是跑在 OpenHarmony 板子上的 IoT 边缘网关：板子通过 MQTT 连 JetLinks 云平台，插件负责采集本机指标、Modbus 设备、小米设备等数据，统一作为「子设备」上报。

按下面顺序读，可以从零完成一次完整对接：

第二章：用 hdc 连上板子，确认 edgecomputer_service 在运行
第三章：配置云平台地址和网关凭证，让 edge-gw-001 在 JetLinks 上显示在线
第四章：plugin load linux_device，在板端和网页上查看 cpu_usage 等属性
第五章：理解网关、子设备、物模型——读懂前三章在干什么
第八章：需要查某个参数或子命令时当字典用

第三章跑通后，就可以边做边回头看第五章；不必一次读完。

1.2 你需要准备

项目	说明
开发板	已烧录含 EdgeComputer 的 ZhihongOS 镜像
宿主机	已安装 `hdc`，能 `hdc shell` 进板子
JetLinks 账号	能登录 zhihongos.cn/iot
基础命令	会复制粘贴 Shell 命令即可；JSON 输出看得懂字段名更好

1.3 CLI 名称

官方命令是 edgecomputer（无下划线）。旧镜像若只有 edge_computer，可建软链：

bash

ln -sf /system/bin/edge_computer /system/bin/edgecomputer

查命令用法：

bash

edgecomputer --version          # 版本
edgecomputer schema             # 全部子命令与参数
edgecomputer schema cloud.set   # 单个命令的参数说明

二、连接开发板

2.1 宿主机连接开发板

bash

# 【宿主机】列出已连接设备
hdc list targets

# 进入板端 Shell
hdc shell

2.2 确认 edgecomputer_service 已运行

ZhihongOS 开机后，edgecomputer_service会由系统自动拉起，一般无需执行 service_control start。进入板端后做一次确认即可：

bash

# 【板端】查看进程（可选）
ps -ef | grep edgecomputer_service | grep -v grep

# 推荐：直接查服务状态（同时可看到 MQTT 是否已连接）
edgecomputer --format json service status

示例（进程列表）：

system        2405     1 2 14:14:40 ?     00:00:00 edgecomputer_service

若 service status 中 "ipc_ok": true 且进程存在，说明服务正常。仅在排障章节（第十章）遇到异常时，才考虑 service_control restart edgecomputer_service。

2.3 第一步验证

日常操作只需使用 edgecomputer 命令，无需记忆配置文件或日志在板端的存放路径（排障时可参考第十章）。

bash

edgecomputer --version
edgecomputer --format json service status
edgecomputer schema

示例输出：

json

{
  "cli_version": "1.1.0",
  "schema_version": "1.0.0"
}

三、快速连云

目标：30 分钟内让网关上线、子设备可见。

3.1 五步连云（复制粘贴版）

下面五步完成「板子能连上 JetLinks 云平台」。建议先看流程图建立整体印象，再按步骤复制命令操作；每一步都会说明在干什么、参数含义是什么。

前置条件：已在 JetLinks 控制台创建好网关产品/实例、子设备产品/实例（见第七章）；板端已 hdc shell 进入，且 edgecomputer --format json service status 显示 ipc_ok: true。

整体流程一览

连云本质上是两件事：先在云平台建好「户口」，再在板子上填写地址和身份并生效，最后确认 MQTT 真的连上了。

角色关系（谁连谁、谁代理谁）：

阶段	在哪里操作	做什么	对应下文
0	JetLinks 网页控制台	建产品、建实例、抄下凭证	第七章
1	板端	告诉板子云平台地址	步骤 1
2	板端	告诉板子「我是哪台网关」	步骤 2
3	板端	告诉板子「默认子设备是谁」	步骤 3
4	板端	让配置生效并重新连 MQTT	步骤 4
5	板端	检查是否真的连上	步骤 5

记忆口诀：云上单据备齐全 → 板端填地址、填网关、填子设备 → apply 生效 → test + status 验收。

步骤 1：配置云平台地址与 API 账号

作用：告诉 EdgeComputer「云平台在哪、REST 管理接口怎么登录」。MQTT 长连接地址和 JetLinks 后台 API 通常在同一域名下。

参数	含义	本教程示例值
`--host`	JetLinks MQTT Broker 域名或 IP	`zhihongos.cn`
`--port`	MQTT 端口（JetLinks 默认 1883）	`1883`
`--api-base`	JetLinks REST API 根路径，用于登录、拓扑同步等	`https://zhihongos.cn/iot/api`
`--api-user`	登录 JetLinks 后台的用户名	`<你的用户名>`
`--api-password`	对应密码	`<你的密码>`

bash

edgecomputer cloud set \
  --host zhihongos.cn \
  --port 1883 \
  --api-base https://zhihongos.cn/iot/api \
  --api-user <你的用户名> \
  --api-password '<你的密码>'

安全提示：请将 <你的用户名>、<你的密码> 替换为 JetLinks 控制台账号，勿将真实密码提交到 Git 或分享给他人。也可改用环境变量：--api-user "$JETLINKS_USER" --api-password "$JETLINKS_PASSWORD"。

此命令把配置写入本地 runtime_config.json，尚未让服务立即用新配置连 MQTT；需要步骤 4 的 config apply 才会生效。

步骤 2：配置网关身份（MQTT 登录凭证）

作用：配置网关设备在云平台上的身份。板子连 MQTT 时用的就是这里的 device_id、secure_id、secure_key，必须与 JetLinks「设备实例」页完全一致。

参数	含义	本教程示例值
`--product-id`	网关产品 ID（物模型模板）	`edge-gateway`
`--device-id`	网关设备实例 ID，也是 MQTT `clientId`	`edge-gw-001`
`--secure-id`	云平台为该实例生成的接入 ID（用户名一部分）	`edge-secure-id`
`--secure-key`	接入密钥	`edge-secure-key-2026`

bash

edgecomputer gateway set \
  --product-id edge-gateway \
  --device-id edge-gw-001 \
  --secure-id edge-secure-id \
  --secure-key edge-secure-key-2026

若这三项与云平台不一致，常见现象是 MQTT 认证失败（日志里 rc=4）。

步骤 3：配置默认子设备

作用：指定「挂在该网关下的主监控节点」是谁。linux_device 等插件会按这里的 product_id / device_id 注册子设备并上报 CPU、磁盘等属性。

参数	含义	本教程示例值
`--product-id`	子设备产品 ID	`edge-linux-child`
`--device-id`	子设备实例 ID	`edge-linux-001`
`--device-name`	在云平台显示的设备名称（可选，便于识别）	`OHOS边缘节点`

bash

edgecomputer child set \
  --product-id edge-linux-child \
  --device-id edge-linux-001 \
  --device-name 'OHOS边缘节点'

子设备不单独连 MQTT，由网关在步骤 2 建立的连接代上报（见第五章 5.3 节）。

步骤 4：应用配置

作用：把步骤 1～3 写入的配置推送给 edgecomputer_service，并触发服务重载，使 MQTT 使用新凭证重新连接云平台。

bash

edgecomputer config apply

说明
何时必须执行	修改 `cloud` / `gateway` / `child` 任一项后
典型返回	`"applied": true`, `"restarted": true`
不执行会怎样	服务仍用旧配置，云平台看不到上线或凭证错误

步骤 5：验证连通性

作用：确认「能登录 JetLinks API」且「MQTT 已真正连上」，而不是只写了配置。

命令	检查什么
`cloud test`	API 能否登录（`api.ok`）、MQTT 端口 TCP 是否可达（`mqtt.reachable`）；不测 MQTT 用户名密码是否正确
`service status`	运行中服务是否 MQTT 已连接（`connected`）、IPC 是否正常（`ipc_ok`）

全局选项 --format json 表示以 JSON 输出，便于阅读字段（脚本解析也推荐）。

bash

edgecomputer cloud test --format json
edgecomputer --format json service status

怎样算成功：cloud test 里 "ready": true；service status 里 "connected": true 且 "ipc_ok": true。详细期望输出见 3.2 节。

3.2 期望结果

检查项	命令	期望
云 API 可达	`cloud test`	`"ready": true`，`api.ok=true`
MQTT 端口可达	`cloud test`	`mqtt.reachable=true`
MQTT 已连接	`service status`	`"connected": true`
IPC 正常	`service status`	`"ipc_ok": true`

示例输出：

json

{
  "api": {
    "api_base": "https://zhihongos.cn/iot/api",
    "detail": "login_ok",
    "ok": true
  },
  "mqtt": {
    "detail": "tcp_ok",
    "host": "zhihongos.cn",
    "port": 1883,
    "reachable": true
  },
  "ready": true
}

service status 关键字段：

json

{
  "connected": true,
  "device_count": 2,
  "ipc_ok": true,
  "fallback_used": true,
  "service": "edgecomputer"
}

连云验证通过后，继续 第四章 加载插件并在网页上查看上报数据。

四、加载插件与查看数据

连云成功后，网关在线只是第一步。要让云平台看到实时数据，需要加载插件，并在板端或 JetLinks 网页上确认属性在更新。

4.1 加载系统监控插件

linux_device 是默认编入镜像的插件，采集本机 CPU、磁盘、温度等，对应子设备 edge-linux-001：

bash

edgecomputer plugin load linux_device --format json

成功时返回 "loaded": true。随后列出子设备：

bash

edgecomputer device list --format json
edgecomputer device get --device-id edge-linux-001 --format json

device get 的 properties 里应有 cpu_usage、disk_usage、temp、load_avg 等字段，数值会随采集周期变化（默认约 15 秒上报一次）。

4.2 在板端确认服务状态

bash

edgecomputer --format json service status

关注：connected 为 true 表示 MQTT 已连上；device_count 随已注册子设备数量增加（网关 + 子设备）。

4.3 在 JetLinks 网页查看

打开 https://zhihongos.cn/iot
设备管理 → 设备
点开 edge-gw-001（网关）或 edge-linux-001（子设备）
在属性或 运行状态 页查看 cpu_usage 等是否刷新

网关显示「在线」、子设备属性有数值，说明端云链路正常。

4.4 手动上报一次（可选）

插件会自动上报；也可用 CLI 手动写一条属性，便于对照网页是否更新：

bash

edgecomputer device property set edge-linux-001   --key cpu_usage --value 45.2

再到 JetLinks 设备详情里看 cpu_usage 是否变为 45.2。

4.5 加载 Modbus 插件（可选）

培训环境可再加载 Modbus 模拟设备，会多出一个子设备 child-modbus-001：

bash

edgecomputer plugin load modbus --format json
edgecomputer device list --format json
edgecomputer device get --device-id child-modbus-001 --format json

点位表与寄存器说明见第九章。

4.6 常用查看命令

想看什么	命令
已加载哪些插件	`edgecomputer plugin list --format json`
某插件是否在跑	`edgecomputer plugin status linux_device --format json`
所有子设备 ID	`edgecomputer device list --format json`
某设备当前属性	`edgecomputer device get --device-id <ID> --format json`
端云是否健康	`edgecomputer edge health --format json`

五、端云协同原理

读完前三章并跑通连云后，用本章把概念串起来：网关、子设备、物模型、数据怎么在板子和云平台之间流动。

本章用本教程里的真实设备 ID 说明四个核心概念。读完后应能回答：

为什么板子要同时有 edge-gw-001 和 edge-linux-001 两个「设备」？
cpu_usage 和 alarm 分别是什么类型？
云平台下发的「开灯」指令最终落到哪里？

5.1 四种设备形态总览

在 JetLinks 物联网平台里，设备实例是云平台侧的一条「数字身份」。按接入方式分为三类（网关子设备是第二类下的常见形态）：

形态	英文/平台类型	谁连 MQTT？	典型例子（本教程）	EdgeComputer 角色
网关设备	`gateway`	板子自己连	`edge-gw-001`	本机就是网关，持有 `secure_id/key`
网关子设备	`childrenDevice`	不直连，经网关代理	`edge-linux-001`、`child-modbus-001`	插件在板端采集，由网关代上报
直连设备	`device`	设备自己连 MQTT	带 WiFi 的智能插座、传感器	EdgeComputer 不代理此类设备
（产品）	—	—	`edge-gateway`、`edge-linux-child`	产品 = 物模型模板；实例 = 具体一台设备

一句话记忆：

产品（Product） = 图纸 / 说明书（定义能报什么、能控什么）
设备实例（Device） = 按图纸造出来的一台具体设备（有唯一 device_id）
网关 = 小区门卫 + 快递代收点（只有它能和云平台「打电话」）
子设备 = 住户（消息由门卫转发，自己不直接打云平台电话）

5.2 网关设备（Gateway）

定义

网关设备是边缘侧与 JetLinks 云平台之间的唯一 MQTT 长连接身份。在 MQTT 网关接入模式下：

板子进程 edgecomputer_service 使用网关的 secure_id + secure_key 登录 Broker
clientId 必须与云平台设备实例 ID 一致（如 edge-gw-001），否则认证失败（rc=4）
网关本身也可以有物模型（如在线状态、固件版本），但本教程主要把它当作「通道 + 管理节点」

本教程示例

字段	值	含义
产品 ID	`edge-gateway`	在 JetLinks「产品」里创建的网关产品
设备 ID	`edge-gw-001`	云平台上的网关实例名，也是 MQTT `clientId`
secure_id	`edge-secure-id`	云平台生成的接入凭证（用户名一部分）
secure_key	`edge-secure-key-2026`	接入密钥

板端配置：

bash

edgecomputer gateway set \
  --product-id edge-gateway \
  --device-id edge-gw-001 \
  --secure-id edge-secure-id \
  --secure-key edge-secure-key-2026

网关做什么、不做什么

网关负责	网关不负责
维持与 JetLinks 的 MQTT 连接	替子设备建立独立 MQTT 连接
代子设备上报属性、事件、上下线	理解每个传感器的具体协议（交给插件）
接收云平台下行指令并路由给插件	直连设备的数据转发（除非另做集成）
拓扑同步、边缘包下载	—

示例：edgecomputer service status 中 "connected": true 表示网关 MQTT 已上线；device list 里会出现 edge-gw-001 本身。

5.3 网关子设备（Children Device）

定义

网关子设备是挂在某一网关实例下的从设备。它们：

在云平台「设备实例」里 parentId 指向网关（如 edge-gw-001）
不单独使用 secure_id/key 连 MQTT
所有上行/下行消息经网关 Topic 转发，报文里携带子设备 device_id

EdgeComputer 通过设备插件（.so）在板端代表每一类子设备采集数据或执行控制。

本教程两个子设备示例

示例 A：edge-linux-001（linux_device 插件）

字段	值
产品 ID	`edge-linux-child`
设备 ID	`edge-linux-001`
设备名称	`OHOS边缘节点`
父设备	`edge-gw-001`
插件	`linux_device`
数据来源	本板 CPU、内存、磁盘、温度等系统指标

示例 device get 片段：

json

{
  "device_id": "edge-linux-001",
  "device_name": "OHOS边缘节点",
  "device_type": "childrenDevice",
  "parent_id": "edge-gw-001",
  "product_id": "edge-linux-child",
  "properties": {
    "disk_usage": 2.49,
    "load_avg": 0.11,
    "temp": 20.06
  },
  "state": "online"
}

示例 B：child-modbus-001（modbus 插件）

字段	值
产品 ID	`modbus-sensor`
设备 ID	`child-modbus-001`
父设备	`edge-gw-001`
插件	`modbus`
数据来源	Modbus TCP 从站（培训环境 `simulate: true` 可无真实 PLC）

加载插件后 device list 会从 2 台变为 3 台（含 modbus 子设备）；edge health 中 device_count 会递增。

子设备在板端如何「出现」

子设备进入 EdgeComputer 的路径通常有两种：

插件加载时自动注册（如 linux_device、modbus 按配置创建实例）
CLI 手动创建：

bash

edgecomputer device create \
  --product-id edge-linux-child \
  --device-id edge-linux-002 \
  --device-name '新边缘节点'

无论哪种方式，子设备都必须：

在 JetLinks 上已有对应产品（物模型已定义）
最好在云平台上也创建了设备实例（否则拓扑可能不一致，可用 topo sync 拉齐）

5.4 直连设备（Direct Device）

定义

直连设备指具备独立联网能力、自己用一套 product_id + device_id + 凭证连接 JetLinks MQTT 的设备，平台类型一般为 device（非 gateway、非 childrenDevice）。

典型例子：

自带 WiFi 的智能插座、温湿度传感器
另一块开发板单独跑 MQTT 客户端
手机 App 模拟的设备（测试用）

与网关子设备的对比

对比项	网关子设备	直连设备
MQTT 连接数	0（复用网关）	1（自己连）
凭证	无独立 secure_key	有自己的 secure_id/key
适用场景	RS485/Modbus/本地串口等无 IP 能力的末端	设备本身能 TCP/IP
EdgeComputer	管理并代理	不管理（除非另写插件做协议转换）
拓扑	`parent_id = edge-gw-001`	无父网关

何时仍用「网关 + 子设备」而不是直连？

场景：一条 RS485 总线上挂了 10 个温湿度探头，探头没有 IP 地址。

❌ 不能让每个探头直连 MQTT（它们上不了网）
✅ 用一个网关连云端，10 个探头作为 10 个子设备，由 modbus 插件分别映射

EdgeComputer 的定位是边缘网关：把现场总线、本地协议上的设备「翻译」成 JetLinks 能理解的子设备，而不是替代所有直连设备。

5.5 物模型（TSL）—— 设备的「说明书」

定义

物模型（Thing Specification Language，常称 TSL 或 DeviceMetadata）是一份 JSON 结构，描述某类产品能表达什么、能做什么、能告警什么。在 JetLinks 里，物模型挂在产品上；每个设备实例继承该产品的物模型，并持有自己的当前属性值。

物模型三大要素：

要素	英文	方向	作用	类比
属性	Property	可读；部分可写	设备状态（温度、开关、CPU 使用率）	体温计的读数
功能	Function	可调用（带输入/输出参数）	一次性动作（重启、自检、抓拍）	按一下「重启」按钮
事件	Event	设备 → 云（上报）	离散告警或状态变化（超限、故障）	烟雾报警器响了

此外还有：

标签（Tag）：静态或半静态元数据（位置、型号），本教程 CLI 较少涉及
读写权限：属性标记 read / write / report，决定云平台能否下发修改

关键理解：物模型只规定「字段名、类型、单位、是否可写」；具体数值由插件采集或 CLI 上报，存在设备实例的 properties 里。

示例 1：`edge-linux-child` 产品物模型（简化）

假设在 JetLinks 产品 edge-linux-child 上定义：

json

{
  "properties": [
    {
      "id": "hostname",
      "name": "主机名",
      "valueType": { "type": "string" },
      "expands": { "readOnly": true }
    },
    {
      "id": "cpu_usage",
      "name": "CPU使用率",
      "valueType": { "type": "float", "unit": "percent" },
      "expands": { "readOnly": true }
    },
    {
      "id": "disk_usage",
      "name": "磁盘使用率",
      "valueType": { "type": "float", "unit": "percent" },
      "expands": { "readOnly": true }
    },
    {
      "id": "temp",
      "name": "芯片温度",
      "valueType": { "type": "float", "unit": "celsius" },
      "expands": { "readOnly": true }
    }
  ],
  "events": [
    {
      "id": "alarm",
      "name": "阈值告警",
      "valueType": { "type": "object", "properties": [
        { "id": "level", "valueType": { "type": "string" } }
      ]}
    }
  ],
  "functions": []
}

对应关系：

物模型 ID	类型	谁产生数据	本教程如何触发
`cpu_usage`	属性	`linux_device` 每 15s 采集	插件自动上报；或 `device property set` 手动
`disk_usage`	属性	同上	同上
`alarm`	事件	业务逻辑 / 手动	`device event edge-linux-001 alarm --data '{"level":"high"}'`

手动上报属性时，key 必须是物模型里已定义的 id：

bash

edgecomputer device property set edge-linux-001 \
  --key cpu_usage --value 45.2

若上报 cpu_usage2 这种未在物模型中定义的字段，云平台可能拒绝或无法展示。

示例 2：`modbus-sensor` 产品物模型 + 点位表

Modbus 插件除云平台物模型外，还有板端点位表（把寄存器地址映射到属性 ID）：

云平台物模型（产品 modbus-sensor）：

json

{
  "properties": [
    { "id": "temp", "name": "温度", "valueType": { "type": "float" } },
    { "id": "humidity", "name": "湿度", "valueType": { "type": "float" } },
    { "id": "switch", "name": "开关", "valueType": { "type": "boolean" },
      "expands": { "readOnly": false } }
  ]
}

板端 modbus 点位表（节选）：

json

{
  "devices": [{
    "device_id": "child-modbus-001",
    "product_id": "modbus-sensor",
    "slave_id": 1,
    "points": [
      { "property": "temp",     "address": 40001, "type": "float32", "writable": false },
      { "property": "humidity", "address": 40003, "type": "uint16",  "writable": false },
      { "property": "switch",   "address": 40010, "type": "bool",    "writable": true }
    ]
  }]
}

数据流：

PLC 寄存器 40001 → modbus 插件读取 → 属性 temp → 网关 MQTT 上报 → JetLinks 展示曲线
云平台写 switch=true → 网关下行 → modbus 插件写寄存器 40010 → 从站线圈动作

这里 物模型的 switch 与 点位表的 property: switch 必须同名，否则云平台和现场设备对不上号。

属性 vs 功能 vs 事件（决策表）

遇到一个新需求时，先判断该用哪种物模型元素：

你想表达的内容	用	例子
持续存在的数值/状态	属性	温度 25.3℃、风扇开/关、CPU 42%
云平台/用户主动触发的一次性动作	功能	`reboot`、`self_check`、`capture_image`
设备主动告知「发生了某件事」	事件	`threshold_alarm`、`disk_full`、`door_opened`

物模型在 EdgeComputer 生态中的传递链

物模型不仅服务于 JetLinks 页面，还会被 EdgeMCP → EdgeClaw 复用：

JetLinks 产品物模型
    ↓ 同步/缓存
edgecomputer 设备实例 metadata
    ↓ IPC
edgemcp get_device_capabilities（返回可读/可写属性、功能列表）
    ↓ MCP
edgeclaw mcp__edge-device__* 工具（LLM 按 schema 填参数）

因此物模型定义得越清晰（中文名、枚举、取值范围），AI 控制设备就越准确。详见 edgemcp.md 第五章。

5.6 端到端示例：从物模型到云平台一条属性

以 edge-linux-001 的 cpu_usage 为例，串起产品、实例、插件、上报全链路：

步骤 1 — 云平台（JetLinks）

创建产品 edge-linux-child，物模型添加属性 cpu_usage（float，只读）
创建设备实例 edge-linux-001，父设备选 edge-gw-001

步骤 2 — 板端配置网关与子设备默认身份

bash

edgecomputer child set \
  --product-id edge-linux-child \
  --device-id edge-linux-001 \
  --device-name 'OHOS边缘节点'
edgecomputer config apply

步骤 3 — 加载插件

bash

edgecomputer plugin load linux_device

插件配置（来自 runtime_config.json）指定：

json

{
  "name": "linux_device",
  "config": {
    "child_product_id": "edge-linux-child",
    "child_device_id": "edge-linux-001",
    "report_interval_sec": 15
  }
}

步骤 4 — 自动上报（每 15 秒）

linux_device 读 /proc → 得到 cpu_usage=32.5
    → MessageReporter → MQTT Topic（子设备 edge-linux-001）
    → JetLinks 设备详情页刷新曲线

步骤 5 — 手动验证（CLI 模拟一次上报）

bash

edgecomputer device property set edge-linux-001 \
  --key cpu_usage --value 45.2

示例输出：

json

{
  "device_id": "edge-linux-001",
  "properties": { "cpu_usage": "45.2" },
  "success": true
}

打开 JetLinks → 设备实例 → edge-linux-001 → 属性，应看到 cpu_usage 更新为 45.2。

5.7 网关模式下的数据流与 Topic 路由

在 JetLinks MQTT 网关模式下，子设备不直接连 Broker，由网关代发。逻辑流程：

要点：

云平台通过 Topic + 设备 ID 区分「这是网关自己的消息」还是「某个子设备的消息」
EdgeComputer 内部维护 device_id → 插件实例 路由表
device list 同时列出网关自身与子设备（例如 edge-gw-001、edge-linux-001）

5.8 配置优先级

从高到低：

runtime_config.json（edgecomputer CLI 写入）
persist.edgecomputer.*（系统持久化参数）
环境变量
default_config.json（/system/etc/edgecomputer/，只读）
编译默认值

edgecomputer config apply 将运行时配置推送给 edgecomputer_service 并触发重启。

5.9 MQTT 认证原理

JetLinks MQTT 用户名格式含毫秒时间戳，板端系统时间与服务器偏差超过约 5 分钟会导致认证失败（rc=4）。

板端 WiFi 连上后会自动 SNTP 校时并写入 /data/service/el1/public/edgecomputer/time_synced；edgecomputer_service 启动前会等待该标记（最多 120s）。

5.10 属性 / 事件 / 上下线与物模型的关系

下表中的「物模型要求」指：对应 ID 必须在产品物模型中预先定义。

类型	方向	CLI 命令	物模型要求	说明
属性	上行	`device property set`	属性 ID 已定义	上报或覆盖当前值
事件	上行	`device event`	事件 ID 已定义	可带 `--data` JSON 载荷
上线	上行	`device online`	—	子设备状态变为 online
下线	上行	`device offline`	—	子设备状态变为 offline
写属性	下行	云平台 → 插件	属性 `writable: true`	如 modbus `switch`
调功能	下行	云平台 → 插件	功能 ID 已定义	经 `invoke` 调用

5.11 离线队列

断网时消息写入 offline_queue.json（最大 8192 条），恢复连接后每 10 秒批量重发（flush_interval_sec: 10）。

5.12 IPC 与 fallback

CLI 优先通过 Unix Socket（/data/service/el1/public/edgecomputer/edgecomputer.sock）与 edgecomputer_service 通信。若 IPC 不可用，部分命令会 fallback 到直接读配置文件（fallback_used: true）。

六、功能一览

EdgeComputer 由 系统服务 + CLI 工具 + 插件框架 三部分组成。

6.1 模块总览

6.2 核心模块说明

模块	二进制/文件	职责
系统服务	`edgecomputer_service`	MQTT 长连接、子设备管理、插件调度、离线队列
CLI 工具	`edgecomputer` v1.1.0	写运行时配置、查询状态、手动上报、健康聚合
云平台适配	JetLinks 协议栈	MQTT 认证、Topic 编解码、REST API 调用
插件框架	`PluginManager` + `.so`	动态加载协议适配器，采集本地数据
配置管理	`runtime_config.json`	CLI 写入的运行时配置，优先级最高
离线队列	`offline_queue.json`	断网缓存消息，恢复后重发
边缘包部署	`packages/installed/`	云平台下发插件包到网关

6.3 插件框架（概要）

EdgeComputer 通过 PluginManager 动态加载 .so 插件，将现场数据适配为 JetLinks 子设备。默认镜像编入 linux_device、modbus、edgeclaw_session；另有 62 个可选 miio_* 小米设备插件。

插件名	一句话功能
`linux_device`	本机 CPU/磁盘/温度监控
`modbus`	Modbus TCP 工业设备
`edgeclaw_session`	EdgeClaw AI 会话桥接
`miio_*`	小米生态链设备（可选编译）

完整插件列表、配置、自定义开发与 Modbus 点位表见 第九章。

6.4 与其他 Extension 服务的关系

服务	关系
edgemcp	IPC 桥接，将物模型暴露为 MCP Tool（5 个 tool）
edgeclaw	经 edgemcp 或 edgeclaw_session 插件与设备对话
edge_engine	无直接集成（AI 推理独立运行）
edge_pipe	无直接集成（视觉管道独立运行）

edgecomputer edge health 会聚合 edgecomputer + cloud + edgemcp + edgeclaw 四项健康状态。

七、JetLinks 配置

在板端执行 cloud set 之前，需要先在 JetLinks 网页上建好网关产品、网关实例和子设备产品。各参数与 CLI 的对应关系及截图，见八、命令手册 → 8.4 cloud。

7.1 登录控制台

浏览器打开 https://zhihongos.cn/iot，使用你的账号登录（界面见命令手册 8.4.2 截图）。

7.2 创建网关产品

「设备管理」→「产品」→「新建」（或复用已有 edge-gateway）。

字段	值
产品 ID	`edge-gateway`
接入方式	MQTT 网关
设备类型	网关设备

产品 ID 在详情页 配置信息 → ID 字段查看（见 8.4 截图 07_product_gateway_detail.png）。

7.3 创建网关设备实例

「设备管理」→「设备」→ 选择 edge-gateway 产品 →「新增」。

字段	值
设备 ID	`edge-gw-001`
secureId	`edge-secure-id`
secureKey	`edge-secure-key-2026`

凭证在设备详情 配置 → MQTT 认证配置 中查看（见 8.4 截图 03_instance.png）。

7.4 创建子设备产品

同样创建子设备产品：

字段	值
产品 ID	`edge-linux-child`
接入方式	网关子设备
属性	`cpu_usage`、`disk_usage`、`temp`、`load_avg`、`hostname` 等

7.5 创建子设备实例

字段	值
产品	`edge-linux-child`
设备 ID	`edge-linux-001`
父设备	`edge-gw-001`

7.6 板端配置并验证

bash

edgecomputer cloud set --host zhihongos.cn --port 1883 \
  --api-base https://zhihongos.cn/iot/api \
  --api-user <你的用户名> --api-password '<你的密码>'
edgecomputer gateway set --product-id edge-gateway --device-id edge-gw-001 \
  --secure-id edge-secure-id --secure-key edge-secure-key-2026
edgecomputer child set --product-id edge-linux-child --device-id edge-linux-001
edgecomputer config apply
edgecomputer cloud test --format json
edgecomputer plugin load linux_device

步骤 5：回到 JetLinks 设备实例，确认 edge-gw-001 在线，edge-linux-001 属性实时更新。

7.7 MQTT 连接架构

八、命令手册

日常记不住命令时，用 edgecomputer schema 查完整列表。下面按子命令说明常用参数。

8.1 全局标志

全局标志作用于整条命令，通常写在子命令之前：

bash

edgecomputer --format json --verbose cloud test
edgecomputer --dry-run gateway set --product-id edge-gateway ...

8.1.1 标志一览

标志	类型	作用	典型场景
`--format json`	输出	以 JSON 打印结果，便于脚本解析	脚本自动化
`--format table`	输出	人类可读表格（TTY 默认 auto 选 table）	交互式排障
`--config <path>`	配置	指定配置文件路径（见 6.2 节；板端通常不需要）	Linux 独立调试、CI
`--dry-run`	行为	预览将发生的变更，不写入磁盘、不重启服务；成功时退出码 10	变更前确认
`--yes` / `--no-interactive`	行为	跳过「是否继续」类确认提示	脚本非交互执行
`--quiet`	行为	减少 stderr 警告/日志	安静模式
`--verbose`	行为	输出更详细的调试信息	排障
`--limit <n>`	分页	限制 `device list` 等列表返回条数（默认 20）	设备很多时
`--full`	行为	列表命令返回完整对象而非精简字段	需要完整 JSON 时
`--if-not-exists`	行为	用于 `cloud ensure` / `gateway ensure`：仅当配置项不存在时才写入	幂等部署脚本
`--confirm`	行为	破坏性操作（如 `device delete`）需显式确认	防误删
`--idempotency-key <key>`	行为	幂等键，防止重复提交产生副作用	自动化重试
`--version`	信息	打印 CLI 版本与 schema 版本	版本核对
`--help`	信息	打印帮助	—

8.1.2 `--format` 详解

值	行为
`auto`（默认）	终端是 TTY 时用 table，管道/重定向时用 json
`json`	始终 JSON；失败时也有结构化 `error` 字段
`table`	始终表格（部分子命令仅支持 json）

环境变量 EC_TOOL_FORMAT=json 可设置默认格式（与 --format 二选一，命令行优先）。

8.1.3 `--dry-run` 详解

项目	说明
作用	走完整参数校验与合并逻辑，但不落盘、不触发 `config apply` 式重启
成功退出码	10（表示「预览成功」，不是错误）
适用命令	`cloud set`、`gateway set`、`child set`、`config apply`、`device create/delete`、`plugin load` 等写操作
示例	`edgecomputer cloud set --host 192.168.1.100 --dry-run` → 可看将写入什么，但不改配置

8.1.4 `--config <path>` 详解（重要）

--config 用于告诉 CLI：从哪个配置文件读取/写入 EdgeComputer 应用配置（包含 jetlinks、gateway、plugins、mqtt 等完整结构）。

在 OpenHarmony 板端（本教程主场景）—— 一般不需要 --config

板端 CLI 编译时启用 EDGE_COMPUTER_OHOS，配置加载逻辑为：

固定从出厂默认 /system/etc/edgecomputer/default_config.json 合并加载
再叠加环境变量、persist.edgecomputer.* 系统参数
最后合并用户运行时文件 runtime_config.json
--config 参数在板端被忽略，不会改用你指定的路径

因此板端正确做法是：

bash

# ✅ 板端推荐：用子命令写入 runtime_config.json
edgecomputer cloud set --host zhihongos.cn ...
edgecomputer config apply

# ✅ 查看实际生效的配置文件路径
edgecomputer config path

# ❌ 板端无需、也不会生效
edgecomputer --config /tmp/my.json cloud set ...

在 Linux 独立调试 / 源码树 standalone 模式—— 需要 --config

开发机上独立运行的 edgecomputer 默认读取 configs/config.yaml（或你通过 --config 指定的 YAML/JSON 路径）。此时：

bash

# 指定自定义配置启动/操作
edgecomputer --config /path/to/my_config.yaml cloud set --host ...

场景	是否使用 `--config`	实际读写的配置
ZhihongOS 开发板端	否	`runtime_config.json`（经子命令写入）
源码 standalone 调试	是（可选）	`--config` 指向的 YAML/JSON
查看板端路径	用 `config path`	输出 `runtime_config.json` 绝对路径

与 --config 易混淆的是 config path 子命令：它不是全局标志，而是查询「当前运行时配置文件落在哪」。

8.1.5 退出码

码	含义	常见原因
0	成功	命令正常完成
1	通用错误	服务不可达、API 失败、写入失败
2	参数错误	缺少必填参数、未知子命令
3	资源不存在	设备 ID、插件名不存在
4	权限拒绝	操作被拒绝
5	冲突	状态冲突（如重复创建）
10	dry-run 成功	仅预览，未实际写入

8.2 配置文件体系

EdgeComputer 的配置不是一个单一文件，而是按优先级分层合并。理解这一点后，就不会困惑「cloud set 写到哪里」「config show 读哪里」。

8.2.1 三类配置文件

文件	板端典型路径	谁写入	能否手动改	内容概要
出厂默认	`/system/etc/edgecomputer/default_config.json`	镜像编译	只读	插件目录、数据目录、默认插件列表、MQTT QoS 等
运行时配置	`/data/service/el1/public/edgecomputer/runtime_config.json`	`edgecomputer` CLI（`cloud set` 等）	CLI 自动维护	云平台地址、网关凭证、子设备默认、插件 enabled
合并结果	内存中 `AppConfig`	服务启动时合并	—	上述文件 + 环境变量 + `persist.*` 的最终生效值

旧镜像可能使用 /system/etc/edge_computer/default_config.json（带下划线），CLI 会自动兼容。

8.2.2 合并优先级（低 → 高，后者覆盖前者）

对应源码：LoadMergedOhosConfig()（ohos_runtime_config.cpp）。

8.2.3 配置相关 CLI 与子命令的关系

你的操作	影响的文件	是否立即让服务生效
`cloud set` / `gateway set` / `child set`	写入 `runtime_config.json`	否，需 `config apply`
`config apply`	读取 `runtime_config.json` 并推送给 edgecomputer_service	是，触发服务重载/重连
`config show`	读取合并后的有效配置（脱敏）	只读
`config path`	打印 `runtime_config.json` 路径	只读
`service status` → `config` 字段	运行中服务持有的配置快照	只读

8.2.4 `runtime_config.json` 结构示例（节选）

cloud set、gateway set 后文件大致如下（密码字段可能明文存储于板端，请勿泄露）：

json

{
  "jetlinks": {
    "host": "zhihongos.cn",
    "port": 1883,
    "api_base": "https://zhihongos.cn/iot/api",
    "api_user": "<你的用户名>",
    "api_password": "..."
  },
  "gateway": {
    "product_id": "edge-gateway",
    "device_id": "edge-gw-001",
    "secure_id": "edge-secure-id",
    "secure_key": "..."
  },
  "child_defaults": {
    "product_id": "edge-linux-child",
    "device_id": "edge-linux-001",
    "device_name": "OHOS边缘节点"
  },
  "plugins": [
    {
      "name": "linux_device",
      "enabled": true,
      "config": { "report_interval_sec": 15 }
    }
  ]
}

查看完整合并结果（敏感字段显示为 ***）：

bash

edgecomputer config show --format json

8.3 命令树

edgecomputer
├── cloud      get | set | ensure | test | status
├── gateway    get | set | ensure
├── child      get | set
├── config     show | path | apply
├── service    status | connect | disconnect
├── device     list | get | create | update | delete
│              property get | property set
│              event | online | offline
├── topo       sync
├── plugin     list | load | status | unload
├── package    list | installed
├── edge       health
└── schema     [command]

8.4 cloud — 云平台连接

cloud 子命令配置的是 EdgeComputer 如何连上 JetLinks 云平台，写入 runtime_config.json 的 jetlinks 段。它解决两类连接：

连接类型	用途	对应 CLI 参数
MQTT	网关/子设备上下行消息（属性、事件、在线状态）	`--host`、`--port`
REST API	CLI 登录云平台、拓扑同步、边缘包查询等	`--api-base`、`--api-user`、`--api-password`

与 gateway set 的关系：cloud set 只配置「连到哪台 JetLinks、用什么账号调 API」；设备 MQTT 认证（product_id / device_id / secure_id / secure_key）由 8.5 gateway 配置。两者都写完后，必须执行 config apply（见 8.7 config）。

8.4.1 参数与云平台界面对照总表

下表列出 cloud set 与 gateway set 各参数在 JetLinks 控制台中的获取位置（平台地址：https://zhihongos.cn/iot）。

CLI 参数	所属子命令	云平台取值	控制台路径
`--host`	`cloud set`	MQTT 公网地址	运维管理 → 网络组件 → JetLinks MQTT → 详情 →「公网地址」
`--port`	`cloud set`	MQTT 公网端口	同上 →「公网端口」
`--api-base`	`cloud set`	REST API 根路径	控制台访问地址 + `/api`（见 8.4.2）
`--api-user`	`cloud set`	Web 登录用户名	登录页「账号」
`--api-password`	`cloud set`	Web 登录密码	登录页「密码」
`--product-id`	`gateway set`	产品 ID	设备管理 → 产品 → 详情 → 配置信息「ID」
`--device-id`	`gateway set`	设备实例 ID	设备管理 → 设备 → 详情 → 标题区 / 设备信息表「设备ID」
`--secure-id`	`gateway set`	MQTT 认证 secureId	设备详情 →「配置」→ MQTT 认证配置
`--secure-key`	`gateway set`	MQTT 认证 secureKey	同上（默认脱敏，点「编辑」查看/修改）

本教程演示环境示例值：

参数	示例值
`--host`	`zhihongos.cn`
`--port`	`1883`
`--api-base`	`https://zhihongos.cn/iot/api`
`--api-user` / `--api-password`	你的 JetLinks 控制台账号（演示环境可用 `admin` / `zhihongos`）
`--product-id`	`edge-gateway`
`--device-id`	`edge-gw-001`
`--secure-id`	`edge-secure-id`
`--secure-key`	`edge-secure-key-2026`

8.4.2 登录控制台，获取 API 账号

步骤 1：浏览器打开 https://zhihongos.cn/iot，进入登录页。

JetLinks 登录页 — 账号密码对应 cloud set 的 --api-user / --api-password

界面字段	对应 CLI 参数	说明
账号	`--api-user`	JetLinks 控制台用户名；`cloud test` 会用此账号调用 REST API 登录
密码	`--api-password`	对应用户密码；写入 `runtime_config.json` 后 CLI 输出会脱敏为 `***`

步骤 2：登录后进入物联网首页。

JetLinks 控制台首页

--api-base 如何确定：JetLinks 部署在子路径 /iot 时，REST API 根路径固定为：

https://<控制台域名>/iot/api

本环境控制台为 https://zhihongos.cn/iot，因此 --api-base 填 https://zhihongos.cn/iot/api。cloud test 会向 {api_base}/authorize/login 发起登录探测。

8.4.3 获取 MQTT `--host` 与 `--port`

MQTT 地址在 网络组件 中配置，不在单个设备页面。

步骤 3：左侧菜单 运维管理 → 网络组件。

网络组件列表 — 卡片「详情」行中的公网地址即 --host，端口即 --port

在列表卡片中可以看到：

界面显示	对应 CLI	本环境值
详情 `公网:mqtt://zhihongos.cn:1883` 中的域名	`--host`	`zhihongos.cn`
同上 URL 中的端口	`--port`	`1883`

步骤 4：点击 JetLinks MQTT 卡片上的查看（或编辑），进入详情页。

MQTT 网络组件详情 — 公网地址 / 公网端口

详情字段	含义	填到 CLI
公网地址	MQTT Broker 域名	`--host zhihongos.cn`
公网端口	MQTT 端口（未开 TLS 时为 1883）	`--port 1883`
开启 TLS	若为「是」，端口通常为 8883，且需证书配置	本教程环境为「否」

8.4.4 获取网关 `product_id` / `device_id` / `secure_id` / `secure_key`

这四个参数通过 gateway set 写入配置，但必须在云平台预先创建产品与设备实例。获取路径如下。

步骤 5：设备管理 → 产品，找到网关产品（本教程为 edge-gateway）。

产品列表

步骤 6：点击产品名称进入详情，在 配置信息 选项卡查看 ID 字段。

网关产品详情 — ID 即 --product-id

界面字段	对应 CLI	本环境值
配置信息 → ID	`gateway set --product-id`	`edge-gateway`
接入方式	须为「MQTT 网关」类接入	EdgeComputer 接入
设备类型	网关设备	网关设备

步骤 7：设备管理 → 设备，打开网关实例（本教程为 edge-gw-001）。

设备实例列表

步骤 8：进入设备详情，在标题区与 实例信息 选项卡读取 ID；在下方 配置 → MQTT 认证配置 读取凭证。

设备实例详情 — 设备ID、secureId、secureKey

界面位置	对应 CLI	本环境值
标题设备ID / 设备信息表「设备ID」	`gateway set --device-id`	`edge-gw-001`
配置 → MQTT 认证配置 → secureId	`gateway set --secure-id`	`edge-secure-id`
配置 → MQTT 认证配置 → secureKey	`gateway set --secure-key`	`edge-secure-key-2026`（界面默认 `******`，点「编辑」查看）

易错点：device_id 必须与云平台设备实例 ID 完全一致（含大小写），否则 MQTT 认证失败（rc=4）。secure_id / secure_key 须与云平台该设备实例上的值一致。

8.4.5 完整配置示例

根据上文从云平台抄录的参数，在板端执行：

bash

# 1. 云平台连接（jetlinks 段）
edgecomputer cloud set \
  --host zhihongos.cn \
  --port 1883 \
  --api-base https://zhihongos.cn/iot/api \
  --api-user admin \
  --api-password 'zhihongos'

# 2. 网关身份（gateway 段，凭证来自 8.4.4）
edgecomputer gateway set \
  --product-id edge-gateway \
  --device-id edge-gw-001 \
  --secure-id edge-secure-id \
  --secure-key edge-secure-key-2026

# 3. 推送给运行中的服务
edgecomputer config apply

# 4. 验证 API 登录 + MQTT 端口可达
edgecomputer cloud test --format json

cloud test 成功时 ready: true；MQTT 真正上线还需 config apply 后服务用 gateway 凭证完成 MQTT 认证，可用 service status 查看 connected。

8.4.6 子命令参考

`cloud get`

读取当前 JetLinks/MQTT 连接配置（密码脱敏）。

bash

edgecomputer cloud get --format json

参数	说明
无额外参数	输出 `jetlinks` + `mqtt` 两段配置

示例输出：

json

{
  "jetlinks": {
    "api_base": "https://zhihongos.cn/iot/api",
    "api_password": "***",
    "api_token": "",
    "api_user": "admin",
    "host": "zhihongos.cn",
    "port": 1883
  },
  "mqtt": {
    "keep_alive": 60,
    "publish_qos": 1,
    "reconnect_interval_sec": 10,
    "subscribe_qos": 1
  }
}

`cloud set`

更新云平台连接配置，写入 runtime_config.json。

bash

edgecomputer cloud set \
  --host <MQTT主机> \
  --port <MQTT端口> \
  --api-base <REST API根路径> \
  --api-user <用户名> \
  --api-password <密码> \
  [--api-token <令牌>] \
  [--keep-alive <秒>] \
  [--dry-run] \
  [--yes]

参数	必填	说明	获取方式
`--host`	是	MQTT Broker 主机名	8.4.3 网络组件「公网地址」
`--port`	是	MQTT 端口	8.4.3 网络组件「公网端口」
`--api-base`	是	REST API 根路径	8.4.2 控制台 URL + `/api`
`--api-user`	是	API 登录用户名	8.4.2 登录页账号
`--api-password`	是	API 登录密码	8.4.2 登录页密码
`--api-token`	否	预置 Token（通常留空）	—
`--keep-alive`	否	MQTT keep-alive 秒数	默认 `60`
`--dry-run`	否	仅预览，不写入	—
`--yes`	否	跳过确认	—

设置后需执行 config apply 才会推送给运行中的服务。

`cloud ensure`

幂等版 cloud set：配合 --if-not-exists 仅在配置不存在时写入。

bash

edgecomputer cloud ensure \
  --host zhihongos.cn --port 1883 \
  --api-base https://zhihongos.cn/iot/api \
  --if-not-exists

`cloud test`

快速探测：API 登录 + MQTT 端口 TCP 连通（不测试 MQTT 设备认证）。

bash

edgecomputer cloud test --format json

返回字段	含义
`api.ok`	REST API 登录是否成功（验证 `--api-base` + 账号密码）
`api.detail`	详情，成功为 `login_ok`
`mqtt.reachable`	MQTT 端口是否可达（验证 `--host` + `--port`）
`mqtt.detail`	详情，成功为 `tcp_ok`
`ready`	综合就绪：`api.ok && mqtt.reachable`

`cloud status`

通过运行中服务查询云连接状态（需 edgecomputer_service 在线）。

8.5 gateway — 网关身份

配置网关在 JetLinks 上的产品 ID、设备实例 ID、MQTT 接入凭证（secure_id / secure_key）。写入 runtime_config.json 的 gateway 段。

`gateway get`

bash

edgecomputer gateway get --format json

示例输出：

json

{
  "device_id": "edge-gw-001",
  "product_id": "edge-gateway",
  "secure_id": "edge-secure-id",
  "secure_key": "***"
}

`gateway set`

设置网关三元组，必须与 JetLinks 设备实例完全一致。

bash

edgecomputer gateway set \
  --product-id <产品ID> \
  --device-id <设备ID> \
  --secure-id <secureId> \
  --secure-key <secureKey> \
  [--dry-run]

参数	必填	说明	本教程示例值
`--product-id`	是	JetLinks 网关产品 ID	`edge-gateway`
`--device-id`	是	JetLinks 网关设备实例 ID（也是 MQTT clientId）	`edge-gw-001`
`--secure-id`	是	设备凭证 secureId	`edge-secure-id`
`--secure-key`	是	设备凭证 secureKey	`edge-secure-key-2026`
`--dry-run`	否	预览	—

重要：device_id 必须与 JetLinks 设备实例 ID 一致，否则 MQTT 认证 rc=4。

示例输出：

json

{
  "changed": false,
  "state": {
    "device_id": "edge-gw-001",
    "product_id": "edge-gateway",
    "secure_id": "edge-secure-id",
    "secure_key": "***"
  }
}

`gateway ensure`

幂等版 gateway set。

8.6 child — 默认子设备

配置 linux_device 等插件使用的默认子设备身份（product_id / device_id / device_name）。写入 runtime_config.json 的 child_defaults 段。

`child get`

bash

edgecomputer child get --format json

示例输出：

json

{
  "device_id": "edge-linux-001",
  "device_name": "OHOS边缘节点",
  "product_id": "edge-linux-child"
}

`child set`

设置默认子设备（linux_device 插件采集目标）。

bash

edgecomputer child set \
  --product-id <产品ID> \
  --device-id <设备ID> \
  [--device-name <显示名称>]

参数	必填	说明	本教程示例值
`--product-id`	是	子设备产品 ID	`edge-linux-child`
`--device-id`	是	子设备实例 ID	`edge-linux-001`
`--device-name`	否	设备显示名称	`OHOS边缘节点`

示例输出：

json

{
  "changed": true,
  "child_defaults": {
    "device_id": "edge-linux-001",
    "device_name": "OHOS边缘节点",
    "product_id": "edge-linux-child"
  }
}

8.7 config — 配置管理

与全局标志 --config 不同，本节 config 子命令用于查看和操作板端运行时配置文件（见 6.2 节）。这是板端用户管理配置的主要入口。

`config show`

显示当前合并后的有效配置（密码等敏感字段脱敏为 ***）。

bash

edgecomputer config show --format json

输出段	含义
`jetlinks`	云平台 MQTT + REST 地址与账号
`gateway`	网关 product_id / device_id / secure 凭证
`child_defaults`	默认子设备身份
`plugins`	各插件 enabled 状态与 config 参数
`mqtt`	keep_alive、QoS、重连间隔
`offline_queue`	离线队列容量与刷盘间隔
`storage`	数据目录路径

用途：确认 cloud set / gateway set 是否已正确写入；排障时与服务内 service status 的 config 字段对照。

`config path`

打印运行时配置文件的绝对路径（即 CLI 写入目标，不是 default_config.json）。

bash

edgecomputer config path

典型输出：

/data/service/el1/public/edgecomputer/runtime_config.json

也可用 JSON 格式：

bash

edgecomputer config path --format json
# {"default_config_path":"/system/etc/edgecomputer/default_config.json",
#  "runtime_config_path":"/data/service/el1/public/edgecomputer/runtime_config.json"}

`config apply`

关键步骤：将 runtime_config.json 中的变更推送给 edgecomputer_service，并触发服务重载，使 MQTT 使用新凭证重新连接。

bash

edgecomputer config apply [--dry-run]

参数	说明
`--dry-run`	预览将应用的网关/云配置，不重启服务；成功退出码 10

时机	是否必须执行
修改 `cloud set` / `gateway set` / `child set` 之后	必须，否则服务仍用旧配置
仅 `plugin load` 等运行时操作	通常不需要
首次烧录镜像、配置已写在 runtime 中	若服务已用该配置启动，可省略

示例输出：

json

{
  "applied": true,
  "gateway": {
    "device_id": "edge-gw-001",
    "product_id": "edge-gateway",
    "secure_id": "edge-secure-id",
    "secure_key": "***"
  },
  "restarted": true
}

restarted: true 表示服务已重载；随后用 service status 检查 connected 是否为 true。

8.8 service — 服务控制

查询或控制 edgecomputer_service的运行状态与 MQTT 长连接。多数信息来自 IPC，不直接读 --config 文件。

`service status`

查询 edgecomputer_service 运行状态、MQTT 连接、设备数量。

bash

edgecomputer --format json service status

返回字段	含义
`connected`	MQTT 是否已连接
`ipc_ok`	IPC Socket 是否可用
`device_count`	当前管理的设备数
`fallback_used`	是否使用了配置 fallback
`config`	当前有效配置快照
`dump`	服务内部状态文本

`service connect`

主动触发 MQTT 连接（REST 控制）。

bash

edgecomputer service connect

示例输出：

json

{
  "connected": true,
  "device_count": 2
}

`service disconnect`

断开 MQTT 连接（调试用）。

bash

edgecomputer service disconnect

8.9 device — 子设备管理

`device list`

列出所有子设备 ID。

bash

edgecomputer device list --format json [--limit <n>] [--full]

参数	说明
`--limit`	返回条数上限（默认 20）
`--full`	返回完整设备对象而非仅 ID

示例输出：

json

{
  "items": [
    "edge-gw-001",
    "edge-linux-001"
  ],
  "limit": 20,
  "total": 2
}

加载 modbus 插件后，列表将包含 child-modbus-001，edge health 显示 device_count: 3。

`device get`

查询单个子设备详情（含属性快照）。

bash

edgecomputer device get --device-id <ID> --format json

示例输出：

json

{
  "device_id": "edge-linux-001",
  "device_name": "OHOS边缘节点",
  "device_type": "childrenDevice",
  "metadata": null,
  "parent_id": "edge-gw-001",
  "product_id": "edge-linux-child",
  "properties": {
    "child_id": "edge-linux-001",
    "disk_usage": 2.491177166883174,
    "load_avg": 0.11,
    "temp": 20.06
  },
  "self_manage_state": false,
  "state": "online",
  "updated_at_ms": 1788329682009
}

`device create`

创建新子设备。

bash

edgecomputer device create \
  --device-id <ID> \
  --product-id <产品ID> \
  [--device-name <名称>] \
  [--dry-run] [--yes]

`device update` / `device delete`

更新或删除子设备。删除需 --confirm 或 --yes。

8.10 device property — 属性上报

`device property get`

bash

edgecomputer device property get <device-id> [--key <属性名>]

`device property set`

手动上报（或覆盖）设备属性值。

bash

edgecomputer device property set <device-id> \
  --key <属性名> \
  --value <属性值> \
  [--dry-run]

参数	必填	说明
`<device-id>`	是	目标子设备 ID（位置参数）
`--key`	是	物模型属性 ID
`--value`	是	属性值（字符串，服务自动转型）
`--dry-run`	否	预览

使用场景：

测试 JetLinks 规则引擎告警
插件未覆盖的属性手动补报
集成测试验证 Topic 通路

示例输出：

json

{
  "device_id": "edge-linux-001",
  "properties": {
    "cpu_usage": "45.2"
  },
  "success": true
}

8.11 device event — 事件上报

上报设备事件（告警、状态变更等）。

bash

edgecomputer device event <device-id> <event-id> --data '<JSON>'

参数	必填	说明
`<device-id>`	是	目标子设备 ID
`<event-id>`	是	物模型事件 ID
`--data`	否	事件数据 JSON 字符串

示例：

bash

edgecomputer device event edge-linux-001 alarm --data '{"level":"high"}'

json

{
  "device_id": "edge-linux-001",
  "event_id": "alarm",
  "success": true
}

8.12 device online / offline — 上下线

`device online`

通知云平台子设备上线。

bash

edgecomputer device online --device-id <ID>

示例输出：

json

{
  "device_id": "edge-linux-001",
  "state": "online",
  "success": true
}

`device offline`

通知云平台子设备离线。

bash

edgecomputer device offline --device-id <ID>

示例输出：

json

{
  "device_id": "edge-linux-001",
  "state": "offline",
  "success": true
}

重新上线：

bash

edgecomputer device online --device-id edge-linux-001

json

{
  "device_id": "edge-linux-001",
  "state": "online",
  "success": true
}

8.13 topo — 拓扑同步

`topo sync`

从 JetLinks 云平台拉取最新设备拓扑到本地。

bash

edgecomputer topo sync --format json [--dry-run]

示例输出：

json

{
  "synced": true
}

8.14 plugin — 插件管理

`plugin list`

列出当前已加载插件。

bash

edgecomputer plugin list --format json

示例输出：

json

{
  "items": [
    "linux_device",
    "edgeclaw_session"
  ],
  "total": 2
}

`plugin load`

加载指定插件（从 plugins_dir 动态 dlopen）。

bash

edgecomputer plugin load <插件名> --format json [--dry-run]

示例：

json

{
  "loaded": true,
  "plugin": "linux_device"
}

示例：

json

{
  "loaded": true,
  "plugin": "modbus"
}

`plugin status`

查询插件能力与状态。

bash

edgecomputer plugin status <插件名> --format json

示例：

json

{
  "abilities": {
    "properties": [
      {"id": "hostname"},
      {"id": "cpu_usage"},
      {"id": "temp"},
      {"id": "disk_usage"}
    ]
  },
  "plugin": "linux_device"
}

`plugin unload`

卸载插件（OHOS IPC 模式下不支持，会返回错误提示）。

8.15 package — 边缘包

`package list`

从 JetLinks API 查询可部署的边缘包列表。

bash

edgecomputer package list --format json

若云平台未配置边缘包或 API 异常，可能返回 api_error。

`package installed`

查询网关本地已安装的边缘包。

bash

edgecomputer package installed --format json

示例输出：

json

{
  "message": "success",
  "result": [],
  "status": 200,
  "timestamp": 1788329693756
}

8.16 edge — 聚合健康

`edge health`

一次性检查 edgecomputer + cloud + edgemcp + edgeclaw 四项健康。

bash

edgecomputer edge health --format json

字段	含义
`ready`	综合就绪（全部子项 OK）
`cloud.api_ok`	JetLinks API 登录
`cloud.mqtt_reachable`	MQTT 端口
`edgecomputer.connected`	MQTT 长连接
`edgecomputer.ipc_ok`	IPC 可用
`edgecomputer.device_count`	设备总数
`edgemcp.bridge_connected`	MCP 桥接
`edgemcp.tool_count`	MCP Tool 数量
`edgeclaw.health.status`	EdgeClaw 状态

8.17 schema — 命令自省

bash

edgecomputer schema              # 完整命令树
edgecomputer schema cloud.set    # 单命令 schema

输出 cli_version: 1.1.0 及全部命令 path、flags 列表。

九、插件开发

源码目录：extension/edge/edge_computer/plugins/
板端路径：/system/lib64/edgecomputer/plugins/*.z.so

插件是 EdgeComputer 的核心扩展机制：把现场协议（系统指标、Modbus、小米 miio、EdgeClaw 会话等）适配为 JetLinks 子设备 + 物模型，由网关统一上报。

9.1 插件在整体架构中的位置

概念	说明
插件	动态库 `.so`，实现 `IDevicePlugin` / `DevicePluginBase`
PluginManager	按名称 `dlopen`、调度生命周期、路由下行指令
子设备	插件在 `OnStart` 时注册，一个插件可管理多个子设备
配置	`runtime_config.json` 的 `plugins[]` 段控制启用与参数

9.2 插件分类总览

plugins/ 目录下所有插件类型如下（默认镜像编入 vs 可选编译）：

类别	插件名（CLI `plugin load`）	默认镜像	功能摘要
系统监控	`linux_device`	✅ 编入	采集网关/子节点 CPU、内存、磁盘、温度
工业协议	`modbus`	✅ 编入	Modbus TCP 主站，点位表映射多子设备
AI 会话	`edgeclaw_session`	✅ 编入	将 EdgeClaw 多会话能力暴露为虚拟子设备
小米 IoT	`miio_*`（62 种）	⚙️ 可选编译	风扇、灯、空调、扫地机等 miio 设备

bash

# 板端查看已安装 .so
ls /system/lib64/edgecomputer/plugins/

# 查看当前已加载插件
edgecomputer plugin list --format json

示例 plugin list 常见输出：

json

{
  "items": ["linux_device", "edgeclaw_session"],
  "total": 2
}

modbus 在配置中默认 enabled: false，需 plugin load modbus 后才会出现在列表中。

9.3 内置插件详解

9.3.1 linux_device — 系统指标采集

项目	说明
源码	`plugins/linux_device/`
典型子设备	`edge-linux-001`（产品 `edge-linux-child`）
默认上报间隔	15 秒（`report_interval_sec`）
主要属性	`hostname`、`cpu_usage`、`temp`、`disk_usage`、`load_avg`

配置示例（runtime_config.json 中 plugins 段）：

json

{
  "name": "linux_device",
  "enabled": true,
  "config": {
    "child_device_id": "edge-linux-001",
    "child_product_id": "edge-linux-child",
    "report_interval_sec": 15
  }
}

使用：

bash

edgecomputer plugin load linux_device --format json
edgecomputer plugin status linux_device --format json
edgecomputer device get --device-id edge-linux-001 --format json

plugin status 返回插件声明的物模型属性列表（abilities.properties）。

9.3.2 modbus — Modbus TCP 主站

项目	说明
源码	`plugins/modbus/`，点位表 `plugins/modbus/maps/*.json`
模式	单 TCP 连接 + 多 `slave_id` → 多子设备
培训模式	`simulate: true` 无需真实 PLC
典型子设备	`child-modbus-001`（产品 `modbus-sensor`）

详见 9.6 Modbus 插件专题。

9.3.3 edgeclaw_session — EdgeClaw 会话虚拟设备

项目	说明
源码	`plugins/edgeclaw_session/`
作用	云平台经物模型调用板端 EdgeClaw（创建会话、发消息、查历史）
依赖	`edgeclaw_service`、`libedgeclaw_client`
适用设备	网关设备、直连设备（不作为普通 childrenDevice 挂载）

物模型能力包括：create_session、send_message、list_sessions、get_history 等（与 IEdgeClawService API 对齐）。架构说明见源码 plugins/docs/EDGECLAW_PLUGIN_ARCHITECTURE.md。

默认 enabled: true，一般无需手动 plugin load；与 EdgeClaw / EdgeMCP 联调见 edgeclaw.md。

9.4 miio 设备插件生态（可选编译）

除上述 3 个核心插件外，plugins/ 下还有 62 个 miio_* 插件，基于 miio-cpp 集成自动生成，覆盖小米生态链设备。

功能大类（15 类）：

大类	代表插件	设备示例
空调/新风	`miio_air_conditioner_miot`、`miio_air_fresh`	米家空调、新风机
加湿/除湿/净化	`miio_air_humidifier`、`miio_air_purifier_miot`	加湿器、空气净化器
风扇	`miio_fan`、`miio_fan_miot`	米家风扇
照明	`miio_yeelight`、`miio_philips_bulb`	Yeelight、飞利浦灯
插座/插排	`miio_chuangmi_plug`、`miio_power_strip`	智能插座
扫地/吸尘	`miio_roborock_vacuum`、`miio_dreame_vacuum`	石头、追觅
摄像头	`miio_chuangmi_camera`、`miio_aqara_camera`	创米摄像头
窗帘	`miio_curtain_miot`	智能窗帘
净水器/饮水机	`miio_water_purifier`、`miio_pet_water_dispenser`	净水器、宠物饮水机
厨房电器	`miio_cooker`、`miio_multi_cooker`	电饭煲
其他	`miio_gateway`、`miio_wifi_speaker` 等	网关、音箱

完整 62 插件名称与 model 对照表：extension/edge/edge_computer/plugins/docs/MIIO_DEVICE_TYPES.md

编译单个 miio 插件（开发机）：

bash

cd /data/ohos
./build.sh --product-name <product_name> --build-target miio_fan
# 产物安装到板端 plugins 目录后：
edgecomputer plugin load miio_fan --format json

标准培训镜像通常未编入全部 miio 插件以控制镜像体积；需要时按设备型号选择性编译打包。

9.5 插件的加载、配置与 CLI

配置与加载的关系

方式	命令/配置	说明
出厂默认	`default_config.json`	只读模板
持久配置	`cloud/gateway/child set` + `config apply`	写入 `plugins[]` 的 `enabled`、`config`
运行时加载	`edgecomputer plugin load <name>`	立即 dlopen，无需重启

CLI 命令速查

命令	作用
`plugin list`	列出已加载插件
`plugin load <name>`	加载插件（`--dry-run` 预览）
`plugin status <name>`	查看插件能力与物模型属性 ID
`plugin unload <name>`	OHOS 上不支持运行时卸载

参数说明见 8.14 plugin。

典型工作流

bash

# 1. 确认插件 .so 存在
ls /system/lib64/edgecomputer/plugins/

# 2. 加载
edgecomputer plugin load linux_device --format json

# 3. 查看能力（与 JetLinks 物模型对齐）
edgecomputer plugin status linux_device --format json

# 4. 确认子设备与属性
edgecomputer device list --format json
edgecomputer device get --device-id edge-linux-001 --format json

9.6 Modbus 插件专题

架构

Modbus 插件采用单网关 + 多子设备模式：一个 Modbus TCP 连接可挂载多个从站（slave_id），每个从站映射为一个 JetLinks 子设备。

点位表配置

配置文件模板（源码：plugins/modbus/maps/temp_sensor.json）：

json

{
  "connection": {
    "host": "127.0.0.1",
    "port": 502
  },
  "poll_interval_sec": 5,
  "simulate": true,
  "devices": [
    {
      "device_id": "child-modbus-001",
      "product_id": "modbus-sensor",
      "device_name": "Modbus温度传感器",
      "slave_id": 1,
      "points": [
        {
          "property": "temp",
          "address": 40001,
          "type": "float32",
          "scale": 0.1,
          "writable": false
        },
        {
          "property": "humidity",
          "address": 40003,
          "type": "uint16",
          "scale": 0.1,
          "writable": false
        },
        {
          "property": "switch",
          "address": 40010,
          "type": "bool",
          "writable": true
        }
      ]
    }
  ]
}

字段	说明
`simulate`	`true` 时无真实 PLC 也生成模拟数据（培训推荐）
`slave_id`	Modbus 从站地址
`address`	保持寄存器地址（40001 = 0x0000）
`type`	`float32` / `uint16` / `bool`
`writable`	是否支持云平台下发写属性

JetLinks 准备与板端部署

创建产品 modbus-sensor（属性：temp、humidity、switch）
创建子设备 child-modbus-001，父设备 edge-gw-001
板端执行：

bash

edgecomputer plugin load modbus --format json
edgecomputer device list --format json
edgecomputer device get --device-id child-modbus-001 --format json

与 EdgeClaw / EdgeMCP 联调

bash

edgemcp tools call get_device_properties \
  --device-id child-modbus-001 \
  --property-ids temp,humidity \
  --format json

edgeclaw chat -s modbus -m \
  '请读取 child-modbus-001 的温度和湿度属性'

9.7 自定义插件开发

开发目录结构

extension/edge/edge_computer/plugins/
├── sdk/
│   ├── device_plugin_base.hpp    # 推荐基类
│   └── edgecomputer_plugin.h     # 插件 API
├── hello/                        # 你的插件目录
│   ├── hello_plugin.hpp
│   ├── hello_plugin.cpp
│   └── plugin_entry.cpp
└── BUILD.gn                      # 注册 ohos_shared_library

最小插件示例

1. 头文件 hello_plugin.hpp

cpp

#pragma once
#include "device_plugin_base.hpp"

namespace ec_plugins {
class HelloPlugin : public edgecomputer::DevicePluginBase {
public:
    const char* Name() const override { return "hello"; }
protected:
    bool OnInit() override {
        OwnDevice("child-hello-001");
        return true;
    }
    bool OnStart() override {
        edgecomputer::DeviceInstance d;
        d.device_id = "child-hello-001";
        d.product_id = "hello-product";
        d.device_type = "childrenDevice";
        d.parent_id = Core().Config().gateway.device_id;
        EnsureChildDevice(d);
        return true;
    }
    edgecomputer::json OnReadProperty(const std::string&,
                                      const std::vector<std::string>&) override {
        return {{"msg", "hello"}};
    }
};
}

2. 导出入口 plugin_entry.cpp

cpp

#include "hello_plugin.hpp"
#include "edgecomputer/plugin/plugin_api.hpp"
EC_PLUGIN_EXPORT(ec_plugins::HelloPlugin)

3. 注册到 plugins/BUILD.gn

ohos_shared_library("hello") {
  sources = [
    "${plugins_path}/hello/hello_plugin.cpp",
    "${plugins_path}/hello/plugin_entry.cpp",
    "${frameworks_path}/plugin_runtime/include/device_plugin_base.cpp",
  ]
  relative_install_dir = "edgecomputer/plugins"
  part_name = "edge_computer"
  subsystem_name = "edgecomputing"
  # ... 与 linux_device 相同的 deps / include_dirs
}

group("edgecomputer_plugins") {
  deps = [ ":linux_device", ":modbus", ":edgeclaw_session", ":hello" ]
}

DevicePluginBase 常用 API

方法	说明
`OwnDevice(id)`	声明插件管理的设备 ID
`EnsureChildDevice(dev)`	向 JetLinks 注册子设备
`Report(id, props)`	上报属性 + 心跳
`StartPollLoop(sec)`	后台轮询，实现 `OnPoll()`
`OnReadProperty`	云平台读属性回调
`OnWriteProperty`	云平台写属性回调
`OnInvoke`	云平台调功能回调

编译与验证

bash

# 宿主机编译
cd /data/ohos
./build.sh --product-name <product_name> --build-target edgecomputer

# 板端加载（或刷入新镜像）
edgecomputer plugin load hello --format json
edgecomputer plugin status hello --format json

开发时参考现有实现：linux_device/（轮询采集）、modbus/（外部协议 + 点位表）。

9.8 边缘包部署（云平台下发插件）

生产环境可通过 JetLinks 边缘包部署将编译好的 .so 下发到网关，无需 hdc 手动推送。

步骤：

编译：./build.sh --build-target edgecomputer
JetLinks → 设备插件管理 → 上传 libmodbus.z.so 等
设备实例 → edge-gw-001 → 边缘包部署 → 安装
板端验证：

bash

edgecomputer plugin list --format json
edgecomputer package installed --format json

若下载 URL 为内网 127.0.0.1，需在 JetLinks 配置文件服务器公网地址（见第十章排障）。

十、常见问题

10.1 connected=false

检查项	命令/操作
凭证一致	`gateway get` 对比 JetLinks `secureId/secureKey`
clientId 匹配	`device_id` 必须与实例 ID 一致
系统时间	`date`；偏差 >5min 会 `rc=4`
云探测	`cloud test --format json`
日志	`tail -30 .../edgecomputer.log`

若系统时间偏差超过约 5 分钟会导致 MQTT rc=4，可校时后重启服务：

bash

sntp -s 203.107.6.88 && hwclock -w
service_control restart edgecomputer_service

10.2 ipc_ok=false

先确认进程存在：ps -ef | grep edgecomputer_service。若进程在但 ipc_ok=false，可尝试：

bash

service_control restart edgecomputer_service
edgecomputer --format json service status

仍失败时查看 edgecomputer.log 与 hilog 中的具体错误信息。

10.3 插件 load 失败

bash

tail -50 /data/service/el1/public/edgecomputer/edgecomputer.log
ls /system/lib64/edgecomputer/plugins/

10.4 边缘包 DOWNLOAD_FAILED

下载 URL 为 127.0.0.1 时失败。需在 JetLinks 配置文件服务器公网地址。

10.5 子设备不上报

plugin list 确认插件已加载
device list 确认子设备已注册
device get 查看 properties 是否更新

10.6 edgemcp 无设备

确认依赖服务均在运行：edgecomputer --format json service status、edgemcp health --format json。异常时再按 edgecomputer_service → edgemcp → edgeclaw_service 顺序重启。

10.7 MQTT 组件重启（宿主机）

bash

curl -X POST "https://zhihongos.cn/iot/network/config/<MQTT_ID>/_shutdown"
curl -X POST "https://zhihongos.cn/iot/network/config/<MQTT_ID>/_start"

10.8 日志关键字

关键字	含义
`rc=4`	MQTT 认证失败
`ipc_ok=false`	IPC 或 Socket 异常，可尝试 `service_control restart edgecomputer_service`
`fallback_used=true`	CLI 使用配置 fallback
`edge package`	边缘包部署日志

十一、附录

附录 A：命令速查表

场景	命令
版本	`edgecomputer --version`
服务状态	`edgecomputer --format json service status`
配置云连接	`edgecomputer cloud set --host zhihongos.cn --port 1883 ...`
设置网关	`edgecomputer gateway set --product-id edge-gateway ...`
设置子设备	`edgecomputer child set --product-id edge-linux-child ...`
应用配置	`edgecomputer config apply`
云探测	`edgecomputer cloud test --format json`
加载插件	`edgecomputer plugin load linux_device`
设备列表	`edgecomputer device list --format json`
属性上报	`edgecomputer device property set <id> --key <k> --value <v>`
事件上报	`edgecomputer device event <id> <eid> --data '<json>'`
上下线	`edgecomputer device online/offline --device-id <id>`
拓扑同步	`edgecomputer topo sync --format json`
聚合健康	`edgecomputer edge health --format json`
命令自省	`edgecomputer schema`

附录 B：练手 checklist

步骤	做什么	怎么确认
1	板子能 `hdc shell`	能执行 `edgecomputer --version`
2	连云五步做完	`cloud test` → `ready: true`
3	加载 linux_device	`device list` 含 `edge-linux-001`
4	网页看属性	JetLinks 上 `cpu_usage` 有数
5	加载 modbus（可选）	`device list` 含 `child-modbus-001`

附录 C：五服务教程体系导航

顺序	服务	本地教程	角色	依赖
1	EdgeComputer	edgecomputer.md（本文）	JetLinks 网关、子设备、插件	WiFi / JetLinks 账号
2	EdgeMCP	edgemcp.md	物模型 → MCP Tool	EdgeComputer
3	EdgeClaw	edgeclaw.md	AI 编排、自然语言控制 IoT	EdgeComputer + EdgeMCP
4	Edge Engine	edgeengine.md	端侧 CV/语音推理	NPU（RK3588）
5	EdgePipe	edgepipe.md	视觉流水线 YAML	Edge Engine

推荐路径：IoT 开发者 1→2→3；视觉 AI 开发者 4→5；全栈 1→2→3 与 4→5 可并行。

文档	路径
使用指南总览	/training/

附录 D：错误 JSON 格式

json

{
  "error": "service_unreachable",
  "message": "edgecomputer REST API unreachable",
  "suggestion": "start edgecomputer service first",
  "retryable": true
}

附录 E：旧命令迁移

旧命令	新命令
`status`	`edgecomputer service status`
`devices`	`edgecomputer device list`
`sync-topo`	`edgecomputer topo sync`
`connect`	`edgecomputer service connect`
`disconnect`	`edgecomputer service disconnect`
`property <id> <k> <v>`	`edgecomputer device property set <id> --key <k> --value <v>`
`event <id> <eid> [json]`	`edgecomputer device event <id> <eid> --data '<json>'`

附录 F：配置字段参考

配置段	关键字段	默认值
`jetlinks`	host, port, api_base	zhihongos.cn:1883
`gateway`	product_id, device_id, secure_*	见教程
`mqtt`	keep_alive, publish_qos	60, 1
`heartbeat`	interval_sec, timeout_sec	30, 90
`offline_queue`	max_size, flush_interval_sec	8192, 10
`compress`	enabled, threshold_bytes	true, 5120
`plugins`	name, enabled, config	linux_device/modbus/edgeclaw_session

EdgeComputer 新手教程 ​

目录 ​

一、开始之前 ​

1.1 这份文档帮你做什么 ​

1.2 你需要准备 ​

1.3 CLI 名称 ​

二、连接开发板 ​

2.1 宿主机连接开发板 ​

2.2 确认 edgecomputer_service 已运行 ​

2.3 第一步验证 ​

三、快速连云 ​

3.1 五步连云（复制粘贴版） ​

整体流程一览 ​

步骤 1：配置云平台地址与 API 账号 ​

步骤 2：配置网关身份（MQTT 登录凭证） ​

步骤 3：配置默认子设备 ​

步骤 4：应用配置 ​

步骤 5：验证连通性 ​

3.2 期望结果 ​

四、加载插件与查看数据 ​

4.1 加载系统监控插件 ​

4.2 在板端确认服务状态 ​

4.3 在 JetLinks 网页查看 ​

4.4 手动上报一次（可选） ​

4.5 加载 Modbus 插件（可选） ​

4.6 常用查看命令 ​

五、端云协同原理 ​

5.1 四种设备形态总览 ​

5.2 网关设备（Gateway） ​

定义 ​

本教程示例 ​

网关做什么、不做什么 ​

5.3 网关子设备（Children Device） ​

定义 ​

本教程两个子设备示例 ​

子设备在板端如何「出现」 ​

5.4 直连设备（Direct Device） ​

定义 ​

与网关子设备的对比 ​

何时仍用「网关 + 子设备」而不是直连？ ​

5.5 物模型（TSL）—— 设备的「说明书」 ​

定义 ​

示例 1：edge-linux-child 产品物模型（简化） ​

示例 2：modbus-sensor 产品物模型 + 点位表 ​

属性 vs 功能 vs 事件（决策表） ​

物模型在 EdgeComputer 生态中的传递链 ​

5.6 端到端示例：从物模型到云平台一条属性 ​

5.7 网关模式下的数据流与 Topic 路由 ​

5.8 配置优先级 ​

5.9 MQTT 认证原理 ​

5.10 属性 / 事件 / 上下线与物模型的关系 ​

5.11 离线队列 ​

5.12 IPC 与 fallback ​

六、功能一览 ​

6.1 模块总览 ​

6.2 核心模块说明 ​

6.3 插件框架（概要） ​

6.4 与其他 Extension 服务的关系 ​

七、JetLinks 配置 ​

7.1 登录控制台 ​

7.2 创建网关产品 ​

7.3 创建网关设备实例 ​

7.4 创建子设备产品 ​

7.5 创建子设备实例 ​

7.6 板端配置并验证 ​

7.7 MQTT 连接架构 ​

八、命令手册 ​

8.1 全局标志 ​

8.1.1 标志一览 ​

8.1.2 --format 详解 ​

8.1.3 --dry-run 详解 ​

8.1.4 --config <path> 详解（重要） ​

8.1.5 退出码 ​

8.2 配置文件体系 ​

8.2.1 三类配置文件 ​

8.2.2 合并优先级（低 → 高，后者覆盖前者） ​

8.2.3 配置相关 CLI 与子命令的关系 ​

8.2.4 runtime_config.json 结构示例（节选） ​

8.3 命令树 ​

8.4 cloud — 云平台连接 ​

EdgeComputer 新手教程

目录

一、开始之前

1.1 这份文档帮你做什么

1.2 你需要准备

1.3 CLI 名称

二、连接开发板

2.1 宿主机连接开发板

2.2 确认 edgecomputer_service 已运行

2.3 第一步验证

三、快速连云

3.1 五步连云（复制粘贴版）

整体流程一览

步骤 1：配置云平台地址与 API 账号

步骤 2：配置网关身份（MQTT 登录凭证）

步骤 3：配置默认子设备

步骤 4：应用配置

步骤 5：验证连通性

3.2 期望结果

四、加载插件与查看数据

4.1 加载系统监控插件

4.2 在板端确认服务状态

4.3 在 JetLinks 网页查看

4.4 手动上报一次（可选）

4.5 加载 Modbus 插件（可选）

4.6 常用查看命令

五、端云协同原理

5.1 四种设备形态总览

5.2 网关设备（Gateway）

定义

本教程示例

网关做什么、不做什么

5.3 网关子设备（Children Device）

定义

本教程两个子设备示例

子设备在板端如何「出现」

5.4 直连设备（Direct Device）

定义

与网关子设备的对比

何时仍用「网关 + 子设备」而不是直连？

5.5 物模型（TSL）—— 设备的「说明书」

定义

示例 1：`edge-linux-child` 产品物模型（简化）

示例 2：`modbus-sensor` 产品物模型 + 点位表

属性 vs 功能 vs 事件（决策表）

物模型在 EdgeComputer 生态中的传递链

5.6 端到端示例：从物模型到云平台一条属性

5.7 网关模式下的数据流与 Topic 路由

5.8 配置优先级

5.9 MQTT 认证原理

5.10 属性 / 事件 / 上下线与物模型的关系

5.11 离线队列

5.12 IPC 与 fallback

六、功能一览

6.1 模块总览

6.2 核心模块说明

6.3 插件框架（概要）

6.4 与其他 Extension 服务的关系

七、JetLinks 配置

7.1 登录控制台

7.2 创建网关产品

7.3 创建网关设备实例

7.4 创建子设备产品

7.5 创建子设备实例

7.6 板端配置并验证

7.7 MQTT 连接架构

八、命令手册

8.1 全局标志

8.1.1 标志一览

8.1.2 `--format` 详解

8.1.3 `--dry-run` 详解

8.1.4 `--config <path>` 详解（重要）

8.1.5 退出码

8.2 配置文件体系

8.2.1 三类配置文件

8.2.2 合并优先级（低 → 高，后者覆盖前者）

8.2.3 配置相关 CLI 与子命令的关系

8.2.4 `runtime_config.json` 结构示例（节选）

8.3 命令树

8.4 cloud — 云平台连接