v0.61.3
ReferenceHardwareEtherCATRead task

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

  1. 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.
  2. Set Sample rate and Stream rate.
  3. 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.

Task options

Setting Default Notes
Sample rate sample_rate 10 Hz Up to 10 kHz. A whole multiple of the stream rate.
Stream rate stream_rate 5 Hz See read tasks.
Data saving data_saving_disabled On See data saving.
Auto start auto_start Off Starts the task each time the Driver starts.

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.

Entry

Python EntryReadChannelTypeScript entry

Reads one input entry at its CoE address.

Setting Default Notes
Entry index, sub_index The CoE address, such as 0x3101:02.
Data type data_type A number type of the same size as the entry.
calibrated false Records physical values. See Dewesoft.
Scale scale None Converts raw values into engineering units. See scales.

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:

Scale type Parameters Result
"none" - The raw value
"linear" slope, offset raw × slope + offset
"map" pre_scaled_min, pre_scaled_max, scaled_min, scaled_max The raw range mapped linearly onto the scaled range
"polynomial" coeffs, from c0 up c0 + c1 × raw + c2 × raw² + ...
"table" pre_scaled_vals, scaled_vals Straight lines between the pairs, clipped at each end

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.

  1. Select the channel, then select a type in Scale: Linear, Map, Polynomial, or Table.
  2. 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.
  3. Click (Start).

Troubleshooting

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.