MQTT协议V1.0.0

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

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

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

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

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

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

2) 消息内容:文本格式的消息内容，内容为Json格式
发送消息内容的示例如下：
```json
{ 
 "serialNo": "6w8keif5g6",
 "uuid": "0a1b2c3d",
 	"cmd": "getConfig",
 "data": {
 ...
 },
 "time":1647580466, 
 "sign":"e0k4jrir85tje8ru4jrur499r99ii4ur"
}
```
返回消息内容的示例如下：
```json
{ 
 "serialNo": "6w8keif5g6",
 "uuid": "0a1b2c3d",
 "cmd": "getConfig",
 "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}`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：
    - data 可以为空，或者不传这个部分，这个时候设备将返回所有配置数据
    - data 可以为string，因为配置数据是 kye/value 对应的 json 格式的对象，所以如果传入一个指定的 key，就可以返回设备里这个 key 对应的 value。

- 请求示例
```json
//获取所有数据
{
	"serialNo": "6w8keif5g6",
	"uuid": "e16559",
	"cmd": "getConfig"
}
//获取网络相关数据
{
	"serialNo": "6w8keif5g6",
	"uuid": "607a9d",
	"cmd": "getConfig",
	"data": "netInfo"
}
```

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

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

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

[回到顶部](#category)

## 配置修改
- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：
    - data 中支持的json对象：netInfo,mqttInfo,sysInfo 详情参考[附件:配置数据详情](#configs)
-注意事项：1. netInfo中type必须存在，dhcp为静态时，必须提供IP相关的配置 
- 请求示例
```json
//关闭网络
{
	"serialNo": "1",
	"uuid": "140126",
	"cmd": "setConfig",
	"data":  {
		"netInfo":{
           "type":255
		}
	}
}
```
```json
//打开并配置wifi
{
	"serialNo": "1",
	"uuid": "140126",
	"cmd": "setConfig",
	"data":  {
		"netInfo":{
           "type":0,
           "ssid": "Vguang_RJ",
           "pwd":"vguangrj_o0",
           "dhcp": 1
		}
	}
}
```
- 流向：设备 -> 平台
- 说明: 
- Topic：**` access_device/v1/cmd/reply  `**
- 内容：[标准格式](#content)
- data 部分：为空

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

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

[回到顶部](#category)

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

| 参数名 | 说明     | 类型   | 必须 | 备注                                     |
| :----- | :------- | :----- | ---- | ---------------------------------------- |
| size   | 每页数量 | Int    | 是   | 每页数量，最大 200                       |
| page   | 页码     | Int    | 是   | 第几页，从0开始                          |
| code   | 凭证号   | String | 是   | 凭证号      code+type=精准查询人                             |
| type   | 凭证类型 | Int    | 是   | 参考[附录-权限码表](#typeDetails)-type列 |

- 请求示例
```json

//按code和type查询
{
    "serialNo": "6w8keif5g6",
    "uuid": "140126",
    "cmd": "getPermission",
    "data": {
  	    "code": "123456",
        "type": 0
    },
    "time": 1647580466
}
```

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

| 参数名             | 说明               | 类型   | 必须 | 备注                                                         |
| ------------------ | ------------------ | ------ | ---- | ------------------------------------------------------------ |
| page               | 当前页             | Int    | 是   | 当前页（0开始）                                              |
| size               | 每页大小           | Int    | 是   | 当前页大小，取值范围 (0, 5]                                  |
| total              | 总数               | Int    | 是   | 白名单总数                                                   |
| totalPage          | 总页数             | Int    | 是   | 总页数                                                       |
| count              | 当前页实际白名单数 | Int    | 是   | 当前页实际白名单数                                           |
| content            | 权限列表           | array  | 是   | 权限list                                                     |
| --type             | 权限类型           | Int    | 是   | 参考[附录-权限类型码表](#typeDetails)-type列                 |
| --code             | 权限值             | String | 是   | 通行权限值                                                   |
| --repeat           | 循环使能           | int    | 是   | BIT0~BIT3: x、时段1、时段2、时段3                   |
| --beginTime        | 生效时间           | Int    | 否   | 生效时间                                                     |
| --endTime          | 失效时间           | Int    | 否   | 失效时间                                                     |
| --timePeriodBegin1 | 时间段1开始时间    | Int    | 否   | 时间段1开始时间 时间范围 0~86400 时间为00:00:00 到 某时间的秒数 |
| --timePeriodEnd1   | 时间段1结束时间    | Int    | 否   | 时间段1结束时间 时间范围 0~86400 时间为00:00:00 到 某时间的秒数 |
| --timePeriodBegin2 | 时间段2开始时间    | Int    | 否   | 时间段2开始时间 时间范围 0~86400 时间为00:00:00 到 某时间的秒数 |
| --timePeriodEnd2   | 时间段2结束时间    | Int    | 否   | 时间段2结束时间 时间范围 0~86400 时间为00:00:00 到 某时间的秒数 |
| --timePeriodBegin3 | 时间段3开始时间    | Int    | 否   | 时间段3开始时间 时间范围 0~86400 时间为00:00:00 到 某时间的秒数 28800  表示上午8点 |
| --timePeriodEnd3   | 时间段3结束时间    | Int    | 否   | 时间段3结束时间 时间范围 0~86400 时间为00:00:00 到 某时间的秒数 32400 表示上午9点 |
| --tag              | 标签（用户名）     | String | 否   | 其他额外属性，比如人员名称等                                 |
| --source           | 凭证来源           | Int    | 否   | 凭证来源                                                     |

- 返回示例：
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "cmd": "getPermission",
    "code": "000000",
    "data": {
        "content": [{
            "type": 0,
            "code": "001002",
           "repeat": "00000"
        }],
        "page": 1,
        "size": 5,
        "total": 1,
        "totalPage": 1,
        "count": 1
    },
    "time": 1647580466,
    "sign": ""
}

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

[回到顶部](#category)

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

| 参数名             | 必填            | 类型   | 说明 | 备注                                                         |
| :----------------- | :-------------- | :----- | ---- | ------------------------------------------------------------ |
| --type             | 权限类型        | Int    | 是   | 参考[附录-权限类型码表](#typeDetails)-type列                 |
| --code             | 权限值          | String | 是   | 通行权限值                                                   |
| --repeat           | 循环使能        | int    | 是   | BIT1~BIT3: 、时段1、时段2、时段3                     |                                        |
| --beginTime        | 生效时间        | Int    | 是   | 生效时间                                                     |
| --endTime          | 失效时间        | Int    | 是   | 失效时间                                                     |
| --timePeriodBegin1 | 时间段1开始时间 | Int    | 否   | 时间段1开始时间 时间范围 0~86400 时间为00:00:00 到 某时间的秒数 |
| --timePeriodEnd1   | 时间段1结束时间 | Int    | 否   | 时间段1结束时间 时间范围 0~86400 时间为00:00:00 到 某时间的秒数 |
| --timePeriodBegin2 | 时间段2开始时间 | Int    | 否   | 时间段2开始时间 时间范围 0~86400 时间为00:00:00 到 某时间的秒数 |
| --timePeriodEnd2   | 时间段2结束时间 | Int    | 否   | 时间段2结束时间 时间范围 0~86400 时间为00:00:00 到 某时间的秒数 |
| --timePeriodBegin3 | 时间段3开始时间 | Int    | 否   | 时间段3开始时间 时间范围 0~86400 时间为00:00:00 到 某时间的秒数 28800  表示上午8点 |
| --timePeriodEnd3   | 时间段3结束时间 | Int    | 否   | 时间段3结束时间 时间范围 0~86400 时间为00:00:00 到 某时间的秒数 32400 表示上午9点 |
| --tag              | 标签（用户名）  | String | 否   | 其他额外属性，比如人员名称等                                 |
| --source           | 凭证来源        | Int    | 否   | 凭证来源                                                     |

### 循环使能
|BIT7|BIT6|BIT5|BIT4|BIT3|BIT2|BIT1|BIT0|
|:----:|:----:|:----:|:----:|:----:|:----:|:----:|:----:|
|x|x|x|次数(不支持)|时段3|时段2|时段1|周(不支持)|

- 请求示例
```json
{
 "cmd" : "insertPermission",
 "data" : 
 [
  {
   "beginTime" : 1729320110,
   "code" : "123456",
   "endTime" : 1762876800,
   "repeat" : 2,
   "tag" : "test",
   "timePeriodBegin1" : 0,
   "timePeriodBegin2" : 0,
   "timePeriodBegin3" : 0,
   "timePeriodEnd1" : 0,
   "timePeriodEnd2" : 0,
   "timePeriodEnd3" : 0,
   "type" : 0
  }
 ],
 "serialNo" : "1",
 "time" : 1745833013,
 "uuid" : "La5xPG"
}
```

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

- 返回示例：
```
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "cmd": "insertPermission",
    "code": "000000",
    "time": 1647580466,
    "sign": ""
}
```
- 特殊结果码
| 类型                  | code   | 信息                   | 说明                   |
| --------------------- | ------ | ---------------------- | ---------------------- |
| 参数异常              | 20000  | 缺少必须要有的参数     | 缺少必须要有的参数     |
| 参数异常              | 200001 | 权限不能为空           | 权限不能为空           |
| 参数异常              | 200002 | 权限数量大于特定的数量 | 权限数量大于特定的数量 |
| 空间不足              | 200003 | 设备磁盘空间不足       | 设备磁盘空间不足       |
| 数据库异常            | 200004 | 数据库错误             | 数据库错误             |
| 参数异常              | 200005 | 不支持的参数           | 可能是凭证类型         |
| 参数异常              | 200006 | 内存不足               | 没有足够的ram空间      |
| 参数异常              | 200007 | 凭证已存在               |       |
| [回到顶部](#category) |        |                        |                        |

## 删除权限
- 说明: 
- 流向：平台 -> 设备
- Topic：**` access_device/v1/cmd/{#uuid}`**
- 内容：[标准格式](#content)
- 内容里的 data 部分：json array 数组对象：
| 参数名 | 必填     | 类型   | 说明 | 备注                                         |
| :----- | :------- | :----- | ---- | -------------------------------------------- |
| --type | 权限类型 | Int    | 是   | 参考[附录-权限类型码表](#typeDetails)-type列 |
| --code | 权限值   | String | 是   | 通行权限值                            |
- 请求示例
```json
//删除权限
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "cmd": "delPermission",
    "data": {
        "type":0，
		"code":"123456"
    },
    "time": 1647580466,
    "sign": ""
}
```

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

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

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

[回到顶部](#category)

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

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

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

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

[回到顶部](#category)

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

| 参数名  | 说明 | 类型 | 必须 | 备注                                         |
| :------ | :--- | :--- | ---- | -------------------------------------------- |
| command | 命令 | Int  | 是   | 0：重启 1：远程开门  4：设备重置 |

- 请求示例
```json
//远程重启
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "cmd": "control",
    "data": {
        "command": 0
    },
    "time": 1647580466,
    "sign": ""
}
//远程开门
{
    "serialNo": "3",
    "uuid": "0a1b2c3d",
    "cmd": "control",
    "data": {
      	"command": 1
    },
    "time": 1647580466
}
```

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

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

| 类型     | code   | 信息                | 说明               |
| -------- | ------ | ------------------- | ------------------ |
| 参数异常 | 200000 | 缺少必须要有的参数  | 缺少必须要有的参数 |
| 参数异常 | 200001 | 不支持的 command 值 | command 值错误     |
| 执行异常 | 200002 | 指令执行失败        | 执行失败           |
| 执行异常 | 300006 | 重置白名单失败(无内存)        |                    |

[回到顶部](#category)

# 三. 事件类接口列表

## 连接上报

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

| 参数名     | 说明         | 类型   | 必须 | 备注         |
| :--------- | :----------- | :----- | ---- | ------------ |
| version    | 应用版本号   | String | 否   | 应用版本号   |
| btMac      | 蓝牙MAC地址  | String | 是   | 蓝牙MAC地址  |
| deviceName | 蓝牙名称     | String | 是   | 蓝牙名称     |
| ip         | ip地址       | String | 是   | ip地址       |

- 请求示例
```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "0a1b2c3d",
  "cmd": "connect",
	"data": {
		"version": "v1.0.3.4050",
		"createTime": 1647550466,
		"uuid": "0a1b2c3d",
		"name": "#12-B01",
		"model":"dx_cc101"
	},
	"time": 1647580466,
	"sign": ""
}
```

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

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

[回到顶部](#category)

## 告警上报

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

| 参数名 | 说明     | 类型   | 必须 | 备注                                                         |
| :----- | :------- | :----- | ---- | ------------------------------------------------------------ |
| type   | 状态类型 | Int    | 是 | 参考[附录-设备状态码表](#alarmDetails)-type列         |
| value  | 状态值   | String | 否 | 参考[附录-设备状态码表](#alarmDetails)，如果是"无"，就不需要传值 |

- 请求示例
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "cmd": "alarm",
    "data": {
        "type": 7,
        "value": "0"
    },
    "time": 1647580466,
    "sign": ""
}
```

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

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

[回到顶部](#category)

## 通行上报

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

| 参数名  | 说明           | 类型   | 必须 | 备注                                         |
| :------ | :------------- | :----- | ---- | -------------------------------------------- |
| code    | 权限凭证       | String | 是   | 权限凭证                                     |
| type    | 权限类型       | Int    | 是   | 参考[附录-权限类型码表](#typeDetails)-type列 |
| time    | 通行时间       | Long   | 是   | 时间戳单位秒                                 |
| result  | 通行结果       | Int    | 是   |[ 通行凭证校验码(#result)]                               |
| tag     | 标签（用户名） | String | 否   | 标签（用户名）                               |
| message | 说明           | String | 否   | 失败原因码或具体原因                         |

通行凭证校验码
|结果|说明|
|:-------:|:-------------:|
| 0x00 | 成功|
| 0x01 | 未在白名单|
| 0x02 | 未在白名单白名单有效期内|
| 0x06 | 不在权限时段内|
| 0xFF | 未知错误|

- 请求示例
```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "cmd": "access",
    "data":{
       "code":"123456",
      "type":400,
      "time":1647580466,
      "result":0,
      "tag":"张三",
      "message":"开门成功"
    },
    "time": 1647580466,
    "sign": ""
}
```

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

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

[回到顶部](#category)

# 四. 附录
## 结果码
| 类型 | code | 信息 | 说明 |
| ------------ | ------------- | ---------------------- | ---------------------------------------------------------- |
| 成功 | 000000 | 成功执行指令 | 无 |
| 通用报错 | 100000 | 未知错误 | 无 |
| 通用报错 | 100001 | 设备已被禁用 | 设备禁用后很多指令不允许执行 |
| 通用报错 | 100002 | 设备正忙，请稍后再试 | 设备正在升级、设置网络或其他任务进程中 |
| 通用报错 | 100003 | 签名检验失败 | 无 |
| 通用报错 | 100004 | 超时错误 | 无 |
| 通用报错 | 100005 | 设备离线 | 无 |
| 通用报错 | 100006 | 设备忙 | 无 |
| 通用报错 | 100007 | 内存不足 | 无 |
| 参数异常 | 200000-299999 | 参数异常 | 不同的指令对应不同的参数规范，参考每个接口后的参数异常描述 |
| 参数异常 | 200000 | data参数错误 | |
| 其它异常 | 300000-399999 | 其它已知原因导致的异常 | 不同的指令对应不同的异常，参考每个接口后的参数异常描述 |
| json打包失败 | 300001 | 设备json打牌失败 | |
| 存储报错 | 300002 | 网络配置保存失败 | |
| 存储报错 | 300003 | MQTT配置保存失败 | |
| 存储报错 | 300004 | 蓝牙配置保存失败 | |
| 存储报错 | 300005 | 系统时间配置保存失败 | |
| 存储报错 | 300006 | door配置保存失败 | |
| 存储报错 | 300007 | 数据已存在 | |
| 存储报错 | 300008 | 数据已存满 | |
| 存储报错 | 300009 | 数据存储失败 | |

[回到顶部](#category)

## 配置项

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

| 参数名     | 说明           | 类型   | 可修改 | 备注                          |
| ---------- | -------------- | ------ | ------ | ----------------------------- |
| type       | 网络类型       | Int    | 是     | 0(WiFi)1(以太网)255(禁用网络) |
| ssid       | Wifi名         | String | 是     | wifi名                        |
| pwd        | Wifi密码       | String | 是     | wifi密码                      |
| dhcp       | 是否为DHCP模式 | Int    | 是     | 是否为DHCP(1:动态,0:静态)     |
| ip         | ip地址         | String | 是     | ip地址                        |
| gateway    | 网关           | String | 是     | 网关                          |
| subnetMask | 子网掩码       | String | 是     | 子网掩码                      |
| mac | 子网掩码       | String |否     | 网卡mac                     |

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

| 参数名   | 说明              | 类型   | 可修改 | 备注                                                  |
| -------- | ----------------- | ------ | ------ | ----------------------------------------------------- |
| mqttAddr | Mqtt服务器 ip     | String | 是     | Mqtt地址（ip）                                        |
| mqttPort | Mqtt服务器 端口号 | Int    | 是     | Mqtt地址（端口）                                      |
| clientId | 客户端id          | String | 否    | 客户端id = 设备地址 +随机码|
| mqttName | mqtt用户名        | String | 是     | mqtt用户名                                            |
| password | mqtt密码          | String | 是     | mqtt密码                                              |
| qos      | mqtt qos          | int    | 否     | mqtt qos 取值 0\1\2                                   |

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

| 参数名 | 说明 | 类型 | 可修改 | 备注 |
| ---------- | ---------- | ------ | -------------------------------- | ----------------------- |
| sysTime | unix 时间戳(秒) | Int | 是 |如：1746337157 |
| version | 应用版本号 | String | 否 | 应用版本号 |
| mac | 蓝牙mac | String |否 | |

- `doorInfo` : 设备开门相关配置信息

| 参数名 | 说明 | 类型 | 可修改 | 备注 |
| ---------- | ---------- | ------ | -------------------------------- | ----------------------- |
| alerts | 告警开关 | Int | 是 |告警开关， 0-关闭，1-开启 |
| bellEnable | 门铃开关 | Int | 是 | 0-关闭，1-开启 |
 |

[回到顶部](#category)

## 权限类型说明

| type | type value | 说明                        |
| -------- | ---- | ---------------------------- |
| password | 0 |  密码数据 ，密码长度：6~14位|
| password | 1 |  卡片（NFC）|
| bluetooth | 2 | 蓝牙开门凭证 |
| ID卡 | 4 |    ID卡片 |

## 设备告警类型表
| 类型 | type | value | door |
| -------- | ---- | ---------------------------- | ------------ |
| 密码错误次数过多键盘锁定 | 7 | 无 | 无 |
| 防拆报警 | 9 | 无 | 无 |

[回到顶部](#category)

# 五. 记录
##  协议修改记录

| 版本   | 日期     | 修改人 | 涉及接口 | 修改内容       |
| ------ | -------- | ------ | -------- | -------------- |
| V1.0.0 | 2024.4.2 | 张归麟 | *        | 初始化接口文档 |

##  支持固件版本

| 版本   | 日期     | 发布人 | 更新记录 | 备注       |
| ------ | -------- | ------ | -------- | -------------- |
|S450_V1.2.2 | 2025.10.22 | 余成强 | 初版固件发布        |  |