Doing More With Analog Input (Data Acquisition Toolbox)

Data Acquisition Toolbox

Extracting Data from the Engine

Many data acquisition applications require that data is acquired at a fixed (often high) rate, and that the data be processed in some way immediately after it is collected. For example, you may want to perform an FFT on the acquired data and then save it to disk. When processing data, you must extract it from the engine in a timely fashion so that no samples are missed.

Data is extracted from memory with the getdata function. getdata is a blocking function that returns control to the MATLAB environment only when the requested data is available. Therefore, samples are not missed or repeated.

The syntax for getdata is

[data, time, abstime, events] = getdata(obj, samples, type);

where:

samples (optional) is the number of samples to return. If samples is not specified, then the number of samples to return is given by the SamplesPerTrigger property.
type (optional) specifies the format of the returned data. If type is specified as 'native', then data is returned in the native data format of the device. If type is not specified, samples are returned as doubles.
data is an m-by-n array containing acquired data where m is the number of samples and n is the number of channels.
time is an m-by-1 array containing the time values for all m samples acquired. time = 0 corresponds to the time the first sample was logged by the data acquisition engine. Time is measured continuously until the acquisition is stopped. Absolute times are available through the TriggerTime property.
abstime is the absolute time of the trigger associated with data.
events is a structure containing a list of events that have occurred up to the time of the getdata call. The possible events that can be returned are identical to those stored by the EventLog property.

The relationship between the samples acquired and the relative time for each sample is shown below for m samples and n channels.

As soon as a trigger is issued and samples are stored in the engine, the SamplesAcquired property keeps a running count of the total number of samples per channel that have been acquired, while the SamplesAvailable property tells you how many samples can be extracted from the engine per channel with getdata. When a getdata call is issued, SamplesAvailable is reduced by the number of samples requested.

getdata and Data Blocks

When a trigger occurs, acquired data fills data blocks in the engine. Data blocks are discussed in "The Data Block". When a getdata function call is processed, the requested samples are returned when the data is available, and then removed from the engine. The situation for when getdata extracts a full block of data is shown below block 1 is the first block filled with data and block n is the most recent block filled with data.

If another getdata call is issued, then those samples are returned such that no data is missed. This situation is shown below.

Example: Previewing and Extracting Data

Suppose you have a time-consuming data acquisition application. By previewing the data, you can ascertain whether the acquisition is proceeding as expected without waiting for all the data to be acquired. If it is not, then you can abort the session and diagnose the problem.

The example below illustrates how you might use peekdata and getdata together in such an application.

Initialization: Create the analog input object AI for a sound card. The available adaptors are found with daqhwinfo.

AI = analoginput('winsound');
%AI = analoginput('nidaq', 1);

Configuration: Add one hardware channel to AI, define a ten second acquisition, set up the plot and store the plot handle in the variable P. The amount of data displayed is given by preview.

chan = addchannel(AI,1);
%chan = addchannel(AI,0);
duration = 10; % Ten second acquisition
set(AI,'SampleRate',8000);
ActualRate = get(AI,'SampleRate');
set(AI,'SamplesPerTrigger',duration*ActualRate);
preview = duration*ActualRate/100;
figure
set(gcf, 'doublebuffer', 'on'); 
subplot(211); 
P = plot(zeros(preview,1)); grid on
title(sprintf('daqdoc4\\_3\nPreview Data'))
xlabel('Samples')
ylabel('Signal Level (Volts)')

Execution: Start AI and update the display using peekdata every time an amount of data given by preview is stored in the engine by polling SamplesAcquired. The drawnow command forces MATLAB to update the plot. After all data is acquired, it is extracted from the engine. Note that whenever peekdata is used, all acquired data may not be displayed.

start(AI);
while AI.SamplesAcquired < preview
end
while AI.SamplesAcquired < duration*ActualRate
   data = peekdata(AI, preview);
    set(P, 'ydata', data);
   drawnow;
end
data = getdata(AI);

Termination: Wait for AI to stop running, plot all the extracted data, and delete the device object.

subplot(212); plot(data);  grid on
title('All Acquired Data')
xlabel('Samples')
ylabel('Signal level (volts)')
delete(AI)

The data is shown below.

[ Previous | Help Desk | Next ]