洗车机主板通讯协议

docs/洗车机MQTT通信协议_优化排版版.md

@@ -0,0 +1,1396 @@
+# 文档目录
+
+- 简介
+- 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⽇
+发布初始版本。