设备管理
设备绑定¶
不通设备类型绑定方式不一样,下面是每一种设备类型的具体绑定方式,一定要按照设备类型操作。
绑定 WIFI 设备¶
绑定 WIFI,需要按照以下步骤,具体参见 IOS 和Android,无需关心过程。
- 使设备进入配网模式
- 获取
PINCode
- 发送配网指令给设备(请使用SDK)
- 设备联网
- 设备发送绑定信息到云端
根据devTid和bindKey绑定设备¶
每个网关设备/透传设备上都有一个唯一的二维码,扫描二维码,得到一个url,类似
并根据得到的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 | |
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调用失败 |