Quantcast

Documentation Center

  • Trial Software
  • Product Updates

Getting Started with Analog Output

Create an Analog Output Object

You must create an Analog Output object with which you can use 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 7-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'

Add 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 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 Reference 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 7-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 Reference Individual Hardware Channels for more information.

Analog Output Properties

After hardware channels are added to the analog output object, you should configure property values. As described in Configure and Return Properties, 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 7-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.

Set 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 the device specific properties 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

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

Output Data

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

  1. Queuing data

  2. Starting the analog output object

  3. Stopping the analog output object

Queue 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 Manage Output Data and in the functions.

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 Define a Trigger and Configure Analog Output Triggers.

Stop 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 Data Acquisition Toolbox software. For most data acquisition applications using analog output subsystems, you must follow these basic steps:

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

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

Output Data with Sound Card

    Note:   You cannot use the legacy interface on 64–bit MATLAB. See Session-Based Interface to acquire and generate data.

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.

  1. 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');
  2. Add channels — Add one channel to AO.

    chan = addchannel(AO,1);
  3. 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)
  4. Output data —- Start AO, issue a manual trigger, and wait for the device object to stop running.

    start(AO)
    trigger(AO)
    wait(AO,5)
  5. Clean up —- When you no longer need AO, you should remove it from memory and from the MATLAB workspace.

    delete(AO)
    clear AO

Output Data with a National Instruments Board

    Note:   You cannot use the legacy interface on 64–bit MATLAB. See Session-Based Interface to acquire and generate data.

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.

  1. 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');
  2. Add channels — Add one channel to AO.

    chan = addchannel(AO,0);
  3. 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)

    To see the samples output, type:

    get (AO, 'SamplesOutput')
    
    ans =
    
            40000
  4. Output data — Start AO, issue a manual trigger, and wait for the device object to stop running.

    start(AO)
    trigger(AO)
    wait(AO,5)
  5. Clean up — When you no longer need AO, you should remove it from memory and from the MATLAB workspace.

    delete(AO)
    clear AO

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

Channel Summary Information

The channel display summary includes property values associated with

  • The hardware channel mapping

  • The channel name

  • The engineering units

The display summary shown below is for the example given in Output Data with Sound Card prior to issuing the start function.

You can use the Channel property to display only the channel summary information.

AO.Channel
Was this topic helpful?