edit

设备云端通信协议

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和发送里面的值有可能不一样
        }
    }
}

注意,透传模式下该接口会等待MCU串口应答帧(超时为3s),在接收到串口应答后根据帧序号匹配msgId再应答。

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" : "asia-dev.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" : "asia-dev.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"
}