VDAC: Free Digital Data Acquisition and Control Software - Manual and Tutorial

Department of Civil and Environmental Engineering
Edmund T. Pratt School of Engineering
Duke University - Box 90287, Durham, NC 27708-0287

1. Downloading, Installing and Compiling the Programs

VDAC is a free, simple data acquisition, visualization and control program written in C to address and control the CIO-DAS16 , CIO-DAS16/F , CIO-DAS1601/12 , CIO-DAS1602/12 , CIO-DAS1602/16 , or PCI-DAS1602/16 plug-in digital data acquisition cards for EISA, PCI, and PCMCIA bus personal computers. These data acquisition cards can collect data at pre-determined sample rates on up to sixteen channels (numbered 0 to 15), and can also convert digital data to analog signals on up to two analog output channels (numbered 0 and 1). The programs are built with the DJGPP compiler. You may download the executeables and the source-code, unzip them to the directory C:\data-aq\.

The programs use an ANSI.SYS driver. To enable this feature, copy the file ... C:\data-aq\ansi.sys ... to ... C:\ansi.sys ; and put the line ... device = C:\ansi.sys ... at the begining of the file ... C:\config.sys .

The pre-complied programs are set-up for a base address of 0x300 (300H); no DMA (the DMA switch is irrelevant); operation with a 1 MHz XTAL clock for counter 2; 16 A/D single-ended channels; a +/- 10 volt bipolar range for both D/A channels (0 and 1); and bipolar A/D ranges.

To use the pre-compiled programs vdac.exe and calib.exe directly, without compiling them yourself, get the run-time files for DJGPP ... select "Run a program I got that was built with DJGPP", your operating system, "DOS"; you will not need on-line documentation; the programs are written in C; you will not need any IDE's (integrated development tools); you will not need gdb (the GNU debugger); you will not need any other "extra stuff." Click on "Tell me which files I need"; download the following files:

     v2/copying.dj        DJGPP Copyright info            3 kb
     v2/djdev203.zip      DJGPP Basic Development Kit   1.5 mb
     v2/faq230b.zip       Frequently Asked Questions    664 kb
     v2/readme.1st        Installation instructions      22 kb

     v2misc/csdpmi5b.zip  CWSDPMI - DPMI server          54 kb
Follow the instructions in the section, "Installation Instructions for dos" and in the file v2/readme.1st to install files in the .zip archives djdev203.zip and csdpmi5b.zip .

To re-compile the programs, get the complete DJGPP compiler ... select "Build and run programs using DJGPP", your operating system, "DOS"; you will not need to read on-line documentation; the programs are written in C; you may or may not want to use the IDE's (integrated development tools); you may or may not want gdb (the GNU debugger); select the "Allegro toolkit" in the "extra stuff" section. Click on "Tell me which files I need"; download the following files:

     v2/copying.dj            DJGPP Copyright info                  3 kb
     v2/djdev203.zip          DJGPP Basic Development Kit         1.5 mb
     v2/faq230b.zip           Frequently Asked Questions          664 kb
     v2/readme.1st            Installation instructions            22 kb
     v2gnu/bnu215b.zip        Basic assembler, linker             3.3 mb
     v2gnu/fil41b.zip         File Utils (for building Allegro)   1.7 mb
     v2gnu/gcc333b.zip        Basic GCC compiler                  2.8 mb
     v2gnu/mak3791b.zip       Make (processes makefiles)          267 kb

     v2misc/csdpmi5b.zip      CWSDPMI - DPMI server                54 kb

     v2tk/allegro/all403.zip  Allegro game library                2.7 mb
Follow the instructions in the section, "Installation Instructions for dos" and in the file v2/readme.1st to install files in the .zip archives. The most recent main source-code file is vdac.c . It includes real-time graphics display, and must be compiled by linking to the Allegro graphics library, with the command:
     gcc  -O  -o  vdac  vdac.c  -lalleg

2. Reference Books
Concepts related to programming data acquisition hardware are described in:

David M. Auslander, Cheng H. Tham Real Time Software for Control: Program Examples in C/With Disk , Prentice Hall, 1990.

Intersil, Data Acquisition and Conversion Handbook, Intersil, 1980.

William H. Rigby and Terry Dalby, Computer Interfacing - A Practical Approach to Data Acquisition and Control , Prentice Hall 1995.

John Yeager and Mary Anne Hrusch-Tupta, ed. Low Level Measurements, 5th ed., Keithley, 1998.

3. Collecting Data

VDAC has real-time visualization, processing and control capabilities. Visualization is accomplisehd via the Allegro graphics library, and allows the user to view X-Y plots of the data as they are collected. Visualization requires 6 microseconds per chanel-scan with a 220 MHz Pentium processor. VDAC can also perform real-time data processing, including real-time integration of continuous-time ordinary differential equations. For example, on a 220 MHz Pentium, three coupled ODE's may be integrated in real time, concurrent with digital data acquisition, at sample rates of 500 samples/second, and with a processing time delay of 15 micro-seconds. For control applications, intermediate results of the real-time computations may be written to the analog output channels. For short processing time delay, it is recommended to run the program under the IBM PC-DOS 2000 operating system.

VDAC reads a short configuration file (named 'vdac.cfg' , in this tutorial) formatted as follows:

      One line description of the experiment ...
      Acquisition Time (sec)      :      35.0
      Sample Rate (Hz)            :      100.0
      Voltage Range (Volts)       :      10.0
      Starting Channel            :      0
      Stopping Channel            :      2
      0: disp. 5.0 V/cm   1: vel. 3.253 V/cm  2: accel. 2.41 V/g
      Sensitivity File            :       sensi
      D/A ch0 Output File Name    :       outfile0.dat
      D/A ch1 Output File Name    :       outfile1.dat

Using the example configuration file above, VDAC collects data for 35 seconds at 100 samples per second (per channel). The voltage range is +/- 10 volts on every channel, and signals on channels 0,1 and 2 are digitized by the data acquisition hardware. The valid voltage ranges are +/- 1.25, 2.5, 5.0, and 10.0 volts on the DAS1602/16 data acquisition hardware. If you specify a different range, VDAC displays a descriptive error message. The sensor sensitivity file, 'sensi' is used to scale data to physical units, while it is being acquired, for real time processing.

Whenever a new sample is digitized (every 10 milli-seconds in this example), the values in files 'outfile0.dat' and 'outfile1.dat' are output through analog outputs 0 and 1. These last two lines are optional. The D/A files must be ASCII text files containing values of the desired analog output signal scaled to integers between -2047 and 2048, corresponding to -10 volts and +10 volts. (The digital-to-analog converter is 12-bit on this hardware.) The first and last values of these data files should be 0 (zero). The D/A files may have non-numeric header information at the top of the file. Lines of header information must start with the '#' character. For some applications it is desireable to smooth the analog output signal with a low-pass filter. To maintain the full dynamic range, the analog output should be scaled with an op-amp and potentiometer.

To run the VDAC program, simply type

      vdac  vdac.cfg  out.i

at a DOS> prompt. This command runs the VDAC program using the configuration parameters listed in the file 'vdac.cfg' (above), and creates a data file 'out.i' containing the measured data. Of course, the files 'vdac.cfg' and 'out.i' may be renamed as is convenient. The program starts by configuring the data acquisition hardware, initializing the visualization software, and displaying a yellow ready prompt when the data acquisition and control process is ready to begin.

At this point, hitting any key immediately initiates the data acquisition. Data from each active channel are plotted to the screen, in real-time, as they are aquired. A termination message indicates the number of samples, the total sample time, the actual sample rate, and the maximum and minimum values recorded on all channels. If the maximum or minimum values equal 32768 or -32767, the amplitude of a signal exceeded the full scale range of the data acquisition hardware. If this is the case, increase the range or decrease the voltage level of the signal, and repeat the measurement.

After digitizing the signals and storing them temporarily in the PC's RAM, VDAC automatically saves the data in the ASCII file named 'out.i' with the format shown below.

      # One line description of the experiment ...
      # Wed Sep 03 09:51:29 1997
      # Data file 'out.i' created using configuration file 'vdac.cfg' .
      # 500 points at 100.000000 Hz in 34.99 seconds.  +/- 10.00 Volts F.S.
      # 0: disp. 5.0 V/cm   1: vel. 3.253 V/cm  2: accel. 2.41 V/g
      # chn 0  chn 1   chn 2
        -156   -1597     719
        -158   -1583     720
        -152   -1580     712
        -154   -1593     724
        -151   -1582     722
           :       :       :
           :       :       :

The data is stored as integers between -32767 and 32768 corresponding to -10 volts and +10 volts in this example (16-bit analog-to-digital conversion). The header of the output file contains all of the information required to scale the data from least significant bits (LSB's) to voltage levels.

4. Scaling Your Data

The computer program SCALE reads data files generated by VDAC, converts the integer LSB data to scaled floating point values, optionally performs some smoothing, and saves the scaled data in a new data file. For example, typing

      scale  sensi  out.i  out.s

at the DOS> prompt uses the sensitivity file named 'sensi' to scale the integer data in the file named 'out.i' and saves the scaled data in the file named 'out.s' The sensitivity file contains channel sensitivities (in volts per physical unit) in the format given below:

     Example of a channel sensitivity file ...
     Chnl : 0  displ : 5.0        Units : V/cm      Smoothing : 0.2  Detrend : 2
     Chnl : 1  veloc : 3.253      Units : V/cm/s    Smoothing : 0.1  Detrend : 3
     Chnl : 2  accel : 2.4567e-3  Units : V/cm/s/s  Smoothing : 0.3  Detrend : 5

The colons (:) are required elements of the sensitivity file and the data acquisition configuration file ('vdac.cfg').

The SCALE program processes the data in many ways:

* it scales the data to physical units, as specified in the sensitivity file, above;
* it corrects for channel-to-channel skew in multiplexed data;
* it optionally smoothes the data;
* it optionally detrends the data;
* it optionally integrates or differentiates a channel using the trapezoidal rule or central differences;
* it finds the maximum, minimum, and computes the root-mean-squared value for each channel; and
* it saves the data in the named output file, along with the time-axis data in the first column.
The smoothing is done by convolving the data with a sinc function. The level of smoothing is indicated in the range from zero to one:
0 = no smoothing and
1 = the maximum smoothing allowed by the program.
The detrending is done in one of five ways:
0 = do not detrend the data;
1 = subtract the average value;
2 = subtract the least-squares straight-line fit;
3 = subtract the straight line passing through the first and last points;
4 = subtract the first point; or
5 = subtract the average of the minimum and maximum values.
The header information from the integer data file is reproduced in the scaled data file, as is the descriptive title of the sensitivity file. The minimum, maximum and root-mean-square values for each channel are written at the bottom of the scaled data file. The scaled data file takes up more than twice as much disk space as the raw integer data file.

      # One line description of the experiment ...
      # Wed Sep 03 09:51:29 1997
      # Data file 'out.i' created using configuration file 'vdac.cfg' .
      # 500 points at 100.000000 Hz in 34.99 seconds.     +/- 10.00 Volts F.S.
      # 0: disp. 5.0 V/cm   1: vel. 3.253 V/cm  2: accel. 2.41 V/g
      # chn 0       chn 1       chn 2      
      # scale file: sensi 
      # Example of a channel sensitivity file ...
        1.0000e-02  -1.6525e-02   0.0000e-00  -2.2336e-01
        2.0000e-02  -1.6647e-02   2.0187e-03  -8.3565e-02
        3.0000e-02  -1.6418e-02   2.3006e-03  -1.2018e+00
        4.0000e-02  -1.9480e-02   1.0816e-03  -2.1275e-02
              :            :            :            :
              :            :            :            :
        3.4980e+01  -1.6220e-02  -6.0764e-04  -7.9180e+00
        3.4990e+01  -1.6708e-02  -1.0764e-03  -9.5952e+00
        3.5000e+01  -1.6586e-02   0.0000e-00  -8.0589e+00
      # MINIMUM     -1.7847e+00  -1.0774e-01  -6.4295e+01
      # MAXIMUM      1.8916e+00   9.1610e-02   6.4295e+01
      # R.M.S.       8.0153e-01   3.6016e-02   2.2034e+01

Several raw data files may be scaled with one command by writing a batch file or a shell script.

5. Plotting and Processing Your Data

The raw data files or the scaled data files may be plotted using Gnuplot without removing the comment lines, as long as the # character precedes each comment. Data files may be loaded into Matlab by globally replacing the # characters with % characters using the commands

      >>   !tr '#' '%' < data_file > matlab_file
      >>   load matlab_file

6. Managing Your Data (meta-data)

1. Create a personal directory under the c:\home\ directory. Your data must be placed in sub-directories of your personal directory.

2. Make a sub-directory of your personal directory named with today's date. For example c:\home\hpgavin\15jul98

3. Create a README (meta-data) file in today's directory with the format shown below:

    EXAMPLE README FILE for data collection notes
    Experiments of  ... type the date here ...
    type in the purpose of running these experiments
     ... what you hope to find
     ... why you need the data in the first place
     ... the methods and experimental set-up that you are using
     ... parameters controlling the experimental hardware
         such as frequencies, feedback gains, etc.
     ... anything else of interest

    Channel         Sensor                          Sensitivity
    1               type of sensor on channel 1     volts / unit
    :               :                               :
    n               type of sensor on channel n     volts / unit
    Data Catalogue
    File            Description
    test1.i         description of file 'test1.i'
    :                       :

In the PURPOSE section, write what these experiments are designed to measure, why you are collecting the data, what instrumentation you are using, how the specimen is being loaded, etc.

Be sure you note all sensor calibrations in the README file. System calibration can be conducted using the interactive CALIB program before the day's testing begins. You may also use the CALIB program to cancel any electronic bias in your signals.

Write a brief description of every data file. If you change your system sensitivity at any time, note the changes and the files they pertain to.

All observations you make during the experiments should be written immediately in the OBSERVATIONS section. Any trouble-shooting steps taken to get the experiment to work should be noted as well.

Be verbose.
Work slowly and methodically.
Be patient.
Do not trust your memory.

© 2001-2004 Henri P. Gavin; Updated: 7-12-2001, 12-17-2003, 6-8-2004