Merge/deformable infantry

[Yukikaze2233]

涵盖v1 v2 3车通用
Deformable 专属 (14 文件) — 底盘/云台/硬件/UI 全套 deformable 控制器与配置
依赖组件 (10 文件）— ADRC、SMC 控制器，ring_buffer、hard_sync 等辅助
共享修改 — plugins.xml 注册、裁判系统协议修复、cross-build `--link-default 软链接等

变形步兵合并 PR 摘要

构建工具链改进

• .script/build-rmcs：添加预运行验证和恢复逻辑，通过 check_default_dir_restorable() 验证构建相关符号链接指向预期的跨平台构建目标，执行前通过 restore_default_dir() 重置 build/install/log 目录。

• .script/build-rmcs-cross：引入新的 --link-default 标志以支持跨平台构建后的符号链接创建，新增 check_default_linkable() 和 link_default_base() 两个辅助函数。

• .script/complete/_build-rmcs-cross：shell 补全脚本中添加 --link-default 选项。

ADRC 主动扰动拒绝控制系统

新增完整的 ADRC 控制器实现，包含三个核心组件：

• TD.hpp - 轨迹微分器：离散有限视距 fhan 动态观察器，支持加速度/速度限制和状态跟踪。

• ESO.hpp - 扩张状态观察器：含自动 beta 参数推导、状态/输出存储、配置验证和 z3 限制钳制。

• NLESF.hpp - 非线性误差曲面滤波器：包含 fal 函数、输出饱和控制、参数边界钳制和配置验证。

• adrc_controller.cpp：完整的 ROS2 ADRC 控制器实现，集成 TD、ESO、NLESF 三个子系统，支持动态限制处理和错误输入模式，作为插件导出供运行时加载。

• adrc_V2_说明.md：ADRC-V2 架构完整文档，含参数接口和变量速查表。

变形底盘控制系统

• deformable_chassis.cpp：变形底盘协调器（1012 行），包含姿态偏差校正、腿部接触感知、扭矩控制和悬挂参数管理。实现 IMU 基础姿态估计、自动 IMU 安装误差校准、多关节速度/加速度约束。

• deformable_joint_controller.cpp：ADRC 基础变形关节控制器（370 行），支持法线/悬挂配置切换、扭矩前馈和 ESO 状态输出。

• deformable_joint_layer.hpp：变形关节层接口和轨迹规划器，包含关节反馈源选择、腿部反馈结构、轨迹目标管理和边界/速度/加速度限制。

• deformable_chassis.cpp（轮子控制）：完整的变形底盘控制器（873 行），集成 QCP 求解器进行约束求解、多 PID 控制器、低通滤波加速度、几何和椭圆参数优化。

• deformable_omni_wheel_controller.cpp：变形全向轮控制器（275 行），使用 QCP 求解器和双自由度平移/旋转 PID 调节，支持基于高度的约束处理和菱形约束方案降级。

变形硬件集成

• deformable-infantry-v2.cpp：DeformableInfantryV2 硬件组件（904 行），包含 BottomBoard/TopBoard 嵌套类，集成 BMI088 IMU、DJI/LK/LK 缩放马达控制、关节/轮子机制、云台控制、硬同步快照处理和多 CAN 总线命令生成。

• deformable-infantry-omni.cpp：DeformableInfantryOmni 硬件组件（848 行），三层子板架构（BottomBoard、ImuBoard、TopBoard），支持 CAN/UART 传输、硬同步快照发布、参数化调试选项和坐标映射。

硬件驱动增强

• VT13.hpp：新增 VT13 遥控输入设备处理器，多输出接口（摇杆轴、开关、鼠标、键盘、旋转旋钮），帧解析 + CRC 校验，原子数据重构。

• dji_motor_with_encoder.hpp：DJI 马达编码器支持，可配置零点/减速比/反向/多圈角度，跨多个马达类型（GM6020、M3508、M2006）。

• lk_motor.hpp：新增 MG5010Ei36 马达类型，重构马达参数初始化和扭矩-电流映射。

• dr16.hpp：跨平台 PACKED_STRUCT 宏以保证结构体内存对齐。

• alpha_beta_angle_filter.hpp：新增角度滤波器，支持 wrap-around 处理、动态增益调整和失效重置。

• ring_buffer.hpp：无锁环形缓冲区（power-of-two 尺寸），支持原子索引和多元素操作。

云台与射击控制

• deformable_infantry_gimbal_controller.cpp：变形步兵云台控制器（217 行），组合 TwoAxisGimbalSolver 和多 PID 控制器，支持自动自瞄和手动模式，含开关安全检查。

• two_axis_gimbal_solver.hpp：扩展云台求解器，新增编码器螺距路径支持（use_encoder_pitch 参数）、容差近零检查替代严格零比较。

• bullet_feeder_controller_17mm.cpp：更新供弹控制器，支持旋转旋钮输入、右鼠标/右开关自瞄启动逻辑。

• chassis_power_controller.cpp：扩展功率控制器支持左/右遥控开关、键盘 ctrl 键加速模式、超级电容基压线处理、超额功率贡献调整为 0.0。

UI 和裁判系统

• deformable_infantry_ui.cpp：新增 DeformableInfantry UI 组件，包含十字准星、状态环、中心准线和底盘方向指示器，读取变形腿部角度配置，更新腿部弧线显示。

• crosshair_circle.hpp：十字准星圆形 UI 控件。

• deformable_chassis_top_view.hpp：变形底盘俯视图腿部弧线渲染器，支持角度范围设置和可见性控制。

• status.cpp：裁判系统扩展，新增 30+ 输出接口（友方各机器人 HP、自身 HP、位置、弹药许可、地图命令数据），新增处理方法 update_event_data、update_dart_info、update_map_command，支持新命令 ID（0x0101、0x0105、0x0303）。

• field.hpp：裁判协议数据结构重构，GameStatus 新增 game_progress 字段，GameRobotHp 改为友方各机器人独立字段，新增 EventData/DartInfo/MapCommand 结构，移除 GameRobotPosition，PowerHeatData 重新排布，BulletAllowance 扩展 17mm/42mm/堡垒 许可和金币追踪。

配置与插件注册

• deformable-infantry-omni.yaml 和 deformable-infantry-v2.yaml：完整的运行时配置文件，包含 rmcs_executor 组件映射、硬件配置、多 PID 控制器参数、ADRC 调优参数、关节悬挂设置、串口过滤器和零点校准。

• plugins.xml：新增 13 个硬件/控制器/广播组件注册（DeformableInfantryV2、DeformableInfantryOmni、DeformableOmniWheelController、DeformableChassis、DeformableJointController、DeformableChassisController、ChassisControllerV2、OmniInfantryPlannerGimbalController、DeformableInfantryGimbalController、AdrcController、TfBroadcaster、ValueBroadcaster 等）；扩展裁判系统和 UI 组件（Status、Command、Interaction、Ui、DeformableInfantry）；新增测试输出接口（AngleOutput）。

框架改进

• executor.hpp：改进循环依赖报告，通过 map lookup 避免非法指针解引用。

• VT13_switch.hpp：新增 VT13Switch 枚举（C、N、S、UNKNOWN）。

• hard_sync_snapshot.hpp：新增硬同步快照数据结构，包含有效标志、曝光时间戳、四元数分量。

总体贡献

该 PR 为 RMCS 引入了完整的变形步兵机器人系统，核心亮点包括：ADRC 主动扰动拒绝控制实现、IMU 基础的姿态 PID 校正、多约束 QCP 求解器集成、裁判系统协议升级、UI 底盘方向指示和腿部弧线可视化、跨平台构建工具链完善，共涉及超 40 个新增或修改的关键文件。

[coderabbitai]

Caution

Review failed

Failed to post review comments

概览

步骤说明

此 PR 引入了对可变形步兵机器人（deformable infantry）的全面支持，包括构建系统验证、ADRC 控制算法、底盘与关节控制、硬件集成和裁判系统扩展。共添加约 7800 行代码，涉及配置、控制器、硬件驱动和 UI 组件的多层变更。

变更

构建系统和链接验证

层 / 文件	摘要
预运行验证 .script/build-rmcs	添加 check_default_dir_restorable() 和 restore_default_dir() 函数，在编译前验证并恢复 build、install、log 目录的链接状态。
跨编译链接支持 .script/build-rmcs-cross	新增 --link-default 标志及对应的 check_default_linkable() 和 link_default_base() 函数，在跨编译完成后为输出目录创建符号链接。
Shell 补全 .script/complete/_build-rmcs-cross	在补全脚本中添加 --link-default 选项的说明。

ADRC 控制器框架

层 / 文件	摘要
核心算法模块 rmcs_ws/src/rmcs_core/src/controller/adrc/TD.hpp, ESO.hpp, NLESF.hpp	分别实现跟踪微分器（TD）、扩展状态观测器（ESO）和非线性误差反馈（NLESF）的离散化算法，包含参数配置、状态管理和计算接口。
控制器集成 rmcs_ws/src/rmcs_core/src/controller/adrc/adrc_controller.cpp	实现完整的 ADRC 控制器组件，整合 TD、ESO、NLESF，支持动态限制、误差输入模式和 ROS 2 参数加载。
文档 rmcs_ws/src/rmcs_core/src/controller/adrc/adrc_V2_说明.md	提供 ADRC V2 架构的详细说明、数学公式和参数映射参考。

可变形底盘和关节控制

层 / 文件	摘要
关节层接口 rmcs_ws/src/rmcs_core/src/controller/chassis/deformable_joint_layer.hpp	定义关节反馈数据结构、腿部反馈、关节轨迹规划器及其状态管理接口。
关节 ADRC 控制 rmcs_ws/src/rmcs_core/src/controller/chassis/deformable_joint_controller.cpp	实现单关节的 ADRC 控制器，支持法向和悬挂模式、动态限制和扭矩前馈。
轮式底盘控制 rmcs_ws/src/rmcs_core/src/controller/chassis/deformable_omni_wheel_controller.cpp	基于 QCP 求解器的全向轮底盘控制器，结合速度 PID 和约束优化。
方向轮底盘控制 rmcs_ws/src/rmcs_core/src/controller/chassis/deformable_wheel_controller.cpp	多自由度方向轮底盘控制器，支持能量限制、几何优化和 QCP 求解约束。
底盘编制 rmcs_ws/src/rmcs_core/src/controller/chassis/deformable_chassis.cpp	高层底盘编制器，集成悬挂、速度控制、传感器融合和动力学管理。
QCP 求解器扩展 rmcs_ws/src/rmcs_core/src/controller/chassis/qcp_solver.hpp	增加半平面约束支持和通用 Sutherland-Hodgman 多边形裁剪算法。
功率管理 rmcs_ws/src/rmcs_core/src/controller/chassis/chassis_power_controller.cpp	扩展功率控制逻辑以支持右侧开关和键盘 Ctrl 键的增压模式检测。

硬件集成和设备驱动

层 / 文件	摘要
硬件抽象 rmcs_ws/src/rmcs_core/src/hardware/device/VT13.hpp, DjiMotorWithEncoder.hpp, dr16.hpp, lk_motor.hpp	新增 VT13 遥控器驱动和 DJI 编码电机支持；扩展 LK 电机型号；统一 PACKED_STRUCT 宏定义。
环形缓冲 rmcs_ws/src/rmcs_core/src/hardware/utility/ring_buffer.hpp	实现无锁环形缓冲区用于生产者-消费者数据传输。
Deformable Infantry V2 硬件 rmcs_ws/src/rmcs_core/src/hardware/deformable-infantry-v2.cpp	完整的硬件集成层，支持 IMU、多个 CAN 总线、UART 通信和状态反馈。
Deformable Infantry Omni 硬件 rmcs_ws/src/rmcs_core/src/hardware/deformable-infantry-omni.cpp	全向轮版本的硬件集成，包含底板、顶板和 IMU 子系统。

云台与控制扩展

层 / 文件	摘要
双轴云台求解器 rmcs_ws/src/rmcs_core/src/controller/gimbal/two_axis_gimbal_solver.hpp	扩展双轴云台求解器以支持编码器反馈路径和可配置的音高源。
可变形步兵云台 rmcs_ws/src/rmcs_core/src/controller/gimbal/deformable_infantry_gimbal_controller.cpp	集成自瞄控制和手动模式的新云台控制器实现。

裁判系统扩展

层 / 文件	摘要
状态数据结构 rmcs_ws/src/rmcs_core/src/referee/status/field.hpp	重构裁判系统数据结构以支持新的 HP、位置、地图指令和事件信息。
状态处理 rmcs_ws/src/rmcs_core/src/referee/status.cpp	扩展裁判状态处理器以解析并输出联盟血量、机器人位置、地图指令和飞镖信息。
UI 组件 rmcs_ws/src/rmcs_core/src/referee/app/ui/widget/crosshair_circle.hpp, deformable_chassis_top_view.hpp	新增准星圆形和可变形底盘腿部弧线的 UI 组件。
可变形步兵 UI rmcs_ws/src/rmcs_core/src/referee/app/ui/deformable_infantry_ui.cpp	完整的可变形步兵 UI 实现，显示底盘方向、腿部状态和实时反馈。

消息和基础设施

层 / 文件	摘要
消息类型 rmcs_ws/src/rmcs_msgs/include/rmcs_msgs/VT13_switch.hpp, hard_sync_snapshot.hpp	定义新消息类型用于 VT13 开关状态和硬同步快照。
滤波器 rmcs_ws/src/rmcs_core/src/filter/alpha_beta_angle_filter.hpp	实现角度 alpha-beta 滤波器以支持角度测量的平滑。
执行器修复 rmcs_ws/src/rmcs_executor/src/executor.hpp	改进圆形依赖检测以避免无效的映射解引用。
配置和插件 rmcs_ws/src/rmcs_bringup/config/deformable-infantry-omni.yaml, deformable-infantry-v2.yaml, rmcs_ws/src/rmcs_core/plugins.xml	为两个可变形步兵平台添加完整的参数配置；在插件注册表中声明所有新组件。

序列图

sequenceDiagram
    participant JoyInput as 遥控/键盘<br/>输入
    participant TD as 跟踪微分器<br/>(TD)
    participant ESO as 扩展状态<br/>观测器(ESO)
    participant NLESF as 非线性反馈<br/>(NLESF)
    participant Joint as 关节执行器
    
    JoyInput->>TD: 参考信号 r
    TD->>TD: 计算目标轨迹
    TD->>ESO: 跟踪信号 y1, y2
    Joint->>ESO: 实际测量 y
    ESO->>ESO: 估计扰动 z3
    ESO->>NLESF: 状态 z1, z2, z3
    NLESF->>NLESF: 非线性反馈<br/>计算控制律
    NLESF->>Joint: 控制指令 u
    Joint->>Joint: 执行/反馈

Loading

代码审查工作量估计

🎯 5 (关键) | ⏱️ ~120 分钟

可能相关的 PR

• Alliance-Algorithm/RMCS#67: 同时修改构建脚本和可变形步兵相关的跨编译集成配置。
• Alliance-Algorithm/RMCS#54: 同样修改 plugins.xml 以添加硬件和控制器插件条目。

建议审阅者

• qzhhhi
• creeper5820
• heyeuu

诗

🐰 在草地上跳过一行行新代码，
ADRC 的观测器如兔子般敏捷，
可变形的四足踏遍每一个方向，
遥控与自动交织成完美的舞蹈，
又一个步兵，准备好参战！ 🎖️

✨ 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 merge/deformable-infantry