EtherCAT read task
Read the input PDOs of EtherCAT modules into channels.
An EtherCAT read task reads the input PDOs of one or more modules on one network into channels. For example, it can record the two analog inputs of an EL3102 module at 1 kHz.
Before you start, you need configured modules.
PDO channels
Each channel reads one entry of an input PDO, such as the value of one analog input. The
channel selects the entry by its CoE address: an index and a sub-index, such as
0x3101:02. The Console lists the entries of a module with their addresses. The entries
come from the scan and depend on the revision of the module. For example, an EL3102 can
show a Value entry at 0x3101:02 and another at 0x3102:02, one for each input.
The data type of a channel must be a number type of the same size as its entry, in whole
bytes. For example, a 16-bit entry takes int16 or uint16.
All modules in a task must be on the same port. The Sample rate sets how often the task takes a sample from the network. The network on a port cycles at a multiple of the sample rate of each read task, from 100 Hz to 10 kHz. If no such rate exists, for example for read tasks at 3 kHz and 4 kHz, the task does not start. See how the Driver runs a network.
Each sample has the time of the network cycle that read it. Without IgH, if a module on the network has a distributed clock, the Driver measures that time with the distributed clock. The timestamps then show when the EtherCAT frame passed the modules, without the jitter of the computer clock, and they stay in line with the computer clock. When the computer is busy, a cycle can still run late, and its timestamp shows the delay. See timing.
Create an EtherCAT read task
Console
Python
TypeScript
- In the devices toolbar, right-click a module and select Create read task. The task starts with a channel for each input of the module. On a module whose settings Synnax knows, such as a Dewesoft module, it starts with the measurement inputs only. To remove a channel, right-click it and select Remove.
- Set Sample rate and Stream rate.
- Click (Start).
To add a channel, click Add channel, select the module in Device, and select an entry in Entry. A new channel starts with the module of the last channel, and Data type shows the type of the entry. To add every input of a module at once, right-click one of its channels and select Add every input of module name.
The Console creates the channels and names them after the identifier of the module and
the name of the entry, such as ai1_Value for a module with the identifier ai1. If
the module has more than one entry with that name, the Console adds the PDO name, or the
address when the module gives no PDO name, such as ai1_Value_3101_02. The name of a
scaled channel ends in _scaled. The index channel is ai1_time.
When you start the task, the Console uses channels that already exist where it can. It
uses an index channel named <identifier>_time. It also uses a channel with the default
name that a deleted device left, when the channel has the same index and no other module
records into it. Otherwise, a channel name that is in use stops the deploy with an
error.
Starting or stopping a task does not restart the network. The other tasks on the port keep running.
Python does not create channels. Create them first.
import synnax as sy
from synnax import ethercat
module = client.devices.retrieve(key="<module key>")
time = client.channels.create(
name="ai1_time", is_index=True, data_type=sy.DataType.TIMESTAMP
)
ch1 = client.channels.create(
name="ai1_ch1", index=time.key, data_type=sy.DataType.INT16
)
ch2 = client.channels.create(
name="ai1_ch2", index=time.key, data_type=sy.DataType.INT16
)
task = ethercat.ReadTask(
name="Analog inputs",
sample_rate=1000,
stream_rate=25,
channels=[
ethercat.EntryReadChannel(
device=module.key,
index=0x3101,
sub_index=0x02,
data_type=sy.DataType.INT16,
channel=ch1.key,
),
ethercat.EntryReadChannel(
device=module.key,
index=0x3102,
sub_index=0x02,
data_type=sy.DataType.INT16,
channel=ch2.key,
),
],
)
client.tasks.configure(task)
task.start()To find an entry by its name, use ethercat.find_entry(module, "<name>"). It returns
the index, sub_index, and data_type of the entry. It raises sy.NotFoundError if
no entry has the name, and sy.MultipleFoundError if entries at more than one address
have it. To select one of them, also pass pdo_name, the name of the PDO that holds the
entry, such as "Channel 1".
TypeScript does not create channels. Create them first.
import { ethercat } from "@synnaxlabs/client";
const module = await client.devices.retrieve({ key: "<module key>" });
const time = await client.channels.create({
name: "ai1_time",
isIndex: true,
dataType: "timestamp",
});
const ch1 = await client.channels.create({
name: "ai1_ch1",
index: time.key,
dataType: "int16",
});
const task = await client.tasks.create({
name: "Analog inputs",
rack: module.rack,
type: "ethercat_read",
config: ethercat.readConfigZ.parse({
sampleRate: 1000,
streamRate: 25,
channels: [
{
type: "entry",
device: module.key,
index: 0x3101,
subIndex: 0x02,
dataType: "int16",
channel: ch1.key,
},
],
}),
});
await task.start();To find an entry by its name, use ethercat.findEntry(inputs, "<name>"), where inputs
is pdos.inputs of the device properties. It throws NotFoundError if no entry has the
name, and MultipleFoundError if entries at more than one address have it. To select
one of them, pass the name of the PDO that holds the entry as the third argument.
Task options
TypeScript uses the same fields in camel case, such as sampleRate.
Channel reference
Each channel has a device, the key of the module (Device), and a channel, the
Synnax channel that records the value. Each table shows the Console label of a setting,
with its Python field under it.
A task from an earlier release can also hold an unresolved channel
(UnresolvedReadChannel). It has the name of an entry, but no address. See
troubleshooting.
Scales
A scale converts the raw value of an entry into engineering units:
A scaled channel writes float values, so its Synnax channel must be float32 or
float64. The Console creates a float64 channel for it, apart from the raw channel,
and its name ends in _scaled.
Some Dewesoft modules send raw counts. The Driver turns them into physical values before the scale.
Console
Python
TypeScript
- Select the channel, then select a type in Scale: Linear, Map, Polynomial, or Table.
- Enter the values of the scale:
- Linear -> Slope and Offset.
- Map -> Pre-scaled min, Pre-scaled max, Scaled min, and Scaled max.
- Polynomial -> the Coefficients, from c0 up.
- Table -> the pairs of raw and scaled values.
- Click (Start).
ethercat.EntryReadChannel(
device=module.key,
index=0x3101,
sub_index=0x02,
data_type=sy.DataType.INT16,
channel=volts.key, # a float64 channel
# Counts to volts for a ±10 V input
scale=sy.task.LinearScale(slope=10 / 32767, offset=0),
)const channel = {
type: "entry",
device: module.key,
index: 0x3101,
subIndex: 0x02,
dataType: "int16",
channel: volts.key, // a float64 channel
// Counts to volts for a ±10 V input
scale: { type: "linear", slope: 10 / 32767, offset: 0 },
};Troubleshooting
- Cause
Earlier releases could select an entry by its name. If the module has more than one entry with that name, or none, the upgrade cannot find the address of the entry. The Console marks the channel, and the task does not start. The error can also read “… matches no input entry …”.
- Fix
Select an entry for the channel in Entry. The first entry in the list with that name is the one that the task read before, and it keeps the old channel.
- Cause
A channel has no entry selected.
- Fix
Select an entry in Entry, or remove the channel.
- Cause
The module has no input entry at the address of the channel.
- Fix
Select an entry from the list again. In code, use an address that the Console lists, or find the entry by its name.
- Cause
The data type of the channel has a different size from the entry. The Console shows the first message, and the Driver shows the second for a task from code.
- Fix
Select a number type of the same size, such as
int16for a 16-bit entry.
- Cause
A scaled or calibrated channel writes float values, but its Synnax channel holds integers.
- Fix
Configure the task in the Console again. The Console creates a
float64channel. In code, use afloat32orfloat64channel.
- Cause
Two channels of the task use the same entry.
- Fix
Select a different entry for one of them.
- Cause
The name of a new channel is in use, by a channel that the Console cannot use for this entry or by another channel of the task.
- Fix
Set another name in Channel.
- Cause
The index channel name
<identifier>_timebelongs to another module, or to a channel that is not an index.- Fix
Change the identifier of the module.
- Cause
A channel that the task uses again has a different data type from the channel of the task.
- Fix
Set the data type to the one that the message names, or delete the old channel so that the task can create it again.
- Cause
The stream rate is above the sample rate, or the sample rate is not a whole multiple of the stream rate.
- Fix
Set a sample rate that is a whole multiple of the stream rate, such as 1000 Hz and 25 Hz.
- Cause
The sample rates of the read tasks on the port have no common multiple at or below 10 kHz.
- Fix
Use sample rates with a small common multiple, such as 250 Hz and 1 kHz.
- Cause
A module on the port stopped responding, so every network cycle fails. Every read task on the port shows this warning and pauses. The task keeps trying, at most 5 seconds apart, and its data starts again when the module responds.
- Fix
The module status shows which module is lost. Check its power and its cable.
For errors that stop every task on a port, such as Failed to reach SAFE-OP or
No EtherCAT slaves found on ..., see
Troubleshoot EtherCAT.