LabJack Agent

LabJacks are generic devices for interfacing with different sensors, providing analog and digital inputs and outputs. They are then commanded and queried over Ethernet.

usage: python3 agent.py [-h] [--ip-address IP_ADDRESS]
                        [--active-channels ACTIVE_CHANNELS [ACTIVE_CHANNELS ...]]
                        [--function-file FUNCTION_FILE]
                        [--sampling-frequency SAMPLING_FREQUENCY]
                        [--mode {idel,acq,acq_reg}]

Agent Options

--ip-address

ip-address of LabJack

--active-channels

Channels or register names to readout default is to read out all available outputs. But typically you would want to pass a list of analog inputs (i.e. [“AIN0”, “AIN1”, “AIN2”]) or a list of custom registers if using --mode=acq_reg.

Default: [‘T7-all’]

--function-file

Path to file that defines functions for converting analog inputs to useful units (i.e. temp, pressure, etc.)

Default: “None”

--sampling-frequency

This is the rate each channel in the active-channels list is sampled at. In --mode=acq_reg the maximum for this is 2.5 Hz can sample much faster O(kHz) in --mode=acq.

Default: “2.5”

--mode

Possible choices: idel, acq, acq_reg

Options are acq: read out analog inputs (can stream quickly), acq_reg: read out custom configured registers, or idle: leave device idle at startup.

Default: “acq”

Dependencies

labjack-ljm - LabJack LJM Library

While there is the above PyPI package for the LJM library, it does not provide the libLabJackM.so shared object file that is needed. This can be obtained by running the LJM installer provided on the LabJack website. You can do so by running:

$ wget https://labjack.com/sites/default/files/software/labjack_ljm_minimal_2020_03_30_x86_64_beta.tar.gz
$ tar zxf ./labjack_ljm_minimal_2020_03_30_x86_64_beta.tar.gz
$ ./labjack_ljm_minimal_2020_03_30_x86_64/labjack_ljm_installer.run -- --no-restart-device-rules

Note

This library is bundled in to the socs base Docker image. If you are running this Agent in Docker you do not also need to install the library on the host system.

Configuration File Examples

Below are configuration examples for the ocs config file and for running the Agent in a docker container.

OCS Site Config

To configure the LabJack Agent we need to add a LabJackAgent block to our ocs configuration file. Here is an example configuration block using all of the available arguments:

{'agent-class': 'LabJackAgent',
 'instance-id': 'labjack',
 'arguments':[
   ['--ip-address', '10.10.10.150'],
   ['--active-channels', ['AIN0', 'AIN1', 'AIN2']],
   ['--function-file', 'labjack-functions.yaml'],
   ['--mode', 'acq'],
   ['--sampling-frequency', '700'],
   ]},

You should assign your LabJack a static IP, you’ll need to know that here. The ‘active-channels’ argument specifies the channels that will be read out. It can be a list, ‘T7-all’, or ‘T4-all’. The latter two read out all 14 or 12 analog channels on the T7 and T4, respectively. ‘sampling_frequency’ is in Hz, and has been tested sucessfully from 0.1 to 5000 Hz. To avoid high sample rates potentially clogging up live monitoring, the main feed doesn’t get published to influxdb. Instead influx gets a seperate feed downsampled to a maximum of 1Hz. Both the main and downsampled feeds are published to g3 files.

The ‘function-file’ argument specifies the labjack configuration file, which is located in your OCS configuration directory. This allows analog voltage inputs on the labjack to be converted to different units. Here is an example labjack configuration file:

AIN0:
    user_defined: 'False'
    type: "MKS390"

AIN1:
    user_defined: 'False'
    type: 'warm_therm'

AIN2:
    user_defined: 'True'
    units: 'Ohms'
    function: '(2.5-v)*10000/v'

In this example, channels AIN0 and AIN1 are hooked up to the MKS390 pressure gauge and a thermistor from the SO-specified warm thermometry setup, respectively. Since these are defined functions in the LabJackFunctions class, specifying the name of their method is all that is needed. AIN2 shows how to define a custom function. In this case, the user specifies the units and the function itself, which takes the input voltage ‘v’ as the only argument.

Note

The (lower-case) letter ‘v’ must be used when writing user-defined functions. No other variable will be parsed correctly.

Docker Compose

The LabJack Agent should be configured to run in a Docker container. An example docker-compose service configuration is shown here:

ocs-labjack:
  image: simonsobs/socs:latest
  <<: *log-options
  hostname: ocs-docker
  network_mode: "host"
  environment:
    - INSTANCE_ID=labjack
  volumes:
    - ${OCS_CONFIG_DIR}:/config

Since the agent within the container needs to communicate with hardware on the host network you must use network_mode: "host" in your compose file.

Custom Register Readout

LabJack has many other registers available to access besides just the voltages on AIN# which we use in the mode=acq option of this agent to readout directly or convert to useful units using the functions module. These extra registers however cannot be streamed out using the ljstream module which is the code that enables streaming channels at up to O(kHz) sample rate. Because ljstream cannot be used for these registers, and the sample rate is much lower we implemented a different acquisition mode, mode=acq_reg, to access these registers at slower sample rates.

The main registers that we have used are called AIN Extended Features and provide readout of a number of standard thermometers (Thermocouples, RTDs, and Thermistors) as well as some other features such as reporting the offset, slope, RMS, averages, min, or max of one of the AINs. Our main usage so far has been for the readout of thermocouples which allow a much larger temperature range. Importantly, thermocouple type J is used to read out the very high temperature (~1000C) ceramic heaters that serve as thermal sources for optical measurements. Thermocouples tend to have a dependence on lead resistance and are sensitive to drift so the labjack has some internal drift compensation using an internal cold junction sensor that it reads in along with the raw voltages to calculate the temperature of the thermocouple.

These extended feature registers can be configured to readout our standard SO warm thermometers (PT1000 RTDs) and do the conversion to temperature internally. However, there is less benefit to using this method since those registers are just interpolating a calibration curve which is essentially the same as the calculations applied when warm_therm is specified in the functions file. The configuration of custom registers on one of the AINs is done through the Kipling software in particular a description of how to setup the AIN#_EF_READ_A register to read out a thermocouple can be found on this page.

There are also other registers that can be accessed through this method such as ethernet settings, power setting, internal offset currents, and clock information to name a few. A full set of registers can be found on the labjack website with many listed on the Modbus Map page.

Example Client

Since labjack functionality is currently limited to acquiring data, which can enabled on startup, users are likely to rarely need a client. This example shows the basic acquisition functionality:

# Initialize the labjack
from ocs import matched_client
lj = matched_client.MatchedClient('labjack')
lj.init_labjack.start()
lj.init_labjack.wait()

# Start data acquisiton
status, msg, session = lj.acq.start(sampling_frequency=10)
print(session)

# Get the current data values 1 second after starting acquistion
import time
time.sleep(1)
status, message, session = lj.acq.status()
print(session["data"])

# Stop acqusition
lj.acq.stop()
lj.acq.wait()

Agent API

class socs.agents.labjack.agent.LabJackAgent(agent, ip_address, active_channels, function_file, sampling_frequency)[source]

Agent to collect data from LabJack device.

Parameters:

agent (OCSAgent) – OCSAgent object for the Agent.
ip_address (str) – IP Address for the LabJack device.
active_channels (str or list) – Active channel description, i.e. ‘T7-all’, ‘T4-all’, or list of channels in form [‘AIN0’, ‘AIN1’].
function_file (str) – Path to file for unit conversion.
sampling_frequency (float) – Sampling rate in Hz.

init_labjack(auto_acquire=False)[source]

Task - Initialize LabJack module.

Parameters:: auto_acquire (bool) – Automatically start acq process after initialization. Defaults to False.

acq(sampling_freq=2.5)[source]

Process - Acquire data from the Labjack.

Parameters:: sampling_frequency (float) – Sampling frequency for data collection. Defaults to 2.5 Hz.

Notes

An example of the session data is shown below. The keys in the ‘data’ dictionary correspond with configured channels from the active_channels attribute:

>>> response.session['data']
{
  "block_name": "sens",
  "data": {
    "AIN0V": 0.0015984050696715713,
    "FIO0V": 1,
    "FIO1V": 1,
    "AIN55V": 0.00033546771737746894,
    "AIN116V": 0.000019733395674847998,
  },
  "timestamp": 1698439453.8471205
}

acq_reg(sampling_frequency=2.5)[source]

Task - Start data acquisition when you want to read out non-standard registers.

In particular the custom registers labjack was built for reading out thermocouples. Maximum is about 2.5 Hz but is set by the register read time which is estimated at the beginning of the acq_reg setup step.

Parameters:: sampling_frequency (float) – Sampling frequency for data collection. Defaults to 2.5 Hz Maximum set by the register read time. Will reset to lower rate if faster than possible read time.

Supporting APIs

class socs.agents.labjack.agent.LabJackFunctions[source]

Labjack helper class to provide unit conversion from analog input voltage

unit_conversion(v_array, function_info)[source]

Given a voltage array and function information from the labjack_config.yaml file, applies a unit conversion. Returns the converted value and its units.

Parameters:

v_array (np.array) – The voltages to be converted.
function_info (dict) – Specifies the type of function. If custom, also gives the function.

MKS390(v_array)[source]: Conversion function for the MKS390 Micro-Ion ATM Modular Vaccum Gauge.

warm_therm(v_array)[source]: Conversion function for SO warm thermometry readout. Voltage is converted to resistance using the LJTick, which has a 2.5V supply and 10kOhm reference resistor. Resistance is converted to degrees Celsius using the calibration curve for the thermistor model, serial number 10K4D25.