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.
Console
Python
TypeScript
- 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.
- Set Execution rate and State update 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 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.
Python does not create channels. Create them first.
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 does not create channels. Create them first.
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
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.
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
- 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.
- 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.
- 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.
- 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
uint8for a 1-bit output.
- 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.
- 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.
- 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 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.
- Cause
The state index name
<identifier>_state_timebelongs to another module, or to a channel that is not an index.- Fix
Change the identifier 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.