# EtherCAT write task

> Write command channel values to the output PDOs of EtherCAT modules.

An EtherCAT write task writes the values of command channels to the output PDOs of one or more modules on one network. For example, a valve on a schematic can switch an output of an EL2004 module.

Each output also has a state channel. The state channel shows the last command that the task wrote. The Driver does not read the state back from the module.

Before you start, you need [configured modules](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device).

## PDO channels

Each channel writes one entry of an output PDO. The channel selects the entry by its CoE address: an index and a sub-index. The Console lists the entries of a module with their addresses. For example, an EL2004 names all four outputs `Output`, at `0x7000:01`, `0x7010:01`, `0x7020:01`, and `0x7030:01`.

The data type of a channel must be a number type of the same size as its entry, in whole bytes. Each EL2004 output is 1 bit, so it takes `uint8` or `int8`. An entry under 8 bits holds an unsigned value with either type, so its stop value on an EL2004 is 0 or 1.

All modules in a task must be on the same port. The network cycles at least as fast as the **Execution rate**, so a higher rate sends new commands to the modules sooner.

When the task stops, the Driver sends the **Stop value** of each channel to the modules before they leave the operational state. While other tasks keep the network running, the entry holds its stop value until a task commands it. After the modules leave the operational state, each module sets its outputs to its own safe value, which is often 0. An integer entry needs a whole number that fits it, from -9007199254740991 to 9007199254740991. See [how the Driver runs a network](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device#how-the-driver-runs-a-network).

## Create an EtherCAT write task

When you create command channels with a client library, give each one its own index channel. A writer that holds several commands on one index must write all of them in every frame.

**Console**

1. In the devices toolbar, right-click a module and select **Create write task**. The task starts with a channel for each output of the module. To remove a channel, right-click it and select **Remove**.
2. Set **Execution rate** and **State update 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 output of a module at once, right-click one of its channels and select **Add every output of** *module name*.

The Console creates a command channel and a state channel for each output. It names them after the identifier of the module and the name of the entry. 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. For a module with the identifier `do1` and no PDO names, the `Output` entry at `0x7000:01` gives `do1_Output_7000_01_cmd`, `do1_Output_7000_01_cmd_time`, and `do1_Output_7000_01_state`, with the index `do1_state_time`.

When you start the task, the Console uses channels that already exist where it can. It uses a state index named `<identifier>_state_time`, and a command index named `<command name>_cmd_time` for a command channel with the default name. 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 writes to it. It never reuses a command channel with a name that you chose. Otherwise, a channel name that is in use stops the deploy with an [error](https://docs.synnaxlabs.com/reference/hardware/ethercat/write-task#troubleshooting).

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/hardware/ethercat/write-task/e45f759640c4-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>")
cmd_time = client.channels.create(
    name="valve_1_cmd_time", is_index=True, data_type=sy.DataType.TIMESTAMP
)
cmd = client.channels.create(
    name="valve_1_cmd", index=cmd_time.key, data_type=sy.DataType.UINT8
)
state_time = client.channels.create(
    name="do1_state_time", is_index=True, data_type=sy.DataType.TIMESTAMP
)
state = client.channels.create(
    name="valve_1_state", index=state_time.key, data_type=sy.DataType.UINT8
)

task = ethercat.WriteTask(
    name="Valves",
    channels=[
        ethercat.EntryWriteChannel(
            device=module.key,
            index=0x7000,
            sub_index=0x01,
            data_type=sy.DataType.UINT8,
            cmd_channel=cmd.key,
            state_channel=state.key,
        )
    ],
)
client.tasks.configure(task)
task.start()
```

To find an entry by its name, use `ethercat.find_entry(module, "<name>", direction="output")`. 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.

**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 cmdTime = await client.channels.create({
  name: "valve_1_cmd_time",
  isIndex: true,
  dataType: "timestamp",
});
const cmd = await client.channels.create({
  name: "valve_1_cmd",
  index: cmdTime.key,
  dataType: "uint8",
});

const task = await client.tasks.create({
  name: "Valves",
  rack: module.rack,
  type: "ethercat_write",
  config: ethercat.writeConfigZ.parse({
    channels: [
      {
        type: "entry",
        device: module.key,
        index: 0x7000,
        subIndex: 0x01,
        dataType: "uint8",
        cmdChannel: cmd.key,
      },
    ],
  }),
});
await task.start();
```

In code, the state channel is optional. With no state channel, the task does not report the output value.

To find an entry by its name, use `ethercat.findEntry(outputs, "<name>")`, where `outputs` is `pdos.outputs` 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                                                                                |
| ---------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| Execution rate `execution_rate`    | 1000 Hz | The lowest rate of the network on the port. Up to 10 kHz.                            |
| State update rate `state_rate`     | 25 Hz   | How often the task writes the state channels.                                        |
| 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 `executionRate`.

## Channel reference

Each channel has a `device`, the key of the module (**Device**), a `cmd_channel`, and a `state_channel`. A `state_channel` of 0 means no state channel. Each table shows the Console label of a setting, with its Python field under it.

**Entry**

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

Python `EntryWriteChannel`TypeScript `entry`

Writes one output entry at its CoE address.

| Setting                    | Default | Notes                                          |
| -------------------------- | ------- | ---------------------------------------------- |
| Entry `index`, `sub_index` |         | The CoE address, such as `0x7000:01`.          |
| Data type `data_type`      |         | A number type of the same size as the entry.   |
| Stop value `stop_value`    | 0       | The value the entry takes when the task stops. |

A task from an earlier release can also hold an `unresolved` channel (`UnresolvedWriteChannel`). It has the name of an entry, but no address. See [troubleshooting](https://docs.synnaxlabs.com/reference/hardware/ethercat/write-task#a-channel-from-an-earlier-release-has-no-entry).

## Troubleshooting

* [... matches more than one output entry ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/write-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 output 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 wrote before, and it keeps the old channels.

* [Found no device with key ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/write-task#found-no-device-with-key)[A channel on slave ... has no entry. Pick an entry.](https://docs.synnaxlabs.com/reference/hardware/ethercat/write-task#found-no-device-with-key)

  * Cause

    A channel has no module or no entry selected, such as the empty channel that the task opens with.

  * Fix

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

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

  * Cause

    The module has no output 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/write-task#data-type-does-not-fit-entry)[data type ... is ... but entry ... holds ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/write-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 `uint8` for a 1-bit output.

* [data type float32 needs a 32 bit entry, but entry ... holds ... bits. Pick an integer type.](https://docs.synnaxlabs.com/reference/hardware/ethercat/write-task#data-type-float32-needs-a-32-bit-entry-but-entry-holds-bits-pick)

  * Cause

    A float data type is on an output entry with fewer bits than the type.

  * Fix

    Select an integer type of the same size as the entry.

* [stop value ... does not fit entry ... on slave .... Pick ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/write-task#stop-value-does-not-fit-entry-on-slave-pick)

  * Cause

    The **Stop value** of a channel is out of range for its entry, or it is not a whole number for an integer entry. The message gives the range that fits.

  * Fix

    Set a **Stop value** in the range that the message gives.

* [More than one channel uses entry ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/write-task#more-than-one-channel-uses-entry)[another channel already uses entry ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/write-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/write-task#a-channel-named-already-exists-give-the-channel-another-name)[Channel ... holds ... data, not ...](https://docs.synnaxlabs.com/reference/hardware/ethercat/write-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 a channel with another data type.

  * Fix

    Set another name for the channel, or delete the old channel so that the task can create it again.

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

  * Cause

    The state index name `<identifier>_state_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.

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