第1章：Fast-Follow 模块概览与核心概念
本章目标
- 理解 Fast-Follow 模块在系统中的定位与职责
- 掌握模块的核心术语：跟踪器、状态机、校准窗口、触发阈值
- 识别典型应用场景，建立快速配置的上下文意识
- 能够通过命令行查看模块状态与基本信息
核心原理
Fast-Follow 模块本质是一个硬件加速的状态跟踪引擎，负责在微秒级时间窗口内：
- 采样：从多个传感器/数据流中获取最新帧信息
- 匹配：与预设的模板参数进行特征对齐
- 决策：通过有限状态机（FSM）判断是否需要触发后续动作
模块内部通过三级流水线实现低延迟：捕获级 → 校准级 → 输出级。每个阶段都可独立配置超时、重试次数和优先级，这是后续章节深入调优的基础。
💡 关键术语
跟踪器（Tracker）：管理单一数据流的采样状态；
状态机（FSM）：控制跟踪器生命周期（空闲/同步/活跃/错误）；
校准窗口（Calibration Window）：允许的最大时间偏差，默认 200μs；
触发阈值（Trigger Threshold）：连续匹配次数达标后触发下游任务。
跟踪器（Tracker）：管理单一数据流的采样状态；
状态机（FSM）：控制跟踪器生命周期（空闲/同步/活跃/错误）；
校准窗口（Calibration Window）：允许的最大时间偏差，默认 200μs；
触发阈值（Trigger Threshold）：连续匹配次数达标后触发下游任务。
配置步骤
首次使用 Fast-Follow 模块需完成基础初始化。以下为典型命令行操作（基于 XFF‑ctl 工具）：
# 检查模块是否存在
xff‑ctl --list-modules | grep fast‑follow
# 加载模块（需要 root 权限）
xff‑ctl --load fast‑follow
# 查看默认配置参数
xff‑ctl --module fast‑follow --show‑config
# 设置采样率（单位：Hz）
xff‑ctl --module fast‑follow --param sample_rate=1000000
# 启用跟踪器（tracker_id = 0）
xff‑ctl --module fast‑follow --enable‑tracker 0若使用 CMake 构建集成代码，需在项目配置中显式链接 Fast-Follow 库：
cmake_minimum_required(VERSION 3.16)
project(ff_app)
find_package(ff_module REQUIRED)
add_executable(ff_app main.cpp)
target_link_libraries(ff_app PRIVATE ff_module::fast_follow)常见错误与解决方法
| 错误现象 | 原因 | 解决措施 |
|---|---|---|
ERR_MODULE_NOT_FOUND |
模块未正确加载或内核驱动缺失 | 运行 xff‑ctl --load fast‑follow；检查 /dev/ff* 设备节点 |
ERR_TRACKER_TIMEOUT |
校准窗口设置过小，传感器数据延迟超标 | 增大 calibration_window_us 参数（建议从 500μs 开始） |
WARN_NO_MATCH |
触发阈值过高，信噪比不足 | 降低 trigger_threshold 或增加模板匹配容差 |
| 状态机卡在“同步”状态 | 多跟踪器间时间戳竞争 | 启用 --force‑resync 或调整跟踪器优先级 |
验收检查清单
- ✅ 模块已通过
xff‑ctl --list-modules列出 - ✅ 默认配置参数与官方基准一致（采样率 ≥ 500 kHz，校准窗口 ≥ 200 μs）
- ✅ 至少一个跟踪器可正常切换到“活跃”状态
- ✅ 无
ERR_MODULE_NOT_FOUND或ERR_TRACKER_TIMEOUT报错 - ✅ 理解 Fast-Follow 三级流水线及每个阶段的可配置项