云端通讯协议 - MQTT - 《终端开放对接文档（MQTT HTTP）》

协议
- 发送数据及示例
- 回复数据及示例
支持的业务场景
云端推送数据至设备
设备发送数据至云端">设备发送数据至云端
- 通行记录上报">通行记录上报
- 异常日志上报
设备配置清单
- 核验方式清单

协议

设备端根据 HTTP注册时获得的MQTT配置信息建立连接，订阅云端消息使用主题 down_topic，上报数据使用主题 up_topic。

消息传输采用JSON数据格式。

发送数据及示例

参数	数据类型	是否必填	说明
biz	string	是	业务类型
id	string	是	数据包ID，消息回复时需要携带该ID
data	object	否	数据包内容
time	int	是	推送时间

{
    "biz":"relay_out", 
    "id":"146548481", 
    "data": {}, 
    "time":1631518842
}

回复数据及示例

参数	数据类型	是否必填	说明
biz	string	是	业务类型
id	string	是	数据包ID，和云端推送的数据包ID保持一致，表示对该消息的应答
data	object	否	数据包内容
time	int	是	设备端当前时间戳
code	int	是	响应码，0表示成功，其它表示异常
msg	string	是	响应信息，异常为具体异常内容

{
    "biz":"relay_out",
    "id":"146548481",
    "data": {}, 
    "time":1631518842, 
    "code": 0,
    "msg": "" 
}

支持的业务场景

	指令类型	编码	备注
云端推送数据至设备	白名单下发	persons	增量下发白名单到设备
	继电器输出（开门）	relay_out	适用于远程开门，远程推送继电器信号
	获取设备信息及配置	get_config	获取设备的配置信息
	修改设备配置	set_config	远程修改设备的配置，具体参考如下清单
	重启	restart	远程重启设备
	OTA升级	upgrade	远程升级软件版本
	运营广告	ad	设备开启广告模式时，推送广告播放内容
	恢复出厂设置	recovery	清空设备端白名单数据，配置恢复至默认状态
设备发送数据至云端	通行记录上报	records	上报各种核验方式的通行结果
	异常日志上报	exception	设备运行异常时，上报日志

云端推送数据至设备

推送继电器动作（开门）

发送数据及示例

参数	数据类型	是否必填	说明
delay	int	是	延时秒数，一般为 5 秒

{ 
    "biz":"relay_out",
    "id":"146548481",
    "data": {
        "delay":5
    }, 
    "time":1631518842 
}

回复数据及示例

{
    "biz":"relay_out",
    "id":"146548481",
    "data": {}, 
    "time":1631518842, 
    "code": 0,
    "msg": "" 
}

白名单下发

发送数据及示例

参数	子参数	数据类型	是否必填	说明
inserts		array	是	新增或更新人员的ID集合
	id	string	是	人员ID，服务端确保唯一性
	name	string	是	姓名
	picture	string	否	图片地址(推荐)或人员图片base64编码
	password	string	否	密码开门时必填，只有设备支持密码时下发
	ic_card	string	否	刷IC卡时必填，多张卡时使用英文逗号拼接
	id_card	string	否	刷身份证必填，只有设备支持身份证时下发
	start_time	int	是	有效期 — 起始时间，Unix时间戳
	end_time	int	是	有效期 — 截止时间，Unix时间戳
	floor	string	否	人员楼层信息，如有多个楼层，用逗号分隔，如 5,6 则具有5层和6层的梯控权限。
deletes		array	是	删除人员的ID集合

{
    "biz": "persons",
    "id": "146548481",
    "data": {
        "inserts": [
            {
                "id": "123",
                "name": "123",
                "start_time": 123,
                "end_time": 123,
                "picture": "https://host.apic.jpg"
            },
            {
                "id": "1234",
                "name": "1234",
                "start_time": 123,
                "end_time": 123,
                "ic_card": "001234,002234,003234",
                "floor": "1,5,22"
            }
        ],
        "deletes": [
            "123",
            "223"
        ]
    },
    "time": 1631518842
}

回复数据及示例

人脸注册失败时会返回face字段

{
    "biz": "persons",
    "id": "146548481",
    "data": {
        "face": [
            {
                "personId1": "人脸注册失败, 图片下载失败"
            },
            {
                "personId2": "人脸注册失败, 未识别到人脸"
            }
        ]
    },
    "time": 1631518842,
    "code": 0,
    "msg": ""
}

获取设备信息及配置

发送数据及示例

{
    "biz":"get_config", 
    "id":"146548481", 
    "data": {}, 
    "time":1631518842
}

回复数据及示例

配置项参考《设备配置清单》

{ 
    "biz":"get_config",
    "id":"146548481",
    "data": { 
        "common": { 
            "device_name":"幸福家园" 
        },
        "system": { 
            "volume":5 
        }, 
        "function": { 
            "face_open":1,
        }
    }, 
    "time":1631518842, 
    "code": 0, 
    "msg": "" 
}

修改设备配置

发送数据及示例

配置项参考《设备配置清单》

{ 
    "biz":"set_config", 
    "id":"146548481", 
    "data": {
        "common": { 
            "device_name":"幸福家园" 
        }, 
        "system": { 
            "volume":5 
        }, 
        "function": { 
            "face_open":1,
        } 
    }, 
    "time":1631518842 
}

回复数据及示例

{
    "biz":"set_config",
    "id":"146548481",
    "time":1631518842,
    "code": 0,
    "msg": ""
}

重启

发送数据及示例

{ 
    "biz":"restart", 
    "id":"146548481", 
    "data": {},
    "time":1631518842
}

回复数据及示例

{ 
    "biz":"restart", 
    "id":"146548481",
    "time":1631518842, 
    "code": 0,
    "msg": "" 
}

OTA升级

发送数据及示例

参数	数据类型	是否必填	说明
url	string	是	升级包地址
version	string	是	待升级的版本号

{ 
    "biz":"upgrade",
    "id":"146548481",
    "data": { 
        "url":"https//ganlin.com/download/xx.apk", 
        "version":"1.1.0" 
    }, 
    "time":1631518842 
}

回复数据及示例

{ 
    "biz":"upgrade",
    "id":"146548481",
    "time":1631518842, 
    "code": 0, 
    "msg": "" 
}

运营广告

发送数据及示例

参数	子参数	数据类型	是否必填	说明
list		array	是	本次广告推送的数据，支持批量
	ad_id	string	是	广告ID，保证唯一性
	duration	int	是	广告播放时长，默认 5 秒
	start_time	int	是	广告投放开始时间
	end_time	int	是	广告投放截止时间
	type	int	是	广告内容类型 1：图片 2：视频
	url	string	是	广告素材的地址
	enable	int	是	是否可用，如果不可用，客户端删除广告
	volume�	float	否	视频广告音量0-1

{ 
    "biz":"ad", 
    "id":"146548481", 
    "data": { 
        "list": [ 
            { 
                "ad_id":"123456789", 
                "duration":5, 
                "start_time": 1631605242, 
                "end_time": 1631608842, 
                "type":1, 
                "url": "https://ganlin.com/1.png", 
                "enable":1 
            }, 
            { 
                "ad_id":"123456780", 
                "duration":5, 
                "start_time": 1631605242, 
                "end_time": 1631608842, 
                "type":2, 
                "url": "https://ganlin.com/2.mp4", 
                "enable":1,
                "volume": 0,
            } 
        ] 
    }, 
    "time":1631518842
}

回复数据及示例

{
    "biz":"ad", 
    "id":"146548481",
    "data": {}, 
    "time":1631518842, 
    "code": 0, 
    "msg": "" 
}

恢复出厂设置

设备执行该指令将配置还原到默认配置，清除白名单数据。

发送数据及示例

{ 
    "biz":"recovery",
    "id":"146548481",
    "data": {},
    "time":1631518842
}

回复数据及示例

{
    "biz":"recovery",
    "id":"146548481",
    "time":1631518842,
    "code": 0,
    "msg": ""
}

设备发送数据至云端

通行记录上报

发送数据及示例

参数	子参数	子参数	数据类型	是否必填	说明
records			array	是	记录数据
	id		int	是	记录ID
	person_id		string	是	人员ID
	name		string	是	人员姓名
	picture		string	否	抓拍的图片base64编码
	password		string	否	密码开门时必填
	ic_card		string	否	刷卡时IC卡号
	id_card		string	否	刷身份证时身份证号
	time		int	是	设备端通行的时间，Unix时间戳
	type		int	是	验证类型 (见下方核验方式清单)
	result		int	是	通行验证结果 0：正常通过 1：陌生人，无法通行 2：已过期 3：未到访问时间 4：超出访问次数
	gauze		int	否	口罩识别情况 0：不检测 1：无口罩 2：有口罩 3：无口罩可通行
	temperature		float	否	体温
	health		object	否	健康码情况
		qr_color	string	否	green：绿码 yellow：黄码 red：红码 gray：灰码 unknown：未知
		nucleic_result	int	否	核酸检测结果，1：阴性 2：阳性
		nucleic_time	int	否	核酸检测时间，Unix时间戳
		inoculate	string	否	疫苗接种情况
		trip	string	否	近14天行程

{
    "biz":"records",
    "id":"146548481",
    "data": {
        "records": [
            {
                "id":1,
                "person_id":"12345678",
    "picture":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyM",
                "password":"",
                "ic_card":"",
                "id_card":"",
                "type":1,
                "time":1631518842,
                "result":0,
                "gauze":0,
                "temperature":36.523
            }
        ]
    },
    "time":1631518842
}

回复数据及示例

只上报，云端收到该消息不做回复。

异常日志上报

发送数据及示例

参数	数据类型	是否必填	说明
type	string	是	异常类型 storage_alert：存储预警 remove：设备被拆除 camara_damage：摄像头损坏 temp_high：温度过高
description	string	否	异常描述
time	int	是	异常发生时间

回复数据及示例

只上报，云端收到该消息不做回复。

设备配置清单

该配置可以通过“获取设备信息及配置”获取，也可通过“修改设备配置”远程进行修改。

类别	字段名	子参数	数据类型	说明	备注
通用 common	device_name		string	设备名称
	open_voice		string	开门提示语音, 可动态替换: 姓名, 体温	默认：请进, 动态: {姓名},请通行, 当前体温: {体温}
	tip_voice		string	靠近提示音	(已忽略)
	io_type		int	进出类型	1: 进, 2: 出
系统 system	volume		float	设备音量
	relay		int	继电器延时关闭时间	默认: 5
功能 function	verify_user		int	是否验证用户白名单	默认：0
	pic_take�		int	人脸抓拍	默认: 0
	led_open�		int	是否开启补光灯�	默认：1
	face_open		int	是否开启人脸识别	默认：1
	face_check�		int	是否开启人脸检测	默认：0
	live_check��		int	是否开启活体检测	默认：0
	call_talk�		int	是否支持呼叫对讲�	默认：1
	display_ad		int	是否开启广告模式	默认：1
	fnVerifyMode�		array	核验方式, (见下方核验方式清单)	默认: [1,3,7]
	call_mode�		array	支持的对讲模式	默认：[]
	face_card_compare		int	是否开启人证比对	默认：0
	health_code		int	健康码核验	0：关闭 1：只查验全部放行 2：仅绿码通行 3：仅绿码+24小时核酸通行 4：仅绿码+48小时核酸通行 5：仅绿码+72小时核酸通行
	health_api		object	健康码接口相关配置	默认：0，开启健康码核验才会有此项值
		region	string	地区，湖北：hubei
		platform	string	调用平台标识
		app_id		调用App ID
		app_secret		调用App 密钥

核验方式清单

1：IC卡
2：蓝牙
3：刷二维码
4：远程
5：人脸识别
6：扫描二维码
7：密码
8：身份证
9：指纹
10：刷健康码