edit

APP通信

说明

所有请求消息、返回以换行("\n")分割,文档中为了美观将json以缩进换行表示,实际调用中JSON体内不换行,仅在消息末尾换行。

服务地址

地址 功能 协议 数据安全级别 服务区域
asia-app.hekr.me:85 APP<->云端通道 TCP长连接 非SSL 亚太
asia-app.hekr.me:185 APP<->云端通道 TCP长连接 SSL 亚太
asia-app.hekr.me:86 APP<->云端通道 WebSocket长连接 非SSL 亚太
asia-app.hekr.me:186 APP<->云端通道 WebSocket长连接 SSL 亚太

appLogin

用户使用已注册账号调用云端 login 接口登录 APP 后会返回一个 token,APP 会使用这个 token 主动调用云端提供的 appLogin 接口建立通道, 云端获取到 appTid 之后可以知道 app 在线状态。

注:token 有效期为12小时。如果APP和云端建立通道前 token 已过期,云端会提示 token 无效; 如果联网之后连接不断,即使 token 过期,APP 还能继续控制设备。

请求

{
  "msgId" : 240,
  "action" : "appLogin",
  "params" : {
      "appTid" : "35897387434734",
      "token" : "eyJhbGc..."
  }
}

参数

字段 是否必须 含义
params.token 新的设备token,设备下次再和云端建立通道时,务必使用这个新token,否则有可能导致设备被锁。
appTid app唯一标识,建议使用 UUID

响应

{
  "msgId" : 240,
  "action" : "appLoginResp",
  "code" : 200,
  "desc" : "success"
}

指令格式中的参数token,是APP调用登录接口,如果APP和云端建立通道前token已过期,云端会提示token无效;如果联网之后连接不断,即使token过期,APP还能继续控制设备。

heartbeat

由于云端30秒没有收到数据会主动和 APP 断开连接,所以 App 为了保持和云端的长连接,需要周期性的发送心跳请求。

指令格式:

{
   "msgId" : 98,
   "action" : "heartbeat"
}
应答格式:
{
    "msgId" : 98,
    "action" : "heartbeatResp",
    "code" : 200,
    "desc" : "success"
}

appSend

该指令用于控制设备。如果设备成功接收消息,那么设备会进行回应,app 会收到 action 为 appSendResp 的指令,除了 action 和发送时候不一样中外,其余参数和发送的指令的参数一样。 appSendResp 仅仅代表设备成功接收消息,并且理解这个消息的内容,至于设备有没有动作,这个要看 appSend 之后设备的当前状态,如果和预期一样则说明控制成功,否则失败。所以成功与否在于设备的执行,而不是云端。

appSend (JSON主控)

{
    "msgId" : 291,
    "action" : "appSend",
    "params" : {
        "devTid" : "ESP_2M_245EC89",
        "ctrlKey" : "123456789123456789",
        "appTid" : "54354353454",
        "data" : {
            "cmdId" : 0,
            "customKey" : 0
        }
    }
}
{
  "msgId" : 291,
  "action" : "appSendResp",
  "code" : 200,
  "desc" : "success",
  "params" : {
      "devTid" : "ESP_2M_245EC89",        
      "ctrlKey" : "123456789123456789",
      "appTid" : "54354353454",       
      "data" : {
          "cmdId" : 0,
          "raw":  "0F2CABDEG",
          "customKey" : 0
      }
  }
}

请求体

字段 是否必须 含义
params.devTid 设备devTid
params.ctrlKey 设备ctrlKey
params.subDevTid 子设备subDevTid,子设备控制时使用
params.appTid app唯一标识
params.data.cmdId 命令ID
params.data.customKey 自定义key,可以指定多个键值对

cmdId, customKey这些值可在氦氪云控制台-产品管理-产品协议-命令上查看它们的具体定义。 指令和应答里的customKey不一定是完全一致的,因为下发指令值是期望值,应答里的值设备的实际返回,可能会因为溢出等原因导致不一致。

发送数据到设备(JSON透传)

{
    "msgId" : 291,
    "action" : "appSend",
    "params" : {
        "devTid" : "ESP_2M_245EC89",
        "ctrlKey" : "123456789123456789",
        "appTid" : "358974675345",
        "data" : {
            "raw" : "48EF4DFA"   
        }
    }
}
{
  "msgId" : 291,
  "action" : "appSendResp",
  "code" : 200,
  "desc" : "success",
  "params" : {
      "devTid" : "ESP_2M_245EC89",
      "ctrlKey" : "123456789123456789",
      "appTid" : "358974675345",
      "data" : {
          "raw" : "48EF4DFA"
      }
  }
}

发送数据到设备(网关JSON主控)

{
    "msgId" : 291,
    "action" : "appSend",
    "params" : {
        "devTid" : "ESP_2M_245EC89",
        "ctrlKey" : "123456789123456789",
        "subDevTid" : "sub_dev_tid",
        "appTid" : "358974675345",
        "data" : {
            "cmdId" : 1,
            "power" : 2
        }
    }
}
{
  "msgId" : 291,
  "action" : "appSendResp",
  "code" : 200,
  "desc" : "success",
  "params" : {
      "devTid" : "ESP_2M_245EC89",
      "ctrlKey" : "123456789123456789",
      "appTid" : "358974675345",
      "data" : {
          "raw" : "48EF4DFA"
      }
  }
}

请求体

字段 是否必须 含义
params.devTid 设备devTid
params.ctrlKey 设备ctrlKey
params.subDevTid 子设备subDevTid,子设备控制时使用
params.appTid app唯一标识
params.data.raw 透传数据

raw的具体格式,可参考氦氪云控制台-产品管理-产品协议-命令-示例帧。

错误码表

错误码 提示信息 中文释义 可能造成的原因
1200000 Success 调用成功
1400000 Error 未知错误 该行以下所有1400开头的错误码需要单独处理
1400001 Json parse error json解析错误 json格式错误
1400002 JWT parse error jwt_token解析错误 jwt token错误
1400003 The field {0} contains a value that is too high 属性值过高 发送报文中某属性的值超过了其上限
1400004 The field {0} contains a value that is too low 属性值过低 发送报文中某属性的值低于了其下限
1400005 The value of the field {0} must be an enumerated value 属性值必须为范围内枚举值 发送报文中某属性值不符合其定义的取值范围
1400006 Field {0} not exist 属性不存在 发送报文中存在了未定义的属性
1400008 devTid not match 设备ID不匹配 报文填写的devTid与登录设备的devTid不一致
1400009 App repeat login APP重复登录 同一个appTid的app重复登录
1400010 User does not exist 用户不存在 用户不存在或者uid填错了
1400011 The device does not have this instruction 设备不具有该指令 设备不具备该指令
1400012 Device does not belong to user 设备不属于该用户 设备不再属于该用户
1400013 Device repeat login 设备重复登录 设备同时登录
1400014 Frame parse error 帧解析错误 报文格式或内容错误
1400015 Device last token can not use 设备上一次token已过期无法使用 使用的旧token已经超过上限
1400016 Action not support 该帧行为不被支持 报文中的action填错了
1400017 Device token can not verification 设备token校验错误 设备token错误
1400018 Device not online 设备不在线 设备离线
1400019 App is not logged in app未登录 app未登录或其他原因导致云端认为app已经离线
1400020 Device is not logged in 设备未登录 设备未登录或其他原因导致云端认为设备已经离线
1400023 appTid does not match app设备id不匹配 当前发送报文的appTid与绑定设备时的appTid不一致
1400024 You report info does not match your connect server 上报节点信息与实际不符 上报的内容与当时连接节点信息不一致
1400025 RAW not valid, Please check your protocol template 协议不合法,请参照协议模板 48协议串不合法
1400026 AuthKey can't auth authKey 认证失败 填写了错误的authkey
1400027 Product key not available 不是有效的pk 填写了错误的pk
1400028 PinCode or SSID not available pinCode或者ssid无效 填写了无效的pinCode或者ssid
1400029 Bind failed due to timeout error 绑定设备超时错误 绑定设备超时
1400030 Can not bind other manufacture's device 无法绑定其它厂商的设备 APP绑定了非该厂家的设备
1400031 Can not force bind device 无法强绑设备 设备设定为无法强绑,强绑失败
1500000 Internal error ({0}) 内部错误 服务内部错误
1500001 Link error 链路错误 链路错误