# LabJack read task

> Read analog, digital, and thermocouple inputs from a LabJack into channels.

A LabJack read task reads the inputs of one LabJack device into channels. For example, it can record a pressure transducer on `AIN0` and a switch on `DIO4` at 1 kHz.

Before you start, you need a [configured device](https://docs.synnaxlabs.com/reference/hardware/labjack/configure-device).

## Channels and timing

A read task has three types of channels:

* **Analog input** -> a voltage on an `AIN` port.
* **Digital input** -> the state of a `DIO` port, as 0 or 1.
* **Thermocouple** -> a temperature from a thermocouple on an `AIN` port. Thermocouples work on the T7 and the T8.

A task streams: the device samples the inputs on its own clock. A T7 task with thermocouple channels polls instead: the Driver reads one sample of each channel at a time, on its own clock. See [timing](https://docs.synnaxlabs.com/reference/hardware/tasks#timing).

A T8 task with thermocouple channels samples at 250 Hz or less. It needs T8 firmware 1.0038 or later and LJM 1.2304 or later.

A LabJack runs one stream at a time and cannot read `AIN` ports during a stream, so a streaming task must be the only read task on its device. Add more channels to that task instead of starting a second one.

## Create a LabJack read task

[Enterprise](https://docs.synnaxlabs.com/reference/get-started/editions "Needs Synnax Enterprise")

**Console**

1. In the devices toolbar, right-click the device and select **Create read task**.
2. Set **Sample rate** and **Stream rate**.
3. Click **Add channel**, then select the type of channel and the **Port**.
4. Click (**Start**).

The Console creates the channels. For a device with the identifier `lj1`, the channel for `AIN0` is `lj1_AIN0`, with the index channel `lj1_time`. To use a different name, enter it in the channel list before you start the task.

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/hardware/labjack/read-task/65603d29824d-dark.mp4#t=0.001)

**Python**

Python does not create channels. Create them first.

```python
import synnax as sy
from synnax import labjack

dev = client.devices.retrieve(key="<serial number>")
time = client.channels.create(
    name="lj1_time", is_index=True, data_type=sy.DataType.TIMESTAMP
)
pressure = client.channels.create(
    name="lj1_AIN0", index=time.key, data_type=sy.DataType.FLOAT32
)
switch = client.channels.create(
    name="lj1_DIO4", index=time.key, data_type=sy.DataType.UINT8
)

task = labjack.ReadTask(
    name="Test stand inputs",
    device=dev.key,
    sample_rate=1000,
    stream_rate=25,
    channels=[
        labjack.AnalogReadChannel(port="AIN0", channel=pressure.key),
        labjack.DigitalReadChannel(port="DIO4", channel=switch.key),
    ],
)
client.tasks.configure(task)
task.start()
```

Python creates the task on the embedded Driver of the Core. For a device on another Driver, use the Console or TypeScript.

For a thermocouple on a T7 or a T8, use `labjack.ThermocoupleReadChannel(port="AIN2", thermocouple_type="K", units="C", channel=...)`.

**TypeScript**

TypeScript does not create channels. Create them first.

```typescript
import { labjack } from "@synnaxlabs/client";

const dev = await client.devices.retrieve({ key: "<serial number>" });
const time = await client.channels.create({
  name: "lj1_time",
  isIndex: true,
  dataType: "timestamp",
});
const pressure = await client.channels.create({
  name: "lj1_AIN0",
  index: time.key,
  dataType: "float32",
});

const task = await client.tasks.create({
  name: "Test stand inputs",
  rack: dev.rack,
  type: "labjack_read",
  config: labjack.readConfigZ.parse({
    device: dev.key,
    sampleRate: 1000,
    streamRate: 25,
    channels: [{ type: "analog", port: "AIN0", channel: pressure.key }],
  }),
});
await task.start();
```

## Tare channels

Tare sets the current value of an analog channel to zero. The task must be running.

1. In the channel list, click **Tare** on an analog channel. To tare several channels, select them, right-click, and select **Tare**.
2. The values of those channels start from zero.

## Task options

| Console label | Python field           | Default | Notes                                                                                |
| ------------- | ---------------------- | ------- | ------------------------------------------------------------------------------------ |
| Device        | `device`               |         | The serial number of the device.                                                     |
| Sample rate   | `sample_rate`          | 10 Hz   | Up to 50,000 Hz in the Console.                                                      |
| Stream rate   | `stream_rate`          | 5 Hz    | See [read tasks](https://docs.synnaxlabs.com/reference/hardware/tasks#read-tasks).   |
| Data saving   | `data_saving_disabled` | On      | See [data saving](https://docs.synnaxlabs.com/reference/hardware/tasks#data-saving). |
| Auto start    | `auto_start`           | Off     | Starts the task each time the Driver starts.                                         |

## Channel reference

Each channel has a `channel`, the Synnax channel that records the value. Each table shows the Console label of a setting, with its Python field under it.

**Analog input**

#### [Analog input](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#analog)

Python `AnalogReadChannel`TypeScript `analog`

Reads a voltage.

| Setting                     | Default | Notes                                                                                    |
| --------------------------- | ------- | ---------------------------------------------------------------------------------------- |
| Port `port`                 | `AIN0`  | An `AIN` port.                                                                           |
| Max voltage `range`         | `10`    | The input uses the smallest range of the device that covers this voltage. Not on the T4. |
| Negative channel `neg_chan` | Ground  | Absent for ground, or the pair of the port for a differential reading. On the T7 only.   |
| Scale `scale`               | None    | None, linear (slope and offset), map (raw range to scaled range), polynomial, or table.  |

**Digital input**

#### [Digital input](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#digital)

Python `DigitalReadChannel`TypeScript `digital`

Reads the state of a digital line as 0 or 1, as `uint8`.

| Setting     | Default | Notes         |
| ----------- | ------- | ------------- |
| Port `port` | `DIO4`  | A `DIO` port. |

**Thermocouple**

#### [Thermocouple](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#thermocouple)

Python `ThermocoupleReadChannel`TypeScript `thermocouple`

Reads a temperature from a thermocouple. The Driver reads the voltage of the thermocouple and the temperature of its cold junction, then converts the two to a temperature.

| Setting                               | Default                | Notes                                                                                         |
| ------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------- |
| Port `port`                           | `AIN0`                 | An `AIN` port.                                                                                |
| Thermocouple type `thermocouple_type` | `K`                    | `B`, `E`, `J`, `K`, `N`, `R`, `S`, `T`, `C`.                                                  |
| Temperature units `units`             | `K`                    | `C`, `F`, `K`.                                                                                |
| Negative channel `neg_chan`           | Ground                 | Absent for ground, or the pair of the port. On the T7 only.                                   |
| CJC source `cjc_source`               | `TEMPERATURE_DEVICE_K` | **Device** (**Terminal** on a T8), **Air** (not on a T8), or an `AIN` port with a CJC sensor. |
| CJC slope `cjc_slope`                 | `1`                    | The CJC sensor scale, in kelvin per volt.                                                     |
| CJC offset `cjc_offset`               | `0`                    | The CJC sensor offset, in kelvin.                                                             |
| Scale `scale`                         | None                   | Applied after the conversion to temperature.                                                  |

## Troubleshooting

* [Falling behind hardware](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#falling-behind-hardware)

  * Cause

    The Driver cannot send the samples as fast as the device makes them.

  * Fix

    Lower the **Stream rate**, or lower the **Sample rate**.

* [Skipped samples](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#skipped-samples)

  * Cause

    The buffer of the device filled, so the device skipped samples. The Driver writes no value for a skipped sample.

  * Fix

    Lower the **Sample rate**, or check the USB cable or the network.

* [Thermocouple out of range](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#thermocouple-out-of-range)

  * Cause

    The voltage of the thermocouple is outside the range of its **Thermocouple type**. The thermocouple is open, a wire is loose, or the type is wrong. The Driver writes NaN until the voltage is in range.

  * Fix

    Check the wires of the thermocouple and its **Thermocouple type**.

* [A T8 task with thermocouples samples at 250 Hz or less](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#a-t8-task-with-thermocouples-samples-at-250-hz-or-less)

  * Cause

    Above 250 Hz, the T8 cannot read the temperature at its terminals, which the Driver needs to convert thermocouples.

  * Fix

    Set the **Sample rate** to 250 Hz or less.

* [Thermocouples on a T8 need firmware ... or later](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#thermocouples-on-a-t8-need-firmware-or-later)

  * Cause

    The firmware of the T8 cannot stream the temperature at its terminals.

  * Fix

    Update the firmware of the T8 with [Kipling](https://support.labjack.com/docs/kipling).

* [Thermocouples on a T8 need LJM ... or later](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#thermocouples-on-a-t8-need-ljm-or-later)

  * Cause

    The LJM library on the computer that runs the Driver cannot stream the temperature at the terminals of a T8.

  * Fix

    Install the latest [LJM](https://support.labjack.com/docs/ljm-software-installer-downloads-t4-t7-t8-digit), then restart the Driver.

* [Using default calibration](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#using-default-calibration)

  * Cause

    The calibration constants of the device are not valid. LJM uses default constants, so readings may be inaccurate. The task continues to record data.

  * Fix

    Contact [LabJack support](https://labjack.com/pages/support).

* [... is a thermocouple channel, but the T4 does not support thermocouples.](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#is-a-thermocouple-channel-but-the-t4-does-not-support-thermocoup)

  * Cause

    The T4 has no thermocouple inputs.

  * Fix

    Use a T7 or a T8 for thermocouple channels.

* [... is a thermocouple channel, so it cannot be the CJC source of ...](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#is-a-thermocouple-channel-so-it-cannot-be-the-cjc-source-of)

  * Cause

    The **CJC source** of a thermocouple is the port of another thermocouple channel. A thermocouple port has no CJC sensor.

  * Fix

    Set **CJC source** to **Device**, or to the `AIN` port of a CJC sensor.

* [... has a max voltage of ..., but the largest range of the device is ...](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#has-a-max-voltage-of-but-the-largest-range-of-the-device-is)

  * Cause

    The **Max voltage** of the channel is larger than the largest input range of the device: ±10 V on a T7, and ±11 V on a T8.

  * Fix

    Lower the **Max voltage** of the channel.

* [A T7 task fails to start after a change to Max voltage.](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#a-t7-task-fails-to-start-after-a-change-to-max-voltage)

  * Cause

    On a T7, a small range takes longer to settle. A task with more than one channel and a **Max voltage** of 1 V or less can then not stream at its **Sample rate**.

  * Fix

    Lower the **Sample rate**, or set **Max voltage** back to 10. See LabJack’s [stream rates](https://support.labjack.com/docs/a-1-1-stream-data-rates-t-series-datasheet).

* [Port ... has already been used on another channel](https://docs.synnaxlabs.com/reference/hardware/labjack/read-task#port-has-already-been-used-on-another-channel)

  * Cause

    Two channels use the same port.

  * Fix

    Select a different port for one of them.

For other problems, see [Configure a LabJack device](https://docs.synnaxlabs.com/reference/hardware/labjack/configure-device#troubleshooting) and [Troubleshoot hardware](https://docs.synnaxlabs.com/reference/hardware/troubleshooting).