Acquiring and Outputting Data :: Data Acquisition Session (Data Acquisition Toolbox™)

Learn more about Data Acquisition Toolbox

Acquiring and Outputting Data

On this page…
Device Object States Starting the Device Object Logging or Sending Data Stopping the Device Object

On this page…

Device Object States

As data is being transferred between the MATLAB workspace and your hardware, you can think of the device object as being in a particular state. Two types of states are defined for the Data Acquisition Toolbox software:

Running — For analog input objects, running means that data is being acquired from an analog input subsystem. However, the acquired data is not necessarily saved to memory or a disk file. For analog output objects, running means that data queued in the engine is ready to be output to an analog output subsystem.
The running state is indicated by the Running property for both analog input and analog output objects. Running can be On or Off.
Logging or Sending — For analog input objects, logging means that data acquired from an analog input subsystem is being stored in the engine or saved to a disk file. The logging state is indicated by the Logging property. Logging can be On or Off.
For analog output objects, sending means the data queued in the engine is being output to an analog output subsystem. The sending state is indicated by the Sending property. Sending can be On or Off.

Running, Logging, and Sending are read-only properties that are automatically set to On or Off by the engine. When Running is Off, Logging and Sending must be Off. When Running is On, Logging and Sending are set to On only when a trigger occurs.

Note Digital I/O objects also possess a running state. However, because they do not store data in the engine, the logging and sending states do not exist.

Starting the Device Object

You start a device object with the start function. For example, to start the analog input object ai,

ai = analoginput('winsound')
addchannel(ai,1:2)
start(ai)

After start is issued, the Running property is automatically set to On, and both the device object and hardware device execute according to the configured and default property values.

While you are acquiring data with an analog input object, you can preview the data with the peekdata function. peekdata takes a snapshot of the most recent data but does not remove data from the engine. For example, to preview the most recent 500 samples acquired by each channel contained by ai,

data = peekdata(ai,500);

Because previewing data is usually a low-priority task, peekdata does not guarantee that all requested data is returned. You can preview data at any time while the device object is running.

Logging or Sending Data

While the device object is running, you can

Log data acquired from an analog input subsystem to the engine (memory) or to a disk file.
Output data queued in the engine to an analog output subsystem.

However, before you can log or send data, a trigger must occur. You configure an analog input or analog output trigger with the TriggerType property. All the examples presented in this section use the default TriggerType value of Immediate, which executes the trigger immediately after the start function is issued. For a detailed description of triggers, refer to Configuring Analog Input Triggers or Configuring Analog Output Triggers.

Extracting Logged Data

When a trigger occurs for an analog input object, the Logging property is automatically set to On and data acquired from the hardware is logged to the engine or a disk file. You extract logged data from the engine with the getdata function. For example, to extract 500 samples for each channel contained by ai,

data = getdata(ai,500);

getdata blocks the MATLAB Command Window until all the requested data is returned to the workspace. You can extract data any time after the trigger occurs.

Sending Queued Data

For analog output objects, you must queue data in the engine with the putdata function before it can be output to the hardware. For example, to queue 8000 samples in the engine for each channel contained by the analog output object ao

ao = analogoutput('winsound');
addchannel(ao,1:2);
data = sin(linspace(0,2*pi*500,8000))';
putdata(ao,[data data])

Before the queued data can be output, you must start the analog output object.

start(ao)

When a trigger occurs, the Sending property is automatically set to On and the queued data is sent to the hardware.

Stopping the Device Object

An analog input (AI) or analog output (AO) object can stop under one of these conditions:

You issue the stop function.
The requested number of samples is acquired (AI) or sent (AO).
A run-time hardware error occurs.
A time-out occurs.

When the device object stops, the Running, Logging, and Sending properties are automatically set to Off. At this point, you can reconfigure the device object or immediately issue another start command using the current configuration.

Configuring and Returning Properties

Cleaning Up

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit