Getting Started with Analog Output :: Analog Output (Data Acquisition Toolbox™)

Learn more about Data Acquisition Toolbox

Getting Started with Analog Output

On this page…
Creating an Analog Output Object Adding Channels to an Analog Output Object Configuring Analog Output Properties Outputting Data Analog Output Examples Evaluating the Analog Output Object Status

On this page…

Creating an Analog Output Object

Adding Channels to an Analog Output Object

Configuring Analog Output Properties

Outputting Data

Analog Output Examples

Evaluating the Analog Output Object Status

Creating an Analog Output Object

You must create an Analog Output object with which you can use the Data Acquisition Toolbox software to perform basic tasks with your analog output (AO) hardware. This section describes the important properties and functions required for an analog output data acquisition session, and also provides several device-specific examples and ways to evaluate the status of the analog output object.

You create an analog output object with the analogoutput function. analogoutput accepts the adaptor name and the hardware device ID as input arguments. For a list of supported adaptors, refer to the Data Acquisition Toolbox Supported Hardware page on the MathWorks™ Web site. The device ID refers to the number associated with your board when it is installed. (When using NI-DAQmx, this is usually a string such as 'Dev1'.) Some vendors refer to the device ID as the device number or the board number. The device ID is optional for sound cards with an ID of 0. Use the daqhwinfo function to determine the available adaptors and device IDs.

Each analog output object is associated with one board and one analog output subsystem. For example, to create an analog output object associated with a National Instruments board with device ID 1:

ao = analogoutput('nidaq','Dev1');

The analog output object ao now exists in the MATLAB workspace. You can display the class of ao with the whos command.

whos ao
  Name      Size         Bytes  Class

  ao        1x1           1334  analogoutput object

Grand total is 53 elements using 1334 bytes

Once the analog output object is created, the properties listed below are automatically assigned values. These general purpose properties provide descriptive information about the object based on its class type and adaptor.

Table 6-1. Descriptive Analog Output Properties

Property Name	Description
`Name`	Specify a descriptive name for the device object.
`Type`	Indicate the device object type.

You can display the values of these properties for ao with the get function.

get(ao,{'Name','Type'})
ans = 
    'nidaqmxDev1-AO'    'Analog Output'

Adding Channels to an Analog Output Object

After creating the analog output object, you must add hardware channels to it. As shown by the figure in Hardware Channels or Lines, you can think of a device object as a container for channels. The collection of channels contained by the device object is referred to as a channel group. As described in Mapping Hardware Channel IDs to the MATLAB Indices, a channel group consists of a mapping between hardware channel IDs and MATLAB indices.

When adding channels to an analog output object, you must follow these rules:

The channels must reside on the same hardware device. You cannot add channels from different devices, or from different subsystems on the same device.
The channels must be sampled at the same rate.

You add channels to an analog output object with the addchannel function. addchannel requires the device object and at least one hardware channel ID as input arguments. You can optionally specify MATLAB indices, descriptive channel names, and an output argument. For example, to add two hardware channels to the device object ao created in the preceding section:

chans = addchannel(ao,0:1);

The output argument chans is a channel object that reflects the channel array contained by ao. You can display the class of chans with the whos command.

whos chans
  Name        Size         Bytes  Class

  chans       2x1            512  aochannel object

Grand total is 7 elements using 512 bytes

You can use chans to easily access channels. For example, you can easily configure or return property values for one or more channels. As described in Referencing Individual Hardware Channels, you can also access channels with the Channel property.

Once you add channels to an analog output object, the properties listed below are automatically assigned values. These properties provide descriptive information about the channels based on their class type and ID.

Table 6-2. Descriptive Analog Output Channel Properties

Property Name	Description
`HwChannel`	Specify the hardware channel ID.
`Index`	Indicate the MATLAB index of a hardware channel.
`Parent`	Indicate the parent (device object) of a channel.
`Type`	Indicate a channel.

You can display the values of these properties for chans with the get function.

get(chans,{'HwChannel','Index','Parent','Type'})
ans = 
    [0]    [1]    [1x1 analogoutput]    'Channel'
    [1]    [2]    [1x1 analogoutput]    'Channel'

To reference individual channels, you must specify either MATLAB indices or descriptive channel names. Refer to Referencing Individual Hardware Channels for more information.

Configuring Analog Output Properties

After hardware channels are added to the analog output object, you should configure property values. As described in Configuring and Returning Properties, the Data Acquisition Toolbox software supports two basic types of properties for analog output objects: common properties and channel properties. Common properties apply to all channels contained by the device object while channel properties apply to individual channels.

The properties you configure depend on your particular analog output application. For many common applications, there is a small group of properties related to the basic setup that you will typically use. These basic setup properties control the sampling rate and define the trigger type. Analog output properties related to the basic setup are given below.

Table 6-3. Analog Output Basic Setup Properties

Property Name	Description
`SampleRate`	Specify the per-channel rate at which digital data is converted to analog data.
`TriggerType`	Specify the type of trigger to execute.

Setting the Sampling Rate

You control the rate at which an analog output subsystem converts digital data to analog data is controlled with the SampleRate property. SampleRate must be specified as samples per second. For example, to set the sampling rate for each channel of your National Instruments board to 100,000 samples per second (100 kHz):

ao = analogoutput('nidaq','Dev1');
addchannel(ao,0:1);
set(ao,'SampleRate',100000)

Data acquisition boards typically have predefined sampling rates that you can set. If you specify a sampling rate that does not match one of these predefined values, there are two possibilities:

If the rate is within the range of valid values, then the engine automatically selects a valid sampling rate. The rules governing this selection process are described in the SampleRate reference pages.
If the rate is outside the range of valid values, then an error is returned.

Note For some sound cards, you can set the sampling rate to any value between the minimum and maximum values defined by the hardware. You can enable this feature with the StandardSampleRates property. Refer to Device-Specific Properties — Alphabetical List for more information.

Most analog output subsystems allow simultaneous sampling of channels. Therefore, the maximum sampling rate for each channel is given by the maximum board rate.

After setting a value for SampleRate, you should find out the actual rate set by the engine.

ActualRate = get(ao,'SampleRate');

Alternatively, you can use the setverify function, which sets a property value and returns the actual value set.

ActualRate = setverify(ao,'SampleRate',100000);

You can find the range of valid sampling rates for your hardware with the propinfo function.

ValidRates = propinfo(ao,'SampleRate');
ValidRates.ConstraintValue
ans =
  1.0e+005 *
    0.0000    2.0000

Defining a Trigger

For analog output objects, a trigger is defined as an event that initiates the output of data from the engine to the analog output hardware.

Defining a trigger for an analog output object involves specifying the trigger type. Trigger types are specified with the TriggerType property. The valid TriggerType values that are supported for all hardware are given below.

Table 6-4. Analog Output TriggerType Property Values

TriggerType Values	Description
`{Immediate}`	The trigger occurs just after you issue the `start` function.
`Manual`	The trigger occurs just after you manually issue the `trigger` function.

Most devices have hardware-specific trigger types, which are available to you through the TriggerType property. For example, to see all the trigger types (including hardware-specific trigger types) for the analog output object ao created in the preceding section:

set(ao,'TriggerType')
[ Manual | {Immediate} | HwDigital ]

This information tells you that the National Instruments board also supports a hardware digital trigger. For a description of device-specific trigger types, refer to Device-Specific Hardware Triggers, or the TriggerType reference pages.

Outputting Data

After you configure the analog output object, you can output data. Outputting data involves these three steps:

Queuing Data in the Engine

Before you can start the device object, data must be queued in the engine. Data is queued in the engine with the putdata function. For example, to queue one second of data for each channel contained by the analog output object ao:

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

putdata is a blocking function, and will not return execution control to MATLAB until the specified data is queued. putdata is described in detail in Managing Output Data and in Functions — Alphabetical List.

Starting the Analog Output Object

You start an analog output object with the start function. For example, to start the analog output object ao:

start(ao)

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 the device object is running, you can continue to queue data.

However, running does not necessarily mean that data is being output from the engine to the analog output hardware. For that to occur, a trigger must execute. When the trigger executes, the Sending property is automatically set to On. Analog output triggers are described on Defining a Trigger and Configuring Analog Output Triggers.

Stopping the Analog Output Object

An analog output object can stop under one of these conditions:

You issue the stop function.
The queued data is output.
A run-time hardware error occurs.
A time-out occurs.

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

Analog Output Examples

This section illustrates how to perform basic data acquisition tasks using analog output subsystems and the Data Acquisition Toolbox software. For most data acquisition applications using analog output subsystems, you must follow these basic steps:

Install and connect the components of your data acquisition hardware. At a minimum, this involves connecting an actuator to a plug-in or external data acquisition device.
Configure your data acquisition session. This involves creating a device object, adding channels, setting property values, and using specific functions to output data.

Simple data acquisition applications using a sound card and a National Instruments board are given below.

Outputting Data with a Sound Card

In this example, sine wave data is generated in the MATLAB workspace, output to the D/A converter on the sound card, and sent to a speaker. The setup is shown below.

You can run this example by typing daqdoc6_1 at the MATLAB Command Window.

Create a device object — Create the analog output object AO for a sound card. The installed adaptors and hardware IDs are found with daqhwinfo.
```
AO = analogoutput('winsound');
```
Add channels — Add one channel to AO.
```
chan = addchannel(AO,1);
```

Configure property values — Define an output time of four seconds, assign values to the basic setup properties, generate data to be queued, and queue the data with one call to putdata.

duration = 4;
set(AO,'SampleRate',8000)
set(AO,'TriggerType','Manual')
ActualRate = get(AO,'SampleRate');
len = ActualRate*duration;
data = sin(linspace(0,2*pi*500,len))';
putdata(AO,data)

Output data —- Start AO, issue a manual trigger, and wait for the device object to stop running.
```
start(AO)
trigger(AO)
wait(AO,5)
```
Clean up —- When you no longer need AO, you should remove it from memory and from the MATLAB workspace.
```
delete(AO)
clear AO
```

Outputting Data with a National Instruments Board

In this example, sine wave data is generated in the MATLAB workspace, output to the D/A converter on a National Instruments board, and displayed with an oscilloscope. The setup is shown below.

You can run this example by typing daqdoc6_2 at the MATLAB Command Window.

Create a device object — Create the analog output object AO for a National Instruments board. The installed adaptors and hardware IDs are found with daqhwinfo.
```
AO = analogoutput('nidaq','Dev1');
```
Add channels — Add one channel to AO.
```
chan = addchannel(AO,0);
```

Configure property values — Define an output time of four seconds, assign values to the basic setup properties, generate data to be queued, and queue the data with one call to putdata.

duration = 4;
set(AO,'SampleRate',10000)
set(AO,'TriggerType','Manual')
ActualRate = get(AO,'SampleRate');
len = ActualRate*duration;
data = sin(linspace(0,2*pi*500,len))';
putdata(AO,data)

Output data — Start AO, issue a manual trigger, and wait for the device object to stop running.
```
start(AO)
trigger(AO)
wait(AO,5)
```
Clean up — When you no longer need AO, you should remove it from memory and from the MATLAB workspace.
```
delete(AO)
clear AO
```

Evaluating the Analog Output Object Status

You can evaluate the status of an analog output (AO) object by

Returning the values of certain properties
Invoking the display summary

Status Properties

The properties associated with the status of your analog output object allow you to evaluate

If the device object is running
If data is being output from the engine
How much data is queued in the engine
How much data has been output from the engine

These properties are given below.

Table 6-5. Analog Output Status Properties

Property Name	Description
`Running`	Indicate if the device object is running.
`SamplesAvailable`	Indicate the number of samples available per channel in the engine.
`SamplesOutput`	Indicate the number of samples output per channel from the engine.
`Sending`	Indicate if data is being sent (output) to the hardware device.

When data is queued in the engine, SamplesAvailable is updated to reflect the total number of samples per channel that was queued. When start is issued, Running is automatically set to On.

When the trigger executes, Sending is automatically set to On and SamplesOutput keeps a running count of the total number of samples per channel output from the engine to the hardware. Additionally, SamplesAvailable tells you how many samples per channel are still queued in the engine and ready to be output to the hardware.

When all the queued data is output from the engine, both Running and Sending are automatically set to Off, SamplesAvailable is 0, and SamplesOutput reflects the total number of samples per channel that was output.

The Display Summary

You can invoke the display summary by typing an AO object or a channel object at the MATLAB Command Window, or by excluding the semicolon when

Creating an AO object
Adding channels
Configuring property values using the dot notation

You can also display summary information via the Workspace browser by right-clicking a toolbox object and selecting Explore > Display Summary from the context menu.

The information displayed reflects many of the basic setup properties described in Configuring Analog Output Properties, and is designed so you can quickly evaluate the status of your data acquisition session. The display is divided into two main sections: general summary information and channel summary information.

General Summary Information

The general display summary includes the device object type and the hardware device name, followed by this information:

Output parameters — The sampling rate
Trigger parameters — The trigger type
The engine status
- Whether the engine is sending data, waiting to start, or waiting to trigger
- The total time required to output the queued data
- The number of samples queued by putdata
- The number of samples sent to the hardware device