Skip to main content

hdds-router

DDS Routing Service for domain bridging, topic remapping, and QoS transformation.

Overview​

hdds-router enables communication between isolated DDS domains by forwarding messages across domain boundaries. Use cases include:

  • Domain Bridging: Connect domains 0 and 1 (e.g., sensor network → control system)
  • Topic Remapping: Rename topics during routing (e.g., rt/cmd_vel → robot/velocity)
  • QoS Transformation: Adapt QoS policies between domains (e.g., BestEffort → Reliable)
  • Network Segmentation: Selective routing of specific topics

Installation​

cargo install hdds-router

Or build from source:

cd crates/hdds-router
cargo build --release

Quick Start​

Basic Domain Bridge​

Route all topics from domain 0 to domain 1:

hdds-router --from-domain 0 --to-domain 1

Bidirectional Routing​

Route topics in both directions:

hdds-router --from-domain 0 --to-domain 1 --bidirectional

Selective Topics​

Route only specific topics:

hdds-router --from-domain 0 --to-domain 1 --topics "sensor/*,rt/cmd_vel"

Topic Remapping​

Rename topics during routing:

hdds-router --from-domain 0 --to-domain 1 \
  --remap "rt/cmd_vel:robot/velocity,sensor/temp:environment/temperature"

CLI Reference​

hdds-router [OPTIONS] [COMMAND]

Options:
  -c, --config <FILE>           Configuration file path (TOML)
      --from-domain <ID>        Source domain ID (0-232)
      --to-domain <ID>          Destination domain ID (0-232)
  -b, --bidirectional           Enable bidirectional routing
  -t, --topics <LIST>           Topic filter (comma-separated, supports globs)
  -e, --exclude <LIST>          Topics to exclude (comma-separated)
  -r, --remap <LIST>            Topic remapping (src:dst,src2:dst2)
  -q, --qos-transform <PRESET>  QoS transformation preset
  -v, --verbose                 Verbose output
  -h, --help                    Print help
  -V, --version                 Print version

Commands:
  gen-config   Generate example configuration file
  validate     Validate configuration file
  status       Show routing statistics

Topic Filters​

Glob patterns are supported:

PatternMatches
sensor/*sensor/temp, sensor/humidity
rt/*_velrt/cmd_vel, rt/linear_vel
?obot/staterobot/state, Robot/state

Configuration File​

For complex setups, use a TOML configuration file:

# hdds-router.toml

[router]
stats_interval_secs = 10

[[routes]]
name = "sensors-to-control"
source_domain = 0
target_domain = 1
bidirectional = false

[routes.topics]
mode = "include"
patterns = ["sensor/*", "status/*"]

[[routes.remaps]]
from = "sensor/temperature"
to = "environment/temp_celsius"

[[routes.remaps]]
from = "sensor/humidity"
to = "environment/humidity_pct"

[routes.qos_transform]
reliability = "reliable"
durability = "transient_local"
history_depth = 10

[[routes]]
name = "commands-to-robot"
source_domain = 1
target_domain = 0
bidirectional = false

[routes.topics]
mode = "pattern"
patterns = ["rt/cmd_*"]

[routes.qos_transform]
reliability = "reliable"
deadline_us = 100000
lifespan_us = 500000

Topic Selection Modes​

ModeDescriptionExample
allRoute all discovered topicsDefault
includeOnly specified topics["sensor/*", "rt/*"]
excludeAll except specified["internal/*"]
patternSingle glob pattern"*_status"

QoS Transformation​

Transform QoS policies during routing:

ParameterTypeDescription
reliability"best_effort" | "reliable"Delivery guarantee
durability"volatile" | "transient_local"Data persistence
history_depthu32Sample history depth
deadline_usu64Deadline period (microseconds)
lifespan_usu64Sample lifespan (microseconds)

Commands​

Generate Config​

Create an example configuration file:

hdds-router gen-config > hdds-router.toml

Validate Config​

Check configuration file for errors:

hdds-router validate -c hdds-router.toml

Show Status​

Display live routing statistics:

hdds-router status

Output:

Route: sensors-to-control (domain 0 → 1)
  Topics: 5 active
  Messages routed: 12,456
  Bytes routed: 1.2 MB
  Errors: 0
  Uptime: 00:15:32

Route: commands-to-robot (domain 1 → 0)
  Topics: 2 active
  Messages routed: 892
  Bytes routed: 45 KB
  Errors: 0
  Uptime: 00:15:32

Examples​

ROS 2 Domain Bridge​

Bridge ROS 2 traffic between robots on different domains:

# Robot 1 (domain 10) ↔ Robot 2 (domain 20)
hdds-router --from-domain 10 --to-domain 20 --bidirectional \
  --topics "rt/tf,rt/cmd_vel,rt/odom,rt/scan"

Sensor Network Gateway​

Route sensor data with QoS upgrade:

# sensor-gateway.toml
[[routes]]
name = "sensor-gateway"
source_domain = 100  # Sensor network (unreliable WiFi)
target_domain = 0    # Control system (wired)

[routes.topics]
mode = "include"
patterns = ["sensor/*"]

[routes.qos_transform]
reliability = "reliable"
durability = "transient_local"
history_depth = 100
hdds-router -c sensor-gateway.toml

Topic Namespace Migration​

Rename legacy topic namespaces:

hdds-router --from-domain 0 --to-domain 0 \
  --remap "old/sensor/temp:sensor/temperature,old/sensor/hum:sensor/humidity"

Architecture​

Domain 0                       Domain 1
┌─────────────┐               ┌─────────────┐
│  Publisher  │               │  Subscriber │
│  (sensor/t) │               │  (env/temp) │
└──────┬──────┘               └──────▲──────┘
       │                             │
       │    ┌─────────────────┐      │
       └───►│   hdds-router   │──────┘
             │                 │
             │ ┌─────────────┐ │
             │ │  Route      │ │
             │ │  - remap    │ │
             │ │  - qos xform│ │
             │ └─────────────┘ │
             └─────────────────┘

Performance​

  • Latency overhead: < 50 μs per message (excluding network)
  • Throughput: 100,000+ msg/s per route (depending on payload size)
  • Memory: ~10 MB base + ~1 KB per cached sample

Limitations​

  • Same host only: Routes between domains on the same machine
  • No cross-network: For WAN bridging, use Discovery Server instead
  • Type compatibility: Source and destination types must match