门禁标品MQTT协议文档（Android版本）

# 一、概述

## 应用场景
该文档用于通过MQTT协议建立和设备的网络通讯。

## 接口格式
**接口Topic**
   - 下行指令：`xxxx/cmd/{#uuid}/xxxx`
   - 上行回复：`xxxx/cmd/xxxx_reply`
   
   - 上行事件：`xxxx/event/yyyy`
   - 下行回复：`xxxx/event/{#uuid}/yyyy_reply`

**通用报文**
   - 参数描述
| 参数名   | 说明         | 类型   | 必须 | 备注                                                         |
| -------- | ------------ | ------ | ---- | ------------------------------------------------------------ |
| serialNo | 序列号       | string | 是   | 后台或应用给设备发送消息必须传递唯一的序列号，不超过32位，设备收到消息后反馈结果的时候会使用同样序列号。反之亦然。 |
| uuid     | 设备唯一标识 | string | 是   | 通常是6字符唯一标识                                              |
| data     | 消息数据正文 | object | 是   | 为json格式，不同类型的消息正文格式不一样，接口列表中主要是详细列出这部分数据格式 |
| time     | 时间戳       | long   | 是   | 10位长度时间戳，单位秒                                       |
| sign     | 消息签名     | string | 否   | 目前默认未开启签名认证 |
| code     | 结果码       | string | 否   | 返回的数据必须包含 code ，不同的 code 表示不同的结果标识。 |

- 发送示例：
    ```json
    {
        "serialNo": "6w8keif5g6",
        "uuid": "1118HD",
        "data": {
            不同接口使用不同参数，参照每个接口 `请求参数`
        },
        "time": 1647580466,
        "sign": "e0k4jrir85tje8ru4jrur499r99ii4ur"
    }
    ```
- 返回示例：
    ```json
    {
        "serialNo": "6w8keif5g6",
        "uuid": "1118HD",
        "code": "000000",
        "data": {
            不同接口使用不同参数，参照每个接口 `请求参数`
        },
        "time": 1647580466,
        "sign": "e0k4jrir85tje8ru4jrur499r99ii4ur"
    }
    ```

# 二、方法接口

## 配置查询
**请求**
- 流向：平台 -> 设备
- Topic：**20220814/cmd/{#uuid}/getConfig**
- 说明：data为空，返回所有配置数据，允许查询分组下的指定配置，支持最多2级。<br>查询指定配置，data传字符串，示例"data": "netInfo.ip"。<br>配置项列表参照属性列表。
- 请求参数

- 请求示例
```json

```

**返回**
- 流向：设备 -> 平台
- Topic：**20220814/cmd/getConfig_reply**
- 说明：key/value 对应很多属性。详情参考属性列表
- 返回参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| netInfo | 网络配置组 | object | 是 |  | 配置项列表参照属性列表。 |
| netInfo.ip | IP地址 | string | 是 | 192.168.1.101 | IP地址 |
| netInfo.dns | DNS地址 | string | 是 | 8.8.8.8 | DNS地址 |

- 返回示例
```json
{
    "netInfo": {
        "ip": "192.168.1.101",
        "dns": "8.8.8.8"
    }
}
```
        
## 配置修改
**请求**
- 流向：平台 -> 设备
- Topic：**20220814/cmd/{#uuid}/setConfig**
- 说明：无
- 请求参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| netInfo | 网络配置组 | object | 是 |  | 配置项列表参照属性列表。 |
| netInfo.ip | IP地址 | string | 是 | 192.168.1.101 | IP地址 |
| netInfo.dns | DNS地址 | string | 是 | 8.8.8.8 | DNS地址 |

- 请求示例
```json
{
    "netInfo": {
        "ip": "192.168.1.101",
        "dns": "8.8.8.8"
    }
}
```

**返回**
- 流向：设备 -> 平台
- Topic：**20220814/cmd/setConfig_reply**
- 说明：data为标准格式
- 返回参数

- 返回示例
```json

```
        
## 查询权限
**请求**
- 流向：平台 -> 设备
- Topic：**20220814/cmd/{#uuid}/getPermission**
- 说明：null
- 请求参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| size | 每页数量 | int | 是 | 10 | 每页数量，最大 200(人脸类型只限1条) |
| page | 页码 | int | 是 | 0 | 第几页，从0开始 |
| code | 凭证号 | string | 否 |  | 凭证号 |
| type | 凭证类型 | int | 否 | 103 | 目前支持100-透传二维码，101-静态二维码，103-动态二维码，202-卡，303-人脸，501-通行密码 |
| id | 权限id | string | 否 | 2kifk39k40 |  |

- 请求示例
```json
{
    "size": 10,
    "page": 0,
    "code": "",
    "type": 103,
    "id": "2kifk39k40"
}
```

**返回**
- 流向：设备 -> 平台
- Topic：**20220814/cmd/getPermission_reply**
- 说明：无
- 返回参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| page | 当前页 | int | 是 | 0 | 当前页（0开始） |
| size | 每页大小 | int | 是 | 10 | 当前页大小 |
| total | 总数 | int | 是 | 100 | 白名单总数 |
| totalPage | 总页数 | int | 是 | 10 | 总页数 |
| count | 当前页实际白名单数 | int | 是 | 5 | 当前页实际白名单数 |
| content | 权限列表 | array | 是 |  | 权限列表 |
| content.id | 权限Id | string | 是 | 2kifk39k40 | 权限的唯一标识，添加和删除时根据这个标识来判定，建议传32位随机值 |
| content.type | 权限类型 | int | 是 | 100 | 目前支持100-透传二维码，101-静态二维码，103-动态二维码，202-卡，303-人脸，501-通行密码 |
| content.code | 权限值 | string | 是 | abcd1234 | 权限类型为303时，这个值对应base64 |
| content.extra | 额外参数 | object | 否 | {} | 可扩展，人脸设备会传递人员名称等信息 |
| content.time | 时间区间 | object | 是 | {} | 查看附录 时间区间列表 |

- 返回示例
```json
{
    "page": 0,
    "size": 10,
    "total": 100,
    "totalPage": 10,
    "count": 5,
    "content": null
}
```
        
## 添加权限
**请求**
- 流向：平台 -> 设备
- Topic：**20220814/cmd/{#uuid}/insertPermission**
- 说明：null
- 请求参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| id | 权限Id | string | 是 | 20190101120101 | 权限的唯一标识，添加和删除时根据这个标识来判定，建议传32位随机值 |
| type | 权限类型 | int | 是 | 103 | 目前支持100-透传二维码，101-静态二维码，103-动态二维码，202-卡，303-人脸，501-通行密码 |
| code | 权限值 | string | 是 | 001002 | 说明：如果权限类型为303，此值传userId ；其他类型，此值对应内容（例如：卡号，通行密码内容，码值） |
| extra | 额外参数 | Object | 否 | 0 | 可扩展，人脸设备会传递人员名称等信息，参数详见权限添加时的extra参数表 |
| time | 时间区间 | Object | 是 | 0 | 参照附录时间参数表 |
| account | 通行次数 | int | 否 | 1 | 通行次数，即通行权限按次计数 |

- 请求示例
```json
{
    "id": "20190101120101",
    "type": 103,
    "code": "001002",
    "extra": null,
    "time": null,
    "account": 1
}
```

**返回**
- 流向：设备 -> 平台
- Topic：**20220814/cmd/insertPermission_reply**
- 说明：要么都成功，要么全部失败，如果插入的权限在设备里已经存在（id一样），则会忽略，但是还是返回成功。json array 字符串数组，每个元素都是权限id，示例：["20190101120101","20190101120102"]
- 返回参数

- 返回示例
```json

```
        
## 删除权限
**请求**
- 流向：平台 -> 设备
- Topic：**20220814/cmd/{#uuid}/delPermission**
- 说明：json array 字符串数组，每个元素都是权限id，示例：["20190101120101","20190101120102"]
- 请求参数

- 请求示例
```json

```

**返回**
- 流向：设备 -> 平台
- Topic：**20220814/cmd/insertPermission_reply**
- 说明：要么都成功，要么全部失败，如果删除的权限id不存在，则会忽略，但是还是返回成功。json array 字符串数组，每个元素都是权限id，示例：["20190101120101","20190101120102"]
- 返回参数

- 返回示例
```json

```
        
## 清空权限
**请求**
- 流向：平台 -> 设备
- Topic：**20220814/cmd/{#uuid}/clearPermission**
- 说明：data为标准格式
- 请求参数

- 请求示例
```json

```

**返回**
- 流向：设备 -> 平台
- Topic：**20220814/cmd/clearPermission_reply**
- 说明：data为标准格式
- 返回参数

- 返回示例
```json

```
        
## 添加人脸
**请求**
- 流向：平台 -> 设备
- Topic：**20220814/cmd/{#uuid}/insertPersonFace**
- 说明：无
- 请求参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| userId | 权限userId | string | 是 | 2kifk39k40 | 权限的唯一标识，添加和删除时根据这个标识来判定，建议传32位随机值 |
| code | 权限值 | string | 是 | abcd1234 | 说明：照片base64或照片文件对应的文件id |
| extra | 额外参数 | object | 否 |  |  |
| extra.name | 人员名称 | string | 是 | 张三 | name 参数必传且内容不可为空。长度、内容无限制。 |
| extra.accessMode | 权限模式 | int | 是 | 0 | 0：仅权限通行模式，1：人员识别+权限通行模式；默认：0 |
| extra.sex | 性别 | int | 否 | 0 | 0：男，1：女 |
| extra.country | 国家 | string | 否 |  |  |
| extra.groupName | 分组名称 | string | 否 |  |  |
| extra.idCardNumber | 卡号 | string | 否 | 1234567890 | 若人脸权限下发时填写了卡号，可直接刷对应卡号的卡进行识别，屏幕也会显示与该卡号对应的人员的名字。 |
| extra.mobile | 手机号 | string | 否 | 13800138000 | 人员手机号 |
| extra.remarks | 备注 | string | 否 | 这是一个备注 | 用于填写说明信息 |
| extra.photo | 屏显照片 | string | 否 | base64EncodedImageString | 人员的Base64图片 |

- 请求示例
```json
{
    "userId": "2kifk39k40",
    "code": "abcd1234",
    "extra": {
        "name": "张三",
        "accessMode": 0,
        "sex": 0,
        "country": "",
        "groupName": "",
        "idCardNumber": "1234567890",
        "mobile": "13800138000",
        "remarks": "这是一个备注",
        "photo": "base64EncodedImageString"
    }
}
```

**返回**
- 流向：设备 -> 平台
- Topic：**20220814/cmd/insertPersonFace_reply**
- 说明：json array 字符串数组，每个元素都是权限id，示例：["20190101120101","20190101120102"]
- 返回参数

- 返回示例
```json

```
        
## 删除人脸
**请求**
- 流向：平台 -> 设备
- Topic：**20220814/cmd/{#uuid}/deletePersonFace**
- 说明：json array 字符串数组，每个元素都是权限id，示例：["20190101120101","20190101120102"]
- 请求参数

- 请求示例
```json

```

**返回**
- 流向：设备 -> 平台
- Topic：**20220814/cmd/deletePersonFace_reply**
- 说明：要么都成功，要么全部失败，删除的人脸不存在，则会忽略，但是还是返回成功。json array 字符串数组，每个元素都是权限id，示例：["20190101120101","20190101120102"]
- 返回参数

- 返回示例
```json

```
        
## 清空人脸
**请求**
- 流向：平台 -> 设备
- Topic：**20220814/cmd/{#uuid}/clearAllPersonFace**
- 说明：data为标准格式
- 请求参数

- 请求示例
```json

```

**返回**
- 流向：设备 -> 平台
- Topic：**20220814/cmd/clearAllPersonFace_reply**
- 说明：data为标准格式
- 返回参数

- 返回示例
```json

```
        
## 查询人脸
**请求**
- 流向：平台 -> 设备
- Topic：**20220814/cmd/{#uuid}/getAllPersonFace**
- 说明：null
- 请求参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| size | 每页数量 | int | 是 | 10 | 每页数量，最大200(人脸类型只限1条) |
| page | 页码 | int | 是 | 0 | 第几页，从0开始 |
| picLarge | 注册时的照片 | int | 否 | 1 | 是否返回注册时照片，0或者不传不返回，1：返回 |

- 请求示例
```json
{
    "size": 10,
    "page": 0,
    "picLarge": 1
}
```

**返回**
- 流向：设备 -> 平台
- Topic：**20220814/cmd/getAllPersonFace_reply**
- 说明：null
- 返回参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| page | 当前页 | int | 是 | 0 | 当前页（0开始） |
| size | 每页大小 | int | 是 | 10 | 当前页大小 |
| total | 总数 | int | 是 | 100 | 白名单总数 |
| totalPage | 总页数 | int | 是 | 10 | 总页数 |
| count | 当前页实际人脸数 | int | 是 | 5 | 当前页实际人脸数 |
| content | 权限列表 | array | 是 |  | 权限列表 |
| content.id | 权限Id | string | 是 | 2kifk39k40 | 人脸的唯一标识，添加和删除时根据这个标识来判定，建议传32位随机值 |
| content.code | 权限值 | string | 是 | abcd1234 | 权限类型为303时，这个值对应base64 |
| content.extra | 额外参数 | object | 否 |  | 可扩展，人脸设备会传递人员名称等信息 |
| content.time | 时间区间 | object | 是 |  | 查看时间区间列表 |

- 返回示例
```json
{
    "page": 0,
    "size": 10,
    "total": 100,
    "totalPage": 10,
    "count": 5,
    "content": null
}
```
        
## 远程控制
**请求**
- 流向：平台 -> 设备
- Topic：**20220814/cmd/{#uuid}/control**
- 说明：远程控制设备，触发设备的相应动作，包括重启、远程开门、设备启用、设备禁用、设备重置等
- 请求参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| command | 命令 | int | 是 | 0 | 0：重启， 1：远程开门， 2：设备启用， 3：设备禁用， 4：设备重置 |

- 请求示例
```json
{
    "command": 0
}
```

**返回**
- 流向：设备 -> 平台
- Topic：**20220814/cmd/control_reply**
- 说明：无
- 返回参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| command | 命令 | int | 是 | 0 | 0：重启， 1：远程开门， 2：设备启用， 3：设备禁用， 4：设备重置 |

- 返回示例
```json
{
    "command": 0
}
```
        
## 应用升级
**请求**
- 流向：平台 -> 设备
- Topic：**20220814/cmd/{#uuid}/upgradeFirmware**
- 说明：设备收到升级固件后，先下载固件文件，下载成功后返回结果给应用平台，然后重启
- 请求参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| type | 升级包类型 | int | 是 | 0 | type值强校验，必须为0或10：系统升级，文件为xxx.pkg1：应用升级升级包为xxx.tar.xz |
| url | 升级包下载地址，http地址 | string | 是 | http://example.com/upgrade/xxx.pkg | 调用接口时访问该url，若url能访问到，则设备开始执行下载文件；若url访问失败，则接口返回提示“url访问失败，设备无法下载” |
| md5 | 升级包MD5值 | string | 是 | d41d8cd98f00b204e9800998ecf8427e | 升级包进行MD5验证 |

- 请求示例
```json
{
    "type": 0,
    "url": "http://example.com/upgrade/xxx.pkg",
    "md5": "d41d8cd98f00b204e9800998ecf8427e"
}
```

**返回**
- 流向：设备 -> 平台
- Topic：**20220814/cmd/upgradeFirmware_reply**
- 说明：data为标准格式
- 返回参数

- 返回示例
```json

```
        
## 同步密钥
**请求**
- 流向：平台 -> 设备
- Topic：**20220814/cmd/{#uuid}/secretSync**
- 说明：设备有同步密钥才能正常使用动态二维码，不然无法识别不可正常使用。
- 请求参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| syncFlag | 同步标识 | int | 是 | 1 | 1-全量，2-增量 |
| secretKeys | 密钥数组 | array | 是 |  |  |
| secretKeys.secretKeyType | 密钥类型 | string | 是 | RSA | 密钥类型，如RSA,AES等 |
| secretKeys.secretKeyCode | 密钥编码 | string | 是 | vguang | 密钥编码，对应密钥编码，如vguang |
| secretKeys.secretKeyValue | 密钥值 | string | 是 | abc123 |  |
| secretKeys.secretKeyStartTime | 开始时间 | int | 是 | 1672502400 | 密钥开始时间，时间戳（秒） |
| secretKeys.secretKeyExpirytime | 过期时间 | int | 是 | 1672588800 | 密钥过期时间，时间戳（秒） |
| secretKeys.syncType | 同步类型 | int | 是 | 1 | 当SyncFlag=2时有效，1-增加，2-修改，3-删除，删除时SecretKeyValue、SecretKeyStartTime、SecretKeyExpirytime为可选，SecretKeyStartTime存在删除大于等于SecretKeyStartTime，SecretKeyExpirytime存在删除小于等于SecretKeyExpirytime |

- 请求示例
```json
{
    "syncFlag": 1,
    "secretKeys": null
}
```

**返回**
- 流向：设备 -> 平台
- Topic：**20220814/cmd/secretSync_reply**
- 说明：data为标准格式
- 返回参数

- 返回示例
```json

```

# 三、事件接口

## 连接上报
**请求**
- 流向：设备 -> 平台
- Topic：**20220814/event/connect**
- 说明：设备一旦连接到 MQTT 服务器后，立刻主动上报设备当前状态
- 请求参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| time | 设备当前时间 | Long | 是 | 1647580466 |  |
| sysVersion | 系统版本号 | string | 是 | v1.0.3.4050 |  |
| appVersion | 应用版本号 | string | 是 | v3.204.234.5 |  |
| createTime | 应用发布日期 | Long | 是 | 1647550466 |  |
| uuid | 设备唯一标识 | string | 是 | 1117U9 |  |
| name | 设备名称 | string | 是 | #12-B01 |  |
| model | 设备类型 | string | 是 | vf106 |  |

- 请求示例
```json
{
    "time": null,
    "sysVersion": "v1.0.3.4050",
    "appVersion": "v3.204.234.5",
    "createTime": null,
    "uuid": "1117U9",
    "name": "#12-B01",
    "model": "vf106"
}
```

**返回**
- 流向：无
- Topic：**无**
- 说明：无需返回
- 返回参数

- 返回示例
```json

```
        
## 告警上报
**请求**
- 流向：设备 -> 平台
- Topic：**20220814/event/alarm**
- 说明：无
- 请求参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| type | 状态类型 | int | 是 | 1 | 参考附录-告警类型列表 |
| value | 状态值 | int | 否 | 0 | 参考附录-告警类型列表 |

- 请求示例
```json
{
    "type": 1,
    "value": 0
}
```

**返回**
- 流向：平台 -> 设备
- Topic：**20220814/event/{#uuid}/alarm_reply**
- 说明：data为标准格式
- 返回参数

- 返回示例
```json

```
        
## 通行上报
**请求**
- 流向：设备 -> 平台
- Topic：**20220814/event/access**
- 说明：设备运行期间，如果人通行门禁，通行结果主动上报给应用平台
- 请求参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| id | 权限Id | string | 是 | 20190101120101 | 如果权限存在设备的白名单就返回对应的权限id，不存在就返回-1 |
| type | 权限类型 | int | 是 | 103 | 目前支持100-透传二维码，101-静态二维码，103-动态二维码，202-卡，303-人脸，501-通行密码 |
| code | 权限值 | string | 是 | 001002 | 如果是人脸则是特征值 |
| time | 通行时间 | Long | 是 | 1647580466 | 时间戳单位秒 |
| result | 通行结果 | int | 是 | 1 | 1表示通过 0表示未通过 |
| extra | 额外参数 | Object | 否 |  | 可扩展，人脸设备会传递人员名称、人员实时照片、体温等信息，如果id为-1，extra的值为识别出来的原始数据 |

- 请求示例
```json
{
    "id": "20190101120101",
    "type": 103,
    "code": "001002",
    "time": null,
    "result": 1,
    "extra": null
}
```

**返回**
- 流向：平台 -> 设备
- Topic：**20220814/event/{#uuid}/access_reply**
- 说明：data为标准格式，平台返回后，设备删除通行记录
- 返回参数

- 返回示例
```json

```

# 四、配置属性

## 网络配置
**配置组名：netInfo**
**配置组描述：关于网络配置的信息体**
- 配置参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| type | 网络类型 | int | 是 | 1 | 网络类型(0:以太网,1:wifi) |
| ssid | Wifi名 | string | 是 | MyWiFiNetwork | wifi名 |
| pwd | Wifi密码 | string | 是 | SecurePassword123 | wifi密码 |
| dhcp | 是否为DHCP模式 | int | 是 | 2 | 是否为DHCP(1:静态,2:动态) |
| ip | ip地址 | string | 是 | 192.168.1.100 | ip地址 |
| gateway | 网关 | string | 是 | 192.168/XMLSchema=instance1.1 | 网关 |
| dns | DNS服务器 | string | 是 | 8.8.8.8 | DNS服务器 |
| subnetMask | 子网掩码 | string | 是 | 255.255.255.0 | 子网掩码 |

## mqtt配置
**配置组名：mqttInfo**
**配置组描述：关于 mqtt 服务器配置的信息体**
- 配置参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| mqttAddr | Mqtt服务器ip | string | 是 | 192.168.1.100:1883 | Mqtt地址（ip:端口） |
| port | Mqtt端口 | string | 是 | 1883 | Mqtt地址（ip:端口） |
| clientId | 客户端id，与设备地址一致 | string | 是 | device_001 | 客户端id，与设备地址一致 |
| mqttName | mqtt用户名 | string | 是 | user123 | mqtt用户名 |
| password | mqtt密码 | string | 是 | securePass456 | mqtt密码 |

## 基础配置
**配置组名：baseInfo**
**配置组描述：关于基础配置信息体**
- 配置参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| time | 时间 | long | 是 | 1672502400 | 时间 |
| sysVersion | 系统版本号 | string | 否 | 1.0.0 | 系统版本号 |
| appVersion | 应用版本号 | string | 否 | 1.0.0 | 应用版本号 |
| createTime | 应用发布日期 | string | 否 | 2023-01-01 | 应用发布日期 |
| uuid | 设备地址（MAC） | string | 否 | 1118HF | 设备地址（MAC） |
| deviceName | 设备名称 | string | 是 | MyDevice | 设备名称 |
| model | 设备类型 | string | 否 | ModelX | 设备类型 |
| status | 设备基本状态 | string | 否 | 1 | 0-未激活，1-正常，2-禁用 |
| operationMode | 运行模式 | string | 否 | 0 | 设备运行模式（不同模式切换时会清除之前模式下的所有数据记录，包含权限白名单），0：互联网模式，1：局域网模式，2：单机版模式，默认：0 |
| tamperSwitch | 防拆开关 | string | 是 | 1 | 0：关闭,1：打开，默认：1 |
| alarmSwitch | 报警开关 | string | 是 | 1 | 0：关闭，1：打开，默认：1 |
| autoRbootTime | 自动重启时间 | int | 是 | 10 | 自动重启时间，单位：秒，默认10s（即应用操作无响应，等待时间超过10s自动重启） |

## 系统配置
**配置组名：sysInfo**
**配置组描述：关于系统配置信息体**
- 配置参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| disk | 设备剩余空间 | int | 否 | 1048576 | 设备剩余空间单位是kb |
| memroy | 内存剩余空间 | int | 否 | 524288 | 内存剩余空间单位是kb |
| cpu | cpu占用比率 | int | 否 | 20 | CPU占用比率% |

## 门禁配置
**配置组名：doorInfo**
**配置组描述：关于门禁配置信息体**
- 配置参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| mode | 设备开门模式 | string | 是 | 0 | 设备开门模式，0-正常，1-常开模式，2-常闭模式；默认：0 |
| openTime | 开门时长，单位秒 | string | 是 | 5 | 开门时长，单位秒 |
| relayDelay | 继电器延时时间，单位秒 | int | 是 | 2 | 默认：2秒 |
| recMode | 识别模式 | int | 是 | 1 | 识别模式（1：人/卡合一，2：人/码合一，3：人/卡/码任一） |
| scannerWorkMode | 扫描器工作模式 | int | 是 | 4 | 工作模式（针对刷卡/扫码1：透传模式，2：协议模式，3：开发模式，4：本地白名单模式）注：当为开发模式时，faceWorkMode亦会同时变为开发模式；默认：4 |
| faceWorkMode | 人脸工作模式 | int | 是 | 4 | 工作模式（针对刷脸1：透传模式，2：协议模式3：开发模式，4：本地白名单模式）注：当为开发模式时，faceWorkMode亦会同时变为开发模式；默认：4 |
| qrEn | 扫码开关 | int | 是 | 1 | 0：关闭，1：打开；默认：1 |
| qrCheckInterval | 扫码间隔 | int | 是 | 1000 | 扫码间隔默认1000毫秒 |
| qrAffixesFt | 前后缀格式 | int | 是 | 1 | 二维码前后缀格式1：字符串格式，2：十六进制格式；默认：1 |
| qrPrefix | 前缀 | string | 是 |  | 二维码前缀，默认：""（空） |
| qrPostfix | 后缀 | string | 是 |  | 二维码后缀，默认：""（空） |
| nfcEn | 刷卡开关 | int | 是 | 1 | 0：关闭，1：打开；默认：1 |
| nfcFt | 格式转换 | int | 是 | 0 | NFC格式转换，0：不转换，1：转16进制字符格式输出，2：转10进制字符输出；默认：0 |
| nfcOrd | 正反序 | int | 是 | 0 | NFC数据正反序0：正序，1：反序；默认：0 |
| nfcAffixesFt | 前后缀格式 | int | 是 | 1 | NFC前后缀格式，1：字符串格式，2：十六进制格式；默认：1 |
| nfcPrefix | 前缀 | string | 是 |  | NFC前缀，默认：""（空） |
| nfcPostfix | 后缀 | string | 是 |  | NFC后缀，默认：""（空） |
| nfcReadIdNum | 身份证号 | int | 是 | 0 | 0：读取身份证物理卡号，1：读取身份证号；默认：0 |
| doorSensorDelay | 报警延时 | int | 是 | 30 | 报警信号出发多久后执行，单位秒，默认：30s |
| doorSensor | 触发类型 | int | 是 | 2 | 报警信号触发类型，0：与地断开触发，1：与地短接触发，2：不触发（默认） |
| alarmOutputSwitch | 输出开关 | int | 是 | 1 | 报警触发输出开关，1：打开（默认），0：关闭 |
| alarmRelay | 报警继电器 | int | 是 | 1 | alarmOutputSwitch=1有效，1：输出继电器，0：不输出继电器 |

## 实时状态
**配置组名：statusInfo**
**配置组描述：关于设备运行实时状态配置信息体**
- 配置参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| door | 门磁状态 | int | 否 | 0 | 0：门磁关、1：门磁开 |
| fire | 火警状态 | int | 否 | 0 | 0：火警关、1：火警开 |

## 测温配置
**配置组名：temperatureInfo**
**配置组描述：关于测温配置信息体**
- 配置参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| alarmTemperature | 报警温度 | float | 是 | 37.3 | 默认37.3 |
| bodyTemperatureDetect | 测温开关 | string | 是 | 1 | 0：关闭，1：打开测温服务模块；默认：0 |
| infraredEnable | 红外预览图 | string | 是 | 1 | 红外图像，0： 关闭，1： 开启；默认：1 |
| temperatureCompensation | 温度补偿 | string | 是 | 0 | 温度补偿，默认：0 |

## 人脸配置
**配置组名：faceInfo**
**配置组描述：关于人脸配置信息体**
- 配置参数

| 参数 | 名称 | 类型 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- | --- | --- |
| recgThreshold | 识别阀值 | string | 是 | 54 | 人脸相似度阀值， 用于判断这个人是否识别通过（0~100）；默认：54 |
| registerThreshold | 权限阈值 | string | 是 | 80 | 权限阈值，人员相似度阈值（0~100），当人员相似度达到此值时将会导致权限下发失败 |
| living | 活体检测 | string | 是 | 1 | 0： 关闭活检，1： 开启活检；默认：1 |
| livingThreshold | 活体阈值 | string | 是 | 10 | 活体检测阈值（0~100）默认（10）， 活检算法每次判断人脸视频帧是否活体，并给出一个分数， 当这个分数累计大于阈值后， 就认为当前是活体， 活体检测阈值越大需要活检的分数越高， 非活体攻击难度越大， 同时可能会影响活体通过率 |
| exposureValues | 曝光补偿 | string | 是 | 0 | 曝光补偿，默认：0 |
| maxTrackFaces | 人脸识别数 | string | 是 | 5 | 多人识别，人脸识别数配置[1,5] |
| faceRecgEnable | 识别开关 | string | 是 | 1 | 人脸识别：0： 关闭，1： 开启；默认：1 |
| maskDetectEnable | 口罩检测 | string | 是 | 0 | 口罩检测：0：关闭，1：打开；默认：0 |
| maskEnable | 口罩识别 | string | 是 | 1 | 口罩识别：0：关闭，1：打开；默认：1 |
| maskThresholdValue | 口罩阈值 | string | 是 | 53 | 口罩阈值（0~100），默认：53 |
| recgDistance | 识别距离 | string | 是 | 150 | 识别距离（50~150cm），默认：150 |
| recgInterval | 识别间隔 | string | 是 | 1500 | 重复识别的时间间隔单位毫秒ms，默认：1500，需大于recgTimeout |
| recgTimeout | 识别超时 | string | 是 | 1000 | 识别超时单位毫秒ms，最低1000 |
| repeatRecgEnable | 重复识别 | string | 是 | 1 | 重复识别开关，0：关闭，1：打开，默认：1 |
| strangerVoice | 识别语音 | string | 是 | 3 | 陌生人语音对应比特位为1有效，bit0：播放请先注册，bit1：播陌生人你好 |
| alarmVoiceData | 报警语音 | string | 是 | 警报 | alarmOutputSwitch=1有效，""（空）：播放默认语音，"警报"：播放 "警报 |
| faceCheckSucVoice | 语音类型 | string | 是 | 1 | 人脸核验成功语音：0：无语音，1：播放默认语音，2：播放自定义语音 |
| faceCheckSucVoiceData | 语音数据 | string | 是 | 自定义语音内容 | 人脸核验成功自定义语音内容 |
| faceCheckSucRelay | 刷脸继电器 | string | 是 | 1 | 人脸核验成功继电器，0：无动作，1：输出继电器 |
| faceCheckFailedVoice | 语音类型 | string | 是 | 1 | 人脸核验失败语音，0：无语音，1：播放默认语音，2：播放自定义语音 |
| faceCheckFailedVoiceData | 语音数据 | string | 是 | 自定义语音内容 | 人脸核验失败自定义语音内容 |
| cardCheckSucVoice | 语音类型 | string | 是 | 1 | 刷卡核验成功语音：0：无语音，1：播放默认语音，2：播放自定义语音 |
| cardCheckSucVoiceData | 语音数据 | string | 是 | 自定义语音内容 | 刷卡核验成功自定义语音内容 |
| cardCheckSucRelay | 继电器开关 | string | 是 | 1 | 刷卡核验成功继电器，0：无动作，1：输出继电器 |
| cardCheckFailedVoice | 语音类型 | string | 是 | 1 | 刷卡核验失败语音，0：无语音，1：播放默认语音，2：播放自定义语音 |
| cardCheckFailedVoiceData | 语音数据 | string | 是 | 自定义语音内容 | 刷卡核验失败语音自定义语音内容 |
| qrCheckSucVoice | 语音类型 | string | 是 | 1 | 扫码核验成功语音：0：无语音，1：播放默认语音，2：播放自定义语音 |
| qrCheckSucVoiceData | 语音数据 | string | 是 | 自定义语音内容 | 扫码核验成功语音自定义语音内容 |
| qrCheckSucRelay | 继电器 | string | 是 | 1 | 扫码核验成功继电器，0：无动作，1：输出继电器 |
| qrCheckFailedVoice | 语音类型 | string | 是 | 1 | 扫码核验失败语音，0：无语音，1：播放默认语音，2：播放自定义语音 |
| qrCheckFailedVoiceData | 语音数据 | string | 是 | 自定义语音内容 | 扫码核验失败语音自定义语音内容 |
| saveLargePic | 全景图片 | string | 是 | 1 | 通行记录全景图片1：保存，0 ：不保存 |
| saveSmallPic | 人脸图片 | string | 是 | 1 | 通行记录人脸图片1：保存，0 ：不保存 |
| saveStrangerRecord | 陌生人记录 | string | 是 | 1 | 陌生人记录：1：保存，0 ：不保存 |
| avoidAttendanceStep | 保存间隔 | string | 是 | 3 | 通行记录保存间隔。单位秒s，默认3 |
| voiceMode | 语音模式 | string | 是 | 3 | 语音模式对应比特位为1有效，bit0播报名字，bit1播放问候语 |
| grettings | 问候语 | string | 是 | 3 | 问候语对应比特位为1有效，bit0：播放打卡成功，bit1：播放请通行，bit2：播放欢迎光临，bit3：播放时间问候语 |
| infraredLightSet | 补光灯 | string | 是 | 2 | 补灯光模式，0：长闭，1：长开，2：自动模式 |
| lightSensitive | 光敏控制 | string | 是 | 1 | 光敏控制（暂时没有使用），1：打开（默认），0：关闭 |
| lightHighBrightness | 最高亮度 | string | 是 | 100 | 环境光高于此值关闭红外检测人脸是否进入识读区域 |
| lightLowBrightness | 最低亮度 | string | 是 | 50 | 环境光低于此值且有人脸进入识读区域打开补光 |
| lightDetInterval | 检测间隔 | string | 是 | 1 | 环境光检测间隔，单位秒，默认：1s |
| lightDelayTime | 补光灯延时 | string | 是 | 15 | 自动模式下补光灯亮起延时时间，单位秒，默认：15s |
| lightBrightness | 亮度 | string | 是 | 50 | 补光灯亮度(0~100) |
| language | 语言 | string | 是 | 0 | 0：中文， 1：英文 |
| volume | 音量 | string | 是 | 50 | 音量（0-100），默认：50 |
| autoSetTime | 时间更新 | string | 是 | 1 | 自动更新时间，0：关闭，1：打开（默认） |
| autoSetTimezone | 时区更新 | string | 是 | 1 | 自动设置时区，0：关闭，1：打开（默认） |
| timezone | 时区 | string | 是 | Asia/Shanghai | 时区，默认："Asia/Shanghai"，可用时区参见[可用时区列表](#timeInterval) |
| deviceName | 设备名 | string | 是 | 大门 | 默认：大门，任意字符串长度小于128 |
| deviceDirection | 设备位置 | string | 是 | 1 | 设备位置，1：进（默认），2：出，3：进/出 |
| nameShow | 姓名 | string | 是 | 1 | 显示姓名，0：不显示，1：显示，默认：1 |
| snShow | 设备SN | string | 是 | 1 | 显示SN，0：不显示，1：显示，默认：1 |
| ipShow | 设备IP | string | 是 | 1 | 显示IP，0：不显示，1：显示，默认：1 |
| autoDisplayBrightness | 屏幕亮度调节 | string | 是 | 0 | 自动调节屏幕亮度，0：关闭，1：打开，默认：0 |
| displayBrightness | 屏幕亮度 | string | 是 | 80 | 屏幕亮度（0-100）默认：80 |
| autoScreenOff | 自动息屏 | string | 是 | 1 | 自动息屏，0：关闭，1：打开，默认：1 |
| autoScreenOffTime | 息屏时间 | string | 是 | 300 | 自动息屏时间，默认：300秒 |
| autoScreenSaverTime | 自动屏保 | string | 是 | 30 | 自动屏保时间，默认：30秒 |

# 五、附录

## 结果码
**说明：无**

| 参数 | 名称 | 说明 |
| --- | --- | --- |
| 000000 | 成功 | 成功执行指令 |
| 100000 | 通用报错 | 未知错误 |
| 100001 | 通用报错 | 设备已被禁用。设备禁用后很多指令不允许执行 |
| 100002 | 通用报错 | 设备正忙，请稍后再试。设备正在升级、设置网络或其他任务进程中 |
| 100003 | 通用报错 | 签名检验失败 |
| 200000-299999 | 参数异常 | 参数异常。不同的指令对应不同的参数规范，参考每个接口后的参数异常描述 |
| 300000-399999 | 其它异常 | 其它已知原因导致的异常。不同的指令对应不同的异常，参考每个接口后的参数异常描述 |

## 告警类型
**说明：无**

| 参数 | 名称 | 说明 |
| --- | --- | --- |
| 0 | 门磁状态 | 0：门磁关、1：门磁开 |
| 1 | 火警状态 | 0：火警关、1：火警开 |
| 2 | 非法开门 | 无 |
| 3 | 开门超时 | 无 |
| 4 | 关门超时 | 无 |
| 5 | 升级汇报 | 0：升级失败、1：升级成功完成 |
| 6 | 看门狗导致重启 | 1：看门狗导致重启 |

## 时间区间
**说明：可用时区：中国标准时间 (北京)、日本时间 (东京)、格林尼治标准时间 (伦敦)、英国时间 (巴黎)、德国时间 (柏林)、美国东部时间 (纽约)**

| 参数 | 名称 | 说明 |
| --- | --- | --- |
| 0 | 永久权限 | {"type":0} |
| 1 | 时间区间 | {"type":1,"beginTime":1640917147,"endTime":1640917147} |
| 2 | 周重复 | {"type":2,"beginTime":1640917147,"endTime":1640917147,"weekPeriodTime":{"1":"9:00-10:00","2":"12:00-13:30|15:00-16:30","3":"xxxxx|xxxxx","7":"xxxxx|xxxxx"}} |