v0.61.3
ReferenceHardwareEtherCATWrite task

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.

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.

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.

  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.

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

Python EntryWriteChannelTypeScript 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.

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.