核心产品实现参考

@cz 最后修改于 2020-09-27 19:20:04 rev.5762 - 最近修改

核心产品实现参考

概述

本文主要描述了本平台所有自研硬件设备包含的服务，和云平台的接口以及具体的数据格式，供设备固件开发参考。

DT01 数据采集器

基于蓝牙 SoC 和 NB-IoT 通信的数据采集器

无操作系统
使用 C 语言开发
支持 OTA 升级
基于 NB-IoT 通信，速率慢，但功耗低
通信协议：CoAP
数据格式: JSON
消息长度限制: 1000 字节

主要遥测服务

NAME	FULL NAME	NOTE
device	Device	必须
connectivity	Connectivity Monitoring	建议
firmware	Firmware Update	必须
location	Location	-
statistics	Connectivity Statistics	可选
config	Parameter Configuration	必须

设备注册

请求消息

{
    "did": "001122334455",
    "type": "register",
    "sign": "471332d2e16f524d377224cda1573c86:md5",
    "data": {
        "version": {
            "firmware": "1.0",
        }
    }
}

did 数据采集器设备 ID (MAC 地址)
type 消息类型，总是为 register
sign 设备签名
data 设备描述信息
- version 表示这个设备的版本信息
  - firmware 表示固件的版本信息，字符串格式

应答消息

{
    "did": "001122334455",
    "type": "register",
    "result": {
        "id": "3434689jkjsdf34398095829",
        "expires": 3600,
        "token": "39409080928349028592"
    }
}

did 数据采集器设备 ID
type 消息类型，总是为 register
result 注册结果
- id 由服务端分配的 ID，暂时没有用到
- token 设备访问令牌
- expires 设备访问令牌有效时间，单位为秒

设备 - device

ID	NAME	TYPE	VALUE	NOTE
0	manufacturer	string	TDK	-
1	modelNumber	string	DT01	-
2	serialNumber	string	345000123	可选, `保留将来使用`
3	firmwareVersion	string	1.0	-
4	reboot	action	-	-
5	reset	action	-	可选, `保留将来使用`
6	powerSources	integer	0	0 表示 DC 供电
7	powerVoltage	integer	3800	3800 mV
10	memoryFree	integer	15	15KB
11	errorCode	integer	0	0 表示没有错误
13	currentTime	integer	1367491215	用于时间同步
14	UTCOffset	string	+02:00	用于时间同步
15	timezone	string	-	可选, 用于时间同步
17	deviceType	string	dtu	-
18	hardwareVersion	string	1.0	-
20	batteryStatus	integer	0~6	可选, `保留将来使用`
21	memoryTotal	integer	256	256KB

电源类型

0 DC 供电
1 内部电池
2 外部电池
4 PoE 供电
5 USB 供电
6 AC 供电
7 太阳能供电

错误码

没有错误
低电量
外部电源关闭
定位模式失败
信号强度低
内存不足
短信异常
IP 连接异常
外围设备异常

read - 读取信息

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "data": {
        "device": {
            "read": {}
        }
    }
}

应答消息:

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "result": {
        "device": {
            "read": {
                "manufacturer": "TDK",
                "modelNumber": "DT01",
                "currentTime": 123403434353,
                "firmwareVersion": "1.0"
            }
        }
    }
}

write - 修改系统时间等

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "data": {
        "device": {
            "write": {
                "currentTime": 123403434353
            }
        }
    }
}

应答消息:

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "result": {
        "device": {
            "write": {
                "code": 0
            }
        }
    }
}

reboot - 设备重启

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "data": {
        "device": {
            "reboot": {
                "delay": 1
            }
        }
    }
}

data 操作数据
- device 设备管理接口
  - reboot 重启操作
    - delay 延时重启时间，单位为秒

应答消息:

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "token": "39409080928349028592",
    "result": {
        "device": {
            "reboot": {
                "code": 0
            }
        }
    }
}

固件 - firmware

ID	NAME	TYPE	VALUE	NOTE
1	uri	string	http://test.com/test.bin	固件文件下载地址
2	update	action	-	-
3	state	integer	0	0 表示空闲状态
5	result	integer	0	0 表示初始状态
7	version	string	1.0	版本 1.0
8	protocol	integer	0	0 表示 CoAP 协议
9	delivery	integer	0	0 表示只支持拉取模式

state 更新状态

0：空闲状态
1：正在下载
2：完成下载
3：正在更新

result 更新结果

0：初始状态
1：固件更新成功
2：没有足够的 Flash 空间
3：没有足够的内存空间
4：下载过程中连接断开
5：固件验证失败
6：不支持的固件类型
7：无效的 URI
8：固件更新失败
9：不支持的通信协议

update - 升级操作

升级请求:

{
    "did": "001122334455",
    "mid": "123456789",
    "type": "action",
    "data": {
        "firmware": {
            "update": {
                "uri": "http://{domain-name}/v2/device/firmware/file?did=1123945343439",
                "md5sum": "11223344556677889900aabbccddeeff",
                "version": "3.0"
            }
        }
    }
}

请求应答:

{
    "did": "001122334455",
    "mid": "123456789",
    "type": "action",
    "result": {
        "firmware": {
            "update": {
                "code": 0
            }
        }
    }
}

read - 读取固件状态

读取请求:

{
    "did": "001122334455",
    "mid": "123456789",
    "type": "action",
    "data": {
        "firmware": {
            "read": {}
        }
    }
}

请求应答:

{
    "did": "001122334455",
    "mid": "123456789",
    "type": "action",
    "result": {
        "firmware": {
            "read": {
                "state": 0,
                "result": 0,
                "protocol": 0,
                "delivery": 0,
                "uri": "http://{domain-name}/v2/device/firmware/file?did=1123945343439",
                "md5sum": "11223344556677889900aabbccddeeff",
                "version": "3.0"
            }
        }
    }
}

下载升级文件

CoAP 协议:

GET coap://{domain-name}:8952/firmware?did=1123945343439

以块传输方式下载固件文件

固件文件暂存在内存或 Flash
下载完后需验证 md5 值

固件升级事件

升级状态事件

{
    "did": "001122334455",
    "type": "event",
    "token": "34242523454639",
    "data": {
        "firmware": {
            "state": 0,
            "result": 0
        }
    }
}

参数配置 - config

DT01 默认只关联一台从机
配置参数最大长度不能超过 1000 个字节

更多信息请参考 Modbus 设备

read - 修改参数

修改参数后不会马上应用
收到参数后将暂时缓存在 RAM 中
只保存 write 内部的内容，需要整体保存
配置参数总共长度不能超过 800 个字节 (包含整个消息不通超过 1KB)

{
    "did": "aa1234567891",
    "mid": "1234",
    "type": "action",
    "data": {
        "config": {
            "write": {
                "properties": {
                },
                "updated": 0
            }
        }
    }
}

properties属性列表
updated 配置参数版本号

应答消息

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "result": {
        "config": {
            "write": {
                "code": 0
            }
        }
    }
}

write - 读取参数

返回最后下发的配置参数内容

{
    "did": "aa1234567891",
    "mid": "1234",
    "type": "action",
    "data": {
        "config": {
            "read": {}
        }
    }
}

应答消息:

{
    "did": "aa1234567891",
    "mid": "1234",
    "type": "action",
    "result": {
        "config": {
            "read": {
                "updated": 0,
                "properties": {}
            }
        }
    }
}

注意：修改参数后需要重启设备才能生效

DT02 物联网关

基于 Linux 的物联网关

内置 Linux 操作系统
使用 C 和 Lua 语言开发
软件可以单独升级
能通过有线或 4G 通信，速率快，功耗高
通信协议: MQTT
数据格式: JSON

主要遥测服务

ID	NAME	FULL NAME	NOTE
3	device	Device	必须
4	connectivity	Connectivity Monitoring	可选
5	firmware	Firmware Update	必须
6	location	Location	可选
7	statistics	Connectivity Statistics	可选
8	config	Parameter Configuration	必须
9	peripheral	Peripheral	可选

错误码

CODE	NAME	NOTE
18001	串口打开失败	串口设置错误或发生异常
18002	连接超时	从机未连接，错误的地址，通信异常等
18003	不支持的操作码	使用了从机不支持的操作码
9	无效的配置参数	错误的配置参数

设备注册

{
    "did": "001122334455",
    "type": "register",
    "sign": "471332d2e16f524d377224cda1573c86:md5",
    "data": {
        "iccid": "898607b9123770729456",
        "imsi": "460041912306456",
        "nodes": ["aa1122334455"],
        "version": {
            "firmware": "1.0",
            "software": "1.0",
            "config": "1234567890"
        }
    }
}

did 数据采集器设备 ID (MAC 地址)
type 消息类型，总是为 register
sign 设备签名
data 设备描述信息
- iccid SIM 卡号
- imsi 电话号码
- nodes 边缘节点列表, 为节点 did字符串的数组
- version 表示这个设备的版本信息
  - firmware 表示固件的版本信息，字符串格式
  - software 表示软件的版本信息，字符串格式
  - config 表示配置文件版本(最后更新时间)，字符串格式

应答消息

{
    "did": "001122334455",
    "type": "register",
    "result": {
        "id": "3434689jkjsdf34398095829",
        "expires": 3600,
        "token": "39409080928349028592"
    }
}

did 数据采集器设备 ID
type 消息类型，总是为 register
result 注册结果
- id 由服务端分配的 ID，暂时没有用到
- token 设备访问令牌
- expires 设备访问令牌有效时间，单位为秒

定位标签

{
    "did": "34dac140001d",
    "type": "stream",
    "stream": "tag",
    "data": [{
        "tid": "ff1122334455",
        "batteryLevel": 73,
        "firmwareVersion": "1.8",
        "rssi": -78,
        "at": 1574400909000
    }]
}

设备 - device

ID	NAME	TYPE	VALUE	NOTE
0	manufacturer	string	TDK	-
1	modelNumber	string	DT01	-
2	serialNumber	string	345000123	可选, `保留将来使用`
3	firmwareVersion	string	1.0	-
4	reboot	action	-	-
5	reset	action	-	可选, `保留将来使用`
6	powerSources	integer	0	0 表示 DC 供电
7	powerVoltage	integer	3800	3800 mV
10	memoryFree	integer	15	15KB
11	errorCode	integer	0	0 表示没有错误
13	currentTime	integer	1367491215	用于时间同步
14	UTCOffset	string	+02:00	用于时间同步
15	timezone	string	-	可选, 用于时间同步
17	deviceType	string	gateway	-
18	hardwareVersion	string	1.0	-
20	batteryStatus	integer	0~6	可选, `保留将来使用`
21	memoryTotal	integer	256	256KB

电源类型

0 DC 供电
1 内部电池
2 外部电池
4 PoE 供电
5 USB 供电
6 AC 供电
7 太阳能供电

错误码

没有错误
低电量
外部电源关闭
定位模式失败
信号强度低
内存不足
短信异常
IP 连接异常
外围设备异常

read - 读取设备信息

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "data": {
        "device": {
            "read": {}
        }
    }
}

应答消息:

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "result": {
        "device": {
            "read": {
                "manufacturer": "TDK",
                "modelNumber": "DT01",
                "currentTime": 123403434353,
                "firmwareVersion": "1.0"
            }
        }
    }
}

write - 修改系统时间

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "data": {
        "device": {
            "write": {
                "currentTime": 123403434353
            }
        }
    }
}

应答消息:

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "result": {
        "device": {
            "write": {
                "code": 0
            }
        }
    }
}

reboot - 设备重启

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "data": {
        "device": {
            "reboot": {
                "delay": 1
            }
        }
    }
}

data 操作数据
- device 设备管理接口
  - reboot 重启操作
    - delay 延时重启时间，单位为秒

应答消息:

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "token": "39409080928349028592",
    "result": {
        "device": {
            "reboot": {
                "code": 0
            }
        }
    }
}

固件 - firmware

ID	NAME	TYPE	VALUE	NOTE
1	uri	string	http://test.com/test.bin	可写, 固件文件下载地址
2	update	action	-	-
3	state	integer	0	0 表示空闲状态
5	result	integer	0	0 表示初始状态
7	version	string	1.0	可写, 版本 1.0
8	protocol	integer	2	2 表示 HTTP 协议
9	delivery	integer	0	0 表示只支持拉取模式
11	md5sum	string	-	可写, md5 摘要

update - 升级操作

升级请求:

{
    "did": "001122334455",
    "mid": "123456789",
    "type": "action",
    "data": {
        "firmware": {
            "update": {
                "uri": "http://{domain-name}/v2/device/firmware/file?did=1123945343439",
                "md5sum": "11223344556677889900aabbccddeeff",
                "version": "3.0"
            }
        }
    }
}

请求应答:

{
    "did": "001122334455",
    "mid": "123456789",
    "type": "action",
    "result": {
        "firmware": {
            "update": {
                "code": 0
            }
        }
    }
}

read - 读取固件状态

读取请求:

{
    "did": "001122334455",
    "mid": "123456789",
    "type": "action",
    "data": {
        "firmware": {
            "read": {}
        }
    }
}

请求应答:

{
    "did": "001122334455",
    "mid": "123456789",
    "type": "action",
    "result": {
        "firmware": {
            "read": {
                "state": 0,
                "result": 0,
                "protocol": 0,
                "delivery": 0,
                "uri": "http://{domain-name}/v2/device/firmware/file?did=1123945343439",
                "md5sum": "11223344556677889900aabbccddeeff",
                "version": "3.0"
            }
        }
    }
}

下载升级文件

HTTP 协议:

GET http://{domain-name}/v2/device/firmware/file?did=1123945343439

固件文件暂存在内存或 Flash
下载完后需验证 md5 值

CoAP 协议:

GET coap://{domain-name}:8952/firmware?did=1123945343439

以块传输方式下载固件文件

固件文件暂存在内存或 Flash
下载完后需验证 md5 值

固件升级事件

升级状态事件

{
    "did": "001122334455",
    "type": "event",
    "token": "34242523454639",
    "data": {
        "firmware": {
            "state": 0,
            "result": 0
        }
    }
}

配置 - config

串口配置

uarts
- 0 ~ 2 串口设备

NAME	CODE	TYPE	DEFAULT	NOTE
device	n	integer	1	串口设备地址, 0 ~ 2
baudrate	b	integer	9600	串口波特率
databits	d	integer	8	串口数据位
parity	p	integer	0	串口校验方式
stopbits	s	integer	1	串口停止位

例如:

{
    uarts: {
        1: {
            baudrate: 9600,
            parity: 0,
            databits: 8,
            stopbits: 1
        }
    }
}

子设备绑定

网络摄像机

camera 网络摄像机，通过以太网通信
- did 摄像机 ID 或 MAC 地址
- protocol 访问协议
  - onvif Onvif 协议网络摄像机
- address 摄像机 IP 地址
- username 访问用户名
- password 访问密码
- secret 设备注册密钥

蓝牙设备

bluetooth 不可连接蓝牙 Beacon, 仅接收蓝牙广播数据
- did 蓝牙从机 MAC 地址
- protocol 访问协议
  - beaconice BeacoNice Beacon 协议
  - bn5001 BeacoNice BN5001 通信协议
- password 访问密码/密钥

Modbus 设备

modbus Modbus 从机设备，通过 RS485 连接
- did Modbus 从机设备 ID
- secret 设备注册密钥
- address 从机地址

串口设备

uart 串口从机设备，通过 RS232/TTL 连接
- did 串口从机设备 ID
- secret 设备注册密钥

RS485 设备

rs485 RS485 从机设备，通过 RS485 连接
- did RS485 从机设备 ID
- secret 设备注册密钥
- address RS485 从机地址

开关量设备

gpio GPIO 从机设备，通过开关量线连接
- did GPIO 从机设备 ID
- secret 设备注册密钥
- address GPIO 从机地址码

Webhook 设备

webhook Webhook 从机设备，通过 HTTP 协议连接
- did Webhook 从机设备 ID
- secret 设备注册密钥
- address Webhook 路径地址

LoRA 设备

lora LoRA 从机设备
- did LoRA 从机设备 ID
- protocol 访问协议
  - modbus 基于 LoRA 的 Modbus 协议
- address 从机地址
- username 配对编码
- password 配对密钥

read - 读取参数

请求消息:

{
    "did": "aa1234567891",
    "mid": "1234",
    "type": "action",
    "data": {
        "config": {
            "read": {}
        }
    }
}

应答消息:

{
    "did": "aa1234567891",
    "mid": "1234",
    "type": "action",
    "result": {
        "config": {
            "read": {
                "camera": [
                    {
                        "did": "aa1234567890",
                        "host": "192.168.1.64",
                        "username": "admin",
                        "password": "admin"
                    }
                ],
                "bluetooth": [
                    {
                        "did": "aa1234567890"
                    }
                ],
                "modbus": [
                    {
                        "did": "aa1234567890"
                    }
                ],
                "updated": 0
            }
        }
    }
}

write - 修改参数

请求消息:

{
    "did": "aa1234567891",
    "mid": "1234",
    "type": "action",
    "data": {
        "config": {
            "write": {
                "camera": [
                    {
                        "did": "aa1234567890",
                        "host": "192.168.1.64",
                        "username": "admin",
                        "password": "admin"
                    }
                ],
                "bluetooth": [
                    {
                        "did": "aa1234567890"
                    }
                ],
                "modbus": [
                    {
                        "did": "aa1234567890"
                    }
                ],
                "updated": 0
            }
        }
    }
}

应答消息

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "result": {
        "config": {
            "write": {
                "code": 0
            }
        }
    }
}

从机 - peripheral

配置

read - 读取参数

请求消息:

{
    "did": "aa1234567891",
    "mid": "1234",
    "type": "action",
    "data": {
        "peripheral": {
            "read": {
                "did": "bb1234567891",
                "config": {}
            }
        }
    }
}

应答消息:

{
    "did": "aa1234567891",
    "mid": "1234",
    "type": "action",
    "result": {
        "peripheral": {
            "read": {
                "did": "bb1234567891",
                "config": {
                    ...
                }
            }
        }
    }
}

write - 修改参数

请求消息:

{
    "did": "aa1234567891",
    "mid": "1234",
    "type": "action",
    "data": {
        "peripheral": {
            "write": {
                "did": "bb1234567891",
                "config": {
                    ...
                }
            }
        }
    }
}

应答消息:

{
    "did": "aa1234567891",
    "mid": "1234",
    "type": "action",
    "result": {
        "peripheral": {
            "write": {
                "did": "bb1234567891",
                "code": 0
            }
        }
    }
}

标准 Modbus 设备

支持 Modbus/485 协议的外围设备

通信协议: Modbus
消息最大长度: 约 200 字节

主要遥测服务

ID	NAME	FULL NAME	NOTE
3	device	Device	可选
8	config	Parameter Configuration	必须

错误码

CODE	NAME	NOTE
18001	串口打开失败	串口设置错误或发生异常
18002	连接超时	从机未连接，错误的地址，通信异常等
18003	不支持的操作码	使用了从机不支持的操作码
9	无效的配置参数	错误的配置参数

设备注册

{
    "did": "001122334455",
    "type": "register",
    "sign": "471332d2e16f524d377224cda1573c86:md5",
    "data": {
        "gateway": "aa1122334455",
        "version": {
            "firmware": "1.0",
        }
    }
}

did 数据采集器设备 ID (MAC 地址)
type 消息类型，总是为 register
sign 设备签名
data 设备描述信息
- gateway 表示这个设备绑定的网关
- version 表示这个设备的版本信息
  - firmware 表示固件的版本信息，字符串格式

配置 - config

Modbus 配置参数

NAME	CODE	TYPE	NOTE
actions	a	object	绑定的操作列表
events	e	object	绑定的事件列表
forms	f	object	串口配置
properties	p	object	绑定的属性列表
updated	u	integer	配置参数最后更新时间

串口配置

NAME	CODE	TYPE	DEFAULT	NOTE
address	a	integer	0	Modbus 从机地址, 1 ~ 247
device	n	string	-	串口设备地址, 0 ~ 2
interval	i	integer	60	采集间隔，单位为秒
mode	m	integer	0	Modbus 传输模式
timeout	t	integer	500	读写超时时间，单位为毫秒

interval (i) 采集间隔, 默认为 60 秒
mode (m) 传输模式 (0-RTU, 1-ASCII, 2-TCP, 3-LoRA), 默认为 0-RTU
timeout (t) 超时时间, 默认为 500 毫秒

属性配置

事物属性 Modbus 协议配置参数

NAME	CODE	TYPE	DEFAULT	NOTE
address	a	integer	0	从机地址, 1 ~ 247
code	c	integer	0x03	Modbus 操作码, 0x00~0xFF
decimals	x	integer	0	要保留的小数位, 默认保留所有小数位
flags	f	integer	0	字节顺序标志位
interval	i	integer	60	采集间隔，单位为秒
offset	o	number	0	偏移值
quantity	q	integer	1	寄存器个数, 1 ~ 125 (0x7D)
register	r	integer	0	寄存器地址, 0x0000~0xFFFF
scale	s	number	1	缩放因子
timeout	t	integer	500	读写超时时间，单位为毫秒
type	y	integer	0	原始数据类型

code (c) Modbus 的功能码, 默认为 0x03, 具体如下：
- 0x01（读线圈）
- 0x02（读离散输入）
- 0x03（读保持寄存器）
- 0x04（读输入寄存器）
flags (f) 字节顺序标识, 默认为大端模式
- bit0: 高低位顺序，
- bit1: 多寄存器顺序
type (y) 数据类型，默认为有符号整数类型
- 0 有符号整数
- 1 无符号整数
- 2 浮点类型
- 3 字符串类型
- 4 布尔类型
- 5 原始数据类型

操作配置

事物操作 Modbus 协议配置参数

NAME	CODE	TYPE	DEFAULT	NOTE
address	a	integer	0	从机地址, 1 ~ 247
code	c	integer	0x06	Modbus 操作码, 0x00~0xFF
flags	f	integer	0	字节顺序标志位
offset	o	number	0	偏移值
quantity	q	integer	1	寄存器个数, 1 ~ 125 (0x7D)
register	r	integer	0	寄存器地址, 0x0000~0xFFFF
scale	s	number	1	缩放因子
timeout	t	integer	500	读写超时时间，单位为毫秒
type	y	integer	0	原始数据类型

操作参数基本同属性参数

code (c) Modbus 的功能码, 默认为 0x06, 具体如下：

0x05、0x0F（读、写线圈）
0x06、0x10（读、写保持寄存器）

数值转换

字节序标志位

Modbus 的寄存器地址和数值都长为 2 个字节，默认字节顺序为大端模式 Big-Endian, 即高字节在前.

当由多个寄存器表示一个数值时，默认寄存器顺序为大端模式 Big-Endian, 即高字节寄存器在前.

标志位:

寄存器值高低字节顺序: 0 高字节在前，1 低字节在前
多寄存器顺序: 0 高字节在前，1 低字节在前
综上所述，总共有 4 种字节排列方式

示例, 假如有一个数的值为 AB (2字节), ABCD (4字节), ABCDEFGH (8字节), 在不同字节序下排列方式如下:

FLAGS	BYTE ORDER	REGISGER ORDER	int16	int32	int64	float	double
0x00	0 高字节在前	0 高字节在前	AB	AB CD	AB CD EF GH	AB CD	AB CD EF GH
0x01	1	0 高字节在前	BA	BA DC	BA DC FE HG	BA DC	BA DC FE HG
0x02	0 高字节在前	1	AB	CD AB	GH EF CD AB	CD AB	GH EF CD AB
0x03	1	1	BA	DC BA	HG FE DC BA	DC BA	HG FE DC BA

数据类型

TYPE	RAW TYPE	VALUE	QUANTITY	MIN	MAX	NOTE
integer	int16	0	1	-32768	32767	有符号整数
integer	int32	0	2	-2147483648	2147483647	有符号整数
integer	int64	0	4	-	-	有符号整数
integer	uint16	1	1	0	65535	无符号整数
integer	uint32	1	2	0	4294967295	无符号整数
integer	uint64	1	4	0	-	无符号整数
number	float	2	2	-	-	浮点数
number	double	2	4	-	-	浮点数
string	string	3	N	-	-	字符串
boolean	bool	4	1	-	-	布尔型
base64 string	byte[]	5	N	-	-	原始数据类型

数据类型:

0: integer
1: integer (无符号)
2: number (浮点数)
3: string
4: boolean
5: base64 string 用 Base64 字符串编码的字节数组

数值换算

在寄存器中，数值可能不是以真实值保存，需要通过以下方式计算

数值型数据真实值计算方式:

real_value = (raw_value * scale) + offset

数值型数据原始值计算方式:

raw_value = (real_value - offset) / scale

示例

{
    "updated": 0,
    "forms": {
        "address": 10,
        "mode": 0,
        "interval": 60,
        "timeout": 500
    },
    "properties": {
        "activePower": {
            "s": 0.001,
            "f": 1,
            "r": 30
        },
        "reactivePower": {
            "s": 0.001,
            "r": 38
        },
        "phaseCurrentA": {
            "r": 16
        },
        "phaseVoltageA": {
            "r": 0
        },
        "phaseCurrentB": {
            "r": 18
        },
        "phaseVoltageB": {
            "r": 2
        },
        "phaseCurrentC": {
            "r": 20
        },
        "phaseVoltageC": {
            "r": 4
        },
        "powerFactor": {
            "r": 54
        }
    },
    "actions": {
        "run": {
            "r": 99
        }
    },
    "events": {

    }
}

write - 修改参数

请求消息

{
    "did": "aa1234567891",
    "mid": "1234",
    "type": "action",
    "data": {
        "config": {
            "write": {
                "updated": 0,
                "properties": {
                    "activePower": {
                        "s": 0.001,
                        "f": 1,
                        "r": 30
                    },
                    ...
                },
                "forms": {
                    "address": 10,
                    "mode": 0,
                    "interval": 60,
                    "timeout": 500
                }
            }
        }
    }
}

did 数据采集器设备 ID
mid 请求消息的 ID
type 总是为 action
data 操作数据
- config 配置服务
  - write 要读取的配置参数

应答消息

{
    "did": "aa1234567891",
    "mid": "1234",
    "type": "action",
    "result": {
        "config": {
            "write": {
                "code": 0
            }
        }
    }
}

did 数据采集器设备 ID
mid 总是和请求消息的 mid 相同
type 总是为 action
result 操作结果
- config 配置服务
  - write
    - code 返回 0 表示执行成功

read - 读取参数

{
    "did": "aa1234567891",
    "mid": "1234",
    "type": "action",
    "data": {
        "config": {
            "read": []
        }
    }
}

did 数据采集器设备 ID
mid 请求消息的 ID
type 总是为 action
data 操作数据
- config 配置服务
  - read 要读取的配置参数

应答消息:

{
    "did": "aa1234567891",
    "mid": "1234",
    "type": "action",
    "result": {
        "config": {
            "read": {
                "updated": 0,
                "properties": {
                    "activePower": {
                        "s": 0.001,
                        "f": 1,
                        "r": 30
                    },
                    ...
                },
                "forms": {
                    "address": 10,
                    "mode": 0,
                    "interval": 60,
                    "timeout": 500
                }
            }
        }
    }
}

did 数据采集器设备 ID
mid 总是和请求消息的 mid 相同
type 总是为 action
result 操作结果
- config 配置服务
  - read 返回配置参数内容

蓝牙传感器

通过蓝牙通信的外围设备

蓝牙广播通信
蓝牙连接双向通信
最大消息长度不超过 200 字节

主要遥测服务

ID	NAME	FULL NAME	NOTE
3	device	Device	必须
4	connectivity	Connectivity Monitoring	-
5	firmware	Firmware Update	-
6	location	Location	-
7	statistics	Connectivity Statistics	-
8	config	Parameter Configuration	必须

错误码

CODE	NAME	NOTE
18001	串口打开失败	串口设置错误或发生异常
18002	连接超时	从机未连接，错误的地址，通信异常等
18003	不支持的操作码	使用了从机不支持的操作码
9	无效的配置参数	错误的配置参数

设备注册

{
    "did": "001122334455",
    "type": "register",
    "sign": "471332d2e16f524d377224cda1573c86:md5",
    "data": {
        "gateway": "aa1122334455",
        "version": {
            "firmware": "1.0",
        }
    }
}

did 数据采集器设备 ID (MAC 地址)
type 消息类型，总是为 register
sign 设备签名
data 设备描述信息
- gateway 表示这个设备绑定的网关
- version 表示这个设备的版本信息
  - firmware 表示固件的版本信息，字符串格式

公共服务

设备 - device

ID	NAME	TYPE	VALUE	NOTE
0	manufacturer	string	SAE	从从机读取
1	modelNumber	string	BN5001	从从机读取
2	serialNumber	string	345000123	从从机读取
3	firmwareVersion	string	1.0	从从机读取
4	reboot	action	-	-
5	reset	action	-	可选, `保留将来使用`
6	powerSources	integer	0	1 表示内置电池
7	powerVoltage	integer	3800	从从机读取, 3800 mV
11	errorCode	integer	0	0 表示没有错误
17	deviceType	string	sensor	从从机读取, 设备名称
18	hardwareVersion	string	1.0	从从机读取
20	batteryStatus	integer	0~6	可选, `保留将来使用`

read 读取信息

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "data": {
        "device": {
            "read": {}
        }
    }
}

应答消息:

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "result": {
        "device": {
            "read": {
                "manufacturer": "TDK",
                "modelNumber": "BN5001",
                "currentTime": 123403434353,
                "firmwareVersion": "1.0"
            }
        }
    }
}

固件 - firmware

ID	NAME	TYPE	VALUE	NOTE
1	uri	string	http://test.com/test.bin	固件文件下载地址
2	update	action	-	-
3	state	integer	0	0 表示空闲状态
5	result	integer	0	0 表示初始状态
7	version	string	1.0	版本 1.0
8	protocol	integer	0	0 表示 CoAP 协议
9	delivery	integer	0	0 表示只支持拉取模式

state 更新状态

0：空闲状态
1：正在下载
2：完成下载
3：正在更新

result 更新结果

0：初始状态
1：固件更新成功
2：没有足够的 Flash 空间
3：没有足够的内存空间
4：下载过程中连接断开
5：固件验证失败
6：不支持的固件类型
7：无效的 URI
8：固件更新失败
9：不支持的通信协议

update - 升级操作

升级请求:

{
    "did": "001122334455",
    "mid": "123456789",
    "type": "action",
    "data": {
        "firmware": {
            "update": {
                "uri": "http://{domain-name}/v2/device/firmware/file?did=1123945343439",
                "md5sum": "11223344556677889900aabbccddeeff",
                "version": "3.0"
            }
        }
    }
}

请求应答:

{
    "did": "001122334455",
    "mid": "123456789",
    "type": "action",
    "result": {
        "firmware": {
            "update": {
                "code": 0
            }
        }
    }
}

配置 - config

配置参数为二进制数据格式

read - 读取参数

{
    "did": "aa1234567890",
    "mid": "1234",
    "type": "action",
    "data": {
        "config": {
            "read": {}
        }
    }
}

应答消息

{
    "did": "aa1234567890",
    "mid": "1234",
    "type": "action",
    "result": {
        "config": {
            "read": {
                "version": 0,
                "raw": "<base64 string>"
            }
        }
    }
}

write - 修改参数

{
    "did": "aa1234567890",
    "mid": "1234",
    "type": "action",
    "data": {
        "config": {
            "write": {
                "version": 0,
                "raw": "<base64 string>"
            }
        }
    }
}

应答消息

{
    "did": "aa1234567890",
    "mid": "1234",
    "type": "action",
    "result": {
        "config": {
            "write": {
                "code": 0
            }
        }
    }
}

BN5001 振动传感器

BN5001A 振动传感器

产品类型: VibrationSensor
接入协议: bluetooth

数据上报

{
    "did": "aa0001000402",
    "type": "stream",
    "data": {
        "rssi": -80,
        "powerVoltage": 1800,
        "sampleRate": 2000,
        "sampleMode": 512,
        "axis": 1,
        "spectral": "<base64 string>"
    }
}

did 设备的 ID
type 消息类型，总是为 'stream'
telemetry 设备遥测信息
- rssi 蓝牙接收信号强度，单位为 dBm
- powerVoltage 电源电压，单位为 mV
data 数据内容
- sampleRate 表示采样率, 单位为 Hz
- sampleMode 表示数据计算模式, 512 表示通过 FFT 换算成 512 个频点
- axis 表示轴的 ID, 1 表示 x 轴, 2 表示 y 轴, 4 表示 z 轴, 8 表示所有轴
- spectral 表示指定轴的加速度频谱数据，以 Base64 编码，原始数据为 16 位无符号整数数组, 单位为 1/1000 G (mG)。

BN5001B 振动传感器

产品类型: VibrationSensor
接入协议: bluetooth
仅蓝牙传输
最大数据包大小 200 字节

数据上报

{
    "did": "aa0001000402",
    "type": "stream",
    "data": {        
        "rssi": -80,
        "powerVoltage": 1800,
        "sampleRate": 2000,
        "sampleMode": 512,
        "axis": 1,
        "spectral": "<base64 string>"
    }
}

did 设备的 ID

BN5001C 振动传感器

产品类型: VibrationSensor
接入协议: nbiot
NB-IoT 传输
最大数据包大小 1000 字节

数据上报

{
    "did": "aa0001000402",
    "type": "stream",
    "data": {         
        "rssi": -80,
        "powerVoltage": 1800,
        "sampleRate": 1600,
        "frequency": 408,
        "acceleration": 1.89,
        "vibration": "<base64 string>"
    }
}

did 设备的 ID
type 消息类型，总是为 'stream'
data 数据内容
- sampleRate 表示采样率, 单位为 Hz
- frequency 振动频率, 单位为 Hz
- acceleration 当前振动加速度, 单位为 G
- vibration 当前振动频谱，以 Base64 编码，原始数据为 16 位无符号整数数组, 单位为 1/1000 G (mG)。

振动频谱

数据表示如下，每项都为 16 位无符号整数，采用小端模式（低字节在前)

Index	Note
1	频谱类型，总是为 'V'
2	采样率, 单位为 Hz
3	分辨率，如 512
4	表示轴的 ID, 1 表示 x 轴, 2 表示 y 轴, 4 表示 z 轴, 8 表示所有轴
5	振动频率, 单位为 Hz
6	振动加速度, 单位为 1/1000 G (mG)。
7	振动频率, 单位为 Hz
8	振动加速度, 单位为 1/1000 G (mG)。
9	...

注意振动频率/振动加速度按加速度大小，从大到小排列

BN5002 振动传感器

数据上报格式

BN5003 温湿度传感器

数据上报格式

{
    "did": "aabbcc112233",
    "type": "stream",
    "data": {
        "temperature": 25,
        "humidity": 60,
        "pressure": 1006.3
    }
}

以上表示温度为 25 摄氏度，相对湿度 60%, 大气压 1006.3 hPa

telemetry 设备遥测信息
- rssi 蓝牙接收信号强度，单位为 dBm
- powerVoltage 电源电压，单位为 mV

BN1005 光能温湿度传感器

同 BN5003

BN5005A 门磁传感器

数据上报格式

{
    "did": "001122334455",
    "type": "stream",
    "data": {
        "open": true
    }
}

open 表示开关状态

BN5005B 水浸传感器

数据上报格式

{
    "did": "001122334455",
    "type": "stream",
    "data": {
        "alarm": true,
    }
}

alarm 表示告警状态

BN5005C Modbus 蓝牙采集器

请参考 Modbus 设备一节

BN5006 气体传感器

数据上报格式

{
    "did": "aabbcc112233",
    "type": "stream",
    "data": {
        "ch2o": 100,
        "co2": 100,
        "nh3": 100,
        "h2s": 100,
        "co": 100,
        "o3": 100,
        "no2": 100,
        "so2": 100,
        "pm25": 100,
        "pm10": 100
    }
}

LoRA 传感器

基于 LoRA 通信的传感器节点

点到点通信
通过 LoRA 网关接入物联网
通信协议: LoRA 点到点 + Modbus
数据格式: Modbus

主要遥测服务

请参考 Modbus 设备

错误码

CODE	NAME	NOTE
18001	串口打开失败	串口设置错误或发生异常
18002	连接超时	从机未连接，错误的地址，通信异常等
18003	不支持的操作码	使用了从机不支持的操作码
9	无效的配置参数	错误的配置参数

ONVIF 摄像机

通用监控摄像机

通过以太网通信
通信协议: ONVIF/RTSP/RTMP
数据格式: JSON/H.264

主要遥测服务

ID	NAME	FULL NAME	NOTE
3	device	Device	必须
4	connectivity	Connectivity Monitoring	-
5	firmware	Firmware Update	必须
6	location	Location	-
7	statistics	Connectivity Statistics	-
8	config	Parameter Configuration	必须
10	ptz	PTZ	-
11	preset	Preset	可选

错误码

CODE	NAME	NOTE
18001	串口打开失败	串口设置错误或发生异常
18002	连接超时	从机未连接，错误的地址，通信异常等
18003	不支持的操作码	使用了从机不支持的操作码
9	无效的配置参数	错误的配置参数

设备注册

{
    "did": "001122334455",
    "type": "register",
    "sign": "471332d2e16f524d377224cda1573c86:md5",
    "data": {
        "gateway": "aa1122334455",
        "version": {
            "firmware": "1.0",
        }
    }
}

did 数据采集器设备 ID (MAC 地址)
type 消息类型，总是为 register
sign 设备签名
data 设备描述信息
- gateway 表示这个设备绑定的网关
- version 表示这个设备的版本信息
  - firmware 表示固件的版本信息，字符串格式

设备 - device

ID	NAME	TYPE	VALUE	NOTE
0	manufacturer	string	HIKVISION	-
1	modelNumber	string	XXXX	-
2	serialNumber	string	345000123	可选, `保留将来使用`
3	firmwareVersion	string	1.0	-
4	reboot	action	-	-
6	powerSources	integer	0	0 表示 DC 供电
7	powerVoltage	integer	3800	3800 mV
10	memoryFree	integer	15	15KB
11	errorCode	integer	0	0 表示没有错误
17	deviceType	string	camera	-
18	hardwareVersion	string	1.0	-
21	memoryTotal	integer	256	256KB

配置 - config

播放 - play

开始播放

{
    "did": "001122334455",
    "mid": "1234",
    "token": "play-token",
    "type": "action",
    "data": {
        "play": {
            "url": String,
            "players": Number
        }
    }
}

did 设备 ID
mid 消息 ID
type 消息类型，总是为 action
data 操作数据
- play 播放操作
  - url 推流地址, 如 rtmp://{domain-name}/live/001122334455，摄像机需要推流到这个地址
  - players 当前正在播放的客户端数量，摄像机不需要关心这个值，且不管有多个少客户端同时播放都只需要上传一支流

停止播放

{
    "did": "001122334455",
    "mid": "1234",
    "token": "play-token",
    "type": "action",
    "data": {
        "stop": {
            "reason": "It's all play done"
        }
    }
}

did 设备 ID
mid 消息 ID
type 消息类型，总是为 action
data 操作数据
- stop 停止播放操作
  - reason 建议提供，表示停止推流的原因

云台 - ptz

start 转动去台
stop 停止转动

开始转动

通过这个命令可以控制摄像机镜头上下左右摆动，或者放大缩小

{
    "did": "001122334455",
    "mid": "1234",
    "token": "ptz-token",
    "type": "action",
    "data": {
        "ptz": {
            "start": {
                "direction": Number,
                "speed": Number
            }
        }
    }
}

did 设备 ID
mid 消息 ID
type 消息类型，总是为 action
data 操作数据
- ptz 云台操作
  - method 云台操作方法, 总是为 start
  - direction 方向
    - 0 上
    - 1 下
    - 2 左
    - 3 右
    - 4 左上
    - 5 左下
    - 6 右上
    - 7 右下
    - 8 放大
    - 9 缩小
  - speed 云台速度:
    - 0 慢
    - 1 适中
    - 2 快

应答消息:

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "result": {
        "ptz": {
            "code": 0
        }
    }
}

停止转动

通过这个命令可以控制摄像机镜头停止摆动或缩放，就算摄像机没有成功收到这个命令，也需要在超过一定时间后自动停止摆动或缩放 (巡航等模式除外)

由流媒体服务器发送给设备:

{
    "did": "001122334455",
    "mid": "1234",
    "token": "ptz-token",
    "type": "action",
    "data": {
        "ptz": {
            "stop": {}
        }
    }
}

did 设备 ID
mid 消息 ID
type 消息类型，总是为 action
data 操作数据
- ptz 云台操作
  - method 云台操作方法, 总是为 stop

应答消息:

{
    "did": "001122334455",
    "mid": "1234",
    "token": "ptz-token",
    "type": "action",
    "result": {
        "ptz": {
            "code": 0
        }
    }
}

错误应答消息

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "result": {
        "ptz": {
            "code": Number,
            "error": String
        }
    }
}

did 必需, 设备 ID
mid 必需, 消息 ID
type 必需, 消息类型，总是为 action
result 操作结果
- ptz 云台操作
  - code 必需, 错误码
  - error 必需, 错误类型

错误码:

CODE	ERROR
60000	该设备不支持云台控制
60001	没有云台控制权限
60002	设备云台旋转达到上限位
60003	设备云台旋转达到下限位
60004	设备云台旋转达到左限位
60005	设备云台旋转达到右限位
60006	云台当前操作失败，请稍后再试
60009	正在调用预置点
60020	不支持该命令

预置位 - preset

read 预置位列表
set 设置预置位
remove 删除预置位
goto 转到预置位

设置预置位

将当前云台位置设置为指定的预置位

由流媒体服务器发送给设备:

{
    "did": "001122334455",
    "mid": "1234",
    "token": "preset-token",
    "type": "action",
    "data": {
        "preset": {
            "set": {
                "index": 1,
                "name": "[name]"
            }
        }
    }
}

did 摄像机 ID
mid 消息 ID, 不同消息不可重复
type 总是为 action
data 操作数据
- preset 预置位操作
  - set 设置预置位操作
    - index 必需，预置位索引，1-128
    - name 可选，预置位显示名称

返回结果:

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "result": {
        "preset": {
            "code": 0
        }
    }
}

did 摄像机 ID
mid 消息 ID, 必须同请求消息一致
type 总是为 action
result 操作结果
- preset 预置位操作
  - code 操作结果，0 表示成功

查询预置位列表

查询摄像机已设置的预置位列表

由流媒体服务器发送给设备:

{
    "did": "001122334455",
    "mid": "1234",
    "token": "preset-token",
    "type": "action",
    "data": {
        "preset": {
            "list": {}
        }
    }
}

did 摄像机 ID
mid 消息 ID, 不同消息不可重复
type 总是为 action
data 操作数据
- preset 预置位操作
  - list 查询预置位列表

返回结果:

{
    "did": "001122334455",
    "mid": "1234",
    "token": "preset-token",
    "type": "action",
    "result": {
        "preset": {
            "presets": [{
                "index": 1,
                "name": "[name]"
            }]
        }
    }
}

did 摄像机 ID
mid 消息 ID, 必须同请求消息一致
type 总是为 action
result 操作结果
- preset 预置位操作
  - presets 预置位数组
    - index 预置位索引
    - name 预置位名称

调用预置位

转到指定的预置位

由流媒体服务器发送给设备:

{
    "did": "001122334455",
    "mid": "1234",
    "token": "preset-token",
    "type": "action",
    "data": {
        "preset": {
            "goto": {
                "index": Number
            }
        }
    }
}

did 摄像机 ID
mid 消息 ID, 不同消息不可重复
type 总是为 action
data 操作数据
- preset 预置位操作
  - goto
    - index 预置位索引，1-128

应答消息:

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "result": {
        "preset": {
            "code": 0
        }
    }
}

did 摄像机 ID
mid 消息 ID, 必须同请求消息一致
type 总是为 action
result 操作结果
- preset 预置位操作
  - code 操作结果 0 表示操作成功

删除预置位

删除指定的预置位

由流媒体服务器发送给设备:

{
    "did": "001122334455",
    "mid": "1234",
    "token": "preset-token",
    "type": "action",
    "data": {
        "preset": {
            "remove": {
                "index": Number
            }
        }
    }
}

did 摄像机 ID
mid 消息 ID, 不同消息不可重复
type 总是为 action
data 操作数据
- preset 预置位操作
  - remove
    - index 预置位索引，1-128

应答消息:

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "result": {
        "preset": {
            "code": 0
        }
    }
}

did 摄像机 ID
mid 消息 ID, 必须同请求消息一致
type 总是为 action
result 操作结果
- preset 预置位操作
  - code 操作结果 0 表示操作成功

错误应答消息

{
    "did": "001122334455",
    "mid": "1234",
    "type": "action",
    "result": {
        "{action}": {
            "code": Number,
            "error": String
        }
    }
}

did 必需, 设备 ID
mid 必需, 消息 ID
type 必需, 消息类型，总是为 action
result 操作结果
- action 操作名称
  - code 必需, 错误码
  - error 必需, 错误类型

错误码:

CODE	ERROR
60000	该设备不支持云台控制
60001	没有云台控制权限
60006	云台当前操作失败，请稍后再试
60009	正在调用预置点
60020	不支持该命令
60007	预置点个数超过最大值
60010	该预置点已经是当前位置
60011	预置点不存在