通用网络协议_apipost mqtt-CSDN博客

==》点击此处返回主目录《==

网络协议默认使用json格式，根据 cmd 区分指令类型。以下协议是设备端默认就支持的，服务器需要根据协议进行适配。若需要根据服务器协议定制软件，请先进行商务洽谈。另外，因SIM卡流量有限，有些指令不需要频繁发送，有些字段不需要发送，请尽量节省流量。

以下是一些常用的辅助工具下载：

向日葵远程工具下载：https://sunlogin.oray.com/download?categ=personal

MQTTX 调试下载：https://mqttx.app/zh

ApiPost HTTP 调试工具：https://www.apipost.cn/download.html?utm_source=10039&bd_vid=9737545722984463407

注意：设备上传给服务器的数据，默认通过长连接（MQTT/socket）方式上传，也可以通过配置HTTP 接口用于接收设备上报的数据。HTTP接口请求示例如下：

配置 HTTP 接口的方法：

1、在 ini 写码配置文件中添加以下内容，然后通过写码工具配置到设备中。

ini文件中添加的内容	内容说明
"api":"http://www.testapi.com"	设备端所有回复给服务器的指令都上传到这个http接口中
"api":"{\\\"getpara,qrcode\\\":\\\"http://www.testapi.com\\\"}"	设备端只有getpara,qrcode这两个指令的消息回复上传到这个 http 接口
"api":"{}"	清除已配置的 http 接口

2、通过服务器发送 setpara 指令配置。

setpara指令内容	内容说明
{"cmd":"setpara","api":"http://www.testapi.com"}	设备端所有回复给服务器的指令都上传到这个http接口中
{"cmd":"setpara","api":"{\"getpara,qrcode\":\"http://www.testapi.com\"}"	设备端只有getpara,qrcode这两个指令的消息回复上传到这个 http 接口
{"cmd":"setpara","api":"{}"}	清除已配置的 http 接口

一、TCP/IP 心跳包（heartbeat指令，TCP/IP 服务器必须对接，MQTT服务器不需要对接）

终端上传

示例：{"cmd":"heartbeat","sn":"B002TTSTESTDEVICE001"}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“heartbeat”
sn	字符串	是	设备sn号，唯一标志一个设备

服务器回复

示例： {"cmd":"heartbeat"}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“heartbeat”

心跳包频率默认2分钟一次，设备连上服务器就会发送一条心跳包，只有收到服务器回复才会提示“服务连接成功”，否则会提示“服务连接失败”。

二、获取设备写码参数（getpara指令，必须对接,流量卡充值需要用到 ICCID）

服务器下发

示例：{"cmd":"getpara","full":1}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“getpara”
full	整形	否	为1，则获取完整的MQTT / TCP参数。否则只返回设备ID

终端回复

示例：{
   "cmd": "getpara",
   "type": "3",
   "para": "[B005202104300001,K3ISBNQWQD,nIGVV+R6ZMBS0JcCPN55MA==]",
   "iccid": "89860483262090779731",
   "imsi": "460080338604181",
   "imei": "863586880000009",
   "poweron": "欢迎使用四机收款音箱",
   "poweroff": "谢谢使用",
   "volume": "1(1-7)",
   "batt": 4192,
   "verno": "[TTS]B006_COMMON_1.0.14_XXXX",
   "otakey": "zyGnh14pvFvYZbyW6bSGLBzIHqXO88jg",
   "SimManuID": 0,
   "SimExpire": 1677599999,
   "ProdDate": "2022-09-15"
}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“getpara”
type	字符串	是	服务器类型名称。"0":自建MQTT,"1":阿里云物联网公共实例,"2":百度云物联网,"3":腾讯云物联网,"4":阿里云微消息队列,"5":阿里云物联网私有实例,"6":TCP/IP 服务器,"7":华为云设备接入IoTDA
para	字符串	是	设备联网参数，格式参考《4G设备写码》第4步。
imei	字符串	是	设备imei号码
imsi	字符串	是	SIM卡IMSI号码
iccid	字符串	是	SIM卡 ICCID 号码。（用于SIM卡充值）
poweron	字符串	是	开机铃声
poweroff	字符串	是	关机铃声
volume	字符串	是	当前音量（最小音量-最大音量）
batt	整形	是	当前电量（mv）
verno	字符串	是	软件版本号
SimManuID	整形	否	物联网卡卡商 ID。（涉及公司供应商信息，仅供公司内部识别）
SimExpire	整形	否	物联网卡到期时间戳，东八区时间
ProdDate	字符串	否	音箱的出厂日期

三、语音播报（voice指令，支持中文 TTS 和 MP3文件播报）

服务器下发

TTS示例：{"cmd":"voice","before":"1-YX0","after":"1-YDI","money":"12.34","msg":"微信收款12.34元","speed":50,"msgid":"202210260001"}

MP3示例：{"cmd":"voice","before":"0-收款成功","after":"0-收款结束","money":"45.67","channel":2,"msgid":"202210260002"}

MP3示例：{"cmd":"voice","before":"0-收款成功","after":"0-收款结束","money":"89.01","playAudibleMsg":"PY3-CH8-SHI-CH9-PIT-CH0-CH1-MNY","msgid":"202210260003"}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“voice”
msg	字符串	否	TTS播报的内容，中文字符必须是 UTF8 编码。只要存在该字段，就会使用 TTS 播报，若需要使用 MP3 播报，则不要传该值。
speed	整形	否	TTS播报语速。取值0-100，值越大，语速越快。默认为50。
channel	整形	否	自定义收款渠道语音，比如：0-顾客取消付款,1-收银通收款，2-微信收款，3-支付宝收款。当使用MP3播报时必传。不传msg才生效。
money	字符串	否	收款金额，必须保留2位小数。在有显示屏的项目中,该金额会在显示屏上显示。当需要在显示屏上显示金额时，必须传入该参数。
playAudibleMsg	字符串	否	依次播报指定的MP3文件名称（101.MP3，104.MP3），改协议适用于外语，或中国小语种
before	字符串	否	播报收款金额前播报。取值为中文字符串或MP3文件名。0-TTS播报，1-MP3播报。（B008 版本开始支持）
after	字符串	否	播报收款金额后播报。取值为中文字符串或MP3文件名。0-TTS播报，1-MP3播报。（B008 版本开始支持）
msgid	字符串	否	消息ID，通常不需要传，若当前消息ID与上一个消息ID相同，则认为是同一个消息，终端不重复执行。若不传消息ID ，则音箱播报消息后不回复。

注意：语音播报指令播报优先级为： msg > playAudibleMsg > (channel+money)

终端回复

示例：{"cmd":"voice","sn": "B002COMMONTESTDEVICE","msgid":"202210260003","status":1}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“voice”
sn	字符串	是	mqtt连接时，该字段不传；TCP/IP连接时才传
msgid	字符串	是	消息ID（接收的信息中没有该字段，不回复）
status	字符串	是	1-播报成功，2-播报失败。

四、获取设备位置信息（getloc 指令）

服务器下发

示例:{"cmd":"getloc", "msgid":"202010260003"}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“getloc”
msgid	字符串	否	消息ID，若当前消息ID与上一个消息ID相同，则认为是同一个消息，终端不重复执行。建议用带时间戳的编号赋值

终端回复

示例：{"cmd":"getloc","sn": "B002COMMONTESTDEVICE","lat":"028.2044303","lng":"112.8847263","lbs":[{"lac":"120600609","mnc":"0","rssi":"18","mcc":"460","cid":"29601"},{"lac":"252332421","mnc":"0","rssi":"18","mcc":"460","cid":"29601"},{"lac":"121619222","mnc":"0","rssi":"16","mcc":"460","cid":"29601"},{"lac":"98152263","mnc":"0","rssi":"15","mcc":"460","cid":"29601"},{"lac":"252332422","mnc":"0","rssi":"17","mcc":"460","cid":"29601"},{"lac":"13706903","mnc":"0","rssi":"8","mcc":"460","cid":"29601"}]}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“getloc”
sn	字符串	是	mqtt连接时，该字段不传；TCP/IP连接时才传
lat	字符串	否	根据lbs数据获取到的纬度（注：2.5G流量版本上不会上传该字段）
lng	字符串	否	根据lbs数据获取到的经度（注：2.5G流量版本上不会上传该字段）
lbs	字符串	是	获取经纬度的lbs数据

五、开关控制（switch指令）

服务器下发

示例：{"cmd":"switch", "gpio":[{"pin":4,"flag":1},{"pin":12,"flag":0,"reset":3}],"cam":17,"Blight":0}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“switch”
gpio	Json数组	否	gpio 数组
pin	整形	是	gpio 编号，取值 0—31。注意：gpio口不能随意控制,只能控制硬件预留的gpio口，否则会引起设备工作不正常。（上述示例指令中 4 为黄灯，12 为蓝灯）
flag	整形	是	gpio 开关状态，1-gpio拉高，0-gpio拉低
reset	整形	否	指定多少秒之后，gpio 复位。若不需要复位，则不传该字段（B008版本开始支持）
cam	整形	否	高位：摄像头补光灯开关，0关闭， F最大亮度低位：摄像头扫码频率，0关闭摄像头（json格式不支持16进制整形，需转换为十进制传输）
Blight	整形	否	屏幕背光时间，单位秒，0=>常亮

终端回复

该指令终端不回复

六、设置写码参数（setpara指令，同写码工具）

服务器下发

示例：{
   "cmd": "setpara",
   "para": "B002COMMONTESTDEVICE,3,K3ISBNQWQD,KaUCMeuTMuB7q2n5bcOcsA==",
   "SnSize": 20,
   "cam": 0,
   "sound": "00",
   "poweron": "欢迎使用四机收款云音箱",
   "poweroff": "谢谢使用"
}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“setpara”
para	字符串	否	服务器连接参数，参考《设备参数写码》
SnSize	整形	否	devicename 或 clientid 的字节长度。当 para 不为空时，该字段必须传
campara	字符串	否	摄像头参数,示例："110"。字符1:开关,取值0/1；字符2:补光灯开关,取值0/1; 字符3:扫码"嘀"声开关,取值0/1.
sound	字符串	否	"00": 中文普通话TTS播报，"01": 中文普通话MP3播报
poweron	字符串	否	开机铃声
poweroff	字符串	否	关机铃声
api	字符串	否	摄像头扫码和身份证识别上报的 http 接口。参考下面第八条或第九条说明。
Blight	整形	否	屏幕背光时间（秒）,0-常亮
uart1 uart2	字符串	否	uart串口功能定义，"0"-键盘,"1"-身份证,"2"-摄像头
ttspeed	字符串	否	TTS 播报语速,默认为 "50", 字符串数字，取值0~100
eint	字符串	否	B008版本：外部中断配置，格式："8A([0]下降沿提示\|[1]上升沿提示)" 示例："830([0]\|[1]请扫场所码)"
simExpire	整形	否	SIM卡到期时间。传入任意整数，若传入0，则将SIM卡到期时间重置
vol	字符串	否	取值：当前音量最小音量最大音量；比如 "317"，表示当前音量为3，最小音量为1，最大音量为7.
simtip	整形	否	0：流量卡到期不播报语音提醒；非0-提前30天每次开机提醒，提前10天有数据交互就提醒。
user	字符串	否	当待机界面左上角出现 “商户：未绑定” 时，可通过该字段设置绑定商户的名称，比如：{"cmd":"setpara","user":"音箱厂家"}。该参数在 ini 写码配置文件中对应 “USR” 参数。
ota	字符串	否	在线差分升级版本下载地址，支持 http 和 https，比如："###https://cdn.openluat-luatcommunity.openluat.com/attachment/[VERNO]_V1.0.2.bin"。###为默认格式，[VERNO]会被替换成设备当前版本。假设当前版本为“B008_通用版本_V1.0.1”，则升级的时候版本下载链接为：https://cdn.openluat-luatcommunity.openluat.com/attachment/B008_通用版本_V1.0.1_1.0.2.bin。该链接放入到浏览器中必须能够下载文件“B008_通用版本_V1.0.1_1.0.2.bin”才能够使用，版本名称表示从 1.0.1版本升级到1.0.2版本
restart	字符串	否	重启模式 "00" - 关闭工厂测试模式，正常重启开机 "01" - 关闭工厂测试模式，静默重启。重启后不播报开机铃声，联网提示，直到连接服务器成功，进入正常工作模式。重启时用户无感知

终端回复

{"cmd":"setpara","error":"seterror","sound":"01","para":"0"}

若para参数设置失败，才回复上述信息。

七、二维码识别（qrcode 指令）

服务器下发

示例：

1）音箱扫手机的付款码： {"cmd":"qrcode", "qrpay":"100"}

2）用户手机扫音箱屏幕上的收款码：{"cmd":"qrcode","qrpay":"100","qrdata":"收款二维码内容","msg":"请支付100元","timeout":30}

3）取消支付：{"cmd":"qrcode", "qrpay":"100", "cancel":1}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“qrcode”
qrpay	字符串	是	收款金额。若qrpay=0则用户扫码后需要在手机上输入金额，若qrpay>0则用户扫码后不需要在手机上输入金额
qrdata	字符串	否	屏幕上显示的收款二维码。若不传该字段，则打开音箱的摄像头，扫用户手机上的付款码。
title	字符串	否	收款的字符提示，显示在二维码上方的标题，比如 “请支付100元”，“Pay:100”
before	字符串	否	音箱收款的语音提示，同voice指令，取值为中文字符串或MP3文件名。0-TTS播报，1-MP3播报。最早播报
msg	字符串	否	音箱收款的语音提示，同voice指令，使用 TTS 播报，比如 “请支付100元”
playAudibleMsg	字符串	否	音箱收款的语音提示，同voice指令，使用 MP3 播报，比如 “PY1-CH1-BAI-MNY”
after	字符串	否	音箱收款的语音提示，同voice指令，取值为中文字符串或MP3文件名。0-TTS播报，1-MP3播报。最迟播报
timeout	整形	否	支付超时时间（秒），若为0则一直显示，若不传则默认为屏幕背光时间。支付超时后退回待机界面。若 qrdata 不存在则无效。
cancel	整形	否	需要取消支付，则传1，否则不传

若设备不带数字键盘，服务器可主动下发该指令启动二维码收款。

终端上传（音箱摄像头扫二维码）

示例:{"cmd":"qrcode","sn":"B002COMMONTESTDEVICE","data":"二维码内容base64编码","money":"31.22","msgid":"20220916103030"}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“qrcode”
sn	字符串	是	设备SN号，唯一标志一个设备的 ID
data	字符串	是	摄像头识别的二维码内容 base64 编码。服务器接收到该消息后，需要base64解码才能得到二维码内容。
money	字符串	否	音箱主动识别用户付款码时，通过键盘输入待收取的金额
msgid	字符串	是	消息ID，由当前时间的年、月、日、时、分、秒拼成

默认通过 MQTT / TCP socket 上报，也可以配置 http 接口上报。

八、身份证识别（idcard 指令）

终端上传

示例： {"cmd":"idcard","xb":"男","mz":"汉","cs":"19870608","zz":"广东省深圳市南山区XXXXX","hm": "430112202205183168","qfjg":"南山公安局","yxq1":"20190422","yxq2":"20390422"}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“idcard”
xb	字符串	是	性别
mz	字符串	是	民族
cs	字符串	否	出生日期
zz	整形	否	住址
hm	整形	否	身份证号码
qfjg	字符串	否	签发机关
yxq1	字符串	否	有效期起始日期
yxq2	字符串	否	有效期结束日期

默认通过 MQTT / TCP socket 上报，也可以配置 http 接口上报。

服务器下发

该指令服务器不回复

九、UI 显示（display指令，必须带显示屏才能使用）

服务器下发

示例：

{
"cmd":"display",
"times":0,
"ui":[
{"type":0,"data":"欢迎使用智能云音箱","x":10000,"y":5,"size":32,"color":63519},
{"type":0,"data":"二维码显示","x":40,"y":80,"size":32,"color":65535},
{"type":1,"data":"This is Qrcode","w":100,"x":220,"y":60,"color":63519},
{"type":0,"data":"日期时间显示","x":10000,"y":160,"size":32,"color":2047}, {"type":2,"date":100,"dx":10000,"dy":200,"dsize":28,"dcolor":65504,"time":200,"tx":10000,"ty":200,"tsize":28, "tcolor":65504}
]
}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“display”
times	整形	是	当前界面显示的秒数。0 表示常亮
ui	可选	是	json数组：表示 UI 中需要显示的元素。字符串：显示预设的屏幕，比如 "poweron"，"poweroff", "idle", "volume"
type	整形	是	0：显示字符串，1：显示二维码，2：显示日期时间
data	字符串	是	type=0：待显示的字符串； type=1：二维码的内容
x	整形	是	UI 显示的横向坐标，取值范围 0~320。10000 表示居中显示
y	整形	是	UI 显示的竖向坐标，取值范围 0~240。10000 表示居中显示
w	整形	是	二维码显示的宽度。不能大于屏幕尺寸。
size	整形	是	表示字符串显示的字体大小，必须为偶数
color	整形	否	16位的RGB565颜色值，取值范围0~65535。RGB888换算成RGB565算法：RGB值第一个字节取高五位，第二个字节取高六位，第三个字节取高五位。比如颜色为粉色，RGB888值为(255, 101, 230)，换算成RGB565值为64316（0XFB3C）
date	整形	是	日期显示的格式。 100: 2022年01月05日; 101: 2022/01/05; 102: 2022-01-05
time	整形	是	时间显示格式。 200：12:20 ； 201：12:20:45
dx，dy tx，ty	整形	是	日期显示的坐标，同 x，y 时间显示的坐标，同 x，y
dsize tsize	整形	是	日期显示的字体大小，同 size 时间显示的字体大小，若dx=tx且dy=ty，则使用 dsize
dcolor tcolor	整形	否	日期显示的字体颜色，同 color 时间显示的字体颜色，若dx=tx且dy=ty，则使用 dcolor
scrn	字符串	否	屏幕名称，比如“test”。当ui为json数组时，会将屏幕保存在设备内存中。下次发送"ui"=“test”即可显示，比如：{"cmd":"display","times":0,"ui":"test"}。当ui不存在时，就会删除屏幕，比如：{"cmd":"display","scrn":"test","msgid":"20230303"}。该指令可以用来替换系统预设的界面，比如："poweron","poweroff","idle","volume"
msgid	字符串	否	消息id，当该值不为空时，设备会有消息返回。

终端回复（当不传 msgid 时，终端不做回复）

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“display”
draw	字符串	否	屏幕显示的结果描述。
mem	字符串	否	屏幕保存或删除的结果描述
msgid	字符串	否	消息id，与服务器下发的消息ID一致

以上示例程序，显示效果如下：

十、红外传感器（irs 指令，必须硬件支持）

终端上传

示例：{"cmd":"eint","sn":"XXXXXXXXXX","count":1}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“eint”（旧版本是 “irs”）
sn	字符串	是	设备唯一标志
count	整形	是	取值为大于0的整数，表示检测到红外线的次数

当红外传感器检测到红外线时，会根据系统设置，判断是否上报该指令。

服务器下发

若服务器需要对红外线传感器进行设置，可以下发以下指令。

示例：

新版本: {"cmd":"setpara","eint":"8*A([0]下降沿提示|[1]上升沿提示)"} （B008 版本）

旧版本：{"cmd":"setpara","irs":"8*30(请扫场所码)"}

irs取值中，8 表示gpio8，不可随意更改；30表示每隔30秒上报一次红外数据；(请扫场所码)表示当检测到红外线时音箱的提示语音，若不需要提示可留空,比如 "8*30()"*1

十一、NFC读卡器（nfc 指令）

终端上传

当NFC读卡器读到了数据时，就会使用该指令上报 NFC 数据到服务器

示例：{"cmd":"nfc","sn":"433399156591058565","data":["020000004AF89B2B020804006263646566676869","0201000088012020000005000000000000000000"],"msgid":"20230704095502"}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“nfc”
sn	字符串	是	设备唯一标志
data	json数组	是	前面4个字节为数据头，后面为实际读取到的 NFC 卡数据字节1：指令码02, 表示读卡器读到了卡。字节2：扇区号，表示0扇区，如果读取的是卡号，则传 FF。字节3：扇区块号，该示例表示读取的是0扇区0块的数据，如果读取的是卡号，则传 FF。字节4：结果码，00表示读取成功。01表示密钥不正确读取失败,02 表示其它原因读取失败。示例指令表示成功读取0扇区0块的数据为：4AF89B2B020804006263646566676869；成功读取1扇区0块的数据为：88012020000005000000000000000000
money	字符串	否	音箱主动识别用户付款码时，通过键盘输入待收取的金额
msgid	字符串	是	消息ID，由当前时间的年、月、日、时、分、秒拼成

服务器下发

有的NFC卡读取数据，需要密码，则服务器下发该指令设置NFC卡的读取密码

示例：{"cmd":"nfc","key":["555555555555","111111111111"]}

字段	类型	必选	取值说明
cmd	字符串	是	指令名称，固定取值：“nfc”
key	json数组	是	设备收到该指令后，会依次将数组中的数据通过串口传输给NFC读卡器