hdds-topic-echo

Echo DDS topic messages in real-time - like rostopic echo for DDS/RTPS.

Overview

hdds-topic-echo subscribes to a DDS topic and prints incoming messages to the terminal. It automatically detects and decodes common data types (strings, integers, floats) and supports multiple output formats.

Installation

From Source

cd hdds/tools/hdds-topic-echo
cargo build --release

Binary at target/release/hdds-topic-echo.

From Cargo

cargo install hdds-topic-echo

Usage

hdds-topic-echo [OPTIONS] <TOPIC>

Arguments:
  <TOPIC>  Topic name to subscribe to

Options:
  -d, --domain <DOMAIN>  DDS domain ID [default: 0]
  -f, --format <FORMAT>  Output format: pretty, json, compact, raw [default: pretty]
      --json             Shortcut for --format json
      --raw              Shortcut for --format raw
  -n, --count <COUNT>    Maximum samples to receive (0 = unlimited) [default: 0]
  -v, --verbose          Show metadata (sequence, timestamps)
  -q, --qos <QOS>        QoS: best-effort, reliable [default: reliable]
      --no-color         Disable colored output
      --quiet            Only output data, no headers
  -h, --help             Print help
  -V, --version          Print version

Examples

Basic Echo

hdds-topic-echo temperature

Output:

>>> Subscribing to temperature (domain=0, qos=Reliable, format=Pretty)
Press Ctrl+C to stop

[2026-01-07 10:30:45.123] #1 (12 bytes)
  string: "23.5"

[2026-01-07 10:30:46.125] #2 (12 bytes)
  string: "24.1"

JSON Output (Pipe-Friendly)

hdds-topic-echo temperature --json | jq .

Output:

{"seq":1,"payload":"BQAAADIzLjUA"}
{"seq":2,"payload":"BQAAADI0LjEA"}

With verbose:

hdds-topic-echo temperature --json -v

{"seq":1,"len":12,"timestamp":1704617445.123456,"payload":"BQAAADIzLjUA"}

Limited Sample Count

Receive 10 samples then exit:

hdds-topic-echo temperature -n 10

Hex Dump (Raw Format)

hdds-topic-echo temperature --raw -v

Output:

[2026-01-07 10:30:45.123] #1 (12 bytes)
  0000  00 01 00 00 05 00 00 00  32 33 2e 35 00 00 00 00  |....23.5....|

Compact Format

One line per sample:

hdds-topic-echo temperature -f compact

Output:

#1: 0001000005000000323335... (12 bytes)
#2: 0001000005000000323431... (12 bytes)

Different Domain

hdds-topic-echo sensor_data -d 42

Best-Effort QoS

For high-frequency topics where some loss is acceptable:

hdds-topic-echo video_frames -q best-effort

Quiet Mode

Only data, no headers (useful in scripts):

hdds-topic-echo temperature --quiet --json > output.jsonl

Disable Colors

For logging or piping:

hdds-topic-echo temperature --no-color

Output Formats

Format	Description	Use Case
pretty	Human-readable with colors	Interactive debugging
json	One JSON object per line	Piping to jq, log parsing
compact	One-line hex preview	Quick overview
raw	Full hex dump	Binary analysis

Auto-Detection

The tool automatically detects and decodes:

Type	Detection	Display
CDR String	4-byte length + ASCII chars	string: "value"
int32	4 bytes	i32: 12345 | f32: 0.0001
int64/float64	8 bytes	i64: 123456789 | f64: 3.141593
Unknown	Any size	bytes: 00 01 02 03 ...

CDR encapsulation header (4 bytes) is automatically skipped.

Exit Codes

Code	Meaning
0	Success (Ctrl+C or count reached)
1	Error (topic not found, DDS error)

Integration Examples

Monitor and Alert

hdds-topic-echo alerts --json | while read line; do
  echo "$line" | jq -r '.payload' | base64 -d
done

Log to File with Timestamps

hdds-topic-echo sensor_data --json -v >> sensor_log.jsonl

Count Messages per Second

hdds-topic-echo high_freq_topic --quiet -f compact | pv -l > /dev/null

Filter with jq

hdds-topic-echo data --json | jq 'select(.seq > 100)'

Comparison with rostopic echo

Feature	hdds-topic-echo	rostopic echo
Protocol	RTPS/DDS	ROS 1 TCPROS
Type info needed	No (raw mode)	Yes (msg definition)
Output formats	4 (pretty/json/compact/raw)	1
JSON output	Built-in	Requires bridge
Sample limit	-n flag	Not built-in
Cross-platform	Yes	ROS required

Troubleshooting

No Messages Received

1. Check topic name spelling
2. Verify domain ID matches publisher
3. Try --qos best-effort if publisher is best-effort
4. Check network/firewall (multicast must be enabled)

Garbled Output

• Data may be in a complex type - use --raw to see hex
• CDR encapsulation might differ - check first 4 bytes

High CPU Usage

For very high frequency topics:

• Use --quiet to reduce output overhead
• Pipe to file instead of terminal
• Consider --qos best-effort to reduce ACK traffic