STM32-FreeRTOS-K210-SmartCar

KO | EN

gitlite — search

#python #hacktoberfest #ai #llm #go #rust #linux #kubernetes #awesome-list #vue #mcp #ios #openai #open-source

STM32-FreeRTOS-K210-SmartCar

(★ 19)

一个基于 STM32 和 FreeRTOS 的智能小车项目。结合 K210 视觉模块实现色块追踪与自动循迹，具备 PID 闭环控制、异构多核串口通信及 OLED 多级菜单交互功能。

STM32-FreeRTOS-K210-SmartCar Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# FreeRTOS 小车（STM32F103 + K210 黑线循迹）

## 项目简介

这是一个基于 `STM32F103` 的多模式智能小车项目，使用 `FreeRTOS` 进行任务调度，支持：

- K210 视觉黑线循迹（当前 README 按 `v13（v2）` 方案说明）
- 超声避障
- 超声跟随
- MPU6050 航向保持直行
- OLED 本地菜单调参与参数保存（Flash 持久化）

项目整体思路是把“模式决策”和“电机底层控制”分开：

- `LogicTask` 负责模式状态机与目标速度生成
- `ControlTask` 负责速度闭环 PID 和电机输出

这样调试时更容易定位问题，也方便逐步替换 K210 算法。

## 项目目标（当前版本）

- 优先保证小车运行稳定
- 在弯道尽量不掉线
- 参数可在车上直接调，不依赖反复改代码烧录
- 保留后续继续优化 K210 视觉算法的空间

## 硬件组成

## 主控与执行

- `STM32F103` 主控（HAL + FreeRTOS）
- 双路直流减速电机（带编码器）
- 电机驱动模块（代码已适配双轮差速控制，具体驱动芯片按你的实物）

## 传感器与视觉

- `K210` 视觉模块（黑线识别，串口输出循迹误差）
- `HC-SR04` 超声波模块（避障 / 跟随）
- `MPU6050`（含 DMP 姿态解算，用于航向保持）
- 4 路灰度/红外输入（`HW_OUT_1~4`，项目里保留并采样）

## 人机交互与通信

- `OLED` 显示屏（本地菜单与状态显示）
- 2 个按键（菜单导航 / 参数编辑）
- 串口通信（蓝牙/遥控命令、K210 视觉数据）

## 软件架构

## FreeRTOS 任务划分（核心）

项目采用 FreeRTOS 静态任务与静态队列，降低动态分配风险，主要任务如下：

- `ControlTask`
  - 电机速度闭环控制（编码器反馈 + PID）
  - 接收 `MotorTargetQueue` 的最新目标速度并输出 PWM
- `SensorTask`
  - 周期采集灰度输入、超声、MPU6050 姿态
  - 组装为传感器快照供逻辑层使用
- `VisionTask`
  - 从 UART 解析后的视觉队列读取 K210 数据
  - 做轻量滤波、质量裁剪，更新视觉运行态
- `LogicTask`
  - 模式状态机（待机 / 循迹 / 避障 / 跟随 / 航向保持）
  - 根据传感器与视觉状态生成目标速度
- `StartUITask`
  - OLED 菜单显示
  - 参数编辑（PID、循迹速度等）
- `DefaultTask`
  - 参数延迟保存（避免频繁写 Flash）

## 模块分层思路

- `main.c`
  - 外设初始化、串口中断、K210 视觉数据包解析
- `freertos.c`
  - 任务创建、模式逻辑、状态机、UI 菜单
- `motor.c / pid.c`
  - 电机控制与 PID
- `settings.c`
  - 参数持久化（Flash 双页轮换 + CRC 校验）
- `HC_SR04.c / mpu6050.c / inv_mpu*.c / oled.c`
  - 外设驱动与传感器支持

## K210（v13 v2）方案说明（本 README 按此版本）

你当前仓库里保留了多个 K210 脚本版本。作为 `v13（v2）` 使用时，建议优先使用：

- `k210（v13）带抗光.py`（推荐）

另外保留了：

- `k210（v13）不带抗光.py`（用于对比）
- `k210（v14）.py`（实验版，不作为本 README 默认方案）

## v13（v2）K210 的特点（旧协议）

- 使用 `0xFF 0xFE` 旧帧协议，仅发送：
  - `x`：横向误差（归一化后放大）
  - `quality`：跟踪质量
- 采用多 ROI 融合（近处 ROI 权重更高）
- 带预测选 blob（降低弯道跳错 blob 概率）
- 带短时 HOLD（弯道瞬时丢线时过渡）
- `带抗光版` 增加 ROI 自适应阈值（对环境光变化更稳）

注意：当前 STM32 工程里的 `main.c` 视觉串口解析也按旧帧（`x + quality`）实现，因此与 `v13（v2）` 是匹配的。

## 功能模式说明（STM32 侧）

代码中存在多种模式，常用模式如下（以 `LogicTask` 的状态机为准）：

- `Mode 0`：待机 / 手动停止
- `Mode 1`：视觉循迹（K210 串口输入）
- `Mode 2`：超声避障
- `Mode 3`：超声跟随
- `Mode 4`：MPU6050 航向保持直行

模式切换时会统一清理 PID 状态与部分运行态，减少模式切换瞬间的冲击。

## 软件亮点

## 1. FreeRTOS 分层清晰，调试友好

- 逻辑控制与电机闭环分离
- 视觉任务只做“数据预处理”，不直接控车
- 通过队列传递“最新值”，降低任务间耦合

## 2. 参数可调且可保存

- OLED 菜单可在线调 PID 和循迹速度参数
- 参数通过 `settings.c` 保存到 Flash
- 使用 CRC 校验 + 双页轮换，提升保存可靠性

## 3. 循迹模式做了稳定性保护

STM32 侧在 `Mode 1` 中包含多种稳定性设计：

- 视觉状态机（`TRACK / SEARCH / LOST_STOP`）
- 按质量值判断是否跟踪有效
- 丢线后按上次方向进行搜索，减少左右来回抖动
- 转向量限幅与斜率限制（slew），降低突转
- 弯道时自动降速，优先稳而不是快

## 4. K210 v13（v2）已做实用化处理

- 多 ROI + 预测选点
- 边缘质量保护（线贴边时不轻易判死）
- 丢线短时 HOLD（应对弯道瞬时出画）
- 抗光版本可在光照变化下提升可用性

## 构建与烧录

## 构建环境

- CMake
- Ninja
- GNU Arm Embedded Toolchain（`arm-none-eabi-gcc`）

## 构建命令

```sh
cmake --preset Debug
cmake --build --preset Debug
```

发布版：

```sh
cmake --preset Release
cmake --build --preset Release
```

构建输出目录：

- `build/Debug`
- `build/Release`

## 烧录说明（STM32）

本仓库不绑定具体烧录工具，可使用以下任一方式：

- ST-Link
- STM32CubeProgrammer
- OpenOCD（按你自己的环境配置）

将生成的 `ELF/HEX` 烧录到板子即可。

## K210 使用说明（v13 v2）

## 推荐脚本

- 默认推荐：`k210（v13）带抗光.py`
- 若现场光照稳定、想做对比测试：`k210（v13）不带抗光.py`

## 通信要求（与当前 STM32 工程匹配）

- 波特率：`115200`
- 协议：旧帧 `0xFF 0xFE + x + quality + checksum`

如果后续改用 `v14`（扩展帧），需要同时确认 STM32 端视觉协议解析也切换到扩展帧版本。

## 项目结构（简要）

```text
Core/
  Inc/                # 应用头文件、驱动头、FreeRTOS 配置
  Src/                # 主逻辑、任务、驱动实现
Drivers/              # STM32 HAL/CMSIS（供应商代码）
Middlewares/          # FreeRTOS 等中间件
cmake/                # 工具链与 CubeMX CMake glue
freertos_car.ioc      # CubeMX 工程配置
STM32F103XX_FLASH.ld  # 链接脚本
startup_stm32f103xb.s # 启动文件
k210（v13）带抗光.py    # K210 视觉脚本（推荐）
```

## 不足与反思（重点：K210 部分）

这一部分主要总结在 K210 黑线循迹调试中遇到的问题和经验。

## 1. 光照变化对阈值影响很大

问题表现：

- 同一套阈值在不同时间段、不同场地表现差异明显
- 阴影、反光、地面材质变化会导致误检或掉线

原因：

- 黑线识别本质上依赖阈值分割，环境光一变，线和背景的对比度就变
- K210 端如果只用固定阈值，鲁棒性有限

应对（v13 v2 的改进）：

- 增加“带抗光版”脚本（ROI 自适应阈值）
- 但这仍然是经验型参数，不是一次调好就通吃所有场景

反思：

- 视觉算法再复杂，如果输入图像质量不稳定，效果也会受限
- 以后应该优先把“光照控制/安装角度/曝光参数”调到更稳定，再调算法

## 2. 弯道容易掉线，原因不止一个

问题表现：

- 急弯处突然找不到线
- 或能过弯，但轨迹不稳、修正滞后

常见原因（实测中容易同时出现）：

- ROI 中选错 blob（阴影/黑块干扰）
- 线在弯道时快速贴边甚至部分出画
- 预瞄项过强或过弱
- 滤波太重导致转向来不及，滤波太轻又容易抖

v13（v2）层面的思路：

- 多 ROI 融合（近处主导）
- 预测选 blob
- 丢线短时 HOLD 过渡

反思：

- “能过弯”和“弯道稳定”是两个不同目标，参数经常互相冲突
- 调参时应固定车速、场地、相机角度，一次只改一个参数

## 3. 旧协议（只传 x + quality）信息量有限

问题：

- STM32 只能拿到横向偏差 `x` 和质量 `quality`
- 没有明确的“线方向/曲率”信息，主控端很难做更精细的弯道控制

影响：

- 过弯时更多依赖经验增益与状态机策略
- 对复杂弯道的适应能力有限

反思：

- 这也是后来考虑 `v14` 扩展帧（near/mid/far）的原因
- 但在工程实践里，“协议升级”必须和 STM32 端一起改，不能只改 K210 一边

## 4. K210 调试成本高于预期

体会：

- 视觉效果受很多因素共同影响：阈值、曝光、安装高度、视角、赛道材质、车速
- 很多问题看起来像“算法不行”，其实是系统联调问题

反思：

- 需要把版本管理做得更规范（脚本命名、参数记录、测试场景记录）
- README 和版本说明提前写清楚，可以减少后续回溯版本时的混乱

## 后续改进方向（建议）

- 统一 K210 脚本命名与版本记录（保留“稳定版/实验版”）
- 给 K210 参数做版本注释（场地、光照、车速）
- 为视觉协议增加版本号或帧类型说明（便于升级）
- 增加接线说明/实物图（上传 GitHub 时可补充）
- 如继续优化过弯稳定性，可考虑：
  - 扩展帧（near/mid/far）+ STM32 端联合改造
  - 更稳的 ROI 置信度策略
  - 场景化参数（直道/弯道）切换

## 说明

本 README 为当前仓库代码的阶段性说明，默认口径为 `v13（v2）` K210 方案。  
如果后续切换到 `v14`，建议同步更新以下内容：

- K210 脚本版本说明
- 串口协议说明（旧帧 / 扩展帧）
- 循迹控制逻辑说明（STM32 侧）

STM32-FreeRTOS-K210-SmartCar

STM32-FreeRTOS-K210-SmartCar Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

STM32-FreeRTOS-K210-SmartCar

STM32-FreeRTOS-K210-SmartCar Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README