5. Commsgs 模块架构设计

本文描述 autonomy/commsgs 的逻辑架构、双层消息模型与全栈集成关系。

5.1 设计目标

commsgs 模块遵循以下设计原则：

  1. ROS 语义兼容：字段命名、坐标系约定、Stamped/WithCovariance 模式与 ROS 2 common_msgs 保持一致

  2. 双层分离：C++ struct 供算法零开销使用，proto 供序列化与跨进程通信

  3. 显式边界转换：ToProto/FromProto 在模块边界集中调用，便于测试与审计

  4. 无 ROS 运行时依赖：不使用 rosidl/rclcpp，Autonomy 自研通信栈

  5. 可扩展：新增消息包遵循 proto → hpp → cpp 三层模式

5.2 实现状态

组件

实现度

说明

16 个 proto 包

✅

schema 已定义

C++ struct 定义

✅

主要消息类型已覆盖

ToProto/FromProto

⏳

核心包完整，部分 stub

PointCloud2 工具

✅

迭代器 + 字段转换

Nav2 Action/Service

✅ proto

C++ 层仅 SpeedLimit

错误码体系

✅ proto

含 Nav2 遗留别名

独立 CMake 目标

❌

随 libautonomy glob 编译

5.3 分层架构

应用层 Planning / Map / Control / Localization 算法模块，使用 C++ commsgs struct
典型消息
Path PoseStamped OccupancyGrid Twist Imu
内存中直接传递 struct / shared_ptr
消息层 autonomy::commsgs C++ struct + ToProto/FromProto 转换
核心包
builtin_interfaces std_msgs geometry_msgs sensor_msgs map_msgs
工具
PointCloud2Iterator PointCloud2Modifier point_field_conversion
ToProto() / FromProto()
序列化层 commsgs::proto protoc 生成的 google::protobuf::Message
生成物
*.pb.h *.pb.cc SerializeToString ParseFromString
Autolink wire format
传输层 Autolink Writer / Reader / Service / Action
通信原语
CreateWriter<T> CreateReader<T> CreateService<Req,Resp> CreateActionClient<ActionT>

5.4 文件组织模式

每个消息包遵循固定三文件模式：

proto/<pkg>.proto          ← schema 定义（单一事实来源）
<pkg>_msgs.hpp             ← C++ struct + ToProto/FromProto 声明
<pkg>_msgs.cpp             ← 转换函数实现

依赖方向（仅向下）：

geometry_msgs.hpp → std_msgs.hpp → builtin_interfaces.hpp
sensor_msgs.hpp   → geometry_msgs.hpp, std_msgs.hpp
map_msgs.hpp      → geometry_msgs.hpp, std_msgs.hpp
planning_msgs.hpp → geometry_msgs.hpp, std_msgs.hpp
nav_msgs.proto    → planning_msgs.proto, geometry_msgs.proto, error_code.proto

5.5 构建集成

commsgs 无独立 CMake 目标，通过根工程统一构建：

# cmake/autonomy_sources.cmake
file(GLOB_RECURSE AUTONOMY_SOURCES "autonomy/*.cpp")
file(GLOB_RECURSE ALL_PROTOS "autonomy/*.proto")

# 根 CMakeLists.txt
protoc --cpp_out=${PROJECT_BINARY_DIR} ...
add_library(autonomy SHARED ${AUTONOMY_SOURCES} ${GENERATED_PROTO_SRCS})
target_link_libraries(autonomy protobuf autolink ...)

安装时同步安装源 hpp 与生成 *.pb.h 到 include/autonomy/commsgs/。

5.6 运行时数据流

5.6.1 进程内 Pub/Sub

模块 A                    Autolink                    模块 B
  │                         │                          │
  │  Write(Imu struct)      │                          │
  ├────────────────────────►│                          │
  │                    [序列化]                         │
  │                         ├─────────────────────────►│
  │                         │              callback(shared_ptr<Imu>)

Autolink 在 Writer/Reader 边界自动处理序列化，应用代码始终操作 C++ struct。

5.6.2 Service / Action

Client (proto)  ──request──►  Service (proto)
                                    │
                              FromProto()
                                    │
                              C++ struct 业务逻辑
                                    │
                              ToProto()
                                    │
Client (proto)  ◄─response──  Service (proto)

5.6.3 跨模块传递（无网络）

同一进程内模块间可直接传递 C++ struct 引用或 shared_ptr，无需 proto 转换：

// system::Autonomy 内部
controller_->SetPlan(path);  // planning_msgs::Path，无序列化

5.7 消费模块矩阵

模块

使用的 commsgs 包

典型消息

planning

geometry_msgs, planning_msgs, proto::nav_msgs

Path, IsPathValid

map/costmap_2d

geometry_msgs, map_msgs, sensor_msgs

OccupancyGrid, PointCloud2

control

geometry_msgs, planning_msgs, builtin_interfaces

Twist, Path, Pose

transform

geometry_msgs, builtin_interfaces

TransformStamped

localization

geometry_msgs, sensor_msgs

PoseWithCovariance, Imu

visualization

多种 commsgs

Marker, Path, OccupancyGrid

sensor

sensor_msgs

Imu, LaserScan, Image

bridge

全部

ROS ↔ Autonomy 转换

5.8 扩展点

扩展场景

步骤

新增消息类型

proto → hpp struct → cpp 转换 → 重编译

新增消息包

新建三文件 + 在消费模块 include

新增 Action

在 nav_msgs.proto 添加 Goal/Feedback/Result

新增错误码

在 error_code.proto 对应模块段添加枚举值

ROS 桥接

在 bridge 模块实现 ROS msg ↔ commsgs 转换

5.9 与 ROS 2 架构对比

维度

ROS 2

Autonomy commsgs

消息定义

.msg / .idl → rosidl 生成

手写 hpp + proto

序列化

CDR / Fast-DDS

Protocol Buffers

运行时

rclcpp

Autolink

类型系统

单一生成类型

C++ struct + proto 双层

扩展

新 .msg 文件

proto + hpp + cpp 三文件