设备接入概述

概述

本文主要描述了如何注册和管理云平台设备.

前端设备主要通过消息订阅/发布模式以和云端消息队列进行通信

本文定义的接口主要供前端设备调用.

系统前缀

API:

http(s)://{domain-name}/v2/stream/

版本

V2.0

作者

@author ChengZhen

修改历史

2019/4/21

• 添加公共组件
• 移出 HTTP API

2019/2/13

• 重写 API

2018/10/9

• 修改注册消息内容, 添加事物描述等信息
• 删除设备状态 API
• 修改边缘节点管理 API 名称
• 添加新的签名算法

消息主题

前端设备通过消息队列和服务器进行通信，下面是主要的消息主题：

messages - 上行主题

/messages/:did

• did 设备 ID

前端设备通过这个主题向云端发送消息

• 只有认证的设备有发布的权限
• 只有认证的服务器有订阅的权限

actions - 下发主题

/actions/:did

• did 设备 ID

前端设备通过订阅这个主题接收云端下发的消息

• 只有认证的设备有订阅的权限
• 只有认证的服务器有发布的权限

消息类型

云平台将所有设备和云, 设备和设备之间的通信数据统称为消息.

消息通常是 JSON 格式:

普通消息

普通消息格式

{
    "did": String,
    "type": "message",
    "data": {}
}

• did 设备的 ID, 由设备端定义，必须是唯一的
• type 消息的类型
• data 消息的内容

数据流消息

前端设备通过发送这个消息来主动上报数据流和属性值

{
    "did": String,
    "token": String,
    "timestamp": Number,
    "type": "stream",
    "data": {
        "<name>": {
            "points": [{
                "isOn": false,
                "temperature": 25.5,
                "battery": 95,
                "status": "on",
                "at": 1234567890
            }],
            "tags": {
                "location": "d2s"
            }
        }
    }
}

• did 设备的 ID
• type 消息类型总是为 stream
• token 设备访问令牌
• timestamp 时间戳
• data 数据流
  • name 数据流的名称
    • points 数据点数组
    • tags 标签信息

操作消息

请求消息

云端通过发送这个消息来调用设备指定的操作方法

{
    "did": String,
    "mid": String,
    "type": "action",
    "data": {
        "<name>": <input>
    }
}

• did 设备 ID
• type 消息类型总是为 action
• mid 消息 ID
• data 操作数据
  • name 操作名称
    • input {any} 输入参数

应答消息

设备通过发送这个消息向云端返回操作调用结果

{
    "did": String,
    "mid": String,
    "type": "action",
    "result": {
        "<name>": <output>
    }
}

• did 设备 ID
• type 消息类型总是为 action
• mid 消息的 ID, 必须和相关的请求消息的 mid 相同
• result 操作结果
  • name 操作名称
    • output 输出参数

错误消息

设备通过发送这个消息向云端返回操作调用结果

{
    "did": String,
    "mid": String,
    "type": "action",
    "result": {
        "<name>": {
            "code": Number,
            "error": String
        }
    }
}

• did 设备 ID
• type 消息类型总是为 action
• mid 消息的 ID, 必须和相关的请求消息的 mid 相同
• result 操作结果
  • name 操作名称
    • code 错误码
    • error 错误短语

属性消息

读取属性消息

云端通过发送这个消息来读取设备的属性值

{
    "did": String,
    "mid": String,
    "type": "action",
    "data": {
        "read": ["<name>"]
    }
}

• did 设备的 ID
• mid 消息 ID
• type 消息类型总是为 action
• data 要读取的属性
  • read 读取操作
    • name 可选，要读取的属性的名称

应答消息

{
    "did": String,
    "mid": String,
    "type": "action",
    "result": {
        "read": {
            "<name>": <value>
        }
    }
}

• did 设备的 ID
• mid 可选的消息 ID，和 read 消息的 mid 相同
• type 消息类型总是为 action
• result操作结果
  • read 读取操作
    • name 属性的名称
      • value {any} 属性的值

修改属性消息

云端通过发送这个消息来修改设备的属性值

{
    "did": String,
    "mid": String,
    "type": "action",
    "data": {
        "write": {
            "<name>": <value>
        }
    }
}

• did 设备的 ID
• mid 消息 ID
• type 消息类型总是为 action
• data 要修改的属性
  • write 修改操作
    • name 要修改的属性的名称
      • value 要修改的属性的值

应答消息

{
    "did": String,
    "mid": String,
    "type": "action",
    "result": {
        "write": {
            "code": 0
        }
    }
}

• did 设备的 ID
• mid 可选的消息 ID，和 read 消息的 mid 相同
• type 消息类型总是为 action
• result操作结果
  • write 修改操作
    • code 执行结果, 0 表示执行成功，否则表示错误码

事件消息

设备通过发送这个消息来发布事件通知

{
    "did": String,
    "token": String,
    "timestamp": Number,
    "type": "event",
    "data": {
        "<name>": <data>
    }
}

• did 设备的 ID
• token 设备访问令牌
• timestamp 时间戳
• type 消息类型总是为 event
• data事件数据
  • name 事件名称
    • data {any} 事件的内容

注册消息

注册请求消息

设备通过发送这个消息向服务端注册

{
  "did": String,
  "type": "register",
  "sign": String,
  "data": {}
}

• did 设备的 ID
• type 消息类型总是为 register
• sign 设备签名
• data 设备事物描述, 具体格式请参考 事物描述 一文

注册应答消息

由云端返回给设备

{
  "did": String,
  "type": "register",
  "result": {
    "id": String,
    "token": String,
    "expires": Number,
  }
}

• did 设备的 ID
• type 消息类型总是为 register
• result 注册信息
  • expires 注册有效期, 单位为秒，-1 表示注销注册
  • token 设备访问令牌, 注册有效期内可用

注册错误消息

由云端返回给设备

{
  "did": String,
  "type": "register",
  "result": {
    "code": Number,
    "error": String
  }
}

• did 设备的 ID
• type 消息类型总是为 register
• result 注册结果
  • code 错误码
  • error 错误信息

更多信息请参考设备注册一节

设备接入

接入方式

设备直连接入

设备通过有线, BN-IoT 或 4G 等直接连接到物联网云平台

• 有线以太网
• 无线局域网
• BN-IoT 窄带广域网
• 4G

通过网关接入

设备通过 Bluetooth, Modbus 等连接到网关，再间接连接到物联网云平台

• RS485/Modbus
• 工业以太网
• Bluetooth
• ONVIF/RTSP 适合网络摄像机等

接入协议

平台支持多种主流接入协议，以便适应不同类型的设备，下面是不同协议的特点。

CoAP (LwM2M)

• 使用 NB-IoT 网络；
• 对成本和功耗十分敏感；
• 对数据传输的实时性要求不高；
• 存在海量连接
• 对于覆盖广度要求高；

MQTT

• 使用 4G 网络或有线宽带
• 需要保持长连接状态；
• 需要实时接收控制指令；
• 有充足的电量支持设备保持在线；

HTTP

• 只上报传感器数据到平台；
• 无需下行控制指令到设备；
• 适合简单数据上报场景

Modbus

• 采用串行或网线有线通信；
• 需要通过支持 modbus 协议 DTU 中转
• 适用于连接标准 modbus 协议通信设备

Bluetooth

• 采用短距离无线通信；
• 对功耗极端敏感；
• 需要通过支持 Bluetooth 协议网关中转

设备接入流程

start=>start: 开始开发
sub2=>operation: 创建产品
sub3=>operation: 创建设备
sub4=>operation: 注册设备
sub5=>operation: 状态上报
sub6=>operation: 设备操作

start(right)->sub2(right)->sub3(bottom)->sub4(right)->sub5(right)->sub6

图1. 设备接入流程

1. 准备硬件方案，移植 SDK 或实现通信协议
2. 在平台上创建新的产品
3. 为新的产品创建新的设备
4. 使用创建的设备的 ID 和密钥，将硬件设备注册到云平台
5. 向云平台上报状态信息
6. 向云平台订阅操作消息，接收并处理云平台发送的操作请求

设备注册

# 示意图
设备->网管服务:   1)注册 (POST /register) 设备描述信息
网管服务->数据库:     2)查询并验证设备
数据库-->网管服务:    2)设备属性
网管服务-->设备:  1)返回访问令牌等注册信息
设备->网管服务:   3)更新注册 (POST /register)
网管服务-->设备:  3)返回注册信息
设备->网管服务:   1)注销注册 (POST /register with -1)
网管服务-->设备:  1)返回注销成功信息

图2. 设备注册通信流程

设备注册流程：

1. 通过 APP 或串口配置设备注册参数
2. 设备向配置的服务器地址发送注册请求
3. 设备接收并保存云平台返回的注册信息
4. 设备向云平台订阅操作消息主题
5. 设备定时向云平台上报设备状态和数据流
6. 需要时设备上云平台发送注销请求
7. 注销成功即可关闭设备，不再上报数据和处理云端操作命令

添加设备

设备注册的目的是为了取得设备的 ID, 并验证设备的合法性, 在注册之前必须先在云端创建相关的设备

设备在线状态

需要根据不同接入协议来判定设备的在线状态

• HTTP

设备注册到云端视为上线, 在控制台显示为在线状态 当超时没有收到设备的任何数据时 (如 30 分钟) 视为下线, 在控制台显示为离线状态

• MQTT

设备注册到云端视为上线, 在控制台显示为在线状态 当设备断开和 MQTT 服务端的连接时视为下线, 在控制台显示为离线状态

• CoAP

设备注册到云端视为上线, 在控制台显示为在线状态 设备通过心跳消息保持在线状态 当 CoAP 服务器超时没有收到设备的心跳消息时 (如 2 分钟) 视为下线, 在控制台显示为离线状态

设备属性

读取属性

应用程序可以远程读取设备属性

设备->消息队列: 订阅 actions/:did
应用程序->消息队列: 订阅 messages/:did
应用程序->消息队列: 发布请求到 actions/:did
消息队列->设备: 请求
设备->消息队列: 发布属性值到 messages/:did
消息队列->应用程序: 属性值

修改属性

应用程序可以远程修改设备属性

设备->消息队列: 订阅 actions/:did
应用程序->消息队列: 订阅 messages/:did
应用程序->消息队列: 发布请求到 actions/:did
消息队列->设备: 请求
设备->消息队列: 发布结果到 messages/:did
消息队列->应用程序: 结果

主动上报

设备可以主动上报属性值及其数据流

数据采集

一般通过以下两种方式采集数据

• 通过定时器采集传感器数据
• 实时监控传感器数据，当数据发生突变时才上报数据

数据缓存

设备应能缓存最近多次采集的数据, 在网络恢复的时候能再次上传给云端

• 通过 MQTT 实现数据断线续传，通过在发布时将 QoS 设置为 1 或 2 即可实现
• 在网关上通过嵌入式数据库保存最近一段时间的数据

设备操作

设备事件

发布事件

设备可通过事件消息上报事件到云端

查询事件

云端会记录设备上报的事件, 应用程序可以查询最近发生的事件