【广告屏通信协议】

文件修改记录

版本	修改日期	修改描述	修改人员
v1.00	2021-09-17	创建此文档	lyon
V1.01	2021-09-27	增加了广告显示界面接口 增加了视频下载参数	lyon
V1.02	2021-12-22	余位设置里面增加了余位显示开关	lyon
V1.03	2023-09-05	列出了每个接口的参数列表和说明	lyon
V2.0	2023-09-10	增加了无牌车扫码页面 过车/支付/广告 增加了 text_list 参数 增加了空闲强制显示视频/图片接口 增加了亮度自动调节接口	lyon

目录

【广告屏通信协议】 1

概述 4

文档约定 5

• 1. 主题格式 6
  2. 消息格式 7
  3. 业务接口 8

搜索设备-search 9

配置广告-set_advert_config 10

设置余位- set_advert_park_num 13

显示过车界面-start_passing_scene 14

显示支付界面-start_pay_scene 16

显示无牌车扫码界面- start_ulp_scene 18

显示广告界面- start_advert_scene 20

配置MQTT 连接参数- set_mqtt_config 21

配置网络连接参数- set_network_config 22

配置声音参数- set_sound_config 23

配置显示参数- set_display_config 24

修改设备名称- set_device_name 25

概述

本文通信协议是建立在 MQTT 协议基础之上的应用层协议，用来实现服务商与设备、设备与设备之间的数据传输和设备管理等功能。对应用层而言，MQTT 层只是作为数据载体，无需关心 MQTT 层的协议栈，本文只对MQTT 的订阅和发布主题进行了规范，以便于设备管理和枚举，应用层之间是通过JSON 格式化的消息进行交互。

设备端的业务接口包含了停车场基本的三个场景显示界面，分别为空闲广告播放、支付、过车；服务商通过调用业务接口应用于不同的场景；一般的流程如下图所示：

入口场景状态切换图:

扫码登记:

显示预缴费

二维码

无牌车辆

登记完成

异常

人工

放行

确认进场

空闲:

1. 播放广告
2. 显示余位

有牌车辆

接口名称:

start_passing_scene

过车:

1. 开闸
2. 显示问候语

过车落杆

出口场景状态切换图:

支付:

1. 显示停车信息
2. 扫码缴费

临时车辆/无牌车

缴费完成

异常

人工

放行

确认放行

空闲:

播放广告

月租车/VIP车/固定车辆

接口名称：

start_passing_scene

过车:

1. 开闸
2. 显示问候语

过车落杆

文档约定

设备:在本文中特指显示屏主板。

服务商:在本文中特指车场收费管理平台。 MQTT: 基于发布/订阅范式的消息协议。 JSON: 一种轻量级的数据交换格式。

发送方/发布者:在本文中泛指发送消息的一端。接收方/订阅者:在本文中泛指接收消息的一端。

设备 ID/CID/ID:在本文中不加以区分，都表示设备的唯一标识符,做为出厂固化信息，不可修改。注:在本文中，如无特殊说明，所有字符串编码采用UTF8。

主题格式

发送消息-主题格式
	固定	可修改	固定	固定
主题类型	媒体卡标识	车场编码	消息类型	设备 CID 或者分组名称
广播主题	“MC/”	test	“/public/”	“all”
私有主题	“MC/”	test	“/private/”	“E2:4E:80:AB:5E:8E”

广播主题用来 发送消息到同一个组的所有设备，可以用来完成一些公共的配置和搜索功能。私有主题用来 发送独立的业务数据和配置数据到一个监听的设备。

例子:

发送广播消息主题:MC/ test/public/all

发送私有消息主题:MC/ test/private/E2:4E:80:AB:5E:8E

接收消息-主题格式
	固定	不限定
主题类型	媒体卡标识	订阅者的 CID
接收主题	“MC/receiver/”	“12345678”

接收主题用来 接收设备回复的消息。接收方可以通过设备回复的 sender 字段来判断是哪个设备回复的消息。

例子:

接收消息主题:MC/receiver/12345678

消息格式

所有数据交互采用JSON 封装，请参考相关 JSON 格式规范文档。

	名称(key)	类型	可选项
消息类型	“type”	字符串
操作命令	“cmd”	字符串
消息序列	“sn”	整型	可选
发送者 CID	“sender”	字符串	可选
请求时间戳	“request_time”	双字整型	可选
其它数据	xxx	不限定	可选

注:type 和 cmd 字段是必须加的。其它字段根据业务功能选择添加。

如果没有sender 字段，表示是一条匿名消息，设备接收到消息后，不会回复。 request_time 字段表示请求方发送消息时的时间戳，设备接收之后，不会处理该字段， 会原型返回发送者，发送者可以用该字段计算消息响应时间，

响应时间 = 当前时间 – request_time;表达的意义为消息在整个环路的时间总和

（发送时间+ MQTT 服务器转发时间 + 设备处理时间 + 设备返回时间）。例子：

{

“cmd”:”set_sound_config”, “config”:{

“advert_vol”:70, “tts_vol”:80

},

“request_time”:1631868598959, “sender”:”04a81120ddde435794e25e0″, “sn”:44,

“type”:”sys_settings”

}

业务接口

	消息类型	操作命令	功能描述	响应范围
广 播	broadcast	search	搜索设备	广播
显示模板	template	set_advert_config	配置广告	广播/私有
	template	get_advert_config	获取广告配置	私有
	template	set_advert_park_num	设置余位	广播/私有
	template	start_passing_scene	显示过车界面	私有
	template	start_pay_scene	显示支付界面	私有
	template	start_advert_scene	显示广告界面	私有
	template	start_ulp_scene	显示无牌车扫码界面	私有
系统配置	sys_settings	set_mqtt_config	配置 MQTT 连接参数	私有
	sys_settings	set_network_config	配置网络参数	私有
	sys_settings	set_sound_config	配置声音参数	私有
	sys_settings	set_display_config	配置显示参数	私有
	sys_settings	set_device_name	修改设备名称	私有

搜索设备-search

搜索设备只在相同的车场编码的设备有效。请求格式:

{

“cmd”:”search”, “request_time”:1693898863797, “sender”:”e53cc527d7a2486bbbf41ac”, “sn”:5,

“type”:”broadcast”

}

回复格式:

参数说明
参数名称	类型	可选项	功能描述
avr	字符串	固定	设备应用程序版本号
cid	字符串	固定	设备唯一标识符 自动关联到 MAC 地址
device_name	字符串	可选	设备名称标识符
fver	字符串	可选	硬件 FPGA 固件版本
hver	字符串	可选	硬件版本
ip	字符串	可选	设备 IP 地址
model	字符串	可选	设备型号

{

“aver”:”3.0″, “cid”:”AE:63:80:A1:1A:71″,

“cmd”:”search”, “device_name”:”S400″, “error”:”OK”,

“fver”:”1.0″,

“hver”:”S400-F10K-A7-10″,

“ip”:”192.168.0.155″,

“model”:”S400-F10K-A7-10″,

“request_time”:1693898863797, “sender”:”AE:63:80:A1:1A:71″, “sn”:5,

“type”:”broadcast”

}

配置广告-set_advert_config

请求格式:

参数说明
参数名称	类型	可选项	功能描述
forced	BOOL	可选	空闲强制播报视频/图片广告
fshow	BOOL	可选	全屏显示视频/图片广告
media_list 视频/图片广告列表 可选项
enable	BOOL	固定	播放开关
name	字符串	固定	广告文件名称
plan	字符串	可选	时间计划表，可以不用
rewrite	BOOL	可选	如果本地文件存在，是否重新下载
url	字符串	固定	视频或者图片的 http 链接地址
text_list 文字广告列表 可选项
color	整型	固定	包含 4 个参数 a:透明度,取值范围 0~255 r:红色分量,取值范围 0~255 g:绿色分量,取值范围 0~255 b:蓝色分量,取值范围 0~255
text	字符串	固定	显示文本
lid	整型	固定	行号

例子 1：下载视频和图片广告

{

“cmd”:“set_advert_config”, “config”:{

“media_list”:[

{

“enable”:true, “name”:“test1.mp4”, “plan”:{

},

“rewrite”:true, “url”:“https://24359353.s21v.faiusr.com/58/ABUIABA6GAAg_J3LpwYoiL3NiQE.mp4“

},

{

“enable”:true, “name”:“test2.jpg”, “plan”:{

},

“rewrite”:true,

“url”:“https://fuss10.elemecdn.com/3/28/bbf893f792f03a54408b3b7a7ebf0jpeg.jpeg“

}

]

},

“request_time”:1693899117362, “save”:false, “sender”:“e53cc527d7a2486bbbf41ac”, “sn”:7,

“type”:“template”

}

例子 2：下载文字广告

{

“cmd”:”set_advert_config”, “config”:{

“text_list”:[

{

“color”:{

“a”:255,

“b”:0,

“g”:0,

“r”:255

},

“lid”:0,

“text”:”天安门停车场”

},

{

“color”:{

“a”:255,

“b”:0,

“g”:255,

“r”:0

},

“lid”:1,

“text”:”`Y-`M-`D `H:`N:`S”

}

]

},

“request_time”:1694338961537, “save”:true, “sender”:”e1c00e693b794018a5985c1″, “sn”:12,

“type”:”template”

}

例子 3:空闲强制显示视频/图片广告

{

“cmd”:”set_advert_config”, “config”:{

“adv_forced”:true, “adv_fshow”:true

},

“request_time”:1694340176317, “save”:true, “sender”:”e1c00e693b794018a5985c1″, “sn”:15,

“type”:”template”

}

回复格式:

{

“cmd”:”set_advert_config”, “error”:”OK”, “request_time”:1693899117362, “sender”:”AE:63:80:A1:1A:71″, “sn”:7,

“type”:”template”

}

设置余位- set_advert_park_num

请求格式:

参数说明
参数名称	类型	可选项	功能描述
park_number	整型	固定	余位数量
park_number_en	BOOL	固定	余位开关

{

“cmd”:”set_advert_park_num”, “park_number”:0, “park_number_en”:true, “request_time”:1693903077581, “sender”:”e53cc527d7a2486bbbf41ac”, “sn”:10,

“type”:”template”

}

回复格式:

{

“cmd”:”set_advert_park_num”, “error”:”OK”, “request_time”:1693903077581, “sender”:”AE:63:80:A1:1A:71″, “sn”:10,

“type”:”template”

}

显示过车界面-start_passing_scene

请求格式:

参数说明
参数名称	类型	可选项	功能描述
show_time	整型	固定	页面显示时间
voice	字符串	固定	语音播报内容
text_list 文字列表
color	整型	固定	包含 4 个参数 a:透明度,取值范围 0~255 r:红色分量,取值范围 0~255 g:绿色分量,取值范围 0~255 b:蓝色分量,取值范围 0~255
text	字符串	固定	显示文本
lid	整型	固定	行号

{

“cmd”:”start_passing_scene”, “config”:{

“show_time”:10, “text_list”:[

{

“color”:{

“a”:255,

“b”:0,

“g”:0,

“r”:255

},

“lid”:0,

“text”:”月租车”

},

{

“color”:{

“a”:255,

“b”:0,

“g”:255,

“r”:0

},

“lid”:1,

“text”:”粤 B12345″

},

{

“color”:{

“a”:255,

“b”:0,

“g”:255,

“r”:255

},

“lid”:2,

“text”:”欢迎光临”

},

{

“color”:{

“a”:255,

“b”:240,

“g”:240,

“r”:240

},

“lid”:3,

“text”:”请入场停车”

}

],

“voice”:”欢迎光临”

},

“request_time”:1694340652923, “sender”:”e1c00e693b794018a5985c1″, “sn”:16,

“type”:”template”

}

回复格式:

{

“cmd”:”start_passing_scene”, “error”:”OK”, “request_time”:1693903989579, “sender”:”AE:63:80:A1:1A:71″, “sn”:11,

“type”:”template”

}

显示支付界面-start_pay_scene

请求格式:

参数说明
参数名称	类型	可选项	功能描述
show_time	整型	固定	页面显示时间
qrcode	字符串	固定	二维码字符串
voice	字符串	固定	语音播报内容
text_list 文字列表
color	整型	固定	包含 4 个参数 a:透明度,取值范围 0~255 r:红色分量,取值范围 0~255 g:绿色分量,取值范围 0~255 b:蓝色分量,取值范围 0~255
text	字符串	固定	显示文本
lid	整型	固定	行号

{

“cmd”:”start_pay_scene”, “config”:{

“qrcode”:”http://www.baidu.com“, “show_time”:10,

“text_list”:[

{

“color”:{

“a”:255,

“b”:255,

“g”:255,

“r”:255

},

“lid”:0,

“text”:”粤 B12345″

},

{

“color”:{

“a”:255,

“b”:0,

“g”:255,

“r”:0

},

“lid”:1,

“text”:”停车 1 小时 5 分钟”

},

{

“color”:{

“a”:255,

“b”:0,

“g”:255,

“r”:255

},

“lid”:2,

“text”:”请缴费 10 元”

},

{

“color”:{

“a”:255,

“b”:0,

“g”:0,

“r”:255

},

“lid”:3,

“text”:”请扫码支付”

}

],

“voice”:”粤 B12345,停车 1 小时 5 分钟,请缴费 10 元”

},

“request_time”:1694340966220, “sender”:”e1c00e693b794018a5985c1″, “sn”:17,

“type”:”template”

}

回复格式:

{

“cmd”:”start_pay_scene”, “error”:”OK”, “request_time”:1693907825060, “sender”:”AE:63:80:A1:1A:71″, “sn”:12,

“type”:”template”

}

显示无牌车扫码界面- start_ulp_scene

请求格式:

参数说明
参数名称	类型	可选项	功能描述
show_time	整型	固定	页面显示时间
qrcode	字符串	固定	二维码字符串
voice	字符串	固定	语音播报内容
text_list 文字列表
color	整型	固定	包含 4 个参数 a:透明度,取值范围 0~255 r:红色分量,取值范围 0~255 g:绿色分量,取值范围 0~255 b:蓝色分量,取值范围 0~255
text	字符串	固定	显示文本
lid	整型	固定	行号

{

“cmd”:”start_ulp_scene”, “config”:{

“qrcode”:”http://www.baidu.com“, “show_time”:0,

“text_list”:[

{

“color”:{

“a”:255,

“b”:240,

“g”:240,

“r”:240

},

“lid”:0,

“text”:”欢迎光临”

},

{

“color”:{

“a”:255,

“b”:255,

“g”:0,

“r”:0

},

“lid”:1,

“text”:”无牌车请扫码”

},

{

“color”:{

“a”:255,

“b”:0,

“g”:0,

“r”:255

},

“lid”:2,

“text”:””

},

{

“color”:{

“a”:255,

“b”:240,

“g”:240,

“r”:240

},

“lid”:3,

“text”:””

}

],

“voice”:”无牌车,请扫码”

},

“request_time”:1694341166252, “sender”:”e1c00e693b794018a5985c1″, “sn”:18,

“type”:”template”

}

回复格式:

{

“cmd”:”start_ulp_scene”, “error”:”OK”, “request_time”:1694341166252, “sender”:”F2:92:A5:65:7B:16″, “sn”:18,

“type”:”template”

}

显示广告界面- start_advert_scene

该指令用来从其它页面立即切换到空闲广告页面请求格式:

{

“cmd”:”start_advert_scene”, “request_time”:1693908106982, “sender”:”e53cc527d7a2486bbbf41ac”, “sn”:16,

“type”:”template”

}

回复格式:

{

“cmd”:”start_advert_scene”, “error”:”OK”, “request_time”:1693908106982, “sender”:”AE:63:80:A1:1A:71″, “sn”:16,

“type”:”template”

}

配置 MQTT 连接参数- set_mqtt_config

请求格式:

参数说明
参数名称	类型	可选项	功能描述
passwd	字符串	固定	连接密码
port	整型	固定	MQTT 服务器端口号
server_name	字符串	固定	MQTT 服务器地址
user_name	字符串	固定	连接用户名

{

“cmd”:”set_mqtt_config”, “config”:{

“park_code”:”test”,

“passwd”:”1234″, “port”:1883,

“server_name”:”www.erverything-park.com“, “user_name”:”test”

},

“request_time”:1693908404896, “sender”:”e53cc527d7a2486bbbf41ac”, “sn”:19,

“type”:”sys_settings”

}

回复格式:

{

“cmd”:”set_mqtt_config”, “error”:”OK”, “request_time”:1693908404896, “sender”:”AE:63:80:A1:1A:71″, “sn”:19,

“type”:”sys_settings”

}

配置网络连接参数- set_network_config

请求格式:

参数说明
参数名称	类型	可选项	功能描述
dhcp	BOOL	可选	动态分配 IP 地址
gate	字符串	固定	网关地址
ip	字符串	固定	IP 地址
mask	字符串	固定	子网掩码
ntp_server	字符串	可选	授时服务器地址
wifi_en	BOOL	可选	WIFI 开关
wifi_name	字符串	可选	WIFI 名称
wifi_passwd	字符串	可选	WIFI 密码

{

“cmd”:”set_network_config”, “config”:{

“dhcp”:false, “gate”:”192.168.0.1″,

“ip”:”192.168.0.155″,

“mask”:”255.255.255.0″,

“ntp_server”:””, “wifi_en”:false, “wifi_name”:””,

“wifi_passwd”:””

},

“request_time”:1693911459060, “sender”:”e53cc527d7a2486bbbf41ac”, “sn”:22,

“type”:”sys_settings”

}

回复格式:

{

“cmd”:”set_network_config”, “error”:”OK”, “request_time”:1694342014640, “sender”:”F2:92:A5:65:7B:16″, “sn”:21,

“type”:”sys_settings”

}

配置声音参数- set_sound_config

请求格式:

参数说明
参数名称	类型	可选项	功能描述
advert_vol	整型	固定	广告视频音量
tts_vol	整型	固定	文字播报音量

{

“cmd”:”set_sound_config”, “config”:{

“advert_vol”:0, “tts_vol”:30

},

“request_time”:1693911852744, “sender”:”e53cc527d7a2486bbbf41ac”, “sn”:24,

“type”:”sys_settings”

}

回复格式:

{

“cmd”:”set_sound_config”, “error”:”OK”, “request_time”:1693911852744, “sender”:”AE:63:80:A1:1A:71″, “sn”:24,

“type”:”sys_settings”

}

配置显示参数- set_display_config

请求格式:

参数说明
参数名称	类型	可选项	功能描述
brightness	整型	可选项	显示屏最大亮度，取值范围 0~100
bl_min	整型	可选项	最小亮度，取值范围 0~100
bl_auto_night	BOOL	可选项	晚上自动调节亮度
bl_auto_idle	BOOL	可选项	空闲自动调节亮度
bl_start_time	字符串	可选项	晚上自动调节亮度-开始时间,格式:”HH:MM”
bl_end_time	字符串	可选项	晚上自动调节亮度-结束时间,格式:”HH:MM”

{

“cmd”:”set_display_config”, “config”:{

“bl_auto_idle”:true, “bl_auto_night”:true, “bl_end_time”:”08:00:00″, “bl_min”:50, “bl_start_time”:”18:00:00″, “brightness”:100

},

“request_time”:1694341512153, “sender”:”e1c00e693b794018a5985c1″, “sn”:19,

“type”:”sys_settings”

}

回复格式:

{

“cmd”:”set_display_config”, “error”:”OK”, “request_time”:1631877909045, “sender”:”E2:4E:80:AB:5E:8E”, “sn”:14,

“type”:”sys_settings”

}

修改设备名称- set_device_name

请求格式:

参数说明
参数名称	类型	可选项	功能描述
device_name	字符串	固定	设备名称

{

“cmd”:”set_device_name”, “device_name”:”新设备”, “request_time”:1693912535857, “sender”:”e53cc527d7a2486bbbf41ac”, “sn”:27,

“type”:”sys_settings”

}

回复格式:

{

“cmd”:”set_device_name”, “error”:”OK”, “request_time”:1693912535857, “sender”:”AE:63:80:A1:1A:71″, “sn”:27,

“type”:”sys_settings”

}

停车技术员温馨提示：此处有惊喜！