صفحهٔ اصلی گشت‌و‌گذار راهنما
ثبت نام ورود
evolve
/
car-wash-java
2
0
انشعاب 0
پرونده‌ها مشکلات 0 درخواست واکشی 0 ویکی
شاخه: master
شاخه‌ها تگ‌ها
car-wash-java
/
docs
/
洗车机MQTT通信协议_优化排版版.md

洗车机MQTT通信协议_优化排版版.md 41 KB
لینک دائمی تاريخچه خام

文档目录

  • 简介
  • 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。 实例认证信息如下：

{
    "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 ⽅法要传递的参数。

{
    "version": "2.0",
    "method": "help",
    "params": []
}

回复

洗车机 MQTT 通信协议

2025-08-10 回复是设备通过阿⾥云物联⽹平台返回的数据。 code 操作状态码。 200 操作成功。 400 错误的请求。 404 没有找到数据。 code_msg 状态码文本解释。 data ⽅法执⾏返回的数据。 errors 如果执⾏出错，这⾥返回具体的错误原因，没有错误返回空。

{
    "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 板载温度传感器的温度值。

{
    "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号。

{
    "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)

{
 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对应的⾦额。

{
    "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 固件的编译时间。

{
    "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列表 请求

{
    "version": "2.0",
    "method": "help",
    "params": []
}

回复

{
    "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帮助信息 请求

{
    "version": "2.0",
    "method": "help",

# 洗车机 MQTT 通信协议
2025-08-10
    "params": {
        "method": "create_order"
    }
}

回复

{、
    "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 显⽰时⻓，单位秒，时间到了对话框⾃动消失。

{
    "version": "2.0",
    "method": "show_msgbox",
    "params": {
        "title": "标题",
        "content": "内容",
        "seconds": 600
    }
}

回复

{
    "version": "2.0",
    "code": 200,

# 洗车机 MQTT 通信协议
2025-08-10
    "code_msg": "success",
    "data": [],
    "errors": []
}

隐藏消息对话框

请求

{
    "version": "2.0",
    "method": "hide_msgbox",
    "params": []
}

回复

{
    "version": "2.0",
    "code": 200,
    "code_msg": "success",
    "data": [],
    "errors": []
}

重启设备

请求 注意:在洗⻋的时候或者账单明细⻚⾯，设备不会重启(在等待重启)，重启前由3-5秒左右的延时(防⽌⽹ 络数据没有发送完成)。

{
    "version": "2.0",
    "method": "reboot",
    "params": []
}

回复

{
    "version": "2.0",
    "code": 200,

# 洗车机 MQTT 通信协议
2025-08-10
    "code_msg": "success",
    "data": [],
    "errors": []
}

查询设备状态

请求

{
    "version": "2.0",
    "method": "query_state",
    "params": []
}

回复 device_state 参考数据定义中的设备状态。 order_info 参考数据定义中的订单信息(只有在洗⻋状态state=busy才会传回来)。

{
    "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": []
}

查询硬件信息

请求

{
    "version": "2.0",
    "method": "query_hardware_info",
    "params": []
}

洗车机 MQTT 通信协议

2025-08-10 回复 network 参考数据定义中的⽹络状态。 board 参考数据定义中的主板信息。

{
    "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"。上报的其他数据和⾃助洗⻋的都是⼀样的， 订单没有详细信息。⾃动洗⻋机的订单也不⽀持远程关闭。

{
    "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 本机订单号(不保证连续)

{
    "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参 数)。

{
    "version": "2.0",
    "method": "close_order",
    "params": {
        "order_id": "1597482244",
        "force_close": 1
    }
}

洗车机 MQTT 通信协议

2025-08-10 回复

{
    "version": "2.0",
    "code": 200,
    "code_msg": "success",
    "data": [],
    "errors": []
}

查询订单

请求 注意：只能查询当前订单和上⼀个订单的信息,2G版本重启后不能查询之前的订单信息。

{
    "version": "2.0",
    "method": "query_order",
    "params": {
        "order_id": "1597482244"
    }
}

正常回复 如果存在，回复200，由订单信息回复，如果订单不存在，回复状态码400。

{
    "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版本重启后不能查询之前的订单信息。

{
    "version": "2.0",
    "code": 404,
    "code_msg": "not found",

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

读取配置

请求

{
    "version": "2.0",
    "method": "read_config",
    "params": []
}

回复

{
    "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": []
}

修改配置

请求

{
    "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
    }
}

回复

{
    "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 动作时间，单位是毫秒，如果为零，表⽰保持在动作后的状态。 请求

{
    "method": "relay_control",
    "params": {
        "relay": 1,
        "action": "on",
        "delay_ms": 1000
    },
    "version": "2.0"
}

回复

{
    "version": "2.0",
    "code": 200,
    "code_msg": "success",
    "data": {
        "relay_state": 1
    },
    "errors": [
    ]
}

事件上传

设备启动事件

洗车机 MQTT 通信协议

2025-08-10 设备上电启动， ⽰例

{
    "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
        }
    }
}

设备状态更新事件

⽰例

{
    "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
        }
    }
}

收到订单事件

⽰例 收到订单时上传，包含订单信息。

{
    "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
    }
}

关闭订单事件

⽰例 关闭设备时上传，包含订单信息。

{
    "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分钟上传⼀次。

{
    "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
                }
            ]
        }
    }
}

⽤户登录事件

**注意：设备端登录的⽤户名和密码只能是纯数字，对于⽯斑⻥平台⽤户名通常是⼿机号码 **

{

"version": "2.0",

"event": "user_login",

"data": {

"name": "123456",

"password": "123456"

}
}

⽤户刷卡事件

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

洗车机 MQTT 通信协议

2025-08-10

{

"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⽇ 发布初始版本。