# 开发者与 API 指南

## 1. 开始使用

### 1.1 准备

步骤1. 请确保网关已通电并正常工作。

步骤2. 确保网关与 PC 连接到同一局域网。然后在浏览器中输入 CUBE 的 URL。 

注意：如果您有多个网关，可以通过以下两种方式获取相应的 IP 地址以访问指定网关。

1. 登录到您的无线路由器并在 DHCP 中检查网关的 IP 地址。
2. CUBE 支持通过 mDNS 本地发现。

### 1.2 开始使用

* 调用 \[Access Token] 接口，收到错误响应，提示点击 <**完成**>。注意，按下后，接口访问有效时间不超过 5 分钟。

```json
// 请求
curl --location --request GET 'http://<ip address>/open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json'

// 响应
{
  "error": 401,
  "data": {},
  "message": "link button not pressed" 
}
```

* 点击 <**完成**> 并再次调用 \[Access Token] 接口。响应成功，获取到 token。

```json
// 请求
curl --location --request GET 'http://<ip address>/open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json'

// 响应
{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}
```

* 验证 token。调用 \[Get Device List] 接口。响应成功，获取到设备列表。

```json
// 请求
curl --location --request GET 'http://<ip address>/open-api/V2/rest/devices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 376310da-7adf-4521-b18c-5e0752cfff8d'

// 响应
{
  "error": 0,
  "data": {
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "name": "device name",
        "manufacturer": "manufacturer name",
        "model": "model name",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          }
        ],
        "protocal": "zigbee",
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ]
  }
  "message": "success"
}
```

* 获取 CUBE 访问令牌的方法：调用 \[Access Token] 接口后，CUBE Web 控制台页面会弹出全局提示框，提示用户确认获取接口调用凭据。
* 注意：如果打开多个 CUBE Web 控制台页面，确认弹框会同时出现在多个页面上，在任一页面点击确认后，其他页面的弹框将被关闭。

## 2. 核心概念

### 2.1 开发接口地址

网关 Web API 接口有两种访问方式（基于 IP 或域名），通常根路径为 /open-api/V2/rest/< specific function module >

// IP 访问 http\:///open-api/V2/rest/bridge

// 域名访问 http\:///open-api/V2/rest/bridge

### 2.2 设备显示类别与能力

* \*\*设备显示类别（DisplayCategory）。\*\*设备显示类别用于识别设备的具体类别，例如开关、插座、灯等。 **此信息将决定设备在网关中的 UI 显示效果**.
* \*\*设备能力（Capability）。\*\*设备能力用于描述设备的具体子功能。例如电源控制、亮度控制、色温控制等。 **单个设备可以支持一个或多个能力**.
  * **capability：** 描述能力名称，必须在全局唯一，类型为字符串。多个英文单词应以连字符（"-"）分隔。例如： `"thermostat-target-setpoint"`.
  * **name：** 描述能力下的分类，类型亦为字符串。多个英文单词应以连字符（"-"）分隔。例如： `"auto-mode"`, `"manual-mode"`.
  * **permission：** 描述与能力相关的权限。类型为字符串，格式为 8421 二进制码。示例如下：
    * 设备可控： `"1000"`
    * 设备可配置： `"0010"`
    * 设备可控且可配置： `"1010"`
    * 设备可控且可上报： `"1100"`

各位的含义，从右到左，依次为：ⅰ. 位 0：允许查询设备 ⅱ. 位 1：允许配置设备 ⅲ. 位 2：允许设备上报数据 ⅳ. 位 3：允许控制设备

```javascript
const permission = {
  "update": "1000",
  "updated": "0100",
  "configure": "0010",
  "query": "0001",  
  "update-updated": "1100",
  "update-query": "1001",
  "update-updated-configure": "1110",
  "updated-configure":"0110",
  "update-updated-query":"1101"
}
```

**settings：** 描述能力的配置项，类型为对象，并包含每个配置项的描述。ⅰ. **key：** 描述配置项的名称，类型为字符串。多个英文单词应使用驼峰命名法。例如： `"temperatureUnit"`. ⅱ. **value：** 描述配置项的内容。具体规范详见下表。

| 属性         | 类型     | 是否可选 | 描述        |
| ---------- | ------ | ---- | --------- |
| permission | string | 否    | 描述配置项的权限。 |
| **可选值：**   |        |      |           |

* 允许修改该配置项： `"10"`
* 允许查看该配置项： `"01"`
* 既允许修改又允许查看该配置项： `"11"`

**位说明：**

1. **位 0：** 允许查看该配置项
2. **位 1：** 允许修改该配置项 | | 类型 | string | N | 描述配置项值的数据类型。 **可选值：**

* `"enum"`
* `"numeric"`
* `"object"`
* `"boolean"`
* `"string"`

**类型相关指南：**

1. **当 `**type = enum**`:**
   * 当 `value` 字段（描述配置项的值）在 `permission` 允许修改（`"10"` 或 `"11"`).
   * 当 `default` （描述配置项的默认值）和 `values` （描述配置项的可选值）字段为可选。
2. **当 `**type = numeric**`:**
   * 当 `value` 字段在 `permission` 允许修改（`"10"` 或 `"11"`).
   * 以下字段为可选：
     * `min` （描述配置项的最小值）
     * `max` （描述配置项的最大值）
     * `step` （描述配置项的步长值）
     * `precision` （描述精度）
     * `unit` （描述配置项的单位）
     * `default` （描述默认值）
3. **当 `**type = object**`:**
   * 当 `value` 字段在 `permission` 允许修改（`"10"` 或 `"11"`).
   * 当 `default` 字段为可选。
4. **当 `**type = boolean**`:**
   * 当 `value` 字段在 `permission` 允许修改（`"10"` 或 `"11"`).
   * 当 `default` 字段为可选。
5. **当 `**type = string**`:**
   * 当 `value` 字段在 `permission` 允许修改（`"10"` 或 `"11"`).
   * 当 `default` 字段为可选。 |

```javascript
// type = enum
{
  "settings":{
    "temperatureUnit": {
      "type": "enum",
      "permission": "11", 
      "values": ["c", "f"], 
      "default": "c",
      "value": "f"
    }
  }
}
// type = numeric
{
  "settings": {
    "setpointRange": {
      "type": "numeric", 
      "permission": "01", 
      "min": 4, 
      "max": 35,
      "default": 20,
      "step": 0.5,
      "precision": 0.01
      "unit": "c"
    }
  }
}

// type = object
{
  "settings":{
    "weeklySchedule":{
      "type": "object",
      "permission": "11", 
      "value": {
        "maxEntryPerDay": 2, 
        "Monday": [
          {
            "startTimeInMinutes": 440, 
            "upperSetpoint": 36.5 
          },
          {
            "startTimeInMinutes": 900,
            "upperSetpoint": 26.5 
          }
        ]，
        "Tuesday": [...],
        "Wednesday": [...],
        "Thursday": [...],
        "Friday": [...],
        "Saturday": [...],
        "Sunday": [...],
      }
    }
  }
}
```

## 3. Web API

### 数据类型

| 类型        | 描述                                                                                                   |
| --------- | ---------------------------------------------------------------------------------------------------- |
| string    | 字符串类型。UTF8 编码。                                                                                       |
| number    | 数字类型。 [双精度 64 位二进制格式 IEEE 754](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) |
| int       | 整数类型。                                                                                                |
| object    | 对象类型。符合 JSON 的对象                                                                                     |
| string\[] | 字符串数组                                                                                                |
| int\[]    | 整数数组                                                                                                 |
| object\[] | 对象数组                                                                                                 |
| bool      | 布尔值                                                                                                  |
| date      | 时间字符串。ISO（ISO 8601 扩展格式）格式的字符串：YYYY-MM-DDTHH:mm:ss.sssZ。时区始终为 UTC（协调世界时），以后缀 "Z" 标识。                 |

### 通用响应结果

| 属性                              | 类型     | 是否可选 | 描述    |
| ------------------------------- | ------ | ---- | ----- |
| error                           | int    | 否    | 错误代码： |
| 0：成功                            |        |      |       |
| 400：参数错误                        |        |      |       |
| 401：认证失败                        |        |      |       |
| 500：服务器异常                       |        |      |       |
| data                            | object | 否    | 响应数据体 |
| message                         | string | 否    | 响应描述： |
| 当 error 等于 0 时，内容为 success      |        |      |       |
| 当 error 不等于 0 时，为非空字符串，内容为错误描述。 |        |      |       |

**响应示例**:

```json
{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}
```

```json
{
  "error": 400,
  "data": {},
  "message": "invalid parameters"
}
```

### 资源列表

| 类型    | 描述               |
| ----- | ---------------- |
| 支持的声音 | - alert1（警报声音 1） |

* alert2（警报声音 2）
* alert3（警报声音 3）
* alert4（警报声音 4）
* alert5（警报声音 5）
* doorbell1（门铃声音 1）
* doorbell2（门铃声音 2）
* doorbell3（门铃声音 3）
* doorbell4（门铃声音 4）
* doorbell5（门铃声音 5）
* alarm1（警报声音 1）
* alarm2（警报声音 2）
* alarm3（警报声音 3）
* alarm4（警报声音 4）
* alarm5（警报声音 5） | | 支持的 deep | - bootComplete（系统启动完成）
* networkConnected（网络已连接）
* networkDisconnected（网络已断开）
* systemShutdown（系统关闭） -deviceDiscovered（发现设备）
* system Armed（系统布防启用）
* system Disarmed（系统布防禁用）
* factoryReset（恢复出厂设置） |

### 3.1 网关功能

#### a. 访问令牌

允许用户获取访问令牌。

* 注意：设备重置后令牌将被清除。
* 注意：获取令牌后，需要再次按按钮才能成功获取新的令牌。

:::提示

* **URL**：`/open-api/V2/rest/bridge/access_token`
* **方法**：`GET`
* **头部**：
  * Content-Type: application/json ::: 请求参数：

| **属性**    | **类型** | **是否可选** | **描述**  |
| --------- | ------ | -------- | ------- |
| app\_name | string | Y        | 应用名称描述。 |

成功的数据响应：

| **属性**    | **类型** | **是否可选** | **描述**           |
| --------- | ------ | -------- | ---------------- |
| token     | string | 否        | 接口访问令牌。有效期较长，请保存 |
| app\_name | string | Y        | 应用名称描述。          |

:::提示 **条件**：用户触发 < command key > 并在有效时间内访问此接口。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```json
{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}
```

失败的数据响应：空对象 :::提示 **条件**：用户未触发 < command key >，或有效时间已过期。\*\*状态代码：\*\* `200 OK` ::: **响应示例**:

```json
{
  "error": 401,
  "data": {},
  "message": "link button not pressed" 
}
```

#### b. 获取网关状态

允许授权用户通过此接口获取网关状态 :::提示

* **URL**：`/open-api/V2/rest/bridge/runtime`
* **方法**：`GET`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：无 成功的数据响应：

| **属性**                      | **类型** | **是否可选** | **描述**             |
| --------------------------- | ------ | -------- | ------------------ |
| ram\_used                   | int    | 否        | 内存使用百分比。\[0-100]   |
| cpu\_used                   | int    | 否        | CPU 使用百分比。\[0-100] |
| power\_up\_time             | date   | 否        | 上次开机时间             |
| cpu\_temp                   | int    | 否        | CPU 温度：            |
| 单位：摄氏度                      |        |          |                    |
| cpu\_temp\_unit             | string | 否        | CPU 温度单位：          |
| 是否可选                        |        |          |                    |
| values：`'c'`, `'f'`         |        |          |                    |
| sd\_card\_used              | int    | Y        | SD 卡使用率（百分比）：      |
| 范围：`[0-100]` 精确到一位小数        |        |          |                    |
| \*注意：如果未插入 SD 卡或未格式化，则该值为空。 |        |          |                    |

:::提示 **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```json
{
  "error": 0,
  "data": {
    "ram_used": 40,
    "cpu_used": 30,
    "power_up_time": "2022-10-12T02:58:09.989Z",
    "cpu_temp": 51,
    "cpu_temp_unit": "c",
    "sd_card_used" : "12"
  },
  "message": "success"
}
```

#### c. 设置网关

允许授权用户通过此接口设置网关 :::提示

* **URL**：`/open-api/V2/rest/bridge/config`
* **方法**：`PUT`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：

| **属性** | **类型** | **是否可选** | **描述**        |
| ------ | ------ | -------- | ------------- |
| volume | int    | Y        | 系统音量。\[0-100] |

成功的数据响应：空对象 {} :::提示 **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

#### d. 获取网关信息

允许授权用户通过此接口获取网关信息 :::提示

* **URL**：`/open-api/V2/rest/bridge`
* **方法**：`GET`
* **头部**：
  * Content-Type: application/json ::: 请求参数：

| **属性**      | **类型** | **是否可选** | **描述** |
| ----------- | ------ | -------- | ------ |
| ip          | string | 否        | IP 地址  |
| mac         | string | 否        | MAC 地址 |
| domain      | string | Y        | 网关服务域名 |
| fw\_version | string | 否        | 固件版本   |
| name        | string | 否        | 设备名称   |

成功的数据响应：空对象 {} :::提示 **条件**：无 \*\*状态代码：\*\*200 OK ::: **响应示例**:

```json
{
  "error": 0,
  "data": {
    "ip": "192.168.31.25",
    "mac": "00:0A:02:0B:03:0C",
    "domain": "ihost.local",
    "fw_version": "1.9.0",
    "name": "iHost"
  },
  "message": "success"
}
```

#### e. 网关静音

允许授权用户通过此接口将网关静音。 :::提示

* **URL**：`/open-api/v2/rest/bridge/mute`
* **方法**：`PUT`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::提示 **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

#### f. 取消网关静音

允许授权用户通过此接口取消网关静音。\
:::提示

* **URL**：`/open-api/v2/rest/bridge/unmute`
* **方法**：`PUT`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::提示 **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

#### g. 取消网关警报

允许授权用户通过此接口禁用网关上的警报声音状态。 :::提示

* **URL**：`/open-api/v2/rest/bridge/cancel_alarm`
* **方法**：`PUT`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::提示 **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

### 3.2 硬件功能

#### a. 重启网关

允许被授权用户通过此接口重启网关 :::提示

* **URL**：`/open-api/V2/rest/hardware/reboot`
* **方法**：`POST`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::提示 **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK :::

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

#### b. 扬声器控制

允许被授权用户通过此接口控制扬声器 :::提示

* **URL**：`/open-api/V2/rest/hardware/speaker`
* **方法**：`POST`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：

| **属性** | **类型**      | **是否可选**                      | **描述**                                      |
| ------ | ----------- | ----------------------------- | ------------------------------------------- |
| type   | string      | 否                             | 可选参数：1.play\_sound（播放声音） 2.play\_beep（播放蜂鸣） |
| sound  | SoundObject | Y（若 type 为 play\_sound 则为 N。） | 声音对象。                                       |
| beep   | BeepObject  | Y（若 type 为 play\_beep 则为 N。）  | 蜂鸣对象                                        |

SoundObject

| **属性**    | **类型** | **是否可选** | **描述**                                |
| --------- | ------ | -------- | ------------------------------------- |
| name      | string | 否        | 声音名称。支持的取值可在【资源列表 - 支持的声音】中查看         |
| volume    | int    | 否        | 声音音量。\[0-100]                         |
| countdown | int    | 否        | 扬声器播放声音的时长，时间到后会自动停止播放。单位：秒。\[0,1799] |

BeepObject

| **属性** | **类型** | **是否可选** | **描述**                              |
| ------ | ------ | -------- | ----------------------------------- |
| name   | string | 否        | deep 名称。支持的取值可在【资源列表 - 支持的 deep】中查看 |
| volume | int    | 否        | deep 音量。\[0-100]                    |

成功的数据响应：空对象 {} :::提示 **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\* `200 OK` ::: **响应示例**:

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

### 3.3 设备管理功能

#### a. 支持的设备类型

| **设备类型** | **取值**                       | iHost 版本 |
| -------- | ---------------------------- | -------- |
| 插座       | plug                         | ≥ 2.1.0  |
| 开关       | switch                       | ≥ 2.1.0  |
| 灯        | light                        | ≥ 2.1.0  |
| 窗帘       | curtain                      | ≥ 2.1.0  |
| 门/窗传感器   | contactSensor                | ≥ 2.1.0  |
| 人体感应传感器  | motionSensor                 | ≥ 2.1.0  |
| 温度传感器    | temperatureSensor            | ≥ 2.1.0  |
| 湿度传感器    | humiditySensor               | ≥ 2.1.0  |
| 温湿度传感器   | temperatureAndHumiditySensor | ≥ 2.1.0  |
| 漏水检测器    | waterLeakDetector            | ≥ 2.1.0  |
| 烟雾探测器    | smokeDetector                | ≥ 2.1.0  |
| 无线按钮     | button                       | ≥ 2.1.0  |
| 摄像头      | camera                       | ≥ 2.1.0  |
| 通用传感器    | sensor                       | ≥ 2.1.0  |
| 通用传感器    | sensor                       | ≥ 2.1.0  |
| 风扇灯      | fanLight                     | ≥ 2.1.0  |
| 空调       | airConditioner               | ≥ 2.1.0  |
| 风扇       | fan                          | ≥ 2.1.0  |
| 恒温器      | thermostat                   | ≥ 2.1.0  |

#### b. 支持的设备能力

**电源开关 (power)：**

**能力声明示例：**

```
[
  {
    "capability": "power", // 能力名称
    "permission": "1100",  // ihost 不支持配置软启/软停，因此没有 configure 字段
  }
]
```

**状态属性：**

```
{
  "powerState": "on", // 字段 powerState 表示开关电源状态。必填。**类型：** string。“on” 表示开机，“off” 表示关机，“toggle” 表示切换。
}
```

**协议（查询状态与控制指令）：**

**开启：**

```
{
  "power": {
    "powerState": "on"
  }
}
```

**关闭：**

```
{
  "power": {
    "powerState": "off"
  }
}
```

**通道开关 (toggle)：**

**能力声明示例：**

单组件示例：

```
[
  {
    "capability": "toggle", // 能力名称
    "permission": "1100",  // 权限
    "name": "1", // 组件名称，**类型：** String。可选值："1"（通道1）、"2"（通道2）、"3"（通道3）、"4"（通道4），或包含大小写字母和数字的其他值
  }
]
```

多组件示例：

```
[
  {
    "capability": "toggle",
    "permission": "1100",
    "name": "1"
  },
  {
    "capability": "toggle",
    "permission": "1100",
    "name": "2"
  }
]
```

**状态属性：**

```
{
  "toggleState": "on", // 字段 toggleState 表示 {device_id} 的 {name} 属性的开关状态。必填。**类型：** String。“on” 表示启用，“off” 表示禁用，“toggle” 表示切换。
}
```

**协议（查询状态与控制指令）：**

开关格式：

```
{
  [capability]: {
    [toggle-name]: {
      [toggleState]: [value]
    }
  }
}
组件1 开，组件2 关：
{
  "toggle": {
    "1": {
      "toggleState": "on"
    },
    "2": {
      "toggleState": "off"
    }
  }
}
```

**通道延时（toggle-inching）：**

**能力声明示例：**

```
[
  {
    "capability": "toggle-inching", // 能力名称
    "permission": "0010",  // 权限
    "settings": {
      "toggleInchingSetting": {
        "permission": "11",
        "type": "object",
        "value": {
          "supported": {
            "1": { // 组件名称
              "enable": true, // 是否启用延时功能。**类型：** Boolean。必填。
              "inchingSwitch": "off", // 延时开关设置。**类型：** String。必填。“off”（断电），“on”（通电）
              "delay": 1000, // 延时时间，单位毫秒。**类型：** Integer。必填。
              "min_delay": 500, // 最小延时时间
              "max_delay": 100000 // 最大延时时间
            },
            "2": { // 组件名称
              "enable": true, // 是否启用延时功能。**类型：** Boolean。必填。
              "inchingSwitch": "off", // 延时开关设置。**类型：** String。必填。“off”（断电），“on”（通电）
              "delay": 1000, // 延时时间，单位毫秒。**类型：** Integer。必填。
              "min_delay": 500, // 最小延时时间
              "max_delay": 100000 // 最大延时时间
            },
            "3": { // 组件名称
              "enable": true, // 是否启用延时功能。**类型：** Boolean。必填。
              "inchingSwitch": "off", // 延时开关设置。**类型：** String。必填。“off”（断电），“on”（通电）
              "delay": 1000, // 延时时间，单位毫秒。**类型：** Integer。必填。
              "min_delay": 500, // 最小延时时间
              "max_delay": 100000 // 最大延时时间
            },
            "4": { // 组件名称
              "enable": true, // 是否启用延时功能。**类型：** Boolean。必填。
              "inchingSwitch": "off", // 延时开关设置。**类型：** String。必填。“off”（断电），“on”（通电）
              "delay": 1000, // 延时时间，单位毫秒。**类型：** Integer。必填。
              "min_delay": 500, // 最小延时时间
              "max_delay": 100000 // 最大延时时间
            }
          }
        }
      }
    }
  }
]
```

**状态属性**

无

**协议（查询状态与控制指令）**

无

**亮度调节 (brightness)：**

**能力声明示例：**

```
{
  "capability": "brightness", // 能力名称
  "permission": "1100"  // 权限
}
```

**状态属性：**

```
{
  "brightness": 100, // 字段 brightness 表示亮度百分比。在 brightness 与 brightnessDelta 之间选择。**类型：** Number。范围：0-100。
}
```

**协议（查询状态与控制指令）：**

将亮度设置为 80%。（0 最暗，100 最亮。）

```
json
复制代码
{
  "brightness": {
    "brightness": 80
  }
}
```

**色温调节 (color-temperature)：**

**能力声明示例：**

```
{
  "capability": "color-temperature", // 能力名称
  "permission": "1100"  // 权限
}
```

**状态属性：**

```
{
  "colorTemperature": 100, // 字段 colorTemperature 表示色温百分比。在 colorTemperature 与 colorTemperatureDelta 之间选择。**类型：** Number。范围：0-100。0 表示暖光，50 表示中性光，100 表示冷光。
}
```

**协议（查询状态与控制指令）：**

将色温调整为 50%：

```
json
 
{
  "color-temperature": {
    "colorTemperature": 50
  }
}
```

**颜色调节 (color-rgb)：**

**能力声明示例：**

```
{
  "capability": "color-rgb", // 能力名称
  "permission": "1100"  // 权限
}
```

**状态属性：**

```
{
  "red": 255, // 字段 red 表示 RGB 颜色空间中的红色值。必填。**类型：** Number。范围：0-255。
  "green": 0, // 字段 green 表示 RGB 颜色空间中的绿色值。必填。**类型：** Number。范围：0-255。
  "blue": 255 // 字段 blue 表示 RGB 颜色空间中的蓝色值。必填。**类型：** Number。范围：0-255。
}
```

**协议（查询状态与控制指令）：**

设置颜色为紫色：

```
{
  "color-rgb": {
    "red": 255,
    "green": 0,
    "blue": 255
  }
}
```

**百分比调节 (percentage)：**

**能力声明示例：**

```
{
  "capability": "percentage",
  "permission": "1100",
  "settings": { // 可选
    "percentageRange": {
      "permission": "01",
      "type": "numeric",
      "min": 0,
      "max": 100,
      "step": 5
    }
  }
}
```

**状态属性：**

```
{
  "percentage": 100, // 字段 percentage 表示百分比值。在 percentage 与 percentageDelta 之间选择。**类型：** Number。范围：0-100。
}
```

**协议（查询状态与控制指令）：**

调整到 40%：

```
{
  "percentage": {
    "percentage": 40
  }
}
```

**电机控制 (motor-control)：**

**能力声明示例：**

```
{
  "capability": "motor-control",
  "permission": "1100"
}
```

**状态属性：**

```
json
 
{
  "motorControl": "stop", // 字段 motorControl 表示电机状态。必填。**类型：** String。可选值："open"（打开）、"close"（关闭）、"stop"（停止）、"lock"（锁定）。
}
```

**协议（查询状态与控制指令）：**

打开电机：

```
{
  "motor-control": {
    "motorControl": "open"
  }
}
```

**电机反转 (motor-reverse)：**

**能力声明示例：**

```
{
  "capability": "motor-reverse",
  "permission": "1100"
}
```

**状态属性：**

```
{
  "motorReverse": true, // 字段 motorReverse 表示电机方向设置。必填。**类型：** Boolean。true 表示正转，false 表示反转。
}
```

**协议（查询状态与控制指令）：**

设置电机为正转：

```
{
  "motor-reverse": {
    "motorReverse": true
  }
}
```

**电机校准 (motor-clb)**

**能力声明示例：**

```
{
  "capability": "motor-clb",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "motorClb": "calibration" // 字段 motorClb 表示电机校准状态。必填。**类型：** String。“normal” 表示正常模式（已校准），“calibration” 表示正在校准。
}
```

**协议（状态上报）：**

上报电机处于校准中：

```
{
  "motor-clb": {
    "motorClb": "calibration"
  }
}
```

**开机状态 (startup)**

**能力声明示例：**

```
{
  "capability": "startup",
  "permission": "1100"
}
```

**属性（状态）：**

```
{
  "startup": "on" // 开机时的电源状态。**类型：** String。必填。可选值："on"（上电）、"stay"（保持通电）、"off"（断电）、"toggle"（取反）。
}
```

**协议（查询状态与控制指令）：**

设置开机为始终开启：

```
{
  "startup": {
    "startup": "on"
  }
}
```

***

**唤醒激活 (identify)**

**能力声明示例：**

```
{
  "capability": "identify",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "identify": true // 表示设备是否主动上报识别结果或被激活。
}
```

**协议（状态上报与控制指令）：**

设置唤醒激活时间：

```
{
  "identify": {
    "countdown": 180 // 字段 countdown 表示倒计时时间。必填。**类型：** Number。单位：秒。
  }
}
```

上报激活状态：

```
{
  "identify": {
    "identify": true // 表示设备是否主动上报识别结果或被激活。
  }
}
```

**实时用电统计开关 (power-consumption)**

**能力声明示例：**

```
{
  "capability": "power-consumption",
  "permission": "1101",
  "settings": {
    "resolution": {
      "permission": "01",
      "type": "numeric",
      "value": 3600
    },
    "timeZoneOffset": {
      "permission": "01",
      "type": "numeric",
      "min": -12,
      "max": 14,
      "value": 0
    }
  }
}
```

**属性（状态）：**

开始/停止实时统计：

```
{
  "rlSummarize": true, // 开始/停止实时统计。**类型：** Boolean。必填。
  "timeRange": { // 汇总时间范围。必填。
    "start": "2020-07-05T08:00:00Z", // 用电统计的开始时间。**类型：** String。必填。
    "end": "2020-07-05T09:00:00Z" // 用电统计的结束时间。**类型：** String。必填。
  }
}
```

按时间范围查询用电：

```
{
  "type": "summarize", // 统计类型。**类型：** String。必填。可选值："rlSummarize"（实时汇总）、"summarize"（当前汇总）。
  "timeRange": { // 汇总时间范围。若 type 为 "summarize" 则必填。
    "start": "2020-07-05T08:00:00Z", // 用电统计的开始时间。**类型：** String。必填。
    "end": "2020-07-05T09:00:00Z" // 用电统计的结束时间。**类型：** String。可选。如省略，表示当前时间。
  }
}
```

在时间范围内返回统计结果：

```
json
 
{
  "type": "summarize", // 统计类型。**类型：** String。必填。可选值："rlSummarize"（实时汇总）、"summarize"（当前汇总）。
  "rlSummarize": 50.0, // 总用电量。**类型：** Number。单位：0.01 kWh。可选。
  "electricityIntervals": [ // 按 configuration.resolution 划分的多条统计记录。可选。type 为 "rlSummarize" 时不出现。
    {
      "usage": 26.5, // 用电量。**类型：** Number。单位：0.01 kWh。必填。
      "start": "2020-07-05T08:00:00Z", // 开始时间。**类型：** Date。必填。
      "end": "2020-07-05T09:00:00Z" // 结束时间。**类型：** Date。必填。如果 end 与 start 之间的间隔小于 resolution，则所有上报记录均视为无效。
    },
    {
      "usage": 26.5, // 用电量。**类型：** Number。单位：0.01 kWh。必填。
      "start": "2020-07-05T09:00:00Z", // 开始时间。**类型：** Date。必填。
      "end": "2020-07-05T10:00:00Z" // 结束时间。**类型：** Date。必填。如果 end 与 start 之间的间隔小于 resolution，则所有上报记录均视为无效。
    }
  ]
}
```

**协议（状态上报与控制指令）：**

开始实时统计：

```
json
 
{
  "power-consumption": {
    "powerConsumption": {
      "rlSummarize": true,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": ""
      }
    }
  }
}
```

停止实时统计：

```
json
 
{
  "power-consumption": {
    "powerConsumption": {
      "rlSummarize": false,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": "2020-07-05T09:00:00Z"
      }
    }
  }
}
```

获取历史用电：

```
json
 
{
  "power-consumption": {
    "type": "summarize",
    "timeRange": {
      "start": "2020-07-05T08:00:00Z",
      "end": "2020-07-05T09:00:00Z"
    }
  }
}
```

获取实时用电：

```
json
 
{
  "power-consumption": {
    "powerConsumption": {
      "type": "rlSummarize"
    }
  }
}
```

**温湿度模式检测 (thermostat-mode-detect)**

**能力声明示例：**

```
{
  "capability": "thermostat-mode-detect",
  "permission": "0110",
  "name": "temperature", // 温度控制检测类型。**类型：** String。必填。可选值："humidity"（湿度检测）、"temperature"（温度检测）。
  "settings": {
    "setpointRange": {
      "permission": "11",
      "type": "object",
      "value": {
        "supported": [ // 支持的检测设置。必填。
          {
            "name": "lowerSetpoint", // 检测值应高于该设定点。lowerSetpoint 或 upperSetpoint 至少需有一项。
            "value": { // 检测范围。可选。存在预设条件时填写。
              "value": 68.0, // 温度值。**类型：** Number。必填。
              "scale": "f" // 温度单位。当 name=temperature 时必填。可选值："c"（摄氏度）、"f"（华氏度）。
            }
          },
          {
            "name": "upperSetpoint", // 检测值应低于该设定点。lowerSetpoint 或 upperSetpoint 至少需有一项。
            "value": { // 检测范围。可选。存在预设条件时填写。
              "value": 68.0, // 温度值。**类型：** Number。必填。
              "scale": "f" // 温度单位。当 name=temperature 时必填。可选值："c"（摄氏度）、"f"（华氏度）。
            }
          }
        ]
      }
    },
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "COMFORT",
        "COLD",
        "HOT"
      ]
    }
  }
}

{
  "capability": "thermostat-mode-detect",
  "permission": "0110",
  "name": "humidity", // 温度控制检测类型。**类型：** String。必填。可选值："humidity"（湿度检测）、"temperature"（温度检测）。
  "settings": {
    "setpointRange": {
      "permission": "11",
      "type": "object",
      "value": {
        "supported": [ // 支持的检测设置。必填。
          {
            "name": "lowerSetpoint", // 检测值应高于该设定点。lowerSetpoint 或 upperSetpoint 至少需有一项。
            "value": { // 检测范围。可选。存在预设条件时填写。
              "value": 68.0, // 湿度值。**类型：** Number。必填
            }
          },
          {
            "name": "upperSetpoint", // 检测值应低于该设定点。lowerSetpoint 或 upperSetpoint 至少需有一项。
            "value": { // 检测范围。可选。存在预设条件时填写。
              "value": 68.0, // 湿度值。**类型：** Number。必填
            }
          }
        ]
      }
    },
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "COMFORT",
        "COLD",
        "HOT"
      ]
    }
  }
}
```

**属性（状态）：**

```
{
  "mode": "COMFORT" // 模式 ID。可选。支持值："COMFORT"（舒适模式）、"COLD"（制冷模式）、"HOT"（制热模式）、"DRY"（干燥模式）、"WET"（潮湿模式）。
}
```

**协议（查询状态与控制指令）：**

格式：

```
{
    [capability] :{
        [mode name] :{
            "mode": [value]
        }
    }
}
```

示例：

```
{
  "thermostat-mode-detect": {
    "humidity": {
      "mode": "COMFORT"
    }
  }
}
```

**恒温器模式 (thermostat-mode)**

**能力声明示例：**

```
{
  "capability": "thermostat",
  "permission": "1100",
  "name": "thermostat-mode",
  "settings": {
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "MANUAL",
        "AUTO",
        "ECO"
      ]
    }
  }
}
```

**属性（状态）：**

```
{
  "thermostatMode": "MANUAL" // 恒温器工作模式。**类型：** String。可选值："MANUAL"、"AUTO"、"ECO"。
}
```

**协议（查询状态与控制指令）：**

```
{
   "thermostat": {
    "thermostat-mode": {
      "thermostatMode": "MANUAL"
    }
  }
}
```

**恒温器自适应恢复状态 (thermostat/adaptive-recovery-status)**

**能力声明示例：**

```
{
  "capability": "thermostat",
  "permission": "0100",
  "name": "adaptive-recovery-status" // 恒温器自适应恢复状态
}
```

**属性（状态）：**

```
{
  "adaptiveRecoveryStatus": "HEATING" // 恒温器自适应恢复状态。**类型：** String。可选值："HEATING"、"INACTIVE"。
}
```

**协议（查询状态与控制指令）：**

```
{
  "thermostat": {
    "adaptive-recovery-status": {
      "adaptiveRecoveryStatus": "HEATING"
    }
  }
}
```

**恒温器目标温度设置 (thermostat-target-setpoint)**

**能力声明示例：**

```
[[
  {
    "capability": "thermostat-target-setpoint",
    "name": "manual-mode",
    "permission": "1110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      }
    }
  },
  {
    "capability": "thermostat-target-setpoint",
    "name": "eco-mode",
    "permission": "1110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      }
    }
  },
  {
    "capability": "thermostat-target-setpoint",
    "name": "auto-mode",
    "permission": "0110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      },
      "weeklySchedule":{
        "type": "object",
        "permission": "11",
        "value": {
          "maxEntryPerDay": 2,
          "Monday": [
          {
            "startTimeInMinutes": 440, // 开始时间（分钟）。**类型：** int。示例：7:20 AM = 440 分钟。
            "upperSetpoint": 36.5, // 最大目标温度。**类型：** number。
            "lowerSetpoint": 20 // 最低目标温度。**类型：** number。
          },
          {
            "startTimeInMinutes": 900, // 开始时间（分钟）。示例：3:00 PM = 900 分钟。
            "upperSetpoint": 26.5, // 最大目标温度。**类型：** number。
            "lowerSetpoint": 21 // 最低目标温度。**类型：** number。
          }
        ],
          "Tuesday": [...
          ],
          "Wednesday": [...
          ],
          "Thursday": [...
          ],
          "Friday": [...
          ],
          "Saturday": [...
          ],
          "Sunday": [...
          ],
        }
      }
    }
  }
]
```

**属性（状态）：**

```
{
  "targetSetpoint": 30 // 指定模式的目标温度。**类型：** number，单位由 temperatureUnit 指定。
}
```

**协议（查询状态与控制指令）：**

```
{
  "thermostat-target-setpoint": {
    "manual-mode": {
        "targetSetpoint": 30 
    },
    "auto-mode": {
        "targetSetpoint": 30 
    }
  }
}
```

**传感器检测 (detect)**

**能力声明示例：**

```
{
  "capability": "detect",
  "permission": "0110",
  "settings": { // 可选
    "detectInterval": {
      "permission": "11",
      "type": "numeric",
      "value": 300
    },
    "detectSensitivity": {
      "permission": "11",
      "type": "numeric",
      "value": 1000
    }
  }
}
```

**属性（状态）：**

```
{
  "detected": true // 检测结果。**类型：** Boolean。`true` 表示检测到，`false` 表示未检测到。
}
```

**协议（查询状态与控制指令）：**

```
{
    "detect": {
        "detected": true
    }
}
```

**温度检测 (temperature)**

**能力声明示例：**

```
{
  "capability": "temperature",
  "permission": "0110",
  "settings": { // 可选
    "temperatureCalibration": { // 可选的温度校准
      "type": "numeric",
      "permission": "11",
      "min": -7, // 最小值
      "max": 7, // 最大值
      "step": 0.2, // 温度调节步进，单位与 temperatureUnit 相同
      "value": 5.2 // 当前温度校准值。**类型：** number。
    },
    "temperatureUnit": { // 可选的温度单位
      "type": "enum",
      "permission": "11",
      "value": "c",
      "values": [
        "c",
        "f"
      ]
    },
    "temperatureRange": { // 可选的温度检测范围
      "type": "numeric",
      "permission": "01",
      "min": -40,
      "max": 80
    }
  }
}
```

**属性（状态）：**

```
json
复制代码
{
  "temperature": 26.5 // 当前温度。**类型：** Number，摄氏度。
}
```

**协议（查询状态与控制指令）：**

```
{
  "temperature": {
    "temperature": 20
  }
}
```

**湿度检测 (humidity)**

**能力声明示例：**

```
{
  "capability": "humidity",
  "permission": "0100",
  "settings": { // 可选的湿度检测范围。
    "humidityRange": {
      "type": "numeric",
      "permission": "01",
      "min": 0,
      "max": 100
    }
  }
}
```

**属性（状态）：**

```
{
  "humidity": 50 // 当前相对湿度（百分比）。**类型：** Number，范围 0-100。
}
```

**协议（查询状态与控制指令）：**

```
{
    "humidity": {
        "humidity": 20
    }
}
```

**电池检测 (battery)**

**能力声明示例：**

```
{
  "capability": "battery",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "battery": 95 // 剩余电量百分比。**类型：** Number，范围 -1 到 100。说明：-1 表示电量未知。
}
```

**协议（查询状态与控制指令）：**

```
{
  "battery": {
    "battery": 40
  }
}
```

**单按键检测 (press)**

**能力声明示例：**

```
{
  "capability": "press",
  "permission": "1100",
  "settings": { // 可选
    "actions": { // 按键动作，可选。
      "type": "enum",
      "permission": "01",
      "values": [ // 可选的按键动作。默认值为 "singlePress"、"doublePress"、"longPress"。配置的动作会替换默认值。
      ]
    }
  }
}
```

**属性（状态）：**

```
{
  "press": "singlePress" // 按键类型。**类型：** String。标准值："singlePress"（单次或短按）、"doublePress"（双击）、"longPress"（长按）。
}
```

**协议（查询状态与控制指令）：**

```
{
  "press": {
    "press": "singlePress"
  }
}
```

**多按键检测 (multi-press)**

**能力声明示例：**

```
{
  "capability": "multi-press",
  "permission": "0100",
  "name": "1", // multi-press 属性名称。**类型：** String。仅允许字母数字字符。
  "settings": { // 可选
    "actions": { // 按键动作，可选。
      "type": "enum",
      "permission": "01",
      "values": [ // 可选的按键动作。默认值为 "singlePress"、"doublePress"、"longPress"。配置的动作会替换默认值。
      ]
    }
  }
}
```

**属性（状态）：**

```
{
  "press": "singlePress" // 按键类型。**类型：** String。标准值："singlePress"（单次或短按）、"doublePress"（双击）、"longPress"（长按）。
}
```

**协议（查询状态与控制指令）：**

```
{
    [capability] :{
        [multi-press-name]：{
            press:[value]
        }
    }
}

示例：
{
  "multi-press": {
    "1": {
      "press": "singlePress"
    },
    "2": {
      "press": "doublePress"
    }
  }
}
```

**信号强度检测 (rssi)**

**能力声明示例：**

```
{
  "capability": "rssi",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "rssi": -65 // 无线信号强度（接收信号强度指示）。**类型：** Number，单位 dBm，负整数值。
}
```

**协议（查询状态与控制指令）：**

```
{
  "rssi": {
    "rssi": -65
  }
}
```

**防拆检测 (tamper-alert)**

**能力声明示例：**

```
{
  "capability": "tamper-alert",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "tamper": "clear" // 防拆状态。**类型：** String。可选值："clear"（未拆）、"detected"（检测到拆卸）。
}
```

**协议（查询状态与控制指令）：**

```
{
  "tamper-alert": {
    "tamper": "clear" // 防拆状态。**类型：** String。可选值："clear"（未拆）、"detected"（检测到拆卸）。
  }
}
```

**光照等级检测 (illumination-level)**

**能力声明示例：**

```
{
  "capability": "illumination-level",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "level": "brighter" // 亮度等级。**类型：** String。可选值："brighter"（较亮）、"darker"（较暗）。
}
```

**协议（查询状态与控制指令）：**

```
{
  "illumination-level": {
    "level": "brighter"
  }
}
```

**电压检测 (voltage)**

**能力声明示例：**

```
{
  "capability": "voltage",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "voltage": 50 // 当前电压值，单位为 0.01V。**类型：** Number，非负值。
}
```

**协议（查询状态与控制指令）：**

```
{
  "voltage": {
    "voltage": 50
  }
}
```

**电流检测 (electric-current)**

**能力声明示例：**

```
{
  "capability": "electric-current",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "electric-current": 50 // 当前电流值，单位为 0.01A。**类型：** Number，非负整数值。
}
```

**协议（查询状态与控制指令）：**

```
{
  "electric-current": {
    "electric-current": 50
  }
}
```

**电功率检测 (electric-power)**

**能力声明示例：**

```
{
  "capability": "electric-power",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "electric-power": 50 // 当前功率值，单位为 0.01W。**类型：** Number，非负整数值。
}
```

**协议（查询状态与控制指令）：**

```
{
  "electric-power": {
    "electric-power": 50
  }
}
```

**故障检测 (fault)**

**能力声明示例：**

```
{
  "capability": "fault",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "fault": "none" // 故障状态。**类型：** String。可选值："none"（无故障）、"detected"（检测到故障）。
}
```

**协议（查询状态与控制指令）：**

```
{
  "fault": {
    "fault": "none"
  }
}
```

**阈值断路器 (threshold-breaker)**

**能力声明示例：**

```
{
  "capability": "threshold-breaker",
  "permission": "0010",
  "settings": {
    "supportedSetting": {
      "type": "object",
      "permission": "11",
      "value": {
        "supported": [
          {
            "name": "lowerPower", // 低功率阈值断路器
            "value": {
              "value": 50, // 检测功率值，单位为 0.01W。**类型：** Integer。范围：>=0。
              "min_range": 10, // 最小检测功率值，单位为 0.01W。**类型：** Integer。范围：>=0。
              "max_range": 3500 // 最大检测功率值，单位为 0.01W。**类型：** Integer。范围：>=0。
            }
          },
          {
            "name": "upperPower", // 高功率阈值断路器
            "value": {
              "value": 50, // 检测功率值，单位为 0.01W。**类型：** Integer。范围：>=0。
              "min_range": 10, // 最小检测功率值，单位为 0.01W。**类型：** Integer。范围：>=0。
              "max_range": 3500 // 最大检测功率值，单位为 0.01W。**类型：** Integer。范围：>=0。
            }
          },
          {
            "name": "lowerElectricCurrent", // 低电流阈值断路器
            "value": {
              "value": 50, // 检测电流值，单位为 0.01A。**类型：** Integer。范围：>=0。
              "min_range": 10, // 最小检测电流值，单位为 0.01A。**类型：** Integer。范围：>=0。
              "max_range": 1500 // 最大检测电流值，单位为 0.01A。**类型：** Integer。范围：>=0。
            }
          },
          {
            "name": "upperElectricCurrent", // 高电流阈值断路器
            "value": {
              "value": 50, // 检测电流值，单位为 0.01A。**类型：** Integer。范围：>=0。
              "min_range": 10, // 最小检测电流值，单位为 0.01A。**类型：** Integer。范围：>=0。
              "max_range": 1500 // 最大检测电流值，单位为 0.01A。**类型：** Integer。范围：>=0。
            }
          },
          {
            "name": "lowerVoltage", // 低电压阈值断路器
            "value": {
              "value": 50, // 检测电压值，单位为 0.01V。**类型：** Integer。范围：>=0。
              "min_range": 10, // 最小检测电压值，单位为 0.01V。**类型：** Integer。范围：>=0。
              "max_range": 24000 // 最大检测电压值，单位为 0.01V。**类型：** Integer。范围：>=0。
            }
          },
          {
            "name": "upperVoltage", // 高电压阈值断路器
            "value": {
              "value": 50, // 检测电压值，单位为 0.01V。**类型：** Integer。范围：>=0。
              "min_range": 10, // 最小检测电压值，单位为 0.01V。**类型：** Integer。范围：>=0。
              "max_range": 24000 // 最大检测电压值，单位为 0.01V。**类型：** Integer。范围：>=0。
            }
          }
        ]
      }
    }
  }
}
```

**属性（状态）**

* 无

**协议（查询状态与控制指令）**

* 无

**点动功能 (inching)**

**能力声明示例：**

```
{
  "capability": "inching",
  "permission": "0010",
  "settings": {
    "inchingEnable": { // 点动功能启用设置
      "permission": "11",
      "type": "boolean",
      "value": false
    },
    "inchingSwitch": { // 点动动作设置
      "type": "enum",
      "permission": "11",
      "value": "on",
      "values": ["on", "off"]
    },
    "inchingDelay": { // 点动时间设置
      "type": "numeric",
      "permission": "11",
      "min": 500,
      "max": 100000,
      "value": 1000,
      "unit": "ms"
    }
  }
}
```

**属性（状态）：**

* 无

**协议（查询状态与控制指令）：**

* 无

**摄像头流 (camera-stream)**

**能力声明示例：**

```
{
  "capability": "camera-stream",
  "permission": "0010",
  "settings": {
    "streamSetting": {
      "type": "object",
      "permission": "11",
      "value": {
        "username": "String", // 访问账号。**类型：** String。必填。
        "password": "String", // 访问密码。**类型：** String。必填。
        "streamUrl": "rtsp://<username>:<password>@<hostname>:<port>/streaming/channel01", // 流地址。**类型：** String。必填。
        "videoCodec": "", // 视频编码。**类型：** String。必填。可选参数待定义。
        "resolution": { // 视频分辨率。必填。
          "width": 1080, // 宽度。**类型：** Number。必填。
          "height": 720 // 高度。**类型：** Number。必填。
        },
        "keyFrameInterval": 5, // 关键帧间隔。**类型：** String。必填。
        "audioCodec": "G711", // 音频编码。**类型：** String。必填。可选参数待定义。
        "samplingRate": 50, // 音频采样率，单位 Hz。**类型：** Number。必填。可选参数待定义。
        "dataRate": 50 // 比特率。**类型：** Number。必填。单位：kb/s。
      }
    }
  }
}
```

**属性（状态）：**

* 无

**协议（查询状态与控制指令）：**

* 无

**模式控制 (mode)**

**能力声明示例：**

```
[
  {
    "capability": "mode",
    "name": "fanLevel",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["low", "medium", "high"] // 自定义模式值。配置值会覆盖默认值。
      }
    }
  },
  {
    "capability": "mode",
    "name": "thermostatMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["auto", "manual"] // 自定义模式值。配置值会覆盖默认值。
      }
    }
  },
  {
    "capability": "mode",
    "name": "airConditionerMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["cool", "heat", "auto", "fan", "dry"] // 自定义模式值。配置值会覆盖默认值。
      }
    }
  },
  {
    "capability": "mode",
    "name": "fanMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["normal", "sleep", "child"] // 自定义模式值。配置值会覆盖默认值。
      }
    }
  },
  {
    "capability": "mode",
    "name": "horizontalAngle",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["30", "60", "90", "120", "180", "360"] // 自定义模式值。配置值会覆盖默认值。
      }
    }
  },
  {
    "capability": "mode",
    "name": "verticalAngle",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["30", "60", "90", "120", "180", "360"] // 自定义模式值。配置值会覆盖默认值。
      }
    }
  }
]
```

**属性（状态）：**

```
{
  "modeValue": "low" // 模式值。**类型：** String。必填。参考支持的预设模式。
}
```

**协议（查询状态与控制指令）：**

```
{
  "mode": {
    "fanLevel": {
      "modeValue": "low"
    }
  }
}
```

**二氧化碳检测 (co2)**

**能力声明示例：**

```
{
  "capability": "co2",
  "permission": "0100",
  "settings": {
    "co2Range": {
      "type": "numeric",
      "permission": "01",
      "min": 400,
      "max": 10000
    }
  }
}
```

**属性（状态）：**

```
{
  "co2": 111 // 二氧化碳浓度。**类型：** Integer。单位：ppm。
}
```

**协议（查询状态与控制指令）：**

```
{
  "co2": {
    "co2": 500
  }
}
```

**照度检测 (illumination)**

**能力声明示例：**

```
{
  "capability": "illumination",
  "permission": "0100",
  "settings": {
    "illuminationRange": {
      "type": "numeric",
      "permission": "01",
      "min": 0,
      "max": 160000
    }
  }
}
```

**属性（状态）：**

```
{
  "illumination": 11 // 照度值。**类型：** Integer。单位：lux。
}
```

**协议（查询状态与控制指令）：**

```
{
  "illumination": {
    "illumination": 50
  }
}
```

**烟雾检测 (smoke)**

**能力声明示例：**

```
{
  "capability": "smoke",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "smoke": true // 检测结果。**类型：** Boolean。`true` 表示检测到，`false` 表示未检测到。
}
```

**协议（查询状态与控制指令）：**

```
{
  "smoke": {
    "smoke": true
  }
}
```

**门磁开关检测（接触）**

**能力声明示例：**

```
{
  "capability": "contact",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "contact": true // 检测结果。**类型：** 布尔。`true` 表示检测到，`false` 表示未检测到。
}
```

**协议（查询状态与控制指令）：**

```
{
  "contact": {
    "contact": true
  }
}
```

**运动检测（motion）**

**能力声明示例：**

```
{
  "capability": "motion",
  "permission": "0110",
  "settings": {
    "motionInterval": {
      "type": "numeric",
      "permission": "11",
      "value": 300
    },
    "motionSensitivity": {
      "type": "numeric",
      "permission": "11",
      "value": 1000
    }
  }
}
```

**属性（状态）：**

```
{
  "motion": true // 检测结果。**类型：** 布尔。`true` 表示检测到，`false` 表示未检测到。
}
```

**协议（查询状态与控制指令）：**

```
{
  "motion": {
    "motion": true
  }
}
```

**漏水检测（water-leak）**

**能力声明示例：**

```
{
  "capability": "water-leak",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "waterLeak": true // 字段 `waterLeak` 表示当前检测结果。**类型：** 布尔。`true` 表示检测到，`false` 表示未检测到。
}
```

**协议（查询状态与控制指令）：**

```
{
  "water-leak": {
    "waterLeak": true
  }
}
```

**窗户检测开关（window-detection）**

**能力声明示例：**

```
{
  "capability": "window-detection",
  "permission": "1100"
}
```

**属性（状态）：**

```
{
  "powerState": "on" // 字段 `powerState` 表示电源状态。**类型：** 字符串。`on` 表示通电，`off` 表示断电。
}
```

**协议（查询状态与控制指令）：**

```
{
  "window-detection": {
    "powerState": "on"
  }
}
```

**儿童锁开关（child-lock）**

**能力声明示例：**

```
{
  "capability": "child-lock",
  "permission": "1100"
}
```

**属性（状态）：**

```
{
  "powerState": "on" // 字段 `powerState` 表示电源状态。**类型：** 字符串。`on` 表示通电，`off` 表示断电。
}
```

**协议（查询状态与控制指令）：**

```
{
  "child-lock": {
    "powerState": "on"
  }
}
```

**防直吹开关（anti-direct-blow）**

**能力声明示例：**

```
{
  "capability": "anti-direct-blow",
  "permission": "1100"
}
```

**属性（状态）：**

```
{
  "powerState": "on" // 字段 `powerState` 表示电源状态。**类型：** 字符串。`on` 表示通电，`off` 表示断电。
}
```

**协议（查询状态与控制指令）：**

```
{
  "anti-direct-blow": {
    "powerState": "on"
  }
}
```

**水平摆风开关（horizontal-swing）**

**能力声明示例：**

```
{
  "capability": "horizontal-swing",
  "permission": "1100"
}
```

**属性（状态）：**

```
{
  "powerState": "on" // 字段 `powerState` 表示电源状态。**类型：** 字符串。`on` 表示通电，`off` 表示断电。
}
```

**协议（查询状态与控制指令）：**

```
{
  "horizontal-swing": {
    "powerState": "on"
  }
}
```

**垂直摆风开关（vertical-swing）**

**能力声明示例：**

```
{
  "capability": "vertical-swing",
  "permission": "1100"
}
```

**属性（状态）：**

```
{
  "powerState": "on" // 字段 `powerState` 表示电源状态。**类型：** 字符串。`on` 表示通电，`off` 表示断电。
}
```

**协议（查询状态与控制指令）：**

```
{
  "vertical-swing": {
    "powerState": "on"
  }
}
```

**节能模式开关（eco）**

**能力声明示例：**

```
{
  "capability": "eco",
  "permission": "1100"
}
```

**属性（状态）：**

```
{
  "powerState": "on" // 字段 `powerState` 表示电源状态。**类型：** 字符串。`on` 表示通电，`off` 表示断电。
}
```

**协议（查询状态与控制指令）：**

```
{
  "eco": {
    "powerState": "on"
  }
}
```

**切换启动（toggle-startup）**

**能力声明示例：**

```
{
  "capability": "toggle-startup",
  "permission": "1100",
  "name": "1" // 字段 `name` 指定 `toggle-startup` 的属性名称。**类型：** 字符串。仅允许字母和数字。
}
```

**属性（状态）：**

```
{
  "startup": "on" // **类型：** 字符串。选项：`on`（上电），`stay`（保持供电），`off`（断电）。
}
```

**协议（查询状态与控制指令）：**

```
{
  "toggle-startup": {
    "1": {
      "startup": "on"
    },
    "2": {
      "startup": "off"
    }
  }
}
```

**检测保持（detect-hold）**

**能力声明示例：**

```
{
  "capability": "detect-hold",
  "permission": "0100",
  "settings": {
    "detectHoldEnable": { // 检测保持启用设置
      "permission": "01",
      "type": "boolean",
      "value": false
    },
    "detectHoldSwitch": { // 检测保持动作设置
      "type": "enum",
      "permission": "01",
      "value": "on",
      "values": ["on", "off"]
    },
    "detectHoldTime": { // 检测保持时间设置
      "type": "numeric",
      "permission": "01",
      "min": 1,
      "max": 359,
      "value": 5,
      "unit": "minute"
    }
  }
}
```

**属性（状态）：**

```
{
  "detectHold": "on" // 字段 `detectHold` 表示检测保持状态。**类型：** 字符串。`on` 表示检测保持生效，`off` 表示检测保持失效。
}
```

**协议（查询状态与控制指令）：**

```
{
  "detect-hold": {
    "detectHold": "on"
  }
}
```

**切换识别/激活（toggle-identify）**

**能力声明示例：**

```
{
  "capability": "toggle-identify",
  "permission": "1100", // 注意：该能力在当前版本（V1.13.7）ihost 上不用于上报。
  "name": "1" // 组件名称。**类型：** 字符串。可选值："1"（通道1）、"2"（通道2）、"3"（通道3）、"4"（通道4）。
}
```

**属性（状态）：**

```
{
  "identify": true, // 表示设备已主动上报识别或激活。
  "countdown": 180 // 字段 `countdown` 表示激活持续时间。**类型：** 数字。单位：秒。
}
```

**协议（查询状态与控制指令）：**

```
{
  "toggle-identify": {
    "1": {
      "countdown": 180 // 激活设备 180 秒。
    }
  }
}

// 设备上报自激活
{
  "toggle-identify": {
    "1": {
      "identify": true
    }
  }
}
```

**切换电压检测（toggle-voltage）**

**能力声明示例：**

```
{
  "capability": "toggle-voltage",
  "permission": "1100"
}
```

**属性（状态）：**

```
{
  "voltage": 230 // 字段 `voltage` 表示检测到的电压。**类型：** 数字。单位：伏特。
}
```

**协议（查询状态与控制指令）：**

```
{
  "toggle-voltage": {
    "voltage": 230
  }
}
```

**子组件电流检测（toggle-electric-current）**

**能力声明示例：**

```
[
  {
    "capability": "toggle-electric-current",
    "permission": "0100",
    "name": "1" // 组件名称。**类型：** 字符串。可选值："1"（通道1）、"2"（通道2）、"3"（通道3）、"4"（通道4）。
  }
]
```

**属性（状态）：**

```
{
  "electricCurrent": 50 // 字段 `electricCurrent` 表示电流值。**单位：** 0.01 A。**类型：** 整数。值必须大于等于 0。
}
```

**协议（查询状态与控制指令）：**

```
{
  "toggle-electric-current": {
    "1": {
      "electricCurrent": 50
    }
  }
}
```

**子组件功率检测（toggle-electric-power）**

**能力声明示例：**

```
[
  {
    "capability": "toggle-electric-power",
    "permission": "0100",
    "name": "1" // 组件名称。**类型：** 字符串。可选值："1"（通道1）、"2"（通道2）、"3"（通道3）、"4"（通道4）。
  }
]
```

**属性（状态）：**

```
{
  "electricPower": 50, // 字段 `electricPower` 表示当前功率值。**单位：** 0.01 W。**类型：** 整数。值必须大于等于 0。
  "reactivePower": 50, // 字段 `reactivePower` 表示当前无功功率值。**单位：** 0.01 W。**类型：** 整数。可选。
  "activePower": 50, // 字段 `activePower` 表示当前有功功率值。**单位：** 0.01 W。**类型：** 整数。可选。
  "apparentPower": 50 // 字段 `apparentPower` 表示当前视在功率值。**单位：** 0.01 W。**类型：** 整数。可选。
}
```

**协议（查询状态与控制指令）：**

```
{
  "toggle-electric-power": {
    "1": {
      "electricPower": 50,
      "reactivePower": 50,
      "activePower": 50,
      "apparentPower": 50
    }
  }
}
```

**子组件能耗统计（toggle-power-consumption）**

**能力声明示例：**

```
[
  {
    "capability": "toggle-power-consumption",
    "permission": "1101",
    "name": "1", // 组件名称。**类型：** 字符串。可选值："1"（通道1）、"2"（通道2）、"3"（通道3）、"4"（通道4）。
    "settings": {
      "resolution": {
        "permission": "01",
        "type": "numeric",
        "value": 3600
      },
      "timeZoneOffset": {
        "permission": "01",
        "type": "numeric",
        "min": -12,
        "max": 14,
        "value": 0
      }
    }
  }
]
```

**属性（状态）：**

开始/停止实时统计：

```
{
  "rlSummarize": true, // 开始或停止实时统计。**类型：** 布尔。必填。
  "timeRange": { // 汇总时间范围。必填。
    "start": "2020-07-05T08:00:00Z", // 能耗开始时间。**类型：** 字符串。必填。
    "end": "2020-07-05T09:00:00Z" // 能耗结束时间。**类型：** 字符串。必填。
  }
}
```

按时间范围查询用电：

```
{
  "type": "summarize", // 汇总类型。**类型：** 字符串。必填。选项："rlSummarize"（实时汇总）、"summarize"（当前汇总）。
  "timeRange": { // 汇总时间范围，当 type 为 "summarize" 时必填。
    "start": "2020-07-05T08:00:00Z", // 能耗开始时间。**类型：** 字符串。必填。
    "end": "2020-07-05T09:00:00Z" // 能耗结束时间。**类型：** 字符串。可选。如未提供，默认使用当前时间。
  }
}
```

指定时间范围内的能耗响应：

```
{
  "type": "summarize", // 汇总类型。**类型：** 字符串。必填。
  "rlSummarize": 50.0, // 总能耗。**单位：** 0.01 kWh。**类型：** 数字。可选。
  "electricityIntervals": [ // 按 `configuration.resolution` 划分为多个记录。可选。当 type 为 "rlSummarize" 时不存在。
    {
      "usage": 26.5, // 能耗。**单位：** 0.01 kWh。**类型：** 数字。必填。
      "start": "2020-07-05T08:00:00Z", // 开始时间。**类型：** 字符串。必填。
      "end": "2020-07-05T09:00:00Z" // 结束时间。**类型：** 字符串。必填。间隔短于 resolution 的记录视为无效。
    },
    {
      "usage": 26.5, // 能耗。**单位：** 0.01 kWh。**类型：** 数字。必填。
      "start": "2020-07-05T09:00:00Z", // 开始时间。**类型：** 字符串。必填。
      "end": "2020-07-05T10:00:00Z" // 结束时间。**类型：** 字符串。必填。间隔短于 resolution 的记录视为无效。
    }
  ]
}
```

**协议（查询状态与控制指令）：**

开始实时统计：

```
{
  "toggle-power-consumption": {
    "1": {
      "rlSummarize": true,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": ""
      }
    }
  }
}
```

停止实时统计：

```
{
  "toggle-power-consumption": {
    "1": {
      "rlSummarize": false,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": "2020-07-05T09:00:00Z"
      }
    }
  }
}
```

获取历史用电：

```
{
  "toggle-power-consumption": {
    "1": {
      "type": "summarize",
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": "2020-07-05T09:00:00Z"
      }
    }
  }
}
```

获取实时用电：

```
{
  "toggle-power-consumption": {
    "1": {
      "type": "rlSummarize"
    }
  }
}
```

**链路质量指示器（lqi）**

**能力声明示例：**

```
{
  "capability": "lqi",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "lqi": 60 // 字段 `lqi` 表示链路质量指示值。**类型：** 数字。取值范围：0 到 255。
}
```

**协议（查询状态与控制指令）：**

```
{
  "lqi": {
    "lqi": 60
  }
}
```

**功能配置（configuration）**

**能力声明示例：**

```
[
  {
    "capability": "configuration",
    "permission": "1100"
  }
]
```

**属性（状态）：**

```
{
  "deviceConfiguration": { // 设备相关的功能配置
    "defaultResolution": 300, // 读取湿度饱和度数据的默认分辨率。**类型：** 整数。**单位：** 秒。必填。
    "maxResolution": 86400, // 读取湿度饱和度数据的最大分辨率。**类型：** 整数。**单位：** 秒。必填。
    "minResolution": 60 // 读取湿度饱和度数据的最小分辨率。**类型：** 整数。**单位：** 秒。必填。
  }
}
```

**协议（查询状态与控制指令）：**

```
{
  "configuration": {
    "deviceConfiguration": { // 设备相关的功能配置
      "defaultResolution": 300, // 读取湿度饱和度数据的默认分辨率。**类型：** 整数。**单位：** 秒。必填。
      "maxResolution": 86400, // 读取湿度饱和度数据的最大分辨率。**类型：** 整数。**单位：** 秒。必填。
      "minResolution": 60 // 读取湿度饱和度数据的最小分辨率。**类型：** 整数。**单位：** 秒。必填。
    }
  }
}
```

**系统（system）**

**能力声明示例：**

```
[
  {
    "capability": "system",
    "permission": "1000"
  }
]
```

**属性（状态）：**

```
{
  "restart": true // 重启设备命令。**类型：** 布尔。必填。值必须为 `true`。
}
```

**协议（查询状态与控制指令）：**

```
{
  "system": { // 与能力相关的配置。可选。
    "restart": true
  }
}
```

**湿度（moisture）**

**能力声明示例：**

```
[
  {
    "capability": "moisture",
    "permission": "0100"
  }
]
```

**属性（状态）：**

```
{
  "moisture": 55.5 // 字段 `moisture` 表示湿度饱和度百分比。**类型：** 数字。必填。范围：0 到 100。
}
```

**协议（查询状态与控制指令）：**

```
{
  "moisture": {
    "moisture": 55.5
  }
}
```

**气压（barometric-pressure）**

**能力声明示例：**

```
[
  {
    "capability": "barometric-pressure",
    "permission": "0100",
    "settings": {
      "barometricPressureRange": {
        "type": "numeric",
        "permission": "01",
        "min": 540, // 最小值。**类型：** 整数。必填。必须小于 `max`。
        "max": 1100 // 最大值。**类型：** 整数。必填。必须大于 `min`。
      }
    }
  }
]
```

**属性（状态）：**

```
{
  "barometricPressure": 50 // 气压值。**类型：** 整数。必填。**单位：** hPa。
}
```

**协议（查询状态与控制指令）：**

```
{
  "barometric-pressure": {
    "barometricPressure": 50
  }
}
```

**风速（wind-speed）**

**能力声明示例：**

```
[
  {
    "capability": "wind-speed",
    "permission": "0100",
    "settings": {
      "windSpeedRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // 最小值。**类型：** 数字。必填。必须小于 `max`。
        "max": 50 // 最大值。**类型：** 数字。必填。必须大于 `min`。
      }
    }
  }
]
```

**属性（状态）：**

```
{
  "windSpeed": 50 // 风速值。**类型：** 数字。必填。**单位：** m/s（米/秒）。
}
```

**协议（查询状态与控制指令）：**

```
{
  "wind-speed": {
    "windSpeed": 50
  }
}
```

**风向（wind-direction）**

**能力声明示例：**

```
[
  {
    "capability": "wind-direction",
    "permission": "0100"
  }
]
```

**属性（状态）：**

```
{
  "windDirection": 10 // 风向。**类型：** 整数。必填。**单位：** 度。范围：0 到 360 度（顺时针方向）。
}
```

**协议（查询状态与控制指令）：**

```
{
  "wind-direction": {
    "windDirection": 10
  }
}
```

**降雨量（rainfall）**

**能力声明示例：**

```
[
  {
    "capability": "rainfall",
    "permission": "0100",
    "settings": {
      "rainfallRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // 最小值。**类型：** 数字。必填。必须小于 `max`。
        "max": 450 // 最大值。**类型：** 数字。必填。必须大于 `min`。
      }
    }
  }
]
```

**属性（状态）：**

```
{
  "rainfall": 11.11 // 降雨量值。**类型：** 数字。必填。**单位：** mm/h（毫米/小时）。
}
```

**协议（查询状态与控制指令）：**

```
{
  "rainfall": {
    "rainfall": 11.11
  }
}
```

**紫外线指数（ultraviolet-index）**

**能力声明示例：**

```
[
  {
    "capability": "ultraviolet-index",
    "permission": "0100",
    "settings": {
      "ultravioletIndexRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // 最小值。**类型：** 数字。必填。必须小于 `max`。
        "max": 16 // 最大值。**类型：** 数字。必填。必须大于 `min`。
      }
    }
  }
]
```

**属性（状态）：**

```
{
  "ultravioletIndex": 11.1 // 紫外线指数。**类型：** 数字。必填。
}
```

**协议（查询状态与控制指令）：**

```
{
  "ultraviolet-index": {
    "ultravioletIndex": 11.1
  }
}
```

**电导率（electrical-conductivity）**

**能力声明示例：**

```
[
  {
    "capability": "electrical-conductivity",
    "permission": "0100",
    "settings": {
      "electricalConductivityRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // 最小值。**类型：** 数字。必填。必须小于 `max`。
        "max": 23 // 最大值。**类型：** 数字。必填。必须大于 `min`。
      }
    }
  }
]
```

**属性（状态）：**

```
{
  "electricalConductivity": 11.11 // 电导率值。**类型：** 数字。必填。**单位：** dS/m。
}
```

**协议（查询状态与控制指令）：**

```
{
  "electrical-conductivity": {
    "electricalConductivity": 11.11
  }
}
```

**发射功率（transmit-power）**

**能力声明示例：**

```
[
  {
    "capability": "transmit-power",
    "permission": "1100"
  }
]
```

**属性（状态）：**

```
{
  "transmitPower": 9 // 设备发射功率值。**类型：** 整数。必填。**单位：** dBm。
}
```

**协议（查询状态与控制指令）：**

```
{
  "transmit-power": {
    "transmitPower": 9
  }
}
```

**PM2.5 检测（pm25）**

**能力声明示例：**

```
[
  {
    "capability": "pm25",
    "permission": "0100"
  }
]
```

**属性（状态）：**

```
{
  "pm25": 10 // 空气中 PM2.5 浓度。**类型：** 数字。必填。**单位：** µg/m³。
}
```

**协议（查询状态与控制指令）：**

```
{
  "pm25": {
    "pm25": 10
  }
}
```

**挥发性有机物指数（voc-index）**

**能力声明示例：**

```
{
  "capability": "voc-index",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "vocIndex": 10 // VOC 指数，反映有害气体污染程度。**类型：** 数字。必填。**单位：** µg/m³。
}
```

**协议（查询状态与控制指令）：**

```
{
  "voc-index": {
    "vocIndex": 10
  }
}
```

**天然气检测（gas）**

**能力声明示例：**

```
{
  "capability": "gas",
  "permission": "0100"
}
```

**属性（状态）：**

```
{
  "gas": true // 表示是否检测到天然气泄漏。**类型：** 布尔。必填。
}
```

**协议（查询状态与控制指令）：**

```
{
  "gas": {
    "gas": true
  }
}
```

**灌溉工作状态（irrigation/work-status）**

**能力声明示例：**

```
[
  {
    "capability": "irrigation",
    "permission": "0101",
    "name": "work-status",
    "settings": {
      "volumeUnit": {
        "type": "enum",
        "permission": "01",
        "values": ["L"],
        "value": "L"
      }
    }
  }
]
```

**属性（状态）：**

```
{
  "realTimeVolume": 20, // 实时灌溉体积。**类型：** 数字。可选。**单位：** L。
  "start": "2020-07-05T08:00:00Z", // 灌溉开始时间。**类型：** 日期。可选。
  "end": "2020-07-05T09:00:00Z", // 灌溉结束时间。**类型：** 日期。可选。
  "dailyVolume": 20 // 日灌溉体积。**类型：** 数字。可选。**单位：** L。
}
```

**协议（查询状态与控制指令）：**

工作状态上报：

```
{
  "irrigation": {
    "work-status": {
      "realTimeVolume": 20,
      "start": "2020-07-05T08:00:00Z",
      "end": "2020-07-05T09:00:00Z",
      "dailyVolume": 20
    }  
  }
}
```

工作状态查询：

```
{
  "irrigation": {
    "type": "oneDay", // 聚合类型。**类型：** 字符串。必填。选项："oneDay"、"30Days"、"180Days"。
    "timeRange": { // 聚合时间范围。**类型：** 对象。必填。
      "start": "2020-07-05T08:00:00Z", // 灌溉数据聚合开始时间。**类型：** 字符串。必填。
      "end": "2020-07-05T09:00:00Z" // 灌溉数据聚合结束时间。**类型：** 字符串。可选。若省略，使用当前时间。
    }
  }
}
```

工作状态查询结果：

```
{
  "irrigation": {
    "type": "oneDay", // 聚合类型。**类型：** 字符串。必填。
    "irrigationIntervals": [
      {
        "volume": 6500, // 灌溉体积。**类型：** 数字。必填。**单位：** L。
        "duration": 30, // 灌溉时长。**类型：** 数字。必填。**单位：** 分钟。
        "start": "2020-07-05T08:00:00Z", // 开始时间。**类型：** 字符串。必填。
        "end": "2020-07-05T09:00:00Z" // 结束时间。**类型：** 字符串。必填。
      },
      {
        "volume": 6500, // 灌溉体积。**类型：** 数字。必填。**单位：** L。
        "duration": 30, // 灌溉时长。**类型：** 数字。必填。**单位：** 分钟。
        "start": "2020-07-05T08:00:00Z", // 开始时间。**类型：** 字符串。必填。
        "end": "2020-07-05T09:00:00Z" // 结束时间。**类型：** 字符串。必填。
      }
    ]
  }
}
```

**灌溉工作模式（irrigation/work-mode）**

**能力声明示例：**

```
[
  {
    "capability": "irrigation",
    "permission": "0100",
    "name": "work-mode",
    "settings": {
      "supportedModes": {
        "type": "enum",
        "permission": "01",
        "values": [
          "MANUAL", // 手动模式
          "TIMER", // 单次定时
          "CYCLE-TIMER", // 循环定时
          "VOLUME", // 单次定量
          "CYCLE-VOLUME" // 循环定量
        ]
      }
    }
  }
]
```

**属性（状态）：**

```
{
  "workMode": "MANUAL" // 灌溉工作模式。**类型：** 字符串。可选。值应来自 `settings.supportedModes`。
}
```

**协议（查询状态与控制指令）：**

```
{
  "irrigation": {
    "work-mode": "MANUAL"
  }
}
```

**自动灌溉控制器（irrigation/auto-controller）**

**能力声明示例：**

```
[
  {
    "capability": "irrigation",
    "permission": "1100",
    "name": "auto-controller",
    "settings": {
      "volumeRange": { // 体积范围
        "type": "enum",
        "permission": "01",
        "min": 0,
        "max": 6500,
        "unit": "L"
      },
      "timeRange": { // 时间范围
        "type": "enum",
        "permission": "01",
        "min": 1,
        "max": 86400,
        "unit": "second"
      },
      "cycleCountRange": { // 循环次数范围
        "type": "enum",
        "permission": "01",
        "min": 1,
        "max": 100,
        "step": 1
      }
    }
  }
]
```

**属性（状态）：**

单次或循环定时：

```
{
  "type": "time", // 灌溉模式。**类型：** 字符串。必填。选项："volume"、"time"。
  "action": {
    "perDuration": 60, // 每次灌溉周期时长。**类型：** 数字。必填。
    "intervalDuration": 20, // 灌溉周期之间的间隔时长。**类型：** 数字。必填。
    "count": 3 // 灌溉周期次数。**类型：** 数字。必填。
  }
}
```

单次或循环定量：

```
{
  "type": "volume", // 灌溉模式。**类型：** 字符串。必填。选项："volume"、"time"。
  "action": {
    "perConsumedVolume": 60, // 每次灌溉周期消耗的体积。**类型：** 数字。必填。
    "intervalDuration": 20, // 灌溉周期之间的间隔时长。**类型：** 数字。必填。
    "count": 3 // 灌溉周期次数。**类型：** 数字。必填。
  }
}
```

**协议（查询状态与控制指令）：**

单次或循环定时：

```
{
  "irrigation": {
    "auto-controller": {
      "type": "time", // 灌溉模式。**类型：** 字符串。必填。
      "action": {
        "perDuration": 60, // 每次灌溉周期时长。**类型：** 数字。必填。
        "intervalDuration": 20, // 周期间隔时长。**类型：** 数字。必填。
        "count": 3 // 周期次数。**类型：** 数字。必填。
      }
    }
  }
}
```

单次或循环定量：

```
{
  "irrigation": {
    "auto-controller": {
      "type": "volume", // 灌溉模式。**类型：** 字符串。必填。
      "action": {
        "perConsumedVolume": 60, // 每周期消耗体积。**类型：** 数字。必填。
        "intervalDuration": 20, // 周期间隔时长。**类型：** 数字。必填。
        "count": 3 // 周期次数。**类型：** 数字。必填。
      }
    }
  }
}
```

**支持的预设模式**

| \*\*模式名称 \*\*                      | \*\*可选值 \*\* |
| ---------------------------------- | ------------ |
| 风扇档位（fanLevel）                     | "low"        |
| "medium"                           |              |
| "high"                             |              |
| 恒温器模式（thermostatMode）              | "auto"       |
| "manual"                           |              |
| 空调模式 >= 1.11.0（airConditionerMode） | "cool"       |
| "heat"                             |              |
| "auto"                             |              |
| "fan"                              |              |
| "dry"                              |              |
| 风扇模式 >= 1.11.0（fanMode）            | "normal"     |
| "sleep"                            |              |
| "child"                            |              |
| 水平角度 >= 1.11.0（horizontalAngle）    | "30"         |
| "60"                               |              |
| "90"                               |              |
| "120"                              |              |
| "180"                              |              |
| "360"                              |              |
| 垂直角度 >= 1.11.0（verticalAngle）      | "30"         |
| "60"                               |              |
| "90"                               |              |
| "120"                              |              |
| "180"                              |              |
| "360"                              |              |

#### c. 标签说明

* 特殊键 toggle 用于设置 toggle 子组件的名称。

```
{
    "toggle": {
        '1': 'Chanel1',
        '2': 'Chanel2',
        '3': 'Chanel3',
        '4': 'Chanel4',
    },
}
```

* 特殊键 temperature\_unit 用于设置温度单位。

```
{
    "temperature_unit":'c' // c-摄氏度；f-华氏度
}
```

#### d. 特殊错误代码及说明

| **错误代码** | **描述**                  | iHost 版本 |
| -------- | ----------------------- | -------- |
| 110000   | 对应 id 的子设备/组不存在         | ≥2.1.0   |
| 110001   | 网关处于发现 zigbee 设备状态      | ≥2.1.0   |
| 110002   | 组内设备没有公共能力              | ≥2.1.0   |
| 110003   | 设备数量不正确                 | ≥2.1.0   |
| 110004   | 组数量不正确                  | ≥2.1.0   |
| 110005   | 设备离线                    | ≥2.1.0   |
| 110006   | 更新设备状态失败                | ≥2.1.0   |
| 110007   | 更新组状态失败                 | ≥2.1.0   |
| 110008   | 已达到最大分组数。最多可创建 50 个组    | ≥2.1.0   |
| 110009   | 摄像机设备的 IP 地址不正确         | ≥2.1.0   |
| 110010   | 摄像机设备访问授权错误             | ≥2.1.0   |
| 110011   | 摄像机设备流地址错误              | ≥2.1.0   |
| 110012   | 摄像机设备视频编码不受支持           | ≥2.1.0   |
| 110013   | 设备已存在                   | ≥2.1.0   |
| 110014   | 摄像机不支持离线操作              | ≥2.1.0   |
| 110015   | 账号密码与 RTSP 流地址中的账号密码不一致 | ≥2.1.0   |
| 110016   | 网关处于发现 onvif 摄像机状态      | ≥2.1.0   |
| 110017   | 超出可添加摄像机的最大数量           | ≥2.1.0   |
| 110018   | ESP 摄像机的路径错误            | ≥2.1.0   |
| 110019   | 无法访问第三方设备的服务地址          | ≥2.1.0   |

#### e. 搜索子设备

允许授权用户通过该接口启用或禁用网关对子设备的搜索

* 💡注意：目前仅支持搜索 Zigbee 子设备。
* 💡注意：Zigbee 子设备搜索后会自动添加。无需使用 “手动添加子设备” 接口 :::tips
* **URL**：/open-api/V2/rest/devices/discovery
* **方法**: PUT
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：

| **属性** | **类型**  | **是否可选** | **描述**                 |
| ------ | ------- | -------- | ---------------------- |
| enable | boolean | 否        | true（开始配对）；false（暂停配对） |
| type   | string  | 否        | 搜索类型：Zigbee            |

成功的数据响应：空对象 {} :::提示 **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\* `200 OK` ::: **响应示例**:

```
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

#### f. 手动添加子设备

允许授权用户通过此接口添加一个 **单个** 子设备。

* 注意：目前仅支持 RTSP 摄像机和 ESP32 摄像机 :::tips
* **URL**：/open-api/V2/rest/devices
* **方法**：POST
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：

| **属性**            | **类型**              | **是否可选** | **描述**                                                                 |
| ----------------- | ------------------- | -------- | ---------------------------------------------------------------------- |
| name              | string              | 否        | 子设备名称                                                                  |
| display\_category | string              | 否        | 设备类型。仅支持摄像头。                                                           |
| capabilities      | CapabilityObject\[] | 否        | 能力列表。当 display\_category = camera 时，capabilities 仅包含 camera-stream 能力。 |
| protocal          | string              | 否        | 设备协议。RTSP；ESP32-CAM                                                    |
| manufacturer      | string              | 否        | 制造商。                                                                   |
| model             | string              | 否        | 设备型号                                                                   |
| firmware\_version | string              | 否        | 设备固件版本                                                                 |

CapabilityObject

| **属性**        | **类型**                          | **是否可选** | **描述**                   |
| ------------- | ------------------------------- | -------- | ------------------------ |
| capability    | string                          | 否        | 能力名称。仅支持 "camera-stream" |
| permission    | string                          | 否        | 设备权限。仅支持读取。              |
| configuration | CameraStreamConfigurationObject | Y        | 摄像流配置。                   |

SettingsObject

| **属性**        | **类型**              | **是否可选** | **描述** |
| ------------- | ------------------- | -------- | ------ |
| streamSetting | StreamSettingObject | 否        | 流服务配置  |

StreamSettingObject

| **属性**     | **类型**                   | **是否可选** | **描述**              |
| ---------- | ------------------------ | -------- | ------------------- |
| type       | string                   | 否        | 流服务配置               |
| permission | string                   | 否        | 能力权限。仅支持 "11"（可修改）。 |
| value      | StreamSettingValueObject | 否        | 具体配置值               |

StreamSettingValueObject

| **属性**                                                                  | **类型** | **是否可选** | **描述**   |
| ----------------------------------------------------------------------- | ------ | -------- | -------- |
| stream\_url                                                             | string | 否        | 流 URL 格式 |
| 格式：`<schema>://<hostname>:<port>/<username>:<password>@<service_path>`  |        |          |          |
| 示例：`rtsp://admin:123456@192.168.10.115:554/streaming/channel01`         |        |          |          |
| 方案选项：                                                                   |        |          |          |
| `rtsp` （实时流传输协议）                                                        |        |          |          |
| `http` （超文本传输协议）— 适用于 ESP32-CAM 设备                                      |        |          |          |
| \*注意：有些摄像机可能不需要用户名或密码。在此情况下，可以从 URL 中省略 `<username>` 和 `<password>` 字段。 |        |          |          |

成功的数据响应：

| **属性**         | **类型** | **是否可选** | **描述**  |
| -------------- | ------ | -------- | ------- |
| serial\_number | string | 否        | 设备唯一序列号 |

:::提示 **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```
{
  "error": 0,
  "data": {
    "serial_number": "serial_number"
  },
  "message": "success"
}
```

失败数据响应：空对象 :::tips **条件**：

1. 摄像机流地址访问错误（格式错误、授权失败、网络异常等）
2. 设备已存在
3. 若单个设备添加失败，则返回所有设备添加失败。

**状态码**: 200 OK **错误代码**： ● 110009 摄像机 IP 地址错误 ● 110010 摄像机访问授权错误 ● 110011 摄像机流地址错误 ● 110012 摄像机视频编码不支持 ● 110013 设备已存在 ::: **响应示例**:

```
{
  "error": 110009,
  "data": {},
  "message": "camera ip access failed" 
}
```

#### g. 获取子设备列表

允许授权用户通过该接口获取网关子设备列表。 :::tips

* **URL**：/open-api/V2/rest/devices
* **方法**: GET
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：无 成功的数据响应：

| **属性**       | **类型**                  | **是否可选** | **描述** |
| ------------ | ----------------------- | -------- | ------ |
| device\_list | ResponseDeviceObject\[] | 否        | 设备列表   |

ResponseDeviceObject

| **属性**                | **类型**              | **是否可选**               | **描述**                                                        |
| --------------------- | ------------------- | ---------------------- | ------------------------------------------------------------- |
| serial\_number        | string              | 否                      | 设备唯一序列号                                                       |
| third\_serial\_number | string              | 当连接第三方设备时为 "N"，否则为 "Y" | 第三方设备唯一序列号                                                    |
| service\_address      | string              | 当连接第三方设备时为 "N"，否则为 "Y" | 第三方服务地址                                                       |
| name                  | string              | 否                      | 设备名称，若未重命名，前端将根据默认显示规则展示。                                     |
| manufacturer          | string              | 否                      | 制造商                                                           |
| model                 | string              | 否                      | 设备型号                                                          |
| firmware\_version     | string              | 否                      | 固件版本。可以为空字符串。                                                 |
| hostname              | string              | Y                      | 设备主机名                                                         |
| mac\_address          | string              | Y                      | 设备 MAC 地址                                                     |
| app\_name             | string              | Y                      | 所属应用的名称。如果在获取开放接口证书时填写了 app\_name，那么后续通过该证书连接的所有设备都会写入此字段。    |
| display\_category     | string              | 否                      | 设备分类                                                          |
| capabilities          | CapabilityObject\[] | 否                      | 设备能力                                                          |
| protocol              | string              | 当连接第三方设备时为 "N"，否则为 "Y" | 设备协议：zigbee、onvif、rtsp、esp32-cam                              |
| state                 | object              | Y                      | 设备状态对象。有关不同能力的状态示例，请查看【支持的设备能力】                               |
| 标签                    | object              | Y                      | JSON 格式的键值，自定义设备信息。用途如下：- 用于存储设备通道- 用于存储温度单位- 存储其他第三方设备的自定义信息 |
| 在线                    | boolean             | 否                      | 在线状态：True 表示在线；False 表示离线                                     |
| 子网                    | boolean             | Y                      | 是否与网关在同一子网内                                                   |

CapabilityObject 💡注意：请查看【支持的设备能力】中的支持设备能力示例。

| **属性**        | **类型** | **是否可选** | **描述**                                                |
| ------------- | ------ | -------- | ----------------------------------------------------- |
| capability    | string | 否        | 能力名称。详情请参见【支持的设备能力】                                   |
| permission    | string | 否        | 能力权限。可能的值为“read”（可读）、“write”（可写）、“readWrite”（可读可写）。   |
| configuration | object | Y        | 能力配置信息。目前用于 camera-stream，详见【支持的设备能力】                 |
| name          | string | Y        | toggle 中的 name 字段。用于标识多通道设备的子通道编号。例如，name 为 1 表示通道 1。 |

:::提示 **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```
{
  "error": 0,
  "data":{
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "name": "我的设备",
        "manufacturer": "SONOFF",
        "model": "BASICZBR3",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          },
          {
            "capability": "rssi",
            "permission": "read"
          }
        ],
        "protocal": "zigbee",
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ],
  }
  "message": "success"
}
```

#### h. 更新指定设备信息或状态

允许授权用户通过此接口修改子设备的基本信息并发送控制命令。:::tips

* **URL**：/open-api/V2/rest/devices/{serial\_number}
* **方法**：PUT
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：

| **属性**        | **类型** | **是否可选** | **描述**                            |
| ------------- | ------ | -------- | --------------------------------- |
| name          | string | Y        | 设备名称                              |
| 标签            | object | Y        | JSON 格式的键值，自定义设备信息。               |
| state         | object | Y        | 设备状态对象。有关不同能力的状态示例，请查看【支持的设备能力】   |
| configuration | object | Y        | 能力配置信息，目前仅 camera\_stream 能力支持修改。 |

成功的数据响应：:::tips **条件**：请求参数合法，且用户身份验证通过。\*\*状态码：\*\*200 OK **错误代码**:

* 110000：对应 id 的子设备/分组不存在 ::: **响应示例**:

```
{
  "error": 0,
  "data":{
    "serial_number": "ABCDEFGHIJK",
    "third_serial_number": "third_serial_number",
    "name": "我的设备",
    "manufacturer": "SONOFF",
    "model": "BASICZBR3",
    "firmware_version": "1.1.0",
    "display_category": "switch",
    "capabilities": [
      {
        "capability": "power",
        "permission": "1100"
      },
      {
        "capability": "rssi",
        "permission": "0100"
      }
    ],
    "protocal": "zigbee",
    "state": {
      "power": {
        "powerState": "on"
      }
    },
    "tags": {
      "key": "value"
    },
    "online": true
  },
  "message": "success"
}
```

#### i. 删除子设备

允许授权用户通过此接口删除子设备。:::tips

* **URL**：/open-api/V2/rest/devices/{serial\_number}
* **方法**：DELETE
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：

| **属性**       | **类型**               | **是否可选** | **描述**                                        |
| ------------ | -------------------- | -------- | --------------------------------------------- |
| name         | string               | Y        | 设备名称。                                         |
| 标签           | object               | Y        | 以 JSON 格式的键值对，用于存储设备通道名称及子设备的其他信息。            |
| state        | object               | Y        | 改变设备状态；具体协议细节请参阅“支持的设备能力”。                    |
| capabilities | CapabilityObject \[] | Y        | 能力配置信息；所有支持设置配置的能力均可修改。注意，权限（permission）不可更改。 |

成功的数据响应：:::tips **条件**：请求参数合法，且用户身份验证通过。\*\*状态码：\*\*200 OK **错误代码：**

* 110000：对应 ID 的子设备/分组不存在。
* 110006：更新设备状态失败。
* 110019：访问第三方设备服务地址失败。
* 110024：更新设备配置失败。::: **响应示例**:

```
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

```javascript
import axios from 'axios';

const serial_number = 'serial_number';
const access_token = 'access_token';

(async function main() {
  // 打开设备
  await axios({
    url: `http://<域名或 IP 地址>/open-api/v2/rest/devices/${serial_number}`,
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${access_token}`
    },
    data: {
      state: {
        power: {
          powerState: 'on'
        }
      }
    }
  });
})()
```

#### j. 删除子设备

允许授权用户通过此接口删除子设备。\
:::tips

* **URL**：`/open-api/v2/rest/devices/{serial_number}`
* **方法**：`DELETE`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：无 成功的数据响应：:::tips **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

#### k. 查询设备状态

允许授权用户通过此接口查询设备状态。\
:::tips

* **URL**：`/open-api/v2/rest/devices/:serial_number/query-state/{capability}`
* **方法**：POST
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：

| **属性**       | **类型** | **是否可选** | **描述**                     |
| ------------ | ------ | -------- | -------------------------- |
| query\_state | object | 否        | 查询设备状态；具体协议细节请参阅“支持的设备能力”。 |

```javascript
import axios from 'axios';

const serial_number = 'serial_number';
const access_token = 'access_token';

(async function main() {
  // 打开设备
  await axios({
    url: `http://<域名或 IP 地址>/open-api/v2/rest/devices/${serial_number}/query-state/power-consumption`,
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${access_token}`
    },
    data: {
      "query_state":{
        "power-consumption":{
          "type": "summarize", // 统计类型，必填
          "timeRange": { // 汇总的时间范围，当 type="summarize" 时必填
            "start": "2020-07-05T08:00:00Z", // 用电量统计的开始时间
            "end": "2020-07-05T09:00:00Z" // 用电量统计的结束时间；若省略，默认为当前时间
          }
        }
      }
    });
})()
```

成功的数据响应：:::tips **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

### 3.4 安全管理

#### a. 获取安防列表

允许授权用户通过此接口修改网关设置。:::tips

* **URL**：`/open-api/v2/rest/security`
* **方法**：`GET`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：无 成功的数据响应：

| **属性**         | **类型**                    | **是否可选** | **描述** |
| -------------- | ------------------------- | -------- | ------ |
| security\_list | ResponseSecurityObject\[] | 否        | 响应设备列表 |

ResponseDeviceObject

| **属性** | **类型** | **是否可选** | **描述** |
| ------ | ------ | -------- | ------ |
| sid    | int    | 否        | 安防 id  |
| name   | string | 否        | 安防名称   |
| enable | bool   | 否        | 是否启用   |

* true 启用
* false 禁用 |

:::提示 **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```json
{
  "error": 0,
  "data": {
    "security_list":[
      {
        "sid": 1,
        "name": "家庭模式",
        "enable": true
      }
    ]
  },
  "message": "success"
}
```

#### b. 启用指定安防模式

允许授权用户通过此接口启用指定的安防模式。\
:::tips

* **URL**：`/open-api/v2/rest/security/{security_id}/enable`
* **方法**：`PUT`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::tips **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

#### c. 禁用指定安防模式

允许授权用户通过此接口禁用指定的安防模式。\
:::tips

* **URL**：`/open-api/v2/rest/security/{security_id}/disable`
* **方法**：`PUT`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::tips **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

#### d. 一键启用安防设置

允许授权用户通过此接口启用一键安防设置模式。\
:::tips

* **URL**：`/open-api/v2/rest/security/enable`
* **方法**：`PUT`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::tips **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

#### e. 关闭安防

允许授权用户通过此接口关闭安防。\
:::tips

* **URL**：`/open-api/v2/rest/security/disable`
* **方法**：`PUT`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：无 成功的数据响应：空对象 {} :::tips **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\*200 OK ::: **响应示例**:

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

## 4. 第三方设备接入

### 4.1 接入说明

#### 设备接入

<figure><img src="https://2213833752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2Fg39SAJlx8k3kQ1NVFPVo%2Fimage.png?alt=media&#x26;token=83139d82-f24e-4e7c-9e75-5062e004b050" alt=""><figcaption></figcaption></figure>

#### 第三方网关接入

<figure><img src="https://2213833752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FaZyatnl9w26YKRwSW8Xd%2Fimage.png?alt=media&#x26;token=8b595f5e-37a0-42cd-8cd6-35f92fe6a7be" alt=""><figcaption></figcaption></figure>

#### 接入步骤

1. 确定设备在网关中的分类。详情请查看【支持的设备类型】。
2. 确定设备可接入的能力。详情请查看【支持的设备能力】。
3. 调用【Discovery Request】接口将设备添加到网关。
   1. *注意：您需要提供用于接收网关下发指令的服务地址，用于接收网关下发的设备控制指令*.
4. 如果第三方设备状态发生变化，您需要调用【设备状态变更上报（Device States Change Report）】接口将最新状态发送回网关。
5. 添加后，第三方设备将出现在设备列表中，拥有大部分与网关（其他非第三方设备）相同的功能。设备相关的常用开放接口可正常使用。

* 选择合适的设备类别。分类会影响设备接入网关后 UI 的最终展示效果。
* 选择正确的设备能力。能力列表将决定设备状态协议的内容。

#### 程序流程

**a. 设备接入**

<figure><img src="https://2213833752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FrwPAhV6PWyBrb8NyzcTw%2Fimage.png?alt=media&#x26;token=035de399-91a4-4525-a475-097823197c3b" alt=""><figcaption></figcaption></figure>

**b. 第三方网关接入**

<figure><img src="https://2213833752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FwEPrDBpBKGBOAtL7KbI9%2Fimage.png?alt=media&#x26;token=1b170644-f9cc-47b3-91b8-6a3710f6afa1" alt=""><figcaption></figcaption></figure>

### 4.2 接入示例

#### 开关、插座

**同步第三方设备**

```
// 请求
URL：/open-api/v2/rest/thirdparty/event
方法：POST
头部：
  Content-Type: application/json
  Authorization: Bearer  <token>
请求体：
{
  "event": {
    "header": {
      "name": "DiscoveryRequest",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "2"
    },
    "payload": {
      "endpoints": [
        {
          "third_serial_number": "third_serial_number_1",
          "name": "我的插座",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission": "1100"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "manufacturer name",
          "model": "model name",
          "firmware_version": "固件版本",
          "service_address": "http://192.168.31.14/webhook"
      	}
      ]
    }
  }
}
```

```
{
  "header": {
    "name": "Response",
    "message_id": "唯一标识，建议使用版本 4 的 UUID",
    "version": "1"
  },
  "payload": {
    "endpoints": [
      {
        "third_serial_number": "third_serial_number",
        "serial_number": "serial number"
      }
    ]
  }
}
```

**上报设备状态**

```
URL：/open-api/V2/rest/thirdparty/event
方法：POST
头部：
  Content-Type: application/json
  Authorization: Bearer  <token>
请求体：

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}
```

```
{
  "header": {
    "name": "Response",
    "message_id": "唯一标识，建议使用版本 4 的 UUID",
    "version": "1"
  },
  "payload": {}
}
```

**上报离线/在线**

```
{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "online": true
    }
  }
}
```

```
{
  "header": {
    "name": "Response",
    "message_id": "唯一标识，建议使用版本 4 的 UUID",
    "version": "1"
  },
  "payload": {}
}
```

**接收关于网关控制设备的指令**

```
URL：<service address>
方法：POST
头部：
  Content-Type: application/json
B

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "1"
    },
    "endpoint": {
      "third_serial_number": "third_serial_number",
      "serial_number": "serial_number"
    },
    "payload": {
       "state": : {
         "power": {
           "powerState": "on"
         }
       }
    }
  }
}
```

```
{
  "header": {
    "name": "Response",
    "message_id": "唯一标识，建议使用版本 4 的 UUID",
    "version": "1"
  },
  "payload": {}
}
```

**查询设备**

```
URL：/open-api/V2/rest/devices
方法：GET
头部：
  Content-Type: application/json
  Authorization: Bearer  <token>
请求体：无
```

```
{
  "error": 0,
  "data": {
    "device_list": [
      {
        "serial_number": "serial number",
        "third_serial_number": "third_serial_number",
        "name": "我的插座",
        "manufacturer": "manufacturer name",
        "model": "model name",
        "firmware_version": "固件版本",
        "display_category": "plug",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          }
        ],
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ]
  },
  "message": "success"
}
```

### 4.3 Web API

#### 第三方请求网关接口

**请求格式**

允许授权用户通过此接口向网关发送事件请求。:::tips

* **URL**：/open-api/V2/rest/thirdparty/event
* **方法**：POST
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数：

| **属性** | **类型**      | **是否可选** | **描述**      |
| ------ | ----------- | -------- | ----------- |
| event  | EventObject | 否        | 请求事件对象的结构信息 |

EventObject

| **属性**   | **类型**         | **是否可选** | **描述**                      |
| -------- | -------------- | -------- | --------------------------- |
| header   | HeaderObject   | 否        | 请求头的结构信息                    |
| endpoint | EndpointObject | Y        | 请求端点的结构信息 注意：同步新设备列表时此字段为空。 |
| payload  | PayloadObject  | 否        | 请求负载的结构信息                   |

HeaderObject

| **属性**      | **类型** | **是否可选** | **描述**                                                                                               |
| ----------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
| name        | string | 否        | 请求名称。可选参数：DiscoveryRequest：同步新设备 DeviceStatesChangeReport：设备状态更新上报 DeviceOnlineChangeReport：设备在线状态上报 |
| message\_id | string | 否        | 请求消息 ID，UUID\_V4                                                                                     |
| version     | string | 否        | 请求协议版本号。目前固定为 1                                                                                      |

EndpointObject

| **属性**                | **类型** | **是否可选** | **描述**                                 |
| --------------------- | ------ | -------- | -------------------------------------- |
| serial\_number        | string | 否        | 设备唯一序列号                                |
| third\_serial\_number | string | 否        | 第三方设备唯一序列号                             |
| 标签                    | object | Y        | JSON 格式的键值，自定义设备信息。\[设备管理功能] - \[标签说明] |

PayloadObject 根据不同的 header.name 有不同的请求结构。

**响应格式**

:::tips \*\*状态码：\*\*200 OK **响应参数：** :::

| **属性**  | **类型**        | **是否可选** | **描述**    |
| ------- | ------------- | -------- | --------- |
| header  | HeaderObject  | 否        | 响应头的结构信息  |
| payload | PayloadObject | 否        | 响应负载的结构信息 |

HeaderObject

| **属性**      | **类型** | **是否可选** | **描述**                                                                               |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| name        | string | 否        | 响应头名称。可选参数：Response：成功响应 ErrorResponse：错误响应                                          |
| message\_id | string | 否        | 响应头消息 ID，UUID\_V4。这里传入请求消息 header.message\_id\*如果请求输入参数缺少 message\_id，则响应时该字段将为空字符串。 |
| version     | string | 否        | - 请求协议版本号。目前固定为 1。                                                                   |

> 成功响应--PayloadObject ：

根据请求类型，响应结构不同。详见具体请求说明文档。

> 失败响应--PayloadObject：

| **属性** | **类型** | **是否可选** | **描述** |
| ------ | ------ | -------- | ------ |
| type   | string | 否        | 错误类型：  |

* INVALID\_PARAMETERS：参数错误
* AUTH\_FAILURE：授权错误
* INTERNAL\_ERROR：内部服务错误 | | description | string | N | 错误描述 |

**DiscoveryRequest 同步新设备列表**

* 注意：设备被同步到网关后，默认处于在线状态，即 online=true。后续的在线状态变更完全依赖第三方通过 DeviceOnlineChangeReport 接口进行同步。

**请求参数：** EndpointObject\*\*：\*\*无 PayloadObject：

| **属性**    | **类型**            | **是否可选** | **描述** |
| --------- | ----------------- | -------- | ------ |
| endpoints | EndpointObject\[] | 否        | 设备列表   |

EndpointObject：

| **属性**                | **类型**              | **是否可选** | **描述**                                         |
| --------------------- | ------------------- | -------- | ---------------------------------------------- |
| third\_serial\_number | string              | 否        | 第三方设备唯一序列号                                     |
| name                  | string              | 否        | 设备名称                                           |
| display\_category     | string              | 否        | 设备分类。详情见【支持的设备类型】。\*第三方设备目前不支持添加摄像头。           |
| capabilities          | CapabilityObject\[] | 否        | 能力列表                                           |
| state                 | object              | 否        | 初始状态信息                                         |
| manufacturer          | string              | 否        | 制造商                                            |
| model                 | string              | 否        | 设备型号                                           |
| 标签                    | object              | Y        | JSON 格式的键值，自定义设备信息：用于存储设备通道用于存储温度单位其他第三方自定义数据  |
| firmware\_version     | string              | 否        | 固件版本                                           |
| service\_address      | string              | 否        | 服务地址。例如 <http://192.168.31.14/service_address> |

请求示例：

```
{
  "event": {
    "header": {
      "name": "DiscoveryRequest",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "1"
    },
    "payload": {
      "endpoints": [
        {
          "third_serial_number": "third_serial_number_1",
          "name": "我的插座",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission" "readWrite"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "manufacturer name",
          "model": "model name",
          "firmware_version": "固件版本",
          "service_address": "http://192.168.31.14/service_address"
        }
      ]
    }
  }
}
```

**响应参数：** PayloadObject：

| **属性**    | **类型**            | **是否可选** | **描述** |
| --------- | ----------------- | -------- | ------ |
| endpoints | EndpointObject\[] | 否        | 设备列表   |

EndpointObject：

| **属性**                | **类型** | **是否可选** | **描述**     |
| --------------------- | ------ | -------- | ---------- |
| serial\_number        | string | 否        | 设备唯一序列号    |
| third\_serial\_number | string | 否        | 第三方设备唯一序列号 |

正确响应示例：

```
{
  "header": {
    "name": "Response",
    "message_id": "唯一标识，建议使用版本 4 的 UUID",
    "version": "1"
  },
  "payload": {
    "endpoints": [
      {
        "serial_number": "serial number",
        "third_serial_number": "third_serial_number"
      }
    ]
  }
}
```

错误响应示例：

```
{
  "header": {
    "name": "ErrorResponse",
    "message_id": "唯一标识，建议使用版本 4 的 UUID",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "webhook 不能为空" 
  }
}
```

**DeviceStatesChangeReport 设备状态变更上报**

* 注意：重复的状态上报可能会误触发关联场景。

**请求参数：** PayloadObject：

| **属性** | **类型** | **是否可选** | **描述**           |
| ------ | ------ | -------- | ---------------- |
| state  | object | 否        | 设备状态，详见【支持的设备能力】 |

请求示例：

```
{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number",
    },
    "payload": {
       "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}
```

**响应参数：** PayloadObject：空对象 成功响应示例：

```
{
  "header": {
    "name": "Response",
    "message_id": "唯一标识，建议使用版本 4 的 UUID",
    "version": "1"
  },
  "payload": {}
}
```

**DeviceOnlineChangeReport 设备在线状态上报**

* 注意：重复的状态上报可能会误触发关联场景。

**请求参数：** PayloadObject：

| **属性**   | **类型**  | **是否可选** | **描述**         |
| -------- | ------- | -------- | -------------- |
| 在线       | boolean | 否        | 设备在线状态 true：在线 |
| false：离线 |         |          |                |

请求示例：

```
{
  "event": {
    "header": {
      "name": "DeviceOnlineChangeReport",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
       "online": true
    }
  }
}
```

**响应参数：** PayloadObject：空对象 成功响应示例：

```
{
  "header": {
    "name": "Response",
    "message_id": "唯一标识，建议使用版本 4 的 UUID",
    "version": "1"
  },
  "payload": {}
}
```

**DeviceInformationUpdatedReport 设备信息更新上报**

* 注意：更新可能影响已有的场景或安防功能。

**请求参数：** PayloadObject：

| **属性**       | **类型** | **是否可选** | **描述** |
| ------------ | ------ | -------- | ------ |
| capabilities |        |          |        |

\| CapabilityObject\[]

\| N

\| 能力列表。详情可见支持的设备能力部分。\*\*注意：\*\*此参数只会更新 `value` 的 `设置` 键（key）内的 `CapabilityObject`，且仅当 `permission` 的 `设置` 键为 `11` 或 `01`时允许更新。关于 `设置` 在 `CapabilityObject`中的具体结构定义，请参阅第 2.3 节 设备显示分类与设备能力 的详细描述。 | | tags

\| object

\| Y

\| JSON 格式的键值，自定义设备信息。

* 可用于存储设备通道
* 可用于存储温度单位
* 其他第三方自定义数据 |

请求示例：

```json
{
  "event": {
    "header": {
      "name": "DeviceInformationUpdatedReport",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
      "capabilities": [
        {
          "capability": "detect",
          "permission": "0110",
          "settings":{
            "detectInterval":{
              "permission": "11",
              "type": "numeric",
              "value": 300,
            },
            "detectSensitivity":{
              "permission": "11",
              "type": "numeric",
              "value": 1000,
            }
          }
        }
      ]
    }
  }
}
```

**响应参数：** PayloadObject：空对象 成功响应示例：

```json
{
  "header": {
    "name": "Response",
    "message_id": "唯一标识，建议使用版本 4 的 UUID",
    "version": "2"
  },
  "payload": {}
}
```

#### 网关通过设备服务地址向该接口下发指令

* 注意：

1. 第三方需在 3 秒内响应网关的请求。否则，网关将判定命令处理超时。
2. 如果第三方服务离线，网关会将设备设置为离线状态，第三方服务需在恢复在线前通过上报设备状态（DeviceStatesChangeReport）或在线状态（DeviceOnlineChangeReport）来使设备返回在线状态。

**请求格式**

网关通过设备服务地址接口向第三方下发指令。:::tips

* **URL**：
* **方法**：POST
* **头部**：
  * Content-Type: application/json ::: 请求参数：

| **属性**    | **类型**          | **是否可选** | **描述**    |
| --------- | --------------- | -------- | --------- |
| directive | DirectiveObject | 否        | 指令对象的结构信息 |

DirectiveObject

| **属性**   | **类型**         | **是否可选** | **描述**    |
| -------- | -------------- | -------- | --------- |
| header   | HeaderObject   | 否        | 请求头的结构信息  |
| endpoint | EndpointObject | 否        | 请求端点的结构信息 |
| payload  | PayloadObject  | 否        | 请求负载的结构信息 |

HeaderObject

| **属性**      | **类型** | **是否可选** | **描述**                              |
| ----------- | ------ | -------- | ----------------------------------- |
| name        | string | 否        | 请求名称。可选参数：UpdateDeviceStates：更新设备状态 |
| message\_id | string | 否        | 请求消息 ID，UUID\_V4                    |
| version     | string | 否        | 请求协议版本号。目前固定为 1。                    |

EndpointObject

| **属性**                | **类型** | **是否可选** | **描述**                                 |
| --------------------- | ------ | -------- | -------------------------------------- |
| serial\_number        | string | 否        | 设备唯一序列号                                |
| third\_serial\_number | string | 否        | 第三方设备唯一序列号                             |
| 标签                    | object | 否        | JSON 格式的键值，自定义设备信息。\[设备管理功能] - \[标签说明] |

PayloadObject：根据不同的 `header.name`，每种都有具体的请求结构。

请求示例：

```
{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number",
      "tags": {}
    },
    "payload": {
      "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}
```

**响应格式**

:::tips \*\*HTTP 状态码：\*\*200 OK **HTTP 响应属性：** :::

| **属性** | **类型**      | **是否可选** | **描述**    |
| ------ | ----------- | -------- | --------- |
| event  | EventObject | 否        | 响应事件的结构信息 |

EventObject

| **属性**  | **类型**        | **是否可选** | **描述**    |
| ------- | ------------- | -------- | --------- |
| header  | HeaderObject  | 否        | 请求头的结构信息  |
| payload | PayloadObject | 否        | 请求负载的结构信息 |

HeaderObject

| **属性**      | **类型** | **是否可选** | **描述**                                                            |
| ----------- | ------ | -------- | ----------------------------------------------------------------- |
| name        | string | 否        | 响应头名称。可选参数：UpdateDeviceStatesResponse：更新设备状态响应 ErrorResponse：错误响应 |
| message\_id | string | 否        | 响应头消息 ID，UUID\_V4。这里传入请求消息 header.message\_id                     |
| version     | string | 否        | 请求协议版本号。目前固定为 1。                                                  |

> 成功响应--PayloadObject：

根据请求类型，响应结构不同。详见具体请求说明文档。

> 失败响应--PayloadObject：

| **属性** | **类型** | **是否可选** | **描述**    |
| ------ | ------ | -------- | --------- |
| type   | string | 否        | **错误类型**: |

* **ENDPOINT\_UNREACHABLE**：设备不可达或离线
* **ENDPOINT\_LOW\_POWER**：设备处于低电量模式，无法被控制
* **INVALID\_DIRECTIVE**：来自网关的指令异常
* **NO\_SUCH\_ENDPOINT**：设备不存在
* **NOT\_SUPPORTED\_IN\_CURRENT\_MODE**：当前模式不支持该操作
* **INTERNAL\_ERROR**：内部服务错误
* **REMOTE\_KEY\_CODE\_NOT\_LEARNED**：遥控器按键码未学习 |

:::提示 **条件**：请求参数合法。\*\*状态码：\*\*200 OK **响应参数：** :::

```
{
  "event": {
    "header": {
      "name": "UpdateDeviceStatesResponse",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "1"
    },
    "payload": {}
  }
}
```

```
{
  "event": {
    "header": {
      "name": "ErrorResponse",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "1"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE"
    }
  }
}
```

**UpdateDeviceStates**

**请求参数：** PayloadObject：

| **属性** | **类型** | **是否可选** | **描述**            |
| ------ | ------ | -------- | ----------------- |
| state  | object | 否        | 设备状态，详见【支持的设备能力】。 |

请求示例：

```
{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": : {
         "power": {
           "powerState": "on"
         }
       }
    }
  }
}
```

**响应参数：** PayloadObject：空对象 成功响应示例

```
{
  "header": {
    "name": "Response",
    "message_id": "唯一标识，建议使用版本 4 的 UUID",
    "version": "1"
  },
  "payload": {}
}
```

**QueryDeviceStates**

**请求参数：** PayloadObject：

| **属性** | **类型** | **是否可选** | **描述**            |
| ------ | ------ | -------- | ----------------- |
| state  | object | 否        | 设备状态，详见【支持的设备能力】。 |

请求示例：

```json
{
  "directive": {
    "header": {
      "name": "QueryDeviceStates",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
      "state": {
        "power-consumption": {
          "timeRange": {
            "start": "2020-07-05T08:00:00Z", // 用电量统计的开始时间，必填。
            "end": "2020-07-05T09:00:00Z"   // 用电量统计的结束时间，必填。
          }
        }
      }
    }
  }
}
```

**响应参数：** PayloadObject：

| **属性** | **类型** | **是否可选** | **描述**            |
| ------ | ------ | -------- | ----------------- |
| state  | object | 否        | 设备状态，详见【支持的设备能力】。 |

**响应示例：**

```json
{
  "event": {
    "header": {
      "name": "Response",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "2"
    },
    "payload": {
      "state": {
        "power-consumption": {
          "electricityIntervals": [ // 根据配置的 resolution 分割成多条记录
            {
              "usage": 26.5, // 用电量值，必填。类型：number。
              "start": "2020-07-05T08:00:00Z", // 开始时间，必填。类型：date。
              "end": "2020-07-05T09:00:00Z"    // 结束时间，必填。类型：date。如果 end 与 start 之间的间隔小于 resolution，则所有上报记录均视为无效。
            },
            {
              "usage": 26.5, // 用电量值，必填。类型：number。
              "start": "2020-07-05T09:00:00Z", // 开始时间，必填。类型：date。
              "end": "2020-07-05T10:00:00Z"    // 结束时间，必填。类型：date。如果 end 与 start 之间的间隔小于 resolution，则所有上报记录均视为无效。
            }
          ]
        }
      }
    }
  }
}
```

**ConfigureDeviceCapabilities**

**请求参数：** PayloadObject：

| **属性**       | **类型**              | **是否可选** | **描述**                                               |
| ------------ | ------------------- | -------- | ---------------------------------------------------- |
| capabilities | CapabilityObject\[] | 否        | 能力列表。详情可见支持的设备能力部分。注意，permission 字段不可更改，同步时传入相同的值即可。 |

请求示例：

```json
{
  "directive": {
    "header": {
      "name": "ConfigureDeviceCapabilities",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
      "capabilities": [
        {
          "capability": "thermostat-mode-detect",
          "permission": "0110",
          "name": "temperature", // 温控检测类型，必填。可选值：humidity（湿度检测）、temperature（温度检测）
          "settings": {
            "setpointRange": {
              "permission": "11",
              "type": "object",
              "value": {
                "supported": [ // 支持的检测设置，必填。
                  {
                    "name": "lowerSetpoint", // 检测应维持的最小值。lowerSetpoint 或 upperSetpoint 必须提供其一。
                    "value": { // 检测范围，可选。如有预设条件则填写。
                      "value": 68.0, // 温度或湿度值，必填。
                      "scale": "f" // 温度单位，当 name=temperature 时必填。选项：c（摄氏度）、f（华氏度）
                    }
                  },
                  {
                    "name": "upperSetpoint", // 检测应维持的最大值。lowerSetpoint 或 upperSetpoint 必须提供其一。
                    "value": { // 检测范围，可选。如有预设条件则填写。
                      "value": 68.0, // 温度或湿度值，必填。
                      "scale": "f" // 温度单位，当 name=temperature 时必填。选项：c（摄氏度）、f（华氏度）
                    }
                  }
                ]
              }
            },
            "supportedModes": {
              "type": "enum",
              "permission": "01",
              "values": [
                "COMFORT",
                "COLD",
                "HOT"
              ]
            }
          }
        }
      ]
    }
  }
}
```

**响应参数：** PayloadObject：空对象 成功响应示例

```json
{
  "event": {
    "header": {
      "name": "Response",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "2"
    },
    "payload": {}
  }
}
```

## 5. 服务端事件（SSE）

> MDN EventSource 接口说明：<https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events>

### 5.1 指令

网关支持使用 SSE（Server-sent events）向客户端推送消息。客户端在获取访问凭证后可以监听 SSE 消息，并在接收到网关推送的消息后按照开放接口事件通知协议解析推送内容。需注意网关目前使用 HTTP1.1 协议，因此浏览器端 SSE 连接存在最多不超过 6 个连接的限制（具体说明见 MDN EventSource 接口文档）。

### 5.2 通用格式

:::提示

* **URL**：/open-api/V2/sse/bridge
* **方法**：`GET` ::: 请求参数：

| 名称            | 类型     | 是否可选 | 描述   |
| ------------- | ------ | ---- | ---- |
| access\_token | string | 否    | 访问令牌 |

注意：请求 SSE 连接时，网关会校验 access\_token，如果无效将返回认证失败错误。{ "error": 401, "data": {}, "message": "invalid access\_token"}

> 例如：模块名称：device 版本：1,v2,v3 消息类型：addDevice

示例：

```javascript
const evtSource = new EventSource("http://<域名或 IP 地址>/open-api/v2/sse/bridge?access_token=xxxxxx");

evtSource.addEventListener('device#v2#addDevice',function (event) {
  try {
    const data = JSON.parse(event.data);
    console.log('data', data);
  } catch (error) {
    console.error(`parse error`,error);
  }
}
```

### 5.3 设备模块

#### a. 添加设备事件

:::tips 模块名称：device 版本：v2 消息类型：addDevice event.data 参数： :::

| 名称      | 类型                                       | 是否可选 | 描述   |
| ------- | ---------------------------------------- | ---- | ---- |
| payload | ResponseDeviceObjectObject - 与获取设备列表接口相同 | 否    | 设备信息 |

示例：

```json
// event.data
{
  "payload": {
    "serial_number": "ABCDEFGHIJK",
    "third_serial_number": "third_serial_number",
    "name": "我的设备",
    "manufacturer": "SONOFF",
    "model": "BASICZBR3",
    "firmware_version": "1.1.0",
    "display_category": "switch",
    "capabilities": [
      {
        "capability": "power",
        "permission": "1100"
      },
      {
        "capability": "rssi",
        "permission": "0100"
      }
    ],
    "protocal": "zigbee",
    "state": {
      "power": {
        "powerState": "on"
      }
    },
    "tags": {
      "key": "value"
    },
    "online": true
  }
}
```

#### b. 更新设备状态事件

:::tips 模块名称：device 版本：v2 消息类型：updateDeviceState event.data 参数： :::

| 名称       | 类型             | 是否可选 | 描述     |
| -------- | -------------- | ---- | ------ |
| endpoint | EndpointObject | 否    | 设备信息   |
| payload  | 对象。结构与设备状态相同   | 否    | 设备状态数据 |

EndpointObject：

| 参数                    | 类型     | 是否可选 | 描述                                |
| --------------------- | ------ | ---- | --------------------------------- |
| serial\_number        | string | 否    | 设备唯一序列号                           |
| third\_serial\_number | string | Y    | 第三方设备的唯一序列号。对于通过开放接口接入的设备，此字段为必填。 |

示例：

```json
// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "power": {
      "powerState": "on"
    },
    "brightness": {
      "brightness": 100
    }
  }
}
```

#### c. 更新设备信息事件

:::tips 模块名称：device 版本：v2 消息类型：updateDeviceInfo event.data 参数： :::

| 名称       | 类型                 | 是否可选 | 描述     |
| -------- | ------------------ | ---- | ------ |
| endpoint | EndpointObject     | 否    | 设备信息   |
| payload  | DeviceChangeObject | 否    | 设备变更数据 |

EndpointObject：

| 属性                    | 类型     | 是否可选 | 描述                                |
| --------------------- | ------ | ---- | --------------------------------- |
| serial\_number        | string | 否    | 设备唯一序列号                           |
| third\_serial\_number | string | Y    | 第三方设备的唯一序列号。对于通过开放接口接入的设备，此字段为必填。 |

DeviceChangeObject

| 名称           | 类型                   | 是否可选 | 描述                                              |
| ------------ | -------------------- | ---- | ----------------------------------------------- |
| name         | string               | 否    | 设备名称                                            |
| capabilities | CapabilityObject \[] | Y    | 设备能力列表。                                         |
| 标签           | object               | Y    | **标签**`object` \| 可为空 \| 用于自定义设备信息的 JSON 格式键值对。 |

* 可用于存储设备通道。
* 可用于存储温度单位。
* 用于其他第三方自定义数据。 |

示例：

```json
// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "name": "device name",
    "capabilities": [
      {
        "capability": "thermostat-mode-detect",
        "permission": "0110",
        "name": "temperature", // 温控检测类型，必填。可选值：humidity（湿度检测）、temperature（温度检测）
        "settings": {
          "setpointRange": {
            "permission": "11",
            "type": "object",
            "value": {
              "supported": [ // 支持的检测设置，必填。
                {
                  "name": "lowerSetpoint", // 检测应维持的最小值。lowerSetpoint 或 upperSetpoint 必须提供其一。
                  "value": { // 检测范围，可选。如有预设条件则填写。
                    "value": 68.0, // 温度或湿度值，必填。
                    "scale": "f" // 温度单位，当 name=temperature 时必填。选项：c（摄氏度）、f（华氏度）
                  }
                },
                {
                  "name": "upperSetpoint", // 检测应维持的最大值。lowerSetpoint 或 upperSetpoint 必须提供其一。
                  "value": { // 检测范围，可选。如有预设条件则填写。
                    "value": 68.0, // 温度或湿度值，必填。
                    "scale": "f" // 温度单位，当 name=temperature 时必填。选项：c（摄氏度）、f（华氏度）
                  }
                }
              ]
            }
          },
          "supportedModes": {
            "type": "enum",
            "permission": "01",
            "values": [
              "COMFORT",
              "COLD",
              "HOT"
            ]
          }
        }
      }
    ]
  }
}
```

#### d. 删除设备事件

:::tips 模块名称：device 版本：v2 消息类型：deleteDevice event.data 参数： :::

| \*\* 名称 \*\* | \*\* 类型 \*\*   | \*\* 可选\*\* | \*\* 描述 \*\* |
| ------------ | -------------- | ----------- | ------------ |
| endpoint     | EndpointObject | 否           | 设备信息         |

EndpointObject：

| 属性                    | 类型     | 是否可选 | 描述                                |
| --------------------- | ------ | ---- | --------------------------------- |
| serial\_number        | string | 否    | 设备唯一序列号                           |
| third\_serial\_number | string | Y    | 第三方设备的唯一序列号。对于通过开放接口接入的设备，此字段为必填。 |

示例：

```json
// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  }
}
```

#### e. 更新设备在线事件

:::tips 模块名称：device 版本：v2 消息类型：updateDeviceOnline event.data 参数： :::

| 名称       | 类型                 | 是否可选 | 描述     |
| -------- | ------------------ | ---- | ------ |
| endpoint | EndpointObject     | 否    | 设备信息   |
| payload  | DeviceChangeObject | 否    | 设备变更数据 |

EndpointObject：

| 属性                    | 类型     | 是否可选 | 描述                                |
| --------------------- | ------ | ---- | --------------------------------- |
| serial\_number        | string | 否    | 设备唯一序列号                           |
| third\_serial\_number | string | Y    | 第三方设备的唯一序列号。对于通过开放接口接入的设备，此字段为必填。 |

DeviceChangeObject

| 名称 | 类型      | 是否可选 | 描述     |
| -- | ------- | ---- | ------ |
| 在线 | boolean | 否    | 设备在线状态 |

示例：

```json
// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "online": false
  }
}
```

### 5.4 网关模块

#### a. 安防状态更新事件

:::tips 模块名称：device 版本：v2 消息类型：updateDeviceOnline event.data 参数： :::

| **属性**  | **类型**              | **是否可选** | **描述** |
| ------- | ------------------- | -------- | ------ |
| payload | SecurityStateObject | 否        | 设备信息   |

SecurityStateObject

| **属性**       | **类型** | **是否可选** | **描述** |
| ------------ | ------ | -------- | ------ |
| alarm\_state | string | 否        |        |

* `arming` | 已布防
* `disarming` | 已撤防 |

示例：

```json
// event.data
{
  "payload": {
    "alarm_state": "alarming"
  }
}
```

### 5.5 安防模块

#### a. 布防状态更新事件

:::tips 模块名称：device 版本：v2 消息类型：updateDeviceOnline event.data 参数： :::

| **属性**  | **类型**         | **是否可选** | **描述**  |
| ------- | -------------- | -------- | ------- |
| payload | ArmStateObject | 否        | 布防与撤防信息 |

ArmStateObject：

| **属性**     | **类型** | **是否可选** | **描述** |
| ---------- | ------ | -------- | ------ |
| arm\_state | string | 否        |        |

* `arming` | 已布防
* `disarming` | 已撤防 | | detail | DetailObject | N | 布防/撤防详情 |

DetailObject：

| **属性** | **类型** | **是否可选** | **描述**  |
| ------ | ------ | -------- | ------- |
| sid    | int    | 否        | 安防模式 id |
| name   | string | 否        | 安防名称    |

示例

```json
// event.data
{
  "payload": {
    "arm_state": "arming",
    "detail": {
      "sid": 1,
      "name": "Home Mode"
    }
  }
}
```

## 6. TTS (**文本转语音) 引擎功能**

### 6.1 说明

#### 关键角色

* TTS 服务提供商：TTS 服务引擎提供商负责在网关上注册 TTS 引擎并提供 TTS 服务
* 网关服务器：iHost
* 网关开放 API 客户端

#### 6.1.1 注册 TTS 引擎服务

1. 【TTS 服务提供商】调用接口在网关上注册 TTS 引擎。
2. 【网关服务器】注册成功后，网关将存储 TTS 引擎的基本信息（包括服务地址 server\_address，后续网关与 TTS 服务提供商之间的通信将通过该 server\_address 地址进行），并在网关内部分配 TTS 引擎服务 ID。

<figure><img src="https://2213833752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FFbcZQSx9tkiFsPhFd5Bs%2Fimage.png?alt=media&#x26;token=503d3700-3236-4a96-86c4-42f59aa5ebc8" alt=""><figcaption></figcaption></figure>

#### 6.1.2 获取合成音频列表

1. 【网关开放 API 客户端】调用接口获取已注册 TTS 引擎服务的列表。可以获取当前已注册的 TTS 引擎列表（包括网关分配的 TTS 引擎 ID）。
2. 【网关开放 API 客户端】调用接口获取指定 TTS 引擎的音频列表。网关将向指定的 TTS 服务提供商下发同步的音频列表指令并返回结果。

<figure><img src="https://2213833752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2Fdc7XkFrVPJSM4qelABE0%2Fimage.png?alt=media&#x26;token=58f3edf7-29bf-4709-888a-4bd52e908e0f" alt=""><figcaption></figcaption></figure>

#### 6.1.3 指定语音引擎进行语音合成

1. 【网关开放 API 客户端】调用接口获取已注册 TTS 引擎服务的列表。可以获取当前已注册的 TTS 引擎列表（包括网关分配的 TTS 引擎 ID）。
2. 【网关开放 API 客户端】调用接口获取指定 TTS 引擎的音频列表。网关将向指定的 TTS 服务提供商下发同步的音频列表指令并返回结果。

<figure><img src="https://2213833752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FUj8BveNMWDcBvMj8pcW1%2Fimage.png?alt=media&#x26;token=6ba23a8d-1bc6-4c72-8267-d359fcff6678" alt=""><figcaption></figcaption></figure>

#### 6.1.4 合成音频并播放 TTS 语音。

1. 【网关开放 API 客户端】调用接口获取已注册 TTS 引擎服务的列表。可以获取当前已注册的 TTS 引擎列表（包括网关分配的 TTS 引擎 ID）。
2. 【网关开放 API 客户端】调用接口获取指定 TTS 引擎的音频列表。网关将向指定的 TTS 服务提供商下发同步的音频列表指令并返回结果。（包括 TTS 音频文件地址）
3. 【网关开放 API 客户端】从上一步返回的结果中记录 TTS 音频文件地址，调用播放音频文件接口，并通过网关进行播放。

### 6.2 TTS 引擎模块

#### 6.2.1 网关开放能力

**a. 获取已注册 TTS 引擎服务列表**

:::提示

* **URL**：`/open-api/V2/rest/tts/engines`
* **方法**：`GET`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数: 无 正确数据响应:

| **属性**  | **类型**           | **是否可选** | **描述**       |
| ------- | ---------------- | -------- | ------------ |
| engines | EngineObject \[] | 否        | 已注册 TTS 引擎列表 |

EngineObject 结构

| **属性** | **类型** | **是否可选** | **描述**     |
| ------ | ------ | -------- | ---------- |
| id     | string | 否        | 网关分配的引擎 ID |
| name   | string | 否        | TTS 引擎服务名称 |

::: 提示 条件：请求参数合法，且通过用户身份验证。\*\*状态码：\*\*`200 OK` **响应示例：**： :::

```json
{
  "error": 0,
  "data": {
    "engines": [
      {
        "id": "engine id",
        "name": "engine name"
      }
    ]
  },
  "message": "success"
}
```

**b. 获取指定 TTS 引擎的音频列表**

:::提示

* **URL**：`/open-api/V2/rest/tts/engine/{id}/audio-list`
* **方法**：`GET`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数: 无 正确数据响应:

| **属性**      | **类型**          | **是否可选** | **描述** |
| ----------- | --------------- | -------- | ------ |
| audio\_list | AudioObject \[] | 否        | 音频列表   |

AudioObject 结构

| **属性**                                                   | **类型** | **是否可选** | **描述**       |
| -------------------------------------------------------- | ------ | -------- | ------------ |
| url                                                      | string | 否        | 音频文件 URL，例如： |
| <https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3> |        |          |              |
| label                                                    | string | Y        | 音频文件标签       |

::: 提示 条件：请求参数合法，且通过用户身份验证。\*\*状态码：\*\*`200 OK` \*\*错误码：\*\*

* 190000 引擎运行异常

**响应示例：**： :::

```json
{
  "error": 0,
  "data": {
    "audio_list": [
      {
        "url": "tts audio address", // 例如: https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
        "label": "tts audio label"
      }
    ]
  },
  "message": "success"
}
```

**c. 使用指定 TTS 引擎进行语音合成**

:::提示

* **URL**：`/open-api/V2/rest/tts/engine/{id}/synthesize`
* **方法**：`POST`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数:

| **属性**   | **类型** | **是否可选** | **描述**                                                                                                       |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| text     | string | 否        | 用于合成音频的文本                                                                                                    |
| label    | string | Y        | 音频文件标签                                                                                                       |
| language | string | Y        | 透明字段。合成语音请求的可选语言代码。具体支持的语言代码列表由 TTS 语音引擎服务提供商提供。注意 TTS 引擎服务需要支持默认语言进行语音合成，这意味着如果未传入 language，则使用引擎的默认语言进行合成。 |
| options  | object | Y        | 透明字段。用于向 TTS 语音引擎服务传递合成所需的配置参数。                                                                              |

正确数据响应:

| **属性** | **类型**      | **是否可选** | **描述** |
| ------ | ----------- | -------- | ------ |
| audio  | AudioObject | 否        | 音频列表   |

AudioObject 结构

| **属性**                                                   | **类型** | **是否可选** | **描述**       |
| -------------------------------------------------------- | ------ | -------- | ------------ |
| url                                                      | string | 否        | 音频文件 URL，例如： |
| <https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3> |        |          |              |
| label                                                    | string | Y        | 音频文件标签       |

::: 提示 条件：请求参数合法，且通过用户身份验证。\*\*状态码：\*\*`200 OK` \*\*错误码：\*\*

* 190000 引擎运行异常

**响应示例：**： :::

```json
{
  "error": 0,
  "data": {
    "audio": {
        "url": "tts audio address" // 例如, https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
        "label": "tts audio label"
    }
  },
  "message": "success"
}
```

#### 6.2.2 网关与 TTS 服务之间的通信

**a. 注册 TTS 引擎服务**

> 由 TTS 服务提供商向网关发送请求

:::提示

* **URL**：`/open-api/V2/rest/thirdparty/event`
* **方法**：`POST`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数:

| **属性** | **类型**      | **是否可选** | **描述**     |
| ------ | ----------- | -------- | ---------- |
| event  | EventObject | 否        | 请求事件对象结构信息 |

EventObject

| **属性**  | **类型**        | **是否可选** | **描述**    |
| ------- | ------------- | -------- | --------- |
| header  | HeaderObject  | 否        | 请求头的结构信息  |
| payload | PayloadObject | 否        | 请求负载的结构信息 |

HeaderObject

| **属性** | **类型** | **是否可选** | **描述**     |
| ------ | ------ | -------- | ---------- |
| name   | string | 否        | 请求名称。可选参数。 |

* RegisterTTSEngine | | message\_id | string | N | 请求消息 ID，UUID\_V4 | | version | string | N | 请求协议版本号。目前固定为 1 |

PayloadObject

| **属性**           | **类型** | **是否可选** | **描述**            |
| ---------------- | ------ | -------- | ----------------- |
| service\_address | string | 否        | 服务地址。例如，http\:/// |
| name             | string | 否        | 服务名称              |

请求示例：

```json
{
  "event": {
    "header": {
      "name": "RegisterTTSEngine",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "1"
    },
    "payload": {
        "service_address": "service_address",
        "name": "tts service name"
    }
  }
}
```

\*\*正确响应参数：\*\*

| **属性**  | **类型**        | **是否可选** | **描述**    |
| ------- | ------------- | -------- | --------- |
| header  | HeaderObject  | 否        | 请求头的结构信息  |
| payload | PayloadObject | 否        | 请求负载的结构信息 |

HeaderObject

| **属性** | **类型** | **是否可选** | **描述**      |
| ------ | ------ | -------- | ----------- |
| name   | string | 否        | 响应头名称。可选参数： |

* 响应（成功响应）
* ErrorResponse（错误响应） | | message\_id | string | N | 响应头消息 ID，UUID\_V4。此处为入参请求消息：header.message\_id | | version | string | N | 请求协议版本号。目前固定为 1 |

PayloadObject

| **属性**     | **类型** | **是否可选** | **描述**     |
| ---------- | ------ | -------- | ---------- |
| engine\_id | string | 否        | 网关分配的引擎 ID |

::: 提示 条件：请求参数合法，且通过用户身份验证。\*\*状态码：\*\*`200 OK` **响应示例：**： ::: 正确响应示例：：

```json
{
    "header": {
      "name": "Response",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "1"
    },
    "payload": {
      "engine_id": "engine id"
    }
  }
```

\*\*异常响应参数：\*\*

| **属性** | **类型** | **是否可选** | **描述** |
| ------ | ------ | -------- | ------ |
| type   | string | 否        | 错误类型   |

* INVALID\_PARAMETERS（参数错误）
* AUTH\_FAILURE（认证失败）
* INTERNAL\_ERROR（服务内部错误） | | description | string | N | 错误描述 |

错误响应示例：：

```json
{
  "header": {
    "name": "ErrorResponse",
    "message_id": "唯一标识，建议使用版本 4 的 UUID",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address cannot be empty" 
  }
}
```

**b. 同步音频列表指令**

> 由网关向 TTS 服务提供商发送指令。

:::提示

* **URL**：`<service address>`
* **方法**：`POST`
* **头部**：
  * Content-Type: application/json ::: 请求参数：

| **属性**    | **类型**          | **是否可选** | **描述**   |
| --------- | --------------- | -------- | -------- |
| directive | DirectiveObject | 否        | 指令对象结构信息 |

DirectiveObject

| **属性**  | **类型**        | **是否可选** | **描述**    |
| ------- | ------------- | -------- | --------- |
| header  | HeaderObject  | 否        | 请求头的结构信息  |
| payload | PayloadObject | 否        | 请求负载的结构信息 |

HeaderObject

| **属性** | **类型** | **是否可选** | **描述**     |
| ------ | ------ | -------- | ---------- |
| name   | string | 否        | 请求名称。可选参数： |

* SyncTTSAudioList | | message\_id | string | N | 请求消息 ID，UUID\_V4 | | version | string | N | 请求协议版本号。目前固定为 1 |

请求示例：

```json
{
  "directive": {
    "header": {
      "name": "SyncTTSAudioList",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "1"
    },
    "payload": {}
  }
}
```

\*\*正确响应参数：\*\*

| **属性**  | **类型**        | **是否可选** | **描述**    |
| ------- | ------------- | -------- | --------- |
| header  | HeaderObject  | 否        | 请求头的结构信息  |
| payload | PayloadObject | 否        | 请求负载的结构信息 |

HeaderObject

| **属性** | **类型** | **是否可选** | **描述**      |
| ------ | ------ | -------- | ----------- |
| name   | string | 否        | 响应头名称。可选参数： |

* 响应（成功响应）
* ErrorResponse（错误响应） | | message\_id | string | N | 响应头消息 ID，UUID\_V4。此处为入参请求消息：header.message\_id | | version | string | N | 请求协议版本号。目前固定为 1 |

PayloadObject:

| **属性**      | **类型**          | **是否可选** | **描述**   |
| ----------- | --------------- | -------- | -------- |
| audio\_list | AudioObject \[] | 否        | TTS 音频列表 |

AudioObject 结构

| **属性**                                                   | **类型** | **是否可选** | **描述**       |
| -------------------------------------------------------- | ------ | -------- | ------------ |
| url                                                      | string | 否        | 音频文件 URL，例如： |
| <https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3> |        |          |              |
| label                                                    | string | Y        | 音频文件标签       |

::: 提示 条件：请求参数合法，且通过用户身份验证。\*\*状态码：\*\*`200 OK` **响应示例：**： ::: 正确响应示例：：

```json
{
    "header": {
      "name": "Response",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "1"
    },
    "payload": {
      "audio_list": [
        {
            "url": "tts audio url",
            "label": "tts audio label"
        }
      ]
    }
}
```

\*\*异常响应参数：\*\*

| **属性** | **类型** | **是否可选** | **描述** |
| ------ | ------ | -------- | ------ |
| type   | string | 否        | 错误类型   |

* INVALID\_PARAMETERS（参数错误）
* AUTH\_FAILURE（认证失败）
* INTERNAL\_ERROR（服务内部错误） | | description | string | N | 错误描述 |

错误响应示例：：

```json
{
  "header": {
    "name": "ErrorResponse",
    "message_id": "唯一标识，建议使用版本 4 的 UUID",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address cannot be empty" 
  }
}
```

**c. 语音合成指令**

> 由网关向 TTS 服务提供商发送指令。

:::提示

* **URL**：`<service address>`
* **方法**：`POST`
* **头部**：
  * Content-Type: application/json ::: 请求参数：

| **属性**    | **类型**          | **是否可选** | **描述**   |
| --------- | --------------- | -------- | -------- |
| directive | DirectiveObject | 否        | 指令对象结构信息 |

DirectiveObject

| **属性**  | **类型**        | **是否可选** | **描述**    |
| ------- | ------------- | -------- | --------- |
| header  | HeaderObject  | 否        | 请求头的结构信息  |
| payload | PayloadObject | 否        | 请求负载的结构信息 |

HeaderObject

| **属性** | **类型** | **是否可选** | **描述**     |
| ------ | ------ | -------- | ---------- |
| name   | string | 否        | 请求名称。可选参数： |

* SynthesizeSpeech | | message\_id | string | N | 请求消息 ID：UUID\_V4 | | version | string | N | 请求协议版本号。目前固定为 1 |

PayloadObject

| **属性**   | **类型** | **是否可选** | **描述**                                                                                                       |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| text     | string | 否        | 用于合成音频的文本                                                                                                    |
| label    | string | Y        | 音频文件标签                                                                                                       |
| language | string | Y        | 透明字段。合成语音请求的可选语言代码。具体支持的语言代码列表由 TTS 语音引擎服务提供商提供。注意 TTS 引擎服务需要支持默认语言进行语音合成，这意味着如果未传入 language，则使用引擎的默认语言进行合成。 |
| options  | object | Y        | 透明字段。用于向 TTS 语音引擎服务传递合成所需的配置参数。                                                                              |

请求示例：

```json
{
    "directive": {
        "header": {
            "name": "SynthesizeSpeech",
            "message_id": "唯一标识，建议使用版本 4 的 UUID",
            "version": "1"
        },
        "payload": {
            "text": "Input text to synthesize.",
            "label": "tts audio label"
        }
    }
}
```

\*\*正确响应参数：\*\*

| **属性**  | **类型**        | **是否可选** | **描述**    |
| ------- | ------------- | -------- | --------- |
| header  | HeaderObject  | 否        | 请求头的结构信息  |
| payload | PayloadObject | 否        | 请求负载的结构信息 |

HeaderObject

| **属性** | **类型** | **是否可选** | **描述**      |
| ------ | ------ | -------- | ----------- |
| name   | string | 否        | 响应头名称。可选参数： |

* 响应（成功响应）
* ErrorResponse（错误响应） | | message\_id | string | N | 响应头消息 ID，UUID\_V4。此处为入参请求消息：header.message\_id | | version | string | N | 请求协议版本号。目前固定为 1 |

PayloadObject

| **属性** | **类型**      | **是否可选** | **描述** |
| ------ | ----------- | -------- | ------ |
| audio  | AudioObject | 否        | TTS 音频 |

AudioObject 结构

| **属性**                                                   | **类型** | **是否可选** | **描述**       |
| -------------------------------------------------------- | ------ | -------- | ------------ |
| url                                                      | string | 否        | 音频文件 URL，例如： |
| <https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3> |        |          |              |
| label                                                    | string | Y        | 音频文件标签       |

::: 提示 条件：请求参数合法，且通过用户身份验证。\*\*状态码：\*\*`200 OK` **响应示例：**： ::: 正确响应示例：：

```json
{
    "header": {
      "name": "Response",
      "message_id": "唯一标识，建议使用版本 4 的 UUID",
      "version": "1"
    },
    "payload": {
      "audio": {
        "url": "tts audio url",
        "label": "tts audio label"
      }
    }
}
```

\*\*异常响应参数：\*\*

| **属性** | **类型** | **是否可选** | **描述** |
| ------ | ------ | -------- | ------ |
| type   | string | 否        | 错误类型   |

* INVALID\_PARAMETERS（参数错误）
* AUTH\_FAILURE（认证失败）
* INTERNAL\_ERROR（服务内部错误） | | description | string | N | 错误描述 |

错误响应示例：：

```json
{
  "header": {
    "name": "ErrorResponse",
    "message_id": "唯一标识，建议使用版本 4 的 UUID",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address cannot be empty" 
  }
}
```

## 7. 多媒体模块

### 7.1 播放音频文件

:::提示

* **URL**：`/open-api/V2/rest/media/audio-player`
* **方法**：`POST`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数:

| **属性**     | **类型** | **是否可选** | **描述**    |
| ---------- | ------ | -------- | --------- |
| audio\_url | string | 否        | 音频 URL 地址 |

正确数据响应: ::: 提示 条件：请求参数合法，且通过用户身份验证。\*\*状态码：\*\*`200 OK` **响应示例：**： :::

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

## 8. 自定义 UI 卡片

自定义 UI 卡片允许您在卡片内显示任意您想要的内容。该内容可以是网页、图片或任何具有 UI 的服务。您只需提供希望显示内容的 URL。UI 卡片将自动适应其宽度和高度，内容将通过 iFrame 渲染。

### 8.1 说明

#### 关键角色

* **UI 服务提供商**：负责在网关上创建自定义 UI 卡片的提供方。
* **网关服务器**：网关服务器（iHost）。
* **网关开放 API 客户端**：网关的开放 API 客户端。

#### 8.1.1 创建自定义 UI 卡片

* **\[UI 服务提供商]**：调用 API 在网关上创建自定义 UI 卡片。
* **\[网关服务器]**：注册成功后，网关会存储 UI 卡片的基本信息（包括尺寸配置和卡片资源 URL）并在网关内部分配 UI 卡片 ID。

<figure><img src="https://2213833752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FBt2FrX78UIyKBkwhUqm8%2Fimage.png?alt=media&#x26;token=cc5844e7-662b-45cf-912a-de419ac13efe" alt=""><figcaption></figcaption></figure>

#### 8.1.2 获取 UI 卡片列表

* **\[UI 服务提供商]**：调用 API 获取 UI 卡片列表。
* **\[网关服务器]**：返回存储在网关上的 UI 卡片列表，包括调用方未创建的自定义 UI 卡片。

<figure><img src="https://2213833752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2F7a1myMdJ8j33N03L4KBi%2Fimage.png?alt=media&#x26;token=9c7c1ba3-8d28-43f3-a145-05eaeb762691" alt=""><figcaption></figcaption></figure>

#### 8.1.3 修改指定 UI 卡片的配置

* **\[UI 服务提供商]**：调用 API 修改指定 UI 卡片的配置，例如尺寸配置和资源 URL。
* **\[网关服务器]**：修改成功后，网关会存储更新后的 UI 卡片信息，包括新的尺寸配置和资源 URL。

<figure><img src="https://2213833752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FSub47oZd5irq2dDhLhrf%2Fimage.png?alt=media&#x26;token=c9080c5e-1b49-4b00-ab31-bf2337b49d35" alt=""><figcaption></figcaption></figure>

#### 8.1.4 删除自定义 UI 卡片

1. **\[UI 服务提供商]**：调用 API 删除指定的自定义 UI 卡片。
2. **\[网关服务器]**：网关将移除与指定 UI 卡片相关的所有信息。

<figure><img src="https://2213833752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FNAX4WVWWxGUwzz33BzHq%2Fimage.png?alt=media&#x26;token=05cacc3e-be1b-44c9-a009-ab83d860bcce" alt=""><figcaption></figcaption></figure>

### 8.2 自定义 UI 卡片模块

#### 8.2.1 创建自定义 UI 卡片

> UI 服务提供商向网关发送请求以创建自定义 UI 卡片。

:::提示

* **URL**：`/open-api/v2/rest/ui/cards`
* **方法**：`POST`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数:

| **属性**         | **类型**             | **是否可选** | **描述**                |
| -------------- | ------------------ | -------- | --------------------- |
| label          | string             | Y        | 卡片标签：用于描述该卡片。它是卡片的别名。 |
| cast\_settings | CastSettingsObject | Y        | 投屏卡片设置：投屏卡片的配置设置。     |
| web\_settings  | WebSettingsObject  | 否        | 网页卡片设置：网页卡片的配置设置。     |

CastSettingsObject:

| **属性**     | **类型**              | **是否可选** | **描述**                 |
| ---------- | ------------------- | -------- | ---------------------- |
| dimensions | DimensionObject \[] | 否        | 尺寸配置：必须至少包含一个配置。       |
| default    | string              | 否        | 默认规格：使用默认尺寸规格，可选参数：2x2 |

WebSettingsObject:

| **属性**            | **类型**              | **是否可选** | **描述**           |
| ----------------- | ------------------- | -------- | ---------------- |
| dimensions        | DimensionObject \[] | 否        | 尺寸配置：必须至少包含一个配置。 |
| drawer\_component | DrawerObject        | Y        | 抽屉组件显示设置。        |
| default           | string              | 否        | 默认规格：            |

* 1x1
* 2x1 |

DimensionObject:

| **属性**                   | **类型** | **是否可选** | **描述**                           |
| ------------------------ | ------ | -------- | -------------------------------- |
| src                      | string | 否        | 资源 URL：例如： <http://example.html> |
| size                     | string | 否        | 尺寸规格：                            |
| CastSettingsObject 可选参数： |        |          |                                  |

* 2×2

WebSettingsObject 可选参数：

* 1x1
* 2x1 |

DrawerObject:

| **属性** | **类型** | **是否可选** | **描述**                           |
| ------ | ------ | -------- | -------------------------------- |
| src    | string | 否        | 资源 URL：例如： <http://example.html> |

成功的数据响应：

| **属性** | **类型** | **是否可选** | **描述**     |
| ------ | ------ | -------- | ---------- |
| id     | string | 否        | UI 卡片唯一 ID |

:::提示 **条件**：请求参数合法且用户身份验证通过。\*\*状态代码：\*\* `200 OK` ::: 请求示例：

```json
{
  "label": "ewelink cube card",
  "cast_settings": {
    "dimensions": [
      {
        "src": "https://ewelink.cc/ewelink-cube/",
        "size": "2×2"
      }
    ],
    "default": "2×2"
  },
  "web_settings": {
    "dimensions": [
      {
        "src": "https://ewelink.cc/ewelink-cube/",
        "size": "2×1"
      },
      {
        "src": "https://ewelink.cc/ewelink-cube/",
        "size": "1×1"
      }
    ],
    "drawer_component": {
      "src": "https://ewelink.cc/ewelink-cube/"
    },
    "default": "2×1"
  }
}
```

响应示例：

```json
{
  "error": 0,
  "data": {
    "id": "72cc5a4a-f486-4287-857f-b482d7818b16"
  },
  "message": "success"
}
```

#### 8.2.2 获取 UI 卡片列表

:::提示

* **URL**：`/open-api/v2/rest/ui/cards`
* **方法**：`GET`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数: 无 响应参数:

| **属性** | **类型**        | **是否可选** | **描述**  |
| ------ | ------------- | -------- | ------- |
| data   | CardObject\[] | 否        | UI 卡片列表 |

CardObjec 对象：

| **属性**         | **类型**             | **是否可选** | **描述**                    |
| -------------- | ------------------ | -------- | ------------------------- |
| id             | string             | 否        | 卡片 ID：卡片的唯一标识符。           |
| label          | string             | Y        | 卡片标签：用于描述该卡片。它作为卡片的别名或名称。 |
| cast\_settings | CastSettingsObject | Y        | 卡片标签：用于描述该卡片。它是卡片的别名。     |
| web\_settings  | WebSettingsObject  | 否        | 投屏卡片设置：投屏卡片的配置设置。         |
| app\_name      | string             | Y        | 网页卡片设置：网页卡片的配置设置。         |

CastSettingsObject:

| **属性**     | **类型**              | **是否可选** | **描述**           |
| ---------- | ------------------- | -------- | ---------------- |
| dimensions | DimensionObject \[] | 否        | 尺寸配置：必须至少包含一个配置。 |
| default    | string              | 否        | 默认规格：            |
| 可选参数：2x2   |                     |          |                  |
| used       | string              | 否        | 当前规格：            |
| 可选参数：2x2   |                     |          |                  |

WebSettingsObject:

| **属性**            | **类型**              | **是否可选** | **描述**           |
| ----------------- | ------------------- | -------- | ---------------- |
| dimensions        | DimensionObject \[] | 否        | 尺寸配置：必须至少包含一个配置。 |
| drawer\_component | DrawerObject        | Y        | 抽屉组件显示设置。        |
| default           | string              | 否        | 默认规格：            |
| 可选参数：             |                     |          |                  |

* 1x1
* 2x1 | | used | string | N | 当前规格： 可选参数：
* 1x1
* 2x1 |

DimensionObject:

| **属性** | **类型** | **是否可选** | **描述**                           |
| ------ | ------ | -------- | -------------------------------- |
| src    | string | 否        | 资源 URL：例如： <http://example.html> |
| size   | string | 否        | 尺寸规格：                            |
| 可选参数：  |        |          |                                  |

* 1x1
* 2x1

**注意**：当前，投屏卡片仅支持 2x2 规格。2x2 规格将不会生效。 |

DrawerObject:

| **属性** | **类型** | **是否可选** | **描述**                           |
| ------ | ------ | -------- | -------------------------------- |
| src    | string | 否        | 资源 URL：例如： <http://example.html> |

响应示例：

```json
{
  "error": 0,
  "data": [
    {
      "id": "72cc5a4a-f486-4287-857f-b482d7818b16",
      "label": "ewelink cube card",
      "cast_settings": {
        "dimensions": [
          {
            "src": "https://ewelink.cc/ewelink-cube/",
            "size": "2×2"
          }
        ],
        "default": "2×2",
        "used": "2×2"
      },
      "web_settings": {
        "dimensions": [
          {
            "src": "https://ewelink.cc/ewelink-cube/",
            "size": "2×1"
          },
          {
            "src": "https://ewelink.cc/ewelink-cube/",
            "size": "1×1"
          }
        ],
        "drawer_component": {
          "src": "https://ewelink.cc/ewelink-cube/"
        },
        "default": "2×1",
        "used": "2×1"
      },
      "appName": "ewelink-cube"
    }
  ],
  "message": "success"
}
```

#### 8.2.3 修改指定 UI 卡片的配置

> 已授权用户可通过此接口修改现有 UI 卡片的配置。自定义卡片服务提供商只能修改他们创建的 UI 卡片。

:::提示

* **URL**：`/open-api/v2/rest/ui/cards/{id}`
* **方法**：`PUT`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数:

| **属性**         | **类型**             | **是否可选** | **描述**           |
| -------------- | ------------------ | -------- | ---------------- |
| label          | string             | Y        | 用于描述该卡片。它是卡片的别名。 |
| cast\_settings | CastSettingsObject | Y        | 投屏卡片设置           |
| web\_settings  | WebSettingsObject  | Y        | 网页卡片设置           |

CastSettingsObject:

| **属性** | **类型** | **是否可选**                                  | **描述** |
| ------ | ------ | ----------------------------------------- | ------ |
| used   | string | Y，任一 `used` 或 `src` 必须提供，但至少需要提供这些参数中的一个。 | 当前规格：  |
| 可选参数：  |        |                                           |        |

* 2x2

\| | src | string | Y，任一 `used` 或 `src` 必须提供，但至少需要提供这些参数中的一个。 | 资源 URL： <http://example.html> |

WebSettingsObject:

| **属性** | **类型** | **是否可选**                                  | **描述** |
| ------ | ------ | ----------------------------------------- | ------ |
| used   | string | Y，任一 `used` 或 `src` 必须提供，但至少需要提供这些参数中的一个。 | 当前规格：  |
| 可选参数：  |        |                                           |        |

* 1x1
* 2x1 | | src | string | Y，任一 `used` 或 `src` 必须提供，但至少需要提供这些参数中的一个。 | 资源 URL： <http://example.html> |

成功的数据响应：:::tips **条件**：请求参数合法，且通过用户身份验证。被修改的 UI 卡片必须由调用该接口的自定义 UI 卡片服务提供商创建。\*\*状态码：\*\* `200 OK` **错误代码：**

* **406**：无权限访问此资源 ::: \*\*响应示例：\*\*

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```

\*\*请求示例：\*\*

```json
{
  "cast_settings": {
    "used": "2×2"
  },
  "web_settings": {
    "used": "1×1"
  }
}
```

#### 8.2.4 删除自定义 UI 卡片

> 已授权用户可使用此接口删除现有 UI 卡片。自定义卡片服务提供商只能删除他们创建的 UI 卡片。

:::提示

* **URL**：`/open-api/v2/rest/ui/cards/{id}`
* **方法**：`DELETE`
* **头部**：
  * Content-Type: application/json
  * Authorization: Bearer ::: 请求参数: 无 成功数据响应: ::: 提示 **条件**：请求参数合法，且通过用户身份验证。被修改的 UI 卡片必须由调用该接口的自定义 UI 卡片服务提供商创建。\*\*状态码：\*\* `200 OK` **错误代码：**
* **406**：无权限访问此资源。 ::: \*\*响应示例：\*\*

```json
{
  "error": 0,
  "data": {},
  "message": "success"
}
```