Headers and utilities for laboratory measurements and machine control with the LabJack T4 and T7
By Christopher R. Martin
Assistant Professor of Mechanical Engineering
Penn State University
[email protected]
Version 4.05
This README is a preliminary introduciton intended to help users decide if LConfig is right for them and to get started. The detailed documentation is contained in the docs folder: General Documentation
In the summer of 2016, I realized I needed to be able to adjust my data acquisition parameters day-by-day as I was tweaking and optimizing an experiment. I love my LabJacks, and the folks at LabJack do a great job of documenting their intuitive interface. HOWEVER, the effort involved in tweaking DAQ properties on the fly AND documenting them with each experiment can be cumbersome.
This little Laboratory CONFIGuration system is designed to work with text-based configuration files using an intuitive human readable format on Linux systems. Configuration and meta data about the experiment are all embedded together in one place as a long term record for easy distribution and sharing of data.
The installation includes three top-level binaries that do just about all the jobs I require: lcrun, lcburst, and lcstat. lcburst collects high speed data in short bursts. lcrun streams data from up to 8 parallel devices directly into data files until stopped with a keystroke. It will run as long as you have hard drive space, so tests that last for days, months, or years become possible. lcstat prints a continuously updating display of the measurements from multiple parallel devices (respecting the channel calibration).
If these binaries don't work for you, the back-end configuration is contained in lconfig.c, lconfig.h, lctools.c, and lctools.h. It has been years since I've needed to build a custom binary, and I've taken some relatively sophisticated measurements with these codes.
While I do my best to keep this README up to date, the authoritative documentation for the behavior of LCONFIG is contained in the headers, lconfig.h and lctools.h. Each function has comments that defines its behavior, and there are even some examples that indicate how the functions should be used. The comments to the lc_load_config() function give a detailed description for each configuration parameter. There is also a changelog commented at the top of the header.
LCONFIG allows automatic configuration and control of most of the T4/T7's advanced features with a few added features for easier post-processing of the data.
- Stream sample rate configuration
- Analog input streaming
- Input range
- Settling time and resolution
- Single-ended vs differential
- Channel labeling
- Linear calibration to engineering units (e.g. Volts to psi for pressure sensors)
- Built-in buffer (no dynamic data management required)
- Non-blocking service for parallel device streaming
- Digital input streaming
- Static digital output
- Software trigger
- Rising/falling/any edge on any AI channel
- Supports pretrigger buffering
- Hardware trigger
- On device-supported DIO channels
- Rising/falling/any edge
- Analog output function generator
- Constant value
- Sine wave offset, amplitude, frequency
- Square wave offset, amplitude, frequency, duty cycle
- Sawtooth offset, amplitude, frequency, duty cycle
- White noise offset, amplitude, repetition frequency
- Channel labeling
- Flexible Input/Output extended features
- Two-channel encoder quadrature
- Frequency input
- Digital counter w/ configurable debounce filter
- Line-to-line phase measurement
- Pulse width measurement
- Pulse width output with configurable phase
- Channel labeling
- Digital Communication Interface
- UART interface
- (future support for other interfaces planned)
- Automatic generation of data files
- The active configuration is embedded in the data
- Stream directly to a file for simplicity
- Stream to buffer then to file for speed
- Tools for real time applications in
lctools.h- Tools for formatted printing to a POSIX terminal
- Tools for handling keyboard interrupts without external libraries
- Tools for real-time signal statistics like
- mean
- peak-to-peak amplitude
- max and min
- root-mean-square (RMS) value
- standard deviation
- Tools for idle time in service loops
- Post processing in Python
lconfig.pypackage loads configurations and data automatically- Applies calibrations
- Index by channel number or channel label
- Error handling
- Messages to STDERR include the funciton's name and a description of the failure
- Each error message uniquely identifies a location in the code
This software is released under the GNU General Public License version 3.0. LCONFIG is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
To get the repository,
$ git clone http://github.com/chmarti1/lconfig
$ cd lconfig
$ sudo make install # Installs binaries to /usr/local/bin
$ lcrun -h # Prints help
$ lcburst -hlcrun and lcburst are binaries built on the LCONFIG system. lcrun continuously streams data to a file, but the read/write times for most hard drives prevents realizing the full speed of the T7. lcburst collects a high speed burst of data and then writes it to a file. Both executables use the LCONFIG library to load a configuration file, open the appropriate device connections, initiate the data transfer, and write data files automatically.
For writing your own executables, a quick tutorial on programming with the LCONFIG system is laid out in LCONFIG_README with the gritty details in this README. The absolute authoritative documentation for LCONFIG is the comments in the prototype section of the header itself. It is always updated with each version change. Versions 2.03 and older used a different system for streaming than version 3.00 and later, so older branches are still available on the git page.
Once you produce your data, there's a good chance that you'll want to analyze it. If you're a Python user, the lconfig.py module will get you up and running quickly. Its documentation is inline.
A configuration file has MANY optional contents, but all configuration files will have a few things in common. ALL configuration directives have the same format; a parameter followed by a value separated by whitespace.
# Configuration files can contain comments
# The first directive always has to be a conneciton type. The connection
# directive tells LCONFIG what interface to use to reach the T7. It
# also tells LCONFIG to start configuring a new device. This allows a
# single configuration file to specify connections to multiple devices.
connection eth
# If the connection is over tcp/ip, then the IP address is used to
# specify which device is being configured. If the connection is over
# USB, then the ip address is treated like any other parameter, and will
# be written to the device.
ip 192.168.10.10
# We can also set some global acquisition options
samplehz 100
nsample 32
settleus 100
# Just like the connection parameter indicates that we've started new
# device connection, aichannel indicates that we're talking about a new
# analog input channel. This indicates the physical port from which
# analog data should be collected. MUX80 channel numbers are not
# supported yet
aichannel 0
# To put the channel in differential mode, the negative can be specified
# to the neighboring odd channel number.
ainegative 1
# Now that we specify aichannel 2, all following analog input directives
# will be applied to this analog input and not the last one. Oh, by the
# way, LCONFIG is case insensitive.
AIchAnnEl 2
ainegative 3
AIRANGE 0.1
# The exception is when quotes are used. Inside of quotes, whitespace
# and case are treated verbatim.
ailabel "Ambient Temperature"
aiunits "degC"
##
Configuration files end when the file ends or when the load_config()
function encounters ##. This text isn't commented because
it will never be read by load_config()Data files are written with the device configuration that was used to collect the data embedded in the file's header. Because ## ends the configuration section, load_config() can open a data file just as easily as it can a configuration file. That means an experiment can be run to repeat prior data simply by specifying the prior data file as the configuration file.
Below are the first 26 lines of a data file. The configuration section is terminated by the ## flag, and the date and time at which the measurement was started is recorded behind a #: prefix.
From there, each line represents a scan of all the configured channels. Data are separated by whitespace. Time values are not listed since they can be reconstructed from the SAMPLEHZ parameter.
# Configuration automatically generated by WRITE_CONFIG()
connection eth
ip 192.168.0.11
samplehz 100.000000
settleus 1.000000
nsample 64
# Analog Inputs
aichannel 0
ainegative 199
airange 10.000000
airesolution 0
aichannel 2
ainegative 3
airange 0.100000
airesolution 0
# Analog Outputs
## End Configuration ##
#: Wed Apr 19 16:25:50 2017
3.988376e-01 -2.633701e-04
4.060992e-01 2.164717e-04
4.023106e-01 -3.075610e-04
4.019948e-01 -6.766737e-05
...
Some of the parameters have not been thoroughly tested; especailly the extended features. I have done some basic testing, but I would not be surprised to learn that there are bugs that need attention there. Please contact me if you find any!
As of version 4.00, only the UART digital COM interface is implemented. It is not currently a high priority to implement the other interfaces, but one day...
No persisting known bugs.