# 21 · DDS 配置 + colcon overlay 完全指南

> **目标**: 理解 ROS2 DDS 中间件配置、colcon overlay 混合工作空间,能为多机 / 跨网段部署做正确配置。

---

## 目录

- [1. DDS 是什么](#1-dds-是什么)
- [2. RMW 实现](#2-rmw-实现)
- [3. 关键环境变量](#3-关键环境变量)
- [4. domain ID 隔离](#4-domain-id-隔离)
- [5. 跨网段发现](#5-跨网段发现)
- [6. Cyclone DDS 配置](#6-cyclone-dds-配置)
- [7. colcon overlay](#7-colcon-overlay)
- [8. 三机部署实操](#8-三机部署实操)
- [9. 推荐阅读](#9-推荐阅读)

---

## 1. DDS 是什么

**DDS (Data Distribution Service)** = OMG 制定的实时通信中间件标准。
ROS2 默认用 DDS 做底层通信,不同 RMW 实现:
- `rmw_fastrtps_cpp`(默认,Fast DDS)
- `rmw_cyclonedds_cpp`(Cyclone DDS)

DDS 提供:
- 自动节点发现(基于 UDP multicast)
- 多种 QoS
- 实时性(零拷贝、共享内存)

## 2. RMW 实现

| RMW | 包 | 适用 |
|---|---|---|
| `rmw_fastrtps_cpp` | `ros-humble-rmw-fastrtps-cpp` | 通用,默认 |
| `rmw_cyclonedds_cpp` | `ros-humble-rmw-cyclonedds-cpp` | 跨网段 / Xenomai 实时 |

切换:

```bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
# 然后 colcon build + 启动节点
```

**注意**: 切换 RMW 后必须 `rm -rf build/ install/ log/` 再 build,否则 CMake 配置缓存导致 link 错误。

## 3. 关键环境变量

| 变量 | 用途 | 默认 |
|---|---|---|
| `ROS_DOMAIN_ID` | DDS 域 ID(0-232) | 0 |
| `RMW_IMPLEMENTATION` | RMW 实现 | `rmw_fastrtts_cpp` |
| `ROS_STATIC_PEERS` | 跨网段单播发现 | `<unset>` |
| `ROS_DISCOVERY_SERVER` | 集中式发现服务 | `<unset>` |
| `ROS_LOCALHOST_ONLY` | 仅本机 | 0 |
| `CYCLONE_DDS_URI` | Cyclone DDS XML 配置 URI | `<unset>` |
| `FASTRTPS_DEFAULT_PROFILES_FILE` | FastDDS XML 配置路径 | `<unset>` |

## 4. domain ID 隔离

同 `ROS_DOMAIN_ID` 才能互通,改 ID 就隔离:

```bash
# PC 端
ROS_DOMAIN_ID=42 ros2 launch my_pkg demo.py

# RK3506 端
ROS_DOMAIN_ID=42 ros2 launch my_pkg demo.py
# 两端可见

# 改 ID 后不可见
ROS_DOMAIN_ID=43 ros2 launch my_pkg demo.py
```

**注意**: 域 ID 范围 0-232(ROS2 DDS 协议)。

## 5. 跨网段发现

### 问题

UDP multicast **不跨路由器**,跨网段(如 192.168.1.x ↔ 192.168.2.x)默认看不见。

### 方案 1: 单播发现 (`ROS_STATIC_PEERS`)

```bash
# PC 端(知道 RK3506 IP,分隔符是英文逗号 `,`,不是分号)
ROS_STATIC_PEERS="192.168.2.10,192.168.2.11" \
  ros2 launch my_pkg demo.py
```

### 方案 2: Discovery Server

```bash
# PC 端启 discovery server
ros2 run discovery_server discovery_server --address 0.0.0.0 --port 11811

# 客户端
export ROS_DISCOVERY_SERVER=192.168.2.10:11811
ros2 launch my_pkg demo.py
```

### 方案 3: Cyclone DDS LAN 配置

`cyclonedds.xml`:

```xml
<CycloneDDS>
  <NetworkInterface name="eth0" priority="default" multicast="default"/>
</CycloneDDS>
```

## 6. Cyclone DDS 配置

### 安装

```bash
sudo apt install ros-humble-rmw-cyclonedds-cpp
```

### 配置 XML

```bash
export CYCLONE_DDS_URI=file:///etc/cyclonedds.xml
```

`/etc/cyclonedds.xml`:

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<CycloneDDS xmlns="https://cdds.io/config">
  <Domain id="any">
    <General>
      <Interfaces>
        <NetworkInterface autodetermine="true" priority="default" multicast="default"/>
      </Interfaces>
    </General>
  </Domain>
</CycloneDDS>
```

## 7. colcon overlay

**colcon overlay** = 多个 colcon 工作空间叠加,后者覆盖前者(同名包优先用 overlay)。

### 工作流

```bash
# 主工作空间 base(完整)
mkdir -p ~/ros2_main_ws/src
cd ~/ros2_main_ws/src
git clone <完整仓库>  # 或 git pull
cd ..
colcon build --symlink-install  # build 全部

# overlay 工作空间(只 build 修改的包)
mkdir -p ~/ros2_overlay_ws/src
cd ~/ros2_overlay_ws/src
# 符号链接主工作空间的 src(只覆盖你想改的包)
ln -s ~/ros2_main_ws/src/my_pkg .
# 修改 my_pkg
cd ..
colcon build --symlink-install --packages-select my_pkg

# 激活:先 base 后 overlay
source ~/ros2_main_ws/install/setup.bash
source ~/ros2_overlay_ws/install/setup.bash  # 覆盖
```

### 典型场景

- **稳定版 + 开发版**:base 用稳定版,overlay 跑新代码
- **共享代码 + 私有修改**:base 装共享库,overlay 装你的定制
- **CI**:base 装大型依赖,overlay 只 build 改的

## 8. 三机部署实操

**典型拓扑**:
```
PC (192.168.1.10, ROS_DOMAIN_ID=0)
   │
   ├─ RDK X5 (192.168.1.20, ROS_DOMAIN_ID=0)
   │
   └─ RK3506 × 2 (192.168.1.30, 192.168.1.31, ROS_DOMAIN_ID=0)
```

**配置**: 三机同 ROS_DOMAIN_ID + 同 LAN,FastDDS multicast 自动发现。

**RK3506 精简**: 用 `ros-humble-ros-base`,关 daemon:

```bash
# 装精简包
sudo apt install ros-humble-ros-base

# 关 daemon(省内存)
sudo systemctl disable --now ros2-daemon

# 设置环境变量(~/.bashrc)
export ROS_DOMAIN_ID=0
source /opt/ros/humble/setup.bash
```

详见 [`doc/100-embedded-deployment.md`](100-embedded-deployment.md)。

## 9. 推荐阅读

- [ROS2 DDS 概念](https://docs.ros.org/en/humble/Concepts/About-DDS-Implementations.html)
- [FastDDS 文档](https://fast-dds.docs.eprosima.com/)
- [Cyclone DDS 文档](https://cyclonedds.io/docs/)
- [colcon 文档](https://colcon.readthedocs.io/)
- [REP-2002 ROS 2 Design](https://www.ros.org/reps/rep-2002.html)
- [`py_overlay_dds` 包](../src/py_overlay_dds/README.md)
- [三机部署实操](100-embedded-deployment.md)

---

---

## 📖 阅读路径导航

> 💡 这是仓库 `doc/` 下所有文档的推荐阅读顺序。[返回 README 总导航](../README.md#-23-篇文档怎么读)
>
> ⏱ **本文预计阅读时间**: 30 分钟
> 📍 **当前位置**: 第 13 / 24 篇

- ⏮ **上一篇**: [ros2 bag 数据记录](20-bag.md)
- ⏭ **下一篇**: [Docker 容器化开发](85-docker.md)