06｜五路循迹模块：采样、偏差滤波与 PD 转向

循迹模块不是“哪个探头黑就向哪打方向”这么简单。当前工程把五路数字输入转换为连续位置偏差，经过低通和微分处理形成转向修正，再叠加到左右轮基础速度上。

1. 底层采样如何定义黑白

Tracker_DecodeInput() 按当前硬件口径把低电平解释为检测到黑线，高电平解释为白色。Tracker_ReadInputs() 每次先把全部 12 个逻辑位置清为白色，再只读取第 4～8 路。

这样做有明确目的：工程接口曾覆盖更多位置，但当前硬件只使用中间五路。未采样位置保持白色，避免被其他功能复用的引脚或悬空逻辑参与图案判断。

ℹ️ Note

“低电平是黑线”由当前源码注释标记为实测结论。更换传感器板或比较器极性后，必须重新验证，不能沿用为通用规律。

Tracker_ReadRange() 给有效区间建立以中心为零的对称位置坐标，对所有检测到黑线的通道求平均：

偏差 = 所有有效黑线位置之和 / 黑线通道数量

若没有任何通道检测到黑线，函数返回失败，并保留上一次偏差，不制造一个虚假的零值。这里“无信号”和“正好居中”是两种不同状态，应用层应通过有效性语义区分。

五路输入可形成类似以下结果：

具体左右符号还要结合传感器排列和 TRACK_STEERING_SIGN，应以小幅上板测试确认。

数字探头在黑白边缘容易快速跳变，直接对离散偏差求微分会放大抖动。TrackMode_UpdateSteering() 先做一阶低通：

滤波偏差 += α ×（原始偏差 - 滤波偏差）

再用相邻两次滤波值计算变化率，并对微分结果限幅。当前 TRACK_OFFSET_FILTER_ALPHA 为 0.55，微分上限也在配置中明确给出。

当只有中心传感器命中时，代码直接把原始偏差、滤波偏差和微分清零，避免中心附近残留的历史滤波值继续施加转向。

转向量来自比例项和微分项：

转向修正 = 方向符号 ×（Kp × 滤波偏差 + Kd × 偏差变化率）× 总增益

比例项根据当前偏差纠偏，微分项根据偏差变化趋势抑制过快摆动。最后的转向量被限制在当前阶段允许范围内，避免算法要求超过基础速度的差速，导致某一轮意外反转。

差速小车通过左右轮速度差转向：

左目标 RPM = 左基础 RPM - 转向修正
右目标 RPM = 右基础 RPM + 转向修正

结果再次限制在电机速度范围内，然后交给左右速度 PID。循迹算法只生成目标 RPM，不直接操作 TB6612，这使速度控制仍能补偿两轮负载差异。

TrackMode_RunDebug() 根据阶段生成基础速度：

转向修正建立在这些基础速度之上，所以同一套循迹偏差在不同阶段可能受到不同限幅。

Tracker 任务除了更新偏差，还检查指定范围内是否出现相邻黑线。进入等待终点阶段后，只有连续达到配置次数，状态机才接受终点图案。

30 秒配置在确认图案后还会进入“等待单路传感器”阶段；20 秒配置则进入后续停止延时。具体规则属于当前任务策略，不属于循迹 BSP。

将“读取黑白”与“终点意味着什么”分开后，底层传感器驱动可以被其他路线或任务复用。

底层在本次无黑线时保留上一偏差，避免偏差突然归零。但当前代码没有独立的“连续丢线时长”状态和专门的搜索策略。

这意味着文章不能声称系统已经具备完整丢线恢复。若要扩展，建议新增：

TrackMode_PrintSerial() 当前输出原始偏差、滤波偏差、微分、转向量、左右目标 RPM、左右滤波实际 RPM 和左右 PWM。建议按同一时间轴绘制这些量，观察问题发生在哪一层。