# 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](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device).

## 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](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#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](https://docs.synnaxlabs.com/reference/hardware/tasks#timing).

## Create an EtherCAT read task

**Console**

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](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#scales) 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](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#troubleshooting).

Starting or stopping a task does not restart the network. The other tasks on the port keep running.

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/hardware/ethercat/read-task/bdadbebc2147-dark.mp4#t=0.001)

**Python**

Python does not create channels. Create them first.

```python
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**

TypeScript does not create channels. Create them first.

```typescript
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

| 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](https://docs.synnaxlabs.com/reference/hardware/tasks#read-tasks).   |
| Data saving `data_saving_disabled` | On      | See [data saving](https://docs.synnaxlabs.com/reference/hardware/tasks#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**

#### [Entry](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#entry)

Python `EntryReadChannel`TypeScript `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](https://docs.synnaxlabs.com/reference/hardware/ethercat/dewesoft#physical-values).          |
| Scale `scale`              | None    | Converts raw values into engineering units. See [scales](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#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](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#a-channel-from-an-earlier-release-has-no-entry).

### 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](https://docs.synnaxlabs.com/reference/hardware/ethercat/dewesoft#physical-values) before the scale.

**Console**

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**).

**Python**

```python
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),
)
```

**TypeScript**

```typescript
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

* [... matches more than one input entry ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#a-channel-from-an-earlier-release-has-no-entry)

  * 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.

* [A channel on slave ... has no entry. Pick an entry.](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#a-channel-on-slave-has-no-entry-pick-an-entry)

  * Cause

    A channel has no entry selected.

  * Fix

    Select an entry in **Entry**, or remove the channel.

* [Slave ... has no input entry at ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#slave-has-no-input-entry-at)

  * 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.

* [Data type ... does not fit entry ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#data-type-does-not-fit-entry)[data type ... is ... but entry ... holds ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#data-type-does-not-fit-entry)

  * 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 `int16` for a 16-bit entry.

* [channel ... is ..., but a ... channel must be float32 or float64](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#channel-is-but-a-channel-must-be-float32-or-float64)

  * 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 `float64` channel. In code, use a `float32` or `float64` channel.

* [More than one channel uses entry ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#more-than-one-channel-uses-entry)[another channel already uses entry ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#more-than-one-channel-uses-entry)

  * Cause

    Two channels of the task use the same entry.

  * Fix

    Select a different entry for one of them.

* [A channel named ... already exists. Give the channel another name.](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#a-channel-named-already-exists-give-the-channel-another-name)[Two channels of the task use the name ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#a-channel-named-already-exists-give-the-channel-another-name)

  * 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**.

* [Slave ... uses the index channel ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#slave-uses-the-index-channel)[A channel named ... already exists and is not an index](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#slave-uses-the-index-channel)

  * Cause

    The index channel name `<identifier>_time` belongs to another module, or to a channel that is not an index.

  * Fix

    Change the [identifier](https://docs.synnaxlabs.com/reference/hardware/devices#identifiers) of the module.

* [Channel ... holds ... data, not ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#channel-holds-data-not)

  * 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.

* [Stream rate must be less than or equal to the sample rate](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#stream-rate-must-be-less-than-or-equal-to-the-sample-rate)[sample_rate must be divisible by stream_rate](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#stream-rate-must-be-less-than-or-equal-to-the-sample-rate)

  * 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.

* [No bus rate at or below 10000 Hz ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#no-bus-rate-at-or-below-10000-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.

* [Failed to read data](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#failed-to-read-data)

  * 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](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#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](https://docs.synnaxlabs.com/reference/hardware/ethercat/troubleshooting).
