v0.61.3
ReferenceHardwareTasks

Tasks

Read tasks, write tasks, timing, data saving, and the task lifecycle.

A task is a job that the Driver runs on one or more devices. A read task records the values of inputs in channels. A write task sends the values that you write to command channels to outputs. Synnax stores the configuration of each task, so you can stop a task and start it again later.

Each task type has its own page in the vendor groups of this section, such as the NI analog read task or the Modbus write task. To start and stop tasks, see Start and stop tasks.

Read tasks

Deviceinputs
Read taskon the Driver
Channelsin the Core
Readersplots, Arc, code
Deviceinputs
Read taskon the Driver
Channelsin the Core
Readersplots, Arc, code

A read task samples its inputs at the Sample rate. It sends the samples to the Core in batches at the Stream rate. Each batch holds the sample rate divided by the stream rate samples for each channel. For example, a task that samples at 100 Hz and streams at 10 Hz sends batches of 10 samples.

The stream rate must be equal to or less than the sample rate. A higher stream rate shows new values sooner, but sends more batches. The HTTP read task has one Rate field instead of the two rates.

Write tasks

Writerschematic, Arc, code
Command channelin the Core
Write taskon the Driver
Deviceoutputs
State channelin the Core
Writerschematic, Arc, code
Command channelin the Core
Write taskon the Driver
Deviceoutputs
State channelin the Core

Command channels

Each output of a write task has a command channel. When a writer, such as a schematic, an Arc automation, or client code, writes a value to the command channel, the task sends the value to the output. To control which writer can send commands, see control authority.

State channels

NI, LabJack, and EtherCAT write tasks also have a state channel for each output. After the task sends a command to the output, it writes the same value to the state channel. A schematic valve can show the state channel, so it shows the value that the Driver sent, not only the value that you clicked.

The state channel holds the last value that the Driver sent. It is not a measurement of the output. If a LabJack write fails, the state channel keeps the old value. An NI analog write that is out of range is an exception: see the outputs stop changing. The task writes the state channels at the State update rate, and also right after each command.

Outputs with no state channel

Modbus, OPC UA, and HTTP write tasks have no state channels. To see the value of an output, read it back with a read task, such as a Modbus read task on the same register.

For the names of command and state channels, see channels that tasks create.

Timing

A hardware timed task uses the clock on the device. The Driver gives each sample a timestamp from the start of the batch and the sample rate. A software timed task has no device clock, so the Driver gives the samples timestamps from the computer clock when it reads them:

  • Hardware timed -> NI analog read, and LabJack read, except a LabJack T7 task with thermocouple channels.
  • Software timed -> NI digital read, NI counter read, LabJack T7 read with thermocouple channels, EtherCAT read, Modbus read, OPC UA read, HTTP read, MQTT read, Kafka read, and every write task.

An HTTP read task can also take its timestamps from the server response. See endpoints and fields. An EtherCAT read task can take its timestamps from the distributed clock of its modules. See PDO channels. The MQTT read task and the Kafka read task can take their timestamps from the message.

A hardware timed task that samples at 100 Hz and streams at 10 Hz gives these timestamps:

Sample Time (s) Batch
0 0.00 First
1 0.01 First
… … …
9 0.09 First
10 0.10 Second
11 0.11 Second

The device clock and the computer clock drift apart over time. The Driver corrects the spacing between samples, so hardware timed samples stay in line with the computer clock and with software timed tasks on the same Driver. For example, the commands from a digital write task stay in line with the analog samples that they caused. Skew correction is on by default. To turn it off on a standalone Driver, see the Driver configuration.

Channels

The task tab lists the channels of the task. A new task starts with one channel. To add another, click Add channel. Select a channel to change its settings.

Each channel has a check box. Clear it to disable the channel. The task keeps the settings of a disabled channel, but does not read or write it. A task needs at least one enabled channel. If you disable all of them, Start shows “At least one enabled channel is required”.

An icon next to the name of a channel shows when its Synnax channel does not exist:

State Meaning
New channel The channel does not exist yet. Starting the task creates it. Starting the task does not create a disabled channel.
Channel not found The channel was deleted. Starting the task creates a new channel with the same name. In a task where you select an existing channel, such as a Kafka write task, select another.

Ports

NI and LabJack tasks show the ports of their devices as a grid:

  • NI analog read, NI analog write, NI counter read, and LabJack read -> select Ports above the channel list to see the channels by port. Select List to go back.
  • NI digital read, NI digital write, and LabJack write -> a map of the lines or ports shows above the channel list.

Click a used port to select its channel. Click a free port to add a channel on it, or right-click the free port and select Add channel. A port that two enabled channels use shows a conflict. A port that only disabled channels use shows faded.

In the settings of a channel, Port shows the same grid. Click a port to move the channel to it.

In the Ports view of an NI analog read or counter read task, Add device adds another configured device of the same Driver. To remove a device and its channels, right-click the device and select Remove device.

Data saving

With Data saving off, a task sends live values to plots and other readers, but the Core does not store them. Turn data saving off to try a setup without storing its data. On a write task, data saving applies to the state channels. Read tasks and the NI, LabJack, and EtherCAT write tasks use Data saving. The Modbus and OPC UA write tasks show the toggle, but they have no state channels, so it has no effect.

To change data saving for a task, use the Data saving toggle at the bottom of the task tab. You can also click the data saving button of the task in the tasks toolbar, or right-click the task and select Enable data saving or Disable data saving. The toolbar restarts a running task, so the change applies at once.

Task lifecycle

A new task is a draft. Its status is “Task not deployed”. The task tab saves each edit as you make it.

When you click Start in the task tab, the Console checks the configuration and creates the channels that the task needs. The Driver then builds the task and starts it. When you stop a task, the Driver stops reading and writing, and Synnax keeps the configuration.

Edits to a running task do not apply until you redeploy it. With Auto start on, the task starts each time the Driver starts.

More than one user can edit a task at the same time. Each user sees the edits of the others in the open task tab. If another user changes the task after you last saw it, the Driver refuses your start with “Config changed”. Review the task, then start it again.

Status Meaning
Task not deployed The task is a draft. It has never started.
Sending start command, Sending stop command The Console sent the command and waits for the Driver.
Started task, Task running The task is running.
Stopped task The task stopped.
Config changed Another user changed the task after you saw it. The Driver did not start it.
Task is not running The Driver got a command, such as a tare, for a task that it does not run. Start the task, then retry.
Task status unknown, No status The Core has no status for the task.

The status shows at the bottom of the task tab. Click it to see the details and to copy them with Copy diagnostics. For device and Driver statuses, see Devices.

Task options

Each task page lists the options that its task has.

Console label Python field TypeScript field Default
Sample rate sample_rate sampleRate 10 Hz, 50 Hz (OPC UA)
Stream rate stream_rate streamRate 5 Hz, 25 Hz (OPC UA)
State update rate state_rate stateRate 10 Hz (NI, LabJack), 25 Hz (EtherCAT)
Data saving data_saving_disabled dataSavingDisabled On (field false)
Auto start auto_start autoStart Off

Data saving and Auto start are toggles at the bottom of the task tab, next to the status.

Tasks toolbar

To open the tasks toolbar, click in the left bar or press T. Each task shows its status, name, and type, a button to start or stop it, and a data saving button for a task that has data saving. To create a task, click (Create task). Double-click a task to open it in a tab.

Right-click a task to open its menu:

Item What it does
Start, Stop Starts or stops the selected tasks.
Redeploy Applies saved edits to a running task. It shows only when edits are waiting.
Edit configuration Opens the task in a tab.
Rename Changes the task name.
Enable data saving, Disable data saving Turns data saving on or off.
Snapshot to <range> Saves a copy of the task to the active range.
Export Saves the task as a JSON file. Run the “Import components” command to load it.
Copy link Copies a link to the task. Not in Synnax Desktop.
Delete Deletes the task.

The task tab has buttons to Copy Python code, Copy TypeScript code, Copy JSON configuration, Copy link (not in Synnax Desktop), and Export. The code buttons copy a line that retrieves the task in a script.

Tasks in code

# Find tasks by name.
task = client.tasks.retrieve(name="Tank sensors")
tasks = client.tasks.retrieve(names=["Tank sensors", "Tank valves"])

# List the tasks on the embedded Driver of the Core.
for t in client.tasks.list():
    print(t.name, t.type)

# Copy a task with a new name.
copy = client.tasks.copy(key=task.key, name="Tank sensors copy")

# Delete a task.
client.tasks.delete(copy.key)

list() with no argument returns only the tasks on the embedded Driver of the Core. To list the tasks of another Driver, pass its rack key: client.tasks.list(rack=key).