# 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](https://docs.synnaxlabs.com/reference/hardware/devices). A read task records the values of inputs in [channels](https://docs.synnaxlabs.com/reference/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](https://docs.synnaxlabs.com/reference/hardware/ni/analog-read-task) or the [Modbus write task](https://docs.synnaxlabs.com/reference/hardware/modbus/write-task). To start and stop tasks, see [Start and stop tasks](https://docs.synnaxlabs.com/reference/hardware/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](https://docs.synnaxlabs.com/reference/visualize/schematics), an [Arc automation](https://docs.synnaxlabs.com/reference/control/arc), 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](https://docs.synnaxlabs.com/reference/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](https://docs.synnaxlabs.com/reference/hardware/ni/analog-write-task#the-outputs-stop-changing-after-a-command). 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](https://docs.synnaxlabs.com/reference/hardware/modbus/read-task) on the same register.

For the names of command and state channels, see [channels that tasks create](https://docs.synnaxlabs.com/reference/channels#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](https://docs.synnaxlabs.com/reference/hardware/http/read-task#endpoints-and-fields). An EtherCAT read task can take its timestamps from the distributed clock of its modules. See [PDO channels](https://docs.synnaxlabs.com/reference/hardware/ethercat/read-task#pdo-channels). The [MQTT read task](https://docs.synnaxlabs.com/reference/hardware/mqtt/read-task) and the [Kafka read task](https://docs.synnaxlabs.com/reference/hardware/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](https://docs.synnaxlabs.com/reference/enterprise/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**.

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/hardware/ni/ports-view/db48248c9c58-dark.mp4#t=0.001)

## 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](https://docs.synnaxlabs.com/reference/hardware/start-and-stop-tasks#apply-edits-to-a-running-task). 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](https://docs.synnaxlabs.com/reference/hardware/devices#statuses).

## 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](https://docs.synnaxlabs.com/reference/hardware/tasks#data-saving) on or off.        |
| Snapshot to \<range>                    | Saves a copy of the task to the active [range](https://docs.synnaxlabs.com/reference/ranges#snapshots). |
| 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

**Python**

```python
# 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)`.

**TypeScript**

```typescript
// 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 } }`.
