设备云端通信协议¶
1. 文档说明¶
本文档作为云端4.x协议补充文档，主要用于定义4.x版本嵌入式提供的功能服务(action)。
文档主要分下行服务指令、上行服务指令两个部分，下行服务指令定义嵌入式提供给云端或APP调用的功能指令，上行服务指令定义嵌入式主动发起的功能指令，上行服务更详细的描述参考云端或者APP的协议文档。
1.1关键词说明¶
devTid : 设备唯一识别码，用于标识区分设备。
ctrlKey : 设备控制码，用于鉴别是否有权限操作。
必选参数 : 表示该参数必填，即该参数key不可省略，value可以留空。
可选参数 : 表示该参数key可以省略。
1.2协议基本格式¶
指令帧基本格式
{
"msgId" : 291, //消息id，应答帧须保持一致
"action" : "action", //消息指令
"params" : { //指令参数，可选参数
}
}
应答帧基本格式
{
"msgId" : 291,//消息id，与指令帧保持一致
"action" : "actionResp",//应答action字段值为"指令+Resp"
"code" : 200, //应答结果码
"desc" : "success", //应答描述
"params" : {//应答帧返回参数，可选参数
}
}
2. 下行服务指令¶
下行服务定义嵌入式提供给云端或APP调用的功能，包括appSend、setToken、devSync、devUpgrade、getPinCode, appGroupSend等
2.1 appSend¶
该指令用于接收 APP发送数据到设备的数据，并根据工作模式处理数据内容，透传模式下data.raw数组内容会被从ASC转化成HEX并通过出串口发送。主控模式下根据K-V定义处理数据。 指令格式：
{
"msgId" : 291,
"action" : "appSend",
"params" : {
"devTid" : "ESP_245EC89", // 接收数据的设备唯一id
"appTid" : "358974675345", // 发送数据的APP唯一id
"ctrlKey" : "123456789ABCDE", // 设备控制码
"data" : {
"raw" : "480E02010201000000000000005C" // 透传数据内容（48透传协议）
}
}
}
应答格式：
{
"msgId" : 291,
"action" : "appSendResp",
"code" : 200,
"desc" : "success",
"params" : {
"devTid" : "ESP_245EC89",
"appTid" : "345887867637",
"ctrlKey" : "123456789ABCDE",
"data" : {
"raw" : "480E02010201000000000000005C" // 注意这里raw和发送里面的值有可能不一样
}
}
}
2.2 setToken¶
该指令用于动态token认证方式时云端给设备设置token。具体流程参考云端设备登录设计方案。
指令格式：
{
"msgId" : 291,
"action" : "setToken",
"params" : {
"devTid" : "ESP_245EC89",
"token" : "1234567890ABCDE", //token最大长度支持64B
"ctrlKey" : "123456789ABCDE", // 设备控制码
"bindKey" : "123456789ABCDE" // 设备绑定码
}
}
应答格式：
{
"msgId" : 291,
"action" : "setTokenResp",
"code" : 200,
"desc" : "success",
"params" : {
"devTid" : "ESP_245EC89",
"token" : "1234567890ABCDE",
"ctrlKey" : "123456789ABCDE"
}
}
2.3 devSync¶
该指令用于云端要求设备同步信息，例如同步定时计划任务。设备接收到该指令后会自动调用getTimerList指令同步一次定时计划任务。具体流程参考4.x定时设计方案。
指令格式：
{
"msgId" : 291,
"action" : "devSync",
"params" : {
"ctrlKey" : "123456789ABCDE" // 设备控制码
}
}
{
"msgId" : 291,
"action" : "devSyncResp",
"code" : 200,
"desc" : "success"
}
2.4 devUpgrade¶
该指令用于设备OTA。
指令格式：
{
"msgId" : 291,
"action" : "devUpgrade",
"params" : {
"devTid" : "ESP_245EC89",
"appTid" : "345887867637",
"ctrlKey" : "123456789ABCDE", // 设备控制码
"binUrl" : "http://update.hekr.me/firmware/xxxx.bin",//必选参数，升级固件下载地址，最大长度512B
"md5" : "ab6469e59ba1d11c037d67b8d0a67930",
"binType" : "B", //可选参数，固件类型
"binVer" : "3.0.61.2", // 新固件版本
"size" : 651234 //固件文件大小，单位Byte
}
}
{
"msgId" : 291,
"action" : "devUpgradeResp",//表示开始升级
"code" : 200,
"desc" : "start upgrade success",
"params" : {
"devTid" : "ESP_245EC89",
"appTid" : "345887867637",
"ctrlKey" : "123456789ABCDE", // 设备控制码
}
}
升级过程中通过devSend指令上报升级进度
{
"msgId" : 382,
"action" : "devSend",
"params" : {
"devTid" : "ESP_245EC89",
"appTid" : [],
"data" : {
"upgradeProgress" : 10, //百分比进度
"upgradeState" : 1 // 0："成功" ，1："下载中" ， 2："固件校验失败" ， 3："超时" ，4："连接失败"
}
}
}
2.5 setProdParam¶
该指令用于设置ProdKey等产品参数，通常在厂测模式下调用。
指令格式：
{
"msgId" : 291,
"action" : "setProdParam",
"params" : {
"devTid" : "ESP_245EC89",// 必选参数，
"ctrlKey" : "123456789ABCDE", // 设备控制码,注意：用于鉴权而不是设置,可以为空(例如厂测时)。
"prodKey" : "012345678ABCDEF",// 必选参数，可留空，最大长度32B
"disableFactoryTest" : 1 // 必选参数，0：允许进入厂测模式；非0：禁止再进入厂测模式
}
}
{
"msgId" : 291,
"action" : "setProdParamResp",
"code" : 200,
"desc" : "success",
"params" : {
"devTid" : "ESP_245EC89",
"ctrlKey" : "123456789ABCDE",
"prodKey" : "012345678ABCDEF",
"disableFactoryTest" : 1
}
}
2.6 appGroupSend¶
该指令用于设备群控。下发改指令后，云端会根据群组ID为对应群组中所有设备下发appSend。
指令格式：
{
"msgId" : 291,
"action" : "appGroupSend",
"params" : {
"groupId" : "f1ab4f8fe79c4b8bb998916ca6b1f637",// 群组ID，
"appTid" : "123456789ABCDE",
"data" : { // 下发指令内容
"cmdId":2,
"startus":1
}
}
}
{
"msgId" : 291,
"action" : "appGroupSendResp",
"code" : 200,
"desc" : "success",
}
3. 上行服务指令¶
上行服务定义嵌入式调用的云端或APP提供的功能，包括devBind、devLogin、reportDevInfo、devSend、heartbeat、getTimerList等
3.1 devBind¶
设备在完成配网并和云端建立连接后,通过devBind指令建立设备与用户的对应关系,从而使用户具有对设备的控制权 指令格式:
{
"msgId" : 123,
"action" : " devBind",
"params" : {
"devTid" : "ESP_34AB094E",
"prodKey" : "0cc175b9c0f1b6a831c399e269772661",
"PINCode" : "1234",
"SSID" : "HEKR",
"token" : "" //首次配网填空,其他情况填设备端保存的token
}
}
{
"msgId" : 123,
"action" : " devBindResp",
"code" : 200,
"desc" : "success",
"params" : {
"devTid" : "ESP_34AB094E",
"token" : "4a8a08f09d37b73795649038408b5f33",
"ctrlKey" : "20005c97f94aff9d7ff8705e3cfa941e",
"bindKey" : "92eb5ffee6ae2fec3ad71c777531578f"
}
}
3.2 getProdInfo¶
该指令用于设备根据ProdKey查询产品信息，该指令可在登录前调用。且服务地址为信息查询服务地址，与其他指令通信连接地址不同。具体参考云端4.x通讯协议文档 指令格式：
{
"msgId" : 90,
"action" : "getProdInfo",
"params" : {
"prodKey" : "0cc175b9c0f1b6a831c399e269772661" // 产品唯一标识
}
}
{
"msgId" : 90,
"action" : "getProdInfoResp",
"code" : 200,
"desc" : "success",
"params" : {
"mid" : "0cc175b9c0f1", // 产品型号
"workMode" : 0, // 设备工作方式，0.JSON透传、1.JSON主控
"tokenType" : 2, // 0、1保留、2.动态token
"encryptType" : "None", // 加密类型，"None":不加密、"SSL":SSL加密
"connectType" : "tcp", // 连接类型，"tcp":tcp长连接、"websocket":websocket长连接
"serviceHost" : "hub.hekr.me", // 连接服务地址
"servicePort" : 83 // 连接服务端口
}
}
3.3 devLogin¶
该指令用于设备登录。 指令格式：
{
"msgId" : 123,
"action" : "devLogin",
"params" : {
"devTid" : "ESP_34AB094E",
"prodKey" : "0cc175b9c0f1b6a831c399e269772661",
"token" : "20005c97f94aff9d7ff8705e3cfa941e" // 设备第一次登录时填""
}
}
{
"msgId" : 123,
"action" : "devLoginResp",
"code" : 200,
"desc" : "success",
"params" : {
"devTid" : "ESP_34AB094E",
"token" : "4a8a08f09d37b73795649038408b5f33", // 新的设备token
"ctrlKey" : "20005c97f94aff9d7ff8705e3cfa941e", // 设备控制码
"bindKey" : "92eb5ffee6ae2fec3ad71c777531578f" // 绑定码
}
}
3.4 reportDevInfo¶
该指令用于设备上报基本设备信息 指令格式：
{
"msgId" : 291,
"action" : "reportDevInfo",
"params" : { // 字段可随时扩展
"devTid" : "ESP_4387EF", // 设备唯一id
"mid" : "0cc175b9c0f1", // 设备型号
"workMode" : 0, // 设备工作方式，0.JSON透传、1.JSON主控
"MAC" : "08EFA809DE6D" // 设备MAC地址
"tokenType" : 2, // 0、1保留、2.动态token
"binVer" : "3.0.61.2", // 固件版本
"binType" : "A", // 固件类型
"SDKVer" : "3.0.61.2", // 固件SDK版本
"serviceHost" : "hub.hekr.me", // 服务器地址
"servicePort" : 83, // 服务器端口
"SSID" : "HEKR-TEST" // 路由器SSID
}
}
{
"msgId" : 240,
"action" : "reportDevInfoResp",
"code" : 200,
"desc" : "success"
}
3.5 devSend¶
该指令用于设备发送数据到APP，透传模式下当串口接收到HEX数据将会转化成ASC并以该格式发送。 指令格式：
{
"msgId" : 382,
"action" : "devSend",
"params" : {
"devTid" : "ESP_245EC89",
"appTid" : [],// 为空数组时，表示设备最大组播；不为空数组时，每个元素都是APP唯一id，系统只会发送到这些指定APP上
"data" : {
"raw" : "48EFDFAB"
}
}
}
{
"msgId" : 382,
"action" : "devSendResp",
"code" : 200,
"desc" : "success"
}
3.6 heartbeat¶
该指令用于设备发送设备心跳。 指令格式：
{
"msgId" : 98,
"action" : "heartbeat"
}
{
"msgId" : 98,
"action" : "heartbeatResp",
"code" : 200,
"desc" : "success"
}
3.7 getTimerList¶
该指令用于设备获取云端的定时任务列表，具体流程参考4.x定时设计方案。
指令格式：
{
"msgId" : 291,
"action" : " getTimerList",
"params" : {
"devTid" : "ESP_245EC89", // 设备唯一id
"taskFormat" : "single", // 定时任务应答格式：single:按task数量逐条回复，list：task以数组返回。 默认list
"timeFormat" : " countdown "// 定时时间应答格式： cronexpr：cron表达式；countdown倒计时。 默认countdown
}
}
single:
{
"msgId": 291,//保持一致
"action": "getTimerListResp",
"code": 200,
"desc": "success",
"params": {
"tasksCount": 2,//任务数量
"taskList": [
{
"taskId": 1952511811,//预约任务编号,int32
"delayTime": 248,//延时时间,单位秒(s),最大3600s
"count": 3,//循环执行次数，1表示执行一次、n表示执行n次(间隔为looptime)
"loopTime": 600,//循环时间间隔，单位秒(s)
"task": {
"cmdId": 1,
"k1": "v1"
}//执行代码,通常为appSend中data部分
}
]
}
}
//第二条任务
{
"msgId": 291,//保持一致
"action": "getTimerListResp",
"code": 200,
"desc": "success",
"params": {
"tasksCount": 2,//任务数量
"taskList": [
{
"taskId": 1958890357,//预约任务编号,int32
"delayTime": 248,//延时时间,单位秒(s),最大3600s
"count": 3,//循环执行次数，1表示执行一次、n表示执行n次(间隔为looptime)
"loopTime": 600,//循环时间间隔，单位秒(s)
"task": {
"cmdId": 1,
"k1": "v1"
}//执行代码,通常为appSend中data部分
}
]
}
}
list：
{
"msgId": 291,
"action": "getTimerListResp",
"code": 200,
"desc": "success",
"params": {
"tasksCount": 2,//任务数量
"taskList": [
{
"taskId": 1952511811,//预约任务编号,int32
"delayTime": 305,//延时时间,单位秒(s),最大3600s
"count": 3,//循环执行次数，1表示执行一次、n表示执行n次(间隔为looptime)
"loopTime": 600,//循环时间间隔，单位秒(s)
"task": {"raw":"4808020122115533"} //执行代码,根据APP添加，通常为appSend消息体中data部分
},
{
"taskId": 1958890357,
"delayTime": 1505,
"count": 1,
"loopTime": 0,
"task": {"raw":"4808020122115533"}
}
]
}
}
3.8 timerReport¶
定时任务执行完后上报
{
"msgId" : 291,
"action" : "timerReport",
"params" : {
"devTid" : "ESP_245EC89",
"taskId" : 1, //预约任务编号,int32
"task" : {"raw":"4808020122115533"},//对应appSendResp中data部分：透传时为MCU应答帧内容。
"code" : 200 //表示任务已经触发
}
}
{
"msgId" : 291,
"action" : "timerReportResp",
"code" : 200,
"desc" : "success"
}
3.9 reportDevLog¶
该指令用于设备上报日志信息 指令格式：
{
"msgId" : 291,
"action" : "reportDevLog",
"params" : {
"devTid" : "ESP_245EC89", // 设备唯一id
"logContent":"system log"//日志内容
}
}
{
"msgId" : 291,
"action" : "reportDevLogResp",
"code" : 200,
"desc" : "success"
}