# ESP32 机器人固件 - 后续步骤与待办事项

本文档旨在记录在当前固件版本基础上，您需要完成的配置、代码调整以及后续的测试和开发步骤。

## 1. 关键配置与代码调整 (必须)

在烧录和测试之前，请务必完成以下配置和代码检查/调整：

### 1.1. `config.h` - 硬件与网络配置

打开 `esp32_robot_firmware/config.h` 文件，根据您的实际情况修改以下宏定义：

*   **WiFi 配置**:
    *   `WIFI_SSID`: 您的WiFi网络名称。
    *   `WIFI_PASSWORD`: 您的WiFi密码。
*   **MQTT Broker 配置**:
    *   检查 `MQTT_BROKER_HOST`, `MQTT_BROKER_PORT` 是否适用于您的MQTT代理。
    *   如果您的代理需要认证，请更新 `MQTT_USERNAME` 和 `MQTT_PASSWORD`。
*   **设备唯一标识符**:
    *   `DEVICE_UID`: **极其重要**，必须与您在后端系统中注册的机器人ID完全一致。
*   **硬件引脚定义**:
    *   `MOTOR_LEFT_IN1_PIN`, `MOTOR_LEFT_IN2_PIN`, `MOTOR_LEFT_ENA_PIN`
    *   `MOTOR_RIGHT_IN3_PIN`, `MOTOR_RIGHT_IN4_PIN`, `MOTOR_RIGHT_ENB_PIN`
    *   `SERVO_PIN`
    *   `ULTRASONIC_FRONT_TRIG_PIN`, `ULTRASONIC_FRONT_ECHO_PIN`
    *   `ULTRASONIC_SIDE_TRIG_PIN`, `ULTRASONIC_SIDE_ECHO_PIN`
    *   `TCRT5000_LEFT_PIN`, `TCRT5000_RIGHT_PIN` (以及您可能添加的更多循迹传感器引脚)
    *   `RELAY_PIN`
    *   **请仔细核对这些引脚号是否与您ESP32板子上实际连接的硬件引脚一致。**
*   **业务逻辑参数**:
    *   `SIDE_ULTRASONIC_SPOT_THRESHOLD_CM`: 侧向超声波检测到充电桩的距离阈值，根据实际情况调整。
    *   `NUM_CHARGING_SPOTS` 和 `SPOT_ID_1`, `SPOT_ID_2`, `SPOT_ID_3`: 根据您的充电桩数量和ID定义进行调整。

### 1.2. `navigation.cpp` - 循迹逻辑 (`navigation_follow_line_once`)

当前 `navigation_follow_line_once` 函数中的循迹逻辑非常基础，**很可能无法直接在您的机器人上良好工作**。您需要：

*   **大幅调整**: 根据您的循迹传感器类型（模拟/数字）、数量、安装位置以及机器人的机械结构（轮子、电机特性）来修改逻辑。
*   **参数校准**: `base_speed`, `turn_speed_diff`, `servo_turn_angle_small`, `servo_turn_angle_large` 等参数需要反复实验和校准。
*   **考虑PID控制**: 为了实现更平滑、更准确的循迹，强烈建议研究并实现PID（比例-积分-微分）控制算法。代码中已预留了PID相关的变量和注释框架。
*   **脱线处理**: 当前脱线处理很简单（停止），您可能需要实现更复杂的逻辑，如原地旋转搜索线路。

### 1.3. `sensor_handler.cpp` - 传感器校准

*   **TCRT5000循迹传感器**:
    *   打开 `sensor_handler.h`，校准 `TCRT5000_THRESHOLD` 的值。这个值取决于您的传感器、巡的线的颜色、地面的颜色。
    *   在 `sensor_handler.cpp` 的 `is_on_line` 函数中，确认 `return sensor_value > threshold;` 这行（或您修改后的逻辑）是否正确反映了传感器在黑线上和不在黑线上的读数关系（是值变大还是变小）。
*   **超声波传感器**:
    *   测试 `get_ultrasonic_distance_cm` 函数的准确性。`pulseIn` 的超时时间可能需要根据实际最大探测距离调整。

### 1.4. `relay_control.cpp` - 继电器逻辑

*   确认 `relay_setup()` 中 `digitalWrite(RELAY_PIN, LOW);` 是否使继电器处于断开状态。有些继电器模块可能是高电平触发断开。相应地调整 `relay_start_charging()` 和 `relay_stop_charging()` 中的 `HIGH`/`LOW`。

## 2. 后续开发与测试步骤

完成上述配置和初步代码调整后，按以下步骤进行测试和进一步开发：

### 2.1. 模块化硬件测试与校准

逐个模块进行测试，确保硬件按预期工作：

*   **电机 (`motor_control.cpp`)**:
    *   测试 `motor_move_forward()`, `motor_move_backward()`, `motor_stop()`。
    *   测试 `motor_turn_left()`, `motor_turn_right()`，观察差速和舵机辅助转向的效果。调整速度、转向强度和舵机角度参数。
    *   确保 `set_motor_speed()` 中 `MOTOR_LEFT_IN1_PIN` 等引脚的 `HIGH`/`LOW` 组合能正确控制电机方向。
*   **舵机 (`motor_control.cpp`)**:
    *   测试 `servo_set_angle()`, `servo_center()`。确认舵机转动范围和中心位置是否准确。
*   **传感器 (`sensor_handler.cpp`)**:
    *   **超声波**: 独立测试前方和侧方超声波传感器，验证距离读数的准确性。
    *   **TCRT5000循迹**: 重点测试 `get_line_follow_values()`，手动移动传感器或机器人，观察 `left_on_line` 和 `right_on_line` 是否能正确反映传感器相对于引导线的位置。
*   **继电器 (`relay_control.cpp`)**:
    *   测试 `relay_start_charging()` 和 `relay_stop_charging()` 是否能正确控制继电器（以及与之关联的任何指示灯或设备）。

### 2.2. 导航逻辑调试 (`navigation.cpp`)

这是最复杂且耗时的部分：

*   **循迹 (`navigation_follow_line_once`)**:
    *   将机器人放在引导线上，逐步调试循迹逻辑。
    *   从低速开始，逐步增加速度。
    *   细致调整转向逻辑和参数，目标是让机器人能够平稳、准确地跟随线路。
    *   处理各种情况：直线、弯道、可能的交叉点（如果场景中有）。
*   **车位检测 (`navigation_check_spot_arrival`)**:
    *   测试侧向超声波传感器检测充电桩（或模拟物）的逻辑。
    *   校准 `SIDE_ULTRASONIC_SPOT_THRESHOLD_CM`。
    *   测试 `SPOT_DEBOUNCE_TIME_MS` 去抖逻辑，确保路过一个桩时只计数一次。
    *   验证 `detected_spot_count` 是否能正确累计。
*   **避障 (`navigation_check_obstacle`, `navigation_handle_obstacle`)**:
    *   测试前方超声波传感器检测障碍物的逻辑。
    *   当前的 `navigation_handle_obstacle` 只是停止，您可以根据需求实现更复杂的避障策略（如后退、转向绕行等）。
*   **完整导航 (`navigation_move_to_spot`)**:
    *   测试从起点到指定目标充电桩的完整导航过程。
    *   观察状态转换、车位计数、最终到达判断是否都符合预期。
    *   测试导航超时逻辑 (`MAX_NAV_TIME_MS`)。

### 2.3. 状态同步与MQTT测试 (`mqtt_handler.cpp`, `esp32_robot_firmware.ino`)

*   **连接**: 确保ESP32能成功连接WiFi和MQTT Broker。
*   **指令接收**: 从后端（或使用MQTT客户端工具）发送指令（MOVE, STOP_CHARGE），检查 `handle_mqtt_command` 是否能正确解析并触发相应动作。
*   **ACK上报**: 验证机器人是否能正确上报ACK消息，包括成功和失败的情况。
*   **状态上报**:
    *   监控机器人定期上报的状态消息。
    *   验证 `current_robot_status`, `robot_current_location`, `robot_battery_level` 等字段是否准确。
    *   特别关注 `CHARGING` 状态下的 `durationSeconds` 和 `spotId`，以及 `FAULTED` 状态下的 `errorCode` 和 `message`。
*   **心跳**: 检查心跳消息是否按预期发送。

### 2.4. 整体联调与鲁棒性测试

*   将所有模块集成起来，进行完整的业务流程测试：
    *   接收移动指令 -> 移动到车位 -> 到达后自动开始充电 -> 状态更新 -> 接收停止充电指令 -> 停止充电 -> 状态更新。
*   测试各种边界条件和异常情况：
    *   WiFi/MQTT断开重连。
    *   导航中途遇到障碍。
    *   目标车位不存在或无法到达。
    *   电池电量模拟变化是否合理。
*   长时间运行测试，观察系统稳定性和资源占用情况（虽然在ESP32上较难直接监控内存）。

## 3. 代码结构与进一步优化建议

*   **错误处理**: 当前的错误处理还比较基础，可以考虑更细致的错误码和错误信息。
*   **状态机完善**: `esp32_robot_firmware.ino` 中的主循环可以进一步优化为更清晰的状态机。
*   **非阻塞操作**: `navigation_move_to_spot` 目前是阻塞函数。对于更复杂的应用，可以考虑将其改造为非阻塞的，通过在 `loop()` 中轮询其状态来执行。但这会显著增加复杂性。
*   **代码注释和可读性**: 在您修改和添加代码时，保持良好的注释习惯。

祝您项目顺利！ 