# 设备管理 ## 设备信息 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :------------- | :------- | :------------ | | deviceList | Array\ | N | 设备列表 | deviceList 列表 item 说明： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :-------------------------------------------| | name | String | N | 设备名称 | | deviceId | String | N | 设备 id | | apikey | String | N | 设备所属用户的 apikey | | extra | Object | N | factoryDevice 的 extra 字段中的内容 | | brandName | String | N | 品牌名称 | | brandLogo | String | N | 品牌 Logo url | | showBrand | Boolean | N | 是否显示品牌 | | productModel | String | N | 产品型号名称 | | devGroups | Array\ | Y | 设备所属的群组信息列表 | | tags | Object | Y | 标签对象，里面是存储的是自定义字符串，服务器只负责透传 | | devConfig | Object | Y | 设备端配置信息，来源于 factorydevices 表的 deviceConfig | | settings | Object | Y | 用户设置 | | family | Object | N | 设备的家庭设置 | | sharedBy | Object | Y | 如果设备是别人分享过来的，就会有该属性 | | shareTo | Array\ | Y | 被分享用户的列表 | | devicekey | String | N | 设备出厂的apikey | | online |Boolean | N | 在线状态 | | params |Object | Y | 设备的状态属性 | | gsmInfoData |Object | Y | GSM 设备的卡状态对象 | extra 说明： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :-------------------------------------------| | model | String | N | 固件名称 | | ui | String | N | UI 的名称 | | uiid | Int | N | UI 的 id | | description | Object | N | 出厂信息备注 | | manufacturer | String | N | 制造商 | | mac | String | N | mac 地址 | | apmac | String | N | ap mac 地址(设备热点的地址) | | modelInfo | String | N | 产品型号 id | | brandId | String | N | 品牌 id | | chipId | String | N | 芯片 id | settings 说明: | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :-------------------------------------------| | opsNotify | Int | Y | 操作变化是否通知用户(默认 0)0=不通知 1=通知 | | opsHistory | Int | Y | 是否记录操作历史(默认 1)0=不记录 1=记录 | | alarmNotify | Int | Y | 是否发送告警信息(默认 1)0=不发送 1=发送 | devGroups 说明: | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :------ | :------- | :--------------| | type | Int | Y | 1 代表设备群组 | | groupId | String | Y | 所属群组的 id | sharedBy 列表 item 说明： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :-------------------------------------------| | permit | Int | N | 用户的权限值 默认为 0 | | apikey | String | N | 接收设备分享的用户账号 ID 标识 | | phoneNumber | String | Y | 设备所属用户手机号 | | email | String | Y | 设备所属用户 email | | nickname | String | Y | 设备所属用户的昵称 | | comment | String | Y | 分享时的备注 | | shareTime | Long | Y | GMT 标准时间，毫秒数，主要用来在客户端显示排序 | devConfig 说明(摄像头)： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :------------------| | p2pServerName | Int | Y | 服务器名称 | | p2pAccout | String | Y | 账号 | | p2pLicense | String | Y | license | family 说明： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :------------------| | familyId | String | Y | 家庭 id | | index | Int | Y | 设备排序号 可能存在负数 | | roomId | String | Y | 所属房间 id | ## device.getAllThings({ lang, familyId, num, beginIndex }) 功能：获取Thing列表(仅指定一页) 说明：Thing包括： - 设备(自己的和别人分享的) - 设备群组 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | |:-----------|:-------|:-----|:-----------------------------| | lang | String | Y | cn 返回中文信息，en 返回英文信息，默认 en | | familyId | String | Y | 家庭 id，不填则默认为当前家庭 | | num | Int | Y | 获取的数量，默认为 30，0 表示获取所有 | | beginIndex | Int | Y | 从哪个序号开始获取列表数据，不填则默认为-9999999 | 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | |:-----------|:-------|:-----|:-----------------------------| | thingList | Array | N | Thing 列表 | | total | Int | N | Thing 总数量 | thingList 列表 item 说明: | 名称 | 类型 | 允许为空 | 说明 | | :---------------| :------ | :------- | :-------------------- | | itemType | Int | N | item 的类型 1=用户自己的设备 2=别人分享的设备 3=自己的群组 | | itemData | Array | N | 根据 itemType 有不同的结构 1 和 2 时参见[device.getAllThings]接口中的 deviceList 列表 item 说明，3 时参见[device.getGroups]接口中的 groupList 列表 item 说明 | | index | Int | N | 排序号 | ## device.getAllThingsAllPages({ lang, familyId, num, beginIndex }) 功能：获取Thing列表(所有页) 传参、返回与[device.getAllThings]接口一致 ## device.getThings({thingList}) 功能：获取指定 Thing 列表信息 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :------- | :--------- | :--------------------| | thingList | Array | N | 需要获取的 thing 列表列表数量必须大于 0，小于等于 10 | thingList item 说明: | 名称 | 类型 | 允许为空 | 说明 | | :------------ | :----- | :------- | :-------------------- | | itemType | Int | N | item 的类型 1=用户自己的设备 2=别人分享的设备 3=自己的群组 | | id | String | N | thing 对应的 id,itemType 为 1 或 2 时为设备的 deviceid,itemType 为 3 或 4 时为群组 id | 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :--------------- | :----- | :------- | :--------------- | | thingList | Array | N | Thing 列表信息 | ## device.getThingStatus({type,id,params}) 功能：获取设备或群组状态 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :-------------------------------------------- | | type | Int | N | 要获取设备还是群组 1=设备 2=群组 | | id | String | N | type=1 时为设备的 deviceid type=2 时为群组 id | | params | String | Y | 需要获取的状态参数 | params 说明： - 调用方可以指定只获取特定的状态参数，以"|"间隔，再做 URL 转换 - 如果要获取设备或群组所有的状态，params 参数为空即可 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :------------- | :-------- | :------- | :--------------------| | params | Object | N | 设备或群组的状态属性 | ## device.setThingStatus({type,id,params}) 功能：更新设备或群组状态 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :-------------------------------------------- | | type | Int | N | 要获取设备还是群组 1=设备 2=群组 | | id | String | N | type=1 时为设备的 device id, type=2 时为群组 id | | params | String | N | 需要更新的状态参数 | 响应的 data 参数：空对象 ## device.setAllThingStatus({thingList,timeout}) 功能：批量更新设备或群组的状态 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :------------| :------- | :-------------------------------------------- | | thingList | Array\ | N | 要更新的 thing 列表，长度大于 0，小于等于 10，客户端需保证列表中的 id 是唯一的，否则报错 | | timeout | String | Y | 等待所有设备响应的时间，单位毫秒， 0 <= timeout <= 8000 ，如果不填则默认为 0，表示立即返回 | thingList item 的说明: | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :-------------------------------| | type | Int | N | 要获取设备还是群组 1=设备 2=群组 | | id | String | N | type=1 时为设备的 deviceid type=2 时为群组 id | | params | Object | N | 要更新的状态参数 | 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :------------- | :------------ | :------- | :------------------------| | respList | Array\ | N | 每个 thing 的响应结果列表 | respList item 的说明: | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :-------------------------------| | type | Int | N | 要获取设备还是群组 1=设备 2=群组 | | id | String | N | type=1 时为设备的 deviceid type=2 时为群组 id | | error | Int | N | 响应错误码，0 代表无错误如果 type=2，则 error 固定为 0 如果调用时 timeout 为 0，则 error 固定为 0 | ## device.addDevice({name,deviceId,settings,ifrCode,deviceKey,chipId,familyId,roomId,sort}) 功能：新增普通的 WiFi 设备 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :-----------| :------- | :-------------------------------------------- | | name | String | N | 设备名称 | | deviceId | String | N | 设备 id | | settings | Object | Y | 用户设置 如果没有则采用默认值 | | ifrCode | String | Y | 红外设备的码值 | | deviceKey | String | N | 设备 apikey | | chipId | String | Y | 设备的芯片 id | | familyId | String | Y | 设备所属的家庭 id，如果为空，表示添加到当前家庭 | | roomId | String | Y | 设备所属的房间 id，如果为空，表示添加到[未分配]下 | | sort | Int | Y | 给新设备分配序号的方式，如果为空则默认为 1 1=更小的序号 2=更大的序号 | settings 的说明: | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :----------------------------------------| | opsNotify | Int | Y | 操作变化是否通知用户(默认 0)0=不通知 1=通知 | | opsHistory | Int | Y | 是否记录操作历史(默认 1)0=不记录 1=记录 | | alarmNotify | Int | Y | 是否发送告警信息(默认 1)0=不发送 1=发送 | 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :-------------------------------| | itemType | Int | N | item 的类型，这里固定为 1 | | itemData | Object | N | 见[device.getThings]接口中的 deviceList 列表 item 说明 | | index | Int | N | 排序号 | 说明：如果报 30017 错误，原因是设备所属的品牌并没有授权给你的 APPID，目前酷宅自有品牌是免费授权的，但其他厂商的品牌会保留使用权限，授权相关的问题可在微信对接群咨询我司市场部销售人员 ## device.addGSMDevice({id,name,familyId,roomId,sort}) 功能：新增 GSM 设备 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :-----------| :------- | :-------------------------------------------- | | id | String | N | 从扫描设备上的二维码 URL 中获取设备 gsmId | | name | String | N | 设备名称 | | familyId | String | Y | 设备所属的家庭 id，如果为空，表示添加到当前家庭 | | roomId | String | Y | 设备所属的房间 id，如果为空，表示添加到[未分配]下 | | sort | Int | Y | 给新设备分配序号的方式，如果为空则默认为 1 1=更小的序号 2=更大的序号 | 备注：应用扫描设备上的二维码可以获取到一个 URL 格式的字符串，URL 格式： https://api.coolkit.cc:8080/api/user/device/addGsm?id=348512d49379bb0acace4598e14fc450，id是后面那个参数，请注意域名是有可能改变的，但 "/addGsm?id={gsmId}" 不会改变 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :------------- | :------------ | :------- | :------------------------| | thingList | Array | N | 每个 thing 的响应结果列表 | thingList item 的说明: | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :-------------------------------| | itemType | Int | N | item 的类型，这里固定为 1 | | itemData | Object | N | 参见[device.getThings]接口中的 deviceList 列表 item 说明 | | index | Int | N | 排序号 | ## device.setDeviceInfo({deviceId,newName,newRoomId}) 功能：更新设备的名称/房间信息 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :-----------| :------- | :-------------- | | deviceId | String | N | 设备 id | | newName | String | Y | 设备名称 | | newRoomId | String | Y | 房间 id | 响应的 data 参数：空对象 ## device.delDevice({id}) 功能：删除设备 说明：删除其他人分享给自己的设备也是通过此接口删除的 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :-----------| :------- | :---------- | | id | String | N | 删除的设备 id | 响应的 data 参数：空对象 ## device.setDeviceTags({deviceId,type,tags}) 功能：修改设备标签，可修改子通道名称，可按照自己想法实现一些特定功能 说明：需要将完整的 tags 对象传过来，服务端整体覆盖原有的值 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :-----------| :------- | :-------------------------------------------- | | deviceId | String | N | 设备 id | | type | String | Y | 修改类型，不填则默认为 replace，replace=覆盖，merge=合并 | | tags | Object | N | 设备标签 | 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :---------------| :----------| :------- | :-------------------| | updatedThing | Object | N | 更新后的 thing 数据 | ## device.getGroups({lang}) 功能：获取设备群组列表 说明： - 设备群组与设备一同排序 - 只获取当前家庭下的设备群组列表 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :-----------| :------- | :---------------------------------------| | lang | String | Y | cn 返回中文信息，en 返回英文信息，默认 en | 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :-----------| :------- | :------------------| | groupList | Array | N | 群组列表 | groupList 列表 item 说明: | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :-------------------------------| | itemType | Int | N | item 的类型，这里固定为 3 | | itemData | Object | N | 群组信息 | | index | Int | N | 排序号 | itemData 说明: | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :------------| :------- | :-------------------------------------------- | | id | String | N | 群组 id | | name | String | N | 群组名称 | | mainDeviceId | String | N | 群组的主设备 id | | family | Object | N | 群组的家庭设置 | | params | Object | N | 群组状态 | family 说明: | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :------------| :------- | :--------- | | familyId | String | N | 家庭id | | index | Int | N | 群组排序号 | | roomid | String | Y | 房间id | ## device.addGroup({name,mainDeviceId,familyId,roomId,sort,deviceidList}) 功能：新增设备群组 说明：如果使用别人分享的设备作为主设备来新增群组，则当分享撤销时，该群组也会被一并删除 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :------------| :------- | :-------------------------------------------- | | name | String | N | 群组名称，限长 50 个字符 | | mainDeviceId | String | N | 群组的主设备 id | | familyId | String | Y | 群组所属的家庭 id，如果为空，表示添加到当前家庭 | | roomId | String | Y | 群组所属的房间 id，如果为空，表示添加到[未分配]下 | | sort | Int | Y | 给新群组分配序号的方式 1=更小的序号 2=更大的序号 | | deviceidList | Array\ | Y | 创建群组时加入到该群组的设备的 id 列表 | 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :----- | :------- | :-------------------------------| | itemType | Int | N | item 的类型，这里固定为 3 | | itemData | Object | N | 见[device.getGroups]接口中的 itemData 说明 | | index | Int | N | 排序号 | ## device.setGroup({id,newName}) 功能：修改设备群组 说明：目前此接口只能修改群组的名称 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :------------| :------- | :-------------------------------------------- | | id | String | N | 群组 id | | newName | String | N | 群组新名称，限长 50 个字符 | 响应的 data 参数：空对象 ## device.delGroup({id}) 功能：删除设备群组 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :------------| :------- | :---------| | id | String | N | 群组 id | 响应的 data 参数：空对象 ## device.setGroupStatus({id，params}) 功能：更改群组状态 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :------------| :------- | :-------------------------------------------- | | id | String | N | 群组 id | | params | Object | N | 群组状态 | 响应的 data 参数：空对象 ## device.coverGroupDeviceList({id，coverDeviceidList}) 功能：更新设备群组的设备列表 说明：该接口会根据传入的设备列表，对群组内的设备做全量覆盖 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :------------| :------- | :------------- | | id | String | N | 群组 id | | coverDeviceidList | Array\ | N | 设备 id 列表 | 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :-------------- | :------- | :-------------------------------| | updatedThingList | Array | N | 更新后的 thing 数据 | ## device.share({deviceidList,user,permit,comment,shareType}) 功能：设备分享 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :------------ | :------------| :------- | :------------- | | deviceidList | Array | N | 设备 id 列表 | | user | Object | N | 用户信息 | | permit | Int | N | 权限值定义：1：新增定时器；2：修改定时器；4：删除定时器；8：启用定时器 | | comment | String | Y | 分享备注 | | shareType | Int | Y | 分享方式，不填则默认为 1，1=静默分享，不需要被分享的用户同意 | user 说明： | 名称 | 类型 | 允许为空 | 说明 | | :------------ | :------------| :------- | :------------- | | countryCode | String | N | 地区区号 | | phoneNumber | String | Y | 用户手机号码 ,必须以国家区号开头，比如"+86" | | email | String | Y | 用户 email，手机号码和 email 不能同时为空，优先检查手机号码 | 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :-------------- | :------- | :-------------------------------| | updatedThingList | Array | N | 更新后的 thing 数据 | ## device.setShare({deviceId,apikey,permit}) 功能：修改设备分享的权限 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :------------ | :------------| :------- | :------------- | | deviceId | String | N | 设备 id | | apikey | String | N | 接收设备分享的用户账号 ID 标识 | | permit | Int | N | 修改的权限，见[device.share]接口参数的说明 | 备注：apikey 参数来自于设备的详情信息，请在文档中搜索 shareTo 这个参数 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :-------------- | :------- | :------------------| | updatedThingList | Array | N | 更新后的 thing 数据 | ## device.delShare({deviceId,apikey}) 功能：取消设备分享 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :------------ | :------------| :------- | :------------- | | deviceId | String | N | 设备 id | | apikey | String | N | 要修改分享权限的用户 apikey | 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :-------------- | :------- | :------------------| | updatedThingList | Array | N | 更新后的 thing 数据 | ## device.getOperationHistory({deviceId,from,num}) 功能：获取设备的操作历史记录 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :------------ | :------------| :------- | :------------- | | deviceid | String | N | 设备 id | | from | Long | Y | 时间戳，表示从什么时间开始，获取更早之前的消息，不填则默认为当前时间 | | num | Int | Y | 最多拉取的消息数量，1<= num <= 30，不填则默认为 30 | 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :---------- | :------------| :------- | :------------------| | histories | Array | N | 历史记录列表 | histories item 说明: | 名称 | 类型 | 允许为空 | 说明 | | :------------ | :-------------| :------- | :------------- | | deviceId | String | N | 设备 id | | userAgent | String | Y | 用户区分是设备端还是 app 端的操作 | | opsSwitchs | String | Y | 记录被操作的通道值。如果是单通道就只有 1 个元素，值为"switch" | | request | String | N | 原始的 request 请求 | | opsAccount | String | Y | 如果是 app 端的操作，返回操作人的账号(有可能是分享用户的)| | opsTime | Long | N | 操作时间戳，精确到毫秒 | ## device.delOperationHistory({deviceId}) 功能：清除设备的操作历史记录 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :------------ | :------------| :------- | :------------- | | deviceId | String | N | 设备 id | 响应的 data 参数：空对象 ## device.getOTAInfo({deviceInfoList}) 功能：查询设备的 OTA 信息 参数类型：Object 参数内容： | 名称 | 类型 | 允许为空 | 说明 | | :----------------- | :------------| :--------- | :------------- | | deviceInfoList | String | N | 要查询的设备信息列表，列表长度大于 0，小于等于 30 | deviceInfoList 列表 item 说明： | 名称 | 类型 | 允许为空 | 说明 | | :------------ | :------------| :------- | :------------- | | deviceId | String | N | 设备 id | | model | String | N | The device model | | version | String | N | The device current version | 响应的 data 参数： | 名称 | 类型 | 允许为空 | 说明 | | :------------ | :------------| :------- | :------------- | | otaInfoList | Array\ | N | OTA 信息列表，如果设备有升级的信息，则会在这个列表中 | otaInfoList 列表 item 说明： | 名称 | 类型 | 允许为空 | 说明 | | :------------ | :------------| :------- | :------------- | | deviceId | String | N | 设备ID | | version | String | N | 设备的模块型号 | | binList | String | N | 不同分区的 bin 列表 | | type | String | N | (保留字段) | | forceTime | String | N | (保留字段) | binList 列表 item 说明： | 名称 | 类型 | 允许为空 | 说明 | | :------------ | :------------| :------- | :------------- | | name | String | N | 下载文件名称 | | downloadUrl | String | N | 下载地址 | | digest | String | Y | 文件 HASH 摘要(SHA256) |