EtherCAT Master

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.

1. run: runs the applications (default)

2. dummy_opcua_server: runs the master with a fake link layer (useful if you only want to see the opcua server)

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,--opcual-port
Cycletime (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

The order of evaluation is:

1. default values

2. config file

3. environment

4. 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 needed capabilities.

ENI File

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

Log directory

Logfiles are created in this directory.

Benchmark directory

The Master operates in a (soft) realtime context. To diagnose timing and realtime 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 realtime issues. However, the benchmarks are currently used for development only.

OPC UA port

This is the port to which the OPC UA server binds to.

Cycletime

The cycletime 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 are unsure about the consequences. In general, it is advisable to use a value 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 (realtime) 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.

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
}

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 OPC UA server is started. See the help message for details (voraus-aux-ethercat-master --help).

Docker

The master is published as a docker image. Here is an example docker compose file to start the master:

services:
  ethercat-master:
    image: voraus-aux-ethercat-master:latest
    network_mode: host
    cap_add:
      - CAP_NET_ADMIN # needed for setting the interface into promiscuous mode
      - CAP_NET_RAW # needed for raw socket communication
      - CAP_IPC_LOCK # needed for memory locking
      - CAP_SYS_NICE # needed for using SCHED_FIFO with a priority
    devices:
      - /dev/cpu_dma_latency:/dev/cpu_dma_latency # needed for sleep state prevention
    volumes:
      - ./data/:/root/data/ # contains eni file and logs
    ports:
      - 4840:4840 # public opcua port
    environment:
      - CODEMETER_HOST=codemeter
      - ECAT_ENI=/root/data/test_eni.xml
      - ECAT_CYCLETIME=2000
      - ECAT_INTERFACE=eth0
      - ECAT_LOG_DIR=/data/log

  codemeter:
    hostname: codemeter
    image: voraus-codemeter:latest
    environment:
      LICENSE_SERVER: host.docker.internal
    extra_hosts:
      - host.docker.internal:host-gateway

The network_mode: host is required because the EtherCAT master uses raw sockets.

See Configuration for details about configuration. This section also contains further explanation for the used capabilities.

The codemeter container is only required, if the master should be used with a licence server. Otherwise, the codemeter runtime of the host can be used. Omit the codemeter container in this case and use CODEMETER_HOST=127.0.0.1 in the master container.