网络协议默认使用json格式，根据 cmd 区分指令类型。以下协议是设备端默认就支持的，服务器需要根据协议进行适配。若需要根据服务器协议定制软件，请先进行商务洽谈。另外，因SIM卡流量有限，有些指令不需要频繁发送，有些字段不需要发送，请尽量节省流量。
以下是一些常用的辅助工具下载：
向日葵远程工具下载：https://sunlogin.oray.com/download?categ=personal
MQTTX 调试下载：https://mqttx.app/zh
ApiPost6 HTTP 调试工具：https://www.apipost.cn/download.html?utm_source=10039&bd_vid=9737545722984463407
一、TCP/IP 心跳包（TCP/IP 服务器必须对接，MQTT服务器不需要对接）
终端上传
示例：{"cmd":"heartbeat","sn":"B002TTSTESTDEVICE001"}
| 字段 | 类型 | 必选 | 取值说明 |
| cmd | 字符串 | 是 | 指令名称，固定取值：“heartbeat” |
| sn | 字符串 | 是 | 设备sn号，唯一标志一个设备 |
服务器回复
示例： {"cmd":"heartbeat"}
| 字段 | 类型 | 必选 | 取值说明 |
| cmd | 字符串 | 是 | 指令名称，固定取值：“heartbeat” |
心跳包频率默认2分钟一次，设备连上服务器就会发送一条心跳包，只有收到服务器回复才会提示“服务连接成功”，否则会提示“服务连接失败”。
二、获取设备写码参数（必须对接,流量卡充值需要用到 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"
}
| 字段 | 类型 | 必选 | 取值说明 |
| cmd | 字符串 | 是 | 指令名称，固定取值：“setpara” |
| 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 | 字符串 | 是 | 软件版本号 |
三、语音播报（支持中文 TTS 和 MP3文件播报）
服务器下发
TTS示例：{"cmd":"voice","before":"YX0","after":"YDI","money":"12.34","msg":"微信收款12.34元","speed":50,"msgid":"202210260001"}
MP3示例：{"cmd":"voice","before":"收款成功","after":"收款结束","money":"45.67","channel":2,"msgid":"202210260002"}
MP3示例：{"cmd":"voice","before":"收款成功","after":"收款结束","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文件名。 |
| after | 字符串 | 否 | 播报收款金额后播报。取值为中文字符串或MP3文件名。 |
| 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-播报失败。 |
四、设置设备参数
服务器下发
示例：{"cmd":"setting","poweron":"欢迎使用万能收款播报机", "poweroff":"谢谢使用","volume":"inc","ttsspeed":50,"msgid":"202010260002"}
| 字段 | 类型 | 必选 | 取值说明 |
| cmd | 字符串 | 否 | 指令名称，固定取值：“setting” |
| poweron | 字符串 | 否 | 设备开机铃声，中文字符编码必须是 UTF8 编码，若poweron=""，则清空设置，使用默认铃声 |
| poweroff | 字符串 | 否 | 设备关机铃声，中文字符编码必须是 UTF8 编码，若poweroff=""，则清空设置，使用默认铃声 |
| volume | 字符串 | 否 | 设置音量。inc-音量递增，dec-音量递减，1~7-数字直接指定音量等级 |
| ttsspeed | 整形 | 否 | 语音播报速度，取值0~100（注：有的设备型号上无效） |
| msgid | 字符串 | 否 | 消息ID，若当前消息ID与上一个消息ID相同，则认为是同一个消息，终端不重复执行。建议用带时间戳的编号赋值 |
终端回复
示例：{"cmd":"setting","sn": "B002COMMONTESTDEVICE","poweron":1,"poweroff":1,"volume":1,"ttsspeed":1}
| 字段 | 类型 | 必选 | 取值说明 |
| cmd | 字符串 | 是 | 指令名称，固定取值：“setting” |
| sn | 字符串 | 是 | mqtt连接时，该字段不传；TCP/IP连接时才传 |
| poweron | 整形 | 否 | 1-开机铃声设置成功，0-开机铃声设置失败 |
| poweroff | 整形 | 否 | 1-关机铃声设置成功，0-关机铃声设置失败 |
| volume | 整形 | 否 | 0-音量设置失败, 1~7 - 音量设置成功，返回对应音量等级。 |
| ttsspeed | 整形 | 否 | 1-语速设置成功，0-语速设置失败（注：有的设备型号上无效） |
五、获取设备位置信息
服务器下发
示例:{"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 | 字符串 | 是 | 指令名称，固定取值：“setting” |
| sn | 字符串 | 是 | mqtt连接时，该字段不传；TCP/IP连接时才传 |
| lat | 字符串 | 否 | 根据lbs数据获取到的纬度（注：2.5G流量版本上不会上传该字段） |
| lng | 字符串 | 否 | 根据lbs数据获取到的经度（注：2.5G流量版本上不会上传该字段） |
| lbs | 字符串 | 是 | 获取经纬度的lbs数据 |
六、开关控制
服务器下发
示例：{"cmd":"switch", "gpio":[{"pin":4,"flag":1},{"pin":12,"flag":0}],"cam":17,"Blight":0}
| 字段 | 类型 | 必选 | 取值说明 |
| cmd | 字符串 | 是 | 指令名称，固定取值：“switch” |
| gpio | Json数组 | 否 | gpio 数组 |
| pin | 整形 | 是 | gpio 编号，取值 0—31。注意：gpio口不能随意控制,只能控制硬件预留的gpio口，否则会引起设备工作不正常。（上述示例指令中 4 为黄灯，12 为蓝灯） |
| flag | 整形 | 是 | gpio 开关状态，1-gpio拉高，0-gpio拉低 |
| cam | 整形 | 否 | 高位：摄像头补光灯开关，0关闭， F最大亮度 低位：摄像头扫码频率，0关闭摄像头 （json格式不支持16进制整形，需转换为十进制传输） |
| Blight | 整形 | 否 | 屏幕背光时间，单位秒，0=>常亮 |
终端回复
该指令终端不回复
七、设置写码参数（同写码工具）
服务器下发
示例：{
"cmd": "setpara",
"para": "B002COMMONTESTDEVICE,3,K3ISBNQWQD,KaUCMeuTMuB7q2n5bcOcsA==",
"SnSize": 20,
"scanfreq": 0,
"sound": "00",
"poweron": "欢迎使用四机收款云音箱",
"poweroff": "谢谢使用"
}
| 字段 | 类型 | 必选 | 取值说明 |
| cmd | 字符串 | 是 | 指令名称，固定取值：“setpara” |
| para | 字符串 | 否 | 写码参数，参考《4G设备写码》第4步 |
| SnSize | 整形 | 否 | devicename 或 clientid 的字节长度。当 para 不为空时，该字段必须传 |
| scanfreq | 整形 | 否 | 重复扫码的频率。若大于0，则打开摄像头。等于0则关闭摄像头 |
| sound | 字符串 | 否 | "00": 中文普通话TTS播报，"01": 中文普通话MP3播报 |
| poweron | 字符串 | 否 | 开机铃声 |
| poweroff | 字符串 | 否 | 关机铃声 |
终端回复
若参数设置成功，设备会自动重启，不回复任何消息。若设备设置失败，则回复对应的失败信息。
八、二维码识别，内容上报
服务器下发
若需要通过服务器下发指令打开摄像头，请使用 switch 指令
终端上传
示例:{"cmd":"qrcode","data":"二维码内容base64编码","money":"31.22"}
| 字段 | 类型 | 必选 | 取值说明 |
| cmd | 字符串 | 是 | 指令名称，固定取值：“qrcode” |
| data | 字符串 | 是 | 摄像头识别的二维码内容 base64 编码。服务器接收到该消息后，需要base64解码才能得到二维码内容。 |
| money | 字符串 | 否 | 音箱主动识别用户付款码时，通过键盘输入待收取的金额 |
默认通过 MQTT / TCP socket 上报，也可以配置 http 接口上报。http接口要求如下
请求方式： post
http head： Content-Type：application/json; charset=UTF-8
九、身份证识别，内容上报
终端上传
示例： {"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 接口上报。http接口要求如下
请求方式： post
http head： Content-Type：application/json; charset=UTF-8
终端上传
该指令终端不回复