Configure an EtherCAT Device
Learn how to discover and configure EtherCAT devices.
Prerequisites
Before configuring EtherCAT devices, ensure you have:
- A Synnax Core running on your network.
- A Synnax Driver running on the same machine as your EtherCAT network interface.
- An EtherCAT master configured (IgH kernel module or SOEM).
- The Synnax Console installed on your local machine.
All channels in a task must use devices connected to the same network interface. If you have devices on multiple EtherCAT networks, create separate tasks for each network.
How Device Discovery Works
EtherCAT devices are automatically discovered when connected to the network. There is no need to manually create device configurations.
- Connect your EtherCAT devices to the network interface.
- The Synnax Driver scans the EtherCAT bus and discovers all connected devices.
- A notification appears in the Console when new devices are found.
- Discovered devices appear in the Devices Toolbar.
The scan task runs periodically to detect new devices and update device information.
Device Properties Reference
When a device is discovered, Synnax stores the following properties:
Understanding PDOs
PDOs (Process Data Objects) define the cyclic data exchanged between the master and devices. PDOs are configured in the device’s ESI (EtherCAT Slave Information) file.
TxPDO (Transmit PDO)
Data transmitted FROM the device TO Synnax. Use TxPDOs in Read Tasks to acquire sensor data, status information, and feedback values.
RxPDO (Receive PDO)
Data received BY the device FROM Synnax. Use RxPDOs in Write Tasks to send control commands, setpoints, and configuration values.
PDO Entry Properties
Each PDO entry has the following properties:
Enabling and Disabling Devices
The enabled property controls whether a device participates in cyclic PDO exchange. By
default, all discovered devices are enabled.
What Happens When a Device is Disabled
When you disable a device:
- The device is excluded from cyclic PDO exchange. The EtherCAT master skips the device during the process data cycle.
- The device status changes to Disabled in the Console.
- The device must still be physically present on the bus. EtherCAT topology validation requires all configured devices to be connected.
- Tasks cannot read from or write to PDOs on disabled devices. Channels associated with disabled devices will not receive data.
Common Use Cases
- Troubleshooting: Isolate a problematic device without physically disconnecting it from the bus.
- Maintenance: Temporarily disable a device undergoing maintenance or calibration.
- Staged commissioning: Enable devices incrementally during system setup and testing.
- Fault isolation: Disable a device that’s causing bus errors to keep other devices operational.
- Reducing cycle time: Exclude unused devices to minimize PDO exchange overhead.
Disabling a Device
To disable an EtherCAT device:
- Open the Devices Toolbar by clicking the device icon () on the left side of the screen.
- Right-click on the device you want to disable.
- Select Disable from the context menu.
The device status will update immediately. You can also select multiple devices and disable them all at once.
import synnax as sy
import json
client = sy.Synnax()
# Retrieve the device
device = client.devices.retrieve(name="EL3102")
# Parse properties (stored as JSON string in Python client)
props = json.loads(device.properties)
# Disable the device
props["enabled"] = False
device.properties = json.dumps(props)
# Update the device
client.devices.create(device)import { Synnax } from "@synnaxlabs/client";
const client = new Synnax();
// Retrieve the device
const device = await client.devices.retrieve({ name: "EL3102" });
// Disable the device
device.properties.enabled = false;
// Update the device
await client.devices.create(device);Re-enabling a Device
To re-enable a disabled EtherCAT device:
- Open the Devices Toolbar by clicking the device icon () on the left side of the screen.
- Right-click on the disabled device.
- Select Enable from the context menu.
import synnax as sy
import json
client = sy.Synnax()
# Retrieve the device
device = client.devices.retrieve(name="EL3102")
# Parse properties
props = json.loads(device.properties)
# Re-enable the device
props["enabled"] = True
device.properties = json.dumps(props)
# Update the device
client.devices.create(device)import { Synnax } from "@synnaxlabs/client";
const client = new Synnax();
// Retrieve the device
const device = await client.devices.retrieve({ name: "EL3102" });
// Re-enable the device
device.properties.enabled = true;
// Update the device
await client.devices.create(device);How-To
Synnax automatically discovers EtherCAT devices when they are connected to the network. To view discovered devices, open the Devices Toolbar by clicking the device icon () on the left side of the screen.
import synnax as sy
# Connect to Synnax
client = sy.Synnax()
# List all devices to find EtherCAT devices
all_devices = client.devices.list()
# Filter for EtherCAT devices
ethercat_devices = [d for d in all_devices if d.make == "EtherCAT"]
for dev in ethercat_devices:
print(f"Device: {dev.name}")
print(f" Key: {dev.key}")
print(f" Network: {dev.location}")
print(f" Position: {dev.properties.get('position')}")
print(f" Vendor ID: {dev.properties.get('vendorId')}")
print(f" Product Code: {dev.properties.get('productCode')}")
# Retrieve a specific device by name
device = client.devices.retrieve(name="EK1100")
# Access PDO information
pdos = device.properties.get("pdos", {})
tx_pdos = pdos.get("inputs", []) # Input PDOs (device -> Synnax)
rx_pdos = pdos.get("outputs", []) # Output PDOs (Synnax -> device)
print(f"\nTxPDOs (inputs) for {device.name}:")
for pdo in tx_pdos:
print(f" {pdo['name']}: index=0x{pdo['index']:04X}, "
f"subindex={pdo['subIndex']}, type={pdo['dataType']}")
print(f"\nRxPDOs (outputs) for {device.name}:")
for pdo in rx_pdos:
print(f" {pdo['name']}: index=0x{pdo['index']:04X}, "
f"subindex={pdo['subIndex']}, type={pdo['dataType']}")import { Synnax } from "@synnaxlabs/client";
// Connect to Synnax
const client = new Synnax();
// List all devices to find EtherCAT devices
const allDevices = await client.devices.list();
// Filter for EtherCAT devices
const ethercatDevices = allDevices.filter((d) => d.make === "EtherCAT");
for (const dev of ethercatDevices) {
console.log(`Device: ${dev.name}`);
console.log(` Key: ${dev.key}`);
console.log(` Network: ${dev.location}`);
console.log(` Position: ${dev.properties?.position}`);
console.log(` Vendor ID: ${dev.properties?.vendorId}`);
console.log(` Product Code: ${dev.properties?.productCode}`);
}
// Retrieve a specific device by name
const device = await client.devices.retrieve({ name: "EK1100" });
// Access PDO information
const pdos = device.properties?.pdos ?? {};
const txPdos = pdos.inputs ?? []; // Input PDOs (device -> Synnax)
const rxPdos = pdos.outputs ?? []; // Output PDOs (Synnax -> device)
console.log(`\nTxPDOs (inputs) for ${device.name}:`);
for (const pdo of txPdos) {
console.log(
` ${pdo.name}: index=0x${pdo.index.toString(16).padStart(4, "0")}, ` +
`subindex=${pdo.subIndex}, type=${pdo.dataType}`,
);
}
console.log(`\nRxPDOs (outputs) for ${device.name}:`);
for (const pdo of rxPdos) {
console.log(
` ${pdo.name}: index=0x${pdo.index.toString(16).padStart(4, "0")}, ` +
`subindex=${pdo.subIndex}, type=${pdo.dataType}`,
);
}