CC101标品20211101MQTT协议V3.6（Vbar版本）

# 20211101云设备接口文档

# 1.概述

接口概述：本文档提供一套直接访问设备的接口，用于推送获取设备信息，使用者购买设备后，就可以直接根据接口说明进行自定义开发整套门禁或相关应用系统。接口使用MQTT通信协议，可以对接各种通用的MQTT代理，也可使用我们推荐的MQTT代理。

## 1.1 应用场景

应用场景：当需要对接自己的业务系统时，可以通过使用接口通过MQTT协议直接与设备通讯。
![](/media/202409/6af1ac5beaf34cad986859e9e8cf5a4b5014.png)

## 1.2 特点

接口简单，功能全面，适应绝大部分门禁的应用情景。

# 2.接口文档

## 2.1 说明

接口使用MQTT协议，分为上行与下行：

上行：是指设备上发消息给后台或应用。

下行：是指后台或应用下发消息给设备。

通信中间通过MQTT代理，消息包含消息topic与消息内容，格式如下：

1.消息topic

消息标题,不管是上行还是下行，发送指令和返回指令的规则是"指令"和"指令_reply"。格式如下：

a)  下行：20211101/cmd/{#DeviceAddr}/xxxx

对应的返回指令（上行）：20211101/cmd/xxxx_reply

b)  上行：20211101/event/yyyy

对应的返回指令（下行）：20211101/event/{#DeviceAddr}/yyyy_reply

注：20211101是接口版本的特定标识，cmd表示由后台或应用主动给设备发送指令，event表示设备主动给后台或应用发送消息或触发事件。

2.消息内容

文本格式的消息内容，内容为Json格式

a)  发送消息

发送指令的格式固定，都包含SerianNo、DeviceAddr、Data，如：

```json
{
	"SerialNo" : "6w8keif5g6", //消息序列号,10位字符串，包含的小写字母和数字，必需的，
	"DeviceAddr" : "xxxxxxxx", //设备地址，设备的唯一地址用于通讯时保证设备是有效的设备
	"Data" : //不同的指令对应的Data内容不一样，可以是任何类型，不是必填
 }
```

b)  返回消息

返回消息格式固定都包含SerianNo、DeviceAddr、Result、Message、Data，如：

```json
{
	"SerialNo" : "6w8keif5g6", //消息序列号,10位字符串，包含的小写字母和数字，必需的，用于通讯时确保同步
	"DeviceAddr" : "xxxxxxxx", //设备地址，设备的唯一地址用于通讯时保证设备是有效的设备
	"Result" :0 ,//0表示成功，非0表示失败 
	"Message" : "出错的原因信息或成功的提示信息", //不是必填
	"Data" : //不同的指令对应的Data内容不一样，可以是任何类型，不是必填
}
```

## 2.2 接口列表

### 2.2.1 心跳接口

a)  设备到后台或应用

消息topic: 20211101/event/heartbeat

消息内容：

```json
{
	"SerialNo" : "6w8keif5g6",//消息序列号
	"DeviceAddr" : "xxxxxxxx",  //设备地址
	"Data": {
		"DeviceStatus" : 1, //0-未激活，1-正常，2-禁用
		"DoorSensorState" : 1, //门磁状态，1：门磁开-。0：门磁关
		"FireSensorState" : 1, //火警状态，1：火警开-。0：火警关
    	"DeviceTime" : 1596277728, //设备时间，时间戳（秒）
	}
}
```

b)  后台或应用回馈到设备

消息topic: 20211101/event/{#DeviceAddr}/heartbeat_reply

```json
{
	"SerialNo" : "6w8keif5g6",//消息序列号
	"DeviceAddr" : "xxxxxxxx",  //设备地址
	"Result":0,  //执行结果，0-成功，非0失败
	"Message":""  //原因（可选）
}
```

### 2.2.2 报警接口

a)  设备到后台或应用

消息topic: 20211101/event/alarm

消息内容：

```json
{
	"SerialNo" : "6w8keif5g6",//消息序列号
	"DeviceAddr" : "xxxxxxxx",  //设备地址
	"Data": {
    	"AlarmType" : 1, //报警类型，1：异常开门报警。2：火警，3：开门超时
    	"DeviceTime" : 1596277728, //设备时间，时间戳（秒）
	}
}
```

b)  后台或应用回馈到设备（可选）

消息topic: 20211101/event/{#DeviceAddr}/alarm_reply

```json
{
	"SerialNo" : "6w8keif5g6",//消息序列号
	"DeviceAddr" : "xxxxxxxx",  //设备地址
	"Result":0,  //执行结果，0-成功，非0失败
	"Message":""  //原因（可选）
}
```

### 2.2.3 写标签

a)  后台或应用到设备

消息topic: 20211101/cmd/{#DeviceAddr}/tagwrite

消息内容：

```json
{
	"SerialNo" : "6w8keif5g6",//消息序列号
	"DeviceAddr" : "xxxxxxxx",  //设备地址
	"Data": //可以设置单个标签的值
	{
    	"tag0" :"标签1的值",  
		"tag1" :"标签2的值",  
		"tag2" :"标签3的值",  
		"tag3" :"标签4的值",  
		"tag4" :"标签5的值",  
		"tag5" :"标签6的值",  
		"tag6" :"标签7的值",  
		"tag7" :"标签8的值",  
		"tag8" :"标签9的值", 
		"tag9" :"标签10的值"
	}
}
```

b)  设备回馈到后台或应用

消息topic: 20211101/cmd/tagwrite_reply

```json
{
	"SerialNo" : "6w8keif5g6",//消息序列号
	"DeviceAddr" : "xxxxxxxx",  //设备地址
	"Result":0,  //执行结果，0-成功，非0失败
	"Message":""  //原因（可选）
}
```

### 2.2.4 读标签

a)  后台或应用到设备

消息topic: 20211101/cmd/{#DeviceAddr}/tagread

消息内容：

```json
{
	"SerialNo" : "6w8keif5g6",//消息序列号
	"DeviceAddr" : "xxxxxxxx",  //设备地址
}
```

b)  设备回馈到后台或应用

消息topic: 20211101/cmd/tagread_reply

```json
{
	"SerialNo": "6w8keif5g6",//消息序列号
	"DeviceAddr": "xxxxxxxx",//设备地址
	"Result": 0,//执行结果，0-成功，非0失败
	"Message": "",//原因（可选）
	"Data": {
		"tag0": "标签1的值",
		"tag1": "标签2的值",
		"tag2": "标签3的值",
		"tag3": "标签4的值",
		"tag4": "标签5的值",
		"tag5": "标签6的值",
		"tag6": "标签7的值",
		"tag7": "标签8的值",
		"tag8": "标签9的值",
		"tag9": "标签10的值"
	}
}
```

### 2.2.5 同步秘钥

a)  后台或应用到设备

消息topic: 20211101/cmd/{#DeviceAddr}/secretsync

消息内容：

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Data": {
		"SyncFlag": 1, //同步标识，1-全量，2-增量
		"SecretKeys": [ //密钥数组
			{
				"SecretKeyType": "xxxx", //密钥类型，如RSA, AES等
				"SecretKeyCode": "xxxx", //密钥编码，对应密钥编码，如vguang
				"SecretKeyValue": "xxxx", //密钥值
				"SecretKeyStartTime": 1566277728 //密钥开始时间，时间戳（秒）
				"SecretKeyExpirytime": 1596277728 //密钥过期时间，时间戳（秒）
				"SyncType": 1 //同步类型，当SyncFlag=2时有效，1-增加，2-修改，3-删除，删除时SecretKeyValue、SecretKeyStartTime、SecretKeyExpirytime为可选SecretKeyStartTime存在删除>=SecretKeyStartTime，SecretKeyExpirytime存在删除<=SecretKeyExpirytime
			}, ….
		]
	}
}
```

b)  设备回馈到后台或应用

消息topic: 20211101/cmd/secretsync_reply

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "", //原因（可选）
}
```

### 2.2.6 同步白名单（100条）

a)  后台或应用到设备

消息topic: 20211101/cmd/{#DeviceAddr}/whitelistsync

消息内容：

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Data": {
		"SyncFlag": 1, //同步标识，1-全量，2-增量
		"WhiteLists": [ //白名单数组
			{
				"IdentityType": 101, //身份类型
				"IdentityCode": "xxxxxxxx", //身份标识
				"OrgId": 100, //组织编号，删除白名单时校验 
				"BeginTime": 1596277728, //开始时间，时间戳（秒）
				"EndTime": 1596277728, //结束时间，时间戳（秒）
				"RepeatFlag": 0, //重复标识(小于等于0-不重复，1-每天重复，2-每周重复，3-每月重复，4-周重复规则对应于weekPeriodTime)
				"RepeatBeginTime": 0, //RepeatFlag=1时必传：开始时间为距0点的时间，范围[0,86400]，eg:28800表示当天8点。RepeatFlag=2时必传：开 始时间为周几，eg: 1-周一，2-周二 … 取值[1, 7]。RepeatFlag=3时必传：开始时间为某日，取值[1, 31]。
				"RepeatEndTime": 0, //RepeatFlag=1时必传：结束时间为距0点的时间，范围[0,86400]，eg:28800表示当天8点。RepeatFlag=2时必传：结束时间为周几，eg: 1-周一，2-周二 … 取值[1, 7]。RepeatFlag=3时必传：结束时间为某日，取值[1, 31]。
				"WeekPeriodTime": { //RepeatFlag=4时必传：周重复规则，"HH:MM-HH:MM"，24小时制时分，Eg："08:00-09:30|10:00-11:30", 最多5个时间段。周1~7至少有一天为必传
					"1": "08:00-18:00", //无此项代表周一无权限，"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"
					"2": "08:00-18:00", //同上
					"3": "08:00-18:00", //同上
					"4": "08:00-18:00", //同上
					"5": "08:00-18:00", //同上
					"6": "08:00-18:00", //同上
					"7": "08:00-18:00" //同上
				},
				"Times": 0, //次数(数字)，0-不限，>0,限制次数
				"SyncType": 1 //同步类型，当SyncFlag=2时有效，1-增加，2-修改，3-删除（当为删除时，如果beginTime, endTime<=0，则删除所有符合要求的，不忽略userType、userId；如beginTime>0，则增加条件开始时间beginTime，并匹配userType与userId;如endTime> 0，则增加条件结束时间endTime，并匹配IdentityType与IdentityCode）
			}, ….
		]
	}
}
```

b)  设备回馈到后台或应用

消息topic: 20211101/cmd/whitelistsync_reply

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "", //原因（可选）
}
```

注：身份类型， 101-普通二维码，

102-微光门禁动态码1, 以&mj开头

103-微光门禁动态码2, 以vg://v103开头

104-微光门禁动态码3, 以vg://v104开头

201-Mifare_UltraLight卡,

202-Mifare_One(S50) 卡,

203-Mifare_One(S70) 卡,

204-Mifare_Pro(X) 卡,

205-Mifare_DESFire卡,

206-身份证,

238-其他卡，

505-应急码，以&em开头的二维码

...

客户可根据自己情况选择101、102、103,或定制专用码制(定制码类型4XX)。

Message：失败原因

0：成功

-1：JSON字符串错误

-2：磁盘空间不足

-3：数据库开启事务失败

-4：清空数据库失败

-5：保存失败

-6：修改失败

-7：删除失败

-8：写入数据库出错

### 2.2.7 查询白名单

a)  后台或应用到设备

消息topic: 20211101/cmd/{#DeviceAddr}/whitelistquery

消息内容：

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Data": {
		"IdentityType": 101, //身份类型，可选，如果有则只查询此类
		"IdentityCode": "xxxxxxxx", //身份标识，可选，如果有则只查询此身份标识对应的
		"OrgId": 100, //组织编号，可选，如果有则只查询此类
		"BeginTime": 1596277728, //开始时间，时间戳（秒），可选，如果有则只查询此时间后的
		"EndTime": 1596277728, //结束	时间，时间戳（秒），可选，如果有则只查询此时间前的
		"PageSize": 50, //查询每页记录条数（最大100）
		"CurrentPage": 1 //查询当前页数,从第0页开始
	}
}
```

b)  设备回馈到后台或应用

消息topic: 20211101/cmd/whitelistquery_reply

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "", //原因（可选）
	"Data": {
		"PageSize": 50, //查询结果每页记录条数
		"CurrentPage": 50, //查询结果当前页数
		"PageCount": 3, //查询结果总页数
		"Total": 150, //查询结果记录总条数
		"WhiteLists": [{ //白名单数组
			"IdentityType": 101, //身份类型，505：应急码
			"IdentityCode": "xxxxxxxx", //身份标识
			"OrgId": 100, //组织编号
			"BeginTime": 1596277728, //开始时间，时间戳（秒）
			"EndTime": 1596277728, //结束时间，时间戳（秒）
			"Times": 0 //次数(数字)，0-不限，>0,限制次数
		}, …]
	}
}
```

### 2.2.8 上报通行记录

a)  设备到后台或应用

消息topic: 20211101/event/reportrecord

消息内容：

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Data": [{
		"IdentityType": 101, //身份类型
		"IdentityCode": "xxxxxxxx", //身份标识
		"OriginalCode": "xxxxxxxx", //原始数据
		"PassTime": 1596277728 //通行时间，时间戳（秒） 
		"DeviceId": "001-A", //设备标识
		"Result": 0 //通行验证结果，=0-成功 <0失败
		"Message": "xxx" //1表示常开状态，2表示常闭状态,扫描没通过”
	}, …]
}
```

b)  后台或应用回馈到设备

消息topic: 20211101/event/{#DeviceAddr}/reportrecord_reply（可选）

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "" //原因（可选）
}
```

### 2.2.9 在线验证

a)  设备到后台或应用

消息topic: 20211101/event/onlinecheck

消息内容：

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Data": {
		"IdentityType": 101, //身份类型
		"IdentityCode": "xxxxxxxx", //身份标识
		"OriginalCode": "xxxxxxxx", //原始数据
		"PassTime": 1596277728 //通行时间，时间戳（秒）
	}
}
```

b)  后台或应用回馈到设备

消息topic: 20211101/event/{#DeviceAddr}/onlinecheck_reply

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "" //原因（可选）
}
```

### 2.2.10 控制设备

a)  后台或应用到设备

消息topic:  20211101/cmd/{#DeviceAddr}/controldevice

消息内容：

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Data": {
		"HintType": 1 //控制类型，1-开门， 100-重启
	}
}
```

b)  设备回馈到后台或应用

消息topic: 20211101/cmd/controldevice_reply

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "" //原因（可选）
}
```

### 2.2.11 查询设备状态

a)  后台或应用到设备

消息topic: 20211101/cmd/{#DeviceAddr}/getstatus

消息内容：

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx" //设备地址
}
```

b)  设备回馈到后台或应用

消息topic: 20211101/cmd/getstatus_reply

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "", //原因（可选）
	"Data": {
		"DeviceName": "001-A", //设备名称
		"DeviceMode": "xxxxxxxx", //设备型号
		"Scanner1Ver": "xxxxxxxx", //设备型号
		"Scanner2Ver": "xxxxxxxx", //设备型号
		"DeviceNetType": 2, //设备网络类型，1-WIFI，2以太网（默认固定）    "DeviceVer" : "xxxxxxxx",  //设备版本
		"OpenMode": 0, //设备开门模式，0-正常，1-常开模式，2-常闭模式
		"OpenTime": 5, //开门时长，单位秒
		"HeartbeatInterval": 60, //心跳间隔，小于等于0，表示关闭心跳
		"TimeSyncInterval": 43200, //主动时钟更新间隔时间，单位秒，缺省43200秒（12小时），如果小于等于0，表示不主动更新
		"DeviceStatus": 1, //0-未激活，1-正常，2-禁用
		"DeviceTime": 1596277728, //设备时间，时间戳（秒）
		"DeviceSpace": 1000000, //设备剩余空间(单位字节)
		"DeviceWhitelistCount": 5000, //白名单总数量
		"DevicePassRecordCount": 5000, //未上传通行记录总数
		"ScanInterval": 1000, //扫码间隔单位毫秒（ms）
		"RecordUploadStrategy": 0, //0：通行优先， 1：上传优先
		"CheckMode": 0, //0：只离线验证，1：先离线验证失败后走在线验证
		"FaultTolerantTimeInterval": 5, //容错时间间隔小时（h）为0时表示禁用动态调整，如每隔5h时间容错增加1秒
		"MaxFaultTolerantTime": 60, //最大容错时间秒（s），如当容错时间达到60s时停止增加
		"AnalogCard": 1, //1：屏蔽手机模拟卡， 0：不屏蔽手机模拟卡
		"DevGroup": 123, //设备分组用于应急码组校验
		"DeviceId": 123, //设备ID用于应急码设备ID校验
		"EmKey": "078571e7c65de78e818ff3083a4814e2" //应急码秘钥
		"MotorKeepTime": 0, //持续工作时间（毫秒）
		"BlockNum": 0, //读取的块 
		"BlockKey": "", //扇区秘钥
		"BlockKeyType": 96, //扇区秘钥类型
		"DoorSensorState": 1, //门磁状态，1：门磁开-。0：门磁关
		"FireSensorState": 1 //火警状态，1：火警开-。0：火警关
	}
}
```

### 2.2.12 设置设备状态

a)  后台或应用到设备

消息topic: 20211101/cmd/{#DeviceAddr}/setstatus

消息内容：

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Data": {
		"DeviceName": "001-A", //设备名称
		"DeviceStatus": 1, //0-未激活，1-正常，2-禁用
		"OpenMode": 0, //设备开门模式，0-正常，1-常开模式，2-常闭模式，3-任意码（卡）开门
		"OpenTime": 1000, //开门时长，单位毫秒
		"OpenTimeout": 30, //开门超时时长，单位秒
		"HeartbeatInterval": 60, //心跳间隔，小于等于0，表示关闭心跳
		"TimeSyncInterval": 43200, //主动时钟更新间隔时间，单位秒，缺省43200秒（12小时），如果小于等于0，表示不主动更新
		"ScanInterval": 1000, //扫码间隔单位毫秒（ms）
		"RecordUploadStrategy": 0, //0：通行优先， 1：上传优先
		"CheckMode": 0, //0：只离线验证1：先离线验证失败后走在线验证
		"FaultTolerantTimeInterval": 5, //容错时间间隔小时（h）为0时表示禁用动态调整，如每隔5h时间容错增加1秒
		"MaxFaultTolerantTime": 60, //最大容错时间秒（s），如当容错时间达到60s时停止增加
		"AnalogCard": 1, //1：屏蔽手机模拟卡， 0：不屏蔽手机模拟卡
		"DevGroup": 123, //设备分组用于应急码组校验
		"DeviceId": 123, //设备ID用于应急码设备ID校验
		"EmKey": "078571e7c65de78e818ff3083a4814e2", //应急码秘钥"MotorKeepTime" :0, //持续工作时间（毫秒）
		"BlockNum": 0, //读取的块 
		"BlockKey": "FFFFFFFFFFFF", //扇区秘钥
		"BlockKeyType": 96, //扇区秘钥类型（96=A密钥，97B密钥）
	}
}
```

b)  设备回馈到后台或应用

消息topic: 20211101/cmd/setstatus_reply

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "", //原因（可选）
}
```

### 2.2.13 同步时钟

a)  后台或应用到设备

消息topic: 20211101/cmd/{#DeviceAddr}/timesync

消息内容：

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Data": {
		"DeviceTime": 1596277728 //设备时间，时间戳（秒）
	}
}
```

b)  设备回馈到后台或应用

消息topic: 20211101/cmd/timesync_reply

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "" //原因（可选）
}
```

### 2.2.14 更新固件

a)  后台或应用到设备

消息topic: 20211101/cmd/{#DeviceAddr}/updatefirmware

消息内容：

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Data": {
		"FirmwareType": 1, //固件类型，1：控制板，2：下位机1（扫码器），3：下位机2（扫码器）
		"FirmwareUrl": "http://xxx.xxx.xxx/", //固件文件下载地址
		"FirmwareMd5": "xxxxxxxxxx" //固件文件MD5值
	}
}
```

b)  设备回馈到后台或应用

消息topic: 20211101/cmd/updatefirmware_reply

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "" //原因（可选）
}
```

### 2.2.15 查询设备日志

a)  后台或应用到设备

消息topic: 20211101/cmd/{#DeviceAddr}/extractlog

消息内容：

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "" //原因（可选）
}
```

b)  设备回馈到后台或应用

消息topic: 20211101/cmd/extractlog_reply

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "", //原因（可选）
	"Data": "Feb  5 09:16:58 vbar: verify_analysis_nfc_offline_check()|82| ERR: nfc offline check failed, identityType: 204, identityCode: cdb332be\n"
}
```

### 2.1.16 设备状态变化通知

a)  设备到后台或应用

消息topic: 20211101/event/statechanged

消息内容：

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx" //设备地址
	"Data": {
		"StateType": 1, //1：表示门磁状态类型，对应的StateValue支持：0：关门，1：开门。2：表示火警状态类型，对应的StateValue支持：0：无火警。1：有火警；3表示时控开关的状态，对应的StateValue支持：0：关闭，1：打开。
		"StateValue": 1, //状态变化的值
		"Time": 1596277728, //状态变化时间，时间戳（秒）
	}
}
```

b)  后台或应用回馈到设备（可选）

消息topic: 20211101/event/{#DeviceAddr}/statechanged_reply

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "" //原因（可选）
}
```

### 2.2.17 设置网络和MQTT

a)  后台或应用到设备

消息topic: 20211101/cmd/{#DeviceAddr}/setnetwork

消息内容：

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Data": {
		"Net": {
			"NetType": 1, //1-WIFI, 2-ETH *只有设备支持此网络类型时才可以配置成功, 此为必填项
			"SSID": "Vguang_JS",
			"PWD": "vguangjs_o0",
			"DHCP": true, //true-动态, false-静态, 此为必填项
			"IP": "192.168.2.236",
			"Gateway": "192.168.2.1",
			"DNS": "114.114.114.114",
			"Mask": "255.255.255.0"
		},
		"Mqtt": {
			"Addr": "123.207.152.144:61613",
			"ClientId": "xxx", //不填需要删掉
			"UserName": "admin",
			"Password": "password"
		}
	}
}
```

b)  设备回馈到后台或应用

消息topic: 20211101/cmd/setnetwork_reply

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "", //原因（可选）
}
```

### 2.2.18 控制时控开关（仅共享茶室固件支持）

a)  后台或应用到设备

消息topic: 20211101/cmd/controltimeswitch

消息内容：

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx" //设备地址
	"Data": {
		"TswitchMode": 0, //，0-常关，1-常开，2-开动作模式 3-关动作模式
		"TswitchTime": 1000, //正常模式下，开门时长，单位秒
	}
}
```

b)  设备回馈到后台或应用

消息topic: 20211101/cmd/{#DeviceAddr}/controltimeswitch_reply

```json
{
	"SerialNo": "6w8keif5g6", //消息序列号
	"DeviceAddr": "xxxxxxxx", //设备地址
	"Result": 0, //执行结果，0-成功，非0失败
	"Message": "" //原因（可选）
}
```
# 3.版本变更记录表

| 版本号 | 日期 | 修改人 | 涉及接口 | 修改内容 |
| ------ | ---- | ------ | -------- | ------------------------------------------------------------ |
| V3.0 | | | | 新增协议文档 |
| V3.1 | | | | 1.秘钥增加开始时间 2.查询设备增加下位机扫码器版本号 3.设置设备状态增加DeviceStatus字段，devGroup 和 DeviceId 改为数字类型 |
| V3.2 | | | | 查询\设置设备状态增加设置设备名称 |
| V3.3 | | | | 通行记录增加子设备ID，DeviceId |
| V3.4 | | | | 1.增加设备状态变化上报接口 2.获取设备状态接口增加门\火警状态 3.心跳接口增加门\火警状态 |
| V3.5 | | | | 1.设备状态变化通知中添加时控开关状态变化的通知 2.新增设备网络和MQTT |
| V3.6 | | | | |