Dds Knowledge Patch

Data Distribution Service (DDS) Knowledge Patch

Use this skill when designing, reviewing, debugging, or operating DDS systems, DDSI-RTPS interoperability, open DDS implementations, or ROS 2 RMW data paths. Start with portable DDS semantics, then separate endpoint matching from discovery transport and implementation-specific configuration.

Reference index

Diagnose silence in layers

Do not treat participant discovery as proof that user endpoints can exchange data. Work through these layers in order:

1. Confirm that the intended participants use the intended domain.
2. Confirm SPDP participant visibility and lease health.
3. Confirm SEDP publication and subscription announcements.
4. Confirm that advertised user-data locators are reachable in both directions.
5. Confirm exact topic, type, key, representation, and partition agreement.
6. Check requested/offered QoS compatibility.
7. Check reader state masks and SampleInfo.valid_data.
8. Inspect resource limits, reliable repair, and writer lifetime.

A visible participant with no user match points toward endpoint discovery, advertised addressing, or matching data. A discovered endpoint pair with no delivery points toward QoS, transport reachability, reader selection, resource limits, or lifecycle behavior.

See references/rtps-discovery-and-reliability.md for the SPDP/SEDP boundary and references/implementation-configuration.md for product configuration.

Apply requested/offered QoS directionally

Compatibility compares a reader's request with a writer's offer policy by policy. Keep the direction explicit:

Discovery can still expose an incompatible pair. Inspect requested- and offered-incompatible-QoS status instead of concluding that discovery failed. For the complete matching and endpoint-lifecycle rules, load references/core-data-and-qos.md.

Treat read, take, and lifecycle samples distinctly

• read leaves matching samples in the reader cache and marks them read.
• take removes matching samples from the reader cache.
• Selection combines independent sample, view, and instance state masks.
• Always inspect SampleInfo.valid_data.
• A lifecycle notification may carry metadata without a new valid value.

Do not deserialize or apply a value merely because a sample was returned. Handle invalid-data samples as lifecycle information using the accompanying metadata.

Treat statuses as state, not queued events

Status structures expose cumulative counts plus changes since the relevant status was last accessed. Reading status, taking data, or running a listener may clear a change value or status flag. Do not assume one callback or one queued notification per occurrence.

Listener callbacks normally run on implementation-controlled threads. Keep them short, avoid blocking and application locks, capture only the required information, and hand work to an application-owned executor or queue.

Recreate entities for immutable QoS changes

Topic QoS copied during reader or writer creation is a template, not a live link. Later topic-QoS changes do not automatically update existing endpoints. Check each policy's mutability before changing it; recreate the entity when an immutable policy must change after enablement.

Bound durability and history expectations

TRANSIENT_LOCAL history resides in the originating writer, so it disappears with that writer. Do not expect it to behave like an external durability service. Verify implementation support before depending on TRANSIENT or PERSISTENT.

KEEP_ALL is still constrained by resource limits. With reliable delivery, exhaustion can block writes or prevent slow readers from being served. Size history and resource limits together, and include slow-reader behavior in tests.

Keep coherent access in scope

PRESENTATION chooses INSTANCE, TOPIC, or GROUP access scope separately from coherent and ordered access. Coherent-change brackets may make a write set visible together to a compatible subscriber, but they do not provide database isolation or rollback. Verify implementation support when using group scope.

Use partitions for matching, not authorization

Partitions belong to publishers and subscribers. Their default is one empty string, and matching requires the two string sequences to intersect under DDS expression rules.

For portable matching, put a literal on at least one side; do not assume two wildcard expressions are intersected as regular expressions. Partition QoS is mutable, so a change can add or remove endpoint matches after enablement. Because partitions are discovery-visible metadata, they are not a security boundary.

Read reliable RTPS traffic per writer

An RTPS change is identified by writer GUID and a monotonically increasing writer-local sequence number. Do not derive a global order from sequence numbers or interpret them as wall-clock time.

Use the repair exchange as a diagnostic map:

See references/rtps-discovery-and-reliability.md before interpreting captures.

Keep a portable network path

Shared memory, data sharing, and zero-copy paths are local optimizations with eligibility constraints. They do not replace a mutually supported network transport for remote or cross-implementation peers.

For interoperable deployments, align all of the following:

• IDL type names, keys, and extensibility;
• type-consistency behavior and XCDR representation;
• topic and partition names;
• requested/offered QoS;
• reachable advertised locators; and
• a common network transport.

Generated source APIs may differ without preventing wire interoperability, but wire-level type and matching details must agree.

Configure Cyclone DDS deliberately

CYCLONEDDS_URI selects XML configuration resources. A Domain with Id="any" makes configuration reusable; it does not choose the participant's domain ID.

On multi-homed hosts, containers, VPNs, or asymmetric networks, select and prioritize the intended interface explicitly when automatic selection advertises unreachable addresses. If multicast is disabled, configure reachable unicast peers and preserve bidirectional reachability of the locators learned through discovery.

Check domain/participant-index port mapping, port conflicts, participant-index search limits, and firewalls. Use configuration documentation for the deployed release because unknown or misplaced XML elements can stop startup and defaults can change.

Configure Fast DDS discovery and profiles deliberately

Choose simple discovery, static EDP, Discovery Server, or manual discovery APIs as implementation facilities with distinct behavior. Static EDP requires consistent endpoint IDs and definitions. Discovery Server clients require explicit server configuration and may use redundant servers.

ROS_DISCOVERY_SERVER is an integration facility for Fast DDS with ROS 2, not a portable standalone DDS or cross-implementation setting. Validate a standard simple-discovery path or another explicitly compatible architecture for mixed implementations.

FASTDDS_DEFAULT_PROFILES_FILE selects the default XML profile file. SKIP_DEFAULT_XML can disable default loading where the deployed release supports it. Profile names are local identifiers, not remote topic or partition names; verify file, default-name, and programmatic-loading precedence for the deployed version.

Keep Connext bindings and profile identity aligned

Do not mix modern C++ and classic C++ examples or entity-creation APIs. Match code to the installed release and language binding.

For repeatable XML QoS, record the loaded file list, library/profile identity, base-profile inheritance, defaults, and programmatic overrides. Keep UDP or another interoperable network path enabled when local shared memory is active.

Handle optional ROS 2 RMW behavior

SYSTEM_DEFAULT delegates a QoS policy to the selected RMW or DDS vendor. BEST_AVAILABLE, where supported, derives values from discovered endpoints. Choose explicit profiles when behavior must remain stable across RMW implementations.

Loaned messages, zero-copy/shared-memory paths, content filters, and unique network-flow requirements are optional capabilities. Query support, handle an unsupported result, and do not assume that changing RMW implementations preserves vendor-specific acceleration.

See references/ros2-rmw.md for the portable decision rules.