Topic 设计说明书

一、 通信基础

• Topic 结构: {ProductKey}/{GatewayID}/{DeviceID}/{Module}/{Direction}
  • Module: prop (属性), event (事件), srv (服务), sys (系统)
  • Direction: u (上行/设备->云), d (下行/云->设备)
• 消息基础外壳:
  • id: 消息唯一标识（由发起方生成）。
  • m: 方法/功能标识符（Method）。
  • p: 业务参数容器（Params）。

二、OTA 管理

 OTA 业务全流程 Topic 映射

所有 OTA 操作统一使用 sys 通道，通过 m (method) 区分具体动作。

 完整 Payload 示例

1. 设备上报当前版本 (Boot/Update Done)

作用： 设备启动或升级完成后，主动同步当前固件信息。云端据此判断是否需要下发升级任务，并更新设备资产信息。

• Topic:  demo/g01/self/sys/u
• Method ：ota.report
• Payload:

{
 "id": "101",  // id 
  "m": "ota.report",  // 方法
  "p": {
    "v": "v1.1.0",
    "module": "main_mcu",
    
    "res": "success"
  }
}

2. 设备主动拉取升级信息 (Pull Mode)

作用： 用于网络受限或低功耗设备，由设备根据自身业务时机（如低峰期）主动询问云端。

• Topic: demo/g01/self/sys/u
• Method ：ota.get
• Payload:

{
"id": "102",
  "m": "ota.get",
  "p": {
    "module": "main_mcu",
    "v": "v1.0.0",
    "type": 1  // full 完整 diff 差分
  }
}

3. 云端回复/主动推送固件信息 (Push Mode)

作用： 云端响应设备的 ota.get 请求，或管理员在后台发起的强制/静默升级。

差分 OTA 增加了 from_ver 字段，确保设备只下载与当前版本匹配的补丁。

• Topic: demo/g01/self/sys/d
• Method ：ota.push
• Payload:

{
"id": "102",
  "m": "ota.push",
  "p": {
    "v": "v1.1.0",        // 目标版本
    "from_v": "v1.0.0",   // 源版本（仅差分使用）
    "type": 1,            // 包类型：1完整, 2差分
    "url": "https://...", // 下载地址
    "size": 524288,       // 固件大小(Byte)
    "MD5": "e10adc3...", //校验算法：MD5, SHA256 ： 校验值，固定的key是：MD5、SHA256
    "force": 0            // 强制升级标志  0 强制 1 非强制，默认1
    "module": "",         // 升级模块名称
    "taskId": "",         // 任务id，设备需要保存，再后续提交，用于日志归类查询，设备主动上报可为空
    "trace_id": ""        // 追踪id，设备需要保存，再后续提交，用于追踪整个链路，设备主动上报可为空
  }
}

4. 设备上报升级进度 (Status Report)

作用： 实时向云端反馈升级进展。云端通过此数据展示进度条或捕获升级失败的原因。设备在下载、解压、烧录过程中上报进度。

• Topic: demo/g01/self/sys/u
• Method ：ota.progress
• Payload:

{
"id": "103",
  "m": "ota.progress",
  "p": {
    "step": 50,         // 0-100 进度百分比
    "state": "download", // 状态枚举：download, burn（烧录）, success（成功）, fail（失败）
    "desc": "downloading",  // 
    "taskId": "110",   // 任务id，设备需要保存，再后续提交，用于日志归类查询，设备主动上报可为空
    "trace_id": "110-ef473ce7"   // 追踪id，设备需要保存，再后续提交，用于追踪整个链路，设备主动上报时可为空
  }
}

枚举值定义与描述

1. 升级结果 (res)

2. 固件包类型 (type)

3. 升级过程状态 (state)

三、NTP 时间对时

NTP 采用“请求-响应”模式，旨在解决设备端没有 RTC 电池或时钟漂移的问题。

NTP业务全流程Topic 映射

所有 NTP 操作统一使用 sys 通道，通过 m (method) 区分具体动作。

完整 Payload 示例

1. 设备端发起同步请求 (ntp.get)

网关在启动时、或者根据配置的周期（如每 24 小时）主动向云端请求标准时间。

作用描述: 告知云端设备当前已知的本地时间，并请求云端授时。

• Topic: demo/g01/self/sys/u
• Method ：ntp.get

• Payload:

  {
  "id": "ntp.get",
    "m": "ntp.get",
    "p": {
      "t_req": 1709712000000  // 设备当前本地毫秒时间戳（可选）
    }
  }

2. 云端授时响应 (ntp.get_reply)

云端收到请求后，返回高精度的服务器时间及环境配置。

作用描述: 下发标准 Unix 时间戳和时区信息，网关据此修正本地硬件时钟。

• Topic: demo/g01/self/sys/d
• Method ：ntp.get

• Payload:

  {
  	"id": "201", // ID保持一致
    "m": "ntp.get", 
    "p": {
      "t_srv": 1709712000500, // 云端当前毫秒时间戳
      "zone": 8               // 时区，默认8表示东八区
    }
  }

   

枚举与说明

四、系统配置

系统配置业务全流程Topic 映射

所有系统配置统一使用 sys 通道，通过 m (method) 区分具体动作。

完整 Payload 示例

设备上报（conf.report）

网关可以将 conf.report 理解为：“向云端同步我当前的配置快照”。

身份 A（响应推送）：云端 conf.push -> 网关应用 -> conf.report（含执行结果 res）。

身份 B（主动同步）：网关上线/配置变更 -> conf.report（告知云端我现在的真实样子）。

设备开机上报使用这个进行上报。

• Topic (Down):  {PK}/{GWID}/self/sys/u
• Method (Key):  conf.report

{

	"id": "801",   // 设备生成ID
  "m": "conf.report",   // 请求方法
  "if": {  // 设备接口，在自定义接口被勾选的时候会进行下发
    "RS485_1": {  // 接口名为 key
      "pt": 1,  // 通信端口号
      "bd": 9600, //波特率
      "dbs": 8,  // 数据位 
      "pty": 0,  // 停止位
      "sbs": 1,  //校验位 
      "fi": 50, //分帧毫秒
      "to": 1000 // 通信超时时间毫秒
    },
    "ETH_0": {
      "md": 1,  // IP模式，1：DHCP； 0：静态IP
      "ip": "192.168.1.100", // IP地址
      "nm": "255.255.255.0", //子网掩码
      "gw": "192.168.1.1",//默认网关
      "lp": 502, //端口
      "dns1": "8.8.8.8"  // DNS
    }
  },
  "sub": { // 物模型，在勾选支持物模型功能的时候进行下发和获取
    "sub_dev_sn_001": { // 
      "m_id": "temp_sensor_v1", // 模型名称
    "proto": 1, //协议类型ID
    "addr": 1, //从站地址
    "bind_if": "RS485_1", //s
    "c_t": 5000, //通信超时毫秒
    "c_r": 500, //采集上报间隔秒
    "params": [
      {
        "id": "temp_val", //唯一
        "f_c": 3, //功能码
        "add": "0x0001", //寄存器
        "d_t": 2, //数据类型ID
        "bit": [0, 1, 2, 3, 4, 5, 6, 7], //位序,当type为Bit 或 具体协议功能必须解析是 bit 时必填,这里表示单个寄存器，多个位。
        "b_o": 0, //字节顺序
        "f_": "x * 1.0", //自定义公式
        "si": 100, //采集间隔毫秒
        "sbr": 1, //是否上报 1上报 0 不上报
        "co": 1.5, //变化偏移值，变化上报时⽣效，表⽰值变化在这个值的正负范围外才触发变化上报。0表示变化上报，不填代表不变化上报。
        "rh": 10 //整点上报（单位：分钟），指定每⼏分钟上报⼀次
      }
    ]
    },
    "sub_dev_sn_002": {  // DLT数据
      "m_id": "power_meter_k3",
      "proto": "modbus_rtu",
      "addr": 2,
      "bind_if": "RS485_1",
      "pl_int": 10000,
      "c_t_m": 1000,
      "params": [
        {
         "id": "temp_val", //唯一
        "add": "0x0001", //DLT协议为表地址，不⽀持⼴播地
        "d_t": 2, //数据类型ID
        "bit": [0, 1, 2, 3, 4, 5, 6, 7], //位序,当type为Bit 或 具体协议功能必须解析是 bit 时必填,这里表示单个寄存器，多个位。
        "b_o": 0, //字节顺序
        "f_": "x * 1.0", //自定义公式
        "si": 100, //采集间隔毫秒
        "sbr": 1, //是否上报 1上报 0 不上报
        "co": 1.5, //变化偏移值，变化上报时⽣效，表⽰值变化在这个值的正负范围外才触发变化上报。0表示变化上报，不填代表不变化上报。
        "rh": 10 //整点上报（单位：分钟），指定每⼏分钟上报⼀次
        }
      ]
    },
    "sub_dev_sn_003": {  // JSON数据
      "m_id": "power_meter_k3",
      "proto": "modbus_rtu",
      "addr": 2,
      "bind_if": "RS485_1",
      "pl_int": 10000,
      "c_t_m": 1000,
      "params": [
        {
         "id": "temp_val", //唯一
         "f_": "x * 1.0", //自定义公式
        "si": 100, //采集间隔毫秒
        "sbr": 1, //是否上报 1上报 0 不上报
        "co": 1.5, //变化偏移值，变化上报时⽣效，表⽰值变化在这个值的正负范围外才触发变化上报。0表示变化上报，不填代表不变化上报。
        "rh": 10 //整点上报（单位：分钟），指定每⼏分钟上报⼀次
        }
      ]
    }
    
  },
  "ext": {  // 系统参数，管理网关自身的生命周期与运维功能；业务相关的状态控制放在物模型中。
    "addr": "iot.platform.com:1883",  // 设备 mqtt 指向地址
    "hb_int": 60,  // 心跳间隔
    "rtty": 1, // 是否开启rtty，1开启 
    "fV": "1.0.0", // 设备固件版本号
    "hV": "1.0.0", // 设备硬件版本号
    "cfV": "1.0.0", // 定制固件版本号，如果是定制⽹关，才会上报该字段
    "flashTotal": 1024000, // 硬盘总量
    "supportProtocols": [1, 2, 3], // 支持的协议类型ID列表
    "gatewayFrp": "12345678901234567890123456789012", // 网关 FRP
    "compressMode": 1, // 压缩模式 1 GZIP 0 无
    "ntpServer": "ntp.aliyun.com", // NTP 服务器地址
    "memTotal": 1024000 // 内存总量
  }
}

设备获取配置（conf.get）

设备开机上报使用这个进行上报。

• Topic (Down):  {PK}/{GWID}/self/sys/u
• Method (Key):  conf.get

{
  "id": "801",
  "m": "conf.get",
  "p":{
  	"key":["if","sub","ext"]   // 根据需要获取，如果为空则代表获取全部
  }
 }

系统配置下发 (conf.push)

该指令用于云端向网关推送全量或增量配置，是网关运行的“大脑”指令。

根据设备需要获取的参数进行下发

• Topic (Down):  {PK}/{GWID}/self/sys/d
• Method (Key):  conf.push

{

	"id": "801",
  "m": "conf.push",
  "v_conf": "20260306",
  "addr": "iot.platform.com:1883",
  "if": {
    "RS485_1": {
      "pt": 1, "bd": 9600, "dbs": 8, "pty": 0, "sbs": 1, "fi": 50, "to": 1000
    },
    "ETH_0": {
      "md": 1, "ip": "192.168.1.100", "nm": "255.255.255.0", "gw": "192.168.1.1",
      "lp": 502, "dns1": "8.8.8.8"
    }
  },
  "sub": {
    "sub_dev_sn_001": { // 
      "m_id": "temp_sensor_v1", // 模型名称
      "v": "v3.0.0",
    "proto": 1, //协议类型ID
    "addr": 1, //从站地址
    "bind_if": "RS485_1", //s
    "c_t": 5000, //通信超时毫秒
    "c_r": 500, //采集上报间隔秒
    "params": [
      {
        "id": "temp_val", //唯一
        "f_c": 3, //功能码
        "add": "0x0001", //寄存器
        "d_t": 2, //数据类型ID
        "bit": [0, 1, 2, 3, 4, 5, 6, 7], //位序,当type为Bit 或 具体协议功能必须解析是 bit 时必填,这里表示单个寄存器，多个位。
        "b_o": 0, //字节顺序
        "f_": "x * 1.0", //自定义公式
        "si": 100, //采集间隔毫秒
        "sbr": 1, //是否上报 1上报 0 不上报
        "co": 1.5, //变化偏移值，变化上报时⽣效，表⽰值变化在这个值的正负范围外才触发变化上报。0表示变化上报，不填代表不变化上报。
        "rh": 10 //整点上报（单位：分钟），指定每⼏分钟上报⼀次
      }
    ]
    },
    "sub_dev_sn_002": {  // DLT数据
      "m_id": "power_meter_k3",
      "proto": "modbus_rtu",
      "add": 2,
      "bind_if": "RS485_1",
      "pl_int": 10000,
      "c_t_m": 1000,
      "params": [
        {
         "id": "temp_val", //唯一
        "add": "0x0001", //DLT协议为表地址，不⽀持⼴播地
        "d_t": 2, //数据类型ID
        "bit": [0, 1, 2, 3, 4, 5, 6, 7], //位序,当type为Bit 或 具体协议功能必须解析是 bit 时必填,这里表示单个寄存器，多个位。
        "b_o": 0, //字节顺序
        "f_": "x * 1.0", //自定义公式
        "si": 100, //采集间隔毫秒
        "sbr": 1, //是否上报 1上报 0 不上报
        "co": 1.5, //变化偏移值，变化上报时⽣效，表⽰值变化在这个值的正负范围外才触发变化上报。0表示变化上报，不填代表不变化上报。
        "rh": 10 //整点上报（单位：分钟），指定每⼏分钟上报⼀次
        }
      ]
    },
    "sub_dev_sn_003": {  // JSON数据
      "m_id": "power_meter_k3",
      "proto": "modbus_rtu",
      "addr": 2,
      "bind_if": "RS485_1",
      "pl_int": 10000,
      "c_t_m": 1000,
      "params": [
        {
         "id": "temp_val", //唯一
         "f_": "x * 1.0", //自定义公式
        "si": 100, //采集间隔毫秒
        "sbr": 1, //是否上报 1上报 0 不上报
        "co": 1.5, //变化偏移值，变化上报时⽣效，表⽰值变化在这个值的正负范围外才触发变化上报。0表示变化上报，不填代表不变化上报。
        "rh": 10 //整点上报（单位：分钟），指定每⼏分钟上报⼀次
        }
      ]
    }
  },
  "ext": {
    "addr": "iot.platform.com:1883",  // 网关 mqtt 指向地址
    "hb_int": 60,  // 心跳间隔
    "rtty": 1, // 是否开启rtty，1开启 
    "fV": "1.0.0", // 设备固件版本号
    "hV": "1.0.0", // 设备硬件版本号
    "cfV": "1.0.0", // 定制固件版本号，如果是定制⽹关，才会上报该字段
    "flashTotal": 1024000, // 硬盘总量
    "supportProtocols": [1, 2, 3], // 支持的协议类型ID列表
    "gatewayFrp": "12345678901234567890123456789012", // 网关 FRP
    "compressMode": 1, // 压缩模式 1 GZIP 0 无
    "ntpServer": "ntp.aliyun.com", // NTP 服务器地址
    "memTotal": 1024000 // 内存总量
  }
}

设计结构描述

1. 基础信息层 (Metadata)

• id: 消息 ID。用于异步通信对齐，设备回复时必须携带此 ID。
• m:  方法类型标识。用于异步通信对齐，设备回复时必须携带此 ID。
• v_conf: 配置版本号。网关以此判断配置是否发生变化，实现“增量应用”或“跳过重复配置”。
• addr: 网关 MQTT 连接地址。允许云端动态迁移网关的接入集群。

2. 硬件接口层 (if)

设计意图：抹平不同厂家网关的硬件接口差异。Key（如 RS485_1）是抽象句柄，网关根据自身硬件映射表开启对应的物理驱动。

• 串口参数：涵盖了工业级通信必备的流控参数（如分帧间隔 fi 和超时 to）。
• 网口参数：支持静态/动态 IP 切换，及本地服务监听端口 lp（用于网关级联或本地调试）。

3. 子设备映射层 (sub)

设计意图：实现“软件定义网关”。通过 SN 作为 Key，灵活绑定物理通道与逻辑协议。

• bind_if: 核心逻辑，将子设备定向到特定的物理接口。
• pl_int / c_t_m: 实现针对每个设备的精细化调度逻辑（有的设备快采，有的慢采）。

4. 边缘解析层 (params)

设计意图：定义从原始二进制到结构化数据的转换逻辑。

• 功能码与地址 (f_c, r_a): 标准协议定位。
• 数据加工 (c_, f_):
  • c_ (系数)：处理简单的线性放缩。
  • f_ (公式)：支持边缘计算公式（如温度补偿或单位转换），降低云端计算压力。
• b_o (字节顺序)：解决工业现场大端/小端的“高低字节交换”痛点（如 ABCD, CDAB 等）。

5. 系统扩展层 (ext)

设计意图：管理网关自身的生命周期与运维功能。

• watchdog: 开启硬件看门狗，确保极端环境下网关死机能自动重启。
• vpn_en: 远程运维开关，仅在需要排查问题时开启隧道。

设备端反馈 (sys.conf.report)

网关应用配置后，必须通过上行通道反馈执行结果。

• Topic (Up): {ProductKey}/{GatewayID}/self/sys/u
• Method (Key):  conf.report  (ID 需与 Push 保持一致)

{
"id": "801",
  "m": "conf.report",
   "res": 0,
    "applied": ["if", "ext"],
    "failed": ["sub"],
    "msg": "Sub-device model v1 not found locally"
}

设备反馈报文 (conf.report) 详细说明

不会上报sub。sub只能平台下发。

结果状态码枚举说明 (res)

为了让云端后台能够自动处理异常（如自动重发或告警），建议定义以下细分状态码：

配置应用逻辑细节

1. 增量反馈机制

当网关只成功应用了部分配置时（如您的示例：硬件接口 if 成功，但子设备 sub 失败）：

• 网关应保持旧的 sub 配置运行，而不应删除已有的子设备，防止业务完全中断。
• 云端收到 failed: ["sub"] 后，应触发“物模型补发”流程。

五、物模型

物模型业务全流程Topic 映射

所有物模型统一使用 p\e\s 通道，通过 m (method) 区分具体动作。

属性业务 (p)

事件业务 (e)

服务业务 (s)

属性业务 (Property)

用于设备状态的实时监控与远程控制。

完整 Payload 示例

 属性写入 (p.set) —— 云端控制设备

场景描述：用户在 App 上下发指令，要求网关修改某个子设备的运行参数（如设置空调温度或打开继电器）。

云端请求 (Down)

云端向网关推送需要修改的属性键值对。

• Topic: {PK}/{GWID}/{SubDevSN}/p/d
• Payload:

{
  "id": "1024",              // 消息唯一标识
  "m": "p.set",           // 方法：属性设置
  "p": {
    "temp_set": 26.5,        // 设置温度为 26.5
    "power_switch": 1        // 开启电源
  }

}

设备执行并反馈 (Up)

网关收到指令后，通过串口或网口将指令转发给子设备。执行完成后，必须回复执行结果。

• Topic: {PK}/{GWID}/{SubDevSN}/prop/u
• Payload:

{
  "id": "1024",              // 必须与下发的 id 一致
  "m": "p.set_reply",     // 方法：设置响应
  "res": 0,                  // 0: 成功, >0: 失败错误码
  "msg": "success"           // 错误描述
}

属性读取 (prop.read) —— 云端同步状态

场景描述：云端后台发现子设备长时间未上报数据，或者在执行关键任务前需要获取设备的实时精确值，发起主动查询。

1. 云端请求 (Down)

云端指定要查询的属性标识符（Key）列表。

• Topic: {PK}/{GWID}/{SubDevSN}/p/d
• Payload:

{
  "id": "2048",
  "m": "p.read",
  "p": ["temp_val", "humi_val", "status"] // 想要读取的属性列表
}

2. 设备响应 (Up)

网关立即采集底层数据并返回结果。

• Topic: {PK}/{GWID}/{SubDevSN}/p/u
• Payload:

{
  "id": "2048",
  "m": "p.read_reply",
  "res": 0,
 // 返回请求的实时属性值
    "temp_val": 25.8,
    "humi_val": 45,
    "status": 1
}

错误码示例 (res)

在读写反馈中，常用的错误码枚举：

• 101 (Not Support): 设备不支持该属性的读/写操作。
• 102 (Offline): 子设备已离线，网关无法与其通信。
• 103 (Timeout): 串口/网口通信超时，子设备未响应。
• 104 (Value Invalid): 写入的值超出合法范围（如设置频率为 -5Hz）。

事件业务 (Event)

用于设备异常告警或重要状态记录。

1. 事件上报示例 (Up)

网关实时推送事件信息。

• Topic: {PK}/{GWID}/{SubDevSN}/e/u
• Payload:

// 单个事件
{
  "id": "3001",
  "m": "e.report",
    "eid": "E1002",             // 事件标识符：传感器异常
    "lvl": "ERROR",             // 告警级别
    "msg": "RS485_1 Timeout",   // 具体的错误描述
    "ts": 1741249860000,       // 事件发生的毫秒时间戳
    "dat": {                    // 发生告警时的上下文快照
      "addr": 1,
      "retry": 3
    }
  
}
// 
{
  "id": "3005",
  "m": "e.batch_report",
  "p": [
      "eid": "E1002",            // 事件标识符
      "lvl": 2,                  // 级别：ERROR
      "ts": 1741249860000,       // 事件发生的毫秒时间戳
      "msg": "Comm Timeout",     // 描述
      "dat": { "retry": 3 }      // 快照数据
    },
    {
      "eid": "W2005",
      "lvl": 1,                  // 级别：WARN
      "ts": 1741249861500,
      "msg": "High Temperature",
      "dat": { "val": 85.5 }
    },
    {
      "did": "gateway_self",     // 网关自身事件
      "eid": "I3001",
      "lvl": 0,                  // 级别：INFO
      "ts": 1741249862000,
      "msg": "Config Applied"
    }
  ]
}

服务业务 (Service)

用于执行一次性、有结果返回的控制指令。

Payload 示例 (srv.reboot):

{"id": "301", "m": "s.reboot", "p": {"delay": 5, "target": "gateway"}}

1. 服务下发 (Down)

云端指定服务标识并传入必要的执行参数。

• Topic: {PK}/{GWID}/self/s/d （注：通常网关自身服务使用 self，子设备服务使用其 SN）
• Payload:

{
  "id": "4001",
  "m": "s.reboot",           // 服务标识：远程重启
  "p": {
    "delay": 10,               // 重启延迟时间(秒)
    "reason": "config_update"  // 重启原因
  }
}

2. 服务反馈 (Up)

网关执行完成后，反馈执行结果。

• Topic: {PK}/{GWID}/self/s/u
• Payload:

{
  "id": "4001",
  "m": "s.reboot_reply",     // 服务响应标识
  "res": 0,                    // 执行结果 (0: 成功)
  "p": {                       // 可选：服务执行后的返回数据
    "exec_time": "2026-03-06 16:30:00"
  }
}