控制板标品MQTT协议文档

# 一. 概述
#### 应用场景
   本文档提供一套直接访问门禁设备的接口，使用者购买设备后，就可以直接根据接口说明进行自定义开发整套门禁或相关应用系统。接口使用 MQTT 通信协议，可以对接各种通用的 MQTT 代理，但是我们推荐使用门禁网关来统一管理设备。

#### 接口规范
接口使用 MQTT 协议，按方向分为上行与下行：
- **上行**：是指设备上发消息给后台或应用。
- **下行**：是指后台或应用下发消息给设备。

按发起方分为：指令类、事件类
- **指令类**：是由应用平台发起，先**下行**，给设备发送指令，再**上行**，设备返回给应用平台
- **事件类**：是由设备主动发起，先**上行**，设备上报到平台应用一些数据，再**下行**，平台应用返回给设备一个回复

消息格式是标准的 MQTT 报文结构，包含消息 Topic 与消息内容，格式如下：

1) 消息 Topic：消息标题,不管是上行还是下行，发送指令和返回指令的 Topic 基本规则是**指令**和**指令_reply**。格式如下：
    - 下行：access_device/v1/cmd/{#uuid}/xxxx，对应的返回指令（上行）：access_device/v1/cmd/xxxx_reply
    - 上行：access_device/v1/event/yyyy，对应的返回指令（下行）：access_device/v1/event/{#uuid}/yyyy_reply

>注：其中access是门禁的特定标识，cmd 表示由后台或应用先主动给设备发送指令，event 表示设备主动给后台或应用发送消息或触发事件，{#uuid} 表示设备的唯一标识

2) 消息内容:文本格式的消息内容，内容为Json格式
发送消息内容的示例如下：
```json
{ 
 "serialNo": "6w8keif5g6",
 "uuid": "0a1b2c3d",
 "data": {
 ...
 },
 "time":1647580466, 
 "sign":"e0k4jrir85tje8ru4jrur499r99ii4ur"
}
```
返回消息内容的示例如下：
```json
{ 
 "serialNo": "6w8keif5g6",
 "uuid": "0a1b2c3d",
 "code": "000000",
 "data": {
 ...
 },
 "time":1647580466, 
 "sign":"e0k4jrir85tje8ru4jrur499r99ii4ur"
}
```
| 参数名 | 说明 | 类型 | 必须 | 备注 |
| -------- | ------------ | ------ | ---- | ------------------------------------------------------------ |
| serialNo | 序列号 | string | 是 | 后台或应用给设备发送消息必须传递唯一的序列号，不超过32位，设备收到消息后反馈结果的时候会使用同样序列号。反之亦然。 |
| uuid | 设备唯一标识 | string | 是 | 大于8位的字符串 |
| data | 消息数据正文 | object | 是 | 为json格式，不同类型的消息正文格式不一样，接口列表中主要是详细列出这部分数据格式 |
| time | 时间戳 | long | 是 | 10位长度时间戳，单位秒 |
| sign | 消息签名 | string | 否 | 如果签名启动，这个值必须有，验证数据的合法性。签名的规则请参考：附录-[签名算法](#sign) |
| code | 结果码 | string | 否 | 返回的数据必须包含 code ，不同的 code 表示不同的结果标识。结果码的基本规则请参考：附录-[结果码](#code) |

>注：要求消息内容中的每一项内容命名，都用小写字母开头，后面可以大小写结合；

# 二. 指令类接口列表

## 配置查询
- 说明： 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}/getConfig `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：
 - data 可以为空，或者不传这个部分，这个时候设备将返回所有配置数据
 - data 可以为string，因为配置数据是 kye/value 对应的 json 格式的对象，所以如果传入一个指定的 key，就可以返回设备里这个 key 对应的 value。

- 请求示例
```json
//获取所有数据
{
    "serialNo": "6w8keif5g6",
    "uuid": "1b89e112c70940f0",
    "time": 1647580466,
    "data": "",
    "sign": ""
}

//获取网络相关数据
{
    "serialNo": "6w8keif5g6",
    "uuid": "1b89e112c70940f0",
    "time": 1647580466,
    "data": "netInfo",
    "sign": ""
}

//查询子设备配置信息
{
    "serialNo": "6w8keif5g6",
    "uuid": "1b89e112c70940f0",
    "time": 1647580466,
    "data": "childInfo",
    "sign": ""
}
```

- 说明: 
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/getConfig_reply  `**
- 内容：[标准格式](#content)
- data 部分：json 格式，key/value 对应很多属性。详情参考[附件:配置数据详情](#configs)
  主要分以下几个大类：
    - `sysInfo`: 设备系统资源信息，包括设备CPU、存储,设备基础信息，包括设备类型、版本、uuid 等等
    - `netInfo`: 设备网络相关信息，包括设备ip、wifi用户密码等等
    - `mqttInfo`: mqtt 服务端相关信息，包括服务的ip、端口等等
    - `doorInfo`:设备控制门相关的信息，包括开门时长等等
    - `childInfo`:设备子设备配置信息等等

- 返回示例：
```json
//比如应用平台发送查询 netInfo,返回示例
{
  "serialNo": "6w8keif5g6",
  "uuid": "1b89e112c70940f0",
  "code": "000000",
  "time": 1701061767,
  "sign": "",
  "message": "Success",
  "data": {
    "netInfo": {
      "type": 1,
      "dhcp": 1,
      "ip": "10.102.106.49",
      "gateway": "10.102.106.124",
      "dns": "10.102.106.124",
      "subnetMask": "255.255.255.0",
      "netMac": "66:a7:71:22:c7:09",
      "ntp": 1,
      "ntpAddr": "182.92.12.11",
      "ntpInterval": 43200,
      "ntpTimeout": 5,
      "ntpHour": 23
    }
  }
}

//查询childInfo,返回示例
{
  "serialNo": "6w8keif5g6",
  "uuid": "1b89e112c70940f0",
  "code": "000000",
  "time": 1701061808,
  "sign": "",
  "message": "Success",
  "data": {
    "childInfo": [
      {
        "index": "01",
        "deviceId": "",
        "config": "",
        "version": ""
      },
      {
        "index": "02",
        "deviceId": "",
        "config": "",
        "version": ""
      },
      {
        "index": "04",
        "deviceId": "",
        "config": "{postfix=\"\",wled=0,com_passwd=\"1234567887654321\",haddr=\"http://192.168.1.1:8080\",ascan=1,nfc_sak28=0,nfc_identity_card_enable=1,tkey_light_en=2,nfc_m1_blk0s=\"\",nnl=0,rs485_timeout=864000,blpos=\"\",p_uart2=\"115200-8-N-1\",nfc_f_braud=8,nfc_otag=0,rs485_poll_timeout=10,ledd=200,st=1,nfc_card_protocol=1,horc=1,language=0,userid=\"userid\",prefix=\"\",backlight=100,owifi=1,app_version=\"m20_v11_v3.1.0.6.lhjy.12\",era_uboot=0,nfc=1,update_flg=0,blcr=0,nochannel=2,update_reboot=0,ft=0,anfc=1,sector_switch=0,idord=0,devnum=0,nfc_f_reqcode=0,update_haddr=\"unset\",blnl=0,uuid=\"1b89e1322afe40d0\",reboot=0,awifi_s=2,devname=\"苏州酷豆物联\",chorc=1,touttime=2,w_mode=2,brightness=0,keycpt=\"D5932817FABD\",head2=170,port=8080,wiegand_busy_delay=50,blochannel=2,beepd=30,len=5,update_md5=\"unset\",key_type=96,volctl=1,houttime=2,heart_data=\"www.vguang.cn\",heart_time=60,p_uart1=\"115200-8-N-1\",head1=85,ndchannel=64,devmac=\"1b89e1322afe40d0\",blpri=\"\",auto_report=129,nfc_timeout_ms=200,nfc_14443p4_enable=0,psam_wmode=1,nfc_version=\"\",uuid_sta=\"unset\",nfc_m1_sec0_key=\"ffffffffffff\",pos=\"\",heart_en=1,nfc_afi_enable=0,keyb=\"ffffffffffff\",blhorc=1,blk_num=8,nfc_work_mode=1,tkey_interval_s=60,ord=0,blft=0,eth=1,wifipra=\"\",keya=\"ffffffffffff\",nft=0,ochannel=2,check_m1=0,bldchannel=64,cr=0,pri=\"\",nfc_card_braud_tx=1,boot_music=0,nfc_f_scode=65535,wiegand_free_delay=100,rs485_id=1,rs485_key=\"UnQkvNpXMq5yVy7D\",psam_en=0,nfc_card_braud_rx=1,rs485_ver=7,taddr=\"192.168.1.1\",vg=1,rs485_sn=\"abcdefgh\",online_id_format=1,awifi_f=4,nft_add_zero=1,dchannel=64,relayd=1000,nfc_afi=0,nl=0,ncr=0}",
        "version": "m20_v11_v3.1.0.6.lhjy.12"
      },
      {
        "index": "08",
        "deviceId": "",
        "config": "",
        "version": ""
      }
    ]
  }
}
```
- 特殊结果码

| 类型     | code   | 信息             | 说明                             |
| -------- | ------ | ---------------- | -------------------------------- |
| 参数异常 | 200000 | 未找到对应的数据 | 传递的参数可能写错了，注意大小写 |

[回到顶部](#category)

## 配置修改
- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}/setConfig `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：
 - data 可以为空，或者不传这个部分，这个时候设备不会做任何配置修改
 - data 可以为 json 格式对象，传入一个指定的 key 和 value，就可以修改设备里这个 key 对应的 value。支持最多2级，比如 `key1.key2`, 表示设置 `key1` 对应的数据对象，再在这个对象里找到 `key2`对应的value。详情参考[附件:配置数据详情](#configs)，里面有部分数据不允许修改

- 请求示例
```json
//修改网络相关数据下的 ip 地址
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466,
    "data": {
        "netInfo": {
            "ip": "192.168 .32 .23"
        }
    },
    "sign": ""
}

//子设备配置
{
	"serialNo": "6w8keif5g6",
	"uuid": "0a1b2c3d",
	"time": 1647580466,
	"data": {
		"childInfo": [{
			"deviceId": "123",
			"config": "___VBAR_CONFIG_V1.1.0___{devname=\"abc\"}--r/tPDmEg1fLBS3FWBoxX1A=="
		},
		{
			"deviceId": "456",
			"config": "___VBAR_CONFIG_V1.1.0___{devname=\"abc\"}--r/tPDmEg1fLBS3FWBoxX1A=="
		}]
	},
	"sign": ""
}
```

- 流向：设备 -> 平台
- 说明: 
- Topic：**` access_device/v1/cmd/setConfig_reply  `**
- 内容：[标准格式](#content)
- data 部分：为空

- 返回示例：
```
//比如应用平台发送查询 netInfo.ip,返回示例
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466,
    "code": "000000",
    "sign": ""
}
```
- 特殊结果码

| 类型     | code   | 信息                   | 说明                                                         |
| -------- | ------ | ---------------------- | ------------------------------------------------------------ |
| 参数异常 | 20000  | 未找到对应的数据       | 传递的参数可能写错了，注意大小写                             |
| 参数异常 | 200001 | 要修改的数据格式不正确 | 比如应该是 String 类型的，但是传递了 int 类型；只能是0/1二种值，但是传递了2 |
| 参数异常 | 200002 | 刷新设备配置失败       | 传递的参数可能写错了，注意大小写                             |
| 其他异常 | 300000 | 这个值不允许修改       | -                                                            |

[回到顶部](#category)

## 查询权限
- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}/getPermission `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：

| 参数名 | 说明     | 类型   | 必须 | 备注                                |
| :----- | :------- | :----- | ---- | ----------------------------------- |
| size   | 每页数量 | Int    | 是   | 每页数量，最大 200(人脸类型只限1条) |
| page   | 页码     | Int    | 是   | 第几页，从0开始                     |
| code   | 凭证号   | String | 否   | 凭证号                              |
| type   | 凭证类型 | Int    | 否   | 参考[附录-设备状态码表](#typeDetails)-type列 |
| id     | 权限id   | String | 否   | -                                   |

- 请求示例
```json
//查询所有权限
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "page": 0,
        "size": 200
    },
    "time": 1647580466,
    "sign": ""
}
//按code和type查询
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "page": 0,
        "size": 200,
        "code": "2kifk39k40",
        "type": 0
    },
    "time": 1647580466,
    "sign": ""
}
//按id查询，虽然最多只有一条记录，为了统一，size和page也加上
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "page": 0,
        "size": 200,
        "id": "2kifk39k40"
    },
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/getPermission_reply  `**
- 内容：[标准格式](#content)
- data 部分：json 对象格式

| 参数名    | 说明               | 类型   | 必须 | 备注                                                         |
| --------- | ------------------ | ------ | ---- | ------------------------------------------------------------ |
| page      | 当前页             | Int    | 是   | 当前页（0开始）                                              |
| size      | 每页大小           | Int    | 是   | 当前页大小                                                   |
| total     | 总数               | Int    | 是   | 白名单总数                                                   |
| totalPage | 总页数             | Int    | 是   | 总页数                                                       |
| count     | 当前页实际白名单数 | Int    | 是   | 当前页实际白名单数                                           |
| content   | 权限列表           | Array  | 是   | 权限列表  |
|  id     | 权限Id             | String | 是   | 权限的唯一标识，添加和删除时根据这个标识来判定，建议传32位随机值 |
|  type   | 权限类型           | Int | 是   | 参考[附录-设备状态码表](#typeDetails)-type列 |
| code    | 权限值             | String | 是   | 通行权限值   |
| index    | 门控编号             | String | 是   | 参考[附录-门控权限映射格式](#controlDetails)门控编号，对应bit为1有效  |
| extra   | 额外参数           | Object | 否   | 其他额外属性，比如人员名称等 |
| time    | 时间区间           | Object | 是   | [查看时间区间](#timeInterval) |

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "data": {
        "content": [{
            "id": "20190101120101",
            "type": 101,
            "code": "001002",
            "index" : "08",
            "extra": {
            },
            "time": {
                "type": 0
            }
        }],
        "page": 1,
        "size": 20,
        "total": 100,
        "totalPage": 5,
        "count": 20
    },
    "time": 1647580466,
    "sign": ""
}

```
- 特殊结果码

| 类型     | code   | 信息                | 说明                             |
| -------- | ------ | ------------------- | -------------------------------- |
| 参数异常 | 200000 | 未找到对应的数据    | 传递的参数可能写错了，注意大小写 |
| 参数异常 | 200001 | 超出页数或页数小于0 | 超出页数限制或页数小于0          |
| 参数异常 | 200002 | 超出每页最大限额    | 超出200，如果是人脸则超出1       |

[回到顶部](#category)

## 添加权限
- 流向：平台 -> 设备
- 说明: 
- Topic：**` access_device/v1/cmd/{#uuid}/insertPermission `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json array 数组对象，每个元素的参数如下：

| 参数名 | 必填       | 类型   | 说明 | 备注                                                         |
| :----- | :--------- | :----- | ---- | ------------------------------------------------------------ |
| id    | 权限Id             | String | 是   | 权限的唯一标识，添加和删除时根据这个标识来判定，建议传32位随机值 |
| type  | 权限类型           | Int    | 是   | 参考[附录-设备状态码表](#typeDetails)-type列 |
| code  | 权限值             | String | 是   | 通行权限值   |
| index | 门控编号             | String | 是  | 参考[附录-门控权限映射格式](#controlDetails)门控编号，对应bit为1有效  |
| extra | 额外参数           | Object | 否   | 其他额外属性，比如人员名称等 |
| time  | 时间区间           | Object | 是   | [查看时间区间](#timeInterval)                                |

- 请求示例
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": [{
            "id": "20190101120101",
            "type": 101,
            "code": "001002",
      			"index": "08",
            "extra": {
            },
            "time": {
                "type": 0
            }
        },
        {
            "id": "20190101120102",
            "type": 103,
            "code": "003004",
          	"index": "01",
            "extra": {
            },
            "time": {
                "type": 0
            }
        }
    ],
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 要么都成功，要么全部失败，不会部分成功,如果插入的权限在设备里已经存在（id一样），则会忽略，但是还是返回成功
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/insertPermission_reply  `**
- 内容：[标准格式](#content)
- data 部分：json array 数组对象，每个元素都是成功插入的权限id

- 返回示例：
```
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "data": ["20190101120101","20190101120102"],
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码

| 类型                  | code   | 信息                   | 说明                   |
| --------------------- | ------ | ---------------------- | ---------------------- |
| 参数异常              | 20000  | 缺少必须要有的参数     | 缺少必须要有的参数     |
| 参数异常              | 200001 | 权限不能为空           | 权限不能为空           |
| 参数异常              | 200002 | 权限数量大于特定的数量 | 权限数量大于特定的数量 |
| 空间不足              | 200003 | 设备磁盘空间不足       | 设备磁盘空间不足       |
| 数据库异常            | 200004 | 数据库错误             | 数据库错误             |
| [回到顶部](#category) |        |                        |                        |

## 删除权限
- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}/delPermission `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json array 数组对象，每个元素都是权限id：

- 请求示例
```json
//删除权限
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": ["20190101120101","20190101120102"],
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 要么都成功，要么全部失败，不会部分成功,如果删除的权限在设备里没有存在，则会忽略，但是还是返回成功
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/delPermission_reply  `**
- 内容：[标准格式](#content)
- data 部分：json array 数组对象，每个元素都是成功删除的权限id

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "data": ["20190101120101","20190101120102"],
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码

| 类型     | code  | 信息               | 说明               |
| -------- | ----- | ------------------ | ------------------ |
| 参数异常 | 20000 | 缺少必须要有的参数 | 缺少必须要有的参数 |

[回到顶部](#category)

## 清空权限
- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}/clearPermission `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：无

- 请求示例
```json
//清空权限
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 不会返回失败
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/clearPermission_reply  `**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```

[回到顶部](#category)

## 查询密钥
- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}/getSecurity `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：

| 参数名 | 说明     | 类型   | 必须 | 备注                                |
| :----- | :------- | :----- | ---- | ----------------------------------- |
| size   | 每页数量 | Int    | 是   | 每页数量，最大 20 |
| page   | 页码     | Int    | 是   | 第几页，从0开始                     |
| key   | 密钥key值   | String | 否   | 凭证号                              |
| type   | 密钥类型 | String    | 否   | RSA之类的 |
| id     | 密钥id   | String | 否   | -                                   |

- 请求示例
```json
//查询所有密钥
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "page": 0,
        "size": 20
    },
    "time": 1647580466,
    "sign": ""
}
//按key和type查询
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "page": 0,
        "size": 20,
        "key": "vguang",
        "type": "RSA"
    },
    "time": 1647580466,
    "sign": ""
}
//按id查询，虽然最多只有一条记录，为了统一，size和page也加上
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "page": 0,
        "size": 20,
        "id": "2kifk39k40"
    },
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/getSecurity_reply  `**
- 内容：[标准格式](#content)
- data 部分：json 对象格式

| 参数名    | 说明               | 类型   | 必须 | 备注                                                         |
| --------- | ------------------ | ------ | ---- | ------------------------------------------------------------ |
| page      | 当前页             | Int    | 是   | 当前页（0开始）                                              |
| size      | 每页大小           | Int    | 是   | 当前页大小                                                   |
| total     | 总数               | Int    | 是   | 白名单总数                                                   |
| totalPage | 总页数             | Int    | 是   | 总页数                                                       |
| count     | 当前页实际白名单数 | Int    | 是   | 当前页实际白名单数                                           |
| content   | 权限列表           | Array  | 是   | 权限列表  |
|  id     | 权限Id             | String | 是   | 密钥的唯一标识|
|  type   | 密钥类型           | String | 是   | RSA之类的 |
| key    | 密钥key值            | String | 是   |  -  |
| value    | 密钥值             | String | 否   | 安全性考虑，密钥值不允许直接查出原始值 |
| startTime   | 开始时间           | Long | 否   | 时间戳（秒） |
| endTime    | 过期时间           | Long | 否   |时间戳（秒）|

- 返回示例：
```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "0a1b2c3d",
	"code": "000000",
	"data": {
		"content": [{
			"type": "RSA",
			"id": "213v",
			"key": "vguang",
			"value": "",
			"startTime": 1560303425,
			"endTime": 1683918932
		}],
		"page": 1,
		"size": 20,
		"total": 100,
		"totalPage": 5,
		"count": 20
	},
	"time": 1647580466,
	"sign": ""
}

```
- 特殊结果码

| 类型     | code   | 信息                | 说明                             |
| -------- | ------ | ------------------- | -------------------------------- |
| 参数异常 | 200000 | 未找到对应的数据    | 传递的参数可能写错了，注意大小写 |
| 参数异常 | 200001 | 超出页数或页数小于0 | 超出页数限制或页数小于0          |
| 参数异常 | 200002 | 超出每页最大限额    | 超出200，如果是人脸则超出1       |

[回到顶部](#category)

## 添加密钥
- 流向：平台 -> 设备
- 说明: 不支持更新密钥，可以删除密钥后再添加来实现更新
- Topic：**` access_device/v1/cmd/{#uuid}/insertSecurity `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json array 数组对象，每个元素的参数如下：

| 参数名 | 必填       | 类型   | 说明 | 备注                                                         |
| :----- | :--------- | :----- | ---- | ------------------------------------------------------------ |
|id     | 权限Id             | String | 是   | 密钥的唯一标识|
| type   | 密钥类型           | String | 是   | RSA之类的 |
|key    | 密钥key值            | String | 是   |  -  |
| value    | 密钥值             | String | 否   | - |
| startTime   | 开始时间           | Long | 否   | 时间戳（秒） |
| endTime    | 过期时间           | Long | 否   |时间戳（秒）  |

- 请求示例
```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "0a1b2c3d",
	"data": [{
			"type": "RSA",
			"id": "213v",
			"key": "vguang",
			"value": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
			"startTime": 1560303425,
			"endTime": 1683918932
		},
		{
			"type": "RSA",
			"id": "213t",
			"key": "test",
			"value": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
			"startTime": 1560303425,
			"endTime": 1683918932
		}
	],
	"time": 1647580466,
	"sign": ""
}
```

- 说明: 要么都成功，要么全部失败，不会部分成功,如果插入的密钥在设备里已经存在（id一样），则会忽略，但是还是返回成功
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/insertSecurity_reply  `**
- 内容：[标准格式](#content)
- data 部分：json array 数组对象，每个元素都是成功插入的密钥id

- 返回示例：
``` json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "data": ["213v","213t"],
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码

| 类型                  | code   | 信息                   | 说明                   |
| --------------------- | ------ | ---------------------- | ---------------------- |
| 参数异常              | 20000  | 缺少必须要有的参数     | 缺少必须要有的参数     |
| 参数异常              | 200001 | 密钥不能为空           | 密钥不能为空           |
| 参数异常              | 200002 | 密钥数量大于特定的数量 | 密钥数量大于特定的数量 |
| 空间不足              | 200003 | 设备磁盘空间不足       | 设备磁盘空间不足       |
| 数据库异常            | 200004 | 数据库错误             | 数据库错误             |
| [回到顶部](#category) |        |                        |                        |

## 删除密钥
- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}/delSecurity `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json array 数组对象，每个元素都是权限id：

- 请求示例
```json
//删除权限
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": ["213v","213t"],
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 要么都成功，要么全部失败，不会部分成功,如果删除的权限在设备里没有存在，则会忽略，但是还是返回成功
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/delSecurity_reply  `**
- 内容：[标准格式](#content)
- data 部分：json array 数组对象，每个元素都是成功删除的权限id

- 返回示例：
```json
{,
    "uuid": "0a1b2c3d",
    "code": "000000",
    "data": ["213v","213t"],
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码

| 类型     | code  | 信息               | 说明               |
| -------- | ----- | ------------------ | ------------------ |
| 参数异常 | 20000 | 缺少必须要有的参数 | 缺少必须要有的参数 |

[回到顶部](#category)

## 清空密钥
- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}/clearSecurity `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：无

- 请求示例
```json
//清空权限
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 不会返回失败
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/clearSecurity_reply  `**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```

[回到顶部](#category)

## 添加人脸（暂未实现）
- 流向：平台 -> 设备
- 说明: 把人脸照片下发到设备上，和code绑定在一起，如果下发多个照片，code一样的话会覆盖旧的照片,每次只能注册一个人脸
- Topic：**` access_device/v1/cmd/{#uuid}/insertFace `**
- 内容：[标准格式](#content)

| 参数名 | 必填       | 类型   | 说明 | 备注                                                         |
| :----- | :--------- | :----- | ---- | ------------------------------------------------------------ |
|code    | 人员的id标识             | String | 是   | 人员的唯一id标识|  
|data    | 人脸base64或特征值             | String | 是   |人脸base64或特征值 | 
|index    | 门控编号             | String | 是   | 参考[附录-门控权限映射格式](#controlDetails)门控编号，对应bit为1有效  |
|extra   | 额外参数           | Object | 否   | 其他额外属性，比如人员名称等 |

- 请求示例
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": [{
            "code": "20190101120101",
            "data": "ZnNmZHNmYXNkZmFzZGY=........",
      			"index":"08",	
            "extra": {
            	"name": "王二"
            }
        },
        {
            "code": "20190101120102",
            "data": "ZnNmZHNmYXffemFzZGY=........",
          	"index":"01",	
            "extra": {
            	"name": "张三"
            }
        }
    ],
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/insertFace_reply  `**
- 内容：[标准格式](#content)

- 返回示例：
```
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码

| 类型                  | code   | 信息                   | 说明                   |
| --------------------- | ------ | ---------------------- | ---------------------- |
| 参数异常              | 20000  | 缺少必须要有的参数     | 缺少必须要有的参数     |
| 空间不足              | 200003 | 设备磁盘空间不足       | 设备磁盘空间不足       |
| 数据库异常            | 200004 | 数据库错误             | 数据库错误             |
| [回到顶部](#category) |        |                        |                        |

## 删除人脸（暂未实现）
- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}/delFace `**
- 内容：[标准格式](#content)

- 请求示例
```json
//删除权限
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "20190101120101",
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/delFace_reply  `**
- 内容：[标准格式](#content)

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码

| 类型     | code  | 信息               | 说明               |
| -------- | ----- | ------------------ | ------------------ |
| 参数异常 | 20000 | 缺少必须要有的参数 | 缺少必须要有的参数 |

[回到顶部](#category)

## 清空人脸（暂未实现）
- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}/clearFace `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：无

- 请求示例
```json
//清空权限
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 不会返回失败
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/clearFace_reply  `**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```

[回到顶部](#category)

## 远程控制
- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}/control `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json object 对象，参数如下：

| 参数名 | 说明 | 类型 | 必须 | 备注 |
| :------ | :--- | :--- | ---- | ------------------------------------------------------- |
| command | 命令 | Int | 是 | 0：重启 1：远程开门/直达楼层 2：设备启用 3：设备禁用 4：设备重置 5:设备提示（UI/语音）6:统一控制|
|index | 门控编号 | String | 是 | 当`command=1`时，此字段必传，参考[附录-门控权限映射格式](#controlDetails)门控编号，对应bit为1有效 |
当`command=5`时 `extra`字段必填 json 支持字段如下表
| 参数名 | 说 明 | 类 型 | 必 须 | 备 注 |
| :----------: | :-----------: | :------: | :----: | :---------------------------|
| msg | 提示信息 | String | 否 | 当设备支持UI时将弹窗显示此信息 |
| msgTimeout | 提示时间 | Int | 否 | 单位:`ms`，当设备支持UI时，UI显示`msg`的时间 此项不存在默认显示时间:`1500ms` |
| wavFileName | 音频文件名 | String | 否 | 此项不存在播放默认语音 此项存在则播放对应名称的语音 如`"wavFileName":"9"`则播放`9.wav` 注：若此项存在需关闭网络传输行为中的`播报语音` |
当控制梯控版的时候：
`command=1`中的index字段为楼层数；
`command=6`中extra字段中的action字段为必填项，0为关闭、1为开启。
- 请求示例
```json
//远程重启
{
 "serialNo": "6w8keif5g6",
 "uuid": "0a1b2c3d",
 "data": {
 "command": 0,
 "extra":{}
 },
 "time": 1647580466,
 "sign": ""
}
//远程开门
{
 "serialNo": "6w8keif5g6",
 "uuid": "0a1b2c3d",
 "data": {
 	"command": 1,
 	"index":"0F",//开启所有门
 	"extra":{}
 },
 "time": 1647580466,
 "sign": ""
}

/*以下是梯控板*/
//直达楼层
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
      	"command": 1,
      	"index": "0000040000"//19楼
    },
    "time": 1647580466,
    "sign": ""
}
//统一控制
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
      	"command": 6,
      	"extra":{
          "action": 1
        }
    },
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/control_reply  `**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码

| 类型     | code   | 信息                | 说明               |
| -------- | ------ | ------------------- | ------------------ |
| 参数异常 | 200000 | 缺少必须要有的参数  | 缺少必须要有的参数 |
| 参数异常 | 200001 | 不支持的 command 值 | command 值错误     |
| 执行异常 | 200002 | 指令执行失败        | 执行失败           |

[回到顶部](#category)

## 升级固件
- 说明: 设备收到升级固件后，先下载固件文件，下载成功后返回结果给应用平台，然后重启
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}/upgradeFirmware `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json object 对象，参数如下：

| 参数名 | 说明                     | 类型   | 必须 | 备注                                                         |
| :----- | :----------------------- | :----- | ---- | ------------------------------------------------------------ |
| type   | 升级包类型               | Int    | 是   | type值强校验  0：本机升级  1：下位机升级  2:电梯升级
| url    | 升级包下载地址，http地址 | String | 是   | 调用接口时访问该url，若url 能访问到，则设备开始执行下载文件；若 url 访问失败，则接口返回失败 |
| md5    | 升级包MD5值              | String | 是   | 升级包进行MD5验证 |
| extra   | 额外参数 | Object | 否 | 下位机升级时需要的额外信息 |
| deviceIndex | 下挂设备升级信息 | String  | 否 | 给下位机升级必传,属于extra对象，要升级的设备编号，对应bit为1有效，及01为485_0对应的设备，0f即为485_0,485_1,485_2,485_3的设备 |
| deviceModel  | 下挂设备型号    | String | 否  | 给下位机升级必传,属于extra对象，下位机升级校验使用 |
| deviceVersion  | 下挂设备版本    | String | 否  | 给下位机升级必传,属于extra对象，下位机当前版本，下位机升级校验使用 |

- 请求示例
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "type": 0,
        "url": "http://host/aio.tar.xz",
        "md5": "521c2bdc835d4f13b5f9d6db164f0881"
    },
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 这里只是下载升级包成功或失败，通常下载升级包后会重启，重启后才能知道是否升级真正成功
- 流向：设备 -> 平台
- Topic：**` access_device/v1/cmd/upgradeFirmware_reply  `**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码

| 类型     | code   | 信息                              | 说明                       |
| -------- | ------ | --------------------------------- | -------------------------- |
| 参数异常 | 200000 | 缺少必须要有的参数                | 缺少必须要有的参数         |
| 参数异常 | 200001 | 对应的固件下载地址下载不了        | 对应的固件下载地址下载不了 |
| 参数异常 | 200002 | 对应的固件下载后对应的md5校验失败 | md5校验失败                |
| 参数异常 | 200003 | 无对应设备                        | 升级的设备不存在           |

[回到顶部](#category)

# 三. 事件类接口列表

## 连接上报

- 说明: 只上报一次
- 流向：设备 -> 平台
- Topic：**` access_device/v1/event/connect `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json object 对象，参数如下：

| 参数名     | 说明               | 类型   | 必须 | 备注              |
| :--------- | :----------------- | :----- | ---- | ----------------- |
| sysVersion | 系统版本号         | String | 否   | 系统版本号        |
| appVersion | 应用版本号         | String | 否   | 应用版本号        |
| createTime | 应用发布日期       | Long   | 否   | 应用发布日期      |
| btMac       | 蓝牙MAC地址     | String | 是   | 蓝牙MAC地址   |
| mac       | 设备硬件唯一标识    | String | 否   | 设备硬件唯一标识   |
| clientId     | 客户端id，与设备地址一致 | String | 是     | 客户端id |
| name       | 设备名称          | String | 是   | 设备名称          |
| type        | 网络类型         | Int    | 是     | 网络类型(1:以太网 2:wifi) |
| ssid        | Wifi名           | String | 是     | wifi名                    |
| pwd         | Wifi密码         | String | 是     | wifi密码                  |
| dhcp        | 是否为DHCP模式   | Int    | 是     | 是否为DHCP(1:动态,0:静态) |
| ip          | ip地址           | String | 是     | ip地址                    |
| gateway     | 网关             | String | 是     | 网关                      |
| dns         | DNS服务器        | String | 是     | DNS服务器                 |
| subnetMask  | 子网掩码         | String | 是     | 子网掩码                  |
| netMac  		| 网卡mac         | String | 是     | 网卡mac                  |

- 请求示例
```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "0a1b2c3d",
	"data": {
		"sysVersion": "v1.0.3.4050",
		"appVersion": "v3.204.234.5",
		"createTime": 1647550466,
		"uuid": "0a1b2c3d",
		"name": "#12-B01",
		"model":"cc104"
	},
	"time": 1647580466,
	"sign": ""
}
```

- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/event/{#uuid}/connect_reply  `**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "0a1b2c3d",
	"code": "000000",
	"time": 1647580466,
	"sign": ""
}
```

[回到顶部](#category)

## 告警上报

- 说明: 告警有很多类型，并不是所有设备都支持所有类型
- 流向：设备 -> 平台
- Topic：**` access_device/v1/event/alarm `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json object 对象，参数如下：

| 参数名 | 说明     | 类型   | 必须 | 备注                                                         |
| :----- | :------- | :----- | ---- | ------------------------------------------------------------ |
| type   | 状态类型 | Int    | 是   | 参考[附录-设备状态码表](#alarmDetails)-type列                |
| value  | 状态值   | String | 否   | 参考[附录-设备状态码表](#alarmDetails)，如果是"无"，就不需要传值 |
| extra   | 额外参数 | Object | 否 | 额外信息 |
| index   | 门控编号 | String | 否 | 门磁、开门时上传，参考[附录-门控权限映射格式](#controlDetails)门控编号，对应bit为1有效  |
| devName | 设备名称 | String | 否 | 控制板的设备名称 |
| deviceId | 子设备标识 | String | 否 | 当前刷配置卡的设备的，子设备标识 |
| deviceUuid | 子设备uuid | String | 否 | 当前刷配置卡的设备的，子设备uuid |
| deviceVersion | 子设备版本 | String | 否 | 当前刷配置卡的设备的，子设备版本号 |

- 请求示例
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "type": 1,
        "value": "1",
      	"index":"08",
        "extra": {
        }
    },
    "time": 1647580466,
    "sign": ""
}

{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "type": 202,
      	"index":"08",
        "extra": {
          "devName": "abc",
					"deviceId": "123abc",
          "deviceUuid": "123456abc",
          "deviceVersion": "m20_v3.1.0.1"
        }
    },
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/event/{#uuid}/alarm_reply  `**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```

[回到顶部](#category)

## 通行上报

- 说明: 
- 流向：设备 -> 平台
- Topic：**` access_device/v1/event/access `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json array 数组对象，参数如下：

| 参数名 | 说明     | 类型   | 必须 | 备注                                                         |
| :----- | :------- | :----- | ---- | ------------------------------------------------------------ |
| id     | 权限id   | String | 是   | 如果权限存在设备的白名单就返回对应的权限id，不存在就返回"-1" |
| code   | 权限凭证 | String | 是   | 如果是人脸则为人脸唯一id|
| type   | 权限类型           | Int | 是   | 参考[附录-设备状态码表](#typeDetails)-type列 |
| index  | 门控编号  | String | 是   | 参考[附录-门控权限映射格式](#controlDetails)门控编号，对应bit为1有效  |
| time   | 通行时间 | Long   | 是   | 时间戳单位秒   |
| result | 通行结果 | Int    | 是   | 1表示通过 0表示未通过  |
| error | 失败原因 | String    | 否   | 失败原因码或具体原因  |
| extra  | 额外参数 | Object | 否   | 其他额外属性，比如人员名称等，如果通行失败，记录原始数据，比如二维码的原始值:```{"srcData":"1234567890"}```  |
| index | 门控编号 | String | 是   | 参考[附录-门控权限映射格式](#controlDetails)门控编号，对应bit为1有效  |
| deviceId | 子设备标识 | String | 否   | 上报二维码的子设备标识 |
- 请求示例
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": [{
        "id": "20190101120101",
        "code":"s345463434gg",
        "type": 101,
        "time": 1640917147,
        "result": 0,
      	"index":"01",	
        "extra": {
          "deviceId":"123abc"
        }
    }],
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/event/{#uuid}/access_reply  `**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```

[回到顶部](#category)

## 在线验证

- 说明: 
- 流向：设备 -> 平台
- Topic：**` access_device/v1/event/access_online `**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json 对象，参数如下：

| 参数名 | 说明     | 类型   | 必须 | 备注                                   |
| :----- | :------- | :----- | ---- | -------------------------------------- |
| code   | 权限凭证 | String | 是   | 如果是人脸则为空                       |
| type   | 权限类型           | Int | 是   | 参考[附录-设备状态码表](#typeDetails)-type列 |
| index  | 数据来源 | String | 是 | 参考[附录-门控权限映射格式](#controlDetails)数据来源，标志来自哪个扫码器或者刷卡器上报，对应bit为1有效 |
| time   | 通行时间 | Long   | 是   | 时间戳单位秒                           |
| extra  | 额外参数 | Object | 否   | 可扩展，通常是记录原始数据，比如扫二维码的原文 |
| srcData | 原始数据 | String | 否   | 如扫二维码的原文或者刷卡数据 |
| deviceId | 子设备标识 | String | 否   | 上报二维码的子设备标识 |

- 请求示例
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "data": {
        "code":"s345463434gg",
        "type": 103,
        "time": 1640917147，
      	"index":"01",
        "extra":{
      		"srcData":"vg://v103AQAGAHZndWFuZwIAQAAlcOsQMXN9TJGCK5Afs14p4orxE+QnmI4gb2F85pvrvbQW1/+CyPEE1Bi3X4T3SYFZRoheykjICfdwWU+kw/Vf2965",
      		"deviceId":"123abc"
    		} 		
    },
    "time": 1647580466,
    "sign": ""
}
```

- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/event/{#uuid}/access_online_reply  `**
- 内容：[标准格式](#content)
- data 部分：无

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",//验证通过返回成功，否则返回300000
    "time": 1647580466,
    "sign": ""
}
```

[回到顶部](#category)

# 四. 附录
## 结果码
| 类型 | code | 信息 | 说明 |
| -------- | ------------- | ---------------------- | ---------------------------------------------------------- |
| 成功 | 000000 | 成功执行指令 | 无 |
| 通用报错 | 100000 | 未知错误 | 无 |
| 通用报错 | 100001 | 设备已被禁用 | 设备禁用后很多指令不允许执行 |
| 通用报错 | 100002 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进程中 |
| 通用报错 | 100003 | 签名检验失败 | 无 |
| 通用报错 | 100004 | 超时错误 | 无 |
| 通用报错 | 100005 | 设备离线 | 无 |
| 参数异常 | 200000-299999 | 参数异常 | 不同的指令对应不同的参数规范，参考每个接口后的参数异常描述 |
| 其它异常 | 300000-399999 | 其它已知原因导致的异常 | 不同的指令对应不同的异常，参考每个接口后的参数异常描述 |

[回到顶部](#category)

## 设备告警类型表
| 类型     | type | value                        | index         |
| -------- | ---- | ---------------------------- | ------------ |
| 门磁状态 | 0    | 0：门磁关、1：门磁开         | 对应门的序号 |
| 火警状态 | 1    | 0：火警关、1：火警开         | 无           |
| 非法开门 | 2    | 无                           | 对应门的序号     |
| 开门超时 | 3    | 无                           | 对应门的序号     |
| 关门超时 | 4    | 无                           | 对应门的序号     |
| 升级汇报 | 5    | 0：升级失败、1：升级成功完成 | 无           |
| 防拆报警 | 6    | 0：正常 1：拆除报警          | 无           |
| 配置上传码 | 100 | 配置字段table表 | |
| M1配置卡 | 202 | 无，设备信息放入到extra对象 | |

[回到顶部](#category)

## 权限类型说明

| type | num | 说明                        |
| -------- | ---- | ---------------------------- |
| face | 300 | 300:人脸数据 |
| qrcode  | 100、101、103 | 100：透传码,101：静态码 ,103：动态码|
| password | 400 |  400：密码数据 ，密码长度：6~10位|
| card | 200 | 200:普通卡号，201：cpu加密卡，202：扇区加密卡 |
| fingerprint |500 | 500：指纹数据  |
| bluetooth | 600 |  600:蓝牙开门凭证 |
| registrationPlate | 700 |  700:牌照 |
| openButton | 800 |  800:开门按钮 |

[回到顶部](#category)

## 时间区间

###### 支持下面四种时间区域设置：
- 1.缺省模式，不限时间，一直有效
```json
{
 "type": 0
}
```
- 2.通常模式，从开始到结束时间内有效
```json
{
 "type": 1,
 "range": {
 "beginTime": 1640917147,
 "endTime": 1690917147
 }
}
```
- 3.每日模式，每日特定时间到特定时间内有效(时间戳为当日零点到该时间的秒数)
```json
{
 "type": 2,
 "beginTime": 30600,
 "endTime": 66600,
 "range": {
 "beginTime": 1640917147,
 "endTime": 1690917147
 }
}
```
- 4.周重复模式，周一到周日特定时间到特定时间内有效，其它时间无效(每天的多组时间段不重叠，最多支持五组)。weekPeriodTime参数如下，每天的时间格式为："HH:MM-HH:MM"，24小时制时分，Eg："08:00-09:30|10:00-11:30"最多5个时间段。1~7至少有一天为必传,无此项代表无权限，"00:00-24:00"：代表全天有效，多个时间段用 | 分割中间不要有空格，每天最多5个时间段Eg:"08:00-09:30|10:00-11:30|12:00-13:30|15:00-16:30|17:00-18:30"
```json
{
 "type": 3,
 "weekPeriodTime":{
 "1":"9:00-10:00",
 "2":"12:00-13:30|15:00-16:30"
 },
 "range": {
 "beginTime": 1640917147,
 "endTime": 1690917147
 }
}
```
[回到顶部](#category)

## 配置项

- `netInfo` : 关于网络配置的信息体

| 参数名      | 说明             | 类型   | 可修改 | 备注                      |
| ----------- | ---------------- | ------ | ------ | ------------------------- |
| type        | 网络类型         | Int    | 是     | 网络类型(1:以太网 2:wifi 4:4G) |
| ssid        | Wifi名           | String | 是     | wifi名                    |
| pwd         | Wifi密码         | String | 是     | wifi密码                  |
| dhcp        | 是否为DHCP模式   | Int    | 是     | 是否为DHCP(1:动态,0:静态) |
| ip          | ip地址           | String | 是     | ip地址                    |
| gateway     | 网关             | String | 是     | 网关                      |
| dns         | DNS服务器        | String | 是     | DNS服务器                 |
| subnetMask  | 子网掩码         | String | 是     | 子网掩码                  |
| netMac  		| 网卡mac         | String | 是     | 网卡mac                  |
| ntp         | ntp使能         | Int    | 是     | 0：关闭 1：间隔同步 2：定时同步 |
| ntpAddr     | 网络时间服务器   | String | 是     | 网络时间服务器            |
| ntpInterval | 网络时间同步间隔 | Int    | 是     | 网络时间同步间隔,单位秒,对应ntp=1   |
| ntpHour 	  | 网络时间同步间隔 | Int    | 是     | 网络时间同步时间：0~23，对应ntp=2  |
| ntpTimeout  | 网络时间同步超时 | Int    | 是     | 网络时间同步超时,单位秒   |

- `mqttInfo` : 关于 mqtt 服务器配置的信息体

| 参数名       | 说明                     | 类型   | 可修改 | 备注                                    |
| ------------ | ------------------------ | ------ | ------ | --------------------------------------- |
| mqttAddr     | Mqtt服务器 ip            | String | 是     | Mqtt地址（ip:端口，当启用mqtts的单向或双向认证时，加入mqtts://或ssl://作为地址开始，例：ssl://192.168.10.1:8888）    |
| clientId     | 客户端id	 | String | 是     | 客户端id，默认与设备地址一致，传空```""``` 将恢复默认         |
| mqttName     | mqtt用户名               | String | 是     | mqtt用户名     |
| password     | mqtt密码                 | String | 是     | mqtt密码          |
| qos     		 | mqtt qos                | int 	| 是     	| mqtt qos 取值 0\1\2     |
| prefix     	 | mqtt主题前缀             | String 	| 是     	|mqtt主题前缀     |
| reporttimely | 上报模式                 | int    | 是     | 0:通行优先，1: 推送优先    |
| onlinecheck  | 在线验证    							| int    | 是     | 0:不在线验证，1：离线验证失败走在线验证 |
| timeout  		| 在线验证\推送优先的超时时间  | int    | 是     | 单位毫秒|
| mqtts  		| Mqtts是否启用  | int    | 是     | 0：不启用 1：启用ssl，双方不做认证 2：单向认证 3：双向认证 |

- `sysInfo` : 设备系统资源信息体

| 参数名 | 说明 | 类型 | 可修改 | 备注 |
| ---------------- | --------------- | ------ | -------------------------------- | ------------------------ |
| time | 时间 | Long | 是 | 时间 |
| appVersion | 应用版本号 | String | 否 | 应用版本号 |
| releaseTime | 应用发布日期 | Long | 否 | 应用发布日期 |
| mac | 设备硬件唯一标识 | String | 否 | 设备硬件唯一标识 | |
| deviceNum | 设备号 | Int | 是 | 设备号 |
| deviceName | 设备名称 | String | 是 | 设备名称 |
| model | 设备类型 | String | 否 | 设备类型 |
| status | 设备基本状态 | Int | 否 | 0-测试模式，1-正常，2-禁用， 3-火警报警|
| disk | 设备剩余空间 | Int | 否 | 设备剩余空间 单位是 kb |
| memory | 内存剩余空间 | Int | 否 | 内存剩余空间 单位是 kb |
| cpu | cpu 占用比率 | Int | 否 | CPU 占用比率 % |
| accessDevVersion | 外接设备版本号 | String | 否 | 外接设备版本号 |
| projectName| 项目名称 | String | 是 | 用于区分不同项目，只初始配置一次 |
| device0Id | 子设备标识 				| String | 否 | 子设备标识，用于区分子设备 |
| device1Id | 子设备标识 				| String | 否 | 子设备标识，用于区分子设备 |
| device2Id | 子设备标识 				| String | 否 | 子设备标识，用于区分子设备 |
| device3Id | 子设备标识 				| String | 否 | 子设备标识，用于区分子设备 |

- `doorInfo` : 设备开门相关配置信息 
  
| 参数名      | 说明                                                     | 类型 | 可修改 | 备注                                                     |
| ----------- | -------------------------------------------------------- | ---- | ------ | -------------------------------------------------------- |
| openMode    | 设备开门模式，0-正常，1-常开模式，2-常闭模式，3-测试模式 | Int  | 是     | 设备开门模式，0-正常，1-常开模式，2-常闭模式 |
| openTime1    | 门1开门时长，单位毫秒 | Int  | 是     | 开门时长，单位毫秒 |
| openTime2    | 门2开门时长，单位毫秒 | Int  | 是     | 开门时长，单位毫秒 |
| openTime3    | 门3开门时长，单位毫秒 | Int  | 是     | 开门时长，单位毫秒 | 
| openTime4    | 门4开门时长，单位毫秒 | Int  | 是     | 开门时长，单位毫秒 |
| outMode     | 继电器输出模式（指动作继电器是高有效还是低有效）  | Int  | 是     | 0 NO有效，1 NC有效 |
| openTimeout | 开门超时时间  | Int  | 是     | 开门时长，单位秒 |
| reporttimely | 上报模式  | int    | 是     | 0:通行优先，1: 推送优先    |
| onlinecheck  | 在线验证  | int    | 是     | 0:不在线验证，1：离线验证失败走在线验证 |
| timeout  		| 在线验证\推送优先的超时时间  | int    | 是     | 单位毫秒|
| relayCtrl | 继电器控制  | Int  | 是     | 0：单门单控 1：双门单控 |
| fireMode | 火警模式  | Int  | 是     | 0：断路上报 1：通路上报 |

- `childInfo` : 下控设备相关配置信息

|参数名|说明|类型|可修改|备注|
  |--|--|--|--|--|
  |index|子设备下标|String|否||
  |deviceId|子设备标识|String|否|子设备标识，用于区分子设备（配置config时此项必传）|
  |config|子设备配置|String|是|子设备配置字符串此项严格按照deviceId对应的设备配置|
  |version|子设备版本|String|否|子设备版本号|

## 门控权限映射格式

- `格式说明` : 数据的每一位表示对应的门

| 数据字节 | 字节位表示 | 字节对应门 |
| ---- | ---- | ---- | ---- | ---- |
| 1bit | 0：未生效，1：生效 | 1 |
| 2bit | 0：未生效，1：生效 | 2 |
| 3bit | 0：未生效，1：生效 | 3 |
| 4bit | 0：未生效，1：生效 | 4 |
 如：0x08 表示仅控制第四个门，0x0F表示可以控制所有门

- `uiInfo` : UI相关配置信息

| 参数名      | 说明                                                     | 类型 | 可修改 | 备注                                                     |
| ----------- | -------------------------------------------------------- | ---- | ------ | -------------------------------------------------------- |
| rotation    |  旋转方式 | Int  | 是     |0：横屏0度，1：90度，2:180度，3:270度      |
| statusBar   |  底部状态栏 | Int  | 否     |0：关闭底部状态栏，1：打开底部状态栏      |
| horBgImage     | 水平背景图                                          | Base64  | 是     |  水平背景图(图像格式仅支持PNG)                   |
| verBgImage     | 竖直背景图                                          | Base64  | 是     |  竖直背景图(图像格式仅支持PNG)                 |

- `bleInfo` : 蓝牙相关配置信息 （当前仅开放版支持）

| 参数名      | 说明                                                     | 类型 | 可修改 | 备注                                                     |
| ----------- | -------------------------------------------------------- | ---- | ------ | -------------------------------------------------------- |
| mac    |  mac地址 | String  | 是     | 6字节（如：d0000c05a6dc）     |
| name     | 蓝牙名称  | String  | 是     | （如：f2ecc32fdc）     |

- `liftInfo` : 梯控接口板相关配置信息

| 参数名      | 说明                                                     | 类型 | 可修改 | 备注                                                     |
| ----------- | -------------------------------------------------------- | ---- | ------ | -------------------------------------------------------- |
| openFloor    | 开放楼层 | String  | 是 | "0000000001"~"FFFFFFFFFF"("0000070000"(17、18、19层权限)) (暂时只支持最高40层)   |
| openTime     | 开放时间 | Int  | 是 | 1~255秒 默认是10s     |
| publicFloor  | 公共楼层 | String  | 是 | "0000000001"~"FFFFFFFFFF"(如"0000070000"(17、18、19层权限)) (暂时只支持最高40层) |
| saveConfig   | 保存配置 | Int  | 是 | 0(不保存)、1(保存)    |

[回到顶部](#category)