物模型

五、物模型

物模型业务全流程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"
  }
}