智能硬件协议文档

智能硬件协议文档

 
电子人云平台项目智能硬件接口协议
1.     简介
本节包括整个文档的概述。它包括此软件架构文档的目的、范围、定义、首字母缩写词、缩略语、参考资料和概述。
 
1.1 目的
本文档将给出第三方智能硬件在接入电子人云平台时需要遵循的接口协议。
 
1.2 范围
本文档适用于电子人云平台项目智能硬件接入应用场景。智能硬件研发以及软件开发小组的每一位参与开发人员都应该阅读本文档,以清楚平台在智能硬件接入时需要遵循的接口协议。
 
1.3 定义、首字母缩写词和缩略语
云企业帐号:厂商在电子人云平台云企业中心注册的帐号。
PROPERTY:设备属性。用于指示控制、检测项目,比如温度PROPERTY代码值指示温度的检测和控制。
安全通信算法:TEA(Tiny Encryption Algorithm)分组
加密算法,具体要求待加密数据如果低于8字节按照8字节对齐进行填充;如果待加密数据大于8字节,则按照4字节对齐填充。对填充内容不作要求。
接入密钥:厂商注册云企业帐号时分配的根密钥,用于生成当次连续通信过程中的随机密钥。
1.4 概述
本文档主要包括以下两个部分:数据类型定义、设备属性元数据、通信方式、协议报文、业务类型、业务报文。
 
2.     数据类型
以下定义了数据类型的名称、代码、中文名称、储存空间等信息。

数据类型 代码值 中文名称 存储空间 说明
BYTE 1 无符号字符 8位  
CHAR 2 字符 8位  
USHORT 3 无符号短整型 16位 网络字节序
SHORT 4 短整型 16位 网络字节序
UINT 5 无符号整型 32位 网络字节序
INT 6 整型 32位 网络字节序
STRING 7 字符串 变长 见2.1小节
VAR 8 不定数据类型 变长 见2.2小节
PROPERTYPAIR 9 PROPERTY键值对 变长 见2.4小节
 
2.1 STRING

字段 单位 长度 说明
字符串长度 USHORT 1 指示字符串数组长度
字符串数组 BYTE 字符串长度 零值字符结尾的UTF-8字节数组
 
2.2 VAR

字段 单位 长度 说明
数据类型代码 BYTE 1 见2小节中的代码值。代码值取值范围:BYTE、CHAR、USHORT、SHORT、UINT、INT、STRING。
数据类型值     由数据类型代码所指示的数据类型值
 
2.3 PROPERTYPAIR

字段 单位 长度 说明
PROPERTY UINT 1 关键指标代码
VALUE VAR 1  
 
3.     设备属性元数据
由电子人平台预定义,设备读取解析。
 
3.1 PROPERTY元数据
采用JSON格式表示,示例如下:
{     “id”: 1,
“name_cn”: “温度”,
“name_en”: “tempture”,
“type”   :  1,
“unit_cn”: “摄氏度”,
“unit_en”: “℃”,
“memo_cn”: “冷热程度的物理量”
“memo_en”: “physical quantities of heat and cold”
}

字段 类型 说明
id 无符号整型 属性代码值,比如温度的代码值是1。不允许重复。
name_cn 普通字符串 代码中文名称。
name_en 普通字符串 代码英文名称。
type 无符号整型 数据类型代码值,参考2小节,仅包括BYTE、CHAR、USHORT、SHORT、UINT、INT、STRING。
unit_cn 普通字符串 中文单位。
unit_en 普通字符串 英文单位。
memo_cn 普通字符串 中文说明或者描述。
memo_en 普通字符串 英文说明或者描述。
 
4.     通信方式
智能硬件与电子人云平台之间采用TCP长连接方式进行通信。
通信报文由协议报文与业务报文组成,如下图:

协议报文 业务报文
除登录及心跳以外的业务报文采用安全通信算法加密传输。
 
5.     协议报文

字段 数据类型 长度 说明
sensorId BYTE 8 智能硬件标识(64位无符号整型网络字节序数组)
cmdType BYTE 1 业务类型。
result BYTE 1 结果代码,值0正常。对于请求报文本字段无效。
payloadSize USHORT 1 负载长度,指示业务报文长度。
seqNo USHORT 1 智能硬件维护的流水号,每次请求自动加1。
version USHORT 1 版本号即本通信协议文档版本号,如2.02则为202。
 
6.     业务类型

业务类型 说明
登录 1 登录。
时间同步 2 时间同步。
心跳 3 智能硬件主动检查链路。
查询配置 4 智能硬件主动获取配置信息。
上报状态 5 智能硬件主动上报状态。
用户信息 6 智能硬件获取用户信息。
软件更新 7 智能硬件查询软件更新。
控制 8 平台主动控制智能硬件。
配置 9 平台主动配置智能硬件。
同步状态 10 智能硬件主动向平台请求同步状态。
 
7.     业务报文
7.1 登录
业务类型:1。
厂商首次注册为电子人云企业帐号,并申请成为开发者,云平台将自动为厂商生成智能硬件接入密钥。登录过程就是验证平台及硬件合法性,以及协商后续动态通信密钥的过程,过程中适用安全通信算法。首先,智能硬件生成16字节随机数,上传到平台,平台使用接入密钥将自己生成的动态通信密钥及智能硬件所生成的随机数加密后下发。智能硬件使用厂商接入密钥解密随机数以验证平台的合法性,同时解密获得后续动态通信密钥。
7.1.1  请求报文

字段 数据类型 长度 说明
id BYTE 8 云企业帐号,64位无符号整型网络字节序数组
type BYTE 8 智能硬件类型,64位无符号整型网络字节序数组
echo BYTE 16 智能硬件随机生成的16字节随机数。
 
7.1.2  响应报文

字段 数据类型 长度 说明
encode BYTE 16 使用厂商接入密钥加密echo后的密文。
key BYTE 16 使用厂商接入密钥加密后的动态通信密钥。
 
7.2 时间同步
业务类型:2。
描述:智能硬件主动获取平台时间,UTC标准时间。
7.2.1  请求报文

字段 数据类型 长度 说明
 
7.2.2  响应报文

字段 数据类型 长度 说明
year BYTE 2 BCD
month BYTE 1 12个月制式。BCD
day BYTE 1 30天制式。BCD
dayOfWeek BYTE 1 7天制式。BCD
hour BYTE 1 24小时制式。BCD
minute BYTE 1 60分钟制式。BCD
second BYTE 1 60秒制式。BCD
 
7.3 心跳
业务类型:3。
描述:智能硬件主动检查链路。每2分钟重复一次。
7.3.1  请求报文

字段 数据类型 长度 说明
 
7.3.2  响应报文

字段 数据类型 长度 说明
 
7.4 查询配置
业务类型:4。
描述:智能硬件主动获取所属类型的配置信息。
7.4.1  请求报文

字段 数据类型 长度 说明
 
7.4.2  响应报文

字段 数据类型 长度 说明
config STRING 1 配置信息。
 
7.5 上报状态
业务类型:5。
描述:智能硬件主动上报状态。
7.5.1  请求报文

字段 数据类型 长度 说明
info STRING 1 状态信息。没有填空字符串。
count USHORT 1 指示附加的PROPERTYPAIR值数目。
property PROPERTYPAIR count PROPERTY数据。
 
7.5.2  响应报文

字段 数据类型 长度 说明
timestamp BYTE 8 设备属性最新的时间戳。
 
7.6 用户信息
业务类型:6。
描述:智能硬件主动获取用户信息。
7.6.1  请求报文

字段 数据类型 长度 说明
type USHORT 1 用户信息类型,参见类型列表。
 
7.6.2  响应报文

字段 数据类型 长度 说明
info STRING 1 用户信息。
 
    类型列表:

Type 说明
1 手机。
 
7.7 软件更新
业务类型:7。
描述:智能硬件查询软件更新。
7.7.1  请求报文

字段 数据类型 长度 说明
version USHORT 1 智能硬件当前版本号。
 
7.7.2  响应报文

字段 数据类型 长度 说明
version USHORT 1 智能硬件新版本号。
url STRING 1 当前版本号小于新版本号,则出现新版本地址,否则为空字符串
 
7.8 控制
业务类型:8。
描述:平台主动控制智能硬件。
7.8.1  请求报文

字段 数据类型 长度 说明
count USHORT 1 指示附加的PROPERTYPAIR值数目。
property PROPERTYPAIR count PROPERTY数据。
 
7.8.2  响应报文
无效。智能硬件在受控后,通过上报状态进行回馈。
 
7.9 配置
业务类型:9。
描述:平台主动配置智能硬件。
7.9.1  请求报文

字段 数据类型 长度 说明
config STRING 1 配置信息。
 
7.9.2  响应报文
无效。智能硬件在配置后,通过上报状态进行回馈。
7.10    同步状态
业务类型:10。
描述:智能硬件主动上报状态。
7.10.1请求报文

字段 数据类型 长度 说明
timestamp BTYE 8 系统当前时间戳
 
7.10.2响应报文

字段 数据类型 长度 说明
count USHORT 1 PROPERTYPAIR值总数目。
property PROPERTYPAIR count PROPERTY数据。

重庆享控智能科技有限公司 地址:重庆市渝北区黄山大道中段66号中智联电子人物联网大厦 联系方式:023-62824888


Copyright © 2013-2018 电子人物联网版权所有 渝ICP备14000411号-3 渝公网备50011202300306

Power by DedeCms

咨询电话
023-62829292