设备标准接入
接入准备
所有智能硬件产品在接入得力E+云平台之前,首先开发商都必须通过开发者平台注册成为开发者,然后创建对应的产品型号model
,完成产品配置,并获取接入平台的密钥信息product_key
。
产品型号和接入密钥是一一对应的关系,在后续该产品型号的设备接入认证过程中将作为产品私密信息与平台进行身份合法性校验,因此需要妥善保管,不要外泄。
注意,产品接入配置信息包含测试和生产两套环境,开发者在研发阶段应使用测试环境的接入配置进行平台对接开发工作。研发结束发布上线时,方可对接到平台生产环境。
更多关于产品定义和配置的具体信息,请访问开发者平台获取。
接入方式
接入得力E+云平台的设备类型主要分为三大类:
- 平台网关接入
- E+APP接入
- 独立APP接入
其中,各类型的接入说明如下:
平台网关接入
通过平台网关接入的设备都是可以直接连接互联网,并通过标准接入协议和平台长期保持连接的设备。该类设备通常都能够独立使用,且支持远程访问控制。常见的设备有考勤机、门禁机等。
目前平台设备网关支持通过MQTTS和HTTPS两种不同的应用协议接入。鉴于MQTT协议在物联网领域的低功耗以及在网络不稳定下的传输可靠性,默认推荐设备使用MQTTS协议。
接入地址如下:
接入环境 | 接入地址 |
---|---|
测试环境 | MQTT协议:tcp://s-device.delicloud.com:8883 ;HTTP协议: https://s-device.delicloud.com |
生产环境 | MQTT协议:tcp://device.delicloud.com:8883 ;HTTP协议: https://device.delicloud.com |
该类设备接入平台后,所有的消息通信都是通过设备与上述平台设备网关地址通信完成。
使用SSL如果发生错误,需要注意:
- 根证书 DigiCert-Global-Root-CA.cer
- 使用MQTT.fx模拟连接时,如果发现SSL相关的报错,需要在配置项里 enable SSL/TLS, 并设置 “CA certificate file” 为 DigiCert-Global-Root-CA.cer
- 自行编写mqtt客户端时,也要导入以上根证书。比如使用java语言,需要将根证书导入到java的证书库里
# 导入根证书到java认证库中 sudo keytool -import -alias delicloud -keystore $JAVA_HOME/jre/lib/security/cacerts -file ./DigiCert-Global-Root-CA.cer # 如果需要输入java认证库的密码,可以尝试 “changeit”
- 遇到其它关于ssl/tls的问题,请及时沟通。
E+APP接入
对于不具备独立联网能力的智能设备,推荐使用蓝牙等点对点连接方式与得力E+APP通信接入平台。常见的设备有蓝牙签到机、蓝牙巡检机、蓝牙智能锁等等。
开发者可通过如下地址下载测试环境的APP进行接入调试(密码是123456):
- Android:
https://www.pgyer.com/smartoffice_v2_sandbox_android
- IOS:
https://www.pgyer.com/smartoffice_v2_sandbox_ios
由于IOS接入受限,推荐使用Android平台手机接入调试。
生产环境的得力E+APP,请直接访问官网下载。
独立APP接入
该类设备因为业务场景比较特殊,一般不具备直接联网能力且需要使用独立的APP进行管理。常见的设备有蓝牙便签打印机、智能摄像头等等。
这一类的设备使用完全自定义的通信协议接入应用APP,并通过应用服务器与平台应用网关对接的方式实现E+云平台的接入。
接入流程
一台智能设备在接入平台时,需要经过设备发现、网络配置、接入认证这三步后方可通过E+平台/APP进行业务通信。其中,网络配置主要是针对联网接入平台网关的设备。
st=>start: 开始
e=>end: 结束
sub0=>subroutine: 设备发现:>./#device_discovery
sub1=>subroutine: 网络配置:>./#network_config
sub2=>subroutine: 接入认证:>./#device_verify
cond=>condition: 网关设备?
st(right)->sub0(right)->cond(right)
cond(yes)->sub1(right)->sub2(right)->e
cond(no)->sub2(right)
设备发现
每台设备都应该具有一个全局唯一的ID标示,并支持通过某种方式能够被E+平台或APP识别发现。平台建议每台设备的ID应该按照如下规则生成:{产品型号}_{唯一序列号}。例如产品3960C下的设备ID应该类似3960C_123456、3960C_123457......。设备ID不要超过64位。
需要特别注意的是,平台要求设备「唯一序列号」不允许包含除数字、字母以及连接字符(-)之外的其他特殊字符。
默认的设备发现方式是通过设备二维码,每台设备根据自己的设备ID生成唯一的二维码并附在设备上,例如通过自带屏幕动态生成、固定印刷在设备包装或者外壳等方式。
设备二维码的格式见这里,通过得力E+APP扫描该设备绑定二维码即可获取设备ID信息并进行后续操作。
对于无法生成设备二维码或者设备二维码中无法存储设备ID信息的设备,得力E+APP支持通过扫描特定的蓝牙或Wifi广播信号来发现设备,并通过与设备点对点通信获取设备ID信息,请访问APP设备标准交互协议获取详情。
网络配置
对于具备联网功能,且通过接入得力E+云平台设备网关进行业务通信的设备,在接入平台之前首先必须通过网络配置功能完成互联网的接入。
网络配置的方式有很多种,主要包括有线接入、设备自配网以及通过APP配网等三种方式。目前得力E+APP支持通过蓝牙、AP热点以及SmartConfig等多种方式完成设备配网,推荐设备使用蓝牙协议完成配网。
具体通过E+APP配网的实现请访问APP设备标准交互协议。
接入认证
所有智能设备在接入平台时都需要第一时间进行基本的安全认证才能完成接入。不同的连接方式,其设备接入认证方式也不同。
MQTT接入认证
对于采用MQTT协议接入云平台的设备,可直接使用协议自带的接入认证方式完成认证即可,认证通过即可保持长连接与平台进行通信。
目前平台支持的MQTT协议版本是3.1.1。
其中认证需要的基础信息说明如下:
接入参数 | 描述 |
---|---|
ClientID | 设备ID,格式:{产品型号}_{唯一序列号},需要具备全局唯一性。另外平台要求设备「唯一序列号」不允许包含除数字、字母以及连接字符(-)之外的其他特殊字符 |
UserName | 产品型号 |
Password | MD5(设备ID + "-" + {产品型号} + "-" + {产品密钥}) |
- 设置
Keep Alive
为30s~60s; - 设置
Clean Session
为true; - 掉线重连: 如果因为各种原因造成设备与平台断开连接,设备需要在网络恢复时第一时间连接上平台。设备应定时尝试连接,直到重新接入平台并订阅成功为止,间隔时间建议控制在1s~5s。
HTTP接入认证
对于采用HTTP协议接入云平台的设备,可通过/api/connect/{ClientID}请求完成连接认证。请求示例如下:
POST /api/connect/{clientId}
Headers:
"Content-Type: application/json"
Body:
{
"clientId": "3T2PL_1323E322", // 格式:**{产品型号}_{厂商设备唯一编码}**,需要具备全局唯一性
"userName": "产品型号", // 产品型号
"password": "MD5生成的密码" // MD5({clientId} + "-" + {产品型号} + "-" + {产品密钥})
"keepAliveTime": 30 // (单位: 秒) 对应MQTT协议的KeepAliveTime设置
}
其中认证的信息内容与MQTT协议认证内容完全一致。
认证通过后,HTTP设备网关会同步返回认证结果信息。 如果认证通过,则返回http状态码200并在HTTP头部携带授权信息Authorization
,后续设备所有的http请求都需要在头部携带该Authorization信息。响应示例如下:
HTTP/1.1 200
Headers:
"Authorization: DELI.eyJ0KV1...iJ9.eyJjbGll...wNH0.gh0ia8c1..Di07o3o"
"Content-Length: 0"
"Date: Wed, 11 Jul 2018 09:45:44 GMT"
如果认证失败,则返回406,后续任意api如果返回406都是认证失败,需要重新发起连接。响应结果如下:
HTTP/1.1 406
Content-Length: 0
Date: Wed, 11 Jul 2018 09:45:44 GMT
如果HTTP接入设备主动离线,应调用/api/disconnect/{clientId}接口通知平台设备离线,离线后设备连接时获得的授权信息将自动失效。请求示例如下:
GET /api/disconnect/{ClientID}
Headers:
"Authorization: DELI.eyJ0KV1...iJ9.eyJjbGll...wNH0.gh0ia8c1..Di07o3o"
"Connection: close"
注意,除了主动离线请求外,如果平台检测到多个心跳周期内没有收到设备的http请求,那么设备授权信息同样会自动失效。
E+APP接入认证
对于通过E+APP点对点连接的设备,请实现APP设备标准交互协议对应章节完成设备认证。
消息通信
一旦完成设备接入认证,设备即可通过认证时使用的连接通道进行后续的业务通信。根据接入方式不同,其发送和接收业务消息的流程略有不同,说明如下:
网关接入设备
所有网关接入设备都是通过互联网连接平台设备网关完成业务通信。具体通信消息协议设计请查看平台标准指令集。
MQTT协议通信
MQTT协议设备采用订阅-发布模型进行消息异步发送和接收处理。
设备->平台网关: device
平台网关->设备: $client/{ClientID}
- 消息接收
设备接入成功后,需要主动订阅以下主题,用于接收设备相关的消息:
主题 | QOS级别 | 是否必要 | 说明 |
---|---|---|---|
$client/{ClientID} | 0 | Y | 用于接收指定发送给该设备的消息,例如设备ID为3960C_123456的设备,应订阅主题$client/3960C_123456。 |
设备订阅成功后,即可根据MQTT协议接口规则接收异步消息响应。 注意,除以上主题外,设备不可以订阅其他主题,否则会被平台视为非法设备而强制踢出。
- 消息发送
如果设备需要向平台或应用发送消息,请固定发送到主题device,QOS级别默认设置为0即可。
HTTP协议通信
设备->平台网关: /api/pull/{clientId}
平台网关->设备: /api/push/{clientId}
- 消息接收
设备通过HTTP请求/api/pull/{clientId}向平台定时拉取发送给设备的缓存消息列表。拉取消息的频率与连接时设置的KeepAliveTime必须保持一致。
请求示例如下:
GET /api/pull/{clientId}?batchSize=10
Headers:
"Accept": "application/json"
"Content-Type": "application/json"
"Authorization: DELI.eyJ0KV1...iJ9.eyJjbGll...wNH0.gh0ia8c1..Di07o3o"
batchSize
是指本次拉取消息的最大条目数(可选参数),如果不提供,则默认为1,仅拉取1条。
平台会按照时间顺序将最早未读取的batchSize条设备缓存消息返回给设备,实际数量可能小于batchSize。如果HTTP请求成功,则返回HTTP状态码200,同时响应结果示例如下:
{
"code": 0,
"msg": "错误描述",
"size": 5,
"data" : [
{"mid":"232231", "from":"应用服务ID", "to":"设备ID", "action": 301, "data": {}},
{"mid":"232232", "from":"system", "to":"设备ID", "action": 203, "data": {}},
// ......
]
}
size
表示本次返回的消息总条数,data
表示返回的消息数组。
如果HTTP响应码为406则表示请求授权信息不正确或已过期,需要重新进行http连接认证。另外,如果HTTP响应码为200, 但是code
不为0,也视为接收消息失败。
- 消息发送
设备可通过HTTP请求/api/push/{clientId}主动向平台发送消息,平台设备网关会同步接收该HTTP请求,并根据接收消息的具体操作指令进行处理或转发。
请求示例如下:
POST /api/push/{clientId}
Headers:
"Accept": "application/json"
"Content-Type": "application/json"
"Authorization: DELI.eyJ0KV1...iJ9.eyJjbGll...wNH0.gh0ia8c1..Di07o3o"
Body:
{
"mid": "17232432412",
"from": "3986X_12344",
"to": "232432423",
"action": 300,
"time": 123456,
"data": {...}
}
如果HTTP请求成功,则返回HTTP状态码200,同时响应结果示例如下:
{
"code": 0, //错误码,0表示成功
"msg": "错误描述"
}
如果HTTP响应码为406则表示请求授权信息不正确或已过期,需要重新进行http连接认证。另外,如果HTTP响应码为200, 但是code
不为0,也视为发送消息失败。
APP接入设备
APP点对点直连设备通信,请访问APP设备标准交互协议查看详情。
调试工具
通用MQTT协议工具
得力云平台专用调试工具
对于通过设备网关接入的设备,为了便于设备开发商快速对接进行协议调试,我们在测试环境提供了设备调试工具。该工具支持对调试设备的日志监控、消息发送/接收控制等功能。
目前该工具仅支持通过MQTT协议接入的设备,接入地址如下:
tcp://s-devicedebug.delicloud.com:1883
除了接入地址不同外,其他接入信息与接入测试环境完全一致。
接入成功后,可通过控制台对设备消息进行日志监控和消息接收/发送管理。控制台地址如下:
http://s-debug.delicloud.com
访问后,在左侧设备菜单找到你正在调试的设备,点击选择即可进入设备调试界面,示例如下:
在设备调试界面会自动显示设备与平台之间的所有事件消息,包括连接、断开、主题订阅、心跳、发送消息和接收消息等。
请特别注意确认选择的设备SN与调试设备一致,如果选择错误,可以重新选择切换。
默认情况下,调试工具不会拦截所有设备发送和接收的消息,但调试人员可以通过顶部【自动收发消息】开关对其进行控制,一旦关闭该开关,所有设备相关的指令消息都会在调试器被拦截,不会自动发送。
此时,调试人员可以在操作列点击【编辑】按钮对消息进行编辑,然后通过点击底部【发送】按钮将消息发出。
另外,调试人员也可以通过点击右侧顶部【向设备发送消息】按钮,主动向设备发送自定义指令消息。
通过人为控制和改变设备的指令消息,可以模拟不同场景下的消息请求和响应,便于检查设备固件程序逻辑是否正确。
除此之外,调试器还提供了【强制设备下线】等更多辅助功能。