176 lines
6.5 KiB
Markdown
176 lines
6.5 KiB
Markdown
激光雷达管理模块 (Laser Manager) 🚀
|
||
===========================
|
||
|
||
本模块专为 **STM32H7 + FreeRTOS** 环境打造，用于同时驱动和解析 4 路单点激光雷达（2 路连续流 STP-23L，2 路文本流 ATK-MS53L1M）。
|
||
|
||
采用 **DMA 环形缓冲 + 串口空闲中断 (IDLE) + RTOS 事件驱动** 架构，彻底消灭单字节中断引起的 CPU 拥堵，是适用于机器人底盘避障与路径规划的“企业级”底层驱动。
|
||
✨ 核心特性
|
||
------
|
||
|
||
1. **零中断阻塞**：所有数据均由硬件 DMA 搬运，CPU 仅在数据接收过半/完成或触发 IDLE 空闲时被唤醒。
|
||
|
||
2. **免 Cache 物理隔离**：基于 MPU 划分专用 `.dma_buffer` 特区，彻底杜绝 Cortex-M7 的 Cache 一致性导致的数据乱码或 USB 掉线问题。
|
||
|
||
3. **极速解析算法**：
|
||
|
||
* **STP 协议**：采用 O(1) 环形指针流式提取，**0 内存搬运 (`memmove`)**。
|
||
|
||
* **ATK 协议**：采用 O(1) 字符特征匹配，彻底抛弃耗时的 `strstr` 和 `strtol` 标准库函数。
|
||
|
||
4. **高质量数据输出**：内置 **滑动中值滤波 (Median Filter)**，有效剔除玻璃反光、灰尘引起的突发测距尖峰，提供平滑稳定的控制级数据。
|
||
|
||
5. **安全可靠**：
|
||
|
||
* 采用 `taskENTER_CRITICAL()` 保护快照读取，杜绝多线程数据撕裂。
|
||
|
||
* 严格区分中断上下文 (`FROM_ISR`) 与任务上下文的临界区调用。
|
||
|
||
* 内置 `HAL_UART_ErrorCallback`，在遭受电磁干扰触发 ORE/FE 错误时自动重启 DMA，永久防死机。
|
||
|
||
* * *
|
||
|
||
⚙️ 移植与配置指南
|
||
----------
|
||
|
||
### 第一步：STM32CubeMX 硬件配置
|
||
|
||
1. **MPU 设置 (极其重要)**
|
||
|
||
* 进入 `Cortex-M7` -> `MPU Control`
|
||
|
||
* Enable MPU
|
||
|
||
* **Region 1**: Base Address = **`0x30000000`**, Size = **`32KB`**
|
||
|
||
* Access Permission: **`ALL ACCESS PERMITTED`**
|
||
|
||
* Cacheable: **`Disable`** (彻底关闭该区域的 D-Cache)
|
||
|
||
2. **串口与 DMA 设置**
|
||
|
||
* **STP 雷达** (如 USART2, UART4 - 230400bps)：添加 RX DMA，模式选 **`Circular`** (数据宽度 Byte)。优先级建议设为 **`High`**。
|
||
|
||
* **ATK 雷达** (如 USART3, USART6 - 115200bps)：添加 RX DMA，模式选 **`Circular`**。优先级设为 **`Medium`**。
|
||
|
||
* **NVIC**：必须开启这 4 个串口的**全局中断 (Global Interrupt)**。
|
||
|
||
### 第二步：链接脚本 (.ld) 配置
|
||
|
||
打开工程的链接脚本（如 `STM32H743XX_FLASH.ld`），在 `RAM_D2` 区域添加 `.dma_buffer` 段定义：
|
||
|
||
代码段
|
||
/* 给雷达 DMA 专门划分的免 Cache 区域 */
|
||
.dma_buffer (NOLOAD) :
|
||
{
|
||
. = ALIGN(32);
|
||
*(.dma_buffer)
|
||
*(.dma_buffer*)
|
||
. = ALIGN(32);
|
||
} >RAM_D2
|
||
|
||
### 第三步：中断回调接管
|
||
|
||
确保在 `usart.c` 或 `main.c` 中 **删除或注释掉** 旧的串口接收回调，因为 `laser_manager.c` 底部已经重写了以下函数并接管了整个链路：
|
||
|
||
* `HAL_UART_RxCpltCallback`
|
||
|
||
* `HAL_UART_RxHalfCpltCallback`
|
||
|
||
* `HAL_UARTEx_RxEventCallback` (用于处理 IDLE)
|
||
|
||
* `HAL_UART_ErrorCallback` (用于自动恢复错误)
|
||
|
||
* * *
|
||
|
||
💻 API 使用说明
|
||
-----------
|
||
|
||
### 1. 数据结构概览
|
||
|
||
C
|
||
typedef struct {
|
||
uint16_t distance_mm; // 经过中值滤波处理后平滑的距离值 (推荐用于避障控制)
|
||
uint16_t raw_distance_mm; // 传感器吐出的原始跳动距离值 (仅供调试观察)
|
||
uint8_t valid; // 数据是否有效 (1:有效, 0:无效)
|
||
uint8_t online; // 雷达是否在线 (未超时)
|
||
uint8_t fault_code; // 故障码 (0x00:正常, 0x80:掉线超时)
|
||
uint32_t update_tick_ms; // 最后一次数据刷新的系统 tick
|
||
} laser_simple_data_t;
|
||
|
||
### 2. 初始化与任务启动
|
||
|
||
在 FreeRTOS 调度器启动前（或统一的应用初始化任务中）调用初始化接口。它会自动配置并开启 DMA，同时创建一个高优先级的解析守护任务。
|
||
|
||
C
|
||
#include "laser/laser_manager.h"
|
||
|
||
// 在 main.c 或 app_tasks.c 初始化阶段调用
|
||
LASER_SIMPLE_Init();
|
||
|
||
### 3. 数据轮询与读取 (应用层)
|
||
|
||
在你的应用周期任务中（如 `100ms` 测试任务或控制任务），调用 `Poll` 并获取快照指针：
|
||
|
||
C
|
||
void AppTasks_RunLaserTestTask_Impl(void *argument)
|
||
{
|
||
const laser_simple_snapshot_t *snap;
|
||
uint32_t print_divider = 0;
|
||
|
||
LASER_SIMPLE_Init();
|
||
|
||
for(;;)
|
||
{
|
||
// 1. 触发状态机巡检 (更新在线状态/超时)
|
||
LASER_SIMPLE_Poll(HAL_GetTick());
|
||
|
||
// 2. 获取绝对安全、无撕裂的全局数据快照
|
||
snap = LASER_SIMPLE_GetSnapshot();
|
||
|
||
// 3. 降频打印 (例如每 500ms 打印一次)
|
||
if (++print_divider >= 5)
|
||
{
|
||
print_divider = 0;
|
||
printf("F_STP [Filter:%4umm, Raw:%4umm] Valid:%d Fault:%02X\r\n",
|
||
snap->ch[LASER_CH_FRONT_STP].distance_mm,
|
||
snap->ch[LASER_CH_FRONT_STP].raw_distance_mm,
|
||
snap->ch[LASER_CH_FRONT_STP].valid,
|
||
snap->ch[LASER_CH_FRONT_STP].fault_code);
|
||
}
|
||
|
||
osDelay(100); // 维持高频巡检节拍 (切勿大于雷达设定的 Timeout 时间)
|
||
}
|
||
}
|
||
|
||
### 4. 便捷测距接口
|
||
|
||
如果你的小车只需要知道“前方/后方离障碍物最近是多少”，可以直接调用辅助接口：
|
||
|
||
C
|
||
// 获取前/后两路雷达中，最近且有效的平滑距离值 (毫米)
|
||
uint16_t front_min_dist = LASER_SIMPLE_GetFrontNearest();
|
||
uint16_t rear_min_dist = LASER_SIMPLE_GetRearNearest();
|
||
|
||
* * *
|
||
|
||
❓ 常见问题 (Troubleshooting)
|
||
------------------------
|
||
|
||
**Q: 烧录程序后，USB 虚拟串口无法识别 (或电脑提示无法识别的 USB 设备)？**
|
||
|
||
> **A:** 请检查 MPU 配置是否生效，以及链接脚本中是否正确加入了 `.dma_buffer`。如果 DMA 数组被编译器分配到了带有 D-Cache 的内存中，USB 外设会因为内存一致性冲突而死机。
|
||
|
||
**Q: 雷达数据一直是 0，且终端不停输出 FaultCode `0x80`？**
|
||
|
||
> **A:** `0x80` 代表超时掉线。请检查：
|
||
>
|
||
> 1. 雷达硬件连线（RX/TX 是否接反）。
|
||
>
|
||
> 2. `CubeMX` 中 4 个串口是否正确开启了**全局中断**（未开启中断将无法唤醒解析任务）。
|
||
>
|
||
> 3. 波特率是否匹配（STP: `230400`，ATK: `115200`）。
|
||
|
||
**Q: 想要调整中值滤波的平滑程度？**
|
||
|
||
> **A:** 在 `laser_manager.c` 顶部修改 `#define FILTER_WIN_SZ 3U`。改为 `5U` 会更平滑，但会增加几毫秒的系统响应延迟。通常 `3` 是最佳平衡点。
|