> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ROS 2 DDS Config Optimizer

[`ROS2-DDSConfig-Optimizer`](https://github.com/qualcomm-qrb-ros/ROS2-DDSConfig-Optimizer) is an LLM-driven auto-tuner for FastDDS configuration. You hand it performance targets (latency, throughput, reliability, CPU, memory) plus a baseline DDS XML, and it iteratively runs your application, benchmarks it, and mutates DDS parameters until the targets are met.

<Note>
  Qualcomm-built, but **SoC-agnostic** — it runs on any Ubuntu host with ROS 2 Humble or Jazzy, no Qualcomm hardware required. Listed in this section because it's part of the QRB ROS ecosystem and signals Qualcomm's investment in broadly-useful ROS 2 tooling, not just silicon plumbing.
</Note>

## Why DDS tuning is a problem worth automating

DDS exposes hundreds of knobs — reliability QoS, history depth, heartbeat periods, socket buffers, participant discovery, transport descriptors. Most teams either leave the defaults in place and eat the latency, or hand-tune for weeks per workload. This tool treats DDS configuration as a black-box optimization problem and delegates the parameter search to an LLM driving FastDDS XML.

```mermaid theme={null}
flowchart LR
    U["Performance targets<br/>(latency, throughput, CPU, mem)"] --> O["DDSConfig Optimizer<br/>(LLM)"]
    C["Baseline DDS XML"] --> O
    O -->|candidate XML| R["Your ROS 2 app"]
    R --> B["ros2_benchmark"]
    B -->|metrics| O
    O --> BEST["Optimized DDS XML"]
    style O fill:#31017D,stroke:#31017D,color:#fff
```

## Quick start

<Info>
  Uses [`uv`](https://docs.astral.sh/uv/) (≥ 0.7.8) for Python env management.
</Info>

<Steps>
  <Step title="Clone and sync">
    ```bash theme={null}
    git clone https://github.com/qualcomm-qrb-ros/ROS2-DDSConfig-Optimizer.git
    cd ROS2-DDSConfig-Optimizer
    uv sync
    ```
  </Step>

  <Step title="Provide targets and a baseline config">
    Fill in [`user_requirements_template.xml`](https://github.com/qualcomm-qrb-ros/ROS2-DDSConfig-Optimizer/blob/main/data/templates/user_requirements_template.xml) with your latency / throughput / reliability / resource targets, and [`fastdds_config_template.xml`](https://github.com/qualcomm-qrb-ros/ROS2-DDSConfig-Optimizer/blob/main/data/templates/fastdds_config_template.xml) with your baseline DDS config.
  </Step>

  <Step title="Run the optimizer">
    ```bash theme={null}
    uv run fastdds-optimizer run \
      --requirements /path/to/user_requirements.xml \
      --initial-config /path/to/initial_DDS_config.xml
    ```

    The best config is written into `data/optimization_history/`.
  </Step>

  <Step title="Inspect the dashboard">
    ```bash theme={null}
    uv run fastdds-optimizer dashboard --port 5000
    ```

    Open [http://localhost:5000/](http://localhost:5000/) to browse iteration history and compare configs.
  </Step>
</Steps>

## Requirements

| Item              | Requirement                                                            |
| ----------------- | ---------------------------------------------------------------------- |
| OS                | Ubuntu                                                                 |
| ROS 2             | Humble or Jazzy                                                        |
| DDS               | FastDDS                                                                |
| Python env        | [`uv`](https://docs.astral.sh/uv/) ≥ 0.7.8                             |
| Benchmark harness | [`ros2_benchmark`](https://github.com/qualcomm-qrb-ros/ros2_benchmark) |

## Why this helps

| Alternative                                       | Short take                                                                                                       |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Manual FastDDS XML editing                        | Full control, but requires reading hundreds of pages of spec; no automated search; weeks of tuning per workload. |
| ROS 2 built-in QoS profiles (`sensor_data`, etc.) | Sensible presets but only \~7 of them; covers a small subset of DDS knobs.                                       |
| `iceoryx` / `rmw_iceoryx`                         | Different problem (shared-memory transport backend); doesn't tune QoS.                                           |
| Hand-rolled benchmark loops + parameter sweeps    | Works, but doesn't transfer between workloads — every project pays the engineering cost again.                   |

The only tool in the ROS 2 ecosystem that treats DDS configuration as a black-box optimization problem with an LLM driving the search. Hand it perf targets and a baseline XML, get back a tuned config without reading the FastDDS spec.

## Related

* [`qrb-ros-benchmark.mdx`](./qrb-ros-benchmark) — the QRB-aware extension of the same `ros2_benchmark` framework this optimizer drives.
* Upstream: [`qualcomm-qrb-ros/ROS2-DDSConfig-Optimizer`](https://github.com/qualcomm-qrb-ros/ROS2-DDSConfig-Optimizer).