stm32-gray-track

name	stm32-gray-track
description	8 路灰度传感器巡线算法调试技能。Use when: 小车脱线/找不到线、十字路口误判、弯道拐不过、S 形摆动、传感器读数异常、防抖逻辑调整、加权差比和参数优化、丢线搜索行为异常。适用于亚博智能 8 路灰度 + STM32 巡线场景。
argument-hint	描述巡线问题或需要调整的行为

8 路灰度巡线算法调试

传感器硬件

• 型号：亚博智能 8 路灰度传感器
• 接口：AD0/AD1/AD2（PB13/PB14/PB15）通道选择 + OUT（PA15）数字输出
• 读取方式：Grayscale_Sensor_Read_All(g_sensor_data) → g_sensor_data[0..7] 存入 D1~D8
• 值含义：0 = 白色（未踩线），1 = 黑色（踩线）

四层算法架构

Grayscale_Sensor_Read_All()  ← 硬件层：逐路切换 AD0~AD2 读 OUT 引脚
        ↓
   g_sensor_data[8]         ← D1~D8 原始值
        ↓
   track() 入口              ← 1. 防抖过滤
        ↓                    ← 2. 加权差比和 → error (raw)
        ↓                    ← 3. 丢线/十字状态机 (GO/FIND/CROSS/R1~R3/L1~L3)
        ↓                    ← 4. 转向 PD → steer_out → 差速分配
   motor_target_set(L,R)    ← 输出左右轮目标速度

调试步骤

1. 先验证传感器数据

在 OLED 第 1 行查看 D1~D8 实时值。用手遮/照传感器验证每路响应：

OLED 第 1 行: 0 0 1 0 0 0 0 0
             D1 D2 D3 D4 D5 D6 D7 D8

• 如果某路始终 0 或始终 1 → 该路传感器故障或 AD0~AD2 通道选择断线
• 可用 sensor_test()（在 gray_track.c 中）通过串口打印原始值
• OLED 第 2 行显示巡线状态字（GO/R1R3/L1L3/FIND/CROSS）

2. 加权差比和原理

8 路传感器按位置加权，中间权重大、边缘权重小：

传感器	权重	归属
D1	×5	左侧 sum_L
D2	×4	左侧 sum_L
D3	×3	左侧 sum_L
D4	×1	左侧 sum_L
D5	×1	右侧 sum_R
D6	×3	右侧 sum_R
D7	×4	右侧 sum_R
D8	×5	右侧 sum_R

• error = sum_L - sum_R（正值=线偏左，负值=线偏右）
• 最大范围 ±12，不除以 cnt（灯越多 → error 越大 → 弯越急转向越猛）

3. 防抖机制

• 单帧毛刺：传感器状态需要保持 1 帧才更新 error → 80ms 延迟
• 快速响应：≥2 个灯同时翻转 → 立即响应（不等待确认帧）
• ⚠️ 这导致传感器噪声最多引起 80ms 的响应延迟，不会引起误判

4. 状态机诊断

OLED 状态	含义	正常/异常
GO	正常跟线	✅ 正常
R1~R3	右偏修正	✅ 正常（线偏右时出现）
L1~L3	左偏修正	✅ 正常（线偏左时出现）
FIND	全白丢线，惯性搜索	⚠️ 如果持续出现 → 传感器安装高度不对或阈值偏差
CROSS	全黑，十字路口	✅ 碰到赛道十字时出现

5. 常见问题排查

现象	原因	解决
直线也左右摆（S 形）	KD 太小或 KP 太大	KD 6 加大阻尼
弯道冲出赛道	KP 太小或速度太快	先降 S，再加 KP
脱线后找不回线	丢线速度太慢	提高 TRACK_SPEED_SLOW
十字路口误停车	CROSS 处理逻辑触发	十字用惯性保持，不会停车。若停车说明传感器数据异常
一直显示 FIND	传感器装太高/太低	调整安装高度使白底输出 0、黑线输出 1
内侧轮停转过猛	steer_out 限幅 ±60 不够	调整 STEER_MAX 宏
OLED 花屏	MPU6050 INT 打断 I2C	确认 OLED 刷新前关闭了 EXTI0

6. 调参速查

参数	位置	默认	作用
g_track_kp	gray_track.c	3.0~5.8	转向比例：越大转弯越猛
g_track_kd	gray_track.c	3.0~4.0	转向微分：越大越稳
TRACK_SPEED_FAST	gray_track.c	30	直道基准速度
TRACK_SPEED_SLOW	gray_track.c	18	丢线搜索速度
TRACK_SPEED_MIN	gray_track.c	2	弯道保底速度
STEER_MAX	gray_track.c	60	转向输出限幅
UART3 KP<值>	实时调参	3.0	在线改转向 P
UART3 KD<值>	实时调参	4.0	在线改转向 D

正确调参顺序

1. 先确认传感器数据正常（OLED 第 1 行 D1~D8）
2. 设定合理速度 S25（不要一开始就很快）
3. 调转向 PD：KP3 → 观察过弯 → 不够加 KP4 → 摆动加 KD5
4. 速度跟不上再调速度环 PID（用 stm32-pid-tuning 技能）
5. 最后微调直道速度 S30

相关文件

• 巡线算法：code/gray_track.c, code/gray_track.h
• 传感器驱动：code/grayscale_sensor.c, code/grayscale_sensor.h
• PID 控制：code/pid.c, code/pid.h
• 巡线详解文档：移植代码相关/循线控制逻辑详解.md
• 项目架构：AGENTS.md