Configuration

General

The application can be configured by a combination of command line interface, config file and environment variables.

Run Modes

The application has two different run modes.

run: runs the application (default)
dummy_opcua_server: starts only the OPC UA server on a dummy link layer, which is useful to explore the OPC UA interface without hardware. There is no EtherCAT communication and the state machine does not run. State requests and Reset are only simulated by the OPC UA server. No real-time setup is done in this mode, so no real-time capabilities are needed.

The mode can only be selected by using the CLI.

Supported options

Currently supported config options are:

Name	Default	Config file key	Environment	CLI
ENI File	None	eni-file	`ECAT_ENI`	`-f,--eni-file`
Log Directory	None	log-dir	`ECAT_LOG_DIR`	`-l,--log-dir`
Benchmark Directory	logdir	benchmark-dir	`ECAT_BENCHMARK_DIR`	`-b,--benchmark-dir`
OPC-UA Port	4840	opcua-port	`ECAT_OPCUA_PORT`	`-o,--opcua-port`
Cycle Time (in µs)	None	cycle-time	`ECAT_CYCLETIME`	`-c,--cycle-time`
Network Interface	None	interface	`ECAT_INTERFACE`	`-i,--interface`
Verbose Mode	false	verbose	`ECAT_VERBOSE`	`-v,--verbose`
RT Priority	49	priority	`ECAT_PRIORITY`	`-p,--priority`
Lock Memory	true	lock-memory	`ECAT_LOCK_MEM`	`-m,--lock-memory`
Prevent Sleep States	true	prevent-sleep-states	`ECAT_PREVENT_SLEEP_STATES`	`-s,--prevent-sleep-states`
CPU Affinity	-1	cpu-affinity	`ECAT_CPU_AFFINITY`	`-n,--cpu-affinity`
Transition Timeout (ms)	0	transition-timeout	`ECAT_TRANSITION_TIMEOUT`	`-t,--transition-timeout`
Relax WKC Check	false	relax-wkc-check	`ECAT_RELAX_WKC_CHECK`	`--relax-wkc-check`
SDO Max Payload Size	256	sdo-max-payload-size	`ECAT_SDO_MAX_PAYLOAD_SIZE`	`--sdo-max-payload-size`
RT Port Config	see below	rt-port-config	`ECAT_RT_PORT_CONFIG`	`--rt-port-config`
EoE TAP Enabled	false	eoe-tap-enabled	`ECAT_EOE_TAP_ENABLED`	`--eoe-tap-enabled`
EoE TAP Ifname	empty	eoe-tap-ifname	`ECAT_EOE_TAP_IFNAME`	`--eoe-tap-ifname`
EoE TAP IPv4 CIDR	empty	eoe-tap-ip-cidr	`ECAT_EOE_TAP_IP_CIDR`	`--eoe-tap-ip-cidr`

The order of evaluation is:

default values
config file
environment
CLI

This means, if an option is provided by config file and CLI, the value from the CLI will be used. Below is a description of all options. Some of them require Linux capabilities. If you run the master as the root user and without docker, all necessary capabilities are typically already present. However, if you use Docker, you have to explicitly add these capabilities. See Docker for a compose file that adds all required capabilities.

ENI File

The EtherCAT Master needs an ENI file which describes the EtherCAT Network.

See ENI Files for details.

Log Directory

Logfiles are created in this directory.

Benchmark Directory

The master operates in a (soft) real-time context. To diagnose timing and real-time issues, some metrics e.g. the runtime of the cyclic task and the jitter of the receive timestamp are saved into a histogram. This helps to diagnose real-time issues. However, the benchmarks are currently used for development only.

OPC UA Port

This is the port to which the OPC UA server will bind.

Cycle Time

The cycle time in microseconds to use.

Network Interface

The interface that is used for the communication with the EtherCAT devices. If the interface is down, or has no link during startup, the master waits for the interface to become ready. The capabilities CAP_NET_RAW and CAP_NET_ADMIN are needed to use raw sockets.

Verbose Mode

If this is true, the master starts with a lower log level.

RT Priority

The main thread is started with SCHED_FIFO and this priority. Leave this at the default value, if you don’t know exactly what you are doing. In general, it is advisable to stay under 50, because most kernel threads have this priority. Using a higher priority generally leads to priority inversion with e.g. the network irq handler or e.g. the RCU thread. Generally, the capability CAP_SYS_NICE is required for using SCHED_FIFO (real-time) priorities.

Lock Memory

On startup, the memory is locked using mlockall if this option is true. The capability CAP_IPC_LOCK is needed for this option.

Prevent Sleep States

Prevents the CPU from entering sleep states (C-States) to avoid latencies caused by the wakeup transitions. This is done, by writing 0 to /dev/cpu_dma_latency. Therefore the application needs to have write access to this file if this option is enabled. See PM QoS for details. If your system has sleep states disabled using some other way, e.g. by the kernel parameter idle=poll, this option can be disabled.

CPU Affinity

Pin the cyclic task to this CPU. The value -1 means that the thread is not pinned.

Transition Timeout

Timeout for the error transition state in milliseconds. With the default of 0, ERROR TRANSITION lasts a single cycle and ERROR is entered right away. See State Machine for details.

Relax WKC Check

If set to true, the working counter checks will be relaxed if the state is not Operational. This is generally not recommended, but required for some EtherCAT slaves.

SDO Max Payload Size

Maximum payload size in bytes used by the real-time port SDO services (ecat-sdo-port) for request and response data buffers.

The default is 256 bytes. Increase this value if your workflow requires transferring larger SDO objects. Since it affects the buffers on the SDO real-time port, you may also need to adjust your application if you change this.

RT Port Config

The file containing real-time port configuration (see Real-Time Port Configuration for details).

Defaults to /etc/voraus/voraus-ethercat-master/port_config.json.

EoE TAP Enabled

Enables Ethernet-over-EtherCAT forwarding to a virtual interface. See Ethernet over EtherCAT (EoE).

EoE TAP Ifname

Name of the virtual Ethernet interface (TAP) used by EoE. If this is not set, the kernel will choose a name. This can either be a preexisting TAP or the master can create the TAP itself. If EoE TAP Enabled is not set to true, this option has no effect.

EoE TAP IPv4 CIDR

Optional IPv4 address in CIDR notation that is set on the EoE TAP. If this is not set, no IP address will be configured on the TAP and the TAP will be considered managed externally. This means that the TAP will also not be brought up by the master. If EoE TAP Enabled is not set to true, this option has no effect.

Config File

The config file is in json format and can be passed using the CLI (--config) or by the environment variable (VORAUS_CONFIG_DIR).

Note

The environment variable VORAUS_CONFIG_DIR contains the path to the config directory and not the path to the actual config file. If the config file is passed by environment variable, it must be named and located at ${VORAUS_CONFIG_DIR}/config.json.

An example config file is:

{
  "eni-file": "example_eni_file.xml",
  "log-dir": "logs",
  "opcua-port": 48400,
  "cycle-time": 2000,
  "interface": "eth0",
  "lock-memory": true,
  "prevent-sleep-states": true,
  "priority": 45,
  "verbose": true,
  "relax-wkc-check": false,
  "sdo-max-payload-size": 256,
  "rt-port-config": "example_port_config.json",
  "eoe-tap-enabled": true,
  "eoe-tap-ifname": "eoe0",
  "eoe-tap-ip-cidr": "192.168.10.1/24"
}

CLI

The CLI works by specifying a subcommand (see run modes). Some options which are required for actually running the master, can be omitted, when only the dummy opcua server is started. See the help message for details (voraus-ethercat-master --help).

FAQ and common pitfalls

State Machine