LCONFIG README

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
crm28@psu.edu

Version 4.05

Foreword

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

---

Contents of this README

• About
• License
• Getting started
• Anatomy of an LCONFIG configuration file
• Anatomy of a data file

About

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.

Features

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.py package 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

License

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.

Getting started

To get the repository,

bash $ git clone http://github.com/chmarti1/lconfig $ cd lconfig $ sudo make install # Installs binaries to /usr/local/bin $ lcrun -h # Prints help $ lcburst -h lcrun 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.

Anatomy of an LCONFIG configuration file

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. ```bash

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 loadconfig() function encounters ##. This text isn't commented because it will never be read by loadconfig() ```

Anatomy of a data file

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 ... ```

Future Improvements

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...

Known Bugs

No persisting known bugs.