cddsctl (Cyclone DDS Control) is a zero-config DDS CLI tool for topic discovery, real-time data inspection, and traffic recording — a ros2 topic / ros2 bag alternative that requires no ROS dependency. Built on CycloneDDS with XTypes introspection and iceoryx shared-memory support, it ships as a single statically-linked binary and writes recordings in the MCAP format.

中文文档

$ cddsctl --help

    _____ _____  _____   _____  _____ _______ _
   / ____|  __ \|  __ \ / ____|/ ____|__   __| |
  | |    | |  | | |  | | (___ | |       | |  | |
  | |    | |  | | |  | |\___ \| |       | |  | |
  | |____| |__| | |__| |____) | |____   | |  | |____
   \_____|_____/|_____/|_____/ \_____|  |_|  |______|

  ╔══════════════════════════════════════════╗
  ║   Cyclone DDS Command Line Tool          ║
  ╚══════════════════════════════════════════╝

  Version: 1.0.0 (with SHM)

  Usage: cddsctl <command> [options]

  Commands:
    hz        Display publishing frequency of a DDS topic
    info      Show information about a DDS topic
    list      List available DDS topics
    echo      Print messages from a DDS topic
    record    Record DDS topics to MCAP file
    ps        Show DDS participants and applications

  Run 'cddsctl <command> --help' for more information.

Core Features:

• list: List discovered topics in DDS network
• echo: Print messages from a topic in real-time (YAML/JSON format)
• hz: Display topic publishing frequency (like rostopic hz)
• record: Record topics to MCAP files
• XTypes introspection: Auto-discover types without IDL compilation
• Shared memory: Zero-copy via iceoryx (automatic fallback to UDP)
• Complex types: Nested structs, arrays, sequences, unions, enums

• Native DDS (no ROS required)
• Built for CycloneDDS
• Unified CLI experience: list / echo / record
• Recording format: MCAP (easy playback, analysis, and visualization)
• Fully static linked binary (easy deployment)
• Ideal for debugging, integration testing, data collection, and issue reproduction

• Robotics DDS debugging without ROS — inspect and echo topics on any CycloneDDS network
• Recording DDS traffic for offline analysis — capture to MCAP, visualize in Foxglove Studio
• Integration testing with DDS data capture — record topic streams during CI or manual test runs
• Headless / embedded deployment — single static binary, no runtime dependencies

Download pre-built binary from Releases:

tar -xzf cddsctl-*-linux-x86_64.tar.gz
sudo mv cddsctl-*/bin/cddsctl /usr/local/bin/
cddsctl --help

The release binary is built with CycloneDDS 0.10.2 and iceoryx 2.0.5. Shared memory transport is used automatically when a compatible RouDi (iceoryx 2.0.5) daemon is running; otherwise it falls back to UDP network transport.

Install system dependencies:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y cmake g++ ninja-build git libacl1-dev

# RHEL/CentOS/Fedora
sudo yum install -y cmake gcc-c++ ninja-build git libacl-devel

# Arch Linux
sudo pacman -S cmake gcc ninja git acl

git clone https://github.com/int0x7/cddsctl.git
cd cddsctl
./build.sh

The build script will automatically:

• Download and compile dependencies (yaml-cpp, iceoryx, CycloneDDS) as static libraries
• Build cddsctl with all dependencies statically linked

Build options:

./build.sh -t          # Build and run tests
./build.sh -c          # Clean build
./build.sh --clean-deps # Rebuild all dependencies
./build.sh -h          # Show help

After building, the binary will be available:

./build/cli/cddsctl

cddsctl requires CycloneDDS 0.10.1+ due to its dependency on the dds_typeinfo_t API for XTypes introspection.

List DDS topics:

cddsctl list

Print topic data:

cddsctl echo /test/sensor

Record topic to MCAP:

cddsctl record /test/sensor -o log.mcap

Record multiple topics:

cddsctl record MotorState IMU CameraImage -o run.mcap

Monitor topic frequency:

cddsctl hz /test/sensor

Monitor multiple topic frequencies:

cddsctl hz /rt/imu_state /rt/joy

List discovered topics in DDS network.

cddsctl list

Example output:

MotorState
MotorCommand
IMU
CameraImage

Print messages from a topic in real-time. Output format is YAML (similar to rostopic echo).

cddsctl echo <topic> [options]

Options:

• -n, --count=N: Exit after printing N messages
• -d, --domain=ID: DDS domain ID (default: 0)
• -t, --timeout=SEC: Topic discovery timeout in seconds (default: 2.0)
• -F, --format=FMT: Output format: yaml, json (default: yaml)
• --no-timestamp: Don't show timestamps

Example:

cddsctl echo /test/sensor -n 5

Example output:

---
[1772686402.862456386]
id: 21
timestamp: 2.102516088
values:
  - 0.861936
  - -0.507016
  - 0.21
name: sensor_1

Nested structures and unions are fully supported:

---
[1772968360.232262]
timestamp_sec: 1772968360
base_pose:
  position:
    x: 0.198669
    y: 0.980066
    z: 0
  orientation:
    x: 0
    y: 0
    z: 0.099833
    w: 0.995004
result:
  _d: 0
  success: true

JSON format (-F json):

{
  "base_pose": {
    "position": { "x": 0.198669, "y": 0.980066, "z": 0 },
    "orientation": { "x": 0, "y": 0, "z": 0.099833, "w": 0.995004 }
  },
  "overall_status": "STATUS_OK"
}

Display publishing frequency of DDS topics (similar to rostopic hz).

cddsctl hz <topic...> [options]

Options:

• -d, --domain=ID: DDS domain ID (default: 0)
• -w, --window=N: Window size for rate calculation (default: 100)
• -t, --timeout=SEC: Topic discovery timeout in seconds (default: 2.0)

Example - single topic:

cddsctl hz /test/sensor

Example output:

subscribed to [/test/sensor]
average rate: 59.987 Hz
    min: 59.823 Hz
    max: 60.156 Hz
    std dev: 0.092 Hz
    window: 100

Example - multiple topics:

cddsctl hz /rt/imu_state /rt/joy

Example output:

subscribed to [/rt/imu_state]
subscribed to [/rt/joy]
[/rt/imu_state]
average rate: 498.738 Hz
    min: 411.489 Hz
    max: 580.234 Hz
    std dev: 25.153 Hz
    window: 100
[/rt/joy]
average rate: 60.001 Hz
    min: 59.768 Hz
    max: 60.192 Hz
    std dev: 0.085 Hz
    window: 100
---

Record topics to MCAP file.

cddsctl record <topic...> -o <file.mcap>

Example:

cddsctl record MotorState -o motor.mcap

The repository includes comprehensive IDL examples for testing:

Run examples:

# Terminal 1: Start publisher
./build/examples/nested_struct_publisher --topic /robot/state

# Terminal 2: Echo with YAML format
./build/cli/cddsctl echo /robot/state -n 10

# Terminal 2: Echo with JSON format
./build/cli/cddsctl echo /robot/state -n 10 --format json

• CycloneDDS — the DDS implementation cddsctl is built on
• iceoryx — zero-copy shared-memory transport
• MCAP — open-source recording format used by cddsctl
• Foxglove Studio — visualize and replay MCAP files

Apache License 2.0