ecal.yaml

ecal.yaml#

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

  • Windows: %localappdata%\eCAL\ecal.yaml

  • Ubuntu: /etc/ecal/ecal.yaml

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. Also, if you place a ecal.yaml in the working directory of the process, it will be loaded if ECAL_DATA is not specified first.

In order to create the eCAL configuration files in the marked (*) directories, you can use the ecal_generate_config tool, which is part of the eCAL installation. It will generate the files in the first of the marked directories that is writable.

Important

This loading strategy is valid for eCAL 6.0 and up.

  • Windows:

    1. %ECAL_DATA%\ecal.yaml

    2. %cd%\ecal.yaml

    3. %localappdata%\eCAL\ecal.yaml *

    4. %ProgramData%\eCAL\ecal.yaml * (fallback)

    5. <ecal installation directory>\etc\ecal.yaml (fallback)

  • Ubuntu:

    1. $ECAL_DATA/ecal.yaml

    2. $PWD/ecal.yaml

    3. $HOME/.ecal/ecal.yaml *

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

Note

When compiling eCAL from source:

In previous versions (before eCAL 6.0.0), you could set CMAKE_INSTALL_SYSCONFDIR to change the default configuration path and the applications could still find it on Linux.

This is not the case anymore.

Instead, when installing your build to a custom path, a directory next to lib named etc will be created containing the ecal.yaml file if no CMAKE_INSTALL_SYSCONFDIR is set. That file in etc relativ to the ecal_core library will be used if no other is found.

ecal.yaml options#

Here you can find the current ecal.yaml options with description and default values. You can download the file here or generate it with the ecal_generate_config tool.

  • ecal.yaml

      1#  _____     _ _                                ____    _    _                             
  2# | ____|___| (_)_ __  ___  ___            ___ / ___|  / \  | |                            
  3# |  _| / __| | | '_ \/ __|/ _ \  _____   / _ \ |     / _ \ | |                            
  4# | |__| (__| | | |_) \__ \  __/ |_____| |  __/ |___ / ___ \| |___                         
  5# |_____\___|_|_| .__/|___/\___|          \___|\____/_/   \_\_____|                        
  6#               |_|                                                                            
  7#        _       _           _                    __ _                       _   _             
  8#   __ _| | ___ | |__   __ _| |   ___ ___  _ __  / _(_) __ _ _   _ _ __ __ _| |_(_) ___  _ __  
  9#  / _` | |/ _ \| '_ \ / _` | |  / __/ _ \| '_ \| |_| |/ _` | | | | '__/ _` | __| |/ _ \| '_ \ 
 10# | (_| | | (_) | |_) | (_| | | | (_| (_) | | | |  _| | (_| | |_| | | | (_| | |_| | (_) | | | |
 11#  \__, |_|\___/|_.__/ \__,_|_|  \___\___/|_| |_|_| |_|\__, |\__,_|_|  \__,_|\__|_|\___/|_| |_|
 12#  |___/                                               |___/                                   
 13
 14
 15# Operation configuration
 16# eCAL components communication mode ("local" or "network"):
 17#   "local": local host only communication (default)
 18#   "network": communication across network boundaries
 19communication_mode: "local"
 20
 21
 22# Registration layer configuration
 23registration:
 24  # Topic registration refresh cylce (has to be smaller then registration timeout! Default: 1000)
 25  registration_refresh: 1000
 26  # Timeout for topic registration in ms (internal, Default: 60000)
 27  registration_timeout: 10000
 28  # Enable to receive registration information on the same local machine
 29  loopback: true
 30  # SHM transport domain that enables interprocess mechanisms across (virtual)
 31  # host borders (e.g, Docker); by default equivalent to local host name
 32  shm_transport_domain: ""
 33
 34  local:
 35    # Specify the transport type for local registration
 36    #   "shm": shared memory based registration
 37    #   "udp": udp based registration (default)
 38    transport_type: "udp"
 39    shm:
 40      # Domain name for shared memory based registration
 41      domain:  "ecal_mon"
 42      # Queue size of registration events
 43      queue_size: 1024
 44    udp:
 45      # Specify port for local registration traffic
 46      port: 14000
 47
 48  network:
 49    # Specify the transport type for network registration
 50    #   "udp": udp based registration (default)
 51    transport_type: "udp"
 52    udp:
 53    # Specify port for network registration traffic
 54      port: 14000
 55
 56
 57# Transport layer configuration
 58transport_layer:
 59  udp:
 60    # UDP configuration version (Since eCAL 5.12.)
 61    # v1: default behavior
 62    # v2: new behavior, comes with a bit more intuitive handling regarding masking of the groups
 63    config_version: "v2"
 64    # Multicast port number
 65    port: 14002
 66    # v1: Mask maximum number of dynamic multicast group (range 0.0.0.1-0.0.0.255)
 67    # v2: Masks are now considered like routes masking (range 255.0.0.0-255.255.255.255)
 68    mask: "255.255.255.240"
 69    # Send buffer in bytes
 70    send_buffer: 5242880
 71    # Receive buffer in bytes
 72    receive_buffer: 5242880
 73    # Linux specific setting to join all network interfaces independend of their link state.
 74    # Enabling ensures that eCAL processes receive data when they are started before the
 75    # network devices are up and running.
 76    join_all_interfaces: false
 77    # Windows specific setting to enable receiving UDP traffic with the Npcap based receiver
 78    npcap_enabled: false
 79
 80    # Local mode multicast group and ttl
 81    local:
 82      # Multicast group base. All registration and logging is sent on this address
 83      group: "127.255.255.255"
 84      # TTL (hop limit) is used to determine the amount of routers being traversed towards the destination
 85      ttl: 1
 86
 87    network:
 88      # Multicast group base. All registration and logging is sent on this address
 89      group: "239.0.0.1"
 90      # TTL (hop limit) is used to determine the amount of routers being traversed towards the destination
 91      ttl: 3
 92
 93  tcp: 
 94    # Reader amount of threads that shall execute workload
 95    number_executor_reader: 4
 96    # Writer amount of threads that shall execute workload
 97    number_executor_writer: 4
 98    # Reconnection attemps the session will try to reconnect in case of an issue
 99    max_reconnections: 5
100
101
102# Publisher specific base settings
103publisher:
104  layer:
105    # Base configuration for shared memory publisher
106    shm:
107      # Enable layer
108      enable: true
109      # Enable zero copy shared memory transport mode
110      zero_copy_mode: false
111      # Force connected subscribers to send acknowledge event after processing the message.
112      # The publisher send call is blocked on this event with this timeout (0 == no handshake).
113      acknowledge_timeout_ms: 0
114      # Maximum number of used buffers (needs to be greater than 1, default = 1)
115      memfile_buffer_count: 1
116      # Default memory file size for new publisher
117      memfile_min_size_bytes: 4096
118      # Dynamic file size reserve before recreating memory file if topic size changes
119      memfile_reserve_percent: 50
120
121    # Base configuration for UDP publisher
122    udp:
123      # Enable layer
124      enable: true
125
126    # Base configuration for TCP publisher
127    tcp:
128      # Enable layer
129      enable: true
130
131  # Priority list for layer usage in local mode (Default: SHM > UDP > TCP)
132  priority_local: ["shm", "udp", "tcp"]
133  # Priority list for layer usage in cloud mode (Default: UDP > TCP)
134  priority_network: ["udp", "tcp"]
135
136
137# Subscriber specific base configuration
138subscriber:
139  layer:
140    # Base configuration for shared memory subscriber
141    shm:
142      # Enable layer
143      enable: true
144
145    # Base configuration for UDP subscriber
146    udp:
147      # Enabler layer
148      enable: true
149
150    # Base configuration for TCP subscriber
151    tcp:
152      # Enable layer
153      enable: false
154
155  # Enable dropping of payload messages that arrive out of order
156  drop_out_of_order_messages: true
157
158
159# Time configuration
160time:
161  # Time synchronisation interface name (dynamic library)
162  # The name will be extended with platform suffix (32|64), debug suffix (d) and platform extension (.dll|.so)
163  # Available modules are:
164  #   - ecaltime-localtime    local system time without synchronization
165  #   - ecaltime-linuxptp     For PTP / gPTP synchronization over ethernet on Linux
166  #                           (device configuration in ecaltime.ini)
167  rt: "ecaltime-localtime"
168  # Specify the module name for replaying
169  replay: ""
170
171
172# eCAL Application Configuration
173application:
174  # Configuration for eCAL Sys
175  sys:
176    # Apps blacklist to be excluded when importing tasks from cloud
177    filter_excl: "^eCALSysClient$|^eCALSysGUI$|^eCALSys$"
178  # Process specific configuration
179  terminal:
180    # Linux only command for starting applications with an external terminal emulator. 
181    # e.g. /usr/bin/x-terminal-emulator -e
182    #      /usr/bin/gnome-terminal -x
183    #      /usr/bin/xterm -e
184    # If empty, the command will be ignored.
185    emulator: ""
186
187
188# Logging configuration
189logging:
190  # Configuration for file, udp and console log provider
191  # Possible levels are: "info", "warning", "error", "fatal", "debug1", "debug2", "debug3", "debug4"
192  # Can be combined like
193  # log_level: ["warning", "fatal", "debug1", ...]
194  provider:
195    # Console logging configuration
196    console:
197      # Enable console logging
198      enable: true
199      # Log level for console output
200      log_level: ["warning", "error", "fatal"]
201    # File logging configuration
202    file:
203      # Enable file logging
204      enable: false
205      # Log level for file output
206      log_level: []
207    # UDP logging configuration
208    udp:
209      # Enable UDP logging
210      enable: true
211      # Log level for UDP output
212      log_level: ["info", "warning", "error", "fatal"]
213    # File specific configuration
214    file_config: 
215      # Log file path
216      path: ""
217    # UDP specific configuration
218    udp_config:
219      # UDP Port for sending logging data
220      port: 14001
221  # Configuration for udp log receiver
222  receiver:
223    # Enable log receiving (UDP only)
224    enable: false
225    # UDP specific configuration
226    udp_config:
227      # UDP Port for sending logging data
228      port: 14001