# 文档目录

- 简介
- MQTT 认证
- MQTT 连接说明
- MQTT Topic 说明
- 设备 RPC 通信
- 数据定义
- 同步操作接口
- 事件上传
- 常见问题解答
- 版本维护记录

---

# 洗车机 MQTT 通信协议
2025-08-10
# 洗车机 MQTT 通信协议
## 简介
设备和Web后端通过MQTT协议连接到MQTT Broker，相对于Broker⽽⾔，设备和Web后端都是MQTT客户端。
MQTT Broker可以使⽤阿⾥云物联⽹平台，也可以⾃⼰基于开源MQTT Broker做⼆次开发。
## MQTT 认证
设备出⼚前写入产品标识、设备名称、设备秘钥三项配置信息(后续简称三元组)和MQTT Broker的信息，按照阿
⾥云物联⽹平台的认证⽅式，计算出MQTT连接需要的客户端标识、⽤户名称、⽤户密码去连接MQTT Broker。
实例认证信息如下：
```json
{
    "clientId":
"${ProductKey}.${DeviceName}|securemode=2,signmethod=hmacsha256,timestamp=17547250
53877|",
    "username": "${DeviceName}&${ProductKey}",
    "passwd": "868deee862f87b5d4136e2adf54bfede427ada8e646a4cec52aacfeafc488220",
    "mqttHostUrl": "${ProductKey}.iot-as-mqtt.cn-shanghai.aliyuncs.com",
    "port": 1883
}
```
以下字段在出⼚前使⽤上位机⼯具写入：
ProductKey：产品标识
DeviceName：设备名称
DeviceSecure：设备秘钥
MqttHost: MQTT服务器地址(覆盖上⾯的mqttHostUrl)
MqttPort: MQTT Broker使⽤的端⼝(覆盖上⾯的port)
对于⽀持WiFi的版本可以提前写入认证信息(ssid和password)，也可以通过触摸屏⾃⾏设置。
认证⽅式⻅文档mqtt-sign-demo中的⽰例程序。提供有C、Java、Python、Go、C#、JavaScript等语⾔
的实现。
clientId字段说明
securemode 加密⽅式，设备固定是2
signmethod 签名算法，设备固定是hmacsha256
timestamp Unix时间戳，单位是毫秒, 系统按照设定的时区来计算。
username 设备名称&产品标识
password 按照阿⾥云物联⽹平台的⽅式进⾏计算。
## MQTT 连接说明
MQTT连接签名⽰例

# 洗车机 MQTT 通信协议
2025-08-10
## MQTT Topic 说明
设备主动上报的数据都是Topic： `/${ProductKey}/${DeviceName}/user/report` 设备的RPC同步调
⽤ Topic中符号+的位置可以是不同的数字，表⽰第N次RPC调⽤，设备会把这个数字原样返回，⽅便调
⽤和分析问题。 设备会使⽤MQTT协议来尝试进⾏NTP时间同步，如果使⽤⾃建的MQTT Broker不⽀持
也不影响正常使⽤。
作⽤
Topic名称
说明
设备主动上
报数据
/${ProductKey}/${DeviceName}/user/report
设备发布Topic(后端订阅来
接收数据)
接收RPC请
求
/sys/${ProductKey}/${DeviceName}/rrpc/request/+
设备订阅的Topic(后端发布
Topic)
回复RPC请
求
/sys/${ProductKey}/${DeviceName}/rrpc/response/+
设备发布Topic(后端订阅来
接收回复)
请求NTP时
间同步
/ext/ntp/${ProductKey}/${DeviceName}/request
设备发布Topic(后端订阅来
接收回复)
接收NTP时
间信息
/ext/ntp/${ProductKey}/${DeviceName}/response
设备订阅的Topic(后端收到
请求后，发布Topic来回复
NTP时间)
## 设备 RPC 通信
请求和回复都使⽤JSON字符串格式，通过兼容MQTT的RPC接⼝来实现。下⾯ 为简化调试和接⼝处理，
配置或参数项只使⽤字符串和整数两种类型(不⽀持布尔类型和浮点类型)。
设备订阅请求：/sys/${ProductKey}/${DeviceName}/rrpc/request/+
设备发布应答：/sys/${ProductKey}/${DeviceName}/rrpc/response/+
参考⽰例如下：
请求
请求是指通过阿⾥云物联⽹平台发送给设备的数据。
version协议版本号，⽬前固定为2.0。
method 要调⽤的远程⽅法名称。
params ⽅法要传递的参数。
```json
{
    "version": "2.0",
    "method": "help",
    "params": []
}
```
回复

# 洗车机 MQTT 通信协议
2025-08-10
回复是设备通过阿⾥云物联⽹平台返回的数据。
code 操作状态码。
200 操作成功。
400 错误的请求。
404 没有找到数据。
code_msg 状态码文本解释。
data ⽅法执⾏返回的数据。
errors 如果执⾏出错，这⾥返回具体的错误原因，没有错误返回空。
```json
{
    "version": "2.0",
    "code": 200,
    "code_msg": "success",
    "data": {
        "api_list": [
            "help",
            "reboot",
            "query_state",
            "query_hardware_info",
            "create_order",
            "close_order",
            "query_order",
            "read_config",
            "write_config",
            "show_msgbox",
            "hide_msgbox"
        ]
    },
    "errors": []
}
```
## 数据定义
### 设备状态
device_state
state 设备的状态(重要)。
init 设备正在初始化(启动阶段，只有在主动上报的启动事件中才可能会出现)。
idle 设备空闲，可以创建订单，开机洗⻋。
busy 设备忙碌，正在洗⻋，不能再次创建订单。
sleep 不在营业时间段，不能创建订单洗⻋。
maintenance 维护模式，不能创建订单洗⻋。
fault 设备故障状态，不能创建订单洗⻋（预留，后续4G版本⽀持）。
fault_reason 故障原因(4G版本⽀持)。
fsm_state 设备主状态机的当前状态(状态可能增加或减少，仅供调试参考。)。
uptime_ms 本次上电以来的时间戳。
boot_flag 启动标识(芯片相关，⼆次开发⽆需关⼼)。
has_water 是否有⽔

# 洗车机 MQTT 通信协议
2025-08-10
-1 不⽀持或未开启
0 表⽰没有⽔
1 表⽰有⽔
has_foam 是否有泡沫
-1 不⽀持或未开启
0 表⽰没有泡沫
1 表⽰有泡沫
temperature_chip 板载温度传感器的温度值。
```json
{
    "uptime_ms": "47141",
    "boot_flag": "software",
    "state": "idle",
    "fsm_state": "play",
    "has_water": -1,
    "has_foam": -1,
    "temperature_chip": 34
}
```
### ⽹络状态
type ⽹络类型。
rssi 信号质量
ber 误码率。
imei ⽹络设备的IMEI号。
```json
{
    "type": "2G",
    "rssi": 13,
    "ber": 0,
    "imei": "8646260436889"
},
### 订单信息
order_info 如果当前正在洗⻋，那么会发送回来订单信息(参考query_order接⼝)。
open_type 开机⽅式。
button 表⽰使⽤机器的维护按钮快速开机的订单。
network 表⽰通过⽹络命令推送来的订单。
coin 表⽰投币开机的订单。
card 表⽰刷卡卡机的订单。
注意:后续可能会增加其它的开机⽅式。
close_type 关机⽅式。
button ⽤户按关机按钮关闭的机器。
network 通过⽹络命令关闭的机器。
no_balance 消费⾦额达到本次开机的最⼤消费⾦额(prepay_money)限制关机的。

# 洗车机 MQTT 通信协议
2025-08-10
idle_timeout 设备空闲超时(⻅配置项idle_timeout)关机的。
operation_timeout 操作超时(⻅配置项operation_timeout)关机的。
card 表⽰刷卡关机的订单。
注意:为空表⽰还没有关机，⽤户正在使⽤。后续可能会增加其它的关机⽅式。
order_id 订单号，和开机命令的order_id相同，如果使⽤按钮快速开机，order_id是空字符串,
并且open_type为button。
order_id_local 本机订单号(不保证连续)。
member_discount 会员折扣比例(0-100,100表⽰不享受折扣，95表⽰9.5折优惠)。
prepay_money 本次开机的预付⾦额(单位分，本次开机最⼤消费⾦额限制)。
amount 消费总额，等于各单项费⽤之和(单位分)。
amount_receivable 应收⾦额，如果⼤于预付⾦额，则限制为预付⾦额并关机，否则等于消费总
额(单位分)。
amount_received 实收⾦额等于应收⾦额乘会员折扣(单位分)。
discount_money 优惠⾦额等于消费总额减去实收⾦额(单位分)。
coin_money 投币的累计⾦额(仅限刷卡订单,单位分)。
coin_num 投币的次数仅限刷卡订单)。
card_type 卡类型(仅限刷卡订单,1表⽰普通卡，2表⽰储值卡)。
card_id 卡内码，卡出⼚的时候⼚家写入的ID(仅限刷卡订单)。
card_sn 卡串号，印刷在卡的表⾯，通过电脑上的卡管理⼯具写入卡内。(仅限刷卡订单)。
card_expired 卡过期时间，从1970年开始的时间戳(仅限刷储值卡的订单有效，普通卡为总是为
0)。
card_balance 卡内余额(仅限刷储值卡的订单有效，普通卡为总是为0)。
operation_remain_time 订单操作剩余操作时间(单位秒)，开机后从operation_timeout开始每
秒减1，减到0关机，关机原因close_type=operation_timeout。
idle_remain_time 设备空闲关机倒计时剩余时间(单位秒)，开机后从idle_timeout开始每秒减
1，⻅到0关机，关机原因close_type=idle_time(递减过程中按任意功能键，重新开始从
idle_timeout递减)。
detail 费⽤明细。 name 名称 price 单价(单位分) seconds 时⻓(单位秒) amount 费⽤(单位分)。
space ⻋位或场地。
water ⾼压清⽔。
foam 泡沫。
cleaner 吸尘器。
tap ⽔龙头。
user_ext ⽤户扩展，消毒或吹⼲等功能。
coat 镀膜。
blow 吹⽓。
{
    "open_type": "button",
    "close_type": "",
    "order_id": "",

# 洗车机 MQTT 通信协议
2025-08-10
    "order_id_local": "2",
    "member_discount": 100,
    "prepay_money": 1000,
    "amount": 40,
    "amount_receivable": 40,
    "amount_received": 40,
    "discount_money": 0,
    "remain_time": 3371,
    "detail": [
        {
            "name": "space",
            "price": 2,
            "seconds": 229,
            "amount": 7
        },
        {
            "name": "water",
            "price": 100,
            "seconds": 5,
            "amount": 8
        },
        {
            "name": "foam",
            "price": 200,
            "seconds": 5,
            "amount": 16
        },
        {
            "name": "tap",
            "price": 50,
            "seconds": 1,
            "amount": 0
        },
        {
            "name": "cleaner",
            "price": 80,
            "seconds": 3,
            "amount": 4
        },
        {
            "name": "user_ext",
            "price": 100,
            "seconds": 3,
            "amount": 5
        }
    ]
}
```
应收实收⾦额的计算
单项费⽤都按秒计算，计算⽅法如下:

# 洗车机 MQTT 通信协议
2025-08-10
//根据时间计算价格
static uint32_t calc_fee(uint32_t seconds, uint32_t price)
```json
{
 return 1.0F * seconds / 60 * price;
}
```
应收⾦额amount_receivable 由单项的费⽤相加所得，应收⾦额达到预付⾦额就会停⽌设备。
由于存在1秒时间可能增加1分钱或2分钱的情况，那么折扣比例为100时，也存在优惠⾦额不为零的情
况。
计算⽅法如下：
//各收费项之和
order->amount = money;

//计算应收⾦额
if (order->amount >= order->prepay_money) {
    order->amount_receivable = order->prepay_money;
    stop = 1;
} else {
    order->amount_receivable = order->amount;
}

//检查折扣比例
if ((order->discount_money < 0) || (order->discount_money > 100)) {
    order->discount_money = 100;
}

//计算实收⾦额
order->amount_received = 1.0F * order->amount_receivable * order-
>member_discount / 100 + 0.5F;

//计算优惠⾦额
if (order->amount >= order->amount_received) {
    order->discount_money = order->amount - order->amount_received;
} else {
    order->discount_money = 0;
}
### 参数配置项
maintenance_mode 维护模式
0 未设置
1 已设置(屏幕显⽰设备维护界⾯).
user_message.1 ⽤户⾃定义信息，屏幕左下⾓文本，可以显⽰公司名称、维护电话、客服电话等。
user_message.2 ⽤户⾃定义信息，屏幕右下⾓文本，可以显⽰公司名称、维护电话、客服电话等。

# 洗车机 MQTT 通信协议
2025-08-10
sensor_water 是否安装了⽔流量传感器。
price_space ⻋位或场地单价(单位：分/分钟)。
price_water 清⽔单价(单位：分/分钟)。
price_foam 泡沫单价(单位：分/分钟)。
price_tap ⽔龙头单价(单位：分/分钟)。
price_cleaner 吸尘器单价(单位：分/分钟)。
price_user_ext ⽤户扩展功能单价(消毒、吹⼲等，单位：分/分钟)。
price_coat 镀膜的单价(单位：分/分钟)。
price_blow 吹⽓的单价(单位：分/分钟)。
idle_timeout 空闲超时，多久不操作设备(⽤户开关功能重新开始倒计时),那么就认为⽤户已离开，直接
关闭设备(单位：秒)。
operation_timeout 操作超时，订单开始之后多久强制关闭，也就是⽤户必须要再多⻓时间内洗完⻋
(单位：秒)。
quick_open_money 快速开机⾦额，按机箱内部的维护按键直接开机(设置为0可以关闭这个功能)。
work_mode 营业时间段控制模块的⼯作模式
0 全天24⼩时暂停营业
1 全天24⼩时营业
2 由时间段控制营业时间,不在营业时间段⽆法开机，屏幕显⽰营业时间信息。
例如: 上午营业 "work_time_period.1" = "08:00 - 12:00"和下午营
业"work_time_period.2 = "13:30 - 20:00"
work_time_period.1 营业时间段1,24⼩时制，程序会处理跨凌晨的情况。
work_time_period.2 营业时间段1,24⼩时制，程序会处理跨凌晨的情况。
light_mode 照明时间段控制模块的⼯作模式
0 全天24⼩时关闭照明
1 全天24⼩时开启照明
2 由时间段控制开灯时间
例如: 整个晚上亮灯"light_time_period.1" = "18:30 - 07:30" 晚上亮灯
"light_time_period.1" = "18:30 - 22:30"和早上亮灯"light_time_period.2 = "05:00
- 7:00"
light_time_period.1 照明时间段1,参考营业时间段配置。
light_time_period.2 照明时间段1,参考营业时间段配置。
sound_volume ⾳量。

# 洗车机 MQTT 通信协议
2025-08-10
screen_type 屏幕类型(0:不⽀持视频播放的屏幕，1:⽀持视频播放的屏幕,两种屏型号不同，填写错误会
导致没有语⾳。)
video_source 视频源(0:内置视频，1:TF卡内的视频，2:U盘内的视频)。
video_play_delay 视频播放延时(单位秒)。设备空闲多久开始循环播放⼴告视频。
work_light_delay 订单结束时延时过久关闭⼯作指⽰灯(单位秒)。
bill_delay 洗⻋结束后，费⽤明细⻚⾯显⽰多久(单位秒)。
errors 如果有参数出现错误，这⾥给出提⽰信息。
notice_throshold_idle 空闲关机倒计时剩余时间⼩于这个数字，发出提⽰⾳(正在倒计时关机，请按
任意功能键阻⽌关机)。
notice_throshold_operation 操作时间倒计时剩余时间⼩于这个数字，发出提⽰⾳(您的洗⻋时间剩
余不多了，请合理使⽤)。
motor_mode 0:流量不能启动电机()；1：有⽔流量的时候启动⾃动启动电机（兼容老客户，新客户请忽略
该参数，请不要发送这个参数给板⼦。）。
motor_on_delay 电机启动最少要⼯作多⻓时间(单位毫秒，请勿随意修改。)。
motor_off_delay 电机关闭后要强制保持关闭状态多⻓时间(单位毫秒，请勿随意修改)。
motor_on_interval 电机关机灵敏度(有流量计有效，单位毫秒，请勿随意修改)。
motor_flow_on 电机是否根据流量启动(有流量⾃动开启电机，请勿随意修改)。
motor_flow_off 电机是否根据流量关闭(⽆流量⾃动关闭电机，请勿随意修改)。
tap_on_delay ⽔龙头开启延时(单位秒，⽔龙头开启多少秒后⾃动关闭，0表⽰不⾃动关闭。)
coin_money 投币信号的币值，也就是⼀个币是多少钱单位分(如⼈⺠币1元设置为100，港币5元，设置
为500)。
coin_num 投币的数量，对于同时接收超过⼀种币值的投币器，投币数量是⽆效的，这个数值等于投币器
发出的脉冲数量。
card_key 卡密码，只有相同密码的卡可以通⽤(注意：这个密码要和使⽤卡管理⼯具初始化卡的时候写
入的密码⼀致，写入后不能再次修改，否则由于和机器上密码不⼀致就不能使⽤了 ，机器总是提⽰卡读
取错误！)。
prepay_money 每次开机的最⼤消费限额(单位分，建议和创建订单的参数prepay_money保持⼀致)。
coat_mode 为0表⽰关闭，为1表⽰使⽤镀膜功能(注意：这个功能和投币器功能不能同时使⽤。)
blow_mode 为0表⽰关闭，为1表⽰使⽤吹⽓功能(注意：这个功能和闸机控制功能不能同时使⽤。)
light_alt_mode 为0表⽰作为照明继电器使⽤；为1表⽰作为复⽤的远程控制继电器使⽤。
⾃动洗⻋机需要配置的⼏个参数
money_unit 货币转换单位，如⼈⺠币对应的是100。

# 洗车机 MQTT 通信协议
2025-08-10
pay_money_ch1 ⾃动洗⻋机的通道1对应的⾦额。
pay_money_ch2 ⾃动洗⻋机的通道2对应的⾦额。
pay_money_ch3 ⾃动洗⻋机的通道3对应的⾦额。
pay_money_ch4 ⾃动洗⻋机的通道4对应的⾦额。
```json
{
    "maintenance_mode": 0,
    "user_message.1": "",
    "user_message.2": "武汉爱⻋轩科技有限公司",
    "sensor_water": 1,
    "price_space": 2,
    "price_water": 100,
    "price_foam": 200,
    "price_tap": 50,
    "price_cleaner": 80,
    "price_user_ext": 100,
    "idle_timeout": 600,
    "operation_timeout": 3600,
    "quick_open_money": 1000,
    "work_mode": 1,
    "work_time_period.1": "08:00 - 20:00",
    "work_time_period.2": "14:00 - 20:00",
    "light_mode": 0,
    "light_time_period.1": "11:46 - 16:48",
    "light_time_period.2": "13:44 - 13:45",
    "sound_volume": 70,
    "screen_type": 1,
    "video_source": 2,
    "video_play_delay": 15,
    "work_light_delay": 10,
    "bill_delay": 10,
    "notice_throshold_idle": 300,
    "notice_throshold_operation": 600,
    "motor_mode": 0
}
```
### 主板信息
hard_version 硬件版本号定义。
chip_id 芯片的唯⼀ID.
firmware_version 固件版本定义。
build_time 固件的编译时间。
```json
{
    "hard_version": "3.3",
    "chip_id": "CAB1001F-00039018-49044E45",
    "firmware_version": "3.0.0",
    "build_time": "Aug 11 2020 14:58:27"
}
```

# 洗车机 MQTT 通信协议
2025-08-10
## 同步操作接口
### 帮助命令
获取API列表
请求
```json
{
    "version": "2.0",
    "method": "help",
    "params": []
}
```
回复
```json
{
    "version": "2.0",
    "code": 200,
    "code_msg": "success",
    "data": {
        "api_list": [
            "help",
            "reboot",
            "query_state",
            "query_hardware_info",
            "create_order",
            "close_order",
            "query_order",
            "read_config",
            "write_config",
            "show_msgbox",
            "hide_msgbox"
        ]
    },
    "errors": []
}
```
获取API帮助信息
请求
```json
{
    "version": "2.0",
    "method": "help",

# 洗车机 MQTT 通信协议
2025-08-10
    "params": {
        "method": "create_order"
    }
}
```
回复
```json
{、
    "version": "2.0",
    "code": 200,
    "code_msg": "success",
    "data": {
        "method": "create_order",
        "help": "打开设备(打开订单);order_id 订单号 必须 字符串类型;prepay_money 预付
⾦额(本次开机最⼤可消费⾦额) 必须 整数类型 单位分;member_balance 会员余额 可选 整数类型
单位分 (仅⽤于显⽰);member_name 会员名称 可选 字符串类型;member_discount 会员折扣 可选
整数类型(0-100,默认为100,表⽰不折扣);"
    },
    "errors": []
}
```
### 显⽰消息对话框
请求
注意：系统只能显⽰⼀个对话框，新的对话框会把旧的覆盖掉。
title 参考数据定义中的设备状态。
content 参考数据定义中的订单信息(只有在洗⻋状态state=busy才会传回来)。
seconds 显⽰时⻓，单位秒，时间到了对话框⾃动消失。
```json
{
    "version": "2.0",
    "method": "show_msgbox",
    "params": {
        "title": "标题",
        "content": "内容",
        "seconds": 600
    }
}
```
回复
```json
{
    "version": "2.0",
    "code": 200,

# 洗车机 MQTT 通信协议
2025-08-10
    "code_msg": "success",
    "data": [],
    "errors": []
}
```
### 隐藏消息对话框
请求
```json
{
    "version": "2.0",
    "method": "hide_msgbox",
    "params": []
}
```
回复
```json
{
    "version": "2.0",
    "code": 200,
    "code_msg": "success",
    "data": [],
    "errors": []
}
```
### 重启设备
请求
注意:在洗⻋的时候或者账单明细⻚⾯，设备不会重启(在等待重启)，重启前由3-5秒左右的延时(防⽌⽹
络数据没有发送完成)。
```json
{
    "version": "2.0",
    "method": "reboot",
    "params": []
}
```
回复
```json
{
    "version": "2.0",
    "code": 200,

# 洗车机 MQTT 通信协议
2025-08-10
    "code_msg": "success",
    "data": [],
    "errors": []
}
```
### 查询设备状态
请求
```json
{
    "version": "2.0",
    "method": "query_state",
    "params": []
}
```
回复
device_state 参考数据定义中的设备状态。
order_info 参考数据定义中的订单信息(只有在洗⻋状态state=busy才会传回来)。
```json
{
    "version": "2.0",
    "code": 200,
    "code_msg": "success",
    "data": {
        "order_info": {
            "open_type": "network",
            "close_type": "",
            "order_id": "1597482244",
            "order_id_local": "101128414",
            "member_discount": 95,
            "prepay_money": 1000,
            "amount": 0,
            "amount_receivable": 0,
            "amount_received": 0,
            "discount_money": 0,
            "operation_remain_time": 3591,
            "idle_remain_time": 591,
            "detail": [
                {
                    "name": "space",
                    "price": 2,
                    "seconds": 8,
                    "amount": 0
                },
                {
                    "name": "water",
                    "price": 100,

# 洗车机 MQTT 通信协议
2025-08-10
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "foam",
                    "price": 200,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "tap",
                    "price": 50,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "cleaner",
                    "price": 80,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "user_ext",
                    "price": 100,
                    "seconds": 0,
                    "amount": 0
                }
            ]
        },
        "device_state": {
            "uptime_ms": "95282",
            "boot_flag": "software",
            "state": "busy",
            "fsm_state": "work",
            "has_water": -1,
            "has_foam": -1,
            "temperature_chip": 34
        }
    },
    "errors": []
}
```
### 查询硬件信息
请求
```json
{
    "version": "2.0",
    "method": "query_hardware_info",
    "params": []
}
```

# 洗车机 MQTT 通信协议
2025-08-10
回复
network 参考数据定义中的⽹络状态。
board 参考数据定义中的主板信息。
```json
{
    "version": "2.0",
    "code": 200,
    "code_msg": "success",
    "data": {
        "network": {
            "type": "2G",
            "rssi": 13,
            "ber": 0,
            "imei": "8646260436889"
        },
        "board": {
            "hard_version": "3.3",
            "chip_id": "CAB1001F-00039018-49044E45",
            "firmware_version": "3.0.0",
            "build_time": "Aug 11 2020 14:58:27"
        }
    },
    "errors": []
}
```
### 创建订单
请求
order_id 订单号，字符串类型，必须。
member_name 会员名称，字符串类型，可选。
member_balance 会员余额(单位分，仅在界⾯上显⽰，不参与任何业务处理)，可选。
member_discount 会员折扣比例(95表⽰9.5折优惠，默认100表⽰没有优惠)，可选。
prepay_money 预付⾦额(本次开机最⼤消费⾦额)，单位分，必须。
card_sn 刷卡的串号(对于刷普通卡的⽤户，服务器端应当在收到刷卡消息的时候查询这张卡绑定的账号
信息，如果这个账号有余额，那么推送开机命令的时候需要把上传的刷卡事件中的card_sn回传回去，
这样板⼦会把这个开机命令标记为刷卡开机，否则会标记为⽹络开机。)。
ext_msg 订单的扩展信息，字符串类型。
对于⾃动洗⻋机，使⽤扩展信息来表⽰需要打开那个通道，也就是对应的套餐,⾃动洗⻋机⽀持4个
通道，对应的是1到4。格式为: "ext_msg": "ch=1"。上报的其他数据和⾃助洗⻋的都是⼀样的，
订单没有详细信息。⾃动洗⻋机的订单也不⽀持远程关闭。
```json
{
    "version": "2.0",
    "method": "create_order",

# 洗车机 MQTT 通信协议
2025-08-10
    "params": {
        "order_id": "1597482244",
        "member_name": "会员名称",
        "member_balance": 9800,
        "member_discount": 95,
        "prepay_money": 1000
    }
}
```
回复
accepted 创建了新订单返回1，订单已存在返回0.
order_id_local 本机订单号(不保证连续)
```json
{
    "version": "2.0",
    "code": 200,
    "code_msg": "success",
    "data": {
        "order_id_local": "101128414",
        "created": 1
    },
    "errors": []
}
```
### 关闭订单
请求
以下两个参数根据情况，⼆选⼀即可。推荐指定订单号来关闭(如果指定了订单号，当订单号和当前订单
的订单号不同时，认为订单已关闭，回复200)。
order_id 如果当前订单的订单号和order_id相同，则执⾏关闭操作(注意：创建订单和关闭订单的订单
号需要保持⼀致，否则⽆法关机。)。
force_close 如果不知道订单号，需要强制关闭设备，那么就⽤这个参数(这时候不要再发送order_id参
数)。
```json
{
    "version": "2.0",
    "method": "close_order",
    "params": {
        "order_id": "1597482244",
        "force_close": 1
    }
}
```

# 洗车机 MQTT 通信协议
2025-08-10
回复
```json
{
    "version": "2.0",
    "code": 200,
    "code_msg": "success",
    "data": [],
    "errors": []
}
```
### 查询订单
请求
注意：只能查询当前订单和上⼀个订单的信息,2G版本重启后不能查询之前的订单信息。
```json
{
    "version": "2.0",
    "method": "query_order",
    "params": {
        "order_id": "1597482244"
    }
}
```
正常回复
如果存在，回复200，由订单信息回复，如果订单不存在，回复状态码400。
```json
{
    "version": "2.0",
    "code": 200,
    "code_msg": "success",
    "data": {
        "order_info": {
            "open_type": "network",
            "close_type": "",
            "order_id": "1597482244",
            "order_id_local": "101128414",
            "member_discount": 95,
            "prepay_money": 1000,
            "amount": 0,
            "amount_receivable": 0,
            "amount_received": 0,
            "discount_money": 0,
            "operation_remain_time": 3596,
            "idle_remain_time": 596,
            "detail": [

# 洗车机 MQTT 通信协议
2025-08-10
                {
                    "name": "space",
                    "price": 2,
                    "seconds": 4,
                    "amount": 0
                },
                {
                    "name": "water",
                    "price": 100,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "foam",
                    "price": 200,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "tap",
                    "price": 50,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "cleaner",
                    "price": 80,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "user_ext",
                    "price": 100,
                    "seconds": 0,
                    "amount": 0
                }
            ]
        }
    },
    "errors": []
}
```

未找到订单，回复信息
注意：只能查询当前订单和上⼀个订单的信息,2G版本重启后不能查询之前的订单信息。
```json
{
    "version": "2.0",
    "code": 404,
    "code_msg": "not found",

# 洗车机 MQTT 通信协议
2025-08-10
    "data": [],
    "errors": []
}
```
### 读取配置
请求
```json
{
    "version": "2.0",
    "method": "read_config",
    "params": []
}
```
回复
```json
{
    "version": "2.0",
    "code": 200,
    "code_msg": "success",
    "data": {
        "maintenance_mode": 0,
        "user_message.1": "公司名称1597484391",
        "user_message.2": "客服电话1597484391",
        "sensor_water": 0,
        "price_space": 2,
        "price_water": 110,
        "price_foam": 220,
        "price_tap": 55,
        "price_cleaner": 88,
        "price_user_ext": 102,
        "idle_timeout": 2100,
        "operation_timeout": 2700,
        "quick_open_money": 1099,
        "work_mode": 2,
        "work_time_period.1": "08:00 - 20:00",
        "work_time_period.2": "14:00 - 20:00",
        "light_mode": 2,
        "light_time_period.1": "11:46 - 16:48",
        "light_time_period.2": "13:44 - 13:45",
        "sound_volume": 70,
        "screen_type": 0,
        "video_source": 0,
        "video_play_delay": 120,
        "work_light_delay": 30,
        "bill_delay": 60,
        "notice_throshold_idle": 300,
        "notice_throshold_operation": 600,

# 洗车机 MQTT 通信协议
2025-08-10
        "motor_mode": 0
    },
    "errors": []
}
```

### 修改配置
请求
```json
{
    "version": "2.0",
    "method": "write_config",
    "params": {
        "maintenance_mode": 0,
        "user_message.1": "公司名称1597484391",
        "user_message.2": "客服电话1597484391",
        "sensor_water": 0,
        "price_space": 2,
        "price_water": 110,
        "price_foam": 220,
        "price_tap": 55,
        "price_cleaner": 88,
        "price_user_ext": 102,
        "idle_timeout": 2100,
        "operation_timeout": 2700,
        "quick_open_money": 1099,
        "work_mode": 2,
        "work_time_period.1": "08:00 - 20:00",
        "work_time_period.2": "14:00 - 20:00",
        "light_mode": 2,
        "light_time_period.1": "11:46 - 16:48",
        "light_time_period.2": "13:44 - 13:45",
        "sound_volume": 70,
        "screen_type": 0,
        "video_source": 0,
        "video_play_delay": 120,
        "work_light_delay": 30,
        "bill_delay": 60,
        "notice_throshold_idle": 300,
        "notice_throshold_operation": 600
    }
}
```
回复
```json
{
    "version": "2.0",

# 洗车机 MQTT 通信协议
2025-08-10
    "code": 200,
    "code_msg": "success",
    "data": [],
    "errors": []
}
```
### 继电器控制命令
这个命令⽤于控制继电器，需要先设置照明继电器复⽤参数light_alt_mode。
relay 继电器的编号，⽬前固定为1.
action 要执⾏的动作。
on 打开继电器。
off 关闭继电器。
toggle 切换继电器的状态。
query 查询继电器的状态。
delay_ms 动作时间，单位是毫秒，如果为零，表⽰保持在动作后的状态。
请求
```json
{
    "method": "relay_control",
    "params": {
        "relay": 1,
        "action": "on",
        "delay_ms": 1000
    },
    "version": "2.0"
}
```
回复
```json
{
    "version": "2.0",
    "code": 200,
    "code_msg": "success",
    "data": {
        "relay_state": 1
    },
    "errors": [
    ]
}
```
## 事件上传
### 设备启动事件

# 洗车机 MQTT 通信协议
2025-08-10
设备上电启动，
⽰例
```json
{
    "version": "2.0",
    "event": "boot",
    "data": {
        "device_state": {
            "uptime_ms": "47139",
            "boot_flag": "software",
            "state": "idle",
            "fsm_state": "play",
            "has_water": -1,
            "has_foam": -1,
            "temperature_chip": 34
        }
    }
}
```
### 设备状态更新事件
⽰例
```json
{
    "version": "2.0",
    "event": "device_state",
    "data": {
        "device_state": {
            "uptime_ms": "29702",
            "boot_flag": "software",
            "state": "idle",
            "fsm_state": "play",
            "has_water": -1,
            "has_foam": -1,
            "temperature_chip": 33
        }
    }
}
```
### 收到订单事件
⽰例
收到订单时上传，包含订单信息。
```json
{
    "version": "2.0",

# 洗车机 MQTT 通信协议
2025-08-10
    "event": "order_create",
    "data": {
        "order_info": {
            "open_type": "network",
            "close_type": "",
            "order_id": "1597485911",
            "order_id_local": "104657724",
            "member_discount": 95,
            "prepay_money": 1000,
            "amount": 0,
            "amount_receivable": 0,
            "amount_received": 0,
            "discount_money": 0,
            "operation_remain_time": 3600,
            "idle_remain_time": 600,
            "detail": [
                {
                    "name": "space",
                    "price": 2,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "water",
                    "price": 100,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "foam",
                    "price": 200,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "tap",
                    "price": 50,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "cleaner",
                    "price": 80,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "user_ext",
                    "price": 100,
                    "seconds": 0,
                    "amount": 0
                }
            ]
        }

# 洗车机 MQTT 通信协议
2025-08-10
    }
}
```
### 关闭订单事件
⽰例
关闭设备时上传，包含订单信息。
```json
{
    "version": "2.0",
    "event": "order_close",
    "data": {
        "order_info": {
            "open_type": "network",
            "close_type": "network",
            "order_id": "1597485911",
            "order_id_local": "104657724",
            "member_discount": 95,
            "prepay_money": 1000,
            "amount": 88,
            "amount_receivable": 88,
            "amount_received": 83,
            "discount_money": 5,
            "operation_remain_time": 3528,
            "idle_remain_time": 600,
            "detail": [
                {
                    "name": "space",
                    "price": 2,
                    "seconds": 72,
                    "amount": 2
                },
                {
                    "name": "water",
                    "price": 100,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "foam",
                    "price": 200,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "tap",
                    "price": 50,
                    "seconds": 0,
                    "amount": 0
                },

# 洗车机 MQTT 通信协议
2025-08-10
                {
                    "name": "cleaner",
                    "price": 80,
                    "seconds": 65,
                    "amount": 86
                },
                {
                    "name": "user_ext",
                    "price": 100,
                    "seconds": 0,
                    "amount": 0
                }
            ]
        }
    }
}
```
### 订单状态更新事件
⽰例
⽤来让服务器知道订单的当前状态,以下两个条件只要满⾜其中⼀个就上传⼀次。
订单的应收⾦额和上次上传的应收⾦额⼤于等于1元则上传⼀次。
如果⾦额不变，每个3分钟上传⼀次。
```json
{
    "version": "2.0",
    "event": "order_update",
    "data": {
        "order_info": {
            "open_type": "network",
            "close_type": "",
            "order_id": "1597485911",
            "order_id_local": "104657724",
            "member_discount": 95,
            "prepay_money": 1000,
            "amount": 88,
            "amount_receivable": 88,
            "amount_received": 83,
            "discount_money": 5,
            "operation_remain_time": 3528,
            "idle_remain_time": 600,
            "detail": [
                {
                    "name": "space",
                    "price": 2,
                    "seconds": 72,
                    "amount": 2
                },
                {
                    "name": "water",

# 洗车机 MQTT 通信协议
2025-08-10
                    "price": 100,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "foam",
                    "price": 200,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "tap",
                    "price": 50,
                    "seconds": 0,
                    "amount": 0
                },
                {
                    "name": "cleaner",
                    "price": 80,
                    "seconds": 65,
                    "amount": 86
                },
                {
                    "name": "user_ext",
                    "price": 100,
                    "seconds": 0,
                    "amount": 0
                }
            ]
        }
    }
}
```
### ⽤户登录事件
**注意：设备端登录的⽤户名和密码只能是纯数字，对于⽯斑⻥平台⽤户名通常是⼿机号码 **
```json
{

"version": "2.0",

"event": "user_login",

"data": {

"name": "123456",

"password": "123456"

}
}
```
### ⽤户刷卡事件
注意：⽆论⽤户刷的是普通卡还是储值卡，都会上传这个事件。 对于储值卡总是可以刷卡开关机，如果设备在
线则上传，不在线则不上传。各字段的意义请参考订单信息中的解释。

# 洗车机 MQTT 通信协议
2025-08-10
```json
{

"version": "2.0",

"event": "card_event",

"data": {

"card_type": 1,

"card_id": 982334256,

"card_sn": 123456,

"card_expired": 0,

"card_balance": 0

}
}
```
## 常见问题解答
如何知道设备是否在在线
1、从MQTT Broker来查询设备是否在线，需要查阅相关Broker实现的文档(推荐)。 2、通过MQTT遗嘱消息来实
现，由于阿⾥云物联⽹平台不⽀持该功能，为保持兼容，设备端未实现该⽅法。 3、通过RPC同步调⽤来实时的
获取设备是否在线。由于4G⽹络延时，可能会出现响应超时，响应较慢。WiFi⽹络下响应较快，有条件可以使
⽤WiFi⽹络。
## 版本维护记录
2025年8⽉8⽇
增加MQTT协议的Topic和连接MQTT Broker的说明。
2024年8⽉15⽇
增加对⾃动洗⻋机的⽀持。在创建订单的时候通过"ext_msg": "ch=1"来指定要打开的通道。
2023年10⽉26⽇
增加照明继电器复⽤为远程控制继电器的功能。
使⽤时需要先设置参数light_alt_mode ,然后使⽤API命令relay_control来控制继电器。
2023年9⽉5⽇
增加语⾳播放器类型字段player_type,类型为整形，取值为0使⽤默认的语⾳合成功能播放，取值为1使
⽤屏幕语⾳文件播放。
2023年7⽉22⽇
增加对show_msgbox和hide_msgbox接⼝的描述。这两个api可以使⽤help命令查到都可以使
⽤。
2022年11⽉7⽇
增加镀膜和吹⽓功能的配置项。
2021年1⽉29⽇
增加清⽔泡沫是否联动配置项(foam_link_mode)为1表⽰打开泡沫的时候⾃动打开清⽔，为0表⽰
单独控制模式。
2021年1⽉12⽇
增加根据流量收费模式(motor_fee_flow为1表⽰根据流量收费，为0表⽰正常收费模式)。
2020年12⽉16⽇
增加投币时上传⼀次订单信息变化事件(order_update)，让服务器及时知道⽤户投了多少钱的
币。
2020年12⽉15⽇

# 洗车机 MQTT 通信协议
2025-08-10
增加刷卡功能，参数card_key表⽰卡密码，相同密码的卡可以通⽤，不同密码的卡不能通⽤。
卡分为普通卡和储值卡两种。普通卡只能⽹络在线时使⽤，可以通过⽹络充值，挂失(⼆次开发的
客户请⾃⼰处理)。储值卡⽆论⽹络在线还是离线都可以正常刷卡使⽤，不能⽹络充值和挂失(设备
⽹络在线就上传记录<订单创建、订单更新、订单关闭>，不在线就不上传)。
2020年12⽉10⽇
增加投币功能，参数coin_money 表⽰币值，表⽰⼀个投币信号代表多少钱(单位分，设备⽹络在
线就上传记录<订单创建、订单更新、订单关闭>，不在线就不上传)。
2020年11⽉12⽇
增加打开⽔龙头超时⾃动关闭的功能(参数tap_on_delay)。
2020年11⽉8⽇
增加电机控制模块的参数远程修改功能(参数motor_on_delay、motor_off_delay、
motor_on_interval、motor_flow_on、motor_flow_off)。
2020年11⽉6⽇
增加设备端登录功能，⽤户点击登录，上报事件user_login。
2020年11⽉5⽇
增加登录界⾯操作超时参数login_timeout(单位秒)。
2020年11⽉3⽇
增加洗⻋超时时间配置space_timeout_seconds。
增加洗⻋超时后的计费⽅式配置值space_timeout_mode(场地费是否包括超时部分的费⽤)。 0表
⽰超时后只计算超时部分的费⽤，1表⽰超时后包括超时部分的费⽤。
2020年11⽉2⽇
增加了流量控制电机启动的配置项motor_mode。
2020年8⽉29⽇
修复拼写错误。hard_version => hardware_version
修复拼写错误。notice_throshold_idle => notice_threshold_idle。
修复拼写错误。notice_throshold_operation => notice_threshold_operation
所有参数免重启立刻⽣效。
优化EEPROM的操作速度。
设备状态(device.state)变化实时上报事件device_state，如果需要知道那些数据发⽣了变化，
请在服务器端做比较操作。
2020年8⽉16⽇
发布初始版本。