【FastDDS】Environment variables

最新推荐文章于 2025-12-07 20:37:01 发布

原创最新推荐文章于 2025-12-07 20:37:01 发布 · 903 阅读

13 ·

CC 4.0 BY-SA版权

文章标签：

#DDS #自动驾驶 #FastDDS #中间件

9. 记录收藏专栏收录该内容

68 篇文章

订阅专栏

11. 环境变量

以下是会影响Fast DDS行为的环境变量列表：

11.1. `FASTDDS_DEFAULT_PROFILES_FILE`

定义默认配置文件XML文件的位置。如果设置了此变量且其值对应一个现有文件，Fast DDS将加载该文件中的配置文件。有关XML配置文件的更多信息，请参考XML配置文件。

Linux

export FASTDDS_DEFAULT_PROFILES_FILE=/home/user/profiles.xml

Windows

set FASTDDS_DEFAULT_PROFILES_FILE=C:\profiles.xml

11.2. `SKIP_DEFAULT_XML`

跳过查找默认配置文件XML文件。如果此变量设置为1，Fast DDS将直接从类定义中加载配置参数，而不会在工作目录中查找DEFAULT_FASTDDS_PROFILES.xml。有关XML配置文件的更多信息，请参考XML配置文件。

Linux
```
export SKIP_DEFAULT_XML=1
```
Windows
```
set SKIP_DEFAULT_XML=1
```

11.3. `FASTDDS_BUILTIN_TRANSPORTS`

设置此变量可以修改在创建DomainParticipant期间初始化的内置传输。这是一种更改传输层默认配置的简单方法，它直接影响DDS实体之间的通信方式。

下面列出了所有现有值及其简要描述：

内置传输选项	描述
`NONE`	不会实例化任何传输。因此，用户必须手动添加所需的传输。否则，参与者创建将失败。
`DEFAULT`	将实例化UDPv4和SHM传输。SHM传输的优先级高于UDPv4传输。这意味着在可能的情况下，将始终使用SHM。
`DEFAULTv6`	将实例化UDPv6和SHM传输。SHM传输的优先级高于UDPv4传输。这意味着在可能的情况下，将始终使用SHM。
`SHM`	仅实例化SHM传输。
`UDPv4`	仅实例化UDPv4传输。
`UDPv6`	仅实例化UDPv6传输。
`LARGE_DATA`	将实例化UDPv4、TCPv4和SHM传输。但是，UDP仅在参与者发现阶段用于多播通知（参见发现阶段），而参与者活跃度和应用程序数据交付则通过TCP或SHM进行。此配置在处理大数据时非常有用（参见大数据模式和基于TCP的Fast DDS）。

注意
仅当use_builtin_transports设置为TRUE时，才会使用此环境变量。在其他任何情况下，该环境变量都无效。

注意
TCPv4传输使用以下配置初始化：
calculate_crc、check_crc和apply_security设置为false。
enable_tcp_nodelay设置为true。
keep_alive_thread和accept_thread使用默认配置。

11.3.1. 配置内置传输选项

Fast DDS提供了一种简单的方法，通过环境变量配置每个内置传输的三个主要参数。但是，此功能在使用LARGE_DATA内置传输选项时特别有价值。LARGE_DATA模式旨在提高处理大数据时的性能。但是，根据每个特定的用例，用户可能希望配置多个选项以更好地满足其需求。此模式还可以使用tcp_negotiation_timeout参数进行配置：

内置传输选项	描述	类型
`max_msg_size`	确定将在传输层中指定的最大消息大小。选择足够大的消息大小以容纳最大的数据消息，将防止分片，这可以显著提高整体发送速率。	uint32_t
`sockets_size`	确定发送和接收套接字缓冲区的大小。为了有效，此参数需要大于或等于指定的最大消息大小。	uint32_t
`non_blocking`	确定是否使用非阻塞发送调用。激活后，如果套接字缓冲区已满，传输将丢弃消息。	bool
`tcp_negotiation_timeout`	确定等待逻辑端口协商的时间。仅在使用`LARGE_DATA`模式时有效。它仅接受毫秒。	uint32_t

环境变量接受多种单位来指定参数的值。此外，小写和大写字母均有效。以下列表显示了可用的单位及其相应的符号：

B：字节。这是默认单位，因此无需指定。
KB：千字节。
MB：兆字节。
GB：千兆字节。
KIB：千比字节。
MIB：兆比字节。
GIB：千兆比字节。

export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA?max_msg_size=200KB&sockets_size=1MB&non_blocking=true&tcp_negotiation_timeout=50

注意
使用LARGE_DATA时，建议将max_msg_size和sockets_size设置为足够大的值以容纳最大的数据消息，并将non_blocking设置为TRUE。请注意，在消息大小较小（存在分片）的情况下激活non_blocking选项可能会导致消息丢弃率增加并产生不良结果。有关更多信息，请参考具有配置选项的大数据。

警告
只有使用LARGE_DATA内置传输选项时，才能将max_msg_size设置为高于65500 KB。尝试与任何其他内置传输一起设置它将导致错误，并且参与者的创建将失败。

11.4. `ROS_DISCOVERY_SERVER`

警告
仅当发现协议设置为SIMPLE、SERVER或BACKUP时，才会使用此环境变量。在其他任何情况下，该环境变量都无效。

设置此变量可将DomainParticipant配置为使用发现服务器发现机制连接到一个或多个服务器。

如果定义了ROS_DISCOVERY_SERVER，并且DomainParticipant的发现协议设置为SIMPLE，则Fast DDS将改为将其配置为给定服务器的CLIENT。

如果定义了ROS_DISCOVERY_SERVER，并且DomainParticipant的发现协议设置为SERVER或BACKUP，则该变量用于将远程服务器添加到给定的服务器，分别将发现协议保留为SERVER或BACKUP。

变量的值必须以以下形式列出服务器的定位器：

类似192.168.2.23的IPv4地址。默认使用UDP协议。可以使用:附加UDP端口，如192.168.2.23:35665。
遵循RFC3513地址约定的IPv6地址，如1080::8:800:200C:417A。同样，默认使用UDP协议。可以像[1080::8:800:200C:417A]:35665那样附加UDP端口。请注意使用方括号以避免歧义。
TCPv4说明符+ IPv4地址，如TCPv4:[127.0.0.1]。TCP协议用于与服务器通信。可以使用:附加TCP端口，如TCPv4:[127.0.0.1]:42100。
TCPv6说明符+ IPv6地址，如TCPv6:[::1]。TCP协议用于与服务器通信。可以使用:附加TCP端口，如TCPv6:[::1]:42100。
可以指定DNS名称。此名称将用于查询已知主机和可用的DNS服务器，以尝试解析有效的IP地址。几种格式都是可接受的：
- 纯域名：eprosima.com。这将包括所有可用的IP地址。
- 域名+端口：eprosima.com:35665。如上，但使用特定端口。
- UDPv4说明符+域名：UDPv4:[eprosima.com]。将仅使用解析的第一个IPv4地址。
- UDPv4说明符+域名+端口：UDPv4:[eprosima.com]:35665。如上，但使用特定端口。
- UDPv6说明符+域名：UDPv6:[<dns>]。将仅使用解析的第一个IPv6地址。
- UDPv6说明符+域名+端口：UDPv6:[<dns>]:35665。如上，但使用特定端口。
- TCPv4说明符+域名：TCPv4:[eprosima.com]。将仅使用解析的第一个IPv4地址。
- TCPv4说明符+域名+端口：TCPv4:[eprosima.com]:42100。如上，但使用特定端口。
- TCPv6说明符+域名：TCPv6:[<dns>]。将仅使用解析的第一个IPv4地址。
- TCPv6说明符+域名+端口：TCPv6:[<dns>]:42100。如上，但使用特定端口。

如果使用默认UDP传输时未指定端口，则使用默认端口11811。

如果使用TCP传输时未指定端口，则使用默认端口42100。

要设置多个服务器的地址，它们必须用分号分隔。

当将IPv6与DNS一起使用时，指定的域名空间（）必须能够解析为IPv6地址。否则将引发错误。

以下示例显示如何设置两个远程发现服务器的地址，分别为’84.22.259.329:8888’和’localhost:1234’。

Linux

export ROS_DISCOVERY_SERVER="84.22.259.329:8888;localhost:1234"

Windows

set ROS_DISCOVERY_SERVER=84.22.259.329:8888;localhost:1234

重要
ROS_DISCOVERY_SERVER中指定的IP地址必须是有效的IPv4/IPv6地址或域名。如果一个名称可以解析为多个地址，则可以使用所有这些地址，或者使用UDPv4或TCPv4前缀将选择限制为第一个IPv4，或者使用UDPv6或TCPv6前缀将选择限制为第一个IPv6地址。

重要
如果使用FASTDDS_ENVIRONMENT_FILE从环境文件加载，则可以在运行时更改此环境变量，向SERVER、BACKUP或CLIENT（之前已使用此环境变量初始化）添加新的远程服务器。

11.5. `ROS2_EASY_MODE`

将ROS2_EASY_MODE设置为IP值可以使参与者自动进入发现服务器简易模式。此模式完全禁用多播通信，并依靠发现服务器进行发现。

使用ROS2_EASY_MODE，将在给定域中自动在本地生成一个新的发现服务器，指向位于指定IP的另一个发现服务器。如果指定的IP属于同一主机，则它仅在本地主机上工作，直到另一个主机连接到它。如果该域存在发现服务器，则将跳过生成过程，依靠现有服务器进行发现。因此，域中每个主机将只存在一个发现服务器。

为了使此变量生效，参与者必须将其发现协议设置为SIMPLE（默认），以自动进入发现服务器简易模式。如果发生这种情况，参与者将被配置为指向本地服务器的SUPER_CLIENT。

以下示例将把参与者配置为指向本地发现服务器的SUPER_CLIENT，该服务器将尝试连接到位于主机10.0.0.1的另一个发现服务器。

export ROS2_EASY_MODE=10.0.0.1

发现服务器的端口是根据知名端口中解释的规则计算的。在此新模式下配置的传输包括用于发现的UDP单播以及用于用户数据的TCP和共享内存。

详细教程可以在Vucanexus简易模式教程文档中找到。

注意
启用ROS2_EASY_MODE时，Fast DDS会自动加载名为service的自定义XML配置文件。此配置文件通过修改max_blocking_time来增加ROS 2服务的服务器响应超时。但是，如果用户提供的XML文件已经包含具有相同名称的配置文件，则Fast DDS不会加载任何额外的配置文件。相反，将使用用户XML文件中定义的max_blocking_time值。

警告
Windows平台尚不支持发现服务器ROS2_EASY_MODE。

11.6. `ROS_SUPER_CLIENT`

如果DomainParticipant的发现协议设置为SIMPLE，并且ROS_SUPER_CLIENT设置为TRUE，则参与者会自动升级为SUPER_CLIENT。

重要
此环境变量旨在与ROS_DISCOVERY_SERVER结合使用，将参与者从SIMPLE提升为SUPER_CLIENT。参与者将具有在ROS_DISCOVERY_SERVER中定义的服务器列表。

可能的值为：TRUE、true、True、1、FALSE、false、False、0。

重要
如果未设置该变量，Fast DDS的默认行为等同于该变量设置为false的情况。

以下示例显示如何将环境变量设置为true。

Linux
```
export ROS_SUPER_CLIENT=TRUE
```
Windows
```
set ROS_SUPER_CLIENT=TRUE
```

11.7. `FASTDDS_STATISTICS`

警告
仅当启用了CMake选项FASTDDS_STATISTICS时，才会使用此环境变量。在其他任何情况下，该环境变量都无效。有关更多信息，请参考CMake选项。

设置此变量可将DomainParticipant配置为启用统计信息DataWriter，其主题包含在此环境变量中设置的列表中。列表的元素应使用分号分隔，并与统计信息主题名称别名匹配。

例如，要启用报告延迟测量的统计信息DataWriter，应按如下方式设置环境变量：

Linux

export FASTDDS_STATISTICS="HISTORY_LATENCY_TOPIC;NETWORK_LATENCY_TOPIC"

Windows

set FASTDDS_STATISTICS=HISTORY_LATENCY_TOPIC;NETWORK_LATENCY_TOPIC

重要
此环境变量可以与XML配置文件一起使用（有关更多信息，请参考自动启用统计信息DataWriter）。将启用的统计信息DataWriter是XML文件中指定的（如果已加载）和环境变量中指定的（如果已设置）的并集。

11.8. `FASTDDS_ENVIRONMENT_FILE`

将此环境变量设置为现有json文件，可以从该文件而不是从环境中加载环境变量。这允许仅通过修改并保存对文件的更改来在运行时更改某些环境变量的值。环境值可以是绝对路径或相对路径。文件格式如下：

{
    "environment_variable_name_1": "environment_variable_value_1",
    "environment_variable_name_2": "environment_variable_value_2"
}

重要
环境文件中设置的环境变量优先于环境中的环境变量。

警告
目前只有ROS_DISCOVERY_SERVER环境变量允许在运行时更改（参见在运行时修改远程服务器列表）。

【FastDDS】Environment variables

11. 环境变量

11.1. FASTDDS_DEFAULT_PROFILES_FILE

11.2. SKIP_DEFAULT_XML

11.3. FASTDDS_BUILTIN_TRANSPORTS

11.3.1. 配置内置传输选项

11.4. ROS_DISCOVERY_SERVER

11.5. ROS2_EASY_MODE

11.6. ROS_SUPER_CLIENT

11.7. FASTDDS_STATISTICS

11.8. FASTDDS_ENVIRONMENT_FILE

11.1. `FASTDDS_DEFAULT_PROFILES_FILE`

11.2. `SKIP_DEFAULT_XML`

11.3. `FASTDDS_BUILTIN_TRANSPORTS`

11.4. `ROS_DISCOVERY_SERVER`

11.5. `ROS2_EASY_MODE`

11.6. `ROS_SUPER_CLIENT`

11.7. `FASTDDS_STATISTICS`

11.8. `FASTDDS_ENVIRONMENT_FILE`