帮助文档

FAQ


瑞瀛物联网数据传输协议(MQTT)

[TOC]

1、概述

本协议时针对网关和云平台之间进行有效通信而设计的一种数据交换规范，数据格式为 JSON，为了方便描述其对象定义，描述格式参照 GraphQL 的标准。

  • gwMAC网关的 COO MAC 地址，用来唯一标识网关
  • productKey子设备的品类编码
  • deviceName子设备的 MAC 地址，用来唯一标识子设备
  • event设备的事件名称，详见品类的物模型定义
  • service设备的服务名称，详见品类的物模型定义

2、设备接入

2.1、设备身份注册

2.1.1、网关动态注册

网关向平台发起注册请求：

  • 数据上行
  • -请求 Topic：rex/auth/register/device
  • 响应 Topic: rex/auth/register/${gwMAC}
  • 请求数据格式：DeviceRegisterReq
  • 响应数据格式：DeviceRegisterRes

2.1.2子设备动态注册

子设备通过网关向平台发起注册请求：

  • 数据上行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/sub/register
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/sub/register_reply
  • 请求数据格式：DeviceListReq
  • 响应数据格式：SubDeviceRegisterRes

2.2、拓扑关系管理

2.2.1、子设备入网通知

子设备加入 ZigBee 网络后，通常需要将该子设备与网关进行拓扑关系的绑定，以方便后期的运维操作：

  • 数据上行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/topo/join
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/topo/join_reply
  • 请求数据格式：TopoAddReq
  • 响应数据格式：DeviceList

2.2.2、子设备离网通知

子设备离开 ZigBee 网络后，网关将通知平台解除绑定：

  • 数据上行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/topo/leave
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/topo/leave_reply
  • 请求数据格式：DeviceListReq
  • 响应数据格式：DeviceList

2.2.3、云端下发子设备列表

在某些场景下，平台通知网关网络中可能存在的子设备，要求网关主动发起设备发现功能，此时扫描出来的子设备将无需上报至平台：

  • 数据下行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/topo/add
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/topo/add_reply
  • 请求数据格式：DeviceListReq
  • 响应数据格式：CommonRes

2.2.4、云端主动删除子设备

云端可以主动要求指定的子设备离网：

  • 数据下行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/topo/delete
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/topo/delete_reply
  • 请求数据格式：DeviceListReq
  • 响应数据格式：DeviceList

2.2.5、获取设备拓扑关系

为了保证网关与平台间的拓扑关系保持一致，平台可以获取网关的设备列表，一旦发现双方设备列表不一致，平台应当主动发起 2.2.3 或 2.2.4 请求以保持后续的数据一致性：

  • 数据下行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/topo/get
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/topo/get_reply
  • 请求数据格式：CommonReq
  • 响应数据格式：DeviceList

2.3、设备状态管理

2.3.1、网关上线

网关上线时通知平台：

  • 数据上行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/login
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/login_reply
  • 请求数据格式：CommonReq
  • 响应数据格式：CommonRes

2.3.2、网关下线

网关下线时通知平台：

  • 数据上行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/logout
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/logout_reply
  • 请求数据格式：CommonReq
  • 响应数据格式：CommonRes

2.2.3、子设备上线

子设备上线时通知平台：

  • 数据上行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/sub/login
  • 响应 Topic: rex/R101Gateway/${gwMAC}/sub/login_reply
  • 请求数据格式：DeviceLoginReq
  • 响应数据格式：DeviceList

2.3.4、子设备下线

子设备离线时通知平台，ZigBee 设备离线时不会主动通知网关，目前是根据 2 倍心跳周期时长内未收到子设备任何报文来判断子设备离线：

  • 数据上行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/sub/logout
  • 响应 Topic: rex/R101Gateway/${gwMAC}/sub/logout_reply
  • 请求数据格式：DeviceListReq
  • 响应数据格式：DeviceList

3、消息通信

3.1、设备属性、事件、服务

3.1.1、属性上报

设备上报属性，其中属性名称和值类型需要参考每一种品类的物模型定义：

  • 数据上行
  • 请求 Topic: rex/${productKey}/${deviceName}/thing/event/property/post
  • 响应 Topic: rex/${productKey}/${deviceName}/thing/event/property/post_reply
  • 请求数据格式：PropertyPostReq
  • 响应数据格式：CommonRes

3.1.2、属性设置

设置设备属性，其中属性名称和值类型需要参考每一种品类的物模型定义：

  • 数据下行
  • 请求 Topic: rex/${productKey}/${deviceName}/thing/service/property/set
  • 响应 Topic: rex/${productKey}/${deviceName}/thing/service/property/set_reply
  • 请求数据格式：PropertySetReq
  • 响应数据格式：CommonRes

3.1.3、事件上报

设备的事件上报，其中事件名称和相应的参数需要参考每一种品类的物模型定义：

  • 数据上行
  • 请求 Topic: rex/${productKey}/${deviceName}/thing/event/${event}/post
  • 响应 Topic: rex/${productKey}/${deviceName}/thing/event/${event}/post_reply
  • 请求数据格式：EventPostReq
  • 响应数据格式：CommonRes

3.1.4、服务调用

设备的服务调用，其中服务名称和相应的参数需要参考每一种品类的物模型定义，如未加特殊说明，服务调用均为异步调用，无法通过响应内容获知该服务调用是否成功：

  • 数据下行
  • 请求 Topic: rex/${productKey}/${deviceName}/thing/service/${service}
  • 响应 Topic: rex/${productKey}/${deviceName}/thing/service/${service}_reply
  • 请求数据格式：ServiceCallReq
  • 响应数据格式：ServiceCallRes

4、监控运维

4.1、OTA升级

4.1.1、版本信息上报

网关上线后，会主动上报版本信息：

  • 数据上行
  • Topic: rex/R101Gateway/${gwMAC}/ota/device/inform
  • 请求数据格式：OtaInform

4.1.2、平台推送 OTA 升级包信息

平台在需要时，将主动推送升级包要求网关进行 OTA 升级

  • 数据下行
  • Topic: rex/R101Gateway/${gwMAC}/ota/device/upgrade
  • 请求数据格式：OtaUpgrade

4.1.3、设备上报升级进度

网关升级过程中会上报升级进度：

  • 数据上行
  • Topic: rex/R101Gateway/${gwMAC}/ota/device/progress
  • 请求数据格式：OtaProgress

4.1.4、子设备 OTA 推送

平台可以发起子设备的 OTA 升级：

  • 数据下行
  • 请求 Topic: rex/${productKey}/${deviceName}/ota/device/upgrade
  • 请求数据格式：OtaUpgrade

4.1.5、子设备升级进度上报

子设备升级过程中也同样会上报升级进度：

  • 数据上行
  • Topic: rex/${productKey}/${deviceName}/ota/device/progress
  • 请求数据格式：OtaProgress

5、本地场景

5.1、设备别名

设备的 MAC 地址具有全局唯一性，在实际的业务场景中如果场景的配置直接使用 MAC 作为设备标识的话，一旦出现设备更换则会导致所有涉及该设备的场景配置均需要重新配置；另一方面，不同的设备 MAC 地址也不利于快速地复制场景到其它的网络中。因此，需要设计一个设备别名机制，只需要保持设备别名相同，场景就能寻找到该设备。

5.1.1、设置设备别名

平台将子设备的 MAC 地址与设备别名进行绑定：

  • 数据下行
  • 请求 Topic: rex/${productKey}/${deviceName}/thing/service/alias/set
  • 响应 Topic: rex/${productKey}/${deviceName}/thing/service/alias/set_reply
  • 请求数据格式：AliasSetReq
  • 响应数据格式：CommonRes

5.2、场景管理

5.2.1、创建或更新场景

平台将场景的配置下发到网关：

  • 数据下行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/service/scene_create_update
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/service/scene_create_update_reply
  • 请求数据格式：ServiceCallReq
  • 响应数据格式：ServiceCallRes

5.2.2、删除场景

平台通知网关删除指定场景：

  • 数据下行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/service/scene_delete
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/service/scene_delete_reply
  • 请求数据格式：ServiceCallReq
  • 响应数据格式：ServiceCallRes

5.2.3、触发场景

触发执行场景：

  • 数据下行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/service/scene_trigger
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/service/scene_trigger_reply
  • 请求数据格式：ServiceCallReq
  • 响应数据格式：ServiceCallRes

5.2.4、启用场景

启用场景：

  • 数据下行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/service/scene_enable
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/service/scene_enable_reply
  • 请求数据格式：ServiceCallReq
  • 响应数据格式：ServiceCallRes

5.2.5、禁用场景

禁用场景，场景一旦被禁用后，将不会被自动触发，但仍然可以通过 5.2.3 节的指令触发该场景：

  • 数据下行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/service/scene_disable
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/service/scene_disable_reply
  • 请求数据格式：ServiceCallReq
  • 响应数据格式：ServiceCallRes

6、其它功能

6.1、ZigBee 相关指令

6.1.1、创建 ZigBee 网络

创建 ZigBee 网络：

  • 数据下行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/service/create_zigbee_network
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/service/create_zigbee_network_reply
  • 请求数据格式：ServiceCallReq
  • 响应数据格式：ServiceCallRes

其中，请求参数有：

  • Trug表示是否使用随即参数建网，默认值为false
  • ZigbeeNetworkParam为 base64 编码后的网络参数

如：

{
  "id": 1671602294,
  "params": [{
    "key": "Trug",
    "value": false
  },{
    "key": "ZigbeeNetworkParam",
    "value": "22irgAXVs3DbaAoWAgEAANtoq4AF1bNwAgAAAI06rAlSBHzHoPwseYZgC8Szk9OZBgtANJGpe09jAkVwAIAbAACAAwA="
  }]
}

6.1.2、离开 ZigBee 网络

离开 ZigBee 网络：

  • 数据下行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/service/leave_zigbee_network
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/service/leave_zigbee_network_reply
  • 请求数据格式：ServiceCallReq
  • 响应数据格式：ServiceCallRes

6.1.3、开启扫网

允许子设备入网：

  • 数据下行
  • 请求 Topic: rex/R101Gateway/${gwMAC}/thing/service/start_permit_join
  • 响应 Topic: rex/R101Gateway/${gwMAC}/thing/service/start_permit_join_reply
  • 请求数据格式：ServiceCallReq
  • 响应数据格式：ServiceCallRes

其中，请求参数有：

  • duration表示开启扫网的时长，默认为30秒，最小值10秒，最大值300秒
  • installCode不为空则表示支持 installCode 入网
  • mac为 MAC 地址的数组，不为空表示白名单入网，在白名单以外的设备拒绝入网请求

示例：

{
  "id": 1671602296,
  "params": [{
    "key": "duration",
    "value": 30
  },{
    "key": "installCode",
    "value": "0123456789ABCDEF"
  },{
    "key": "mac",
    "value": ["0123456789ABCDEF"]
  }]
}

7、数据结构定义

input DeviceRegisterReq {
    deviceName: String!
    productKey: String!
}
input CommonReq {
    id: ID!                     # 消息 id 在当前设备中要求具有唯一性
}
input DeviceListReq {
    id: ID!
    params: [DeviceParam!]
}
input DeviceParam {
    deviceName: String!         # 设备名称
    productKey: String!         # 设备的产品 ProductKey
}
input TopoAddReq {
    id: ID!
    deviceName: String!     # 子设备名称
    productKey: String!     # 子设备所属产品的 ProductKey
}
input DeviceLoginReq {
    id: ID!
    productKey: String!
    deviceName: String!
}
input PropertyPostReq {
    id: ID!
    params: [DeviceProperty!]
}
input DeviceProperty {
    name: String!
    value: Value!
    time: Timestamp!
}
input PropertySetReq {
    id: ID!
    params: [DevicePropertySet!]
}
input DevicePropertySet {
    name: String!
    value: Value!
}
input EventPostReq {
    id: ID!
    params: [KeyValuePair!]
    time: Timestamp!
}
input KeyValuePair {
    key: String!
    value: Value!
}
input ServiceCallReq {
    id: ID!
    params: [KeyValuePair!]
}
input AliasSetReq {
    id: ID!
    alias: String!
}
input OtaInform {
    id: ID!
    version: String!
    module: String! # 模块名称
}
input OtaUpgrade {
    id: ID!
    size: Int
    version: String
    module: String
    url: String!
    md5: String
    params: [KeyValuePair!]
}
input OtaProgress {
    id: ID!
    step: Int!
    module: String1
    desc: String
}

union Value = Int | Float | String | Boolean

type CommonRes {
    id: ID!
    code: Int!
}
type DeviceRegisterRes {
    code: Int!
    device: RegisterData!
}
type SubDeviceRegisterRes {
    id: ID!
    code: Int!
    data: [RegisterData!]
}
type RegisterData {
    deviceName: String!
    productKey: String!
    deviceSecret: String!
}
type DeviceList {
    id: ID!
    code: Int!
    data: [DeviceData!]
}
type DeviceData {
    deviceName: String!
    productKey: String!
}
type ServiceCallRes {
    id: ID!
    code: Int!
    data: [KeyValueData!]
}
type KeyValueData {
    key: String!
    value: Value!
}

8、错误信息码

页面列表

ITEM_HTML