设备管理

设备绑定¶

不通设备类型绑定方式不一样，下面是每一种设备类型的具体绑定方式，一定要按照设备类型操作。

绑定 WIFI 设备¶

绑定 WIFI，需要按照以下步骤，具体参见 IOS 和Android，无需关心过程。

使设备进入配网模式
获取 PINCode
发送配网指令给设备（请使用SDK）
设备联网
设备发送绑定信息到云端

根据devTid和bindKey绑定设备¶

每个网关设备/透传设备上都有一个唯一的二维码，扫描二维码，得到一个url，类似

http://www.hekr.me?action=bind&devTid=224ef8099f884ddxxxxxxxxxxx&bindKey=59d5afd5aa98442591898xxxxxxxxxxxxxx

并根据得到的URL提取参数：

参数	说明
action	动作，是bind的时候说明是绑定操作
devTid	设备id
bindKey	绑定码

curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device" \
    -d '{
        "devTid" : "ESP_XXXX",
        "deviceName" : "我的设备1号",
        "bindKey" : "xxxxxx",
        "desc" : "我的第一台hekr智能设备"
    }'

参数

参数名	是否可选	参数类型	取值范围	说明
devTid	必选	String		设备ID
bindKey	必选	String		绑定码
deviceName	可选	String	长度[1,128]	设备名称
desc	可选	String	长度[1,128]	设备描述

返回

< 201
< {
    "deviceName" : "我的设备1号",
    "devTid" : "ESP_XXXX",
    "ctrlKey" : "6ef3c2cb87d341f9a83ce12",
    "logo" : "http://app.hekr.me/res/img/icon/icon_33@3x.png",
    "currentLoginTime" : 1459426566661,
    "ownerUid" : "20039941211",
    "ssid" : null,
    "granted" : false,
    "eventRuleMap" : None,
    "workModeType" : "JSON_CTRL",
    "timerMap" : null,
    "wanIp" : "127.0.0.1",
    "lastLoginTime" : 1454294875463,
    "connectIp" : "192.168.1.2",
    "productPublicKey" : "xxxxxx",
    "androidH5Page" : "",
    "online" : true,
    "setSchedulerTask" : false,
    "lastUpdateTime" : null,
    "servicePort" : 0,
    "firstLoginTime" : 1454294875463,
    "folderId" : "0",
    "sdkVer" : null,
    "desc" : "我的第一台hekr智能设备",
    "binVersion" : '1.1.1',
    "cid" : "test-cid",
    "devShareNum" : 0,
    "iosH5Page" : "",
    "ctrlKey" : "xxxxxxxxx",
    "bindKey" : "xxxxxxxxx",
    "lastHeartbeat" : 1454294875463
}

根据短码和短码密码绑定设备¶

curl -X POST \
  https://user-openapi.hekr.me/device/bindByCode \
  -H 'Authorization: Bearer {JWT_TOKEN}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
      "code":"gzaasUFB",
      "password":"N8EQ21",
      "deviceName":"devName",
      "desc":"test"
  }'

参数

参数名	是否可选	参数类型	取值范围	说明
code	必选	String		短码
password	必选	String		短码密码
deviceName	可选	String	长度[1,128]	设备名称
desc	可选	String	长度[1,128]	设备描述

返回

< 201
< {
    "deviceName" : "我的设备1号",
    "tokenType" : 2,
    "devTid" : "ESP_XXXX",
    "ctrlKey" : "6ef3c2cb87d341f9a83ce12",
    "logo" : "http://app.hekr.me/res/img/icon/icon_33@3x.png",
    "currentLoginTime" : 1459426566661,
    "ownerUid" : "20039941211",
    "ssid" : null,
    "granted" : false,
    "eventRuleMap" : None,
    "workModeType" : "JSON_CTRL",
    "timerMap" : null,
    "wanIp" : "127.0.0.1",
    "lastLoginTime" : 1454294875463,
    "connectIp" : "192.168.1.2",
    "productPublicKey" : "xxxxxx",
    "androidH5Page" : "",
    "online" : true,
    "setSchedulerTask" : false,
    "lastUpdateTime" : null,
    "servicePort" : 0,
    "firstLoginTime" : 1454294875463,
    "folderId" : "0",
    "sdkVer" : null,
    "desc" : "我的第一台hekr智能设备",
    "binVersion" : "1.1.1",
    "cid" : "test-cid",
    "devShareNum" : 0,
    "iosH5Page" : "",
    "ctrlKey" : "xxxxxxxxx",
    "bindKey" : "xxxxxxxxx",
    "lastHeartbeat" : 1454294875463
}

修改设备短码密码¶

curl -X PUT \
    https://user-openapi.hekr.me/device/resetShortCodePassword \
    -H 'Authorization: Bearer {JWT_TOKEN}' \
    -H 'Cache-Control: no-cache' \
    -H 'Content-Type: application/json' \
    -d '{
        "ctrlKey":"420d8e77c2ab459786ab4e44ef2dd39b",
        "code":"gzab463t",
        "oldPassword":"445UE8",
        "newPassword":"445UE9"
    }'

参数

参数名	是否可选	参数类型	说明
ctrlKey	必选	String	设备ctrlKey
code	必选	String	短码
oldPassword	必选	String	原有密码
newPassword	必选	String	新密码

绑定子设备¶

绑定子设备需要通过 WebSocket 或者 TCP方式，发送数据：

{
    "action": "appSend",
    "params": {
        "devTid": "xxxx",
        "ctrlKey": "xxxx",
        "appTid": "",
        "subDevTid": "",
        "data": {
            "cmdId": 2,
            "subMid": "xxxx",
            "overtime": 60
        }
    }
}

参数	必填	说明
action	是	固定为 appSend
devTid	是	网关设备id
ctrlKey	是	网关ctrlKey
appTid	是	APP建立链接的时候使用appTid
subDevTid	是	固定为空字符串
cmdId	是	固定为 2
subMid	是	子设备的mid，根据

首先监听 action 为 appSendResp 的消息，如果不是200，则说明下发指令失败，200成功后继续监听 action 为 addSubDev 的消息，如果成功，则返回如下信息，否则请根据错误码判断具体错误信息，

{
    "devTid": "b28c9356c4ad42c0b22f035a0df851eb ", //网关设备id
    "subDevTid": "00124b0004207a98", // 子设备id
    "subMid": "012345abcdef", // 子设备产品id
    "subConnectType": "ZigBee_HA", // 子设备链接方式
    "online": true, // 是否在线
    "binVer": "3.0.1.2", // 固件版本
    "subDevName": " ", // 子设备名字
    "subDevModel": " ", // 子设备型号
    "manufacturerName": "hekr",
    "description": " " // 描述
}

获取PINCode¶

该接口用于配网时获取PINCode

curl -v -X GET \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  "https://user-openapi.hekr.me/getPINCode?ssid=1111"

参数

参数名	是否可选	参数类型	取值范围	说明
ssid	必选	String		当前连接路由器的ssid

返回

> 200
> {
  "PINCode" : "sS16sg"
}

获取当前局域网设备配网详情¶

该接口用于配网时查看当前局域网内设备配网进度

curl -v -X GET \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  "https://user-openapi.hekr.me/getNewDeviceList?pinCode=xx&ssid=xxx"

参数

参数名	是否可选	参数类型	取值范围	说明
ssid	必选	String		当前连接路由器的ssid
pinCode	必选	String		当前配网使用的pinCode

返回

> 200
> [
    {
        // 部分 kv 释义请参考 4.1.2
        "deviceName": null,
        "cidName": "\u751f\u6d3b\u7535\u5668/\u706f",
        "binType": null,
        "bindResultCode": 0,                            // 绑定（配网）是否成功 0：成功 1：失败
        "devTid": "zyut4fxrbn",
        "serviceHost": null,
        "ctrlKey": "2ef0a36d9583413daf6",
        "logo": "http://7xsk3u.com1.z0.glb.clouddn.com/1464157649632lamp2.png",
        "iosPageZipURL": "",
        "currentLoginTime": 1470904732349,
        "productBand": "a",
        "groupInfo": [],
        "ssid": null,
        "granted": false,
        "eventRuleMap": null,
        "androidPageZipURL": "",
        "forceBind": true,
        "workModeType": "JSON_TRANSPARENT",
        "bindResultMsg": "18518018418",                 // 绑定结果信息
        "finger": "d4e67da1-a06d-4708-90d7-0edef855b611",
        "timerMap": null,
        "wanIp": "182.50.118.126",
        "lastLoginTime": 1470904732349,
        "bindKey": "ced854a79c4a4ed519ba",
        "status": "ONLINE",
        "categoryName": {
            "en_US": "EA/Lamp",
            "zh_CN": "\u751f\u6d3b\u7535\u5668/\u706f"
        },
        "maxDevShareNum": 0,
        "ownerUid": "13805966378",
        "deviceAuthorizationStatuses": null,
        "androidH5Page": "",
        "online": true,
        "setSchedulerTask": false,
        "servicePort": 0,
        "deviceBindingStatus": {
            "bindTime": 1470904732372,
            "expire": -1,
            "uid": "13805966378",
            "desc": ""
        },
        "mac": null,
        "firstLoginTime": 1470904732349,
        "folderId": null,
        "sdkVer": null,
        "productName": {
            "en_US": "",
            "zh_CN": ""
        },
        "desc": null,
        "productPublicKey": "k0wfHypbzGlO9FdoxF",
        "cid": "b7f9a8ecabef",
        "devShareNum": 0,
        "iosH5Page": "",
        "folderName": "",
        "model": "pass_through",
        "binVersion": null,
        "lastHeartbeat": 1470904732349
    }
]

列举设备¶

列举设备提供了几种不同的方式供开发者使用，每个接口有不同格式，可以满足不同场景的需要，下面是具体的列举设备的接口描述。

设备列表中会有一个统一的字段 dcInfo，这个是数据中心信息，其中 fromDC 是指这个设备链接在哪个数据中心，domain是拼接好的域名，跟设备链接的数据中心相关。如果app要想控制该设备，需要链接该域名所对应的地址，详细信息参见多数据中心控制设备

获取嵌套模式的设备列表¶

该接口返回的子设备在网关设备下的 subDevices 属性中。不指定分页信息默认最多只返回20条记录。

curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device?devTid=tid1234,tid22,tid55&folderId=fid1234&groupId=gid1234&page=0&size=10"

参数

参数名	是否可选	参数类型	取值范围	说明
devTid	可选	String		（废弃，请使用ctrlKey）设备devTid，多个使用逗号分隔
ctrlKey	可选	String		设备唯一ID，多个使用逗号分隔
folderId	可选	String		目录ID，按其值筛选
groupId	可选	String		群ID，按其值筛选
granted	可选	Boolean		是否授权，按其值筛选
setSchedulerTask	可选	Boolean		是否设置了预约，按其值筛选
page	可选	Int	[0, ?]	分页参数，默认为0
size	可选	Int	[1, 20]	分页参数，默认为20

返回

当调用者为该设备属主时，bindKey与ctrlKey皆返回，否则只返回ctrlKey。

< 200
< [
    {
        "dcInfo":{ //见段落开头描述
            "opTimestamp": 1517930387464,
            "fromDC": "gz",
            "dc": "gz",
            "area": "asia",
            "fromArea": "asia",
            "connectHost": "hub.hekr.me"
        },
        "deviceName" : "hekr_device",                   // 设备绑定指定名字
        "tokenType" : 2,                                // token类型 2：动态token
        "mid": "01650ca78f33",                          // 产品ID
        "binType" : null,                               // 固件类型
        "devTid" : "tid2",                              // 设备ID
        "devKey" : "xxxx",                              // 设备秘钥
        "serviceHost" : null,                           // 连接服务器host
        // 设备logo地址
        "logo" : "http://7xl8jv.com2.z0.glb.qiniucdn.com/1455783857385iconfont-hekriconshebeitaideng18.png",
        "androidH5Page" : "",                           // 安卓H5页面地址
        "iosH5Page" : "",                               // ios H5页面地址
        "devShareNum" : 0,                              // 设备当前授权人数
        "currentLoginTime" : 1458732550117,             // 最新登录时间时间戳
        "ownerUid" : "20039941211",                     // 设备属主UID
        "ssid" : null,                                  // 连接WIFI ssid
        "granted" : false,                              // 是否授权给了其他人
        "productPublicKey" : "xxxxxx",                  // 设备产品公共密钥
        "workModeType" : "JSON_CTRL",                   // 设备工作模式 JSON_CTRL（JSON主控）/JSON_TRANSPARENT（JSON透传）
        "timerMap" : null,                              // 定时预约任务
        "gis": {                                        // 地理位置信息
              "ip": {
                "country": "中国",
                "province": "北京市",
                "city": "北京市",
                "citycode": null,
                "district": null,
                "adcode": null,
                "township": null,
                "towncode": null,
                "street": null,
                "ip": "61.148.244.191"
              },
              "geo": null,
              "bs": null,
              "bsOther": null
        },
        "wanIp" : "127.0.0.1",                          // 公网IP
        "lanIp": "192.168.1.245",                       // 局域网IP
        "lanIpUpdateDate": 1454294875463,               // 局域网IP上报时间
        "lastLoginTime" : 1454294875463,                // 上一次登录时间
        "connectIp" : "192.168.1.2",                    // 连接服务器IP
        "online" : true,                                // 是否在线
        "setSchedulerTask" : false,                     // 是否设置了预约任务
        "lastUpdateTime" : null,                        // 上次更新固件时间
        "servicePort" : 0,                              // 服务端口
        "firstLoginTime" : 1454294875463,               // 首次登录时间时间戳
        "folderId" : "0",                               // 设备所在文件夹ID
        "sdkVer" : null,                                // sdk版本
        "desc" : "",                                    // 设备描述
        "binVersion" : null,                            // 固件版本
        "cid" : "test-cid",                             // 品类ID
        "ctrlKey" : "8971a6b62c0649f6bdec99c",          // 设备控制码
        "bindKey" : "20005c97f94aff9d7ff870a941e",      // 设备绑定码
        "lastHeartbeat" : 1454294875463                 // 上次心跳时间时间戳
        "groupInfo" : [
            {
                "groupId" : "gid1234",                  // 设备所在群组信息
                "groupName" : "联动小组001",
                "deviceList": [
                  {
                    "devTid": "xketuo2z5c",
                    "ctrlKey": "704973e8d3a3424ebcc"
                  }
                ],
                "createTime": 1462343277675,
                "updateTime": null,
                "groupMid": "01d836a3cb28"
            },
            ...
        ]
        "androidH5Page": "https://xxxx/index.html",      // 安卓的H5控制页面
        "iosH5Page": "https://xxxx/index.html",          // IOS的H5控制页面
        "weChatH5Page": "https://xxxx/index.html",       // 微信的H5控制页面
        "iosPageZipURL" : "https://xxxx/xxxx.zip",       // IOS的H5控制页的zip包
        "androidPageZipURL" : "https://xxxx/xxxx.zip",   // 安卓的H5控制页的zip包
        "weChatPageZipURL": "https://xxxx/xxxx.zip",     // 微信的H5控制页的zip包
        "categoryName": {
          "zh_CN": "xxxx",                               //品类中文名称
          "en_US": "xxxx"                                //品类英文名称
        },
        "productName": {
          "zh_CN": "xxxx",                               //产品中文名称
          "en_US": "xxxx"                                //产品英文名称
        },
        "productBand" : "xxx"                            // 设备品牌
        "model" : "xxxx"                                 // 产商设置的设备型号
        "cidName" : "xxx"                                // 具体的品类名称
        "bindPid": "01015362077",                        // 当前绑定人pid
        "subscribe": true,                               // 是否为产品订阅企业用户绑定
        "subDevices": [                                  // 设备下子设备列表（网关设备独有）
            {
                "dcInfo":{ //见段落开头描述
                    "opTimestamp": 1517930387464,
                    "fromDC": "gz",
                    "dc": "gz",
                    "area": "asia",
                    "fromArea": "asia",
                    "connectHost": "hub.hekr.me"
                },
                "devTid": "0003b1b000000000", // 子设备ID
                "mid": "01b49090fe42",  // 子产品ID
                "connectType": "linptech",  // 连接方式
                "online": true,   //是否在线
                "binVer": "2.1.0", //
                "devName": "",
                "devModel": "",
                "manufacturerName": "Linptech",
                "description": "scene button-3",
                "cidName": "家居家装/情景开关",
                "categoryName": {
                  "zh_CN": "家居家装/情景开关",
                  "en_US": "Misc/Scene Switch"
                },
                "productName": {
                  "en_US": "Scene Button",
                  "zh_CN": "三键情景按钮"
                },
                "logo": "https://allinone-ufile.hekr.me/product/60e182aa-474e-49ae-a33a-3fd231dd9e6d.png",
                "androidH5Page": "https://allinone-ufile.hekr.me/h5page/e9ae2147-ca32-41f6-8d05-283220e370c5/index.html",
                "iosH5Page": "https://allinone-ufile.hekr.me/h5page/e9ae2147-ca32-41f6-8d05-283220e370c5/index.html",
                "iosPageZipURL": "https://allinone-ufile.hekr.me/h5page/e9ae2147-ca32-41f6-8d05-283220e370c5/cloud-house-scene-button.zip",
                "androidPageZipURL": "https://allinone-ufile.hekr.me/h5page/e9ae2147-ca32-41f6-8d05-283220e370c5/cloud-house-scene-button.zip",
                "productPublicKey": "k0wfHypbzGlO984xLmtZMCNI+tAqIZKOmM2vxb+xLOVoZqfuJ4ZjTi9ZBAcuRiV1Qp",
                "folderId": "0",
                "folderName": "root",
                "parentDevTid": "7f992582caec4b8587fb3ba4d23b2d46",
                "parentCtrlKey": "042a9c2a96c647949d49c8b0e9f0b7fd",
                "devType": "SUB"
            },
            ......
        ],
        "quickOperationConfigList":[] // 快捷操作相关
    },
    ...
  ]

带文件夹和过滤条件的设备列表接口¶

该接口返回的子设备和独立设备或者网关设备一个层次上，结果不分页，并且可以根据条件过滤。

curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/devices?quickOperation=true&folderId=xx&ctrlKey=aa,bb&subDevTid=cc&type=SUB"

参数	必填	说明
quickOperation	否	如果为true则显示快捷操作属性，否则不显示，默认不显示
folderId	否	文件夹id，可以根据文件夹id过滤，只显示该文件夹下的设备
ctrlKey	否	设备ctrlKey，多个用（英文）逗号隔开，可以根据指定ctrlKey查询独立设备或者网关
subDevTid	否	子设备id，多个用（英文）逗号隔开，可以根据指定子设备id查询，如果该参数填写，必须填写ctrlKey，并且，结果返回指定子设备和网关
type	否	设备类型，INDEPENDENT:独立设备，GATEWAY:网关设备，SUB:子设备，ALL:全部类型设备

过滤条件说明： folderId 和 type 的优先级最高，比如当同时指定ctrlKey，subDevTid，folderId 和type的时候，优先过滤type类型和folderId的设备。

举例：

获取指定文件夹下的所有子设备： folderId=xx&type=SUB
获取某个网关下的指定子设备，不包含网关：ctrlKey=xx&subDevTid=xx
获取某个网关（包含）和旗下某个子设备：ctrlKey=xx&subDevTid=xx&type=ALL
获取指定网关或者WIFI设备：ctrlKey=xx,mm
获取所有子设备：type=ALL
获取所有网关设备：type=GATEWAY

结果：

[
    {
        "dcInfo":{ //见段落开头描述
            "opTimestamp": 1517930387464,
            "fromDC": "gz",
            "dc": "gz",
            "area": "asia",
            "fromArea": "asia",
            "connectHost": "hub.hekr.me"
        },
        "ctrlKey": "xx",
        "devTid": "xx",
        "devType": "GATEWAY",
        "mid": "xx",
        "bindKey": "xx",
        "workModeType": "JSON_CTRL",
        "ssid": "NULL",
        "mac": "xx",
        "gis": {
            "ip": {
                "country": "中国",
                "province": "浙江省",
                "city": "杭州市",
                "citycode": null,
                "district": null,
                "adcode": null,
                "township": null,
                "towncode": null,
                "street": null,
                "ip": "122.235.xx.xx"
            },
            "geo": null,
            "bs": null,
            "bsOther": null
        },
        "lanIp": null,
        "lanIpUpdateDate": null,
        "binVersion": "4.0.1.2",
        "binType": "A",
        "ownerUid": "xxx",
        "granted": false,
        "forceBind": false,
        "productPublicKey": "xxx/GKbY9btTRfk/xxx",
        "logo": "https://stage-allinone-ufile.hekr.me/category/2dfc4d39-02dc-4b97-a003-fd62e7c6e4a2/1473413193001.png",
        "androidH5Page": "https://stage-allinone-ufile.hekr.me/h5page/58c60e0be4b00a456278fb68/index.html",
        "iosH5Page": "https://stage-allinone-ufile.hekr.me/h5page/58c60e0be4b00a456278fb68/index.html",
        "weChatH5Page": "",
        "iosPageZipURL": "https://stage-allinone-ufile.hekr.me/h5package/58c60e0be4b00a456278fb68/NetStation.zip",
        "androidPageZipURL": "https://stage-allinone-ufile.hekr.me/h5package/58c60e0be4b00a456278fb68/NetStation.zip",
        "weChatPageZipURL": null,
        "productBand": "hekr",
        "model": "GW-01",
        "cidName": "测试增加大品类/测试",
        "categoryName": {
            "zh_CN": "测试增加大品类/测试",
            "en_US": "Test Add Big Category/test1"
        },
        "productName": {
            "en_US": "gateway",
            "zh_CN": "网关"
        },
        "online": false, // 是否在线
        "quickOperationConfigList": [],//快捷操作信息
        "deviceSort": 1,
        "name": "gateway-59", // 设备名字
        "desc": "", // 描述
        "folderSort": -1, // 文件夹排序
        "folderId": "0", // 文件夹id
        "folderName": "root", // 文件夹名字
        "showType": "COMMON",
        "subDevices": []
    },
    {
        "devTid": "sub_a8bh1",
        "mid": "014caee7a409",
        "online": false,
        "binVer": "test",
        "quickOperationConfigList": [],
        "deviceSort": 4,
        "deviceName": "",
        "name": "门铃按钮-h1",
        "devName": "",
        "cidName": "测试增加大品类/测试",
        "categoryName": {
            "zh_CN": "测试增加大品类/测试",
            "en_US": "Test Add Big Category/test1"
        },
        "productName": {
            "zh_CN": "门铃按钮"
        },
        "logo": "https://stage-allinone-ufile.hekr.me/category/2dfc4d39-02dc-4b97-a003-fd62e7c6e4a2/1473413193001.png",
        "androidH5Page": "",
        "iosH5Page": "",
        "iosPageZipURL": null,
        "androidPageZipURL": null,
        "productPublicKey": "xx/GKbY9btTRfk/xx+cJzBSX7Rc7YYh5UA8SvqDSxWqpEq",
        "folderId": "0",
        "folderName": "root", //文件夹id
        "folderSort": -1,
        "ownerUid": "13347860823",
        "parentOnline": false,
        "parentDevTid": "xx", // 所属网关设备id
        "parentCtrlKey": "xxx", // 所属网关ctrlKey
        "showType": "COMMON",
        "devType": "SUB",
        "irda": false
    }
]

按照文件夹分组的设备列表接口¶

该接口会按照文件夹分组返回每个文件夹下的设备列表

curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/folder/device?page=0&size=10"

参数

参数名	是否可选	参数类型	取值范围	说明
page	可选	Int	[0, ?]	分页参数，默认为0
size	可选	Int	[1, 20]	分页参数，默认为20

{
    "folderId": "bc6fbfc17be443fd9d42c690a3d5a780", // 文件夹id
    "folderName": "客厅", // 文件夹名字
    "folderSort": 3, // 文件夹排序
    "deviceList": [// 设备列表
        {
            "dcInfo":{ //见段落开头描述
                "opTimestamp": 1517930387464,
                "fromDC": "gz",
                "dc": "gz",
                "area": "asia",
                "fromArea": "asia",
                "connectHost": "hub.hekr.me"
            },
            "ctrlKey": "xxx", // 独立设备或者网关ctrlKey
            "devTid": "xxxx", // 设备id
            "devType": "INDEPENDENT",// 设备类型，INDEPENDENT：（WIFI）独立设备，GATEWAY：网关设备，SUB：网关子设备
            "mid": "xxxx",// 产品id
            "bindKey": "xxxx", // 绑定码
            "workModeType": "JSON_CTRL", // 工作模式，JSON_CTRL：json主控，JSON_TRANSPARENT：json透传，JSON_TRANSPARENT_NOT_CHECK_RAW：json透传不校验
            "ssid": "HEKR",// WIFI ssid
            "mac": "xxxx", // mac 地址
            "gis": { // 地理位置信息
                "ip": { // ip 信息
                    "country": "中国",
                    "province": "浙江省",
                    "city": "杭州市",
                    "ip": "125.119.111.111"
                }
            },
            "binVersion": "4.1.20.12", // 固件版本
            "binType": "B", // 固件版本（类型）
            "ownerUid": "37506155513", // 所属用户id
            "granted": false, // 是否授权
            "productPublicKey": "k0wfHypbzGlO8lNp+HTtGdJ2qbQeUMtHNSSwn+cJzBSX5n0+4hLx36nZUkRhf6nKUl",// ppk
            "logo": "https://xx.png",
            "androidH5Page": "https://index.html",
            "iosH5Page": "https://index.html",
            "weChatH5Page": "",
            "iosPageZipURL": "https://cloud-house-infrared-socket.zip",
            "androidPageZipURL": "https://cloud-house-infrared-socket.zip",
            "weChatPageZipURL": null,
            "productBand": "杭州第九区科技有限公司",
            "model": "IR-001",
            "cidName": "智能家居/智能电器",
            "categoryName": {
                "zh_CN": "智能家居/智能电器",
                "en_US": "Smart Home/Smart Appliances"
            },
            "productName": {
                "en_US": "IR Socket",
                "zh_CN": "红外计量插座"
            },
            "online": true, // 是否在线
            "quickOperationConfigList": [], // 快捷操作信息
            "deviceSort": 0, // 设备排序
            "name": "IR Socket-DB", // 设备名字
            "folderSort": 2,
            "folderId": "6cc7cfeab4174e43a129fbb261a5d114",
            "folderName": "主卧",
            "showType": "COMMON",
            "subDevices": []
        }
    ]
}

列举指定目录下设备列表¶

curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device/{folderId}?page=0&size=10"

参数

参数名	是否可选	参数类型	取值范围	说明
folderId	必选	String		目录ID
page	可选	Int	[0, ?]	分页参数，默认为0
size	可选	Int	[1, 20]	分页参数，默认为20

返回

>200
>[
  {
    "dcInfo":{ //见段落开头描述
            "opTimestamp": 1517930387464,
            "fromDC": "gz",
            "dc": "gz",
            "area": "asia",
            "fromArea": "asia",
            "connectHost": "hub.hekr.me"
    },
    "devTid": "d0364654e8b",
    "devType": "GATEWAY",
    "mid": "xxx",
    "cid": "694aec7",
    "ctrlKey": "xxx",
    "bindKey": "xxx",
    "workModeType": "JSON_CTRL",
    "ssid": "NULL",
    "mac": "d0364654d788e8b",
    "gis": {
      "country": null
    },
    "wanIp": "xxx",
    "country": null,
    "province": null,
    "city": null,
    "binType": "A",
    "finger": "c9e4f2f8-33bb-4fc6-baa8-c31ab2",
    "lastHeartbeat": 1488884595573,
    "ownerUid": "xxx",
    "status": "ONLINE",
    "granted": true,
    "setSchedulerTask": true,
    "forceBind": false,
    "devShareNum": 3,
    "maxDevShareNum": 0,
    "bindPid": null,
    "subscribe": false,
    "timerMap": {
      "1": {
        "uid": "xxx",
        "taskId": 1,
        "taskName": "新加预约",
        "taskKey": null,
        "enable": true,
        "code": {
          "cmdId": 2,
          "sw": 0
        },
        "desc": "备注",
        "timeZoneOffset": 480,
        "count": 1,
        "timerTaskStatus": "SCHEDULING",
        "createTime": 1488872928681,
        "updateTime": 1488876565571,
        "subDevTid": "00124b000",
        "schedulerType": "LOOP",
        "cronExpr": "0 52 16 ? * TUE,WED,SUN *",
        "triggerDateTime": null,
        "triggerTime": "16:52:00",
        "repeatList": [
          "TUE",
        ]
      }
    },
    "eventRuleMap": null,
    "deviceBindingStatus": {
      "uid": "xxx",
      "bindTime": 1488793564998,
      "expire": 33024793564998,
      "desc": ""
    },
    "deviceAuthorizationStatuses": [
      {
        "grantee": "xxx",
        "grantTime": 1488871803948,
        "updateTime": null,
        "expire": 3636355450948,
        "instructionExpire": null,
        "mode": "ALL",
        "enableIFTTT": true,
        "enableScheduler": true,
        "desc": "",
        "subDevTids": [
          "00124b000"
        ]
      }
    ],
    "deviceName": "智能网关",
    "desc": "",
    "folderId": "0",
    "productPublicKey": "xxx",
    "logo": "",
    "androidH5Page": "",
    "iosH5Page": "",
    "productBand": "新歌",
    "model": "HEKR-01",
    "cidName": "家居家装/智能网关",
    "categoryName": {
      "zh_CN": "家居家装/智能网关",
      "en_US": "Misc/Smart Gateway"
    },
    "productName": {
      "en_US": "Smart Gateway",
      "zh_CN": "智能网关"
    },
    "folderName": "root",
    "online": true,
    "groupInfo": [],
    "bindResultCode": null,
    "bindResultMsg": null,
    "subDevices": [
      {
        "dcInfo":{ //见段落开头描述
            "opTimestamp": 1517930387464,
            "fromDC": "gz",
            "dc": "gz",
            "area": "asia",
            "fromArea": "asia",
            "connectHost": "hub.hekr.me"
        },
        "devTid": "00124b000",
        "mid": "xxx",
        "connectType": "zigbee_zha",
        "online": true,
        "devName": "",
        "devModel": "42",
        "manufacturerName": "Hongsi",
        "description": "WP sensor",
        "cidName": "家居家装/传感器",
        "categoryName": {
          "zh_CN": "家居家装/传感器",
          "en_US": "Misc/Sensor"
        },
        "productName": {
          "en_US": "Flooding Detection",
          "zh_CN": "水浸传感器"
        },
        "logo": "",
        "androidH5Page": "",
        "iosH5Page": "",
        "folderId": "0",
        "folderName": "root",
        "parentDevTid": "d0364654d3d",
        "parentCtrlKey": "82bfb8e1",
        "devType": "SUB"
      }
    ],
    "quickOperationConfigList":[] // 快捷操作相关
  }
]

列举当前用户下指定设备下所有子设备¶

curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device/subDevList?devTid=tid1234&ctrlKey=fidxxxxxxxxx&subDevTid=gid1234&page=0&size=10"

参数

参数名	是否可选	参数类型	取值范围	说明
devTid	必选	String		设备ID
ctrlKey	必选	String		设备控制码
subDevTid	可选	String		子设备ID
page	可选	Int	[0, ?]	分页参数，默认为0
size	可选	Int	[1, 20]	分页参数，默认为20

返回

>200
>[
  {
    "dcInfo":{ //见段落开头描述
            "opTimestamp": 1517930387464,
            "fromDC": "gz",
            "dc": "gz",
            "area": "asia",
            "fromArea": "asia",
            "connectHost": "hub.hekr.me"
    },
    "devTid": "gid1234",
    "mid": "xxx",
    "connectType": "zigbee_zha",
    "online": true,
    "binVer": "3.0.10",
    "devName": "",
    "devModel": "42",
    "manufacturerName": "Heiman",
    "description": "WP sensor",
    "cidName": "家居家装/传感器",
    "categoryName": {
      "zh_CN": "家居家装/传感器",
      "en_US": "Misc/Sensor"
    },
    "productName": {
      "en_US": "Flooding Detection",
      "zh_CN": "水浸传感器"
    },
    "logo": "",
    "androidH5Page": "",
    "iosH5Page": "",
    "iosPageZipURL": "",
    "androidPageZipURL": "",
    "productPublicKey": "",
    "folderId": "0",
    "folderName": "root",
    "parentDevTid": "d0364654d3d8bd",
    "parentCtrlKey": "82bfb8e19f1be",
    "devType": "SUB"
  }
  .....
 ]

快捷操作¶

快捷操作的属性会在列举设备列表或者获取文件夹下的设备列表【TODO】接口中的设备信息中展示。

需要从设备列表中展示快捷操作参数，需要加上请求参数 quickOperation=true。

功能类型分为3类：

显示 SHOW
控制 CONTROL
显示+控制 SHOW_CONTROL

组件类型：

功能类型	组件类型
SHOW	NUMBER（数值类型），STATUS（状态类型，也就是枚举类型）
CONTROL	ON（开启），STOP（停止），OFF（关闭）
SHOW_CONTROL	SWITCH（开关）

功能相同部分参数说明：

参数	类型	说明
function	string	功能名称
functionType	string	功能类型，上面提到的3种
showType	string	组件类型
value	object	根据功能类型不同的而有所区别，详细信息继续阅读下面内容
contents	array	数组，配置的参数信息

显示¶

只是用来在界面上进行数值、状态等显示。

最佳实践 直接使用desc参数即可。

参数说明，其他参数无需关心

参数	类型	说明
showType	NUMBER 或者 STATUS
value	object	协议模板定义的参数类型
unit	string	单位（符号）
desc	string	value + unit 的字符串

showType 为 NUMBER 示例：

{
    "function": "PM2.5",
    "functionType": "SHOW",
    "showType": "NUMBER",
    "value": "45",
    "unit": "ug/m3",
    "desc": "45ug/m3"
}

showType 为 STATUS 示例：

{
    "function": "传感器状态",
    "functionType": "SHOW",
    "showType": "STATUS",
    "value": 1,
    "name": "正常",
    "nameEN": "Normal",
    "desc": "正常",
    "descEN": "Normal"
}

控制¶

只是用于发送指令，没有状态、数值等显示作用。

最佳实践 根据 showType 的说明构造按钮，比如开，关。然后根据协议模板和contents内容构造指令，发送cmdId和params。

参数说明

参数	类型	说明
cmdId	int	控制指令
param	string	参数名字
showType	ON, OFF 或者 STOP
value	string	ON 开，OFF 关, STOP 停止
contents	array	一个元素

示例：

{
    "function": "窗帘电机控制",
    "functionType": "CONTROL",
    "showType": "ON",
    "cmdId": 2,
    "param": "Power",
    "contents": [
        {
            "value": 1
        }
    ]
}

显示+控制¶

既能显示数值、状态等，也能进行控制发送指令。

最佳实践 根据 value 的说明构造按钮，比如开，关。然后根据协议模板和contents内容构造指令，发送cmdId和params。

参数说明

参数	类型	说明
cmdId	int	控制指令
param	string	参数名字
showType	NUMBER 或者 STATUS
value	string	ON 开，OFF关
contents	array	可能有多个

示例：

{
    "function": "开关",
    "functionType": "SHOW_CONTROL",
    "showType": "SWITCH",
    "cmdId": 2,
    "param": "Power",
    "value": "OFF",
    "contents": [
        {
            "value": 1,
            "ctrlType": "ON"
        },
        {
            "value": 2,
            "ctrlType": "OFF"
        }
    ]
}

删除设备¶

删除不同类型设备有不同的操作，下面是每种类型设备删除操作。

删除（解除绑定）网关和 WIFI（独立）设备¶

该接口只适用于网关和WIFI设备，删除子设备请参见删除子设备接口

curl -v -X DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device/{devTid}?bindKey={bindKey}"

参数

参数名	是否可选	参数类型	取值范围	说明
devTid	必选	String		设备ID
bindKey	必选	String		绑定码

返回

如果该设备在场景和联动中有使用，则返回如下信息，否则删除成功。

< 202
< {
    "randomToken"："1qazxsw23edcvfr4"
    "scene":[
      {
        "sceneId":"222222222",
        "sceneName":"睡觉"
      },
      {
        "sceneId":"333333"
        "sceneName":"会家"
      }
      ...
    ]
    "ifttt":[
      {
        "ruleId":"1111111",
        "ruleName":"看电视"
      }，
      {
        "ruleId":"666666",
        "ruleName":"开门"
      },
      .....
    ]
  }

如果确认要删除，则加上上面返回的 randomToken 参数，调用删除

curl -v -X DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device/{devTid}?bindKey={bindKey}&randomToken={randomToken}"

> 204
> No Content

删除子设备¶

删除子设备联动和场景¶

删除子设备前,需要先调用删除接口删除子设备在场景和联动；如果存在场景和联动，则会返回参数 randomToken，详情如下：

curl -X DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device/delSubDevice?devTid=xxx&ctrlKey=xxx&subDevTid=xxx"

参数

参数名	是否可选	参数类型	说明
devTid	必选	String	网关设备tid
ctrlKey	必选	String	网关设备ctrlKey
subDevTid	必选	String	要删除的子设备的tid

返回

如果没有返回值则返回null

< 200
< {
    "randomKey"："1qazxsw23edcvfr4"
    "scene":[
      {
        "sceneId":"222222222",
        "sceneName":"睡觉"
      },
      {
        "sceneId":"333333"
        "sceneName":"会家"
      }
      ...
    ]
    "ifttt":[
      {
        "ruleId":"1111111",
        "ruleName":"看电视"
      }，
      {
        "ruleId":"666666",
        "ruleName":"开门"
      },
      .....
    ]
  }

真正删除子设备¶

删除成功后才可以调用删除子设备接口进行删除。真正删除子设备需要通过 WebSocket 或者 TCP方式，类似于绑定子设备

APP建立TCP或者WebSocket之后，发送指令：

{
    "action": "devDelete",
    "params": {
        "devTid": "xxxx",
        "ctrlKey": "xxxx",
        "appTid": "xxxx",
        "subDevTid":"xxx",
        "randomToken":"xxxx"
    }
}

参数	必填	说明
action	是	固定为 devDelete
devTid	是	网关id
ctrlKey	是	网关ctrlKey
appTid	是	app 建立链接时候用的appTid
subDevTid	是	要删除的子设备的id
randomToken	否	删除子设备场景接口中返回的 `randomToken` 参数。

需要监听action为 devDeleteResp 的消息，请根据错误码判断具体错误信息。

更改设备名称/描述¶

curl -v -X PATCH \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device/{devTid}" \
    -d '{
        "deviceName" : "新的设备1",
        "desc" : "新的设备描述",
        "ctrlKey" : "xxxx"
    }'

参数

参数名	是否可选	参数类型	取值范围	说明
devTid	必选	String		设备ID
ctrlKey	必选	String		设备控制码
deviceName	可选	String	长度[1, 128]	设备名称
desc	可选	String	长度[1, 128]	设备描述

返回

< 204
< No Content

更改子设备名称和描述¶

curl -v -X PATCH \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device/{devTid}/{subDevTid}" \
    -d '{
        "deviceName" : "新的子设备名称",
        "desc" : "新的子设备描述",
        "ctrlKey" : "xxxx"
    }'

参数

参数名	是否可选	参数类型	说明
devTid	必选	String	设备ID
ctrlKey	必选	String	设备控制码
subDevTid	必选	String	子设备ID
deviceName	可选	String	设备名称
desc	可选	String	设备描述

返回

< 204
< No Content

获取当前局域网内所有设备绑定状态¶

根据devTid和bindKey查询设备绑定状态¶

curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/deviceBindStatus"
    -d '[{
          "bindKey" : "xxxxx",
          "devTid" : "ESP_test"
      },
      ...
    ]'

参数

参数名	是否可选	参数类型	取值范围	说明
devTid	必选	String		设备ID
bindKey	必选	String		绑定码

返回

只返回正确的devTid/bindKey对应的设备绑定状态，所以返回里的元素数量会少于提交里的元素数量。

< 200
< [
    {
        "devTid": "test-2016-4-18-1",                   // 设备ID
        "bindKey": "xxxxx",                             // 设备bindKey
        "bindToUser": true,                             // 是否已被用户绑定
        "forceBind": false,                             // 是否可以被强制绑定
        "deviceName": "",                               // 设备名字
        // logo url
        "logo": "http://app.hekr.me/res/img/icon/icon_33@3x.png",
        "cid": "fc1345a42510",                          // 设备品类
        "cidName": "厨房电器/电饭煲",                     // 设备品类名称
        "productBand": "HEKR"                           // 设备品牌
    },
    ...
]

根据短码和密码查询设备绑定状态¶

curl -X POST \
  'https://user-openapi.hekr.me/deviceBindStatus?type=shortCode' \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '[
    {
        "code": "gzaasUFB",
        "password": "N8EQ21"
    }
]'

参数

参数名	是否可选	参数类型	取值范围	说明
code	True	String		设备短码
password	True	String		设备短码密码

返回

[
    {
        "devTid": "xxxxx",
        "bindKey": "xxxx",
        "deviceName": "",
        "logo": "https://xxxx",
        "cid": "CtV7eTQvd4hJdLF4",
        "cidName": "测试编辑大品类/门磁",
        "categoryName": {
            "zh_CN": "测试编辑大品类/门磁",
            "en_US": "Test Edit Big Category/mc"
        },
        "productName": {
            "zh_CN": "门磁",
            "en_US": "mc"
        },
        "bindToUser": true,
        "forceBind": true
    }
]

字段	含义
devTid	设备devTid
bindKey	设备绑定key
bindToUser	是否已被用户绑定
forceBind	是否可以被强制绑定
cid	设备品类
cidName	设备品类名称
deviceName	设备名字
logo	logo url

批量查询设备状态¶

被查询设备可以不属于同一个型号。

curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/deviceStatusQuery" \
    -d '[{
          "devTid" : "ESP_X01",                         // 设备ID
          // 控制码
          "ctrlKey" : "8971a6b62c0649f6bdc99c"
      },
      {
          "devTid" : "ESP_X02",
          "ctrlKey" : "4571bcb62c0909f6d43c909"
      },
      ...
    ]'

参数

期望查询的设备列表，最少1个，最多512个设备。

返回

> 200
> [
    {
        "devTid": "ESP_X01",
        // 该设备型号的设备参数
        "status": {
            "power": {
                "currentValue": 0,
                "lastValue": 1,
                "reportTimestamp": 1458724895439
        }
    },
    {
        "devTid" : "ESP_X02",
        "status": {
            "light": {
                "currentValue": null,
                "lastValue": 24,
                "reportTimestamp": 1458724895439
            }
        }
    },
    ...
]

注意返回的个数小于等于查询的个数。如果设备仅仅上线但是没有发过devSend（正确的）数据，那么是不存在这个设备快照的。另外如果设备长时间不登录，可能会被当做僵尸设备清理部分数据导致快照不存在。

最佳实践 先判断设备是否在线，如果在线再查询设备快照。如果查询的快照不存在，则忽略。

控制设备¶

对于相同类型(即属于同一个产品)的设备，可以进行群发控制。该接口仅支持json主控和json透传

POST https://user-openapi.hekr.me/deviceControl HTTP/1.1
Content-Type: application/json
Authorization: Bearer {JWT_TOKEN}

{
    "deviceList": [
        {
            "ctrlKey": "a36bd4..." ,
            "subDevTid": "mEc..."
        }
    ],
    "data": { // 支持json主控和json透传，json透传还可以将数据按48透传协议提交，如： {"raw":"48070201020054"}
        "cmdId": 2,
        "Power": 0
    }
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "results": [
        {
            "ctrlKey": "a36bd4...",
            "subDevTid": "mEc...",
            "result": "success"
        }
    ],
    "success": 1,
    "failure": 0
}

请求参数¶

参数	类型	是否必须	含义
deviceList.ctrlKey	String	是	设备ctrlKey
deviceList.subDevTid	String	否	子设备subDevTid，当控制子设备时指定网关ctrlKey + 子设备subDevTid
data	Object	true	设备下发控制命令，请参考产品协议-命令-示例帧

返回体¶

字段	含义
results.ctrlKey	设备ctrlKey
results.subDevTid	子设备subDevTid 当控制非子设备时该值为空
results.result	控制结果, 可能取值 [success, offline, unauthorized] 分别表示成功、设备离线、用户未授权
success	成功控制下发的个数
failure	失败个数

返回非强绑设备属主联系信息¶

该接口用于用户由于尝试绑定, 有归属且非强绑类型的, 设备失败之后查询当前设备的属主信息的接口.

POST https://user-openapi.hekr.me/queryOwner HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
    "devTid": "xxxxx",
    "bindKey" : "xxxxxx"
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "message": "18676717698",
    "phoneNumber": "18676717698",
    "email": "foo@hekr.me",
    "owner": "0138719232",
    "self": false
}

请求体¶

参数名	是否可选	参数类型	取值范围	说明
devTid	必选	String		设备devTid
bindKey	必选	String		绑定码

返回体¶

参数	含义
message	设备属主的联系方式
phoneNumber	设备属主的手机号可能为空
email	设备属主的email
owner	设备属主的uid
self	设备属主是否是自己

获取设备事件记录¶

curl -v -X GET \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  "https://user-openapi.hekr.me/queryHistory?devTid=xxx&ctrlKey=xxx&actions=xxx&start=11111&end=22222&page=0&size=20"

参数¶

参数名	是否可选	参数类型	取值范围	说明
devTid	必选	String		设备ID
ctrlKey	必选	String		设备控制码
actions	必选	String	多个用逗号“,”分开	执行指令
millsOfDay	可选	Long	正整数	要查询天的毫秒数，可以是一天之内任意值，如果该参数填写，则优先生效，跟start和end互斥
start	可选	Long	正整数	查询起始时间毫秒数，默认今天0点
end	可选	Long	正整数	查询结束时间毫秒数，默认当前
startTime	可选	String	yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700	查询起始时间废弃，请使用start
endTime	可选	String	yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700	查询结束时间废弃，请使用end
page	可选	Int	[0, ?]	分页参数，默认为0
size	可选	Int	[1, 20]	分页参数，默认为20

返回¶

> 200
> {
  "content": [
    {
      "objectId": "58b0faf5e4b07bd40b653fb1",
      "finger": "2d25d5dad728",
      "sessionId": "4fc5adfe-8ced-4978-8964-56c9278",
      "action": "appSend",
      "devTid": "xxxxxxxxx",
      "ctrlKey": "xxxxxxxxxxx",
      "msgId": 10,
      "timestamp": 1487993589681,
      "pid": "00000000000",
      "mid": "xxxxxxxx",
      "cid": null,
      "rawRequest": "{xxxxx}",
      "rawResult": null,
      "request": {
        "msgId": 10,
        "action": "appSend",
        "params": {
          "raw": "xxxxxxxxxxxx"
          }
        }
      },
      "result": {
        "msgId": 10,
        "action": "appSendResp",
        "code": 200,
        "desc": null,
        "params": {
          "devTid": null,
          "ctrlKey": null,
          "appTid": null,
          "subDevTid": null,
          "data": null
        }
      }
    }
   ],
  "last": false,
  "totalPages": 2,
  "totalElements": 40,
  "sort": null,
  "first": true,
  "numberOfElements": 20,
  "size": 20,
  "number": 0
}

获取设备上下线记录¶

该API是获取设备事件记录的简化版，只用来获取action为 devLogin 和 devLogout 的数据。

curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/queryDevLoginHistory?devTid=xxxxxx&ctrlKey=tid1234&type=xx&start=111111&end=222222222&page=0&size=20"

参数

参数名	是否可选	参数类型	取值范围	说明
devTid	必选	String		设备ID
ctrlKey	必选	String		设备控制码
type	可选	String		类型 devLogin或者 devLogout
millsOfDay	可选	Long	正整数	要查询天的毫秒数，可以是一天之内任意值，如果该参数填写，则优先生效，跟start和end互斥
start	可选	Long	正整数	查询起始时间毫秒数，默认今天0点
end	可选	Long	正整数	查询结束时间毫秒数，默认当前
startTime	可选	String	yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700	查询起始时间废弃，请使用start
endTime	可选	String	yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700	查询结束时间废弃，请使用end
page	可选	Int	[0, ?]	分页参数，默认为0
size	可选	Int	[1, 20]	分页参数，默认为20

返回

> 200
> {
    "sort" : null,
    "numberOfElements" : 1,
    "last" : true,
    "number" : 0,
    "content" : [
        {
            "time" : 1457946475120,
            "type" : "xxxxxxx"
        },
        ...
    ],
    "totalPages" : 1,
    "first" : true,
    "totalElements" : n,
    "size" : 20
}

返回设备上报帧，下发帧记录¶

该API是获取设备事件记录的简化版，只用来获取action为 devSend 和 appSend 的数据。

curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/devSendAndRecv?devTid=xxxxxx&ctrlKey=tid1234&type=xxx&start=111111111&end=2222222&page=0&size=20"

参数

参数名	是否可选	参数类型	取值范围	说明
devTid	必选	String		设备ID
ctrlKey	必选	String		设备控制码
type	必选	String		类型, 可取值 [devSend, appSend]
millsOfDay	可选	Long	正整数	要查询天的毫秒数，可以是一天之内任意值，如果该参数填写，则优先生效，跟start和end互斥
start	可选	Long	正整数	查询起始时间毫秒数，默认今天0点
end	可选	Long	正整数	查询结束时间毫秒数，默认当前
startTime	可选	String	yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700	查询起始时间废弃，请使用start
endTime	可选	String	yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700	查询结束时间废弃，请使用end
page	可选	Int	[0, ?]	分页参数，默认为0
size	可选	Int	[1, 20]	分页参数，默认为20

返回

{
  "totalPages": 207,
  "totalElements": 207,
  "deviceHistoryList": [
    {
      "time": 1487994014288,
      "type": "devSend",
      "data": {
        "raw": "xxxxxxxxxx"
      }
    },
    ....
  ]
}

查询设备快照¶

该接口返回当前用户下所有设备的快照信息

curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/devSnapshot?page=0&size=20"

参数

参数名	是否可选	参数类型	取值范围	说明
page	可选	Int	[0, ?]	分页参数，默认为0
size	可选	Int	[1, 20]	分页参数，默认为20
devTid	可选	String		设备ID（如果有多个使用英文半角逗号分开）
ctrlKey	可选	String		设备ctrlKey（如果有多个使用英文半角逗号分开）

调用说明

多个ctrlKey使用英文半角逗号分割
多个devTid使用英文半角逗号分割（ctrlKey和devTid是或的关系，也就是说符合的都会查询出来，建议只使用ctrlKey查询）
支持模糊查询
当subDevTid参数不为空时代表该快照为子设备快照

返回

返回该设备快照信息，不指定分页参数默认返回20条

< 200
< [
    {
        "devStatus": "online", // 设备状态，
        "devTid": "c520ea53d373",
        "ctrlKey": "78cefdc033dd35a",
        "subDevTid":null
        "snapshot": {
                "power" : {             // 设备上报参数
                    "currentValue" : 0, // 当前值
                    "lastValue" : 0,    // 上次值
                    "reportTimestamp" : NumberLong("1479709915369") // 上报时间
                },
        ...
        },
        "lastOprationTime": 0 // 最后操作时间
    },
    {
        "devStatus": "offline",
        "devTid": "c520ea64d373",
        "ctrlKey": "78cefdc01dd35a",
        "subDevTid":"0003b1b000000000"
        "snapshot": {
                "channel_1" : {
                        "currentValue" : 1,
                        "lastValue" : 2,
                        "reportTimestamp" : NumberLong("1479802058250")
                },
                ...

        },
        "lastOprationTime": 1472020160281
    },
    ...
]

更改WiFi设备的wifi和密码¶

注意，之后该设备信息中的features字段中包含了changeWIFI的字段的设备才支持此功能。

Request¶

POST https://user-openapi.hekr.me/device/{ctrlKey}/wifi HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

{
    "ssid":"wifi-ssid",
    "password":"加密后的密码"
}

获取设备的功能¶

Request¶

GET https://user-openapi.hekr.me/device/{ctrlKey}/features HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {JWT_TOKEN}

Response¶

HTTP/1.1 200 OK

{
    "changeWIFI":{ // 设备变更wifi和密码
        "status":0 // 0，默认值（设备正常登录后上报）， 1:设备变更成功，2:云端给设备下发了变更wifi和密码的指令， 3:收到了response，4:ssid错误（可能信号太弱，找不到ssid），5:密码错误，6:其他错误
    }
}

设备变更wifi和密码¶

考虑到通过长连接（websockt或者tcp可能会有链接断开，收不到变更结果问题，采用http（s）方式）。如果 changeWIFI.status 的值为 2或者3 则客户端应该在 15s 内持续拉取，如果一直为 2或者3 则为失败。如果拉取到值为大于等于4 则直接认为失败，如果拉取到的值为 1 则是成功。

企业查询设备事件记录¶

curl -v -X GET \
  -H "Authorization: key={serverKey}" \
  "https://user-openapi.hekr.me/enterprise/packages?prodKey=xxxx&actions=xxx&millsOfDay=11111111&page=0&size=20"

参数¶

参数名	是否可选	参数类型	取值范围	说明
prodKey	必填	String		产品密钥
actions	可选	String	多个用逗号“,”分开	执行指令，参见 Actions
millsOfDay	可选	long	毫秒时间戳	要查询日期的开始时间毫秒时间戳，比如要查2018-08-01这天的数据，则应该填写这天开始的时间戳 1533052800000
page	可选	Int	[0, ?]	分页参数，默认为0
size	可选	Int	[1, 1000]	分页参数，默认为20

返回¶

[
    {
        "action": "reportDevInfo",
        "devTid": "08acdb3521884fd5ac212a33a7d8fe4a",
        "ctrlKey": "5c88f3ec410b4baaab06a28877542bee",
        "msgId": 987,
        "timestamp": 1508816856444,
        "pid": "xxxx",//产品制造商的pid
        "bindPid": "xxxxx", // 用户所属企业的pid
        "mid": "lhFr3irxljal",
        "cid": null,
        "rawRequest": "{\"msgId\":987,\"action\":\"reportDevInfo\",\"params\":{\"devTid\":\"xzxxxxxx\",\"mid\":\"lhFr3irxljal\",\"workMode\":1,\"MAC\":\"xxxxxx\",\"tokenType\":2,\"binVer\":\"4.0.1.8\",\"binType\":\"A\",\"SDKVer\":\"4.0.2\",\"serviceHost\":\"test-hub.hekr.me\",\"servicePort\":83,\"SSID\":\"NULL\"}}",
        "rawResult": null,
        "request": {
            "msgId": 987,
            "action": "reportDevInfo",
            "params": {
                "mac": "xxxx",
                "sdkver": "4.0.2",
                "ssid": "hekr",
                "devTid": "xxxx",
                "mid": "lhFr3irxljal",
                "workMode": 1,
                "MAC": "xxxx",
                "tokenType": 2,
                "binVer": "4.0.1.8",
                "binType": "A",
                "SDKVer": "4.0.2",
                "serviceHost": "hub.hekr.me",
                "servicePort": 83
            }
        },
        "result": null
    }
]

Actions¶

action	说明
devSend	设备发送
appSend	控制发送
devLogin	设备登录
devLogout	设备登出
appLogin	APP 登录
appLogout	APP 登出
heartbeat	心跳
devUpgrade	设备升级
gatewayLogin	网关登录
addSubDev	添加子设备
devDelete	删除设备
devDistribution	控制设备进入配网模式

错误码表¶

错误码	提示信息	中文释义	可能造成的原因
5200000, 620000	Success	成功	无
5400000	Error	未知错误	该行下面的以5400、6400开头的错误码需要单独处理
5400002	App repeat login error	app重复登录	同一个appTid的app重复登录
5400003	appTid can not be empty	appTid不能为空	appTid不能为空
5400004	Authorization already exists	授权关系已存在	授权关系已存在
5400005	Authorization does not exist	授权关系不存在	授权关系不存在
5400006	Bind failed due to network error	因网络原因绑定失败	因网络原因绑定失败
5400007	Bind failed due to timeout error	因超时原因绑定失败	因超时原因绑定失败
5400008	Can not bind other manufacture's device	无法绑定其他厂商设备	非公版用户无法绑定非该pid设备
5400009	Modified user profile failed	修改用户档案失败	修改用户档案失败
5400010	Check verify code error	校验code失败	校验code失败
5400011	You have reached your device's authorization limits	设备授权次数达到上限	设备授权次数达到上限，无法再次授权
5400012	Bind failed due to internal error	因内部错误绑定失败	因内部错误绑定失败，一般是因为bindKey不对或者是devTid不对
5400013	Bind failed due to repeat bind	因重复绑定绑定失败	因重复绑定绑定失败
5400014	Device does not belong to user	设备不属于用户	设备不再属于该用户
5400015	No such instruction error	没有这样的指令	没有这样的指令
5400016	Device can not repeat login	设备无法重复登录	设备无法同时登录
5400017	devTid can not be empty	devTid不能为空	devTid不能为空
5400018	Create timer task failed due to counts reach limit	创建定时预约次数达到上限	创建定时预约次数达到上限
5400019	Instruction expired	授权的指令已过期	授权的指令已过期
5400020	Instruction not support	不支持该指令	不支持该指令，可能是指令填错了
5400021	Invalid email token	不合法的邮件token	不合法的邮件token
5400022	Invalid old password	不合法的旧密码	不合法的旧密码
5400023	Invalid verify code	不合法的校验code	不合法的校验code
5400024	Device does not found due to internal error, please reconnect	由于内部错误设备无法找到，请重连
5400025	No such manufacture id	不存在该pid	不存在该pid
5400026	No permission to access the instruction	没有对该指令的权限	没有对该指令的权限
5400027	Template with given id does not exist	指定模板不存在	指定模板不存在
5400028	Device does not found due to incorrect status	由于内部不正确的状态导致设备无法被找到
5400035	TaskId does not exist	指定任务不存在	指定任务不存在
5400036	Can not create duplicate template	无法创建重复模板	无法创建重复模板
5400037	devTid not match	设备id 不匹配	报文填写的devTid与登录设备的devTid不一致
5400039	User does not exist	用户不存在	用户不存在
5400045		短码或者短码密码错误
5400046		短码不足（系统错误）
5400047		无权修改其他用户绑定设备
5400043	Device can not force bind	设备无法强制绑定	设备无法强制绑定
5500000	Internal error	内部错误	内部服务错误
6400001	Reverse auth template with given id does not exist	指定id的反向注册申请不存在	请求已经被同意或拒绝
6400002	Invalid reverse authorization request	不合法的反向授权请求	设备此时已经不属于该授权者；调用者不是授权者；反向授权请求id错误
6400003	Only owner can authorize	只有属主可以授权设备给其他人	非属主尝试授权设备给其他人
6400004	Device with given devTid does not exist	指定devTid的设备不存在	操作不存在的设备
6400005	Reached the maximum number of device the folder can hold	达到文件夹所能容纳设备数量的上限	达到文件夹所能容纳设备数量的上限
6400006	Can not create duplicate template folder	无法创建同名文件夹	创建同名文件夹
6400007	Folder with given id does not exist	指定id的文件夹不存在	操作不存在的文件夹
6400008	Reached the maximum number of folder the user can create	达到创建文件夹数量上限	达到创建文件夹数量上限
6400009	Can not remove root folder	无法删除根目录	删除根目录
6400010	Can not rename root folder	无法给根目录改名	给根目录改名
6400011	Rule with given id does not exist	指定的规则不存在	操作不存在的规则
6400012	Scheduler task with given id does not exist	指定的定时预约任务不存在	操作不存在的定时预约任务
6400013	Can not create duplicate rule	无法创建相同的规则	创建相同的规则
6400014	Can not create duplicate scheduler task	无法创建相同的定时预约	创建相同的定时预约
6400015	Invalid prodPubKey	不合法的产品公共秘钥	不合法的产品公共秘钥
6400016	Has no privilege do that	没有权限这样做	操作没有权限
6400017	Invalid Param {0}	参数错误	请求参数错误
6400018	Cloud storage file with given name does not exist	指定的网盘文件不存在	操作不存在的网盘文件
6400020	Can not find this infrared code	找不到这个红外码	操作不存在的红外码
6400021	Infrared code request without response	红外服务请求出错
6400022	Can not find instruction set	无法找到指令集	操作不存在的指令集
6400023	Request params not supported	参数不支持	请求参数错误
6400024	Translating Json to String failure	解析json失败
6400025	Scheduler not supported	不支持定时预约	该设备不支持定时预约功能
6500001	Delete cloud storage file failed	删除网盘文件失败	网盘操作失败
6500002	Upload cloud storage file failed	上传网盘文件失败	网盘操作失败
6500003	Server use httpClient invoke failed	http网络调用失败	http调用失败