v0.61.3
ReferenceHardwareEtherCATConfigure a device

Configure an EtherCAT device

Connect an EtherCAT network to the Driver and configure its modules.

EtherCAT is a fieldbus that runs on a standard Ethernet port. The Driver is the EtherCAT master: it finds each module on the network and reads and writes the process data of the module, which EtherCAT calls PDOs. Before a task can use a module, you configure it. For Dewesoft IOLITE and SIRIUS devices, also see Dewesoft devices.

The Console and the Driver call a module a slave, as EtherCAT does. A message that says “slave” refers to a module.

Prerequisites

Supported
WindowsmacOSLinuxNI Linux RT
Not supported
Docker
  • An Ethernet port on the computer that runs the Driver, cabled to the first module. Use a port for EtherCAT only, and do not connect it to a switch or to your office network.
  • Packet capture access:
    • Windows -> install Npcap. The default install options work. If DewesoftX is installed, turn off its network filter on the port for Synnax.
    • macOS -> install the ChmodBPF package that comes with Wireshark, or give your user read and write access to /dev/bpf*. Then log out, log in again, and restart the Driver.
    • Linux -> nothing to install. See network interface access.
Enterprise

On Linux, if the IgH EtherCAT Master kernel module is loaded, the Driver uses it instead of its built-in master.

Network interface access

EtherCAT sends raw Ethernet frames, so the Driver needs direct access to the network interface.

Platform What the Driver needs
Linux service Nothing. The service has raw Ethernet access and IgH access.
Linux, embedded in the Core Run the Core as root. Without IgH, you can also start the Core from a systemd unit with AmbientCapabilities=CAP_NET_RAW.
NI Linux Real-Time Nothing. The service runs as root.
Windows Npcap.
macOS Read and write access to /dev/bpf*, from ChmodBPF or set by hand. Root also has it.

Synnax Desktop runs the Core and the Driver as your user, so on macOS it needs ChmodBPF or access to /dev/bpf*. The Core’s Docker image runs as a user without these permissions, so its embedded Driver cannot run EtherCAT tasks.

Enterprise

To start the Driver on Linux by hand, run it as root or give it the access that the service has. Without IgH, the Driver needs the raw Ethernet capability:

sudo setcap cap_net_raw+ep /usr/local/bin/synnax-driver

With IgH, the Driver needs access to the master device (/dev/EtherCAT0) instead. sudo synnax-driver install gives this access to the synnax group, so add your user to that group, then log in again:

sudo usermod -aG synnax $USER

A service installed by an older Driver does not have these permissions. To update it, run sudo synnax-driver install again.

How the Driver finds modules

The Driver looks for EtherCAT modules on each wired Ethernet port every 5 seconds. It skips loopback, Wi-Fi, VPN, bridge, container, and other virtual ports, and it checks a port with no modules every 30 seconds. A module shows in the devices toolbar under its Driver:

  • Name -> the name stored in the module, such as EL3102, or “EtherCAT Slave <position>”.
  • Location -> the port and the position of the module on the network, such as en5.Slot 2.

When no task uses the network, a module that you connect shows at the next scan, and a module that you remove shows Device disconnected. While a task uses the network, the list of modules does not change. To find new modules, stop the tasks on the port.

The Driver reads the PDOs of a module from the module itself. If the module does not report them, the Driver uses a built-in catalog of Beckhoff and Dewesoft modules. If it cannot find them, the status of the module reads “Failed to discover PDOs”, and its description gives the reason. While no task uses the port, the Driver tries to discover the PDOs again every 30 seconds. A module that the scan cannot read is not supported yet.

How the Driver runs a network

  • One network per port -> All read and write tasks on a port share one network. Starting or stopping one task does not interrupt the others.
  • Start and stop -> The network starts when the first task on the port starts, and stops when the last task stops.
  • A module that refuses to start -> With the built-in master, the network starts without a module that refuses SAFE-OP or OP. The status of the module shows Failed to start, and a task that uses the module does not start. The other tasks start. The Driver tries the module again the next time the network starts. If every module with inputs or outputs refuses, or a module does not reach OP within 10 seconds, no task on the port starts.
  • DC sync -> The Driver runs each module in its sync mode. With the built-in master, it starts SYNC0 and SYNC1 of a module in DC sync before the module goes to SAFE-OP.
  • Cycle rate -> The network cycles at the slowest rate that is a multiple of each read task’s sample rate and at least each write task’s execution rate. The rate is always between 100 Hz and 10 kHz. For example, read tasks at 250 Hz and 1 kHz make the network cycle at 1 kHz. If no rate in that range is a multiple of every read rate, such as for 3 kHz and 4 kHz, the task fails to start. While a module runs in DC sync, the rate does not change until every task on the port stops. See The bus on ... cycles at ... Hz while a slave runs DC sync.
  • Outputs -> Each output holds the last value a write task commanded. When a write task stops, its outputs go to their stop values and hold them while the network runs. When the network stops, or the Driver loses contact with a module, the module sets its outputs to its own safe value. When the network starts, each output is 0 until a write task commands it.
  • Lost modules -> When a module stops responding, the network continues to cycle, and the Driver returns the module to operation when it responds again. Until then, every read task on the port pauses with the warning “Failed to read data”, and its data starts again when the module responds.

Configure a device

  1. In the devices toolbar, right-click the module and select Configure. You can also click Configure in the “New slave connected” notification. To list each module that the Driver found, click and select EtherCAT network.
  2. At the top of the dialog, enter a name for the module. The field shows “EtherCAT slave” until you type.
  3. Under General, enter an Identifier, or click one of the identifiers that the Console suggests.
  4. To run the module in a mode other than the default, set its sync mode under Sync mode.
  5. To write CoE settings when the network starts, add them under Startup parameters.
  6. Click Save. For a module that is not configured yet, you can click Save and create read task or Save and create write task to also open a task for it.

Configure each module that a task uses.

Set the sync mode

The sync mode sets what times the data exchange of a module: each frame from the Driver (SM sync), or the clock ticks of the module (DC sync). Most modules need the default. Select a DC sync mode for a module that is set to DC sync, such as a Dewesoft module.

  1. In the devices toolbar, right-click the module and select Configure.
  2. Under Sync mode, select a Mode. The default item shows the mode that the Driver picks, such as “SM”, with an Auto badge.
  3. For a DC sync mode, enter a SYNC0 cycle or a SYNC1 cycle in µs to replace the cycle of the mode. A cycle that you leave empty shows Auto and uses the cycle of the mode.
  4. Click Save.

The Driver picks a mode by these rules:

  • Default -> the Driver runs SM sync when the module lists an SM sync mode, and else the first mode that the module lists.
  • A listed mode -> the Driver runs that mode.
  • SYNC0 cycle and SYNC1 cycle -> a DC sync mode gives its own cycles, often as a number of bus cycles. A cycle that you enter replaces the cycle of the mode. The SYNC1 cycle must be a multiple of the SYNC0 cycle, and a SYNC1 cycle turns on SYNC1 when the mode leaves it off.

The dialog checks each cycle before you save. It shows “This mode gives no SYNC0 cycle. Type one.”, “SYNC1 cycle must be a multiple of the SYNC0 cycle”, or “… is over the limit of …”. When the module no longer lists the saved mode, it shows “The device no longer lists this mode, so the network fails to start. Pick a mode.”

A change applies the next time the network starts: stop every task on the port, then start them again.

Enterprise

The IgH master does not run DC sync and reads no sync modes, so Sync mode lists none. A module that needs DC sync, such as a Dewesoft module set to DC sync, cannot reach OP with IgH. A DC sync mode selected during an earlier scan with the built-in master fails the start.

The Driver uses IgH whenever the IgH kernel module is loaded. To use the built-in master instead:

  1. Stop IgH with sudo systemctl stop ethercat, or with sudo /etc/init.d/ethercat stop on a computer without systemd.
  2. To keep IgH off after a reboot, run sudo systemctl disable ethercat.
  3. Check that the port shows in ip link. If IgH used a native device module, the port can need its standard Linux driver again first.
  4. Restart the Driver.
  5. A module with no serial number shows as a new device, because its key comes from the port and the position. Configure it, then select it again in each task that used it.

Disable a device

Disable a module to leave it out of the network, for example when it is not cabled yet or when it does not start.

  1. In the devices toolbar, right-click the module and select Disable. To disable several modules, select them first.
  2. The status changes to “Device disabled”.

The change applies the next time the network on the port starts: stop every task on the port, then start them again. To use the module again, right-click it and select Enable. The status changes to “Device enabled”.

Set startup parameters

Many modules keep settings such as filters, measurement ranges, and sensor types in CoE objects. Add these settings as startup parameters, and the Driver writes them to the module each time the network starts, before the module exchanges data. The Driver also writes them again when a module returns after a power loss.

  1. In the devices toolbar, right-click the module and select Configure.
  2. Under Startup parameters, click Add parameter.
  3. Enter the Index and Subindex in hexadecimal, such as 8000 and 15. Select the Data type, and enter the Value and an optional Name.
  4. Click Save. If the data type cannot hold the value, the Console marks the value and does not save.
  • When changes apply -> If the network is running, a change applies the next time the network starts. Stop every task on the port, then start them again.
  • Rejected values -> If a module rejects a value, the task does not start. The error names the parameter and the reason that the module gave, for example rejected startup parameter 0x8000:15 (Filter settings): Value of parameter written too high. If a module rejects a value when it reconnects, it stays out of operation until the network starts again.
  • Invalid properties -> If a parameter is not valid, the status of the module shows Invalid device properties and says which field is wrong. The network starts every module on it, so no task on that network starts until you correct the parameter.

Module status

While a task uses the network, the status of each module shows its live state. The Driver updates it every 5 seconds.

Status Meaning
Operational The module exchanges data in OP, the operational state of EtherCAT.
In SAFE-OP, In PRE-OP The module left OP. The Driver is returning it to OP.
Error in SAFE-OP, Error in PRE-OP The module reports an error. The status description shows the error text of the module. With IgH, the kernel log (dmesg) shows the error code instead.
Failed to start The module refused SAFE-OP or OP, and the network started without it. The Driver tries it again the next time the network starts.
Failed to restore the distributed clock The module lost its clock settings, and the Driver could not set them again. The Driver keeps it out of OP and tries again.
Not responding The module does not answer. Check its power and cabling.
Invalid device properties A stored property, such as a startup parameter, is not valid. The description names the field.
Device disabled, Device enabled You disabled or enabled the module.
Device disconnected The last scan did not find the module.

When no task uses the network, the status shows what the scan found, such as Discovered (4 inputs, 2 outputs) or Failed to discover PDOs.

Device properties

Property Meaning
name The name stored in the module.
identifier The identifier that starts the channel names of the module.
vendor_id, product_code The vendor and model of the module, as numbers.
revision, serial The revision and serial number of the module, as numbers.
network The port of the module, such as en5. With IgH, igh:0.
position The position on the network. Starts at 1.
enabled false when the module is disabled.
op_modes The sync modes that the module lists. Read only. See below.
op_mode The sync mode that you chose. Absent means the default.
startup_parameters CoE values that the Driver writes when the network starts. See startup parameters.
pdos.inputs, pdos.outputs The PDO entries of the module. See below.

Each entry of op_modes has a name, an assign_activate, and the cycles of the mode: sync0_cycle, sync0_factor, sync0_shift, sync1_factor, and sync1_shift. The op_mode property has the index of the mode in op_modes, its assign_activate, and a sync0_cycle and a sync1_cycle in nanoseconds, where 0 uses the cycle of the mode.

Each startup parameter has these fields:

Field Type Required Notes
index number CoE object index, from 0x0000 to 0xFFFF.
sub_index number CoE object subindex, from 0 to 255.
data_type string int8 to int64, uint8 to uint64, float32, or float64.
value number Must fit in data_type. An integer is between -9007199254740991 and 9007199254740991.
name string A label that error messages show.

Each PDO entry has a name, an index and a sub_index (its CoE address), a bit_length, a data_type, and a pdo_index, the index of the PDO that holds it. When the module names its PDOs, an entry also has a pdo_name. TypeScript uses the same fields in camel case, such as subIndex.

Troubleshooting

For setup errors, networks that do not start, and sync mode errors, see Troubleshoot EtherCAT.