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.
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.
- Linux and macOS -> nothing to install.
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.
The Core’s Docker image runs as a user without these permissions, so its embedded Driver cannot run EtherCAT tasks.
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-driverWith 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 $USERA 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. To scan again, restart the Driver. 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.
- 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.
- Outputs -> Each output holds the last value a write task commanded. When a write task stops, its outputs go to zero. An output that another running write task commanded keeps the last value of that task instead.
- 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
Console
Python
TypeScript
- 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.
- Enter a Name and an Identifier, or click one of the identifiers that the Console suggests.
- Click Save. To also open a read task for the module, click Save and create read task.
Configure each module that a task uses.
Find modules and list their PDOs:
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"])Configure modules in the Console.
Find modules and list their PDOs:
for (const module of await client.devices.retrieve({ makes: ["ethercat"] })) {
const { network, position, pdos } = module.properties;
console.log(module.name, network, position, JSON.stringify(pdos));
}Configure modules in the Console. TypeScript returns device properties in camel case.
Disable a device
Disable a module to leave it out of the network, for example when it is not cabled yet.
Console
Python
TypeScript
- In the devices toolbar, right-click the module and select Disable. To disable several modules, select them first.
- 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.
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);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
- Check the cable from the port to the first module, and the power to the modules.
- Make sure that no other program uses the port.
- Check the prerequisites and the network interface access, then restart the Driver.
“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.
“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.
“device … expected at position … not found on bus”
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.