设备管理
## 设备管理
### 1. 接口列表
|接口功能|请求方式|API|
|-|-|-|
|[设备添加](#1)|HTTP|add_device|
|[设备删除](#2)|HTTP|delete_device|
|[设备同步](#3)|HTTP|sync_device|
|[获取用户设备列表](#4)|Firebase Firestore|```db.collection('users').document('<user_id>').collection('houses').document('<house_id>').collection('devices').get()```|
|[监听用户设备列表](#4)|Firebase Firestore|```db.collection('users').document('<user_id>').collection('houses').document('<house_id>').collection('devices').snapshots()```|
|[执行设备指令](#5)|HTTP|execute_device|
|[修改设备名称](#6)|HTTP|update_device_name|
|[修改设备所在房间](#7)|HTTP|update_device_room|
|[修改设备密码](#8)|HTTP|update_device_password|
|[获取设备操作日志](#9)|HTTP|list_device_operations|
|[获取设备告警列表](#10)|HTTP|list_device_alarms|
|[获取设备历史状态列表](#11)|HTTP|list_device_datas, 用于环境检测类设备，保存设备历史状态数据，比如温度/湿度/亮度|
|[获取所有支持的设备类型列表](#12)|HTTP|list_support_devices|
<span id="1"></span>
### 2. 设备添加（绑定）
- 请求方式: HTTP POST
- URL
```{base_url}/add_device```
- Body Para
|参数名称|类型|描述|
|-|-|-|
|owner_id|String|房子的owner的user_id|
|house_id|String|房间id|
|device_serial|String|设备序列号|
|device_code|String|设备密码(验证码)，对于物联网关默认是序列号的后面六位数字，对于萤石摄像头，device_code直接印在设备上面|
|device_vendor|String|设备归属的厂商，比如：devices.vendor.WULIAN|
|device_type|String|（可选）设备类型，比如：devices.type.GATEWAY_01|
>d owner_id和house_id可以不提供，如果没有提供owner_id和house_id，后台将从用户当前所在的house字段，提取owner_id和house_id。建议直接提供这两个参数。
- 返回格式说明
code/message字段具体参考 《概述》章节，data字段的内容，为设备添加成功后的设备ID
```
{
"code": 200,
"data": {
"device_id": ...
},
"message": "success"
}
```
<span id="2"></span>
### 3. 设备删除（解绑）
- 请求方式: HTTP POST
- URL
```{base_url}/delete_device```
- Body Para
|参数名称|类型|描述|
|-|-|-|
|owner_id|String|房子的owner的user_id|
|house_id|String|房间id|
|device_id|String|设备id|
>d owner_id和house_id可以不提供，如果没有提供owner_id和house_id，后台将从用户当前所在的house字段，提取owner_id和house_id。建议直接提供这两个参数。
- 返回格式说明
code/message字段具体参考 《概述》章节
```
{
"code": 200,
"data": null,
"message": "success"
}
```
<span id="3"></span>
### 4. 设备同步
- 请求方式: HTTP POST
- URL
```{base_url}/sync_device```
- Body Para
|参数名称|类型|描述|
|-|-|-|
|owner_id|String|房子的owner的user_id|
|house_id|String|房间id|
|device_id|String|设备id|
>d owner_id和house_id可以不提供，如果没有提供owner_id和house_id，后台将从用户当前所在的house字段，提取owner_id和house_id。建议直接提供这两个参数。
- 返回格式说明
code/message字段具体参考 《概述》章节
```
{
"code": 200,
"data": null,
"message": "success"
}
```
>w 只有gw类型的设备才支持sync_device接口
<span id="4"></span>
### 5. 获取/监听用户设备列表 （Flutter例子）：
- 请求方式：Firestore接口
```
FirebaseFirestore.instance.collection('<collection_name>').snapshots()
```
- 请求需要参数
用户所有设备的collection, 的访问路径如下：
```
FirebaseFirestore.instance
.collection("users").document("<user_id>")
.collection("houses").document("<house_id>")
.collection("devices")
```
需要的参数：
（1）user_id: 用户的id, 这里是指房子的owner的user_id
（2）house_id: 想要访问的用户的houses的id
- 例子：
```
class UserInformation extends StatelessWidget {
@override
Widget build(BuildContext context) {
CollectionReference devices = FirebaseFirestore.instance.collection('users').document('<user_id>').collection('houses').document('<house_id>').collection('devices');
return StreamBuilder<QuerySnapshot>(
stream: devices.snapshots(),
builder: (BuildContext context, AsyncSnapshot<QuerySnapshot> snapshot) {
if (snapshot.hasError) {
return Text('Something went wrong');
}
if (snapshot.connectionState == ConnectionState.waiting) {
return Text("Loading");
}
return new ListView(
children: snapshot.data.documents.map((DocumentSnapshot document) {
return new ListTile(
title: new Text(document.data()['name']['nicknames'][0]),
subtitle: new Text(document.data()['type']),
);
}).toList(),
);
},
);
}
}
```
<span id="5"></span>
### 6. 执行设备指令
- 请求方式: HTTP POST
- URL
```{base_url}/execute_device```
- Body Para
|参数名称|类型|描述|
|-|-|-|
|owner_id|String|房子的owner的user_id|
|house_id|String|房子的ID|
|device_id|String|设备ID|
|executions|list<execute_object>|设备ID|
>d owner_id和house_id可以不提供，如果没有提供owner_id和house_id，后台将从用户当前所在的house字段，提取owner_id和house_id。建议直接提供这两个参数。
<b>execution object字段</b>
|参数名称|类型|描述|
|-|-|-|
|challenge|Object|{pin: xxx}，认证信息|
|command|String|执行的命令类型|
|params|Object|执行命令的参数，根据不同的命令类型，有所不同|
- 返回格式说明
code/message字段具体参考 《概述》章节
```
{
"code": 200,
"data": null,
"message": "success"
}
```
<span id="6"></span>
### 7. 修改设备昵称
- 请求方式: HTTP POST
- URL
```{base_url}/update_device_name```
- Body Para
|参数名称|类型|描述|
|-|-|-|
|owner_id|String|房子的owner的user_id|
|house_id|String|房子的ID|
|device_id|String|设备ID|
|device_name|String|设备昵称|
>d owner_id和house_id可以不提供，如果没有提供owner_id和house_id，后台将从用户当前所在的house字段，提取owner_id和house_id。建议直接提供这两个参数。
- 返回格式说明
code/message字段具体参考 《概述》章节
```
{
"code": 200,
"data": null,
"message": "success"
}
```
<span id="7"></span>
### 8. 修改设备归属房间
- 请求方式: HTTP POST
- URL
```{base_url}/update_device_room```
- Body Para
|参数名称|类型|描述|
|-|-|-|
|owner_id|String|房子的owner的user_id|
|house_id|String|房子的ID|
|device_id|String|设备ID|
|room_id|String|房间ID，如果提供了room_id,将归属设备到该房间，如果没有提供room_id, 将设备移出该房间|
>d owner_id和house_id可以不提供，如果没有提供owner_id和house_id，后台将从用户当前所在的house字段，提取owner_id和house_id。建议直接提供这两个参数。
>d 关于 room_id 参数，如果提供了room_id,将归属设备到该房间，如果没有提供room_id, 将设备移出该房间
- 返回格式说明
code/message字段具体参考 《概述》章节
```
{
"code": 200,
"data": null,
"message": "success"
}
```
<span id="8"></span>
### 9. 修改设备密码
- 请求方式: HTTP POST
- URL
```{base_url}/update_device_password```
- Body Para
|参数名称|类型|描述|
|-|-|-|
|owner_id|String|房子的owner的user_id|
|house_id|String|房子的ID|
|device_id|String|设备ID|
|device_password|String|设备新的密码|
|device_vendor|String|设备归属的厂商，比如：devices.vendor.WULIAN|
- 返回格式说明
code/message字段具体参考 《概述》章节
```
{
"code": 200,
"data": null,
"message": "success"
}
```
>d 目前只有物联的网关设备支持修改设备密码操作
<span id="9"></span>
### 10. 获取设备操作日志
- 请求方式: HTTP POST
- URL
```{base_url}/list_device_operations```
- Body Para
|参数名称|类型|描述|
|-|-|-|
|owner_id|String|房子的owner的user_id|
|house_id|String|房子的ID|
|device_id|String|设备ID|
>d owner_id和house_id可以不提供，如果没有提供owner_id和house_id，后台将从用户当前所在的house字段，提取owner_id和house_id。建议直接提供这两个参数。
- 返回格式说明
code/message字段具体参考 《概述》章节
```
{
"code": 200,
"data": [
{
"time": <时间戳，13位，毫秒>,
"operation": <操作描述>
}
],
"message": "success"
}
```
<span id="10"></span>
### 11. 获取设备告警列表
- 请求方式: HTTP POST
- URL
```{base_url}/list_device_alarms```
- Body Para
|参数名称|类型|描述|
|-|-|-|
|owner_id|String|房子的owner的user_id|
|house_id|String|房子的ID|
|device_id|String|设备ID|
>d owner_id和house_id可以不提供，如果没有提供owner_id和house_id，后台将从用户当前所在的house字段，提取owner_id和house_id。建议直接提供这两个参数。
- 返回格式说明
code/message字段具体参考 《概述》章节
```
{
"code": 200,
"data": [
{
"time": <时间戳，13位，毫秒>,
"event": <告警描述>
}
],
"message": "success"
}
```
<span id="11"></span>
### 12. 获取设备历史状态列表
- 请求方式: HTTP POST
- URL
```{base_url}/list_device_datas```
- Body Para
|参数名称|类型|描述|
|-|-|-|
|owner_id|String|房子的owner的user_id|
|house_id|String|房子的ID|
|device_id|String|设备ID|
>d owner_id和house_id可以不提供，如果没有提供owner_id和house_id，后台将从用户当前所在的house字段，提取owner_id和house_id。建议直接提供这两个参数。
- 返回格式说明
code/message字段具体参考 《概述》章节
```
{
"code": 200,
"data": [
{
"time": <时间戳，13位，毫秒>,
"states": <设备状态字段，根据不同设备类型，有所不同>
}
],
"message": "success"
}
```
<span id="12"></span>
### 13. 获取所有支持的设备类型
- 请求方式: HTTP POST
- URL
```{base_url}/list_support_devices```
- Body Para
不需要参数
- 返回格式说明
code/message字段具体参考 《概述》章节
```
{
"code": 200,
"data": [
],
"message": "success"
}
```
### 相关字段说明
### （1）设备厂商字段 device_vendor
|字段值|类型|说明|
|-|-|-|
|devices.vendor.WULIAN|String|物联|
|devices.vendor.EZVIZ|String|萤石|
|devices.vendor.TUYA|String|涂鸦|
### （2）设备字段
|字段|类型|说明|
|-|-|-|
|id|String|设备ID编号|
|category|String|设备类型，安防检测/环境检测/电器开关/摄像头|
|type|String|设备具体产品类型（SKU）|
|icons|Object|设备icon，分small, median, large, superLarge|
|googleType|String|对应到google平台的产品类型|
|name|Obj|设备名称,包括defaultName, name, nicknames|
|deviceInfo|Obj|设备厂家信息，包括manufacturer, productPicture, model, hwVersion, swVersion|
|error|String|设备出现错误，错误信息|
|alarm|Object|设备当前的告警，如果当前没有告警，则为null。如果有，告警内容格式：id, event, time|
|willReportState|boolean|是否上报设备状态变化，给APP端使用|
|attributes|Obj|设备属性定义，不同设备内容也不同|
|states|Obj|设备当前状态|
|traits|Obj|设备支持的状态|
|room|Obj|设备所属的房间{id:, name:, floor:, rank_id:}|
|roomHint|String|设备所属的房间 <room_name>_<floor>F|
|otherDeviceIds|List|其他设备ID编码，对应三方的设备ID|
|gatewayDeviceId|String|设备归属的网关ID|
|customData|String|其他设备信息，对应三方的其他字段，（可选）|
### （3）设备类别 category字段 说明
|Category值|说明|
|-|-|
|devices.category.SMART_GATEWAY|智能网关|
|devices.category.SECURITY_DETECTOR|安防检测|
|devices.category.ENVIRONMENT_SENSOR|环境检测|
|devices.category.SMART_SWITCH|智能开关|
|devices.category.SMART_CAMERA|智能摄像头|
### （4）设备型号 type字段 说明
|type值|说明|
|-|-|
|devices.types.GATEWAY_01|竖型智能网关|
|devices.types.GATEWAY_02|盒型智能网关|
|devices.types.GAS_DETECTOR|天然气检测器|
|devices.types.PIR_DETECTOR|红外动作检测器|
|devices.types.CONTACT_DETECTOR|门窗磁检测器|
|devices.types.WATER_LEAK_DETECTOR|水浸检测器|
|devices.types.SMOKE_DETECTOR|烟雾检测器|
|devices.types.SOUND_WARNER|声光报警器|
|devices.types.TEMP_HUMI_SENSOR|温湿度感应器|
|devices.types.LIGHT_SENSOR|光强感应器|
|devices.types.SCENE_SWITCH_6|六路场景开关|
|devices.types.EMBEDDED_SWITCH_1|嵌入式零火一路开关|
|devices.types.EMBEDDED_SWITCH_2|嵌入式零火两路开关|
|devices.types.WALL_SWITCH_1|墙壁一路开关|
|devices.types.WALL_SWITCH_2|墙壁两路开关|
|devices.types.WALL_SWITCH_3|墙壁三路开关|
|devices.types.GARAGE_DOOR_OPENER|车库门控制器|
|devices.types.CAMERA_C3W|C3W摄像头|
|devices.types.CAMERA_C3A|C3A摄像头|
### （5）设备状态 states字段 说明
|states值|说明|
|-|-|
|online|设备是否上线，True为上线，False为离线|
|isArmed|设备的设防状态，True表示当前设备处于设防状态中，False表示当前设备处于撤防状态中<br>一般用于安防检测类设备|
|currentSensorStateData|设备传感器当前状态数据|
|currentToggleSettings|开关状态数据，当前开关的开/关 状态|
|currentElectricalData|电压/电流/实时功率/累计电量数据|