Skip to content

Latest commit

 

History

History
201 lines (160 loc) · 7.84 KB

labjack.rst

File metadata and controls

201 lines (160 loc) · 7.84 KB
Raw

rst

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.

Dependencies

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

socs.agents.labjack.agent.LabJackAgent

Supporting APIs

socs.agents.labjack.agent.LabJackFunctions