|
|
@@ -1,39 +1,102 @@
|
|
|
-## 设备配置数据格式
|
|
|
+<center> <font size=28>设备配置数据格式说明文档</font> </center>
|
|
|
+
|
|
|
+<center><font size=12>版本: 1.0 </font></center>
|
|
|
+
|
|
|
+<center><font size=12>发布日期: 2024-11-18 </font></center>
|
|
|
+
|
|
|
+<div style="page-break-after: always;"></div>
|
|
|
+
|
|
|
+<font size=12> 历史记录 </font>
|
|
|
+
|
|
|
+
|
|
|
+| 修订日期 | 版本 | 作者 | 说明 |
|
|
|
+| --------- | ---- | ---------- | -------- |
|
|
|
+| 2024-11-18 | V1.0 | alva.huang | 初始版本 |
|
|
|
+
|
|
|
+
|
|
|
+<div style="page-break-after: always;"></div>
|
|
|
+
|
|
|
+[toc]
|
|
|
+
|
|
|
+<div style="page-break-after: always;"></div>
|
|
|
+
|
|
|
+# 前言
|
|
|
+
|
|
|
+## 概述
|
|
|
+
|
|
|
+本文档旨在说明爱智居设备配置的数据格式，帮助开发人员如何使用api获取配置数据，和解析数据格式，包含API的功能，调用方式，返回结果和错误码。数据格式定义，数据结构，字段说明等。
|
|
|
+
|
|
|
+## 范围说明
|
|
|
+
|
|
|
+此开发文档只针对智能家居面板，门禁，网关等设备。
|
|
|
+
|
|
|
+# 设备配置数据格式
|
|
|
|
|
|
GET 请求URL：
|
|
|
-[https://dev.izhiju.cn/device/config](https://dev.izhiju.cn/device/config)
|
|
|
+[https://dev.izhiju.cn/device](https://dev.izhiju.cn/device)
|
|
|
|
|
|
请求头参数：
|
|
|
Content-Type: application/json
|
|
|
+Authorization: Bearer {{token}}
|
|
|
+
|
|
|
+## HTTP返回状态码说明
|
|
|
+
|
|
|
+200-299 请求成功
|
|
|
+400-499 请求失败，客户端参数或信息错误
|
|
|
+500-599 请求失败，服务端错误
|
|
|
|
|
|
-查寻参数：
|
|
|
+| 状态码 | 说明 |
|
|
|
+|:-------|:---------------------------------------------|
|
|
|
+| 200 | 请求成功 |
|
|
|
+| 201 | 新增成功 |
|
|
|
+| 204 | 删除成功/更新成功 |
|
|
|
+| 401 | 请求失败，无权限，没有登陆认证或认证token错误 |
|
|
|
+| 403 | 请求失败，无权限 |
|
|
|
+| 404 | 请求失败，资源不存在 |
|
|
|
+| 405 | 请求失败，请求方法不支持 |
|
|
|
+| 406 | 请求失败，参数错误 |
|
|
|
+| 400 | 请求失败，参数错误 |
|
|
|
+| 408 | 请求失败，请求超时 |
|
|
|
+| 415 | 请求失败，不支持的媒体类型 |
|
|
|
+| 500 | 请求失败，服务端内部错误 |
|
|
|
|
|
|
+## 获取设备配置列表数据
|
|
|
|
|
|
-| 参数名 | 参数类型 | 值 | 说明 |
|
|
|
-| -------- | -------- | --------------------- | ---------------------------------------------------------------------------------------- |
|
|
|
-| package | string | cn.izhiju.android.xxx | 获取配置的应用包名，必须字段如：cn.izhiju.android.panela |
|
|
|
+### GET请求URL
|
|
|
+
|
|
|
+ {{api_url}}/config?{{query_params}}
|
|
|
+
|
|
|
+### 查寻参数
|
|
|
+
|
|
|
+| 参数名 | 参数类型 | 值 | 说明 |
|
|
|
+| -------- | ------------ | --------------------- | ------------------------------------------------- |
|
|
|
+| package | string | cn.izhiju.android.xxx | 获取配置的应用包名，必须字段如：cn.izhiju.android.panela |
|
|
|
| key | string | 平台相关的密钥 | 应用获取升级的密钥，必须字段 |
|
|
|
| deviceId | string | ac:bc:cd:ee:11:22 | 设备ID或MAC地址，必须字段，后台添加限制时保持一致即可，智能家居应用目前定为大写MAC去冒号 |
|
|
|
-| type | string | 0b11111111 | 获取哪些配置 0和不传为所有，高位在前低位在后，从低到高，1位为设备，2为场景，3为区域，组合7为所有 |
|
|
|
+| type | string | device | 获取哪些配置 all和不传为所有，device为设备配置
|
|
|
+
|
|
|
+### 返回结果
|
|
|
+
|
|
|
+1. 成功，状态码200，返回设备配置列表数据
|
|
|
+2. 失败，状态码401，授权失败
|
|
|
+3. 具体返回状态码和http标准状态码一致，具体请查看[HTTP状态码](https://www.runoob.com/http/http-status-codes.html)
|
|
|
|
|
|
-返回结果：
|
|
|
|
|
|
-1. 成功，状态码200，返回如下内容：
|
|
|
+### 所有设备具有的配置属性返回数据格式示例
|
|
|
|
|
|
```json
|
|
|
-{
|
|
|
- "version": "1.0",
|
|
|
- "devices":[
|
|
|
+[
|
|
|
+ //第一个模板为所有配置，包含必选配置和可选配置，不同设备类型的配置都有说明
|
|
|
{
|
|
|
- "id": 1,
|
|
|
- "pid": 1,
|
|
|
+ "id": 1, //设备配置id
|
|
|
+ "pid": 1, //设备父级id，0为顶级
|
|
|
"areaId": "区域id",
|
|
|
"area": "区域名称",
|
|
|
- "name": "0001",
|
|
|
+ "name": "0001", //设备名称，设备唯一名称
|
|
|
"displayName": "设备显示名称",
|
|
|
- "type": "设备类型",
|
|
|
+ "type": "设备类型", //entrance_guard 门禁，light ,switch,aircon,curtain,fan,airrefresh
|
|
|
"subtype": "设备子类型",
|
|
|
- "channels":[{//缓存的设备状态，或初始默认值，可不存在
|
|
|
+ "channels":[{//缓存的设备状态，或初始默认值，可选，不传时为空，具体项看设备控制协议定义
|
|
|
"name": "action",
|
|
|
"type": "STRING",
|
|
|
"mode": "READ_WRITE",
|
|
|
@@ -72,7 +135,7 @@ Content-Type: application/json
|
|
|
]
|
|
|
"card_format":1,//卡数据格式 0为无，1为10位10进制，2为10位10进制反向输出，3为8位16进制，4为8位16进制反向输出，5为8位10进制（id后3字节转换），6为00+8位10进制，7为8位10进制（id后4字节转换），8为5位10进制
|
|
|
"associated_lock": //关联的锁，如门锁，窗锁，门禁等
|
|
|
- //智能控制面板配置
|
|
|
+ //智能控制面板配置 panel
|
|
|
"display_device": //面板上要显示的设备列表
|
|
|
[{
|
|
|
"name": "0001",
|
|
|
@@ -95,7 +158,7 @@ Content-Type: application/json
|
|
|
"lock_weekday": [1, 2, 3, 4, 5], //一周中哪些天需要锁定
|
|
|
"lock_start_time": "12:00:00", //一天中锁定的开始时间，格式为24小时制
|
|
|
"lock_end_time": "23:59:59", //一天中锁定的结束时间，格式为24小时制
|
|
|
- //门禁面板配置
|
|
|
+ //门禁面板配置 entrance_guard
|
|
|
"camera_type": "IR",// 门禁摄像头类型，IR红外，RGB为全彩，RGB_IR为红外+彩
|
|
|
"brightness": 100,//亮度
|
|
|
"screen_off": 2,//屏幕关闭时间，单位为分钟,0为不关闭,和系统的熄屏列表对应
|
|
|
@@ -107,93 +170,158 @@ Content-Type: application/json
|
|
|
"mask_detection": false,//是否开启口罩检测
|
|
|
}
|
|
|
},
|
|
|
+ // 继电器灯光配置，
|
|
|
{
|
|
|
- "id": 1,
|
|
|
- "pid": 1,
|
|
|
- "areaId": "CAN区域",
|
|
|
- "area": "区域名称",
|
|
|
- "name": "0001",
|
|
|
- "displayName": "灯光",
|
|
|
+ "id": 1, "pid": 1,"areaId": "CAN区域", "area": "区域名称", "name": "0001", "displayName": "灯光",
|
|
|
"type": "light",
|
|
|
- "subtype": "light_plat",
|
|
|
+ "subtype": "light_common",
|
|
|
"config":
|
|
|
{
|
|
|
"address": "12345678", //地址
|
|
|
- "ports": [1], //端口
|
|
|
- "broadcast": false //跨网关是否广播 false为不广播，true为广播
|
|
|
+ "ports": [1], //端口，只用一个端口的设备取数组第一个值
|
|
|
+ "broadcast": false //跨网关是否广播 false为不广播，true为广播，废弃状态
|
|
|
}
|
|
|
- },
|
|
|
+ }]
|
|
|
+```
|
|
|
+
|
|
|
+### 灯光设备配置数据示例
|
|
|
+
|
|
|
+```json
|
|
|
+[
|
|
|
+ {
|
|
|
+ "id": 1, "pid": 1,"areaId": "CAN区域", "area": "区域名称", "name": "0001", "displayName": "灯光",
|
|
|
+ "type": "light",
|
|
|
+ "subtype": "light_common", //subtype为子类型，light_common为普通灯光,默认值
|
|
|
+ "config":
|
|
|
{
|
|
|
- "id": 2,
|
|
|
- "pid": 1,
|
|
|
- "areaId": "CAN区域",
|
|
|
- "area": "区域名称",
|
|
|
- "name": "0002",
|
|
|
- "displayName": "窗帘",
|
|
|
- "type": "curtain",
|
|
|
- "subtype": "canbus",
|
|
|
- "config":
|
|
|
- {
|
|
|
- "address": "12345678",
|
|
|
- "ports": [1,2], //多端口 当继电器窗帘或空调时用，窗帘1为开，2为关端口
|
|
|
- "broadcast": false,
|
|
|
- "sub_address":"22",
|
|
|
- "control_type": "1",//控制类型 1协议类型，2继电器单信号，3继电器断信号，4继电器双信号
|
|
|
- }
|
|
|
- },
|
|
|
+ "address": "A5", //地址
|
|
|
+ "ports": [1], //端口，只用一个端口的设备取数组第一个值
|
|
|
+ "bus":"canbus",//设备接入总线或协议类型，canbus/network/serial/RS485/zigbee/bluetooth/dali/knx/plc-iot,默认canbus
|
|
|
+ }
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "id": 1, "pid": 1,"areaId": "CAN区域", "area": "区域名称", "name": "0001", "displayName": "灯光",
|
|
|
+ "type": "lightdim",//调光灯，
|
|
|
+ "subtype": "dimming_single", //"dimming_single", "单路调光灯"/"dimming_color_temp", "调亮度调色温灯"
|
|
|
+ "config":
|
|
|
{
|
|
|
- "id": 2,
|
|
|
- "pid": 1,
|
|
|
- "areaId": "CAN区域",
|
|
|
- "area": "区域名称",
|
|
|
- "name": "0002",
|
|
|
- "displayName": "窗帘",
|
|
|
- "type": "curtain",
|
|
|
- "subtype": "canbus",
|
|
|
- "config":
|
|
|
- {
|
|
|
- "address": "12345678",
|
|
|
- "port": 1,
|
|
|
- "ports": [1,2], //多端口 当为继电器窗帘时，继电器1为开，2为关端口
|
|
|
- "broadcast": false,
|
|
|
- "sub_address":"22", //协议窗帘子地址，如485协议窗帘，子地址为22
|
|
|
- "control_type": 2, //控制类型 1协议类型，2继电器单信号，3继电器断信号，4继电器双信号
|
|
|
- }
|
|
|
+ "address": "F012345678FF", //地址
|
|
|
+ "ports": [1], //端口，只用一个端口的设备取数组第一个值
|
|
|
+ "bus":"bluetooth",//设备接入总线或协议类型，canbus/network/serial/RS485/zigbee/bluetooth/dali/knx/plc-iot,默认canbus
|
|
|
+ }
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "id": 1, "pid": 1,"areaId": "CAN区域", "area": "区域名称", "name": "0001", "displayName": "灯光",
|
|
|
+ "type": "lightrgb",//彩光灯，
|
|
|
+ "subtype": "lightrgb_common", // "lightrgb_common", "彩灯"/"lightrgb_rgbw", "带白光彩灯"
|
|
|
+ "config":
|
|
|
+ {
|
|
|
+ "address": "F012345678FF", //地址
|
|
|
+ "ports": [1], //端口，只用一个端口的设备取数组第一个值
|
|
|
+ "bus":"bluetooth",//设备接入总线或协议类型，canbus/network/serial/RS485/zigbee/bluetooth/dali/knx/plc-iot,默认canbus
|
|
|
+ }
|
|
|
+ }
|
|
|
+]
|
|
|
+```
|
|
|
+
|
|
|
+### 窗帘设备配置数据示例
|
|
|
+
|
|
|
+```json
|
|
|
+[
|
|
|
+ {//继电器窗帘
|
|
|
+ "id": 1, "pid": 1,"areaId": "CAN区域", "area": "区域名称", "name": "0001", "displayName": "窗帘",
|
|
|
+ "type": "curtain",
|
|
|
+ //curtain_horizontal 横窗帘 curtain_horizontal_double 双层横窗帘 curtain_vertical 卷帘 curtain_shutter 百页窗
|
|
|
+ //curtain_position_horizontal 可定位置开合帘 curtain_position_vertical 可定位置升降帘
|
|
|
+ "subtype": "curtain_horizontal", //subtype为子类型，light_common为普通灯光,默认值
|
|
|
+ "config":
|
|
|
+ {
|
|
|
+ "address": "A5", //地址继电器地址或协议转换器地址
|
|
|
+ "ports": [1,2], //继电器按顺序排列1为开，2为关端口,can协议转换窗帘为协议转换器端口
|
|
|
+ "control_type": 2, //控制类型 0协议类型，1为继电器，当为窗帘时1为单信号，2继电器断信号，3继电器双信号,4为干节点
|
|
|
+ "bus":"canbus",//设备接入总线或协议类型，canbus/network/serial/RS485/zigbee/bluetooth/dali/knx/plc-iot,默认canbus
|
|
|
+ }
|
|
|
+ },
|
|
|
+ {//协议窗帘
|
|
|
+ "id": 1, "pid": 1,"areaId": "CAN区域", "area": "区域名称", "name": "0001", "displayName": "窗帘",
|
|
|
+ "type": "curtain",
|
|
|
+ //curtain_horizontal 横窗帘 curtain_horizontal_double 双层横窗帘 curtain_vertical 卷帘 curtain_shutter 百页窗
|
|
|
+ //curtain_position_horizontal 可定位置开合帘 curtain_position_vertical 可定位置升降帘
|
|
|
+ "subtype": "curtain_horizontal", //subtype为子类型，light_common为普通灯光,默认值
|
|
|
+ "config":
|
|
|
+ {
|
|
|
+ "address": "A5", //地址继电器地址或协议转换器地址
|
|
|
+ "ports": [1,2], //继电器按顺序排列1为开，2为关端口,can协议转换窗帘为协议转换器端口
|
|
|
+ "sub_address":["22FA33"], //如485协议窗帘，第一个即窗帘485地址，或433窗帘的遥控器id,433设备对应的遥控码,3字节16进制字符串格式， 取值范围 0-16777215(小端在后比如0x112233)
|
|
|
+ "control_type": 0, //控制类型 0协议类型，1为继电器，当为窗帘时1为单信号，2继电器断信号，3继电器双信号,4为干节点
|
|
|
+ "bus":"canbus",//设备接入总线或协议类型，canbus/network/serial/RS485/zigbee/bluetooth/dali/knx/plc-iot,默认canbus
|
|
|
+ }
|
|
|
+ },
|
|
|
+]
|
|
|
+```
|
|
|
+
|
|
|
+### 暖通空调设备配置数据示例
|
|
|
+
|
|
|
+```json
|
|
|
+[
|
|
|
+ {//继电器空调
|
|
|
+ "id": 1, "pid": 1,"areaId": "CAN区域", "area": "区域名称", "name": "0001", "displayName": "空调",
|
|
|
+ "type": "aircon",
|
|
|
+ //aircon_common 默认类型 aircon_fcu 风机盘管 aircon_daikin 大金空调 aircon_haier 海尔空调
|
|
|
+ //aircon_gree 格力空调 aircon_hisense 海信空调 aircon_midea 美的空调 aircon_hitachi 日立空调
|
|
|
+ "subtype": "aircon_common", //subtype为子类型，aircon_common为默认值，通用空调
|
|
|
+ "config":
|
|
|
+ {
|
|
|
+ "address": "A5", //canbus总线时，地址为继电器地址或协议转换器地址，网络总线时，地址为网络设备mac地址
|
|
|
+ "ports": [1,2], //按数组顺序 1,2,3为一二三档对应的继电器端口，4为制冷，5为制热端口
|
|
|
+ "control_type": 2, //控制类型 0协议类型，1为继电器，当为窗帘时1为单信号，2继电器断信号，3继电器双信号,4为干节点
|
|
|
+ "bus":"canbus",//设备接入总线或协议类型，canbus/network/serial/RS485/zigbee/bluetooth/dali/knx/plc-iot,默认canbus
|
|
|
+ "temp": 30,//默认温度
|
|
|
+ "humidity": 60,//默认湿度
|
|
|
+ "speed":3 ,//空调，风扇风力档位数量，默认为3档，低，中，高，取值1-6
|
|
|
+ "modes": ["fan","cool","heat",""],//支持模式列表 fan,cool,heat,auto,saving,dehumidify,sleeping
|
|
|
+ "bus":"canbus",//设备接入总线或协议类型，canbus/network/serial/RS485/zigbee/bluetooth/dali/knx/plc-iot
|
|
|
+ "associated_sensor": //关联传感器，如温湿度传感器,第一个为环境温湿度传感器，当为地暖时，第二个为报警温度传感器，默认45度
|
|
|
+ [{"name":"humiture1","calibration":10},
|
|
|
+ {"name":"humiture2", //关联传感器2，设备唯一的名称
|
|
|
+ "calibration":5 //校正温度度数
|
|
|
+ }],
|
|
|
+ }
|
|
|
+ },
|
|
|
+
|
|
|
+]
|
|
|
+```
|
|
|
+
|
|
|
+### 组合配置数据格式实例
|
|
|
+
|
|
|
+```json
|
|
|
+ {
|
|
|
+ "version": "1.0",
|
|
|
+ "devices":[
|
|
|
+ {
|
|
|
+ "id": 1, "pid": 1,"areaId": "CAN区域", "area": "区域名称", "name": "0001", "displayName": "灯光",
|
|
|
+ "type": "light",
|
|
|
+ "subtype": "light_common", //subtype为子类型，light_common为普通灯光,默认值
|
|
|
+ "config":
|
|
|
+ {
|
|
|
+ "address": "A5", //地址
|
|
|
+ "ports": [1], //端口，只用一个端口的设备取数组第一个值
|
|
|
+ "bus":"canbus",//设备接入总线或协议类型，canbus/network/serial/RS485/zigbee/bluetooth/dali/knx/plc-iot,默认canbus
|
|
|
+ }
|
|
|
},
|
|
|
{
|
|
|
"id": 1,
|
|
|
"pid": 1,
|
|
|
"areaId": "CAN区域",
|
|
|
- "name": "2001",
|
|
|
- "displayName": "can面板",
|
|
|
- "type": "panel",
|
|
|
- "subtype": "canbus",
|
|
|
+ "area": "区域名称",
|
|
|
+ "name": "0001",
|
|
|
+ "displayName": "灯光",
|
|
|
+ "type": "light",
|
|
|
+ "subtype": "light_plat",
|
|
|
"config":
|
|
|
{
|
|
|
- "address": "12345678",
|
|
|
- "port": 1,
|
|
|
- "broadcast": false,
|
|
|
- "associated_sensor": ["humiture1","humiture2"],//关联传感器
|
|
|
- "display_device": [{
|
|
|
- "name": "0001",
|
|
|
- "lock": false
|
|
|
- }, {
|
|
|
- "name": "0003",
|
|
|
- "lock": false
|
|
|
- }],
|
|
|
- "display_scene": [{
|
|
|
- "name": "1009",
|
|
|
- "lock": false
|
|
|
- }, {
|
|
|
- "name": "100A",
|
|
|
- "lock": false
|
|
|
- }, {
|
|
|
- "name": "100B",
|
|
|
- "lock": false
|
|
|
- }],
|
|
|
- "lock_weekday": [1, 2, 3, 4, 5],
|
|
|
- "lock_start_time": "12:00:00",
|
|
|
- "lock_end_time": "23:59:59"
|
|
|
+ "address": "12345678", //地址
|
|
|
+ "ports": [1], //端口
|
|
|
}
|
|
|
}],
|
|
|
|
miricy