摩根客控控制接口

## 1. 说明：
**客控云系统对外接口主要分为两部分：**

1. http接口，主要功能包括 获取场景和设备，控制场景和设备；
   2. mqtt接口，主要功能是接收设备状态数据的推送；

## 2. http接口
###  1. 认证
请参考[摩根公用接口鉴权说明](https://doc.moorgen.com/doc/607 "摩根公用接口鉴权说明")
### 2. 分页获取空间位置对应的设备列表
#### 接口说明
该系列接口默认的前提是第三方有具体的空间标识，并且和客控云中空间标识对应，例如：1-3-301 即1栋楼第三层301室，
传参：
buildingNum:1
floorNum:3 
roomNum:301
#### 接口地址
> **GET** /interface/pms/v1/device/page

#### 请求参数
| **参数名** | **类型** | **参数类型** | **必填** | **说明** |
| --- | --- | --- | --- | --- |
| hotelToken | String | header | true | 酒店标识 |
| buildingNum | integer | query | false | 建筑编号 |
| floorNum | integer | query | false | 楼层编号 |
| roomNum | String | query | false | 房间编号 |
| pageNo | integer | query | false | 分页页码 |
| pageSize | integer | query | false | 分页大小 |

#### 返回参数
| **参数名** | **类型** | **说明** |
| --- | --- | --- |
| code | Integer | 响应码，0正常，其它详见 [错误码](https://www.yuque.com/lichunyang-9hqd0/moorgen_interface_doc/mbvq8o#ZjBWx) 。 |
| msg | String | 请求失败返回的信息，成功则返回空值。 |
| data | Object<result> | 返回数据 |
| ok | boolean | 状态反馈  |

**result 说明**

| **参数名** | **类型** | **说明** |
| --- | --- | --- |
| records | JSONArray | 数据集合 |
| total | integer | 数据总数量 |
| size | integer | 分页大小 |
| current | integer | 当前页 |
| pages | integer | 总页数 |

**records说明（JSONArray）**

| **参数名** | **类型** | **说明** |
| --- | --- | --- |
| rcuToken | String  | 主机唯一标识 |
| deviceId | String  | 该主机内的设备唯一标识 |
| deviceType | integer | 设备类型 |
| deviceName | String  | 设备名称 |
| dataPoints | JSONObject | 数据点属性 |

#### 请求示例
![](/media/202406/2024-06-11_165651_9919270.05555658446149381.png)
#### 返回示例
```json
{
  "code": 0,
  "msg": null,
  "data": {
    "records": [
      {
        "rcuToken": "02203501ffff0090",
        "deviceId": "00d2ffffffffffff",
        "deviceType": 2,
        "deviceName": "调光灯-0",
        "dataPoints": {
          "currentBrightness": 0,
          "state": 0
        }
      },
      {
        "rcuToken": "02203501ffff0090",
        "deviceId": "01d2ffffffffffff",
        "deviceType": 2,
        "deviceName": "调光灯-1",
        "dataPoints": {
          "currentBrightness": 0,
          "state": 0
        }
      }
    ],
    "total": 13,
    "size": 2,
    "current": 1,
    "orders": [],
    "optimizeCountSql": true,
    "hitCount": false,
    "countId": null,
    "maxLimit": null,
    "searchCount": true,
    "pages": 7
  },
  "ok": true
}
```
### 3. 获取空间位置对应的设备列表
#### 接口说明
该系列接口默认的前提是第三方有具体的空间标识，并且和客控云中空间标识对应，例如：1-3-301 即1栋楼第三层301室，
传参：
buildingNum:1
floorNum:3
roomNum:301
#### 接口地址
> **GET** /interface/pms/v1/device/list

#### 请求参数
| **参数名** | **类型** | **参数类型** | **必填** | **说明** |
| --- | --- | --- | --- | --- |
| hotelToken | String | header | true | 酒店标识 |
| buildingNum | integer | query | false | 建筑编号 |
| floorNum | integer | query | false | 楼层编号 |
| roomNum | String | query | false | 房间编号 |

#### 返回参数
| **参数名** | **类型** | **说明** |
| --- | --- | --- |
| code | Integer | 响应码，0正常，其它详见 [错误码](https://www.yuque.com/lichunyang-9hqd0/moorgen_interface_doc/mbvq8o#ZjBWx) 。 |
| msg | String | 请求失败返回的信息，成功则返回空值。 |
| data | Object<result> | 返回数据 |
| ok | boolean | 状态反馈  |

**result 说明 （JSONArray 设备数据）**

| **参数名** | **类型** | **说明** |
| --- | --- | --- |
| rcuToken | String  | 主机唯一标识 |
| deviceId | String  | 该主机内的设备唯一标识 |
| deviceType | integer | 设备类型 |
| deviceName | String  | 设备名称 |
| dataPoints | JOSNObject | 数据点 |

#### 请求示例
![](/media/202406/2024-06-11_165755_4833850.08838601878884733.png)
#### 返回示例
```json
{
  "code": 0,
  "msg": null,
  "data": [
    {
      "rcuToken": "02203501ffff0090",
      "deviceId": "00d2ffffffffffff",
      "deviceType": 2,
      "deviceName": "调光灯-0",
      "dataPoints": {
        "currentBrightness": 0,
        "state": 0
      }
    },
    {
      "rcuToken": "02203501ffff0090",
      "deviceId": "0111ffffffffffff",
      "deviceType": 1,
      "deviceName": "普通灯-1",
      "dataPoints": {
        "status": 0
      }
    },
    {
      "rcuToken": "02203501ffff0090",
      "deviceId": "03a4ffffffffffff",
      "deviceType": 174,
      "deviceName": "PM2.5传感器-3",
      "dataPoints": {
        "state": 1,
        "PM": 10
      }
    }
  ],
  "ok": true
}
```

### 4. 设备控制
#### 接口说明
设备控制使用摩根对外提供的设备数据点进行接口的控制，数据点详情请联系摩根技术对接人员获取；
#### 接口地址
> **POST** /interface/pms/v1/device/control

#### 请求参数
| **参数名** | **类型** | **参数类型** | **必填** | **说明** |
| --- | --- | --- | --- | --- |
| hotelToken | String | header | true | 酒店标识 |
| rcuToken | String | body(json) | true | rcu唯一标识（设备列表返回中包含） |
| deviceId | String | body(json) | true | 设备唯一标识（设备列表返回中包含） |
| dataPoints | JSONObject | body(json) | true | 写数据点 |

#### 返回参数
| **参数名** | **类型** | **说明** |
| --- | --- | --- |
| code | Integer | 响应码，0正常，其它详见 [错误码](https://www.yuque.com/lichunyang-9hqd0/moorgen_interface_doc/mbvq8o#ZjBWx) 。 |
| msg | String | 请求失败返回的信息，成功则返回空值。 |
| data | null | 返回数据 |
| ok | boolean | 状态反馈  |

#### 请求示例
![](/media/202406/2024-06-11_165853_2340510.819245753814215.png)
#### 返回示例
```json
{
  "code": 0,
  "msg": null,
  "data": null,
  "ok": true
}
```

### 5. 分页获取空间位置对应的场景列表
#### 接口说明
该系列接口默认的前提是第三方有具体的空间标识，并且和客控云中空间标识对应，例如：1-3-301 即1栋楼第三层301室，
传参：
buildingNum:1
floorNum:3
roomNum:301
#### 接口地址
> **GET** /interface/pms/v1/scene/page

#### 请求参数
| **参数名** | **类型** | **参数类型** | **必填** | **说明** |
| --- | --- | --- | --- | --- |
| hotelToken | String | header | true | 酒店标识 |
| buildingNum | integer | query | false | 建筑编号 |
| floorNum | integer | query | false | 楼层编号 |
| roomNum | String | query | false | 房间编号 |
| pageNo | integer | query | false | 分页页码 |
| pageSize | integer | query | false | 分页大小 |

#### 返回参数
| **参数名** | **类型** | **说明** |
| --- | --- | --- |
| code | Integer | 响应码，0正常，其它详见 [错误码](https://www.yuque.com/lichunyang-9hqd0/moorgen_interface_doc/mbvq8o#ZjBWx) 。 |
| msg | String | 请求失败返回的信息，成功则返回空值。 |
| data | Object<result> | 返回数据 |
| ok | boolean | 状态反馈  |

**result 说明**

| **参数名** | **类型** | **说明** |
| --- | --- | --- |
| records | JSONArray | 数据集合 |
| total | integer | 数据总数量 |
| size | integer | 分页大小 |
| current | integer | 当前页 |
| pages | integer | 总页数 |

**records说明**

| **参数名** | **类型** | **说明** |
| --- | --- | --- |
| rcuToken | String  | 设备唯一标识 |
| sceneId | integer | 数据总数量 |
| sceneName | integer | 分页大小 |
| sceneType | integer | 当前页 |

#### 请求示例
![](/media/202406/2024-06-11_170015_4553890.24198217343033668.png)
#### 返回示例
```json
{
  "code": 0,
  "msg": null,
  "data": {
    "records": [
      {
        "rcuToken": "02203501ffff0090",
        "sceneId": "0100",
        "sceneName": "普通灯开",
        "sceneType": 0
      },
      {
        "rcuToken": "02203501ffff0090",
        "sceneId": "0200",
        "sceneName": "普通灯关",
        "sceneType": 0
      }
    ],
    "total": 2,
    "size": 2,
    "current": 1,
    "orders": [],
    "optimizeCountSql": true,
    "hitCount": false,
    "countId": null,
    "maxLimit": null,
    "searchCount": true,
    "pages": 1
  },
  "ok": true
}
```
### 6. 获取空间位置对应的场景列表
#### 接口说明
该系列接口默认的前提是第三方有具体的空间标识，并且和客控云中空间标识对应，例如：1-3-301 即1栋楼第三层301室，
传参：
buildingNum:1
floorNum:3
roomNum:301
#### 接口地址
> **GET** /interface/pms/v1/scene/list

#### 请求参数
| **参数名** | **类型** | **参数类型** | **必填** | **说明** |
| --- | --- | --- | --- | --- |
| hotelToken | String | header | true | 酒店标识 |
| buildingNum | integer | query | false | 建筑编号 |
| floorNum | integer | query | false | 楼层编号 |
| roomNum | String | query | false | 房间编号 |

#### 返回参数
| **参数名** | **类型** | **说明** |
| --- | --- | --- |
| code | Integer | 响应码，0正常，其它详见 [错误码](https://www.yuque.com/lichunyang-9hqd0/moorgen_interface_doc/mbvq8o#ZjBWx) 。 |
| msg | String | 请求失败返回的信息，成功则返回空值。 |
| data | Object<result> | 返回数据 |
| ok | boolean | 状态反馈  |

**result 说明 （JSONArray 设备数据）**

| **参数名** | **类型** | **说明** |
| --- | --- | --- |
| rcuToken | String  | 设备唯一标识 |
| sceneId | integer | 数据总数量 |
| sceneName | integer | 分页大小 |
| sceneType | integer | 当前页 |

#### 请求示例

![](/media/202406/2024-06-11_170143_1151390.9664088009581503.png)
#### 返回示例
```json
{
  "code": 0,
  "msg": null,
  "data": [
    {
      "rcuToken": "02203501ffff0090",
      "sceneId": "0100",
      "sceneName": "普通灯开",
      "sceneType": 0
    },
    {
      "rcuToken": "02203501ffff0090",
      "sceneId": "0200",
      "sceneName": "普通灯关",
      "sceneType": 0
    }
  ],
  "ok": true
}
```
### 7. 场景触发
#### 接口说明
场景控制使用rcu标识和场景标识+场景类型（0场景，1序列（可以理解为稍微复制的场景））；
#### 接口地址
> **POST** /interface/pms/v1/scene/control

#### 请求参数
| **参数名** | **类型** | **参数类型** | **必填** | **说明** |
| --- | --- | --- | --- | --- |
| hotelToken | String | header | true | 酒店标识 |
| rcuToken | String | body(json) | true | rcu唯一标识（设备列表返回中包含） |
| sceneId | String | body(json) | true | 场景唯一标识 |
| sceneType | Integer | body(json) | true | 场景类型（0/1） |

#### 返回参数
| **参数名** | **类型** | **说明** |
| --- | --- | --- |
| code | Integer | 响应码，0正常，其它详见 [错误码](https://www.yuque.com/lichunyang-9hqd0/moorgen_interface_doc/mbvq8o#ZjBWx) 。 |
| msg | String | 请求失败返回的信息，成功则返回空值。 |
| data | null | 返回数据 |
| ok | boolean | 状态反馈  |

#### 请求示例
![](/media/202406/2024-06-11_170219_9710250.2569196600365534.png)
#### 返回示例
```json
{
  "code": 0,
  "msg": null,
  "data": null,
  "ok": true
}
```
### 8. 获取主机列表
#### 接口说明
获取酒店内所有的RCU主机信息列表
#### 接口地址
> **POST**  /interface/pms/v2/host/list

#### 请求参数
| **参数名** | **类型** | **参数类型** | **必填** | **说明** |
| --- | --- | --- | --- | --- |
| hotelToken | String | header | true | 酒店标识 |

#### 返回参数
| **参数名** | **类型** | **说明** |
| --- | --- | --- |
| code | Integer | 响应码，0正常，其它详见 [错误码](https://www.yuque.com/lichunyang-9hqd0/moorgen_interface_doc/mbvq8o#ZjBWx) 。 |
| msg | String | 请求失败返回的信息，成功则返回空值。 |
| data | null | 返回数据 |
| ok | boolean | 状态反馈  |

#### 请求示例
![](/media/202406/2024-06-11_170319_3952580.2816494183754761.png)
#### 返回示例
```json
{
    "code": 0,
    "data": [
        {
            "rcuId": 96832,
            "rcuVersion": "MR7222-22-08-04-S1.03.01",
            "deviceType": "01nuty3s",
            "rcuToken": "01214620ffff5ef8",
            "mac": "7274aff05801",
            "hotelToken": "ff889d3044504f48881dc9f1b7561ba9",
            "buildingNum": 1,
            "floorNum": 6,
            "roomNum": "6201",
            "roomType": 0,
            "roomTypeName": "测试房间类型",
            "onlineFlag": 1,
            "localIp": "211.91.57.96",
            "delFlag": 0,
            "createTime": "2022-08-04 09:12:36",
            "updateTime": "2022-09-20 08:28:13"
        },
        {
            "rcuId": 96840,
            "rcuVersion": "MT7022-GB6792-3.3.6",
            "deviceType": "01cx03vj",
            "rcuToken": "01212122ffff17e3",
            "mac": "1442fca9dafa",
            "hotelToken": "ff889d3044504f48881dc9f1b7561ba9",
            "buildingNum": 5,
            "floorNum": 8,
            "roomNum": "808",
            "roomType": 2,
            "roomTypeName": "rcu",
            "onlineFlag": 0,
            "localIp": "112.64.139.250",
            "delFlag": 0,
            "createTime": "2022-09-05 16:11:34",
            "updateTime": "2022-09-14 15:54:43"
        }
    ],
    "ok": true
}
```
### 9. 获取指定主机列表中的设备列表
#### 接口说明
可以获取指定一个或者多个RCU主机集合，获取对应的设备信息集合
#### 接口地址
> **POST  /interface/pms/v2/device/list**

#### 请求参数
| **参数名** | **类型** | **参数类型** | **必填** | **说明** |
| --- | --- | --- | --- | --- |
| hotelToken | String | header | true | 酒店标识 |
| String[] | json | true | RCU主机标识集合 |

#### 请求示例
![](/media/202406/2024-06-11_170410_1408190.8268766559067952.png)
#### 返回参数
| **参数名** | **类型** | **说明** |
| --- | --- | --- |
| code | Integer | 响应码，0正常，其它详见 [错误码](https://www.yuque.com/lichunyang-9hqd0/moorgen_interface_doc/mbvq8o#ZjBWx) 。 |
| msg | String | 请求失败返回的信息，成功则返回空值。 |
| data | null | 返回数据 |
| ok | boolean | 状态反馈  |

#### 返回示例
```json
{
    "code": 0,
    "data": [
        {
            "rcuToken": "01212122ffff17e3",
            "deviceId": "1821ffffffff00ff",
            "deviceType": 87,
            "deviceName": "空调",
            "online": 1,
            "dataPoints": {
                "horizontalDirection": 1,
                "verticalDirection": 1,
                "state": 0,
                "currentTemp": 20.0,
                "currentSpeed": 0,
                "currentMode": 1
            }
        },
        {
            "rcuToken": "01212122ffff17e3",
            "deviceId": "1821ffffffff01ff",
            "deviceType": 86,
            "deviceName": "新风",
            "online": 1,
            "dataPoints": {
                "currentWind": 1,
                "currentHumidity": 0,
                "state": 0
            }
        },
        {
            "rcuToken": "01212122ffff17e3",
            "deviceId": "1821ffffffff02ff",
            "deviceType": 161,
            "deviceName": "地暖",
            "online": 1,
            "dataPoints": {
                "state": 0,
                "currentTemp": 20.0
            }
        },
        {
            "rcuToken": "01212122ffff17e3",
            "deviceId": "1721ffffffff00ff",
            "deviceType": 133,
            "deviceName": "玄关感应",
            "online": 0,
            "dataPoints": {
                "alarmStatus": 0,
                "state": 1
            }
        }
    ],
    "ok": true
}
```

## 3. mqtt连接
### 1. 连接说明

-  遵循mqtt v3.1.1
- 具体连接参数：
   - **clientId**: pmsMqtt前缀+pmsToken; ( pmsMqtt前缀 = "Pms@"，pmsToken 在酒店信息中配置或者生成)
   - **username**: pmsKey ( 在酒店信息中查询)
   - **password**: pmsValue ( 在酒店信息中查询)
- 订阅规则：

**topic**= **"PmsTopic@"+ 酒店唯一标识（hotelToken）**( 在酒店信息中查询)
### 2. 消息
报文内容统一使用json字符串，目前支持设备状态的推送；
### 3.mqtt协议说明：
消息主机包括：消息类型，消息类型说明，消息ID，消息数据
```json
{
  "data": {
    "dataPoints": {
      "state": 1
    },
    "deviceId": "2022ffffffff00ff",
    "deviceType": 1,
    "online": 1,
    "rcuToken": "01212122ffff17e3"
  },
  "messageDesc": "更新设备",
  "messageId": 1663305201298,
  "messageType": 3
}
```
#### 消息类型说明：
| 类型代（messageType） | 说明 |
| --- | --- |
| 1 | 添加设备 |
| 2 | 删除设备 |
| 3 | 更新设备 |
| 13 | 主机掉线 |
| 14 | 主机上线 |
| 15 | 设备掉线 |
| 16 | 设备上线 |
| 17 | 设备数据重载 |

说明：15，16两个命令在使用RCU主机情况下一般不会出现
##### 1. 添加设备
```json
{
  "data": {
    "dataPoints": {
      "currentTemperature": 30.0,
      "state": 1
    },
    "deviceId": "9a01ffffffff06ff",
    "deviceName": "9a01-6",
    "deviceType": 197,
    "online": 1,
    "rcuToken": "01214620ffff5ef8"
  },
  "messageDesc": "添加设备",
  "messageId": 1663636192735,
  "messageType": 1
}
```
##### 2.删除设备
```json
{
  "data": {
    "deviceId": "9a01ffffffff01ff",
    "rcuToken": "01214620ffff5ef8"
  },
  "messageDesc": "删除设备",
  "messageId": 1663635992061,
  "messageType": 2
}
```
##### 3. 更新设备
```json
{
    "data":{
        "dataPoints":{                         //设备可读数据点集合
            "state":1,
            "PM":11
        },
        "deviceId":"03a4ffffffffffff",         //设备唯一标识
        "deviceName":"PM2.5传感器-3",          //rcu唯一标识
        "deviceType":174,
        "rcuToken":"02203501ffff0090"
    },
    "messageId":1630554021048,                 //消息唯一ID
    "messageType":3                            //消息类型,目前使用一种设备状态推送类型=3
}
```
##### 4.主机掉线
```json
{
  "data": {
    "rcuToken": "01214620ffff5ef8"
  },
  "messageDesc": "主机掉线",
  "messageId": 1663636346775,
  "messageType": 13
}
```
##### 5.主机上线
```json
{
  "data": {
    "rcuToken": "01214620ffff5ef8"
  },
  "messageDesc": "主机上线",
  "messageId": 1663636444684,
  "messageType": 14
}
```
##### 6.设备掉线
```json
{
  "data": {
    "dataPoints": {
      "currentTemperature": 30.0,
      "state": 1
    },
    "deviceId": "9a01ffffffff06ff",
    "deviceName": "9a01-6",
    "deviceType": 197,
    "online": 0,
    "rcuToken": "01214620ffff5ef8"
  },
  "messageDesc": "设备掉线",
  "messageId": 1663636192735,
  "messageType": 15
}
```
##### 7.设备上线
```json
{
  "data": {
    "dataPoints": {
      "currentTemperature": 30.0,
      "state": 1
    },
    "deviceId": "9a01ffffffff06ff",
    "deviceName": "9a01-6",
    "deviceType": 197,
    "online": 1,
    "rcuToken": "01214620ffff5ef8"
  },
  "messageDesc": "设备上线",
  "messageId": 1663636192735,
  "messageType": 16
}
```
##### 8.设备数据重载
```json
{
  "data": {
    "rcuToken": "01214620ffff5ef8"
  },
  "messageDesc": "设备数据重载",
  "messageId": 1663636460221,
  "messageType": 17
}
```