# 文档目录 - 简介 - 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⽇ 发布初始版本。