Skip to content

Latest commit

 

History

History
446 lines (320 loc) · 15 KB

configuration.rst

File metadata and controls

446 lines (320 loc) · 15 KB
Raw

Configuration

A instance can be configured by a YAML configuration file. In order to retrieve a configuration file to a , use user_manual_user_interface_configuration_file_argument.

DDS Configurations

The YAML Configuration supports a dds optional tag that contains certain DDS configurations. The values available to configure are:

Topic Filtering

The automatically detects the topics that are being used in a DDS Network. The then creates internal DDS Readers<DataReader> for each topic to process the data published. The allows filtering DDS Topics<Topic>, that is, it allows users to configure the DDS Topics<Topic> to process. These data filtering rules can be configured under the allowlist and blocklist tags. If the allowlist and blocklist are not configured, the will process all the data published on the topics it discovers. If both the allowlist and blocklist are configured and a topic appears in both of them, the blocklist has priority and the topic will be blocked.

Topics are determined by the tags name (required) and type, both of which accept wildcard characters.

Note

Placing quotation marks around values in a YAML file is generally optional, but values containing wildcard characters do require single or double quotation marks.

Consider the following example:

allowlist:
  - name: AllowedTopic1
    type: Allowed

  - name: AllowedTopic2
    type: "*"

  - name: HelloWorldTopic
    type: HelloWorld

blocklist:
  - name: "*"
    type: HelloWorld

In this example, the data in the topic AllowedTopic1 with type Allowed and the data in the topic AllowedTopic2 with any type will be processed by the . The data in the topic HelloWorldTopic with type HelloWorld will be blocked, since the blocklist is blocking all topics with any name and with type HelloWorld.

Topic QoS

The following is the set of QoS that are configurable for a topic. For more information on topics, please read the Fast DDS Topic section.

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
Ownership ownership bool false EXCLUSIVE_OWNERSHIP_QOS / SHARED_OWNERSHIP_QOS
Partitions partitions bool false Topic with / without partitions
Key keyed bool false Topic with / without key
History Depth history-depth unsigned integer 5000 user_manual_configuration_dds__history_depth
Max Reception Rate max-rx-rate float 0 (unlimited) user_manual_configuration_dds__max_rx_rate
Downsampling downsampling unsigned integer 1 user_manual_configuration_dds__downsampling

Warning

Manually configuring TRANSIENT_LOCAL durability may lead to incompatibility issues when the discovered reliability is BEST_EFFORT. Please ensure to always configure the reliability when configuring the durability to avoid the issue.

History Depth

The history-depth tag configures the history depth of the Fast DDS internal entities. By default, the depth of every RTPS History instance is 5000. Its value should be decreased when the sample size and/or number of created endpoints (increasing with the number of topics) are big enough to cause memory exhaustion issues.

Max Reception Rate

The max-rx-rate tag limits the frequency [Hz] at which samples are processed by discarding messages received before 1/max-rx-rate seconds have passed since the last processed message. It only accepts non-negative numbers. By default it is set to 0; it processes samples at an unlimited reception rate.

Downsampling

The downsampling tag reduces the sampling rate of the received data by only keeping 1 out of every n samples received (per topic), where n is the value specified under the downsampling tag. When the max-rx-rate tag is also set, downsampling only applies to messages that have passed the max-rx-rate filter. It only accepts positive integers. By default it is set to 1; it accepts every message.

Manual Topics

A subset of Topic QoS <user_manual_configuration_dds__topic_qos> can be manually configured for a specific topic under the tag topics. The tag topics has a required name tag that accepts wildcard characters. It also has two optional tags: a type tag that accepts wildcard characters and a qos tag with the Topic QoS <user_manual_configuration_dds__topic_qos> that the user wants to manually configure. If a qos is not manually configured, it will get its value by discovery.

topics:
  - name: "temperature/*"
    type: "temperature/types/*"
    qos:
      max-tx-rate: 15
      downsampling: 2

Note

The Topic QoS <user_manual_configuration_dds__topic_qos> configured in the Manual Topics take precedence over the Specs Topic QoS <user_manual_configuration_specs_topic_qos>.

DDS Domain Id

In order to execute a instance in a Domain Id different than the default (0) use tag domain.

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.

Custom Transport Descriptors

By default, 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, will only communicate with applications using Shared Memory Transport exclusively (with disabled UDP transport).

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 user_manual_configuration_dds_ignore_participant_flags). Example:

whitelist-interfaces:
  - "127.0.0.1"    # Localhost only

See Interface Whitelist for more information.

Topic type format

The optional ros2-types tag enables specification of the format for displaying schemas. When set to true, schemas are displayed in ROS 2 message format (.msg). If set to false, schemas are displayed in OMG IDL format (.idl).

Specs Configurations

The YAML Configuration supports a specs optional tag that contains certain options related with the overall configuration of the application. The values available to configure are:

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 data transmission between participants.

This value should be set by each user depending on each system characteristics. By default, this value is 12.

Discovery Time

specs supports a discovery-time optional value that allows the user to set the time (in milliseconds) before a user_manual_user_interface_one_shot retrieves the output and closes. This parameter is useful for very big networks, as may not discover the whole network fast enough to return a complete information. By default, this value is 1000 (1 second).

QoS

specs supports a qos optional tag to configure the default values of the Topic QoS <user_manual_configuration_dds__topic_qos>.

Note

The Topic QoS <user_manual_configuration_dds__topic_qos> configured in specs can be overwritten by the Manual Topics <user_manual_configuration_dds__manual_topics>.

Logging

specs supports a logging optional tag to configure the logs. Under the logging tag, users can configure the type of logs to display and filter the logs based on their content and category. When configuring the verbosity to info, all types of logs, including informational messages, warnings, and errors, will be displayed. Conversely, setting it to warning will only show warnings and errors, while choosing error will exclusively display errors. By default, the filter allows all errors to be displayed, while selectively permitting warning and informational messages from FASTDDSSPY category.

Note

Configuring the logs via the Command-Line is still active and takes precedence over YAML configuration when both methods are used simultaneously.

Logging Yaml tag Description Data type Default value Possible values
Verbosity verbosity Show messages of equal or higher importance. enum error info / warning / error
Filter filter Regex to filter the category or message of the logs. string info : FASTDDSSPY warning : FASTDDSSPY error : "" Regex string

Note

For the logs to function properly, the -DLOG_INFO=ON compilation flag is required.

The prints the logs by default (warnings and errors in the standard error and infos in the standard output). The , however, can also publish the logs in a DDS topic. To publish the logs, under the tag publish, set enable: true and set a domain and a topic-name. The type of the logs published is defined as follows:

LogEntry.idl

const long UNDEFINED = 0x10000000;
const long SAMPLE_LOST = 0x10000001;
const long TOPIC_MISMATCH_TYPE = 0x10000002;
const long TOPIC_MISMATCH_QOS = 0x10000003;

enum Kind {
  Info,
  Warning,
  Error
};

struct LogEntry {
  @key long event;
  Kind kind;
  string category;
  string message;
  string timestamp;
};

Note

The type of the logs can be published by setting publish-type: true.

Example of usage

logging:
  verbosity: info
  filter:
    error: "DDSPIPE|FASTDDSSPY"
    warning: "DDSPIPE|FASTDDSSPY"
    info: "FASTDDSSPY"
  publish:
    enable: true
    domain: 84
    topic-name: "FastDdsSpyLogs"
    publish-type: false
  stdout: true

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"

  topics:
    - name: "temperature/*"
      type: "temperature/types/*"
      qos:
        max-rx-rate: 5
        downsampling: 1

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

  ros2-types: false

specs:
  threads: 12
  discovery-time: 1000

  qos:
    history-depth: 5000
    max-rx-rate: 10
    downsampling: 2

  logging:
    verbosity: warning
    filter:
      error: ""
      warning: "FASTDDSSPY"
      info: "FASTDDSSPY"
    publish:
      enable: true
      domain: 0
      topic-name: "FastDdsSpyLogs"
      publish-type: false
    stdout: true