OOMWOO I/O Board 的 ROS2 映射设计：oomwoo_mcu_bridge 硬件桥接节点完整解析

OOMWOO I/O Board 的 ROS2 映射设计oomwoo_mcu_bridge 硬件桥接节点完整解析【免费下载链接】oomwooOpen-source vacuum robot cleaner项目地址: https://gitcode.com/gh_mirrors/oo/oomwooOOMWOO 开源扫地机器人将高层行为与硬安全分别交给 ROS2运行在 CPU 侧与 STM32 I/O 板固件运行在 MCU 侧二者之间需要一个薄薄的桥接层。本文基于contributions/io-board-interface/xbattlax/docs/ros2_mapping.md的草案系统讲解未来oomwoo_mcu_bridge节点的角色定位、ROS2 主题/服务与 CPU/MCU 串行帧之间的映射关系、QoS 与速率约束、生命周期状态机、低层安全仲裁规则以及消息演进策略并结合仓库中的串行协议契约、参考编解码器与测试代码给出源码级佐证。读完本文你将掌握如何在 ROS2 一侧用标准消息驱动 OOMWOO 硬件、如何让 MCU 在 ROS2 崩溃时依然保持硬安全以及如何把DRIVE_SETPOINT、FAST_TELEMETRY等协议帧翻译为可被 Nav2、SLAM 与诊断工具直接消费的公开接口。说明本文对应的映射文档当前处于draft mapping for a futureoomwoo_mcu_bridgenode为未来节点准备的草案映射状态文中所有主题、帧、速率均为提议值最终以固件与 PCB 冻结后的合约为准。桥接角色ROS2 与 MCU 之间的薄翻译层oomwoo_mcu_bridge的职责是在公开的 ROS2 接口与 CPU/MCU 串行契约之间做翻译。文档明确要求这个桥必须薄thinROS2 拥有高层行为Nav2 导航、SLAM 建图、恢复recovery、清扫任务jobs、诊断聚合全部运行在 CPU 侧MCU 拥有硬安全与电机 IO电机驱动、编码器计数、电源切换、充电控制、悬崖/碰撞/轮跌响应与看门狗决策属于 MCU与 Linux/ROS2 是否存活无关。这一点与 ARCHITECTURE.md 中CPU/MCU 拆分把所有硬安全放在 MCU 上独立于 Linux/ROS2的顶层设计一脉相承Linux 和 ROS2 只能请求运动MCU 才决定运动是否仍然安全。文档给出了桥接层的标准数据流Nav2 / recovery / jobs / diagnostics | v oomwoo_mcu_bridge | CPU/MCU serial frames | v STM32 I/O board firmware桥接层在 CPU 侧消化geometry_msgs、sensor_msgs、std_msgs等标准消息在 MCU 侧产出/消费带0x0001~0x8005消息 ID 的二进制帧。这一划分与 SOFTWARE_INTERFACES.md 中硬件桥接草案章节的立场一致物理机器人通过 MCU 桥接而非 Gazebo 插件来暴露仿真级契约硬安全事件即使 ROS2 宕机也必须在 MCU 层处理。订阅的 ROS2 输入从 Twist 到有界运动指令映射文档为桥接节点定义了如下订阅侧接口每一行都对应一个具体的 MCU 帧MCU frameTopic/Service类型桥接动作MCU 帧/cmd_velgeometry_msgs/msg/Twist将线速度/角速度转换为有界 setpointDRIVE_SETPOINT/oomwoo/safety/e_stopstd_msgs/msg/Bool锁存或清除软件急停请求ESTOP_SET/oomwoo/cleaning/main_brush_pctstd_msgs/msg/UInt8设置主刷转速百分比CLEANING_MOTORS_SET/oomwoo/cleaning/side_brush_pctstd_msgs/msg/UInt8设置边刷转速百分比CLEANING_MOTORS_SET/oomwoo/cleaning/fan_pctstd_msgs/msg/UInt8设置吸尘风机转速百分比CLEANING_MOTORS_SET/oomwoo/cleaning/pump_pctstd_msgs/msg/UInt8设置水泵转速百分比CLEANING_MOTORS_SET/oomwoo/lidar/motor_pctstd_msgs/msg/UInt8若 MCU 拥有 LiDAR 电机控制则设置其 PWMLIDAR_MOTOR_SET/oomwoo/io/clear_faultsstd_srvs/srv/Trigger或自定义服务在安全条件恢复后清除选定的锁存故障CLEAR_LATCHED_FAULT/oomwoo/dock/final_cmd_velgeometry_msgs/msg/Twist可选Nav2 到达预对接位姿后的低速最终逼近指令DRIVE_SETPOINT更紧的钳位几个值得注意的细节百分比类输入四个清扫执行器共用同一个CLEANING_MOTORS_SET帧。查看参考编解码器 tools/oomwoo_mcu_frame.py 可知其负载为struct.pack(BBBB, main_brush_pct, side_brush_pct, fan_pct, pump_pct)四个字段取值范围均为 0~100越界会在编码阶段直接抛出ValueError。运动指令的短寿命设计/cmd_vel被转换为DRIVE_SETPOINT时并不带持续运动语义而是携带一个显式的duration_ms有效期。编解码器中的常量给出了硬性边界MAX_LINEAR_MM_S 500最大线速度 500 mm/s、MAX_ANGULAR_MRAD_S 4000最大角速度 4000 mrad/s、MAX_SETPOINT_DURATION_MS 250setpoint 最长存活 250 ms且duration_ms 0会被拒绝——这意味着永远运动的指令在协议层根本不存在。急停与清障ESTOP_SET由 CPU 主动请求但 MCU 仍是最终安全权威CLEAR_LATCHED_FAULT通过u16 fault_mask位掩码选择要清除的锁存故障与SAFETY_STATE中的latched_flags一一对应。发布的 ROS2 输出把 MCU 遥测翻译成标准主题桥接节点向 ROS2 网络发布的输出主题如下每行标注了帧来源与用途说明Topic类型来源帧说明/odomnav_msgs/msg/OdometryFAST_TELEMETRY可选若桥接节点自行计算轮式里程计则发布否则只发布轮子数据/joint_statessensor_msgs/msg/JointStateFAST_TELEMETRY由编码器 ticks 换算的轮关节位置/battery_statesensor_msgs/msg/BatteryStatePOWER_TELEMETRY电压、电流、充电状态、回充/充电标志/oomwoo/io/bumperstd_msgs/msg/UInt8初期FAST_TELEMETRY、SAFETY_EVENT、SAFETY_STATE位域直到自定义消息就绪/oomwoo/io/cliffstd_msgs/msg/UInt8初期FAST_TELEMETRY、SAFETY_EVENT、SAFETY_STATE悬崖传感器位域/oomwoo/io/wheel_dropstd_msgs/msg/UInt8初期FAST_TELEMETRY、SAFETY_EVENT、SAFETY_STATE轮跌落传感器位域/oomwoo/io/dockstd_msgs/msg/UInt8初期POWER_TELEMETRY回充座在位与充电位/oomwoo/dock_ir/front_leftstd_msgs/msg/Float32初期FAST_TELEMETRY或传感器帧归一化最终逼近 IR 信标强度/oomwoo/dock_ir/front_rightstd_msgs/msg/Float32初期FAST_TELEMETRY或传感器帧归一化最终逼近 IR 信标强度/oomwoo/dock_ir/search_leftstd_msgs/msg/Float32初期FAST_TELEMETRY或传感器帧左侧回充搜索信标强度/oomwoo/dock_ir/search_rightstd_msgs/msg/Float32初期FAST_TELEMETRY或传感器帧右侧回充搜索信标强度/oomwoo/dock/statestd_msgs/msg/String初期桥接层 回充周期策略JSON 状态visible、aligned、contact made、charging active/oomwoo/io/mcu_statusdiagnostic_msgs/msg/DiagnosticArrayMCU_DIAGNOSTIC看门狗、循环时序、CRC 丢帧、复位原因/diagnosticsdiagnostic_msgs/msg/DiagnosticArray全部遥测与标准 ROS 诊断工具集成/oomwoo/statusstd_msgs/msg/String初期桥接策略 安全帧与现有恢复原型兼容的 JSON 状态要点解读帧来源决定信息新鲜度碰撞、悬崖、轮跌三个位域同时从高频FAST_TELEMETRY、事件型SAFETY_EVENT与周期型SAFETY_STATE汇聚而来。这与串行契约中SAFETY_STATE是权威的周期安全快照事件码 N 映射到位 N-1FAST_TELEMETRY保留低 8 位锁存位以兼容 protocol-v1 实现但新桥接层必须用SAFETY_STATE重建完整的 active/latched 状态的约定一致见 cpu_mcu_serial_contract.md。安全快照的位域换算参考实现 tools/oomwoo_mcu_frame.py 的safety_event_flag()说明事件码从 1 开始计位偏移为1 (event - 1)当前 1~10 号事件恰好能放进一个u16未知高位必须保留用于诊断并在含义明确前视为抑制运动。FAST_TELEMETRY负载形状从 tools/oomwoo_mcu_frame.py 可看到其负载格式为IiiBBBBBH依次是timestamp_ms、left_ticks、right_ticks32 位有符号编码器 ticks、bumper_flags、cliff_flags、wheel_drop_flags、dock_flags、safety_latched_flags各 8 位与battery_mv16 位。单元测试 tests/test_oomwoo_mcu_frame.py 验证了该负载的打包/解包往返一致性。回充 IR 主题四个dock_ir主题源自 docking_ir_requirements.md 的传感器归属提议——两个前向 IR 传感器中间隔板分离用于最终逼近归航左右各一个用于未知回充座位置时的搜索初期全部以归一化 0.0~1.0 强度发布。QoS 与速率约束让每个通道用正确的新鲜度说话映射文档对每个接口给出了明确的 QoS/速率建议这是桥接层最容易踩坑的部分接口QoS/速率/cmd_vel输入Reliable 或 best-effort 小队列过期值绝不允许重放DRIVE_SETPOINT串行输出活动时 20-50 Hz携带短 duration 字段FAST_TELEMETRY串行输入目标 50-100 HzSAFETY_STATE串行输入10 Hz且安全状态变化后立即补发一次电池/电源主题1-5 Hz诊断1 Hz 事件突发安全事件可行时 Reliable锁存期间重复发送这些速率与 cpu_mcu_serial_contract.md 的消息目录逐条对齐HEARTBEAT20-50 Hz、DRIVE_SETPOINT20-50 Hz、FAST_TELEMETRY50-100 Hz、POWER_TELEMETRY1-5 Hz、MCU_DIAGNOSTIC1 Hz/事件、SAFETY_STATE10 Hz事件。两条核心原则过期指令必须失败安全/cmd_vel使用小队列陈旧 Twist 不得被重放。串行契约侧的配合是DRIVE_SETPOINT.duration_ms草案上限 250 ms——setpoint 一旦过期MCU 自行把驱动输出归零绝不记住上一条指令继续跑。状态通道分级需要高频闭环的量编码器、安全标志走高带宽通道电池、诊断这类低频量走 1-5 Hz 通道避免占用串口带宽影响运动控制。这与 SOFTWARE_INTERFACES.md 中命令主题应使用小队列并失败安全的总则一致。生命周期行为让桥接节点可被管理桥接节点应采用lifecycle node或等价状态机因为串行连接与运动输出都不能在节点未就绪时随意打开。文档定义的状态机如下状态行为unconfigured无串行连接无执行器指令inactive串行可打开发送IDENTIFY_REQUEST并等待MCU_HELLO但不发送心跳、不输出任何运动active心跳运行、接受 setpoint、发布遥测error心跳停止、setpoint 归零、诊断说明原因关键安全语义deactivate、shutdown 或崩溃时心跳随之停止MCU 随后独立停止运动。这正是MCU 是硬安全终点的体现——CPU 侧无论以何种方式消失MCU 都能通过心跳超时草案 150 ms 硬停止阈值接管局面。IDENTIFY_REQUEST的设计让启动顺序解耦无论哪一端先上电CPU 都能主动发起握手MCU 在启动时自发发出MCU_HELLO并在每次有效 identify 请求后重新应答。握手请求不会武装输出、不会刷新心跳、不会重放历史指令见 cpu_mcu_serial_contract.md。编解码器用空负载表示IDENTIFY_REQUESTstruct_format: 一致性清单 conformance/protocol_v1.json 中也有对应记录。仲裁桥接层只管低层安全不做高层裁决文档明确指出同一时刻只允许一个 ROS2 组件写入/cmd_vel高层仲裁谁有权发指令由 Nav2、恢复节点、任务模块自己去解决桥接层只负责强制低层安全钳制最大线速度/角速度对应编解码器中的MAX_LINEAR_MM_S 500、MAX_ANGULAR_MRAD_S 4000钳制 setpoint 时长MAX_SETPOINT_DURATION_MS 250deactivate 时发送全零 setpoint当 e-stop、悬崖、轮跌或 CPU 超时处于锁存状态时停止转发运动指令。这套桥接层不抢 Nav2 的活但守住安全底线的分工正是 SOFTWARE_INTERFACES.md 对模块的普遍要求若某模块需要直接指挥运动必须定义它与 Nav2、恢复节点之间的仲裁方式避免两个节点在/cmd_vel上打架。回充低速阶段的特殊钳位回充docking有一个特殊阶段Nav2 到达已知预对接位姿之后回充控制器可发布/oomwoo/dock/final_cmd_vel。此时桥接层应施加比正常导航更紧的线/角速度钳位、更短的 setpoint 时长而 MCU 的硬停止权限不变。这与 docking_ir_requirements.md 中的两段式回充状态机呼应navigate_to_predock由 Nav2 负责 →search_for_beacon/final_ir_align交给独立回充控制器不依赖 Nav2最终逼近依靠前左/前右 IR 读数平衡且递增判据整个过程中 MCU 依然在 bumper/cliff/wheel-drop/e-stop/心跳超时上保有最终停止权。也就是说低速只是 CPU 侧的请求姿态变化MCU 侧的硬安全边界从未放宽。消息演进先标准消息后冻结自定义消息映射文档为第一个可用桥接节点制定了务实的消息策略起步就用标准 ROS2 消息geometry_msgs/msg/Twist、sensor_msgs/msg/BatteryState、sensor_msgs/msg/JointState、diagnostic_msgs/msg/DiagnosticArray以及小型std_msgs位域碰撞/悬崖/轮跌/回充各用一个UInt8等到真实硬件信号稳定后再把位域升级为oomwoo_msgs包中的自定义消息。换句话说硬件定型前不值得为可能变动的位域冻结自定义消息类型用标准消息先跑通仿真与真机等信号语义稳定再冻结。这与 SOFTWARE_INTERFACES.md 中优先使用标准 ROS2/Nav2 消息类型再引入自定义 OOMWOO 消息的规则完全一致也呼应了 xbattlax 贡献 README 中列出的评审问题之一桥接层是先发布简单标准 ROS 消息等硬件稳定后再引入自定义 OOMWOO 消息还是直接上自定义消息——本文档的答案显然是前者。仓库中的落地配套编解码器、仿真器与一致性验证虽然oomwoo_mcu_bridge节点本身尚属未来但映射文档依赖的协议侧工具已经在仓库中可运行、可测试恰好为桥接开发提供了先验证协议、再写节点的路径参考编解码器tools/oomwoo_mcu_frame.py 实现完整帧格式魔数OW、版本、flags、序号、消息类型、负载长度、CRC-16/CCITT-FALSE魔数参与 CRC并提供encode_frame/decode_frame/StreamDecoder以及pack_heartbeat、pack_drive_setpoint、pack_cleaning_motors、pack_safety_event、pack_safety_state、pack_fast_telemetry等负载打包助手。流式解码器可丢弃噪声、容忍半帧、等待下一个OW魔数重新对齐——这正是 UART/CDC 串口上桥接节点需要的解析行为。单元测试tests/test_oomwoo_mcu_frame.py 覆盖 CRC 已知向量crc16_ccitt_false(b123456789) 0x29B1、心跳往返、坏 CRC 拒绝、流式解码处理噪声与半帧、拆分魔数、DRIVE_SETPOINT边界线速度 501 拒绝、时长 251 拒绝、时长为 0 拒绝、百分比负载边界101 拒绝以及安全状态位域换算。桥接节点可以直接复用这些解析逻辑与边界语义。确定性 MCU 仿真器tools/sim_mcu.py 生成确定性样本帧高频FAST_TELEMETRYSAFETY_EVENTSAFETY_STATE可用于桥接层与日志解析测试。运行方式从仓库根目录python3 contributions/io-board-interface/xbattlax/tools/sim_mcu.py --count 3一致性套件conformance/ 把冻结的消息 ID 与负载布局固化为机器可读清单protocol_v1.json与语言无关的黄金向量golden_vectors_v1.jsonPOWER_TELEMETRY与MCU_DIAGNOSTIC在清单中标记为payload_status: open即必须有明确理由说明为何未冻结负载。verify_vectors.c以严格 C11/C17 编译并校验每一帧的头部、负载与 CRC——固件、Python 测试与未来 C/Rust 桥接层共享同一套可执行参考。运行全部 Python 测试README 中的快速验证命令python3 -m unittest discover \ -s contributions/io-board-interface/xbattlax/tests \ -p test_*.py总结oomwoo_mcu_bridge的 ROS2 映射草案给出了一个职责清晰的分层方案ROS2 消费标准消息、生产标准遥测MCU 通过短寿命 setpoint 与心跳看门狗始终握有硬安全权。映射表、QoS 速率表、生命周期状态机与仲裁规则共同保证了ROS2 可以请求、MCU 决定安全这一核心边界而仓库中的参考编解码器、仿真器与跨语言一致性向量则为桥接层提供了先验证协议、再写节点的可执行基础。后续开发中位域消息是否升级为oomwoo_msgs自定义类型、POWER_TELEMETRY/MCU_DIAGNOSTIC负载何时冻结将是消息演进路线上的两个关键决策点。【免费下载链接】oomwooOpen-source vacuum robot cleaner项目地址: https://gitcode.com/gh_mirrors/oo/oomwoo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考