3. Configuration¶

DDS Replayer Configuration

3.1. DDS Replayer Configuration¶

A DDS Replayer is configured by a .yaml configuration file. This .yaml file contains all the information regarding the DDS interface configuration, playback parameters, and DDS Replayer specifications. Thus, this file has four major configuration groups:

dds: configuration related to DDS communication.
replayer: configuration with data playback parameters.
specs: configuration of the internal operation of the DDS Replayer.

3.1.1. DDS Configuration¶

Configuration related to DDS communication.

3.1.1.1. Topic Filtering¶

As seen in DDS Recorder topic filtering, a user can define a set of rules to only record DDS Topics of interest.

In addition to the filters applied to DDS Recorder when recording, DDS Replayer also allows filtering of DDS Topics. That is, it allows to define the DDS Topics’ data that is going to be replayed by the application. This way, it is possible to define a set of rules in DDS Replayer to filter those data samples the user does not wish to replay.

It is not mandatory to define such set of rules in the configuration file. In this case, a DDS Replayer will publish all data stored in the provided input MCAP file.

To define these data filtering rules based on the Topics to which they belong, the following lists are available:

Allowed topics list (allowlist)
Block topics list (blocklist)

These lists of topics stated above are defined by a tag in the YAML configuration file, which defines a YAML vector ([]). This vector contains the list of topics for each filtering rule. Each Topic is determined by its entries name and type, with only the first one being mandatory.

Topic entries	Data type	Default value
`name`	`string`	-
`type`	`string`	`"*"`

See Topic section for further information about the topic.

Note

Placing quotation marks around values in a YAML file is generally optional. However, values containing wildcard characters must be enclosed by single or double quotation marks.

3.1.1.1.1. Allow topic list¶

This is the list of topics that DDS Replayer will replay, i.e. only recorded data under the topics matching the expressions in the allowlist will be published by DDS Replayer.

Note

If no allowlist is provided, data will be replayed for all topics (unless filtered out in blocklist).

3.1.1.1.2. Block topic list¶

This is the list of topics that the DDS Replayer will block, that is, all input data under the topics matching the filters specified in the blocklist will be discarded by the DDS Replayer and therefore will not be published.

This list takes precedence over the allowlist. If a topic matches an expression both in the allowlist and in the blocklist, the blocklist takes precedence, causing the data under this topic to be discarded.

Example of usage - Allowlist and blocklist collision:

In the following example, the HelloWorldTopic topic is both in the allowlist and (implicitly) in the blocklist, so according to the blocklist preference rule this topic is blocked. Moreover, only the topics present in the allowlist are relayed, regardless of whether more topics are dynamically discovered in the DDS network. In this case the forwarded topics are AllowedTopic1 with data type Allowed and AllowedTopic2 regardless of its data type.
allowlist:
  - name: AllowedTopic1
    type: Allowed
  - name: AllowedTopic2
    type: "*"
  - name: HelloWorldTopic
    type: HelloWorld

blocklist:
  - name: "*"
    type: HelloWorld

3.1.1.2. Built-in Topics¶

As seen in Topic Filtering, a DDS Recorder uses the QoS of the first Publisher/Subscriber found in every recorded topic, unless manually defined in the built-in topics list. This QoS information is stored in the MCAP file along with the user data, and thus a DDS Replayer instance is able to publish recorded data preserving the original QoS.

However, the user has the option to manually set the QoS of any topic to be played back through the replayer’s builtin-topics list. The builtin-topics list is defined in the same form as the allowlist and blocklist.

This feature also allows to manually force the QoS of a specific topic, so the entities created in such topic follows the specified QoS and not the one first discovered.

3.1.1.2.1. Topic Quality of Service¶

For every topic contained in this list, both name and type must be specified and contain no wildcard characters. Apart from these values, the tag qos under each topic allows to configure the following values:

Quality of Service	Yaml tag	Data type	Default value	QoS set
Reliability	`reliability`	bool	`false`	`RELIABLE` / `BEST_EFFORT`
Durability	`durability`	bool	`false`	`TRANSIENT_LOCAL` / `VOLATILE`
Partitions	`partitions`	bool	`false`	Topic with / without partitions
Ownership	`ownership`	bool	`false`	`EXCLUSIVE_OWNERSHIP_QOS` / `SHARED_OWNERSHIP_QOS`
Key	`keyed`	bool	`false`	Topic with / without key

Example of usage:

builtin-topics:
  - name: HelloWorldTopic
    type: HelloWorld
    qos:
      reliability: true       # Use QoS RELIABLE
      durability: true        # Use QoS TRANSIENT_LOCAL
      partitions: true        # Topic with partitions
      ownership: false        # Use QoS SHARED_OWNERSHIP_QOS
      keyed: true             # Topic with key

3.1.1.3. DDS Domain¶

Tag domain configures the Domain Id.

domain: 101

3.1.1.4. Ignore Participant Flags¶

A set of discovery traffic filters can be defined in order to add an extra level of isolation. This configuration option can be set through the ignore-participant-flags tag:

ignore-participant-flags: no_filter                          # No filter (default)
# or
ignore-participant-flags: filter_different_host              # Discovery traffic from another host is discarded
# or
ignore-participant-flags: filter_different_process           # Discovery traffic from another process on same host is discarded
# or
ignore-participant-flags: filter_same_process                # Discovery traffic from own process is discarded
# or
ignore-participant-flags: filter_different_and_same_process  # Discovery traffic from own host is discarded

See Ignore Participant Flags for more information.

3.1.1.5. Custom Transport Descriptors¶

By default, DDS Replayer internal participants are created with enabled UDP and Shared Memory transport descriptors. The use of one or the other for communication will depend on the specific scenario, and whenever both are viable candidates, the most efficient one (Shared Memory Transport) is automatically selected. However, a user may desire to force the use of one of the two, which can be accomplished via the transport configuration tag.

transport: builtin    # UDP & SHM (default)
# or
transport: udp        # UDP only
# or
transport: shm        # SHM only

Warning

When configured with transport: shm, DDS Replayer will only communicate with applications using Shared Memory Transport exclusively (with disabled UDP transport).

3.1.1.6. Interface Whitelist¶

Optional tag whitelist-interfaces allows to limit the network interfaces used by UDP and TCP transport. This may be useful to only allow communication within the host (note: same can be done with Ignore Participant Flags). Example:

whitelist-interfaces:
  - "127.0.0.1"    # Localhost only

See Interface Whitelist for more information.

Warning

When providing an interface whitelist, external participants with which communication is desired must also be configured with interface whitelisting.

3.1.2. Replay Configuration¶

Configuration of data playback settings.

3.1.2.1. Input File¶

The path to the file, set through the input-file configuration tag. When the input file is specified both through CLI argument and YAML configuration file, the former takes precedence.

3.1.2.2. Begin Time¶

By default, all data stored in the provided MCAP file is played back. However, a user might be interested in only replaying data relative to a specific time frame. begin-time and end-time configuration options can be leveraged for this purpose, and their format is as follows:

Parameter	Tag	Description	Data type	Default value
Use local time zone	`local`	Whether to interpret the provided datetime as local (`true`) or as a Greenwich Mean Time (GMT/UTC +0) without Daylight Saving Time (DST) considerations (`false`).	`bool`	`true`
Datetime Format	`format`	Format followed by the provided datetime.	`string`	`"%Y-%m-%d_%H-%M-%S"`
Datetime	`datetime`	Datetime (seconds precision).	`string`
Milliseconds	`milliseconds`	Milliseconds.	`integer`	`0`
Microseconds	`microseconds`	Microseconds.	`integer`	`0`
Nanoseconds	`nanoseconds`	Nanoseconds.	`integer`	`0`

Messages recorded/sent (see Log Publish Time) before begin-time will not be played back by a DDS Replayer instance.

3.1.2.3. End Time¶

As with begin-time, a user can discard messages recorded/sent after a specific timepoint set through the end-time tag, which follows the format described in Begin Time.

3.1.2.4. Start Replay Time¶

This configuration option (start-replay-time) allows to start replaying data at a certain timepoint following the format described in Begin Time. If the provided timepoint already expired, the replayer starts publishing messages right away.

3.1.2.5. Playback Rate¶

By default, data is replayed at the same rate it was published/received. However, a user might be interested in playing messages back at a rate different than the original one. This can be accomplished through the playback rate tag, which accepts positive float values (e.g. 0.5 <–> half speed || 2 <–> double speed).

3.1.2.6. Replay Types¶

By default, a DDS Replayer instance automatically sends all type information found in the provided MCAP file, which might be required for applications relying on Dynamic Types. Nonetheless, a user can choose to avoid this by setting replay-types: false, so only data samples are sent while their associated type information is disregarded.

3.1.3. Specs Configuration¶

The internals of a DDS Replayer can be configured using the specs optional tag that contains certain options related with the overall configuration of the DDS Replayer instance to run. The values available to configure are:

3.1.3.1. Number of Threads¶

specs supports a threads optional value that allows the user to set a maximum number of threads for the internal ThreadPool. This ThreadPool allows to limit the number of threads spawned by the application. This improves the performance of the internal data communications.

This value should be set by each user depending on each system characteristics. In case this value is not set, the default number of threads used is 12.

3.1.3.2. Wait-for-acknowledgement Timeout¶

The execution of a DDS Replayer instance ends when the last message contained in the provided input file is published (or the user manually aborts the process, see Closing Replay Application). Note that this last message might be lost after publication, and if reliable Reliability QoS is being used, a mechanism should be established to avoid this problematic situation. For this purpose, the user can specify the maximum amount of milliseconds (wait-all-acked-timeout) to wait on closure until published messages are acknowledged by matched readers. Its value is set to 0 by default (no wait).

3.1.4. General Example¶

A complete example of all the configurations described on this page can be found below.

Warning

This example can be used as a quick reference, but it may not be correct due to incompatibility or exclusive properties. Do not take it as a working example.

dds:
  domain: 0

  allowlist:
    - name: "topic_name"
      type: "topic_type"

  blocklist:
    - name: "topic_name"
      type: "topic_type"

  builtin-topics:
    - name: "HelloWorldTopic"
      type: "HelloWorld"
      qos:
        reliability: true
        durability: true
        keyed: false
        partitions: true
        ownership: false

  ignore-participant-flags: no_filter
  transport: builtin
  whitelist-interfaces:
    - "127.0.0.1"

replayer:
  input-file: my_input.mcap

  begin-time:
    local: true
    datetime: 2023-04-10_10-37-50
    milliseconds: 100
    nanoseconds: 50

  end-time:
    format: "%H-%M-%S_%Y-%m-%d"
    local: true
    datetime: 10-39-11_2023-04-10
    milliseconds: 200

  start-replay-time:
    local: true
    datetime: 2023-04-12_12-00-00
    milliseconds: 500

  rate: 1.4
  replay-types: true

specs:
  threads: 8
  wait-all-acked-timeout: 10