Dev/imuheat

[qzhhhi]

PR 摘要：IMU 温度传感器与时间戳支持（dev/imuheat → main）

概述

本 PR 引入对 BMI088 温度传感器的固件实现，并在数据层、协议层与固件驱动中广泛添加或扩展四分之一微秒（quarter-µs）级时间戳支持，用于加速度计、陀螺仪和可选的 GPIO 数字读取。为此还重构/新增了高精度定时器实现及若干驱动之间的“待处理读（pending read）”协调机制。协议格式与序列化/反序列化逻辑也相应扩展，因此需要固件与主机端配套更新。

主要变更点

core（协议与数据结构）

• 数据视图扩展：
  • 为 AccelerometerDataView、GyroscopeDataView、TemperatureDataView 添加 timestamp_quarter_us 字段（携带采样时间）。
  • 为 GpioDigitalDataView 添加可选时间戳（std::optional<uint32_t>）。
  • 在 GpioReadConfigView 中增加 capture_timestamp 布尔标志以控制是否采集时间戳。
• 枚举与能力：
  • 在 GpioCapability 中添加 kTimestampedDigitalRead 标志，并将其纳入 kDigitalCapabilities。
• 回调接口：
  • 在 DataCallback / 反序列化回调链中增加 temperature_receive_callback / temperature_deserialized_callback，用于温度数据的传递（目前多处为占位/空实现）。
• 协议结构（core/src/protocol）：
  • 扩展 GpioHeader 与 GpioReadConfigPayload、添加 GpioDigitalReadTimestampPayload。
  • 增加 IMU payload 类型 kTemperature，扩展 ImuAccelerometer/ImuGyroscope/ImuTemperature payload 位字段以包含 TimestampQuarterUs。
  • 序列化器/反序列化器：支持 timestamped 数字读取、对 DigitalReadResult 增加可选时间戳解析/序列化；IMU 路径增加温度 payload 与时间戳处理并校验不支持的组合（如模拟读取的时间戳被拒绝）。

固件（rmcs_board 与 c_board）

• 高精度定时器：
  • 新增 Timer 类（timer.hpp/.cpp），提供 quarter-µs 的 32/64 位时间戳接口，替换旧 tick 实现，新增 ISR 转发实现。
  • 修改板级计时器配置（board.c）并移除旧的 tick_clock 初始化与 ISR 声明（lite/pro 板卡）。
• BMI088 驱动扩展（accel / gyro / temperature）：
  • 为加速度计与陀螺仪添加 data_ready_callback(uint32_t capture_timestamp_quarter_us) 与 service_pending_read()，使用原子与中断锁管理 pending/active 时间戳并将时间戳随数据上报。
  • 新增完整的 Temperature 类（temperature.hpp）及其定时器 ISR 实现（temperature.cpp），实现周期采样、SPI 读取、时间戳附带以及心跳上报逻辑；在 spi/bmi088 增加 service_pending_reads 接口用于协调多个传感器的 pending 读取。
  • 在固件 IRQ 处理路径（spi 中断、GPIO 中断）处采集并传递 capture_timestamp_quarter_us。
• GPIO 驱动：
  • 引入 ChannelState.capture_timestamp 标志、current_timestamp_quarter_us() 帮助函数，并将 publish_digital_input_sample 改为接受可选时间戳（签名变化），在 ASAP、周期采样与端口中断路径中选择性发布时间戳。
• 应用层：
  • 在 App::run 等主循环处调用 spi::bmi088::service_pending_reads() 以处理 pending 读取。

主机端（host）

• Agent / Handler：
  • 在各 Agent（c_board、rmcs_board_lite、rmcs_board_pro）添加 temperature_receive_callback 占位实现以接收温度数据。
  • 在 protocol Handler 中添加 temperature_deserialized_callback 的转发实现。
• API 变化：
  • 从 PacketBuilder 中移除 write_imu_accelerometer 与 write_imu_gyroscope（已从该接口删除 IMU 写入方法；注意这影响主机发送路径）。

向后兼容性与注意事项

• 破坏性/协议兼容性：本 PR 修改了底层协议的字段布局（GPIO 与 IMU payload、header 位域等）以及序列化格式，固件与主机端必须配套更新，否则会导致协议解析/互操作失败。
• 行为变更：GPIO 数字读取现在可选携带时间戳（需要 capture_timestamp 配置），IMU 路径新增温度 payload 与时间戳字段，部分之前同步/即时的驱动改为中断捕获→pending→service 的两阶段交付流程。

影响范围（文件/组件）

• core：数据视图、协议头、序列化/反序列化器（多处修改）
• firmware：rmcs_board 与 c_board 的 timer、GPIO、BMI088 accel/gyro/temperature、service 协调、板级时钟修改
• host：Agent 回调与 Handler，PacketBuilder 接口移除部分 IMU 写入方法

代码量（估计）

• 新增与扩展文件显著（包括 temperature 驱动、timer 实现与多处驱动扩展）；原摘要估计增加约数百行，删除旧 tick 相关代码若干十行。

建议的审阅重点

• 协议兼容性检查：protocol.hpp / serializer / deserializer 修改是否严格对应新旧边界与校验逻辑（注意 analog read 对 timestamp 的拒绝路径）。
• 并发与同步：BMI088 accel/gyro 的 pending/active timestamp 原子与 interrupt_lock 使用是否正确且无竞态。
• 定时器与 ISR：新 Timer 的初始化、ISR 声明与板级时钟分频（mchtmr0 从 24MHz→4MHz）是否在各板卡配置中一致。
• API/接口影响：主机端 PacketBuilder 接口移除是否会影响上层调用者，Agent 的 temperature 回调目前为占位，需确认上层如何使用温度数据。

[coderabbitai]

Caution

Review failed

Failed to post review comments

Walkthrough

为数据通路引入可选/每样本时间戳：扩展数据视图与协议载荷、序列化/反序列化、固件 GPIO 与 BMI088 驱动以抓取并传播时间戳；新增 BMI088 温度驱动与高精度定时器并调整板级时钟与 ISR 架构。

Changes

时间戳支持扩展

Layer / File(s)	Summary
数据结构 core/include/librmcs/data/datas.hpp	为 GpioDigitalDataView 添加 std::optional<uint32_t> timestamp_quarter_us；为 AccelerometerDataView、GyroscopeDataView、TemperatureDataView 添加 timestamp_quarter_us；在 GpioReadConfigView 添加 capture_timestamp；在 DataCallback 添加 temperature_receive_callback。
能力位与常量 core/include/librmcs/spec/gpio.hpp	新增 GpioCapability::kTimestampedDigitalRead，并把它加入 kDigitalCapabilities。
协议版式 core/src/protocol/protocol.hpp	GpioHeader 增加 Timestamped 位；GpioReadConfigPayload 扩展字段；新增 GpioDigitalReadTimestampPayload；IMU payload 增加 TimestampQuarterUs 并添加 kTemperature 枚举。
序列化 core/src/protocol/serializer.hpp	GPIO/IMU 写入路径加入时间戳字段与校验；数字读结果支持可选时间戳载荷；IMU 写入含时间戳与新增 temperature payload 处理。
反序列化 core/src/protocol/deserializer.cpp, core/src/protocol/deserializer.hpp	GPIO 字段引入 timestamped 模式判定并解析数字读时间戳；拒绝不支持的组合（如模拟读带时间戳）；IMU 反序列化新增温度分支并提取时间戳；在回调接口添加 temperature_deserialized_callback。
固件 GPIO 驱动 firmware/*/gpio/gpio.hpp, firmware/*/gpio/gpio.cpp	引入 std::optional 时间戳路径；ChannelState 加 capture_timestamp；publish_digital_input_sample 改为接收高电平与可选时间戳；在 ASAP、周期采样与端口中断路径捕获并传递时间戳。
主机回调占位 host/include/*, host/src/protocol/handler.cpp, firmware/*/usb/vendor.hpp	在主机与固件的接收/反序列化回调中加入温度数据的占位处理（no-op 实现）。

BMI088 驱动与待处理服务

Layer / File(s)	Summary
驱动接口与状态 firmware/*/spi/bmi088/accel.hpp, firmware/*/spi/bmi088/gyro.hpp	为加速度计/陀螺仪添加 data_ready_callback(uint32_t) 与 service_pending_read() 公共方法；引入原子与中断保护，维护 pending/active 时间戳状态并在读取时提升到 active。
驱动上行与时间戳传播 firmware/*/spi/bmi088/accel.hpp, firmware/*/spi/bmi088/gyro.hpp, firmware/*/spi/bmi088/accel.cpp, firmware/*/spi/bmi088/gyro.cpp	在 SPI 异步回调中检索 active 时间戳并将其传入 handle_uplink，由序列化器输出带时间戳的 IMU payload。
服务编排 firmware/*/spi/bmi088/service.hpp	新增 service_pending_reads()，按优先级依次委派 gyroscope、accelerometer、temperature 的待处理读取服务。
温度传感器驱动 firmware/rmcs_board/app/src/spi/bmi088/temperature.hpp, .../temperature.cpp	新增 Temperature 类：定时器触发探测、SPI 读取、时间戳锚定与中点计算、心跳上报逻辑并通过序列化器上报温度带时间戳。包含专用 timer ISR。
应用与 IRQ 集成 firmware/*/app/src/app.cpp, firmware/rmcs_board/app/src/spi/spi.cpp, firmware/*/spi/*/*.cpp	在主循环/IRQ 路径调用 service_pending_reads()；在 accel/gyro IRQ 处理处抓取时间戳并调用 data_ready_callback(timestamp)。

定时器与板级调整

Layer / File(s)	Summary
新定时器实现 firmware/rmcs_board/app/src/timer/timer.hpp, .../timer.cpp	新增 Timer 类及全局实例，提供 MCHTMR 初始化、IRQ 处理与四分之一微秒（32/64 位）时间戳助手。
板级时钟/ISR 清理 firmware/rmcs_board/boards/*/*	移除旧的 tick ISR 与 init_tick_clock，替换为基于新 timer 的架构；在板级 board.c 中将 mchtmr0 分频从 1 改为 6（24MHz→4MHz）。

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant IRQ as BMI088 IRQ
    participant Timer as Timer (MCHTMR)
    participant Driver as BMI088 Driver (accel/gyro/temp)
    participant SPI as SPI Controller
    participant Serializer as USB Serializer
    participant Host as Host Deserialize/Handler

    IRQ->>Timer: read timestamp_quarter_us()
    Timer-->>IRQ: timestamp
    IRQ->>Driver: data_ready_callback(timestamp)
    Driver->>Driver: store pending timestamp (atomic, guarded)
    Driver->>Driver: service_pending_read()? (serviced by service_pending_reads)
    Driver->>SPI: read_async(...)
    SPI-->>Driver: transmit_receive_async_callback(size)
    Driver->>Serializer: handle_uplink(data, active_timestamp)
    Serializer->>Host: serialized packet (IMU/Temperature with timestamp)
    Host->>Host: deserializer parses timestamped payload
    Host->>Host: temperature_deserialized_callback / imu callbacks invoked

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Alliance-Algorithm/librmcs#21：修改并扩展了 BMI088 SPI/驱动与异步回调，和本 PR 在同一子系统有重叠。
• Alliance-Algorithm/librmcs#9：早期引入了 BMI088 驱动与 ISR，本 PR 在其上添加时间戳与待处理读取机制。
• Alliance-Algorithm/librmcs#34：关联的 GPIO/协议改动基础上扩展了时间戳支持和数字读取路径。

Poem

🐰
我在四分之一微秒里跳跃，
抓住每个引脚与温度的节拍，
BMI088 与时钟共舞，数据轻快传来，
兔足撒下时间戳，代码悄然开怀。

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 1.05% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	PR标题'Dev/imuheat'过于简洁模糊，未能清晰表达PR的主要变更内容，使用了分支名称而非描述性标题。	建议将标题改为更具描述性的内容，如'Add IMU temperature sensor support with timestamping'，以清楚表达该PR添加了IMU温度传感器和时间戳功能的核心变更。

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev/imuheat

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[qzhhhi]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[qzhhhi]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.