lingyunxsh/mqtt_power
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

单片机互通调试初步完成

Browse Source
This commit is contained in:
lingyunxsh
2025-05-27 16:56:10 +08:00
parent 6aaae06bac
commit 5612b2e782
2 changed files with 171 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
LogBook.md
View File

@@ -40,4 +40,40 @@
- 更新了MQTT通信约定、消息示例、单片机开发关键逻辑以及示例充电流程，以反映"到达即充电"的新业务规则。
- **待考虑/后续**:
- `ChargingSessionServiceImpl.handleChargingStart` 方法目前因 `START_CHARGE` 指令不再由后端主动发送而可能不再被主要流程调用，其定位和用途需要进一步明确或在未来重构中调整。
- 前端界面和用户交互流程可能需要相应调整，以匹配后端"到达即充电"的逻辑（例如，可能不再需要用户在机器人到达后点击"开始充电"按钮）。
- 前端界面和用户交互流程可能需要相应调整，以匹配后端"到达即充电"的逻辑（例如，可能不再需要用户在机器人到达后点击"开始充电"按钮）。
## YYYY-MM-DD (自动填充日期)
### ESP32 固件与后端通信逻辑校准与文档更新
**主要变更点：**
1. **MQTT ACK 消息格式校准 (关键)**:
* **问题分析**: 通过深入分析后端代码 (`MqttMessageHandlerImpl.java` 和 `CommandTypeEnum.java`)，发现后端期望的MQTT ACK消息格式与之前`README.md`及单片机固件发送的格式存在显著差异。
* 后端期望ACK中包含 `command_ack` 字段，其值为指令的**中文描述** (例如 "移动到指定点")，用于 `CommandTypeEnum.fromAck()` 方法匹配。
* 后端期望任务ID字段为 `task_id` (数字类型)。
* 后端期望成功状态字段为 `success` (布尔类型)。
* **`README.md` 更新**: 已更新 `README.md` (4.2.1节) 中的ACK消息示例，以准确反映后端期望的格式。包括添加了 `command_ack`，并将 `taskId` 改为 `task_id`，`status` (String) 改为 `success` (Boolean)。
* **行动项 (开发者)**: **开发者需要修改 `esp32_robot_firmware/mqtt_handler.cpp` 中的 `mqtt_publish_ack` 函数，使其发送的ACK JSON符合后端 `MqttMessageHandlerImpl.java` 的实际解析逻辑 (即包含中文描述的 `command_ack`，数字类型的 `task_id`，和布尔类型的 `success`)。**
2. **MQTT 下行 `MOVE_TO_SPOT` 指令校准**:
* **问题分析**: 后端 `ChargingSessionServiceImpl.java` 在发送移动指令时，实际使用的payload是 `{"command":"MOVE", ...}`，而 `README.md` 先前示例为 `{"commandType":"MOVE_TO_SPOT", ...}`。
* **`README.md` 更新**: 已更新 `README.md` (4.2.2节) 中移动指令的示例，以反映后端实际发送的 `command: "MOVE"`格式，并添加了说明指出单片机固件已做兼容处理。
* **行动项 (开发者, 可选)**: 为保持一致性，可考虑更新后端 `ChargingSessionServiceImpl.java`，使其发送移动指令时使用 `commandType: "MOVE_TO_SPOT"`。
3. **文档整体一致性提升**:
* `README.md` 中关于单片机处理逻辑 (4.3节) 和示例流程 (4.4节) 的部分也相应作了调整，以强调新的ACK格式要求和指令细节。
**代码分析涉及文件：**
* `springboot-init-main/src/main/java/com/yupi/project/service/impl/ChargingSessionServiceImpl.java` (下行指令发送)
* `springboot-init-main/src/main/java/com/yupi/project/service/impl/MqttServiceImpl.java` (下行指令封装与 `taskId` 注入)
* `springboot-init-main/src/main/java/com/yupi/project/mqtt/handler/MqttMessageHandlerImpl.java` (上行消息及ACK处理核心逻辑)
* `springboot-init-main/src/main/java/com/yupi/project/model/enums/CommandTypeEnum.java` (ACK中`command_ack`的解析方式)
* `esp32_robot_firmware/mqtt_handler.cpp` (单片机ACK发送逻辑 - **需修改**)
* `esp32_robot_firmware/esp32_robot_firmware.ino` (单片机指令回调处理)
**后续影响与建议**:
* **首要任务是修正单片机固件的ACK发送逻辑**，确保与后端正确对接。
* 在完成固件修改后，建议进行完整的MQTT通信测试，覆盖所有指令类型及其ACK流程。

180
README.md
View File

@@ -122,12 +122,13 @@
## 4. 单片机 (充电桩硬件) 对接指南
智能充电桩硬件需通过 MQTT 协议与本系统的后端服务进行通信。
智能充电桩硬件（在本例中为基于ESP32的移动机器人）需通过 MQTT 协议与本系统的后端服务进行通信。
**注意**: 本项目提供了一个新的、功能更完整的ESP32固件项目，位于 `esp32_robot_firmware/` 文件夹下。本文档后续的对接指南主要基于此新固件的逻辑。旧的 `mqtt_esp32_client.ino` 主要作为简易模拟器，其功能已被新固件覆盖和扩展。
### 4.1. MQTT 连接配置
* **Broker 地址**: 单片机需配置连接到与后端服务相同的 MQTT Broker (例如 `tcp://your_mqtt_broker_address:1883`)。
* **Client ID**: 每个充电桩应使用唯一的 Client ID。建议使用充电桩的物理ID或序列号，例如 `charger_spot_001`。
* **认证**: 如果 MQTT Broker 配置了用户名/密码认证，单片机连接时也需提供。
* **Client ID**: 每个充电桩应使用唯一的 Client ID。对于新固件，这在 `esp32_robot_firmware/config.h` 中通过 `DEVICE_UID` 配置，必须与后端系统中注册的机器人ID一致。
* **认证**: 如果 MQTT Broker 配置了用户名/密码认证，单片机连接时也需提供 (在 `config.h` 中配置)。
### 4.2. MQTT 主题 (Topics) 约定
@@ -138,7 +139,7 @@
所有类型的上行消息，包括设备状态更新、心跳以及对后端指令的执行回执 (ACK)，都统一发送到以下主题：
* **统一上行主题格式**: `yupi_mqtt_power_project/robot/status/{spotUid}`
* `{spotUid}`: 充电桩/车位的唯一标识符 (例如 `ESP32_SPOT_001`，必须与后端系统中注册的设备ID一致)。
* `{spotUid}`: 充电桩/车位的唯一标识符 (例如 `ESP32_SPOT_001`，即 `DEVICE_UID`)。
* **消息格式 (Payload)**: JSON。
消息体结构应与后端 `com.yupi.project.model.dto.mqtt.RobotStatusMessage` 类对应。通过消息体内的字段来区分具体的消息含义。
@@ -148,24 +149,43 @@
"robotUid": "ESP32_SPOT_001",
"actualRobotStatus": "CHARGING", // 设备当前状态, 如 IDLE, MOVING, CHARGING, COMPLETED, FAULTED
// 以下为可选的详细状态，根据实际需求和后端处理逻辑添加
"voltage": 220.5, // 充电时相关
"current": 5.1, // 充电时相关
"power": 1.12, // kW, 充电时相关
"energyConsumed": 0.5, // kWh, 本次充电已消耗电量
"voltage": 0, // 充电时相关 (示例值，实际由固件模拟或测量)
"current": 0, // 充电时相关 (示例值)
"power": 0, // kW, 充电时相关 (示例值)
"energyConsumed": 0, // kWh, 本次充电已消耗电量 (示例值)
"batteryLevel": 85, // 机器人当前电量百分比
"currentLocation": "SPOT_ID_001", // 机器人当前所在或最后到达的位置ID
"chargeDurationSeconds": 120, // 如果在充电状态，已充电时长（秒）
"errorCode": 0, // 0表示无错误，其他值表示特定错误类型
"message": "Status normal", // 附加信息，例如错误描述
"activeTaskId": "session_xyz123" // 如果设备当前正在执行某个任务或会话，上报其ID
}
```
**示例 - 对后端指令的ACK (成功):**
**示例 - 对后端指令的ACK (成功, 以MOVE_TO_SPOT为例):**
机器人成功到达目标车位并开始充电后，发送此ACK。
**注意：后端期望的ACK格式包含 `command_ack` (指令的中文描述), `task_id` (数字类型), 和 `success` (布尔类型)。**
```json
{
"robotUid": "ESP32_SPOT_001",
"taskId": "backend_task_789", // 对应后端指令中的taskId
"status": "SUCCESS", // 指令执行结果: SUCCESS 或 FAILURE
"message": "Command executed successfully",
"actualRobotStatus": "IDLE", // ACK发生时，设备的当前核心状态
"activeTaskId": "session_abc456" // 可选，如果ACK与特定会话相关
"command_ack": "移动到指定点",
"task_id": 789,
"success": true,
"message": "Move to spot completed, charging started.",
"actualRobotStatus": "CHARGING",
"spotId": "SPOT_UID_001"
}
```
**示例 - 对后端指令的ACK (失败):**
```json
{
"robotUid": "ESP32_SPOT_001",
"command_ack": "移动到指定点",
"task_id": 790,
"success": false,
"message": "Failed to reach spot, obstacle detected.",
"actualRobotStatus": "FAULTED"
}
```
@@ -178,16 +198,18 @@
* **消息格式 (Payload)**: JSON。
JSON消息体内部包含了具体的指令类型和所需参数。
**示例 - 移动到车位指令 (MOVE_TO_SPOT):**
此指令指示机器人移动到指定车位。机器人到达后将自动进入充电状态。
**示例 - 移动到车位指令 (后端实际发送格式):**
此指令指示机器人移动到指定车位。**机器人到达后将自动进入充电状态并上报。**
后端实际发送的指令可能使用 `command` 字段。
```json
{
"commandType": "MOVE_TO_SPOT",
"taskId": "backend_task_id_for_ack_789", // 供单片机ACK时使用的任务ID
"target_spot_uid": "SPOT_UID_001" // 目标车位ID (单片机仅用于确认，主要由 spotUid 主题参数决定目标)
// "sessionId": "session_abc_123" // 可选，如果需要在payload中也传递会话ID
"command": "MOVE",
"target_spot_uid": "SPOT_UID_001",
"taskId": "backend_task_id_for_ack_789",
"sessionId": "session_abc_123"
}
```
* 单片机固件 (`esp32_robot_firmware`) 已兼容解析 `command` 或 `commandType` 字段作为指令类型。
**示例 - 停止充电指令 (STOP_CHARGE):**
```json
@@ -197,37 +219,68 @@
"sessionId": "session_abc_123" // 关联的充电会话ID
}
```
* **单片机处理逻辑**: 单片机收到消息后，需解析JSON负载，识别 `commandType`，提取 `taskId` (用于后续ACK)，并获取其他指令参数来执行相应操作。 对于 `MOVE_TO_SPOT`，到达后自动转换为 `CHARGING` 状态。
### 4.3. 单片机开发关键逻辑
1. **MQTT 初始化与重连机制**。
2. **订阅指令主题**。
3. **JSON 指令消息解析**。
4. **移动控制** (如果机器人需要物理移动)。
5. **充电启停控制** (继电器等硬件操作，停止充电时需要)。
6. **状态监测与实时上报**:
* 收到 `MOVE_TO_SPOT` 后，状态变为 `MOVING` 并上报。
* 到达目标车位后，状态变为 `CHARGING` 并上报，同时对 `MOVE_TO_SPOT` 指令进行ACK。
* 收到 `STOP_CHARGE` 后，停止充电，状态变为 `COMPLETED` (或 `IDLE`) 并上报，同时对 `STOP_CHARGE` 指令进行ACK。
7. **心跳包定时发送**。
8. **故障检测与上报**。
9. **安全性**: 确保 `spotUid` 唯一性；推荐 MQTT 通信使用 TLS/SSL 加密。
**示例 - 开始充电指令 (START_CHARGE):**
**注意: 此指令当前未被后端主动使用。业务逻辑已调整为机器人到达车位后自动开始充电 (`MOVE_TO_SPOT` 完成即充电)。保留此指令定义主要为了兼容性或未来可能的扩展。单片机固件目前仅简单ACK此指令。**
```json
{
"commandType": "START_CHARGE",
"taskId": "backend_task_id_for_ack_111",
"sessionId": "session_def_456" // 关联的充电会话ID
}
```
### 4.4. 示例流程：用户启动充电 (更新后)
* **单片机处理逻辑**: 单片机收到消息后，需解析JSON负载，识别 `commandType`，提取 `taskId` (用于后续ACK)，并获取其他指令参数来执行相应操作。
* 对于 `MOVE_TO_SPOT` (或后端发送的`MOVE`): 执行移动，到达后自动转换到 `CHARGING` 状态，并上报符合后端期望格式的ACK (包含`command_ack`, `task_id`, `success`等)及新状态。
* 对于 `STOP_CHARGE`: 停止充电（如断开继电器），更新状态为 `COMPLETED` (或 `IDLE`)，并上报符合后端期望格式的ACK及新状态。
* 对于 `START_CHARGE` (当前): 仅发送符合后端期望格式的ACK表示收到指令。
### 4.3. 单片机开发关键逻辑 (基于 `esp32_robot_firmware`)
1. **配置 (`config.h`)**: 仔细配置WiFi凭据、MQTT Broker、`DEVICE_UID`以及所有硬件引脚。
2. **MQTT 初始化与重连机制** (由 `mqtt_handler.cpp` 处理)。
3. **订阅指令主题** (由 `mqtt_handler.cpp` 处理)。
4. **JSON 指令消息解析** (在 `esp32_robot_firmware.ino` 的 `handle_mqtt_command` 中处理, `mqtt_handler.cpp`的`callback`负责通用解析并调用回调)。
* 需能正确解析后端下发的指令，如 `MOVE` (实际) 或 `MOVE_TO_SPOT` (枚举定义)。
5. **移动控制** (由 `motor_control.cpp` 和 `navigation.cpp` 实现)。
6. **充电启停控制** (由 `relay_control.cpp` 实现，停止充电时操作继电器)。
7. **状态监测与实时上报** (主要在 `esp32_robot_firmware.ino` 的 `loop()` 函数和 `handle_mqtt_command` 中管理和触发):
* 收到 `MOVE` (或 `MOVE_TO_SPOT`) 指令后，`current_robot_status` 变为 `MOVING`，`target_spot_for_move` 被设置，并立即上报状态。
* `loop()` 函数中的导航逻辑 (`navigation_move_to_spot()`) 执行移动。
* 成功到达目标车位后 (`navigation_move_to_spot()` 返回成功):
* `current_robot_status` 变为 `CHARGING`。
* `robot_current_location` 更新为到达的车位ID。
* 调用 `relay_start_charging()`。
* 向上行主题发送 `MOVE` 指令的成功ACK。**此ACK需符合后端期望格式**: 包含 `robotUid`, `command_ack` (值为"移动到指定点"), `task_id` (来自原指令, 类型为数字), `success` (true), `message`, `actualRobotStatus` ("CHARGING"), 和 `spotId`。
* 立即上报一次完整的 `CHARGING` 状态。
* 导航失败后 (`navigation_move_to_spot()` 返回失败):
* `current_robot_status` 变为 `FAULTED`。
* 向上行主题发送 `MOVE` 指令的失败ACK。**此ACK需符合后端期望格式**: 包含 `command_ack` (值为"移动到指定点"), `task_id`, `success` (false), `message` (错误信息), `actualRobotStatus` ("FAULTED")。
* 立即上报一次完整的 `FAULTED` 状态。
* 收到 `STOP_CHARGE` 后:
* 调用 `relay_stop_charging()`。
* `current_robot_status` 变为 `COMPLETED` (或 `IDLE`，根据固件逻辑)。
* 向上行主题发送 `STOP_CHARGE` 的成功ACK。**此ACK需符合后端期望格式**: 包含 `command_ack` (值为"停止充电"), `task_id`, `success` (true), `message`, `actualRobotStatus` ("COMPLETED")。
* 立即上报一次完整的状态。
8. **心跳包定时发送** (由 `esp32_robot_firmware.ino` 的 `loop()` 函数处理)。
9. **故障检测与上报** (部分在导航逻辑中处理，状态上报时包含错误码)。
10. **安全性**: 确保 `DEVICE_UID` 唯一性；推荐 MQTT 通信使用 TLS/SSL 加密 (当前固件未直接集成，需额外配置)。
11. **电池电量模拟与上报** (由 `esp32_robot_firmware.ino` 的 `simulate_battery_update()` 和状态上报逻辑处理)。
### 4.4. 示例流程：用户启动充电 (已更新为到达即充逻辑)
1. 用户在前端 App 请求在车位 `SPOT001` 进行充电。
2. 后端服务验证，创建充电会话 `sessionId=789`，状态为 `REQUESTED`。
3. 后端分配机器人，创建 `MOVE_TO_SPOT` 任务 (例如 `taskId=task_move_123`)，并将机器人DB状态更新为 `MOVING`，会话状态更新为 `ROBOT_ASSIGNED`。
4. 后端向 MQTT 主题 `yupi_mqtt_power_project/robot/command/SPOT001` 发布 `MOVE_TO_SPOT` 指令，payload 包含 `taskId=task_move_123`。
5. 单片机 `SPOT001` 接收指令：
a. 将其内部状态更新为 `MOVING`。
b. 向上行主题 `yupi_mqtt_power_project/robot/status/SPOT001` 上报状态 `MOVING`。
c. (模拟)执行移动。
d. 移动到达后，将其内部状态更新为 `CHARGING`。
e. 向上行主题发送 ACK 消息，确认 `taskId=task_move_123` 完成，消息中 `actualRobotStatus` 为 `CHARGING`。
f. (可选，或由ACK消息覆盖) 再次向上行主题上报状态 `CHARGING`，包含 `sessionId`。
3. 后端分配机器人 (例如 `DEVICE_UID=ESP32_BOT_001`)，创建 `MOVE_TO_SPOT` 任务 (例如 `taskId=task_move_123`)，并将机器人DB状态更新为 `ASSIGNED` (或 `MOVING`，取决于后端状态流转设计)，会话状态更新为 `ROBOT_ASSIGNED`。
4. 后端向 MQTT 主题 `yupi_mqtt_power_project/robot/command/ESP32_BOT_001` 发布 `MOVE_TO_SPOT` 指令，payload 包含 `taskId=task_move_123` 和 `target_spot_uid="SPOT001"`。
5. 单片机 `ESP32_BOT_001` 接收指令：
a. 将其内部状态 `current_robot_status` 更新为 `MOVING`。
b. 向上行主题 `yupi_mqtt_power_project/robot/status/ESP32_BOT_001` 上报状态 `MOVING`。
c. 执行导航到 `SPOT001`。
d. 移动到达后，将其内部状态 `current_robot_status` 更新为 `CHARGING`，`robot_current_location` 更新为 `SPOT001`，并启动充电 (闭合继电器)。
e. 向上行主题发送 ACK 消息，确认 `taskId=task_move_123` 完成，消息中 `actualRobotStatus` 为 `CHARGING`，并包含 `spotId="SPOT001"`。
f. (通常ACK消息已包含最新状态，但为确保) 再次向上行主题上报完整的 `CHARGING` 状态，包含 `sessionId` 和 `chargeDurationSeconds` (初始为0)。
6. 后端接收到 `MOVE_TO_SPOT` 任务 ( `taskId=task_move_123`) 的 ACK (其中机器人状态为 `CHARGING`):
a. 将 `RobotTask` ( `taskId=task_move_123`) 标记为 `COMPLETED`。
b. 将机器人 `SPOT001` 在数据库中的状态更新为 `CHARGING`。
b. 将机器人 `ESP32_BOT_001` 在数据库中的状态更新为 `CHARGING`。
c. 将充电会话 `sessionId=789` 的状态更新为 `CHARGING_STARTED`，并记录充电开始时间。
7. 前端界面同步更新，显示充电已开始。
@@ -239,6 +292,15 @@
│ ├── src/
│ ├── public/
│ └── package.json
├── esp32_robot_firmware/ # ESP32 机器人固件项目 (推荐使用)
│ ├── esp32_robot_firmware.ino # 主程序文件
│ ├── config.h # 配置文件 (WiFi, MQTT, 引脚等)
│ ├── mqtt_handler.h/.cpp # MQTT 通信处理
│ ├── motor_control.h/.cpp # 电机与舵机控制
│ ├── sensor_handler.h/.cpp # 传感器数据读取
│ ├── navigation.h/.cpp # 导航与循迹逻辑
│ ├── relay_control.h/.cpp # 继电器控制 (模拟充电)
│ └── NEXT_STEPS.md # 后续开发与测试步骤指南
├── springboot-init-main/ # 后端 Spring Boot 应用
│ ├── src/
│ │ ├── main/
@@ -247,10 +309,36 @@
│ │ └── test/
│ ├── doc/ # 项目文档 (如数据库DDL, 阶段计划等)
│ └── pom.xml
├── mqtt_esp32_client.ino # 旧的、简易的ESP32 MQTT模拟器 (不推荐新开发使用)
└── README.md # 本文件
```
## 6. 后续工作与展望
## 6. ESP32 固件 (`esp32_robot_firmware`) 使用入门
1. **环境准备**:
* 安装 Arduino IDE 或 PlatformIO IDE。
* 在IDE中安装 ESP32 开发板支持。
* 根据需要安装相关库 (如 `PubSubClient` for MQTT, `ESP32Servo` for Servo control等，大部分已包含在ESP32核心库中或作为标准库提供)。
2. **打开项目**:
* 使用IDE打开 `esp32_robot_firmware/esp32_robot_firmware.ino`。IDE通常会自动加载文件夹内所有 `.h` 和 `.cpp` 文件。
3. **配置 `config.h`**:
* **非常重要**: 打开 `config.h` 文件。
* 填写您的 `WIFI_SSID` 和 `WIFI_PASSWORD`。
* 配置 `MQTT_BROKER_HOST`, `MQTT_BROKER_PORT`, 以及可选的 `MQTT_USERNAME`, `MQTT_PASSWORD`。
* **设置 `DEVICE_UID`**: 此ID必须与您在后端系统中为该机器人注册的ID完全一致。
* **核对并修改所有硬件引脚定义** (`MOTOR_*_PIN`, `SERVO_PIN`, `ULTRASONIC_*_PIN`, `TCRT5000_*_PIN`, `RELAY_PIN`) 以匹配您的实际硬件连接。
* 调整其他业务参数如 `SIDE_ULTRASONIC_SPOT_THRESHOLD_CM`, `NUM_CHARGING_SPOTS` 等。
4. **编译与烧录**:
* 选择正确的ESP32开发板型号和端口。
* 编译并上传固件到您的ESP32设备。
5. **监控与调试**:
* 打开串口监视器 (波特率在 `config.h` 中 `SERIAL_BAUD_RATE` 定义，默认为 115200)。
* 观察串口输出，检查WiFi连接、MQTT连接状态、传感器读数、指令接收和状态上报等。
* 参考 `esp32_robot_firmware/NEXT_STEPS.md` 文件进行详细的模块化测试和导航逻辑调试。
**重要提示**: `navigation.cpp` 中的循迹逻辑 (`navigation_follow_line_once`) 是一个非常基础的实现，**您极有可能需要根据您的具体机器人平台、传感器和环境对其进行大幅修改和参数调优，甚至采用更高级的控制算法（如PID）才能获得满意的循迹效果。** `NEXT_STEPS.md` 提供了更详细的指导。
## 7. 后续工作与展望
* 完善各模块的单元测试和集成测试。
* 进一步优化 API 文档和错误处理机制。
* 根据实际运营需求，增加更细致的统计报表功能。