fix(protocol): Fail invalid routes and simplify GPIO payloads

[qzhhhi]

• Propagate deserializer callback failures for CAN, UART, and GPIO so unexpected DataId values, channel indexes, and unsupported GPIO configurations abort the current transfer instead of being logged and ignored.
• Collapse GPIO write and read-result packets into shared value payloads and rename GPIO config payload enums to reflect protocol semantics. Keep timestamped digital samples for uplink reads, but reject timestamped digital writes on host and firmware downlink paths.

变更概述

本次PR修复了librmcs库中的协议处理方式，并简化了GPIO有效负载结构。主要涉及两个方面的改进：

1. 反序列化器中的错误传播

核心库更新（deserializer.cpp 和 deserializer.hpp）

• CAN和UART字段处理：修改了 process_can_field 和 process_uart_field 方法，使其不再无条件返回 true，而是将回调的返回值（can_deserialized_callback / uart_deserialized_callback）直接作为结果返回，从而使无效的DataId值或错误的处理能够正确地终止当前传输。

• GPIO字段处理：调整了 process_gpio_field 的分支逻辑：

  • 数字和模拟数据分支：新增回调返回值检查，回调失败时返回 false
  • 读配置分支：对模拟读配置添加了约束检查（若包含 capture_timestamp 标志则视为失败），两类读配置的回调均以返回值决定成败

• 方法签名更新：将六个关键回调从 virtual void 改为 [[nodiscard]] virtual bool：

  • can_deserialized_callback
  • uart_deserialized_callback
  • gpio_digital_data_deserialized_callback
  • gpio_analog_data_deserialized_callback
  • gpio_digital_read_config_deserialized_callback
  • gpio_analog_read_config_deserialized_callback

固件端实现更新

C板固件 (firmware/c_board/app/src/usb/vendor.hpp)：

• CAN和UART回调：在未建立会话时返回 true，匹配失败时返回 false（替代原有的assert断言）
• GPIO数字/模拟写回调：新增对通道越界和能力支持的检查，返回失败状态而非无返回值
• GPIO数字写回调：新增对时间戳的检查，若 timestamp_quarter_us 存在则返回 false
• GPIO读配置回调：改为明确返回 bool 值

RMCS板固件 (firmware/rmcs_board/app/src/usb/vendor.hpp)：

• 类似的回调改造，使错误条件能够被正确传播而非忽略

主机端处理 (host/src/protocol/handler.cpp)：

• 反序列化回调：当会话未建立时返回 true，当上层拒绝处理时记录错误并返回 false
• GPIO数字/模拟数据结果回调：新增布尔返回值以反映是否接受该字段
• GPIO读配置回调：改为在记录异常后返回 false

2. GPIO有效负载结构简化

协议定义修改 (protocol.hpp)

• PayloadEnum重组：将原有的 kDigitalWriteLow、kDigitalWriteHigh、kDigitalRead、kAnalogRead、kDigitalReadResultLow 等枚举项重新组织为：
  • kDigitalLow 和 kDigitalHigh（用于数字读写值）
  • kAnalog（用于模拟数据）
  • kDigitalReadConfig 和 kAnalogReadConfig（用于读配置）
• 移除了原有的读结果专用枚举值

序列化器更新 (serializer.hpp)

• 方法重命名：
  • write_gpio_digital_data → write_gpio_digital_value（支持可选的 timestamp_quarter_us 字段）
  • write_gpio_analog_data → write_gpio_analog_value
• 读配置序列化调整：
  • write_gpio_digital_read_config 现在设置 kDigitalReadConfig 有效负载类型
  • write_gpio_analog_read_config 现在设置 kAnalogReadConfig 有效负载类型
• 移除的方法：删除了 write_gpio_digital_read_result 和 write_gpio_analog_read_result
• Size计算更新：required_gpio_size 的switch表已适配新的有效负载枚举值

固件端序列化调用更新

C板 (firmware/c_board/app/src/gpio/gpio.hpp)：

• publish_digital_input_sample 改用 write_gpio_digital_value 替代 write_gpio_digital_read_result

RMCS板 (firmware/rmcs_board/app/src/gpio/gpio.hpp)：

• 同样更新了数字输入采样的序列化调用

主机端 (host/src/protocol/handler.cpp)：

• PacketBuilder实现中更新了GPIO数据写入的调用路径
• write_gpio_digital_data 新增对时间戳的检查（若存在则拒绝）

总体影响

这些改动提高了协议实现的健壮性，确保无效或意外的数据能够导致传输失败而非被无声忽略，使调试更加便利，并防止畸形消息导致的潜在问题。GPIO有效负载的整合减少了冗余，使协议结构更加清晰。

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 91e1e878-f2c7-4311-80b7-44c5fff14baf

📥 Commits

Reviewing files that changed from the base of the PR and between f707518 and d24d5bc.

📒 Files selected for processing (9)

• core/src/protocol/deserializer.cpp
• core/src/protocol/deserializer.hpp
• core/src/protocol/protocol.hpp
• core/src/protocol/serializer.hpp
• firmware/c_board/app/src/gpio/gpio.hpp
• firmware/c_board/app/src/usb/vendor.hpp
• firmware/rmcs_board/app/src/gpio/gpio.hpp
• firmware/rmcs_board/app/src/usb/vendor.hpp
• host/src/protocol/handler.cpp

---

Walkthrough

重命名 GpioHeader::PayloadEnum 枚举项（移除 write/result 语义，统一为 kDigitalLow/kDigitalHigh/kDigitalReadConfig/kAnalogReadConfig/kAnalog），将 DeserializeCallback 的多个回调从 virtual void 改为 [[nodiscard]] virtual bool，序列化器方法相应重命名并新增可选时间戳支持，删除读结果序列化方法，并在反序列化器、固件及 host 中全面传播这些变更。

Changes

GPIO 协议枚举重命名与回调布尔返回值重构

Layer / File(s)	Summary
协议枚举与回调接口契约 core/src/protocol/protocol.hpp, core/src/protocol/deserializer.hpp	GpioHeader::PayloadEnum 枚举项被替换为 kDigitalLow/kDigitalHigh/kDigitalReadConfig/kAnalogReadConfig；DeserializeCallback 中 CAN、UART 及 GPIO 相关回调从 virtual void 改为 [[nodiscard]] virtual bool。
序列化器方法重命名与 payload 枚举更新 core/src/protocol/serializer.hpp	write_gpio_digital_data/write_gpio_analog_data 重命名为 write_gpio_digital_value/write_gpio_analog_value，新增可选时间戳序列化，更新读配置 payload 枚举，删除 write_gpio_digital_read_result/write_gpio_analog_read_result，同步更新 required_gpio_size 映射表。
反序列化器分支逻辑与回调返回值传播 core/src/protocol/deserializer.cpp	process_can_field/process_uart_field 改为直接返回回调布尔结果；process_gpio_field 各分支均改为根据回调返回值决定是否 co_return false，模拟读配置新增 capture_timestamp/边沿标志约束。
固件 GPIO 发布接口切换 firmware/c_board/app/src/gpio/gpio.hpp, firmware/rmcs_board/app/src/gpio/gpio.hpp	两块板的 publish_digital_input_sample 将 write_gpio_digital_read_result 调用替换为 write_gpio_digital_value。
固件 Vendor 回调实现 firmware/c_board/app/src/usb/vendor.hpp, firmware/rmcs_board/app/src/usb/vendor.hpp	所有覆写回调从 void 改为 bool；CAN/UART 未建立会话返回 true，未知 DataId 返回 false；GPIO 数字写新增 timestamp 门控；模拟读配置统一返回 false。
Host Handler 回调与序列化器调用更新 host/src/protocol/handler.cpp	反序列化回调改为 bool，上层回调拒绝时记录错误并返回 false；write_gpio_digital_data 新增 timestamp 存在性检查，write_gpio_analog_data 调用切换为 write_gpio_analog_value。

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Alliance-Algorithm/librmcs#34: 本 PR 在同一套 GPIO write 反序列化回调路径上引入 bool 返回并门控丢弃逻辑，与 #34 新增的 GPIO 写反序列化管道直接相关。
• Alliance-Algorithm/librmcs#35: 本 PR 对 GPIO read-config 反序列化回调引入 bool 返回与配置约束，与 #35 新增并重构 GPIO read-config 反序列化回调的代码路径直接重叠。
• Alliance-Algorithm/librmcs#58: 两者均围绕"反序列化回调从 void 改为 bool 并用返回值驱动上层处理/丢弃"的契约展开，改动了同一套回调接口与路由逻辑。

Poem

🐇 枚举改了名，回调返真假，
Write 和 Result 已悄悄隐退，
Digital、Analog 各就各位，
Timestamp 可选，边沿有检查，
小兔竖耳听——协议更整洁啦！🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	标题准确概括了PR的核心变更：修复协议中无效路由的错误处理，并简化GPIO负载结构。
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/fail-route

---

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.}