ecal.yaml

eCAL has many options that can be configured via an .ini file which is located at:

Loading strategy (Priority)

The eCAL configuration file is loaded based on the following priorities, whereever it is found first. If you want a specific eCAL Node to run with another ecal.yaml than the others, you can set the ECAL_DATA variable before starting the process, e.g. from a batch or shell skript. In addition, some eCAL applications support providing a path from the command line option --ecal-config-file.

Important

This loading strategy is valid for eCAL 5.10 and up.

  • |fa-windows| Windows:

    1. %ECAL_DATA%/ecal.yaml

    2. %ProgramData%/ecal/ecal.yaml

  • |fa-ubuntu| Ubuntu:

    1. $ECAL_DATA/ecal.yaml

    2. /etc/ecal/ecal.yaml (from CMAKE_INSTALL_SYSCONFDIR)

    3. /etc/ecal/ecal.yaml (fallback)

      Note

      This second path is set from CMake to CMAKE_INSTALL_SYSCONFDIR/ecal/ecal.yaml. Official builds are configured to use /etc. If you are compiling eCAL yourself and don’t provide the SYSCONFDIR, CMake will usually use /usr/local/etc/ecal/ecal.yaml.

ecal.yaml options

Registration settings are listed in the section registration

registration
registration_refresh

< registration_timeout/2, default 1000

topic registration refresh cycle (has to be smaller than registration timeout!)

registration_timeout

1000 + (x * 1000), default 60000

timeout for topic registration in ms

loopback

true / false, default true

enable to receive registration information on the same local machine

host_group_name

<hostname>, default ""

host group name that enables interprocess mechanisms across (virtual) host borders (e.g. Docker); by default equivalent to local host name

network_enabled

true / false, default: true

true = all eCAL components communicate over network boundaries

false = local host only communication

layer
shm
enabled

true / false, default: false

enable shared memory layer

domain

ecal_mon

Domain name for shared momory based registration

queue_size

1024

Queue size of registration events

udp
enabled

true / false, default: true

enable UDP multicast layer

port

14000 + x

UDP port for registration information if UDP is enabled

Monitoring settings are listed in the section monitoring

monitoring
timeout

1000 + (x * 1000) default 1000 Timeout for topic monitoring in ms If no additional registration information for the topic has be received in that time period, topics will no longer be shown in eCAL Monitor.

filter_excl

topics blacklist as regular expression (will not be monitored) Per default includes all eCAL internal topics.

default = ^__.*$

filter_incl

topics whitelist as regular expression (will be monitored only)

default = `` ``

Transportlayer settings are listed in the section transport_layer

transport_layer
udp
config_version

v1 / v2, default: v2

UDP configuration version (Since eCAL 5.12.)

v1 = default behavior

v2 = new behavior, comes with a bit more intuitive handling regarding masking of the groups

mode

local / network, default: local

local = use local network settings - not configurable by the user

network = use network settings - configurable by the user

port

14000 + x

UDP multicast port number

mask

v1 behavior:

0.0.0.1-0.0.0.255

Mask maximum number of dynamic multicast group

v2 behavior:

255.0.0.0-255.255.255.255

Mask for the multicast group. Topic traffic may be set on any of the unmasked addresses.

With group: 239.0.0.1 and mask: 255.255.255.0, topic traffic will be sent on addresses 239.0.0.0-239.0.0.255.

send_buffer

1024 * x default 5242880

UDP send buffer in bytes

receive_buffer

1024 * x default 5242880

UDP receive buffer in bytes

join_all_interfaces

true / false default false

Linux specific setting to join all network interfaces independend of their link state. Enabling ensures that eCAL processes receive data when they are started before the network devices are up and running.

npcap_enabled

true / false default false

Enable to receive UDP traffic with the Npcap based receiver

local

In local mode the UDP multicast group is set to the local host address (“127.0.0.1”) and the multicast TTL is set to 0 by default. This is not configurable.

network
group

xxx.xxx.xxx.xxx IP address as text, default 239.0.0.1

Multicast group base: all registration and logging is sent on this address

ttl

0 + x default 3

TTL (hop limit) is used to determine the amount of routers being traversed towards the destination

tcp
number_executor_reader

1 + x default 1

Number of reader threads that shall execute workload

number_executor_writer

1 + x default 1

Number of writer threads that shall execute workload

max_reconnections

1 + x default 1

Reconnection attemps the session will try to reconnect in case of an issue

Publisher settings are listed in the section publisher

publisher
layer
shm
enable

true / false default true

Enable shared memory layer

zero_copy_mode

true / false default false

Enable zero copy mode for shared memory transport mode

acknowledge_timeout_ms

0 + x default 0

Force connected subscribers to send acknowledge event after processing the message. The publisher send call is blocked on this event with this timeout (0 == no handshake).

memfile_buffer_count

1 + x default 1

Maximum number of used buffers (needs to be greater than 0, default = 1)

memfile_min_size_bytes

x * 4096 kB default 4096

Default memory file size for new publisher

memfile_reserve_percent

20 .. x default 50

Dynamic file size reserve before recreating memory file if topic size changes

udp
enable

true / false default true

Enable UDP multicast layer

tcp
enable

true / false default false

Enable TCP layer

share_topic_type

true / false default true

Share topic type via registration layer

share_topic_description

true / false default true

Share topic description via registration layer. If set to false, reflection is completely disabled. It is not possible then to monitor the content of messages in the eCAL Monitor.

priority_local

["shm", "udp", "tcp"] default ["shm", "udp", "tcp"]

A list of transport layers as text that specifies the prioritized layer for local communication.

priority_remote

["udp", "tcp"] default ["udp", "tcp"]

A list of transport layers as text that specifies the prioritized layer for remote communication.

Subscriber settings are listed in the section subscriber

subscriber
layer
shm
enable

true / false default true

Enable shared memory layer

udp
enable

true / false default true

Enable UDP multicast layer

tcp
enable

true / false default false

Enable TCP layer

drop_out_of_order_messages

true / false default false

Enable dropping of payload messages that arrive out of order

Time settings are listed in the section time

time
rt

default: "ecaltime-localtime"

Module (dll / so) name time sync interface. The name will be extended with debug suffix (d) and platform extension (.dll|.so)

Available modules are:

  • ecaltime-localtime local system time without synchronization

  • ecaltime-linuxptp For PTP / gPTP synchronization over ethernet on Linux (device configuration in ecaltime.ini)

  • ecaltime-simtime Simulation time as published by the eCAL Player.

replay

default ""

Module name of time plugin for replaying

Service settings are listed in the section service

service
protocol_v0

true / false default true

Support service protocol v0, eCAL 5.11 and older

protocol_v1

true / false default false

Support service protocol v1, eCAL 5.12 and newer

Application settings are listed in the section application

Logging settings are listed in the section logging

logging
sinks

Log levels are: “info”, “warning”, “error”, “fatal”, “debug1”, “debug2”, “debug3”, “debug4”

console
enable

true / false default false

Enable console logging

level

List of log levels as text, default ["info", "warning", "error", "fatal"]

file
enable

true / false default false

Enable file logging

level

List of log levels as text, default []

path

Path as text, default ecal.log

udp
enable

true / false default false

Enable udp logging

level

List of log levels as text, default ["info", "warning", "error", "fatal"]

port

14000 + x default 14001

UDP port for logging information