# Configure an EtherCAT device > Connect an EtherCAT network to the Driver and configure its modules. [EtherCAT](https://www.ethercat.org/) 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](https://docs.synnaxlabs.com/reference/hardware/ethercat/dewesoft). ## 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](https://npcap.com/#download). The default install options work. If DewesoftX is installed, [turn off its network filter](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#no-modules-show-on-a-computer-with-dewesoftx) on the port for Synnax. * **Linux** and **macOS** -> nothing to install. Enterprise On Linux, if the [IgH EtherCAT Master](https://etherlab.org/en_GB/ethercat) 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](https://npcap.com/#download). | | macOS | Root access, because only root can open the packet capture devices (`/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: ```bash 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: ```bash 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](https://docs.synnaxlabs.com/reference/hardware/devices#devices-toolbar) under its Driver: * **Name** -> the name stored in the module, such as `EL3102`, or “EtherCAT Slave \”. * **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](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#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”](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#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. ## 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. | | **Not responding** | The module does not answer. Check its power and cabling. | | **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**. ## Configure a device [Enterprise](https://docs.synnaxlabs.com/reference/get-started/editions "Needs Synnax Enterprise") **Console** 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. Enter a **Name** and an [**Identifier**](https://docs.synnaxlabs.com/reference/hardware/devices#identifiers), or click one of the identifiers that the Console suggests. 3. To run the module in a mode other than the default, set its [**Sync mode**](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#sync-mode). 4. Click **Save**. To also open a read task for the module, click **Save and create read task**. Configure each module that a task uses. [](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/device-drivers/ethercat/configure-device/ethercat-configure/def9acd71867-dark.mp4#t=0.001) **Python** Find modules and list their PDOs: ```python 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. **TypeScript** Find modules and list their PDOs: ```typescript 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)); } ``` Configure modules in the Console. TypeScript returns device properties in camel case. ## 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. 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](https://docs.synnaxlabs.com/reference/hardware/troubleshooting#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. [Enterprise](https://docs.synnaxlabs.com/reference/get-started/editions "Needs Synnax Enterprise") **Console** 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**. **Python** ```python module = client.devices.retrieve(key="") module.properties["enabled"] = False client.devices.create(module) ``` **TypeScript** ```typescript const module = await client.devices.retrieve({ 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. | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------ | | `index` | number | | - | CoE object index (`0x0000` to `0xFFFF`) | | `sub_index` | number | | - | CoE object subindex (`0` to `255`) | | `data_type` | string | | - | `int8` to `int64`, `uint8` to `uint64`, `float32`, or `float64` | | `value` | number | | - | The value to write. It must fit in `data_type`. An integer must be between -9007199254740991 and 9007199254740991. | | `name` | string | | `""` | A label that error messages show | * **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. [Enterprise](https://docs.synnaxlabs.com/reference/get-started/editions "Needs Synnax Enterprise") **Console** 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. **Python** ```python module = client.devices.retrieve(key="") module.properties["startup_parameters"] = [ { "index": 0x8000, "sub_index": 0x15, "data_type": "uint16", "value": 1, "name": "Filter settings", }, ] client.devices.create(module) ``` **TypeScript** ```typescript const module = await client.devices.retrieve({ key: "" }); module.properties.startupParameters = [ { index: 0x8000, subIndex: 0x15, dataType: "uint16", value: 1, name: "Filter settings", }, ]; await client.devices.create(module); ``` ## Device properties | Property | Meaning | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | The name stored in 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](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#disable-a-device). | | `startup_parameters` | CoE values that the Driver writes to the module when the network starts. See [startup parameters](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#startup-parameters). | | `pdos.inputs`, `pdos.outputs` | The PDO entries of the module. See below. | 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](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#no-modules-show-on-a-computer-with-dewesoftx). 3. Check the [prerequisites](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#prerequisites) and the [network interface access](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#network-interface-access), then [restart the Driver](https://docs.synnaxlabs.com/reference/hardware/troubleshooting#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: ```powershell 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](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#prerequisites), then [restart the Driver](https://docs.synnaxlabs.com/reference/hardware/troubleshooting#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](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#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](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#disable-a-device) 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**](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#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](https://downloads.dewesoft.com/manuals/dewesoft-3rd-party-ethercat-masters-manual.pdf) lists the modes of each model and how to set them. * **Disable the module** -> [Disable](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#disable-a-device) 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**](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#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](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#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](https://docs.synnaxlabs.com/reference/hardware/troubleshooting#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](https://docs.synnaxlabs.com/reference/hardware/troubleshooting).