个人笔记

外观

1. 概述 ​

Eclipse Cyclone DDS 采用基于 XML Schema (XSD) 的配置文件机制，允许用户在不修改源代码或重新编译的情况下，精细控制 DDS 运行时的网络行为、发现策略及性能参数。该机制遵循声明式配置原则，确保配置的一致性与合法性。

2. 配置文件加载机制 ​

Cyclone DDS 在启动时按以下优先级顺序查找并加载配置文件：

2.1 环境变量 (最高优先级) ​

通过设置 CYCLONEDDS_URI 环境变量指定配置源：

  • 本地文件路径：

    bash
    export CYCLONEDDS_URI=file://path/to/cyclonedds.xml
# 或使用相对路径
export CYCLONEDDS_URI=file://./cyclonedds.xml

  • 网络资源 URL：

    bash
    export CYCLONEDDS_URI=https://example.com/configs/cyclonedds_prod.xml

  • 直接嵌入内容：
    部分场景下可直接传入 XML 字符串（具体取决于实现版本）。

2.2 默认位置 ​

若未设置环境变量，系统将尝试在标准路径查找名为 cyclonedds.xml 的文件。常见位置包括：

  • /etc/cyclonedds.xml
  • 用户主目录

2.3 代码指定 (C API) ​

在使用 C API 创建参与者 (dds_create_participant) 时，可通过参数字符串覆盖全局配置。

3. XML 结构规范 ​

配置文件根元素为 <CycloneDDS>，需声明正确的命名空间及 Schema 位置以启用编辑器智能提示与校验。

xml
<CycloneDDS xmlns="https://cdds.io/config" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd">
    <Domain id="any">
        <!-- 配置内容 -->
    </Domain>
</CycloneDDS>

注：xsi:schemaLocation 指向官方 XSD 文件，用于验证语法正确性。

4. 核心配置模块详解 ​

有关配置设置（以及每个参数的默认值）的完整列表，请参阅配置文件参考 。

4.1 通用行为控制 (<General>) ​

控制 DDS 的全局传输行为。

配置项 类型 说明 示例值
AllowMulticast 布尔/枚举 控制是否允许 UDP 多播。设为 false 可强制单播，适用于受限网络。 true, false, default
MaxMessageSize 整数+单位 单个 RTPS 消息最大大小，超出部分将分片。 65536B, 1MB
MaxRecvMessageSize 整数+单位 接收缓冲区的最大消息大小。通常应大于等于 MaxMessageSize。 1MB
EnableUDPTransmission 布尔 是否启用 UDP 传输协议。 true, false
EnableTCPPort 整数 若使用 TCP 传输，指定监听端口。 7400

示例：

xml
<General>
    <AllowMulticast>false</AllowMulticast>
    <MaxMessageSize>1MB</MaxMessageSize>
    <EnableUDPTransmission>true</EnableUDPTransmission>
</General>

4.2 网络接口绑定 (<Network>) ​

指定绑定的网络接口，适用于多网卡环境。

  • autodetermine (布尔): 默认为 true 自动选择；设为 false 需手动指定。
  • address (IP): 当自动检测关闭时，指定绑定的单播 IP。
  • multicast (IP): 指定多播通信使用的接口 IP。

示例：

xml
<Network>
    <autodetermine>false</autodetermine>
    <address>192.168.1.100</address>
</Network>

4.3 发现机制 (<Discovery>) ​

控制节点间的发现方式，是跨子网或禁用多播环境下的关键配置。

  • Peers: 显式指定对等节点 IP 列表，用于静态发现。
  • ParticipantIndex: 固定内置端点 GUID 的索引。
  • MaxAutoPeerIndex: 自动发现 Peer 的最大索引值。

示例（静态指定 Peer）：

xml
<Discovery>
    <Peers>
        <Peer Address="192.168.1.20"/>
        <Peer Address="192.168.1.21"/>
    </Peers>
</Discovery>

4.4 共享内存加速 (<SharedMemory>) ​

启用 Eclipse Iceoryx 以实现同机进程间零拷贝通信。

  • 前提条件：系统已安装 Iceoryx 库，且 Cyclone DDS 编译时开启 -DENABLE_ICEORYX=ON。
  • Enable (布尔): 设为 true 启用。
  • Locator (字符串): 定位策略，通常为 auto (基于 MAC 地址生成标识)。

示例：

xml
<SharedMemory>
    <Enable>true</Enable>
    <Locator>auto</Locator>
</SharedMemory>

4.5 日志与调试 (<Tracing>) ​

控制内部日志输出，用于故障排查。

  • OutputFile: 日志文件路径，默认为 stderr。
  • Verbosity: 详细程度等级。
    • 0: Fatal, 1: Error, 2: Warning, 3: Config, 4: Info, 5: Debug, 6: Trace.

示例：

xml
<Tracing>
    <OutputFile>/tmp/cyclonedds.log</OutputFile>
    <Verbosity>debug</Verbosity>
</Tracing>

4.6 兼容性调整 (<Compatibility>) ​

用于解决与其他 DDS 实现（如 RTI Connext）的互操作问题。

  • AssumeRtiHasPmdEndpoints: 布尔值，假设对方拥有 PMD 端点。
  • StandardsConformance: 控制对 DDS 标准的遵循严格度。

5. 综合配置示例 ​

以下示例展示了一个生产环境的配置：禁用多播、使用静态发现、启用共享内存及详细日志。

文件名: cyclonedds_advanced.xml

xml
<CycloneDDS xmlns="https://cdds.io/config" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd">
    <Domain id="any">
        <General>
            <AllowMulticast>false</AllowMulticast>
            <MaxMessageSize>2MB</MaxMessageSize>
            <MaxRecvMessageSize>2MB</MaxRecvMessageSize>
        </General>
        
        <Network>
            <address>192.168.10.50</address>
        </Network>
        
        <Discovery>
            <Peers>
                <Peer Address="192.168.10.51"/>
                <Peer Address="192.168.10.52"/>
            </Peers>
        </Discovery>
        
        <SharedMemory>
            <Enable>true</Enable>
        </SharedMemory>
        
        <Tracing>
            <OutputFile>/var/log/cyclonedds.log</OutputFile>
            <Verbosity>info</Verbosity>
        </Tracing>
    </Domain>
</CycloneDDS>

加载方式：

bash
export CYCLONEDDS_URI=file:///path/to/cyclonedds_advanced.xml
./your_dds_application

6. 调试与验证 ​

6.1 语法验证 ​

使用 xmllint 工具校验 XML 是否符合官方 XSD：

bash
xmllint --noout --schema https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd cyclonedds.xml

若输出 cyclonedds.xml validates，则格式正确。

6.2 配置加载确认 ​

  1. 将 <Tracing>、<Verbosity> 设置为 config (3) 或更高。
  2. 启动应用，检查日志开头。系统通常会打印当前加载的配置摘要（如多播状态、共享内存状态等）。

6.3 共享内存生效验证 ​

  • 日志检查：在 info 或更高 verbosity 下，搜索 "Iceoryx" 或 "SHM" 关键字，确认出现初始化成功信息。
  • 文件系统检查：运行 ls -la /dev/shm | grep iox，若存在 iox_ 开头的文件，表明共享内存段已创建。
  • 网络抓包：在同机运行发布/订阅者，使用 tcpdump 监听端口。若共享内存生效，数据面流量应消失（仅保留少量发现流量）。

6.4 常见问题排查 ​

  • XML 解析失败：检查标签闭合、属性引号及命名空间声明。
  • 配置不生效：确认 CYCLONEDDS_URI 在进程启动前已导出。若在 ROS 2 环境中，需在 source setup.bash 后设置。
  • 共享内存无法启用：
    • 确认 Iceoryx 库已安装 (ldd your_app | grep iceoryx)。
    • 确认 Cyclone DDS 编译时启用了 ENABLE_ICEORYX。

7. 总结 ​

Cyclone DDS 的 XML 配置机制将网络拓扑、传输协议及性能参数从代码中解耦。通过合理配置，可实现：

  • 环境适配：同一二进制文件适应开发（多播）、生产（单播+静态 Peer）等不同网络环境。
  • 性能优化：灵活启用共享内存或调整缓冲区，无需重新编译。
  • 维护便捷：集中管理分布式系统的通信策略。

基于 VitePress 构建

Copyright © 2026 ww1820