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.

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 software:
  • Windows -> install Npcap. The default install options work. If DewesoftX is installed, turn off its network filter on the port for Synnax.
  • Linux and macOS -> nothing to install.

Network interface access

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

The Core’s Docker image runs as a user without these permissions, so its embedded Driver cannot run EtherCAT tasks.

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

sudo usermod -aG synnax $USER

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 device status of the module shows why, 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 in time, 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 “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.

Module status

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

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.

Configure a device

for module in client.devices.retrieve(makes=["ethercat"]):
    props = module.properties
    print(module.name, props["network"], props["position"])
    for pdo in props["pdos"]["inputs"]:
        print("  in ", pdo["name"], hex(pdo["index"]), pdo["sub_index"], pdo["data_type"])
    for pdo in props["pdos"]["outputs"]:
        print("  out", pdo["name"], hex(pdo["index"]), pdo["sub_index"], pdo["data_type"])

const modules = await client.devices.retrieve({ where: { make: { eq: "ethercat" } } });
for (const module of modules) {
  const { network, position, pdos } = module.properties;
  console.log(module.name, network, position, JSON.stringify(pdos));
}

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). The modes that a module lists show under Sync mode in the Configure dialog.

• Auto -> The 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. Select the DC sync mode of a module that is set to DC sync, such as a Dewesoft module.
• 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. Clear a cycle to use the cycle of the mode again.

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

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.

module = client.devices.retrieve(key="<module key>")
module.properties["enabled"] = False
client.devices.create(module)

const module = await client.devices.retrieve({ key: "<module key>" });
module.properties.enabled = false;
await client.devices.create(module);

Startup parameters

Many modules keep settings such as filters, measurement ranges, and sensor types in CoE objects. Add these settings to the startup_parameters property, 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.

• 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 = client.devices.retrieve(key="<module key>")
module.properties["startup_parameters"] = [
    {
        "index": 0x8000,
        "sub_index": 0x15,
        "data_type": "uint16",
        "value": 1,
        "name": "Filter settings",
    },
]
client.devices.create(module)

const module = await client.devices.retrieve({ key: "<module key>" });
module.properties.startupParameters = [
  {
    index: 0x8000,
    subIndex: 0x15,
    dataType: "uint16",
    value: 1,
    name: "Filter settings",
  },
];
await client.devices.create(module);

Device properties

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

Troubleshooting

No modules show in the devices toolbar

1. Check the cable from the port to the first module, and the power to the modules.
2. Make sure that no other program uses the port. On Windows, DewesoftX can block the port also when DewesoftX is closed. See No modules show on a computer with DewesoftX.
3. Check the prerequisites and the network interface access, then restart the Driver.

No modules show on a computer with DewesoftX

DewesoftX adds a network filter, EthercatDAQ Filter, to each Ethernet port. After DewesoftX starts, the filter stops the replies of the modules before they get to the Driver. This continues after you close DewesoftX, and a restart of the port does not stop it. The scan finds no modules, and a task shows “no EtherCAT slaves found”.

To turn off the filter on the port for Synnax:

1. In Windows Settings, go to Network and internet > Advanced network settings > More network adapter options. You can also press Windows + R and enter ncpa.cpl.
2. Right-click the port that connects to the first module, then select Properties. Windows asks for administrator access.
3. Clear EthercatDAQ Filter, then select OK.

The modules show in the devices toolbar in 30 seconds or less. You do not need to restart the Driver. From an administrator PowerShell, this command does the same, with the name of the port from step 2:

Disable-NetAdapterBinding -Name "Ethernet 2" -ComponentID DW_EthcatDAQ

DewesoftX cannot use a port while its filter is off. To use DewesoftX and Synnax at the same time, connect each one to a different port. To give a port back to DewesoftX, select EthercatDAQ Filter again.

“EtherCAT is unavailable because a required packet capture library is not installed”

A task shows this message when the Driver cannot load the packet capture software. Follow the prerequisites, then restart the Driver.

“Failed to scan for devices”

The Console shows this warning when the Driver cannot scan a port. The description gives the reason, such as no raw Ethernet access. See network interface access.

“failed to reach SAFE-OP” or “failed to reach OP”

A module did not move to SAFE-OP or OP in time when the network started, or every module refused the change, so no task on the port starts. The error names each of these modules and its state. When a module refuses the change, the error also gives the error text of the module, such as “Invalid output configuration”.

Check the error text in the documentation of the module. To run the other modules now, disable the module, then start the tasks again.

“Slave … is not on the network”

A task shows this error when it uses a module that refused SAFE-OP or OP. The network started without the module, and the error gives the error text of the module. Fix the module, then stop every task on the port and start them again.

“failed to reach SAFE-OP: … Invalid DC SYNC configuration”

The module is set to a sync mode that the Driver did not set up, so it stays in PRE-OP. By default, the Driver runs SM sync when the module lists an SM sync mode, so a module that is set to DC sync and also lists an SM sync mode does not start.

• Select the mode of the module -> In the Configure dialog, set the Sync mode to the mode that the module is set to.
• Set the module to SM sync -> Dewesoft modules keep the mode in the module, and use a new mode after a power cycle. The Dewesoft manual for third-party EtherCAT masters lists the modes of each model and how to set them.
• Disable the module -> Disable it, so that the Driver stops trying to start it.

“slave … cannot run its DC mode at a bus cycle of …”

The DC sync mode of the module gives a SYNC0 or SYNC1 cycle that its registers cannot hold at the cycle rate of the network. The error gives the value and its limit. For example, the Dewesoft IOLITE 16xAO and 16xLV set SYNC1 to 1000 cycles, which is more than the 4.29 s limit when the network cycles slower than 233 Hz. Under Sync mode, enter a cycle that fits, such as a SYNC1 cycle of 1 s. You can also make the network cycle faster, for example with a write task at an execution rate of 250 Hz or more.

“slave … cannot use its chosen mode”

The sync mode of the module cannot start, so no task on the port starts. The error gives the reason, for example:

• The module does not list the mode, such as after a firmware update. The error lists the modes of the module, and the Configure dialog marks the mode. Select a mode again.
• A SYNC0 or SYNC1 cycle is set on a mode that does not run SYNC0, or on a mode in which the module sets its own clock ticks. Clear the cycles, or select a mode that takes them.

“the clock of slave … is … off the reference clock”

The clock of a module in DC sync stayed more than 10 µs off the reference clock for two seconds, so the Driver did not start SYNC0. Check the cables and the power of the modules, then start the task again.

“the bus on … cycles at … Hz while a slave runs DC sync”

The Driver sets the SYNC0 and SYNC1 cycles of a module in DC sync from the cycle rate when the network starts, so the rate stays the same while the network runs. A task that needs another rate does not start. Use a sample rate that the network rate is a multiple of, or an execution rate at or below the network rate.

To change the rate, stop every task on the port. The first task that starts again sets the rate, so start a task at a rate that every task fits first. For example, read tasks at 300 Hz and 200 Hz need 600 Hz, so first start a write task at an execution rate of 600 Hz.

“slave … maps … input and … output bits, but its discovered PDO entries hold … and …”

A task shows this error when the PDOs that the Driver found have a different size than the data that the module exchanges. The Driver does not read or write that module, so it does not give wrong values. Restart the Driver to scan again. If the error stays, the module is not supported yet.

“slave … is not on the bus” or “slave …: expected …, found …”

The network changed after you created the task. A module moved, or the Driver does not find it. Check the cables, then edit the channels of the task to use the modules that are on the network now.

For other problems, see Troubleshoot hardware.