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
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
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:
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:
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.
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.
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:
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
Python
TypeScript
# 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).
// Find tasks by name.
const task = await client.tasks.retrieve({ name: "Tank sensors" });
const tasks = await client.tasks.retrieve({
where: { name: { in: ["Tank sensors", "Tank valves"] } },
});
// List the tasks on every Driver.
const all = await client.tasks.retrieve({ where: { internal: { eq: false } } });
for (const t of all) console.log(t.name, t.type);
// Copy a task with a new name.
const copy = await client.tasks.copy(task.key, "Tank sensors copy", false);
// Delete a task.
await client.tasks.delete(copy.key);The where filter with internal: { eq: false } returns the tasks on every Driver. To
list the tasks of one Driver, add its rack key:
where: { rack: { eq: key }, internal: { eq: false } }.