Data Acquisition Toolbox User`s Guide

Data Acquisition Toolbox User`s Guide
Data Acquisition
Toolbox
For Use with MATLAB
®
Computation
Visualization
Programming
User’s Guide
Version 2
How to Contact The MathWorks:
508-647-7000
Phone
508-647-7001
Fax
The MathWorks, Inc.
3 Apple Hill Drive
Natick, MA 01760-2098
Mail
http://www.mathworks.com
Web
Anonymous FTP server
Newsgroup
ftp.mathworks.com
comp.soft-sys.matlab
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
Technical support
Product enhancement suggestions
Bug reports
Documentation error reports
Subscribing user registration
Order status, license renewals, passcodes
Sales, pricing, and general information
Data Acquisition Toolbox User’s Guide
 COPYRIGHT 1999 - 2000 by The MathWorks, Inc.
The software described in this document is furnished under a license agreement. The software may be used
or copied only under the terms of the license agreement. No part of this manual may be photocopied or reproduced in any form without prior written consent from The MathWorks, Inc.
FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by
or for the federal government of the United States. By accepting delivery of the Program, the government
hereby agrees that this software qualifies as "commercial" computer software within the meaning of FAR
Part 12.212, DFARS Part 227.7202-1, DFARS Part 227.7202-3, DFARS Part 252.227-7013, and DFARS Part
252.227-7014. The terms and conditions of The MathWorks, Inc. Software License Agreement shall pertain
to the government’s use and disclosure of the Program and Documentation, and shall supersede any
conflicting contractual terms or conditions. If this license fails to meet the government’s minimum needs or
is inconsistent in any respect with federal procurement law, the government agrees to return the Program
and Documentation, unused, to MathWorks.
MATLAB, Simulink, Stateflow, Handle Graphics, and Real-Time Workshop are registered trademarks, and
Target Language Compiler is a trademark of The MathWorks, Inc.
Other product or brand names are trademarks or registered trademarks of their respective holders.
Printing History: May 1999
First printing
New for Version 1
November 2000 Second printing Revised for Version 2 (Release 12)
Contents
Preface
What Is the Data Acquisition Toolbox? . . . . . . . . . . . . . . . . . . xvi
Exploring the Toolbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Related Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Associated Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Using This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Expected Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Using the Documentation Examples . . . . . . . . . . . . . . . . . . . . . . xx
How This Guide is Organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx
Installation Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Toolbox Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Hardware and Driver Installation . . . . . . . . . . . . . . . . . . . . . . xxii
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Introduction to Data Acquisition
1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Anatomy of a Data Acquisition Experiment . . . . . . . . . . . . . 1-3
The Data Acquisition System . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Data Acquisition Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Sensors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Signal Conditioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
The Computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
i
Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
The Analog Input Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . .
Sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Quantization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Channel Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transferring Data from Hardware to System Memory . . . . . .
1-16
1-16
1-20
1-24
1-27
Making Quality Measurements . . . . . . . . . . . . . . . . . . . . . . . .
Accuracy and Precision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Noise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Matching the Sensor Range and A/D Converter Range . . . . . .
How Fast Should a Signal be Sampled? . . . . . . . . . . . . . . . . . .
1-29
1-29
1-33
1-34
1-35
Selected Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-39
Getting Started with the Data Acquisition Toolbox
2
Toolbox Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
M-File Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Data Acquisition Engine . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Hardware Driver Adaptor . . . . . . . . . . . . . . . . . . . . . . . . . .
2-2
2-3
2-4
2-7
Accessing Your Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Acquiring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Outputting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Reading and Writing Digital Values . . . . . . . . . . . . . . . . . . . . . 2-10
Understanding the Toolbox Capabilities . . . . . . . . . . . . . . .
The Contents and Readme Files . . . . . . . . . . . . . . . . . . . . . . . .
Documentation Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Quick Reference Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Demos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-12
2-12
2-12
2-13
2-13
Examining Your Hardware Resources . . . . . . . . . . . . . . . . . 2-17
General Toolbox Information . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
ii
Contents
Adaptor-Specific Information . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18
Device Object Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19
Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20
The daqhelp Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20
The propinfo Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
The Data Acquisition Session
3
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Example: The Data Acquisition Session . . . . . . . . . . . . . . . . . . . 3-3
Creating a Device Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Creating an Array of Device Objects . . . . . . . . . . . . . . . . . . . . . . 3-5
Where Do Device Objects Exist? . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
Adding Channels or Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
Mapping Hardware Channel IDs to MATLAB Indices . . . . . . . 3-9
Configuring and Returning Properties . . . . . . . . . . . . . . . . .
Property Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Returning Property Names and Property Values . . . . . . . . . .
Configuring Property Values . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Property Names . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default Property Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
daqpropedit: A Graphical Property Editor . . . . . . . . . . . . . . . .
3-12
3-12
3-14
3-18
3-19
3-19
3-20
Acquiring and Outputting Data . . . . . . . . . . . . . . . . . . . . . . .
Starting the Device Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging or Sending Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stopping the Device Object . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3-22
3-23
3-23
3-24
Cleaning Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25
iii
Getting Started with Analog Input
4
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Creating an Analog Input Object . . . . . . . . . . . . . . . . . . . . . . . 4-3
Adding Channels to an Analog Input Object . . . . . . . . . . . . . 4-4
Referencing Individual Hardware Channels . . . . . . . . . . . . . . . 4-6
Example: Adding Channels for a Sound Card . . . . . . . . . . . . . . 4-7
Configuring Analog Input Properties . . . . . . . . . . . . . . . . . . . 4-9
The Sampling Rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9
Trigger Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11
The Samples to Acquire per Trigger . . . . . . . . . . . . . . . . . . . . . 4-12
Acquiring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the Analog Input Object . . . . . . . . . . . . . . . . . . . . . . .
Logging Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stopping the Analog Input Object . . . . . . . . . . . . . . . . . . . . . . .
4-13
4-13
4-14
4-14
Analog Input Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15
Acquiring Data with a Sound Card . . . . . . . . . . . . . . . . . . . . . . 4-15
Acquiring Data with a National Instruments Board . . . . . . . . 4-19
Evaluating the Analog Input Object Status . . . . . . . . . . . . . 4-22
Status Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22
The Display Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
Doing More with Analog Input
5
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Configuring and Sampling Input Channels . . . . . . . . . . . . . . 5-3
Input Channel Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Sampling Rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
iv
Contents
Channel Skew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Managing Acquired Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
Previewing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
Extracting Data from the Engine . . . . . . . . . . . . . . . . . . . . . . . 5-13
Returning Time Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
Configuring Analog Input Triggers . . . . . . . . . . . . . . . . . . . .
Defining a Trigger: Trigger Types and Conditions . . . . . . . . .
Executing the Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Trigger Delays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Repeating Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How Many Triggers Occurred? . . . . . . . . . . . . . . . . . . . . . . . . .
When Did the Trigger Occur? . . . . . . . . . . . . . . . . . . . . . . . . . .
Device-Specific Hardware Triggers . . . . . . . . . . . . . . . . . . . . . .
5-20
5-21
5-26
5-26
5-30
5-36
5-37
5-37
Configuring Events and Actions . . . . . . . . . . . . . . . . . . . . . . .
Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Recording and Retrieving Event Information . . . . . . . . . . . . .
Creating and Executing Action Functions . . . . . . . . . . . . . . . .
Examples: Using Action Properties and Functions . . . . . . . . .
5-46
5-46
5-49
5-52
5-53
Linearly Scaling the Data: Engineering Units . . . . . . . . . . . 5-56
Example: Performing a Linear Conversion . . . . . . . . . . . . . . . 5-57
Analog Output
6
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Getting Started with Analog Output . . . . . . . . . . . . . . . . . . . . 6-3
Creating an Analog Output Object . . . . . . . . . . . . . . . . . . . . . . . 6-3
Adding Channels to an Analog Output Object . . . . . . . . . . . . . . 6-4
Configuring Analog Output Properties . . . . . . . . . . . . . . . . . . . . 6-6
Outputting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
Analog Output Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
Evaluating the Analog Output Object Status . . . . . . . . . . . . . 6-14
v
Managing Output Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
Queuing Data with putdata . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
Example: Queuing Data with putdata . . . . . . . . . . . . . . . . . . . 6-19
Configuring Analog Output Triggers . . . . . . . . . . . . . . . . . . .
Defining a Trigger: Trigger Types . . . . . . . . . . . . . . . . . . . . . . .
Executing the Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How Many Triggers Occurred? . . . . . . . . . . . . . . . . . . . . . . . . .
When Did the Trigger Occur? . . . . . . . . . . . . . . . . . . . . . . . . . .
Device-Specific Hardware Triggers . . . . . . . . . . . . . . . . . . . . . .
6-21
6-22
6-23
6-23
6-24
6-25
Configuring Events and Actions . . . . . . . . . . . . . . . . . . . . . . .
Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Recording and Retrieving Event Information . . . . . . . . . . . . .
Examples: Using Action Properties and Action Functions . . .
6-27
6-27
6-29
6-31
Linearly Scaling the Data: Engineering Units . . . . . . . . . . . 6-34
Example: Performing a Linear Conversion . . . . . . . . . . . . . . . 6-35
Starting Multiple Device Objects . . . . . . . . . . . . . . . . . . . . . . 6-37
Digital Input/Output
7
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Creating a Digital I/O Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Adding Lines to a Digital I/O Object . . . . . . . . . . . . . . . . . . . . 7-4
Line and Port Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Referencing Individual Hardware Lines . . . . . . . . . . . . . . . . . . 7-8
Writing and Reading Digital I/O Line Values . . . . . . . . . . .
Writing Digital Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reading Digital Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: Writing and Reading Digital Values . . . . . . . . . . . .
vi
Contents
7-10
7-10
7-12
7-13
Generating Timer Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Timer Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting and Stopping a Digital I/O Object . . . . . . . . . . . . . . .
Example: Generating Timer Events . . . . . . . . . . . . . . . . . . . . .
7-15
7-15
7-16
7-17
Evaluating the Digital I/O Object Status . . . . . . . . . . . . . . . . 7-18
The Display Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18
Saving and Loading the Session
8
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Saving and Loading Device Objects . . . . . . . . . . . . . . . . . . . . . 8-3
Saving Device Objects to an M-File . . . . . . . . . . . . . . . . . . . . . . 8-3
Saving Device Objects to a MAT-File . . . . . . . . . . . . . . . . . . . . . 8-5
Logging Information to Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6
Specifying a Filename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Retrieving Logged Information . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8
Example: Logging and Retrieving Information . . . . . . . . . . . . 8-10
Function Reference
9
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
Getting Command Line Function Help . . . . . . . . . . . . . . . . . . . 9-2
Functions Grouped by Category . . . . . . . . . . . . . . . . . . . . . . . . 9-4
Functions Listed Alphabetically . . . . . . . . . . . . . . . . . . . . . . . . 9-8
addchannel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
addline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-14
addmuxchannel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17
vii
analoginput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
analogoutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
binvec2dec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
daqaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
daqfind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
daqhelp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
daqhwinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
daqmem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
daqpropedit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
daqread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
daqregister . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
daqreset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
daqschool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dec2binvec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
digitalio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
disp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
flushdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getsample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getvalue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ischannel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
isdioline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
isvalid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
makenames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
muxchanidx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
obj2mfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
peekdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
propinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
putdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
putsample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
putvalue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
setverify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
showdaqevents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
viii Contents
9-18
9-21
9-24
9-25
9-27
9-28
9-30
9-32
9-34
9-37
9-39
9-43
9-44
9-45
9-46
9-48
9-50
9-52
9-53
9-55
9-57
9-61
9-62
9-63
9-64
9-65
9-67
9-69
9-71
9-72
9-74
9-76
9-78
9-80
9-82
9-83
9-84
9-85
9-88
9-90
size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
waittilstop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9-92
9-94
9-95
9-97
9-98
Base Property Reference
10
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2
Getting Command Line Property Help . . . . . . . . . . . . . . . . . . . 10-2
Properties Grouped by Category . . . . . . . . . . . . . . . . . . . . . . 10-3
Analog Input Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3
Analog Output Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8
Digital I/O Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12
Properties Listed Alphabetically . . . . . . . . . . . . . . . . . . . . .
BufferingConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BufferingMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ChannelName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ChannelSkew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ChannelSkewMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ClockSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DataMissedAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DefaultChannelValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Direction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EventLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HwChannel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HwLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
InitialTriggerTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
InputOverRangeAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
InputRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
InputType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10-14
10-15
10-17
10-18
10-20
10-21
10-22
10-24
10-26
10-27
10-28
10-29
10-31
10-33
10-34
10-36
10-38
10-39
10-41
10-43
ix
LineName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LogFileName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LoggingMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LogToDiskMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ManualTriggerHwOn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MaxSamplesQueued . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NativeOffset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NativeScaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OutputRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RepeatOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RuntimeErrorAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SampleRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SamplesAcquired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SamplesAcquiredAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SamplesAcquiredActionCount . . . . . . . . . . . . . . . . . . . . . . . . .
SamplesAvailable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SamplesOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SamplesOutputAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SamplesOutputActionCount . . . . . . . . . . . . . . . . . . . . . . . . . .
SamplesPerTrigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SensorRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
StartAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
StopAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TimerAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TimerPeriod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TriggerAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TriggerChannel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TriggerCondition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TriggerConditionValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TriggerDelay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TriggerDelayUnits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TriggerRepeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
x
Contents
10-44
10-45
10-46
10-47
10-48
10-49
10-51
10-52
10-53
10-55
10-56
10-58
10-59
10-60
10-61
10-62
10-64
10-66
10-67
10-68
10-69
10-70
10-71
10-72
10-73
10-74
10-75
10-76
10-77
10-79
10-80
10-81
10-82
10-83
10-84
10-85
10-89
10-90
10-91
10-92
TriggersExecuted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TriggerType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UnitsRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UserData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10-93
10-94
10-96
10-97
10-98
10-99
Device-Specific Property Reference
11
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Getting Command Line Property Help . . . . . . . . . . . . . . . . . . . 11-2
Properties Listed by Vendor . . . . . . . . . . . . . . . . . . . . . . . . . .
National Instruments Properties . . . . . . . . . . . . . . . . . . . . . . .
ComputerBoards Properties . . . . . . . . . . . . . . . . . . . . . . . . . . .
Agilent Technologies Properties . . . . . . . . . . . . . . . . . . . . . . . .
Sound Card Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11-3
11-3
11-4
11-4
11-5
Properties Listed Alphabetically . . . . . . . . . . . . . . . . . . . . . . 11-6
BitsPerSample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7
COLA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-8
Coupling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-9
DriveAISenseToGround . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10
GroundingMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-11
InputMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-12
InputSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-14
NumMuxBoards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-15
OutOfDataMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-16
RampRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-17
SourceMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-18
SourceOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-19
Span . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-21
StandardSampleRates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-23
Sum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-24
TransferMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-25
xi
Troubleshooting Your Hardware
A
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2
Troubleshooting National Instruments Hardware . . . . . . . . A-3
What Driver Are You Using? . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Is Your Hardware Functioning Properly? . . . . . . . . . . . . . . . . . A-5
Troubleshooting ComputerBoards Hardware . . . . . . . . . . . . A-6
What Driver Are You Using? . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
Is Your Hardware Functioning Properly? . . . . . . . . . . . . . . . . . A-8
Troubleshooting Agilent Technologies Hardware . . . . . . . . A-9
What Driver Are You Using? . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9
Is Your Hardware Functioning Properly? . . . . . . . . . . . . . . . . A-10
Troubleshooting Sound Cards . . . . . . . . . . . . . . . . . . . . . . . . .
Microphone and Sound Card Types . . . . . . . . . . . . . . . . . . . . .
Testing with a Microphone . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing with a CD Player . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running in Full Duplex Mode . . . . . . . . . . . . . . . . . . . . . . . . . .
A-12
A-15
A-16
A-16
A-18
Other Things to Try . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-19
Registering the Hardware Driver Adaptor . . . . . . . . . . . . . . . . A-19
Contacting The MathWorks . . . . . . . . . . . . . . . . . . . . . . . . . . . A-20
Managing Your Memory Resources
B
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2
How Much Memory Do You Need? . . . . . . . . . . . . . . . . . . . . . . B-3
Example: Managing Memory Resources . . . . . . . . . . . . . . . . . B-4
xii
Contents
Glossary
C
xiii
xiv Contents
Preface
What Is the Data Acquisition Toolbox? . . . . . . . . xvi
Exploring the Toolbox . . . . . . . . . . . . . . . . . xvi
Related Products . . . . . . . . . . . . . . . . . . xvii
System Requirements . . . . . . . . . . . . . . . . . xvii
Associated Products . . . . . . . . . . . . . . . . . xvii
Using This Guide . . . . . . .
Expected Background . . . . . .
Using the Documentation Examples
How This Guide is Organized . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xix
xix
. xx
. xx
Installation Information . . . . . . . . . . . . . . xxii
Toolbox Installation . . . . . . . . . . . . . . . . . xxii
Hardware and Driver Installation . . . . . . . . . . . . xxii
Typographical Conventions . . . . . . . . . . . . . xxiii
Preface
What Is the Data Acquisition Toolbox?
The Data Acquisition Toolbox is a collection of M-file functions and MEX-file
dynamic link libraries (DLLs) built on the MATLAB® Technical Computing
Environment. The toolbox provides you with these main features:
• A framework for bringing live, measured data into MATLAB using
PC-compatible, plug-in data acquisition hardware
• Support for these popular hardware devices:
- National Instruments E Series and 1200 Series boards
- ComputerBoards (Measurement Computing Corporation) boards
- Agilent Technologies E1432A/33A/34A VXI modules
- Microsoft Windows sound cards
Additionally, you can use the Data Acquisition Toolbox Adaptor Kit to
interface unsupported hardware devices to the toolbox.
• Support for analog input (AI), analog output (AO), and digital I/O (DIO)
subsystems including simultaneous AI and AO conversions
• Data buffering for background acquisitions
• Data logging
• Event-driven acquisitions
Exploring the Toolbox
A list of the toolbox functions is available to you by typing
help daq
You can view the code for any function by typing
type function_name
You can view the help for any function by typing
daqhelp function_name
You can change the way any toolbox function works by copying and renaming
the M-file, then modifying your copy. You can also extend the toolbox by adding
your own M-files, or by using it in combination with other products such as the
Signal Processing Toolbox or the Instrument Control Toolbox.
xvi
Related Products
Related Products
System Requirements
The Data Acquisition Toolbox is a multiplatform product that you install on a
host computer running Microsoft Windows 95, Windows 98, Windows 2000, or
Windows NT 4.0.
The toolbox requires:
• MATLAB 6.0 (Release 12)
• A supported data acquisition device – for a complete listing of all supported
devices, visit the Data Acquisition Toolbox section of the MathWorks Web
site at http://www.mathworks.com/products/daq/
• Software such as drivers and support libraries, as required by your data
acquisition device
Associated Products
The MathWorks provides several associated products that are especially
relevant to the kinds of tasks you can perform with the Data Acquisition
Toolbox. For more information about any of these products, see either:
• The online documentation for that product, if it is installed or if you are
reading the documentation from the CD
• The MathWorks Web site, at http://www.mathworks.com; see the “products”
section
Note The toolboxes listed below all include functions that extend MATLAB’s
capabilities.
xvii
Preface
Products Associated with the Data Acquisition Toolbox
xviii
Product
Description
Control System Toolbox
Tool for modeling, analyzing, and designing
control systems using classical and modern
techniques
Database Toolbox
Tool for connecting to, and interacting with,
most ODBC/JDBC databases from within
MATLAB
Instrument Control
Toolbox
Tool for communicating with instruments that
support the GPIB (IEEE-488, HPIB) interface,
the VISA standard, or the serial port interface
MATLAB Report
Generator
Tool for documenting information in MATLAB
in multiple output formats
Neural Network Toolbox
A comprehensive environment for neural
network research, design, and simulation
within MATLAB
Signal Processing
Toolbox
Tool for algorithm development, signal and
linear system analysis, and time-series data
modeling
Statistics Toolbox
Tool for analyzing historical data, modeling
systems, developing statistical algorithms, and
learning and teaching statistics
System Identification
Toolbox
Tool for building accurate, simplified models of
complex systems from noisy time-series data
Wavelet Toolbox
Tool for signal and image analysis,
compression, and de-noising
Using This Guide
Using This Guide
Expected Background
To use the Data Acquisition Toolbox, you should have some familiarity with:
• The basic features of MATLAB
• The capabilities of your hardware device
• The basic concepts associated with acquiring live, measured data
If You Are a New User
For a brief review of basic data acquisition concepts, you should start with
Chapter 1, “Introduction to Data Acquisition.” Otherwise, start with Chapter
2, “Getting Started with the Data Acquisition Toolbox”, which provides simple
examples that illustrate how to input and output data. Then read the
appropriate chapter based on the hardware subsystem you are using. For
example, if you are acquiring data with an analog input subsystem, you should
read Chapter 4, “Getting Started with Analog Input.”
After you have successfully transferred data between your hardware device
and MATLAB, you should read the appropriate reference material as needed.
If you want detailed information about a specific function, refer to Chapter 9,
“Function Reference.” If you want detailed information about a specific
property, refer to Chapter 10, “Base Property Reference” or Chapter 11,
“Device-Specific Property Reference.”
If You Are an Experienced User
Start with “Data Acquisition Toolbox 2.0” in the Release Notes for a description
of new and modified toolbox features.
You should then read the appropriate reference material as needed. If you want
detailed information about a specific function, refer to Chapter 9, “Function
Reference.” If you want detailed information about a specific property, refer to
Chapter 10, “Base Property Reference” or Chapter 11, “Device-Specific
Property Reference.”
xix
Preface
Using the Documentation Examples
When you encounter examples or code snippets in this book, you may want to
try them for yourself. An easy way to do this is to cut the relevant text from the
PDF or HTML versions of this guide and paste it into the MATLAB workspace.
You access the PDF and HTML content with the Help browser.
Some examples are constructed as mini-applications that illustrate one or two
important toolbox features, and serve as templates so you can see how to build
applications that suit your specific needs. These examples are included as
toolbox M-files and are treated as demos. You can list all Data Acquisition
Toolbox demos by typing
help daqdemos
All documentation example M-files begin with daqdoc. To run an example, type
the M-file name at the command line. Note that most examples are written for
specific hardware devices. To use these examples with your hardware device,
you should modify the creation function input arguments and the device object
property values as needed.
How This Guide is Organized
The organization of this guide is described below.
xx
Chapter
Description
Introduction to Data
Acquisition
Provides you with general information about
making measurements with data acquisition
hardware. The topics covered should help you
understand the specification sheet associated with
your hardware.
Getting Started with
the Data Acquisition
Toolbox
Describes the toolbox components, and shows you
how to access your hardware, examine your
hardware resources, and get command line help.
The Data Acquisition
Session
Describes all the steps you are likely to take when
acquiring or outputting data.
Getting Started with
Analog Input
Shows you how to perform basic data acquisition
tasks using your analog input subsystem.
Using This Guide
Chapter
Description
Doing More with
Analog Input
Presents the complete analog input functionality.
Analog Output
Shows you how to perform data acquisition tasks
using your analog output subsystem.
Digital Input/Output
Shows you how to perform data acquisition tasks
using your digital I/O subsystem.
Saving and Loading
the Session
Shows you how to save and load device objects,
data, and event information using several disk file
formats.
Function Reference
Presents a complete description of all toolbox
functions.
Base Property
Reference
Presents a complete description of all toolbox base
properties.
Device-Specific
Property Reference
Presents a complete description of all toolbox
device-specific properties.
Troubleshooting
Your Hardware
Presents tips to help you troubleshoot your
hardware.
Managing Your
Memory Resources
Describes how to allocate and return memory
resources.
Glossary
Presents a glossary of data acquisition terms.
xxi
Preface
Installation Information
To acquire live, measured data into the MATLAB environment, or to output
data from the MATLAB environment, you must install these three
components:
• The Data Acquisition Toolbox
• Data acquisition hardware
• Software such as drivers and support libraries, as required by your data
acquisition hardware
Toolbox Installation
To determine if the Data Acquisition Toolbox is installed on your system, type
ver
at the MATLAB prompt. MATLAB displays information about the versions of
MATLAB you are running, including a list of installed add-on products and
their version numbers. Check the list to see if the Data Acquisition Toolbox
appears. For information about installing the toolbox, see the MATLAB
Installation Guide for your platform.
If you experience installation difficulties and have Web access, look for the
license manager and installation information at the MathWorks Web site
(http://www.mathworks.com).
Hardware and Driver Installation
Installation of your hardware device, hardware drivers, and any other
device-specific software is described in the documentation provided by your
hardware vendor.
Note You need to install all necessary device-specific software provided by
your hardware vendor in addition to the Data Acquisition Toolbox.
xxii
Typographical Conventions
Typographical Conventions
This guide uses the following typographical conventions.
Item
Convention to Use
Example
Example code
Monospace font
To assign the value 5 to A,
enter
A = 5
Function names/syntax
Monospace font
The cos function finds the
cosine of each array element.
Syntax line example is
MLGetVar ML_var_name
Keys
Boldface with an initial
capital letter
Press the Return key.
Literal string (in syntax
descriptions in Reference
chapters)
Use monospace bold for
literals.
f = freqspace(n,'whole')
Mathematical
expressions
Variables in italics
This vector represents the
polynomial
MATLAB output
Functions, operators, and
constants in standard text.
Monospace font
p = x2 + 2x + 3
MATLAB responds with
A =
5
Menu names, menu items, and
controls
Boldface with an initial
capital letter
Choose the File menu.
New terms
Italics
An array is an ordered
collection of information.
String variables (from a finite
list)
Monospace italics
sysc = d2c(sysd, 'method')
xxiii
Preface
xxiv
1
Introduction to Data
Acquisition
Overview
. . . . . . . . . . . . . . . . . . . . . 1-2
Anatomy of a Data Acquisition Experiment . . . . . . 1-3
The Data Acquisition System
Data Acquisition Hardware . .
Sensors . . . . . . . . . . .
Signal Conditioning . . . . .
The Computer . . . . . . . .
Software . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 1-4
. 1-6
. 1-8
. 1-11
. 1-13
. 1-13
The Analog Input Subsystem . . . . . . . . .
Sampling . . . . . . . . . . . . . . . . . . .
Quantization . . . . . . . . . . . . . . . . .
Channel Configuration . . . . . . . . . . . . .
Transferring Data from Hardware to System Memory
.
.
.
.
.
.
.
.
.
.
. 1-16
. 1-16
. 1-20
. 1-24
. 1-27
Making Quality Measurements . . . . . . . .
Accuracy and Precision . . . . . . . . . . . . .
Noise . . . . . . . . . . . . . . . . . . . .
Matching the Sensor Range and A/D Converter Range
How Fast Should a Signal be Sampled? . . . . . .
.
.
.
.
.
.
.
.
.
.
. 1-29
. 1-29
. 1-33
. 1-34
. 1-35
Selected Bibliography
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . 1-39
1
Introduction to Data Acquisition
Overview
Before you set up any data acquisition system, you should understand the
physical quantities you want to measure, the characteristics of those physical
quantities, the appropriate sensor to use, and the appropriate data acquisition
hardware to use.
The purpose of this chapter is to provide you with some general information
about making measurements with a data acquisition system. The topics
covered should assist you in understanding the above considerations, and
understanding the specification sheet associated with your hardware. Topics
include:
• Anatomy of a data acquisition experiment
• The data acquisition system
• The analog input subsystem
• Making quality measurements
• Selected bibliography
1-2
Anatomy of a Data Acquisition Experiment
Anatomy of a Data Acquisition Experiment
For each new data acquisition experiment, you need to perform these tasks:
• System setup
• Calibration
• Trials
System Setup
The first step in any data acquisition experiment is to install the hardware and
software. Hardware installation consists of plugging a board into your
computer or installing modules into an external chassis. Software installation
consists of loading hardware drivers and application software onto your
computer. After the hardware and software are installed, you can attach your
sensors.
Calibration
After the hardware and software are installed and the sensors are connected,
the data acquisition hardware should be calibrated. Calibration consists of
providing a known input to the system and recording the output. For many
data acquisition devices, calibration can be easily accomplished with software
provided by the vendor.
Trials
After the hardware is set up and calibrated, you can begin to acquire data. You
may think that if you completely understand the characteristics of the signal
you are measuring, then you should be able to configure your data acquisition
system and acquire the data.
In the real world however, your sensor may be picking up unacceptable noise
levels and require shielding, or you may need to run the device at a higher rate,
or perhaps you need to add an antialias filter to remove unwanted frequency
components.
These real-world effects act as obstacles between you and a precise, accurate
measurement. To overcome these obstacles, you need to experiment with
different hardware and software configurations. In other words, you need to
perform multiple data acquisition trials.
1-3
1
Introduction to Data Acquisition
The Data Acquisition System
As a user of MATLAB and the Data Acquisition Toolbox, you are interested in
measuring and analyzing physical phenomena. The purpose of any data
acquisition system is to provide you with the tools and resources necessary to
do so.
You can think of a data acquisition system as a collection of software and
hardware that connects you to the physical world. A typical data acquisition
system consists of these components:
• Data acquisition hardware
At the heart of any data acquisition system lies the data acquisition
hardware. The main function of this hardware is to convert analog signals to
digital signals, and to convert digital signals to analog signals.
• Sensors and actuators (transducers)
Sensors and actuators can both be transducers. A transducer is a device that
converts input energy of one form into output energy of another form. For
example, a microphone is a sensor that converts sound energy (in the form of
pressure) into electrical energy, while a loudspeaker is an actuator that
converts electrical energy into sound energy.
• Signal conditioning hardware
Sensor signals are often incompatible with data acquisition hardware. To
overcome this incompatibility, the signal must be conditioned. For example,
you may need to condition an input signal by amplifying it or by removing
unwanted frequency components. Output signals may need conditioning as
well. However, only input signal conditioning is discussed in this chapter.
• The computer
The computer provides a processor, a system clock, a bus to transfer data,
and memory and disk space to store data.
• Software
Data acquisition software allows you to exchange information between the
computer and the hardware. For example, typical software allows you to
configure the sampling rate of your board, and acquire a predefined amount
of data.
1-4
The Data Acquisition System
The data acquisition components, and their relationship to each other, are
shown below.
Physical
phenomena
Data Acquisition System
Sensor
Signal
conditioning
Acquisition
hardware
Computer
Software
Actuator
Data
analysis
Physical
phenomena
The figure depicts the two important features of a data acquisition system:
• Signals are input to a sensor, conditioned, converted into bits that a
computer can read, and analyzed to extract meaningful information.
For example, sound level data is acquired from a microphone, amplified,
digitized by a sound card, and stored in MATLAB for subsequent analysis of
frequency content.
1-5
1
Introduction to Data Acquisition
• Data from a computer is converted into an analog signal and output to an
actuator.
For example, a vector of data in MATLAB is converted to an analog signal by
a sound card and output to a loudspeaker.
Data Acquisition Hardware
Data acquisition hardware is either internal and installed directly into an
expansion slot inside your computer, or external and connected to your
computer through an external cable. For example, VXI modules are installed
in an external VXI chassis, and data is transferred between MATLAB and the
module using an external link such as FireWire (IEEE 1394).
At the simplest level, data acquisition hardware is characterized by the
subsystems it possesses. A subsystem is a component of your data acquisition
hardware that performs a specialized task. Common subsystems include:
• Analog input
• Analog output
• Digital input/output
• Counter/timer
Hardware devices that consist of multiple subsystems, such as the one depicted
below, are called multifunction boards.
1-6
Analog input
subsystem
Analog output
subsystem
Digital I/O
subsystem
Counter/timer
subsystem
The Data Acquisition System
Analog Input Subsystems
Analog input subsystems convert real-world analog input signals from a sensor
into bits that can be read by your computer. Perhaps the most important of all
the subsystems commonly available, they are typically multichannel devices
offering 12 or 16 bits of resolution.
Analog input subsystems are also referred to as AI subsystems, A/D converters,
or ADCs. Analog input subsystems are discussed in detail beginning in “The
Analog Input Subsystem” on page 1-16.
Analog Output Subsystems
Analog output subsystems convert digital data stored on your computer to a
real-world analog signal. These subsystems perform the inverse conversion of
analog input subsystems. Typical acquisition boards offer two output channels
with 12 bits of resolution, with special hardware available to support multiple
channel analog output operations.
Analog output subsystems are also referred to as AO subsystems, D/A
converters, or DACs.
Digital Input/Output Subsystems
Digital input/output (DIO) subsystems are designed to input and output digital
values (logic levels) to and from hardware. These values are typically handled
either as single bits or lines, or as a port, which typically consists of eight lines.
While most popular data acquisition cards include some digital I/O capability,
it is usually limited to simple operations, and special dedicated hardware is
often necessary for performing advanced digital I/O operations.
Counter/Timer Subsystems
Counter/timer (C/T) subsystems are used for event counting, frequency and
period measurement, and pulse train generation.
1-7
1
Introduction to Data Acquisition
Sensors
A sensor converts the physical phenomena of interest into a signal that is input
into your data acquisition hardware. There are two main types of sensors based
on the output they produce: digital sensors and analog sensors.
Digital sensors produce an output signal that is a digital representation of the
input signal, and has discrete values of magnitude measured at discrete times.
A digital sensor must output logic levels that are compatible with the digital
receiver. Some standard logic levels include transistor-transistor logic (TTL)
and emitter-coupled logic (ECL). Examples of digital sensors include switches
and position encoders.
Analog sensors produce an output signal that is directly proportional to the
input signal, and is continuous in both magnitude and in time. Most physical
variables such as temperature, pressure, and acceleration are continuous in
nature and are readily measured with an analog sensor. For example, the
temperature of an automobile cooling system and the acceleration produced by
a child on a swing all vary continuously.
The sensor you use depends on the phenomena you are measuring. Some
common analog sensors and the physical variables they measure are listed
below.
Table 1-1: Common Analog Sensors
1-8
Sensor
Physical Variable
Accelerometer
Acceleration
Microphone
Pressure
Pressure gauge
Pressure
Resistance temperature
device (RTD)
Temperature
Strain gauge
Force
Thermocouple
Temperature
The Data Acquisition System
When choosing the best analog sensor to use, you must match the
characteristics of the physical variable you are measuring with the
characteristics of the sensor. The two most important sensor characteristics
are:
• The sensor output
• The sensor bandwidth
Sensor Output
The output from a sensor can be an analog signal or a digital signal, and the
output variable is usually a voltage although some sensors output current.
Current Signals. Current is often used to transmit signals in noisy environments
because it is much less affected by environmental noise. The full scale range of
the current signal is often either 4-20 mA or 0-20 mA. A 4-20 mA signal has the
advantage that even at minimum signal value, there should be a detectable
current flowing. The absence of this indicates a wiring problem.
Before conversion by the analog input subsystem, the current signals are
usually turned into voltage signals by a current-sensing resistor. The resistor
should be of high precision, perhaps 0.03% or 0.01% depending on the
resolution of your hardware. Additionally, the voltage signal should match the
signal to an input range of the analog input hardware. For 4-20 mA signals, a
50 ohm resistor will give a voltage of 1 V for a 20 mA signal by Ohm’s law.
Voltage Signals. The most commonly interfaced signal is a voltage signal. For
example, thermocouples, strain gauges, and accelerometers all produce voltage
signals. There are three major aspects of a voltage signal that you need to
consider:
• Amplitude
If the signal is smaller than a few millivolts, you may need to amplify it. If it
is larger than the maximum range of your analog input hardware (typically
±10 V), you will have to divide the signal down using a resistor network.
The amplitude is related to the sensitivity (resolution) of your hardware.
Refer to “Accuracy and Precision” on page 1-29 for more information about
hardware sensitivity.
1-9
1
Introduction to Data Acquisition
• Frequency
Whenever you acquire data, you should decide the highest frequency you
want to measure.
The highest frequency component of the signal determines how often you
should sample the input. If you have more than one input, but only one
analog input subsystem, then the overall sampling rate goes up in proportion
to the number of inputs. Higher frequencies may be present as noise, which
you can remove by filtering the signal before it is digitized.
If you sample the input signal at least twice as fast as the highest frequency
component, then that signal will be uniquely characterized. However, this
rate may not mimic the waveform very closely. For a rapidly varying signal,
you may need a sampling rate of roughly 10 to 20 times the highest frequency
to get an accurate picture of the waveform. For slowly varying signals, you
need only consider the minimum time for a significant change in the signal.
The frequency is related to the bandwidth of your measurement. Bandwidth
is discussed in the next section.
• Duration
How long do you want to sample the signal for? If you are storing data to
memory or to a disk file, then the duration determines the storage resources
required. The format of the stored data also affects the amount of storage
space required. For example, data stored in ASCII format takes more space
than data stored in binary format.
Sensor Bandwidth
In a real-world data acquisition experiment, the physical phenomena you are
measuring has expected limits. For example, the temperature of your
automobile’s cooling system varies continuously between its low limit and high
limit. The temperature limits, as well as how rapidly the temperature varies
between the limits, depends on several factors including your driving habits,
the weather, and the condition of the cooling system. The expected limits may
be readily approximated, but there are an infinite number of possible
temperatures that you can measure at a given time. As explained in
“Quantization” on page 1-20, these unlimited possibilities are mapped to a
finite set of values by your data acquisition hardware.
The bandwidth is given by the range of frequencies present in the signal being
measured. You can also think of bandwidth as being related to the rate of
change of the signal. A slowly varying signal has a low bandwidth, while a
1-10
The Data Acquisition System
rapidly varying signal has a high bandwidth. To properly measure the physical
phenomena of interest, the sensor bandwidth must be compatible with the
measurement bandwidth.
You may want to use sensors with the widest possible bandwidth when making
any physical measurement. This is the one way to ensure that the basic
measurement system is capable of responding linearly over the full range of
interest. However, the wider the bandwidth of the sensor, the more you must
be concerned with eliminating sensor response to unwanted frequency
components.
Signal Conditioning
Sensor signals are often incompatible with data acquisition hardware. To
overcome this incompatibility, the sensor signal must be conditioned. The type
of signal conditioning required depends on the sensor you are using. For
example, a signal may have a small amplitude and require amplification, or it
may contain unwanted frequency components and require filtering. Common
ways to condition signals include:
• Amplification
• Filtering
• Electrical isolation
• Multiplexing
• Excitation source
Amplification
Low-level signals – less than around 100 millivolts – usually need to be
amplified. High-level signals may also require amplification depending on the
input range of the analog input subsystem.
For example, the output signal from a thermocouple is small and must be
amplified before it is digitized. Signal amplification allows you to reduce noise
and to make use of the full range of your hardware thereby increasing the
resolution of the measurement.
1-11
1
Introduction to Data Acquisition
Filtering
Filtering removes unwanted noise from the signal of interest. A noise filter is
used on slowly varying signals such as temperature to attenuate higher
frequency signals that can reduce the accuracy of your measurement.
Rapidly varying signals such as vibration often require a different type of filter
known as an antialiasing filter. An antialiasing filter removes undesirable
higher frequencies that may lead to erroneous measurements.
Electrical Isolation
If the signal of interest may contain high-voltage transients that could damage
the computer, then the sensor signals should be electrically isolated from the
computer for safety purposes.
You can also use electrical isolation to make sure that the readings from the
data acquisition hardware are not affected by differences in ground potentials.
For example, when the hardware device and the sensor signal are each
referenced to ground, problems occur if there is a potential difference between
the two grounds. This difference can lead to a ground loop, which may lead to
erroneous measurements. Using electrically isolated signal conditioning
modules eliminates the ground loop and ensures that the signals are accurately
represented.
Multiplexing
A common technique for measuring several signals with a single measuring
device is multiplexing.
Signal conditioning devices for analog signals often provide multiplexing for
use with slowly changing signals such as temperature. This is in addition to
any built-in multiplexing on the DAQ board. The A/D converter samples one
channel, switches to the next channel and samples it, switches to the next
channel, and so on. Because the same A/D converter is sampling many
channels, the effective sampling rate of each individual channel is inversely
proportional to the number of channels sampled.
You must take care when using multiplexers so that the switched signal has
sufficient time to settle. Refer to “Noise” on page 1-33 for more information
about settling time.
1-12
The Data Acquisition System
Excitation Source
Some sensors require an excitation source to operate. For example, strain
gauges, and resistive temperature devices (RTDs) require external voltage or
current excitation. Signal conditioning modules for these sensors usually
provide the necessary excitation. RTD measurements are usually made with a
current source that converts the variation in resistance to a measurable
voltage.
The Computer
The computer provides a processor, a system clock, a bus to transfer data, and
memory and disk space to store data.
The processor controls how fast data is accepted by the converter. The system
clock provides time information about the acquired data. Knowing that you
recorded a sensor reading is generally not enough. You also need to know when
that measurement occurred.
Data is transferred from the hardware to system memory via dynamic memory
access (DMA) or interrupts. DMA is hardware controlled and therefore
extremely fast. Interrupts may be slow due to the latency time between when
a board requests interrupt servicing and when the computer responds. The
maximum acquisition rate is also determined by the computer’s bus
architecture. Refer to “How Are Acquired Samples Clocked?” on page 1-23 for
more information about DMA and interrupts.
Software
Regardless of the hardware you are using, you must send information to the
hardware and receive information from the hardware. You send configuration
information to the hardware such as the sampling rate, and receive
information from the hardware such as data, status messages, and error
messages. You may also need to supply the hardware with information so that
you can integrate it with other hardware and with computer resources. This
information exchange is accomplished with software.
1-13
1
Introduction to Data Acquisition
There are two kinds of software:
• Driver software
• Application software
For example, suppose you are using the Data Acquisition Toolbox with a
National Instruments AT-MIO-16E-1 board and its associated NI-DAQ driver.
The relationship between you, the driver software, the application software,
and the hardware is shown below.
User
Application
software
You
Data Acquisition Toolbox and MATLAB
Driver
software
NI-DAQ
Hardware
National Instruments
AT-MIO-16E-1 board
The diagram illustrates that you supply information to the hardware, and you
receive information from the hardware.
1-14
The Data Acquisition System
Driver Software
For data acquisition device, there is associated driver software that you must
use. Driver software allows you to access and control the capabilities of your
hardware. Among other things, basic driver software allows you to:
• Bring data on to and get data off of the board
• Control the rate at which data is acquired
• Integrate the data acquisition hardware with computer resources such as
processor interrupts, DMA, and memory
• Integrate the data acquisition hardware with signal conditioning hardware
• Access multiple subsystems on a given data acquisition board
• Access multiple data acquisition boards
Application Software
Application software provides a convenient “front-end” to the driver software.
Basic application software allows you to:
• Report relevant information such as the number of samples acquired
• Generate events
• Manage the data stored in computer memory
• Condition a signal
• Plot acquired data
With some application software, you can also perform analysis on the data.
MATLAB and the Data Acquisition Toolbox provide you with these capabilities
and more.
1-15
1
Introduction to Data Acquisition
The Analog Input Subsystem
Many data acquisition hardware devices contain one or more subsystems that
convert (digitize) real-world sensor signals into numbers your computer can
read. Such devices are called analog input subsystems (AI subsystems, A/D
converters, or ADCs). After the real-world signal is digitized, you can analyze
it, store it in system memory, or store it to a disk file.
The function of the analog input subsystem is to sample and quantize the
analog signal using one or more channels. You can think of a channel as a path
through which the sensor signal travels. Typical analog input subsystems have
eight or 16 input channels available to you. After data is sampled and
quantized, it must be transferred to system memory.
Analog signals are continuous in time and in amplitude (within predefined
limits). Sampling takes a “snapshot” of the signal at discrete times, while
quantization divides the voltage (or current) value into discrete amplitudes.
Sampling, quantization, channel configuration, and transferring data from
hardware to system memory are discussed below.
Sampling
Sampling takes a “snapshot” of the sensor signal at discrete times. For most
applications, the time interval between samples is kept constant (for example,
sample every millisecond) unless externally clocked.
For most digital converters, sampling is performed by a sample and hold (S/H)
circuit. An S/H circuit usually consists of a signal buffer followed by an
electronic switch connected to a capacitor. The operation of an S/H circuit
follows these steps:
1 At a given sampling instant, the switch connects the buffer and capacitor to
an input.
2 The capacitor is charged to the input voltage.
3 The charge is held until the A/D converter digitizes the signal.
4 For multiple channels connected (multiplexed) to one A/D converter, the
previous steps are repeated for each input channel.
5 The entire process is repeated for the next sampling instant.
1-16
The Analog Input Subsystem
A multiplexer, S/H circuit, and A/D converter are illustrated in the next
section.
Hardware can be divided into two main categories based on how signals are
sampled: scanning hardware, which samples input signals sequentially, and
simultaneous sample and hold (SS/H) hardware, which samples all signals at
the same time. These two types of hardware are discussed below.
Scanning Hardware
Scanning hardware samples a single input signal, converts that signal to a
digital value, and then repeats the process for every input channel used. In
other words, each input channel is sampled sequentially. A scan occurs when
each input in a group is sampled once.
As shown below, most data acquisition devices have one A/D converter that is
multiplexed to multiple input channels.
Signal buffer
Input
channels
Multiplexer
Amplifier
A/D converter
Sample and hold circuit
Therefore, if you use multiple channels, those channels cannot be sampled
simultaneously and a time gap exists between consecutive sampled channels.
This time gap is called the channel skew. You can think of the channel skew as
the time it takes the analog input subsystem to sample a single channel.
1-17
1
Introduction to Data Acquisition
Additionally, the maximum sampling rate your hardware is rated at typically
applies for one channel. Therefore, the maximum sampling rate per channel is
given by the formula
Maximum board rate
Maximum sampling rate per channel = -------------------------------------------------------------------------------Number of channels scanned
Typically, you can achieve this maximum rate only under ideal conditions. In
practice, the sampling rate depends on several characteristics of the analog
input subsystem including the settling time and the gain, as well as the
channel skew. The sample period and channel skew for a multichannel
configuration using scanning hardware is shown below.
Group
scan 2
Channels
Group
scan 1
Group
scan n
...
Sample period
Channel skew
Time
If you cannot tolerate channel skew in your application, you must use
hardware that allows simultaneous sampling of all channels. Simultaneous
sample and hold hardware is discussed in the next section.
1-18
The Analog Input Subsystem
Simultaneous Sample and Hold Hardware
Simultaneous sample and hold (SS/H) hardware samples all input signals at
the same time and holds the values until the A/D converter digitizes all the
signals. For high-end systems, there can be a separate A/D converter for each
input channel.
For example, suppose you need to simultaneously measure the acceleration of
multiple accelerometers to determine the vibration of some device under test.
To do this, you must use SS/H hardware since it does not have a channel skew.
In general, you may need to use SS/H hardware if your sensor signal changes
significantly in a time that is less than the channel skew, or if you need to use
a transfer function or perform a frequency domain correlation.
The sample period for a multichannel configuration using SS/H hardware is
shown below. Note that there is no channel skew.
Group
scan 2
Channels
Group
scan 1
Group
scan n
...
Sample period
Time
1-19
1
Introduction to Data Acquisition
Quantization
As discussed in the previous section, sampling takes a snapshot of the input
signal at an instant of time. When the snapshot is taken, the sampled analog
signal must be converted from a voltage value to a binary number that the
computer can read. The conversion from an infinitely precise amplitude to a
binary number is called quantization.
During quantization, the A/D converter uses a finite number of evenly spaced
values to represent the analog signal. The number of different values is
determined by the number of bits used for the conversion. Most modern
converters use 12 or 16 bits. Typically, the converter selects the digital value
that is closest to the actual sampled value.
The figure below shows a 1 Hz sine wave quantized by a 3-bit A/D converter.
7
6
Amplitude
5
4
3
2
1
0
0
0.1
0.2
0.3
0.4
0.5
Time (sec.)
1-20
0.6
0.7
0.8
0.9
1
The Analog Input Subsystem
The number of quantized values is given by 23 = 8, the largest representable
value is given by 111 = 22 + 21 + 20 = 7.0, and the smallest representable value
is given by 000 = 0.0.
Quantization Error
There is always some error associated with the quantization of a continuous
signal. Ideally, the maximum quantization error is ±0.5 least significant bits
(LSBs), and over the full input range, the average quantization error is zero.
As shown below, the quantization error for the previous sine wave is calculated
by subtracting the actual signal from the quantized signal.
1.5
Quantization error (bits)
1
0.5
0
−0.5
−1
−1.5
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Time (sec.)
1-21
1
Introduction to Data Acquisition
Input Range and Polarity
The input range of the analog input subsystem is the span of input values for
which a conversion is valid. You can change the input range by selecting a
different gain value. For example, National Instruments’ AT-MIO-16E-1 board
has eight gain values ranging from 0.5 to 100. Many boards include a
programmable gain amplifier that allows you to change the device gain
through software.
When an input signal exceeds the valid input range of the converter, an
overrange condition occurs. In this case, most devices saturate to the largest
representable value, and the converted data is almost definitely incorrect. The
gain setting affects the precision of your measurement – the higher (lower) the
gain value, the lower (higher) the precision. Refer to “How Are Range, Gain,
and Measurement Precision Related?” on page 1-32 for more information about
how input range, gain, and precision are related to each other.
An analog input subsystem can typically convert both unipolar signals and
bipolar signals. A unipolar signal contains only positive values and zero, while
a bipolar signal contains positive values, negative values, and zero.
Unipolar and bipolar signals are depicted below. Refer to the figure in
“Quantization” on page 1-20 for an example of a unipolar signal.
10 Volts
5 Volts
0 Volts
-5 Volts
Unipolar
1-22
Bipolar
Unipolar
The Analog Input Subsystem
In many cases, the signal polarity is a fixed characteristic of the sensor and you
must configure the input range to match this polarity.
As you can see, it is crucial to understand the range of signals expected from
your sensor so that you can configure the input range of the analog input
subsystem to maximize resolution and minimize the chance of an overrange
condition.
How Are Acquired Samples Clocked?
Samples are acquired from an analog input subsystem at a specific rate by a
clock. Like any timing system, data acquisition clocks are characterized their
resolution and accuracy. Timing resolution is defined as the smallest time
interval that you can accurately measure. The timing accuracy is affected by
clock jitter. Jitter arises when a clock produces slightly different values for a
given time interval.
For any data acquisition system, there are typically three clock sources that
you can use: the onboard data acquisition clock, the computer clock, or an
external clock. The Data Acquisition Toolbox supports all of these clock
sources, depending on the requirements of your hardware.
The Onboard Clock. The onboard clock is typically a timer chip on the hardware
board that is programmed to generate a pulse stream at the desired rate. The
onboard clock generally has high accuracy and low jitter compared to the
computer clock. You should always use the onboard clock when the sampling
rate is high, and when you require a fixed time interval between samples. The
onboard clock is referred to as the internal clock in this guide.
The Computer Clock. The computer (PC) clock is used for boards that do not
possess an onboard clock. The computer clock is less accurate and has more
jitter than the onboard clock, and is generally limited to sampling rates below
500 Hz. The computer clock is referred to as the software clock in this guide.
External Clock. An external clock is often used when the sampling rate is low and
not constant. For example, an external clock source is often used in automotive
applications where samples are acquired as a function of crank angle.
1-23
1
Introduction to Data Acquisition
Channel Configuration
You can configure input channels in one of these two ways:
• Differential
• Single-ended
Your choice of input channel configuration may depend on whether the input
signal is floating or grounded.
A floating signal uses an isolated ground reference and is not connected to the
building ground. As a result, the input signal and hardware device are not
connected to a common reference, which can cause the input signal to exceed
the valid range of the hardware device. To circumvent this problem, you must
connect the signal to the onboard ground of the device. Examples of floating
signal sources include ungrounded thermocouples and battery devices.
A grounded signal is connected to the building ground. As a result, the input
signal and hardware device are connected to a common reference. Examples of
grounded signal sources include nonisolated instrument outputs and devices
that are connected to the building power system.
Note For more information about channel configuration, refer to your
hardware documentation.
Differential Inputs
When you configure your hardware for differential input, there are two signal
wires associated with each input signal – one for the input signal and one for
the reference (return) signal. The measurement is the difference in voltage
between the two wires, which helps reduce noise and any voltage that is
common to both wires.
As shown below, the input signal is connected to the positive amplifier socket
(labeled +) and the return signal is connected to the negative amplifier socket
1-24
The Analog Input Subsystem
(labeled –). The amplifier has a third connector that allows these signals to be
referenced to ground.
Amplifier
Input signal
Return signal
Vout
National Instruments recommends that you use differential inputs under any
of these conditions:
• The input signal is low level (less than 1 volt).
• The leads connecting the signal are greater than 10 feet.
• The input signal requires a separate ground-reference point or return signal.
• The signal leads travel through a noisy environment.
Single-Ended Inputs
When you configure your hardware for single-ended input, there is one signal
wire associated with each input signal, and each input signal is connected to
the same ground. Single-ended measurements are more susceptible to noise
than differential measurements due to differences in the signal paths.
1-25
1
Introduction to Data Acquisition
As shown below, the input signal is connected to the positive amplifier socket
(labeled +) and the ground is connected to the negative amplifier socket
(labeled –).
Amplifier
Input signal
Ground
Vout
National Instruments suggests that you can use single-ended inputs under any
of these conditions:
• The input signal is high level (greater than 1 volt).
• The leads connecting the signal are less than 10 feet.
• The input signal can share a common reference point with other signals.
You should use differential input connectors for any input signal that does not
meet the preceding conditions. You can configure many National Instruments
boards for two different types of single-ended connections:
• Referenced single-ended (RSE) connection
The RSE configuration is used for floating signal sources. In this case, the
hardware device itself provides the reference ground for the input signal.
• Nonreferenced single-ended (NRSE) connection
The NRSE input configuration is used for grounded signal sources. In this
case, the input signal provides its own reference ground and the hardware
device should not supply one.
Refer to your National Instruments hardware documentation for more
information about RSE and NRSE connections.
1-26
The Analog Input Subsystem
Transferring Data from Hardware to System
Memory
The transfer of acquired data from the hardware to system memory follows
these steps:
1 Acquired data is stored in the hardware’s first-in first-out (FIFO) buffer.
2 Data is transferred from the FIFO buffer to system memory using interrupts
or DMA.
These steps happen automatically. Typically, all that’s required from you is
some initial configuration of the hardware device when it is installed.
The FIFO Buffer
The FIFO buffer is used to temporarily store acquired data. The data is
temporarily stored until it can be transferred to system memory. The process
of transferring data into and out of an analog input FIFO buffer is given below:
1 The FIFO buffer stores newly acquired samples at a constant sampling rate.
2 Before the FIFO buffer is filled, the software starts removing the samples.
For example, an interrupt is generated when the FIFO is half full, and
signals the software to extract the samples as quickly as possible.
3 Since servicing interrupts or programming the DMA controller can take up
to a few milliseconds, additional data is stored in the FIFO for future
retrieval. For a larger FIFO buffer, longer latencies can be tolerated.
4 The samples are transferred to system memory via the system bus (for
example, PCI bus or AT bus). After the samples are transferred, the
software is free to perform other tasks until the next interrupt occurs. For
example, the data can be processed or saved to a disk file. As long as the
average rates of storing and extracting data are equal, acquired data will not
be missed and your application should run smoothly.
Interrupts
The slowest but most common method to move acquired data to system
memory is for the board to generate an interrupt request (IRQ) signal. This
signal can be generated when one sample is acquired or when multiple samples
1-27
1
Introduction to Data Acquisition
are acquired. The process of transferring data to system memory via interrupts
is given below:
1 When data is ready for transfer, the CPU stops whatever it is doing and runs
a special interrupt handler routine that saves the current machine registers,
and then sets them to access the board.
2 The data is extracted from the board and placed into system memory.
3 The saved machine registers are restored, and the CPU returns to the
original interrupted process.
The actual data move is fairly quick, but there is a lot of overhead time spent
saving, setting up, and restoring the register information. Therefore,
depending on your specific system, transferring data by interrupts may not be
a good choice when the sampling rate is greater than around 5 kHz.
DMA
Direct memory access (DMA) is a system whereby samples are automatically
stored in system memory while the processor does something else. The process
of transferring data via DMA is given below:
1 When data is ready for transfer, the board directs the system DMA
controller to put it into in system memory as soon as possible.
2 As soon as the CPU is able (which is usually very quickly), it stops
interacting with the data acquisition hardware and the DMA controller
moves the data directly into memory.
3 The DMA controller gets ready for the next sample by pointing to the next
open memory location.
4 The previous steps are repeated indefinitely, with data going to each open
memory location in a continuously circulating buffer. No interaction
between the CPU and the board is needed.
Your computer supports several different DMA channels. Depending on your
application, you can use one or more of these channels, For example,
simultaneous input and output with a sound card requires one DMA channel
for the input and another DMA channel for the output.
1-28
Making Quality Measurements
Making Quality Measurements
For most data acquisition applications, you need to measure the signal
produced by a sensor at a specific rate.
In many cases, the sensor signal is a voltage level that is proportional to the
physical phenomena of interest (for example, temperature, pressure, or
acceleration). If you are measuring slowly changing (quasi-static) phenomena
like temperature, a slow sampling rate usually suffices. If you are measuring
rapidly changing (dynamic) phenomena like vibration or acoustic
measurements, a fast sampling rate is required.
To make high-quality measurements, you should follow these rules:
• Maximize the precision and accuracy
• Minimize the noise
• Match the sensor range to the A/D range
Accuracy and Precision
Whenever you acquire measured data, you should make every effort to
maximize its accuracy and precision. The quality of your measurement
depends on the accuracy and precision of the entire data acquisition system,
and can be limited by such factors as board resolution or environmental noise.
In general terms, the accuracy of a measurement determines how close the
measurement comes to the true value. Therefore, it indicates the correctness of
the result. The precision of a measurement reflects how exactly the result is
determined without reference to what the result means. The relative precision
indicates the uncertainty in a measurement as a fraction of the result.
For example, suppose you measure a table top with a meter stick and find its
length to be 1.502 meters. This number indicates that the meter stick (and your
eyes) can resolve distances down to at least a millimeter. Under most
circumstances, this is considered to be a fairly precise measurement with a
relative precision of around 1/1500. However, suppose you perform the
measurement again and obtain a result of 1.510 meters. After careful
consideration, you discover that your initial technique for reading the meter
stick was faulty because you did not read it from directly above. Therefore, the
first measurement was not accurate.
1-29
1
Introduction to Data Acquisition
Precision and accuracy are illustrated below.
Not precise
Not accurate
Precise
Not accurate
Not precise
Accurate
Precise
Accurate
For analog input subsystems, accuracy is usually limited by calibration errors
while precision is usually limited by the A/D converter. Accuracy and precision
are discussed in more detail below.
Accuracy
Accuracy is defined as the agreement between a measured quantity and the
true value of that quantity. Every component that appears in the analog signal
path affects system accuracy and performance. The overall system accuracy is
given by the component with the worst accuracy.
1-30
Making Quality Measurements
For data acquisition hardware, accuracy is often expressed as a percent or a
fraction of the least significant bit (LSB). Under ideal circumstances, board
accuracy is typically ±0.5 LSB. Therefore, a 12-bit converter has only 11 usable
bits.
Many boards include a programmable gain amplifier, which is located just
before the converter input. To prevent system accuracy from being degraded,
the accuracy and linearity of the gain must be better than that of the A/D
converter. The specified accuracy of a board is also affected by the sampling
rate and the settling time of the amplifier. The settling time is defined as the
time required for the instrumentation amplifier to settle to a specified
accuracy. To maintain full accuracy, the amplifier output must settle to a level
given by the magnitude of 0.5 LSB before the next conversion, and is on the
order of several tenths of a millisecond for most boards.
Settling time is a function of sampling rate and gain value. High rate, high gain
configurations require longer settling times while low rate, low gain
configurations require shorter settling times.
Precision
The number of bits used to represent an analog signal determines the precision
(resolution) of the device. The more bits provided by your board, the more
precise your measurement will be. A high precision, high resolution device
divides the input range into more divisions thereby allowing a smaller
detectable voltage value. A low precision, low resolution device divides the
input range into fewer divisions thereby increasing the detectable voltage
value.
The overall precision of your data acquisition system is usually determined by
the A/D converter, and is specified by the number of bits used to represent the
analog signal. Most boards use 12 or 16 bits. The precision of your
measurement is given by
Precision = one part in 2(number of bits)
The precision in volts is given by
Precision = voltage range / 2(number of bits)
1-31
1
Introduction to Data Acquisition
For example, if you are using a 12-bit A/D converter configured for a 10 volt
range, then
Precision = 10 volts/ 2(12)
This means that the converter can detect voltage differences at the level of
0.00244 volts (2.44 mV).
How Are Range, Gain, and Measurement Precision Related?
When you configure the input range and gain of your analog input subsystem,
the end result should maximize the measurement resolution and minimize the
chance of an overrange condition. The actual input range is given by the
formula
Actual input range = Input range/Gain
The relationship between gain, actual input range, and precision for a unipolar
and bipolar signal having an input range of 10 V is shown below.
Table 1-2: Relationship Between Input Range, Gain, and Precision
Input Range
Gain
Actual Input Range
Precision (12 Bit A/D)
0 to 10 V
1.0
0 to 10 V
2.44 mV
2.0
0 to 5 V
1.22 mV
5.0
0 to 2 V
0.488 mV
10.0
0 to 1 V
0.244 mV
0.5
-10 to 10 V
4.88 mV
1.0
-5 to 5 V
2.44 mV
2.0
-2.5 to 2.5 V
1.22 mV
5.0
-1.0 to 1.0 V
0.488 mV
10.0
-0.5 to 0.5 V
0.244 mV
-5 to 5 V
1-32
Making Quality Measurements
As shown in the table, the gain affects the precision of your measurement. If
you select a gain that decreases the actual input range, then the precision
increases. Conversely, if you select a gain that increases the actual input range,
then the precision decreases. This is because the actual input range varies but
the number of bits used by the A/D converter remains fixed.
Note With the Data Acquisition Toolbox, you do not have to specify the range
and gain. Instead, you simply specify the actual input range desired.
Noise
Noise is considered to be any measurement that is not part of the phenomena
of interest. Noise can be generated within the electrical components of the
input amplifier (internal noise), or it can be added to the signal as it travels
down the input wires to the amplifier (external noise). Techniques that you can
use to reduce the effects of noise are described below.
Removing Internal Noise
Internal noise arises from thermal effects in the amplifier. Amplifiers typically
generate a few microvolts of internal noise, which limits the resolution of the
signal to this level. The amount of noise added to the signal depends on the
bandwidth of the input amplifier.
To reduce internal noise, you should select an amplifier with a bandwidth that
closely matches the bandwidth of the input signal.
Removing External Noise
External noise arises from many sources. For example, many data acquisition
experiments are subject to 60 Hz noise generated by a.c. power circuits. This
type of noise is referred to as pick-up or hum, and appears as a sinusoidal
interference signal in the measurement circuit. Another common interference
source is fluorescent lighting. These lights generate an arc at twice the power
line frequency (120 Hz).
Noise is added to the acquisition circuit from these external sources because
the signal leads act as aerials picking up environmental electrical activity.
1-33
1
Introduction to Data Acquisition
Much of this noise is common to both signal wires. To remove most of this
common-mode voltage, you should:
• Configure the input channels in differential mode. Refer to “Channel
Configuration” on page 1-24 for more information about channel
configuration.
• Use signal wires that are twisted together rather than separate.
• Keep the signal wires as short as possible.
• Keep the signal wires as far away as possible from environmental electrical
activity.
Filtering
Filtering also reduces signal noise. For many data acquisition applications, a
low-pass filter is beneficial. As the name suggests, a low-pass filter passes the
lower frequency components but attenuates the higher frequency components.
The cut-off frequency of the filter must be compatible with the frequencies
present in the signal of interest and the sampling rate used for the A/D
conversion.
A low-pass filter that’s used to prevent higher frequencies from introducing
distortion into the digitized signal is known as an antialiasing filter if the
cut-off occurs at the Nyquist frequency. That is, the filter removes frequencies
greater than one-half the sampling frequency. These filters generally have a
sharper cut-off than the normal low-pass filter used to condition a signal.
Antialiasing filters are specified according to the sampling rate of the system
and there must be one filter per input signal.
Matching the Sensor Range and A/D Converter
Range
When sensor data is digitized by an A/D converter, you must be aware of these
two issues:
• The expected range of the data produced by your sensor. This range depends
on the physical phenomena you are measuring and the output range of the
sensor.
• The range of your A/D converter. For many devices, the hardware range is
specified by the gain and polarity.
1-34
Making Quality Measurements
You should select the sensor and hardware ranges such that the maximum
precision is obtained, and the full dynamic range of the input signal is covered.
For example, suppose you are using a microphone with a dynamic range of 20
dB to 140 dB and an output sensitivity of 50 mV/Pa. If you are measuring street
noise in your application, then you might expect that the sound level never
exceeds 80 dB, which corresponds to a sound pressure magnitude of 200 mPa
and a voltage output from the microphone of 10 mV. Under these conditions,
you should set the input range of your data acquisition card for a maximum
signal amplitude of 10 mV, or a little more.
How Fast Should a Signal be Sampled?
Whenever a continuous signal is sampled, some information is lost. The key
objective is to sample at a rate such that the signal of interest is well
characterized and the amount of information lost is minimized.
If you sample at a rate that is too slow, then the signal is undersampled, and
aliasing can occur. Aliasing can occur for both rapidly varying signals and
slowly varying signals. For example, suppose you are measuring temperature
once a minute. If your acquisition system is picking up a 60 Hz hum from an
a.c power supply, then that hum will appear as constant noise level if you are
sampling at 30 Hz.
Aliasing occurs when the sampled signal contains frequency components
greater than one-half the sampling rate. The frequency components could
originate from the signal of interest in which case you are undersampling and
should increase the sampling rate. The frequency components could also
originate from noise in which case you may need to condition the signal using
a filter. The rule used to prevent aliasing is given by the Nyquist theorem,
which states that:
• An analog signal can be uniquely reconstructed, without error, from samples
taken at equal time intervals.
• The sampling rate must be equal to or greater than twice the highest
frequency component in the analog signal. A frequency of one-half the
sampling rate is called the Nyquist frequency.
However, if your input signal is corrupted by noise, then aliasing can still
occur.
1-35
1
Introduction to Data Acquisition
For example, suppose you configure your A/D converter to sample at a rate of
4 samples per second (4 S/s or 4 Hz), and the signal of interest is a 1 Hz sine
wave. Since the signal frequency is one-fourth the sampling rate, then
according to the Nyquist theorem, it should be completely characterized.
However, if a 5 Hz sine wave is also present, then these two signals cannot be
distinguished. In other words, the 1 Hz sine wave produces the same samples
as the 5 Hz sine wave when the sampling rate is 4 S/s. This situation is shown
below.
1
0.8
0.6
0.4
Amplitude
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Time (sec.)
Sample period
In a real-world data acquisition environment, you may need to condition the
signal by filtering out the high frequency components.
1-36
Making Quality Measurements
Even though the samples appear to represent a sine wave with a frequency of
one-fourth the sampling rate, the actual signal could be any sine wave with a
frequency of
( n ± 0.25 ) × ( Sampling rate )
where n is zero or any positive integer. For this example, the actual signal may
be at a frequency of 3 Hz, 5 Hz, 7 Hz, 9 Hz, and so on. The relationship
0.25 × ( Sampling rate ) is called the alias of a signal that may be at another
frequency. In other words, aliasing occurs when one frequency assumes the
identity of another frequency.
If you sample the input signal at least twice as fast as the highest frequency
component, then that signal may be uniquely characterized but this rate would
not mimic the waveform very closely. As shown below, to get an accurate
picture of the waveform, you need a sampling rate of roughly 10 to 20 times the
highest frequency.
1
Amplitude
0.5
0
−0.5
−1
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
0.6
0.7
0.8
0.9
1
Time (sec.)
1
Amplitude
0.5
0
−0.5
−1
0
0.1
0.2
0.3
0.4
0.5
Time (sec.)
1-37
1
Introduction to Data Acquisition
As shown in the top figure, the low sampling rate produces a sampled signal
that appears to be a triangular waveform. As shown in the bottom figure, a
higher fidelity sampled signal is produced when the sampling rate is higher. In
the latter case, the sampled signal actually looks like a sine wave.
How Can Aliasing be Eliminated?
The primary considerations involved in antialiasing are the sampling rate of
the A/D converter and the frequencies present in the sampled data. To
eliminate aliasing, you must:
• Establish the useful bandwidth of the measurement.
• Select a sensor with sufficient bandwidth.
• Select a low-pass anti-aliasing analog filter that can eliminate all
frequencies exceeding this bandwidth.
• Sample the data at a rate at least twice that of the filter’s upper cutoff
frequency.
1-38
Selected Bibliography
Selected Bibliography
1 Transducer Interfacing Handbook – A Guide to Analog Signal Conditioning,
edited by Daniel H. Sheingold; Analog Devices Inc., Norwood,
Massachusetts, 1980.
2 Bentley, John P., Principles of Measurement Systems, Second Edition;
Longman Scientific and Technical, Harlow, Essex, UK, 1988.
3 Bevington, Philip R., Data Reduction and Error Analysis for the Physical
Sciences; McGraw-Hill, New York, NY, 1969.
4 Carr, Joseph J., Sensors; Prompt Publications, Indianapolis, Indiana, 1997.
5 The Measurement, Instrumentation, and Sensors Handbook, edited by John
G. Webster; CRC Press, Boca Raton, FL, 1999.
6 PCI-MIO E Series User Manual, January 1997 Edition; Part Number
320945B-01, National Instruments, Austin, TX, 1997.
1-39
1
Introduction to Data Acquisition
1-40
2
Getting Started with the
Data Acquisition Toolbox
Toolbox Components . . .
M-File Functions . . . . . .
The Data Acquisition Engine .
The Hardware Driver Adaptor
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2-2
2-3
2-4
2-7
Accessing Your Hardware . . .
Acquiring Data . . . . . . . .
Outputting Data . . . . . . . .
Reading and Writing Digital Values
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2-8
2-8
2-9
2-10
Understanding the Toolbox Capabilities
The Contents and Readme Files . . . . .
Documentation Examples . . . . . . . .
The Quick Reference Guide . . . . . . .
Demos . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2-12
2-12
2-12
2-13
2-13
Examining Your Hardware Resources
General Toolbox Information . . . . . .
Adaptor-Specific Information . . . . . .
Device Object Information . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2-17
2-17
2-18
2-19
.
.
.
.
Getting Help . . . . . . . . . . . . . . . . . . . . 2-20
The daqhelp Function . . . . . . . . . . . . . . . . . 2-20
The propinfo Function . . . . . . . . . . . . . . . . 2-21
2
Getting Started with the Data Acquisition Toolbox
Toolbox Components
The Data Acquisition Toolbox consists of three distinct components: M-file
functions, the data acquisition engine, and hardware driver adaptors. As
shown below, these components allow you to pass information between
MATLAB and your data acquisition hardware.
MATLAB
Interactive functions and data
Data Acquisition Toolbox
M-file functions
Data acquisition engine
Disk file
Hardware driver adaptors
Property values, data, and events
Hardware driver
Property values, data, and events
Sensors
Hardware
Actuators
2-2
Toolbox Components
The preceding diagram illustrates how information flows from component to
component. Information consists of:
• Property values
You can control the behavior of your data acquisition application by
configuring property values. In general, you can think of a property as a
characteristic of the toolbox or of the hardware driver that can be
manipulated to suit your needs.
• Data
You can acquire data from a sensor connected to an analog input subsystem
and store it in MATLAB, or output data from MATLAB to an actuator
connected to an analog output subsystem. Additionally you can transfer
values (1’s and 0’s) between MATLAB and a digital I/O subsystem.
• Events
An event occurs at a particular time after a condition is met and may result
in one or more actions that you specify. Events can be generated only after
you configure the associated properties. Some of the ways you can use events
include initiating analysis after a predetermined amount of data is acquired,
or displaying a message to the MATLAB workspace after an error occurs.
M-File Functions
To perform any task with your data acquisition application, you must call
M-file functions from the MATLAB environment. Among other things, these
functions allow you to:
• Create device objects, which provide a gateway to your hardware’s
capabilities and allow you to control the behavior of your application.
• Acquire or output data.
• Configure property values.
• Evaluate your acquisition status and hardware resources.
For a listing of all Data Acquisition Toolbox functions, refer to Chapter 9,
“Function Reference.” You can also display all the toolbox functions by typing
help daq
2-3
2
Getting Started with the Data Acquisition Toolbox
The Data Acquisition Engine
The data acquisition engine (or just engine) is a MEX-file dynamic link library
(DLL) file that:
• Stores the device objects and associated property values that control your
data acquisition application
• Controls the synchronization of events
• Controls the storage of acquired or queued data
While the engine performs these tasks, you can use MATLAB for other tasks
such as analyzing acquired data. In other words, the engine and MATLAB are
asynchronous. The relationship between acquiring data, outputting data, and
data flow is described below.
The Flow of Acquired Data
Acquiring data means that data is flowing from your hardware device into the
data acquisition engine where it is temporarily stored in memory. The data is
stored temporarily because it can be overwritten. The rate at which the data is
overwritten depends on several factors including the available memory, the
rate at which data is acquired, and the number of hardware channels from
which data is acquired.
The stored data is not automatically available in the MATLAB workspace.
Instead, you must explicitly extract data from the engine using the getdata
function.
2-4
Toolbox Components
The flow of acquired data consists of these two independent steps:
1 Data acquired from the hardware is stored in the engine.
2 Data is extracted from the engine and stored in MATLAB, or output to a disk
file.
These two steps are illustrated below.
MATLAB
2 Extract data from the engine
Data Acquisition Toolbox
Data acquisition engine
Acquired data
Disk file
1 Fill engine with acquired data
Hardware
Sensors
2-5
2
Getting Started with the Data Acquisition Toolbox
The Flow of Output Data
Outputting data means that data is flowing from the data acquisition engine to
the hardware device. However, before data is output, you must queue it in the
engine with the putdata function. The amount of data that you can queue
depends on several factors including the available memory, the number of
hardware channels to which data is output, and the size of each data sample.
The flow of output data consists of these two independent steps:
1 Data from MATLAB is queued in the engine.
2 Data queued in the engine is output to the hardware.
These two steps are illustrated below.
MATLAB
1 Queue data into the engine
Data Acquisition Toolbox
Data acquisition engine
Queued data
2 Output data to the hardware
Hardware
2-6
Actuators
Toolbox Components
The Hardware Driver Adaptor
The hardware driver adaptor (or just adaptor) is the interface between the data
acquisition engine and the hardware driver. The adaptor’s main purpose is to
pass information between MATLAB and your hardware device via the driver.
Hardware drivers are provided by your device vendor. For example, if you are
acquiring data using a National Instruments E Series board, then the
appropriate version of the NI-DAQ driver must be installed on your platform.
Note that hardware drivers are not installed as part of the Data Acquisition
Toolbox. The supported vendors and the adaptor names used by the toolbox are
listed below.
Table 2-1: Supported Vendors and Adaptor Names
Vendor
Adaptor Name
National Instruments
nidaq
ComputerBoards
cbi
Agilent Technologies
hpe1432
Windows sound cards
winsound
Note You can use the Data Acquisition Toolbox Adaptor Kit to interface
unsupported hardware devices to the toolbox. Refer to the MathWorks Web
site at http://www.mathworks.com/products/daq/ for more information
about the adaptor kit.
As described in “Examining Your Hardware Resources” on page 2-17, you can
list the supported adaptor names with the daqhwinfo function. For a list of
vendor driver requirements and limitations, refer to “Data Acquisition Toolbox
2.0” in the Release Notes.
2-7
2
Getting Started with the Data Acquisition Toolbox
Accessing Your Hardware
Perhaps the most effective way to get started with the Data Acquisition
Toolbox is to connect to your hardware, and input or output data. This section
provides simple examples that show you how to:
• Acquire data from analog input channels
• Output data to analog output channels
• Read values from and write values to digital I/O lines
Each example illustrates a typical data acquisition session. The data
acquisition session comprises all the steps you are likely to take when
acquiring or outputting data using a supported hardware device. You should
keep these steps in mind when constructing your own data acquisition
applications.
Note that the analog input and analog output examples use a sound card, while
the digital I/O example uses a National Instruments PCI-6024E board. If you
are using a different supported hardware device, you should modify the
adaptor name and the device ID supplied to the creation function as needed.
If you want detailed information about any functions that are used, refer to
Chapter 9, “Function Reference.” If you want detailed information about any
properties that are used, refer to Chapter 10, “Base Property Reference.”
Acquiring Data
If you have a sound card installed, you can run the following example, which
acquires one second of data from two analog input hardware channels, and
then plots the acquired data.
You should modify this example to suit your specific application needs. If you
want detailed information about acquiring data, refer to Chapter 5, “Doing
More with Analog Input.”
1. Create a device object – Create the analog input object ai for a sound card.
ai = analoginput('winsound');
2. Add channels – Add two hardware channels to ai.
addchannel(ai,1:2);
2-8
Accessing Your Hardware
3. Configure property values – Configure the sampling rate to 44.1 kHz and
collect 1 second of data (44,100 samples) for each channel.
set(ai,'SampleRate',44100)
set(ai,'SamplesPerTrigger',44100)
4. Acquire data – Start the acquisition. When all the data is acquired, ai
automatically stops executing.
start(ai)
data = getdata(ai);
plot(data)
5. Clean up – When you no longer need ai, you should remove it from memory
and from the MATLAB workspace.
delete(ai)
clear ai
Outputting Data
If you have a sound card installed, you can run the following example, which
outputs 1 second of data to two analog output hardware channels.
You should modify this example to suit your specific application needs. If you
want detailed information about outputting data, refer to Chapter 6, “Analog
Output.”
1. Create a device object – Create the analog output object ao for a sound card.
ao = analogoutput('winsound');
2. Add channels – Add two hardware channels to ao.
addchannel(ao,1:2);
3. Configure property values – Configure the sampling rate to 44.1 kHz for
each channel.
set(ao,'SampleRate',44100)
2-9
2
Getting Started with the Data Acquisition Toolbox
4. Output data – Create 1 second of output data, and queue the data in the
engine for eventual output to the analog output subsystem. You must queue
one column of data for each hardware channel added.
data = sin(linspace(0,2*pi,44100)');
putdata(ao,[data data])
Start the output. When all the data is output, ao automatically stops executing.
start(ao)
Block the MATLAB command line until ao stops running.
while strcmp(ao.Running,'On')
end
5. Clean up – When you no longer need ao, you should remove it from memory
and from the MATLAB workspace.
delete(ao)
clear ao
Reading and Writing Digital Values
If you have a supported National Instruments board with at least eight digital
I/O lines, you can run the following example, which outputs digital values, and
then reads back those values.
You should modify this example to suit your specific application needs. If you
want detailed information about reading and writing digital values, refer to
Chapter 7, “Digital Input/Output.”
1. Create a device object – Create the digital I/O object dio for a National
Instruments PCI-6024E board with hardware ID 1.
dio = digitalio('nidaq',1);
2. Add lines – Add eight hardware lines to dio, and configure them for output.
addline(dio,0:7,'out');
2-10
Accessing Your Hardware
3. Read and write values – Create an array of output values, and write the
values to the digital I/O subsystem. Note that reading and writing digital I/O
line values typically does not require that you configure specific property
values.
pval = [1 1 1 1 0 1 0 1];
putvalue(dio,pval)
gval = getvalue(dio);
4. Clean up – When you no longer need dio, you should remove it from memory
and from the MATLAB workspace.
delete(dio)
clear dio
Note Digital line values are usually not transferred at a specific rate.
Although some specialized boards support clocked I/O, the Data Acquisition
Toolbox does not support this functionality.
2-11
2
Getting Started with the Data Acquisition Toolbox
Understanding the Toolbox Capabilities
In addition to the printed and online documentation, the Data Acquisition
Toolbox provides these resources to help you understand the product
capabilities:
• The Contents and Readme files
• Documentation examples
• The Quick Reference Guide
• Demos
The Contents and Readme Files
The Contents M-file lists the toolbox functions and demos. You can display this
information by typing
help daq
The Readme HTML file contains toolbox modifications and bug fixes. You can
display this information by typing
whatsnew daq
Documentation Examples
This guide provides detailed examples that show you how to acquire or output
data. These examples are collected in the example index, which is available
through the Help browser
Some examples are constructed as mini-applications that illustrate one or two
important features of the toolbox and serve as templates so you can see how to
build applications that suit your specific needs. These examples are included
as toolbox M-files and are treated as demos. You can list all Data Acquisition
Toolbox demos by typing
help daqdemos
All documentation example M-files begin with daqdoc. To run an example, type
the M-file name at the command line. Note that most analog input (AI) and
analog output (AO) examples are written for sound cards. To use these
examples with your hardware device, you should modify the adaptor name and
the device ID supplied to the creation function as needed.
2-12
Understanding the Toolbox Capabilities
Additionally, most documentation examples are written for clocked
subsystems. However, some supported hardware devices – particularly
ComputerBoards devices – do not possess onboard clocks. If the AI or AO
subsystem of your hardware device does not have an onboard clock, then these
examples will not work. To use the documentation examples, you can:
• Input single values using the getsample function, or output single values
using the putsample function.
• Configure the ClockSource property to Software.
The Quick Reference Guide
The Quick Reference Guide gives you a brief but complete overview of the
toolbox capabilities, functions, and properties. You may find it useful to print
this guide and keep it handy when using the toolbox. You can access this guide
through the Help browser.
Demos
The toolbox includes a large collection of demos, which are available through
the daqschool interface. To launch this interface, type daqschool at the
command line.
daqschool
You can also launch individual demos by typing the appropriate M-file name at
the command line. Alternatively, you can launch a toolbox demo through the
MATLAB Demo window by typing
demo toolbox 'Data Acquisition'
The data acquisition demos, organized by device object, are listed below.
Note Most analog input and analog output demos require that you have a
sound card installed. The digital I/O demos require that you have a supported
National Instruments board with digital I/O capabilities.
2-13
2
Getting Started with the Data Acquisition Toolbox
daqschool is shown below.
Common Demos
The common demos illustrate features that are common to all supported device
objects. These demos are listed below.
2-14
Demo Name
Description
demodaq_action
Introduction to action functions.
demodaq_intro
Introduction to the Data Acquisition Toolbox.
demodaq_save
Save and load device objects.
daqtimerplot
Example action function that plots acquired data.
Understanding the Toolbox Capabilities
Analog Input Demos
The analog input demos are listed below.
Demo Name
Description
daqrecord
Record data from the specified adaptor.
daqscope
Example oscilloscope.
demoai_channel
Introduction to analog input channels.
demoai_fft
Fast Fourier transform (FFT) of an incoming signal.
demoai_intro
Introduction to analog input objects.
demoai_logging
Demonstrate logging data to a disk file.
demoai_trig
Demonstrate the use of immediate, manual, and
software triggers.
Analog Output Demos
The analog output demos are listed below.
Demo Name
Description
daqfcngen
Example function generator.
daqplay
Output data to the specified adaptor.
daqsong
Output data from HANDEL.MAT to a sound card.
demoao_channel
Introduction to analog output channels.
demoao_intro
Introduction to analog output objects.
demoao_trig
Demonstrate the use of immediate and manual
triggers.
2-15
2
Getting Started with the Data Acquisition Toolbox
Digital I/O Demos
The digital I/O demos are listed below.
2-16
Demo Name
Description
demodio_intro
Introduction to digital I/O objects.
demodio_line
Introduction to digital I/O lines.
diopanel
Example panel for transferring values between
MATLAB and a digital I/O subsystem.
Examining Your Hardware Resources
Examining Your Hardware Resources
You can examine the data acquisition hardware resources visible to the toolbox
with the daqhwinfo function. Hardware resources include installed boards,
hardware drivers, and adaptors. The information returned by daqhwinfo
depends on the supplied arguments, and is divided into these three categories:
• General toolbox information
• Adaptor-specific information
• Device object information
If you configure hardware parameters using a vendor tool such as National
Instruments’ Measurement and Automation Explorer or ComputerBoards’
InstaCal, then daqhwinfo will return this configuration information. For
example, if you configure your ComputerBoards device for 16 single-ended
channels using InstaCal, then daqhwinfo returns this hardware configuration.
However, the toolbox does not preserve configuration information that is not
directly associated with your hardware. For example, channel name
information is not preserved. Refer to Appendix A, “Troubleshooting Your
Hardware” for more information about using vendor tools.
General Toolbox Information
To display general information about the Data Acquisition Toolbox
out = daqhwinfo
out =
ToolboxName:
ToolboxVersion:
MatlabVersion:
InstalledAdaptors:
'Data Acquisition Toolbox'
[1x39 char]
'6.0.0.74976 (R12)'
{4x1 cell}
The InstalledAdaptors field lists the hardware driver adaptors installed on
your system. To display the installed adaptors
out.InstalledAdaptors
ans =
'cbi'
'hpe1432'
'nidaq'
'winsound'
2-17
2
Getting Started with the Data Acquisition Toolbox
This information tells you that an adaptor is available for ComputerBoards,
Agilent Technologies, National Instruments, and sound card devices.
Note Toolbox adaptors are available to you only if the associated hardware
driver is installed on your platform.
Adaptor-Specific Information
To display hardware information for a particular vendor, you must supply the
adaptor name as an argument to daqhwinfo. The supported vendors and
adaptor names are given in “The Hardware Driver Adaptor” on page 2-7. For
example, to display hardware information for the winsound adaptor
out = daqhwinfo('winsound')
out =
AdaptorDllName: 'd:\v6\toolbox\daq\daq\private\mwwinsound.dll'
AdaptorDllVersion: 'Version 2.0
(R12) 05-Oct-2000'
AdaptorName: 'winsound'
BoardNames: {'AudioPCI Record'}
InstalledBoardIds: {'0'}
ObjectConstructorName:{'analoginput('winsound',0)'[1x26 char]}
The ObjectConstructorName field lists the subsystems supported by the
installed sound cards, and the syntax for creating a device object associated
with a given subsystem. To display the device object constructor names
available for the AudioPCI Record board
out.ObjectConstructorName(:)
ans =
'analoginput('winsound',0)'
'analogoutput('winsound',0)'
This information tells you that the sound card supports analog input and
analog output objects. To create an analog input object for the sound card
ai = analoginput('winsound');
To create an analog output object for the sound card
ao = analogoutput('winsound');
2-18
Examining Your Hardware Resources
Device Object Information
To display hardware information for a specific device object, you must supply
the device object as an argument to daqhwinfo. The hardware information for
the analog input object ai created in the preceding section is given below.
out = daqhwinfo(ai)
out =
AdaptorName:
Bits:
Coupling:
DeviceName:
DifferentialIDs:
Gains:
ID:
InputRanges:
MaxSampleRate:
MinSampleRate:
NativeDataType:
Polarity:
SampleType:
SingleEndedIDs:
SubsystemType:
TotalChannels:
VendorDriverDescription:
VendorDriverVersion:
'winsound'
16
{'AC Coupled'}
'AudioPCI Record'
[]
[]
'0'
[-1 1]
44100
8000
'int16'
{'Bipolar'}
'SimultaneousSample'
[1 2]
'AnalogInput'
2
'Windows Multimedia Driver'
'1.0'
Among other things, this information tells you that the minimum sampling
rate is 8 kHz, the maximum sampling rate is 44.1 kHz, and there are two
hardware channels that you can add to the analog input object.
2-19
2
Getting Started with the Data Acquisition Toolbox
Getting Help
The Data Acquisition Toolbox provides you with these help resources:
• The HTML and PDF versions of this guide, and the Quick Reference Guide,
which are available through the Help browser
• M-file function help, which you can display with the help command (since
some toolbox functions are overloaded, you may need to specify the
appropriate pathname as well)
• The daqhelp function
• The propinfo function
The daqhelp Function
You can use the daqhelp function to:
• Display command line help for functions and properties
• List all the functions and properties associated with a specific device object
A device object need not exist for you to obtain this information. For example,
to display all the functions and properties associated with an analog input
object, as well as the constructor M-file help
daqhelp analoginput
To display help for the SampleRate property
daqhelp SampleRate
You can also display help for an existing device object. For example, to display
help for the BitsPerSample property for an analog input object associated with
a sound card
ai = analoginput('winsound');
out = daqhelp(ai,'BitsPerSample');
2-20
Getting Help
The propinfo Function
You can use the propinfo function to return the characteristics of Data
Acquisition Toolbox properties. For example, you can find the default value for
any property using this function. propinfo returns a structure containing the
fields shown below.
Table 2-2: propinfo Fields
Field Name
Description
Type
The property data type. Possible values are action
function, any, double, and string.
Constraint
The type of constraint on the property value. Possible
values are action function, bounded, enum, and none.
ConstraintValue
The property value constraint. The constraint can be
a range of valid values or a list of valid string values.
DefaultValue
The property default value.
ReadOnly
If the property is read-only, a 1 is returned.
Otherwise, a 0 is returned.
ReadOnlyRunning
If the property is read-only while the device object is
running, a 1 is returned. Otherwise, a 0 is returned.
DeviceSpecific
If the property is device-specific, a 1 is returned. If a 0
is returned, the property is supported for all device
objects of a given type.
2-21
2
Getting Started with the Data Acquisition Toolbox
For example, to return the characteristics for all the properties associated with
the analog input object ai created in the preceding section
AIinfo = propinfo(ai);
The characteristics for the TriggerType property are displayed below.
AIinfo.TriggerType
ans =
Type:
Constraint:
ConstraintValue:
DefaultValue:
ReadOnly:
ReadOnlyRunning:
DeviceSpecific:
'string'
'Enum'
{3x1 cell}
'Immediate'
0
1
0
This information tells you that:
• The property value data type is a string.
• The property value is constrained as an enumerated list of values.
• There are three possible property values.
• The default value is Immediate.
• The property is not read-only.
• You cannot configure the property while the device object is running.
• The property is supported for all analog input objects.
To display the property value constraints
AIinfo.TriggerType.ConstraintValue
ans =
'Manual'
'Immediate'
'Software'
2-22
3
The Data Acquisition
Session
Overview . . . . . . . . . . . . . . . . . . . . . 3-2
Example: The Data Acquisition Session . . . . . . . . . 3-3
Creating a Device Object . . . . . . . . . . . . . . 3-4
Creating an Array of Device Objects . . . . . . . . . . . 3-5
Where Do Device Objects Exist? . . . . . . . . . . . . 3-6
Adding Channels or Lines . . . . . . . . . . . . . . 3-8
Mapping Hardware Channel IDs to MATLAB Indices . . . . 3-9
Configuring and Returning Properties . .
Property Types . . . . . . . . . . . . .
Returning Property Names and Property Values
Configuring Property Values . . . . . . . .
Specifying Property Names . . . . . . . .
Default Property Values . . . . . . . . . .
daqpropedit: A Graphical Property Editor . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 3-12
. 3-12
. 3-14
. 3-18
. 3-19
. 3-19
. 3-20
Acquiring and Outputting Data
Starting the Device Object . . . .
Logging or Sending Data . . . .
Stopping the Device Object . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3-22
3-23
3-23
3-24
Cleaning Up . . . . . . . . . . . . . . . . . . . . 3-25
3
The Data Acquisition Session
Overview
The data acquisition session comprises all the steps you are likely to take when
acquiring or outputting data. These steps are:
1 Create a device object – You create a device object using the analoginput,
analogoutput, or digitalio creation function. Device objects are the basic
toolbox elements you use to access your hardware device.
2 Add channels or lines – After a device object is created, you must add
channels or lines to it. Channels are added to analog input and analog
output objects, while lines are added to digital I/O objects. Channels and
lines are the basic hardware device elements with which you acquire or
output data.
3 Configure properties – To establish the device object behavior, you assign
values to properties using the set function or dot notation.
You can configure many of the properties at any time. However, some
properties are configurable only when the device object is not running.
Conversely, depending on your hardware settings and the requirements of
your application, you may be able to accept the default property values and
skip this step.
4 Acquire or output data – To acquire or output data, you must execute the
device object with the start function. While the device object is running, it
behaves according to the previously configured or default property values.
After data is acquired, you must extract it from the engine with the getdata
function. Before you can output data, you must queue it in the engine with
the putdata function.
5 Clean up – When you no longer need the device object, you should remove it
from memory using the delete function, and remove it from the MATLAB
workspace using the clear command.
The data acquisition session is used in many of the documentation examples
included in this guide. Note that the fourth step is treated differently for digital
I/O objects since they do not store data in the engine. Therefore, only analog
input and analog output objects are discussed in this section.
3-2
Overview
Example: The Data Acquisition Session
This example illustrates the basic steps you take during a data acquisition
session using an analog input object. You can run this example by typing
daqdoc3_1 at the MATLAB command line.
1. Create a device object – Create the analog input object AI for a sound card.
The installed adaptors and hardware IDs are found with daqhwinfo.
AI = analoginput('winsound');
%AI = analoginput('nidaq',1);
%AI = analoginput('cbi',1);
2. Add channels – Add two channels to AI.
addchannel(AI,1:2);
%addchannel(AI,0:1); % For NI and CBI
3. Configure property values – Configure the sampling rate to 11.025 kHz
and define a 2 second acquisition.
set(AI,'SampleRate',11025)
set(AI,'SamplesPerTrigger',22050)
4. Acquire data – Start AI, wait until the requested samples are acquired, and
extract all the data from the engine. Before start is issued, you may want to
begin inputting data from a microphone or a CD player.
start(AI)
while strcmp(AI.Running,'On')
end
data = getdata(AI);
Plot the data and label the figure axes.
plot(data)
xlabel('Samples')
ylabel('Signal (Volts)')
5. Clean up – When you no longer need AI, you should remove it from memory
and from the MATLAB workspace.
delete(AI)
clear AI
3-3
3
The Data Acquisition Session
Creating a Device Object
Device objects are the toolbox components you use to access your hardware
device. They provide a gateway to the functionality of your hardware, and allow
you to control the behavior of your data acquisition application. Each device
object is associated with a specific hardware subsystem.
To create a device object, you call M-file functions called object creation
functions (or object constructors). These M-files are implemented using
MATLAB’s object-oriented programming capabilities, which are described in
“MATLAB Classes and Objects” in the Help browser. The device object creation
functions are listed below.
Table 3-1: Device Object Creation Functions
Function
Description
analoginput
Create an analog input object.
analogoutput
Create an analog output object.
digitalio
Create a digital I/O object.
Before you can create a device object, the associated hardware driver adaptor
must be registered. Adaptor registration occurs automatically. However, if for
some reason an adaptor is not automatically registered, then you must do so
manually with the daqregister function. Refer to “Registering the Hardware
Driver Adaptor” on page A-19 for more information.
You can find out how to create device objects for a particular vendor and
subsystem with the ObjectConstructorName field of the daqhwinfo function.
For example, to find out how to create an analog input object for an installed
National Instruments board, you supply the appropriate adaptor name to
daqhwinfo.
out = daqhwinfo('nidaq');
out.ObjectConstructorName(:)
ans =
'analoginput('nidaq',1)'
'analogoutput('nidaq',1)'
'digitalio('nidaq',1)'
3-4
Creating a Device Object
The constructor syntax tells you that you must supply the adaptor name and
the hardware ID to the analoginput function
ai = analoginput('nidaq',1);
The association between device objects and hardware subsystems is shown
below.
AI
object
AO
object
DIO
object
Toolbox device objects
AI
subsystem
AO
subsystem
DIO
subsystem
Hardware subsystems
Creating an Array of Device Objects
In MATLAB, you can create an array from existing variables by concatenating
those variables together. The same is true for device objects. For example,
suppose you create the analog input object ai and the analog output object ao
for a sound card
ai = analoginput('winsound');
ao = analogoutput('winsound');
You can now create a device object array consisting of ai and ao using the usual
MATLAB syntax. To create the row array x
x = [ai ao]
Index:
1
2
Subsystem:
Analog Input
Analog Output
Name:
winsound0-AI
winsound0-AO
3-5
3
The Data Acquisition Session
To create the column array y
y = [ai;ao];
Note that you cannot create a matrix of device objects. For example, you cannot
create the matrix
z = [ai ao;ai ao];
??? Error using ==> analoginput/vertcat
Only a row or column vector of device objects can be created.
Depending on your application, you may want to pass an array of device objects
to a function. For example, using one call to the set function, you can configure
both ai and ao to the same property value.
set(x,'SampleRate',44100)
Refer to Chapter 9, “Function Reference” to see which functions accept a device
object array as an input argument.
Where Do Device Objects Exist?
When you create a device object, it exists in both the MATLAB workspace and
the data acquisition engine. For example, suppose you create the analog input
object ai for a sound card and then make a copy of ai.
ai = analoginput('winsound');
newai = ai;
The copied device object newai is identical to the original device object ai. You
can verify this by setting a property value for ai and returning the value of the
same property from newai.
set(ai,'SampleRate',22050);
get(newai,'SampleRate')
ans =
22050
3-6
Creating a Device Object
As shown below, ai and newai return the same property value because they
both reference the same device object in the data acquisition engine.
copy
MATLAB
Data Acquisition
Engine
newai
ai
ai
If you delete either the original device object or a copy, then the engine device
object is also deleted. In this case, you cannot use any copies of the device object
that remain in the workspace since they are no longer associated with any
hardware. Device objects that are no longer associated with hardware are
called invalid objects. The example below illustrates this situation.
delete(ai);
newai
newai =
Invalid Data Acquisition object.
This object is not associated with any hardware and
should be removed from your workspace using CLEAR.
You should remove invalid device objects from the workspace with the clear
command.
3-7
3
The Data Acquisition Session
Adding Channels or Lines
Channels and lines are the basic hardware device elements with which you
acquire or output data
After you create a device object, you must add channels or lines to it. Channels
are added to analog input and analog output objects, while lines are added to
digital I/O objects. The channels added to a device object constitute a channel
group, while the lines added to a device object constitute a line group.
The functions associated with adding channels or lines to a device object are
listed below.
Table 3-2: Functions Associated with Adding Channels or Lines
Functions
Description
addchannel
Add hardware channels to an analog input or analog
output object.
addline
Add hardware lines to a digital I/O object.
addmuxchannel
Add channels when using a National Instruments
AMUX-64T multiplexer.
For example, to add two channels to an analog input object associated with a
sound card, you must supply the appropriate hardware channel identifiers
(IDs) to addchannel.
ai = analoginput('winsound');
addchannel(ai,1:2)
Note You cannot acquire or output data with a device object that does not
contain channels or lines. Similarly, you cannot acquire or output data with
channels or lines that are not contained by a device object.
You can think of a device object as a channel or line container that reflects the
common functionality of a particular device. The common functionality of a
device applies to all channels or lines that it contains. For example, the
sampling rate of an analog input object applies to all channels contained by
3-8
Adding Channels or Lines
that object. In contrast, the channels and lines contained by the device object
reflect the functionality of a particular channel or line. For example, you can
configure the input range (gain and polarity) on a per-channel basis.
The relationship between an analog input object and the channels it contains
is shown below.
Analog Input Object
Container (device object)
Channel 1
Channel 2
Channel 3
Channel group (hardware channels)
.
.
.
Channel n
For digital I/O objects, the diagram would look the same except that lines
would be substituted for channels.
Mapping Hardware Channel IDs to MATLAB Indices
When you add channels to a device object, the resulting channel group consists
of a mapping between hardware channel IDs and MATLAB indices.
Hardware channel IDs are numeric values defined by the hardware vendor
that uniquely identify a channel. For National Instruments and
ComputerBoards hardware, the channel IDs are “zero-based” (begin at zero).
For Agilent Technologies hardware and sound cards, the channel IDs are
“one-based” (begin at one). However, when you reference channels, you use the
MATLAB indices and not the hardware IDs. Given this, you should keep in
mind that MATLAB is one-based. You can return the vendor’s hardware IDs
with the daqhwinfo function.
3-9
3
The Data Acquisition Session
For example, suppose you create the analog input object ai for a National
Instruments board and you want to add the first three differential channels.
ai = analoginput('nidaq',1);
To return the hardware IDs, supply the device object to daqhwinfo, and
examine the DifferentialIDs field.
out = daqhwinfo(ai)
out.DifferentialIDs
ans =
0
1
2
3
4
5
6
7
The first three differential channels have IDs 0, 1, and 2, respectively.
addchannel(ai,0:2);
The index assigned to a hardware channel depends on the order in which you
add it to the device object. In the above example, the channels are
automatically assigned the MATLAB indices 1, 2, and 3, respectively. You can
change the hardware channels associated with the MATLAB indices using the
HwChannel property. For example, to swap the order of the second and third
hardware channels
ai.Channel(2).HwChannel = 2;
ai.Channel(3).HwChannel = 1;
3-10
Adding Channels or Lines
The original and modified index assignments are shown below.
Hardware channel ID
Original index
assignment
Modified index
assignment
MATLAB index
0
1
1
2
2
3
0
1
1
2
2
3
Note If you are using scanning hardware, then the MATLAB indices define
the scan order; index 1 is sampled first, index 2 is sampled second, and so on.
For digital I/O objects, the diagram would look the same except that lines
would be substituted for channels.
3-11
3
The Data Acquisition Session
Configuring and Returning Properties
You define and evaluate the behavior of your data acquisition application with
device object properties. You define your application behavior by assigning
values to properties with the set function or the dot notation. You evaluate
your application configuration and status by displaying property values with
the get function or the dot notation.
Property Types
Data Acquisition Toolbox properties are divided into two main types:
• Common properties – Common properties apply to every channel or line
contained by a device object.
• Channel/Line properties – Channel/line properties are configured for
individual channels or lines.
The relationship between an analog input object, the channels it contains, and
their properties is shown below.
Analog Input Object
Common properties apply to
all channels
Channel 1
Channel 2
Channel 3
.
.
.
Channel properties are set on a
per-channel basis
Channel n
For digital I/O objects, the diagram would look the same except that lines
would be substituted for channels.
3-12
Configuring and Returning Properties
Common properties and channel/line properties are subdivided into these two
categories:
• Base properties – Base properties apply to all supported hardware
subsystems of a given type, such as analog input. For example, the
SampleRate property is supported for all analog input subsystems regardless
of the vendor.
• Device-specific properties – Device-specific properties apply only to
specific hardware devices. For example, the BitsPerSample property is
supported only for sound cards. Note that base properties can have
device-specific values. For example, the InputType property has a different
set of values for each supported hardware vendor.
The relationship between common properties, channel/line properties, base
properties, and device-specific properties is shown below.
Device
object
Base
properties
Common properties
Device-specific
properties
Hardware
channels/lines
Base
properties
Device-specific
properties
Channel/line
properties
For a complete description of all properties, refer to Chapter 10, “Base Property
Reference” or Chapter 11, “Device-Specific Property Reference.”
3-13
3
The Data Acquisition Session
Returning Property Names and Property Values
Once the device object is created, you can use the set function to return all
configurable properties to a variable or to the command line. Additionally, if a
property has a finite set of string values, then set also returns these values.
You can use the get function to return one or more properties and their current
values to a variable or to the command line.
The syntax used to return common and channel/line properties is described
below. The examples are based on the analog input object ai created for a
sound card and containing two channels.
ai = analoginput('winsound');
addchannel(ai,1:2);
Common Properties
To return all configurable common property names and their possible values
for a device object, you must supply the device object to set. For example, all
configurable common properties for ai are shown below. The base properties
are listed first, followed by the device-specific properties.
set(ai)
BufferingConfig
BufferingMode: [ {Auto} | Manual ]
Channel
ChannelSkew
ChannelSkewMode: [ {None} ]
ClockSource: [ {Internal} ]
DataMissedAction
InputOverRangeAction
InputType: [ {AC-Coupled} ]
LogFileName
LoggingMode: [ Disk | {Memory} | Disk&Memory ]
LogToDiskMode: [ {Overwrite} | Index ]
ManualTriggerHwOn: [ {Start} | Trigger ]
Name
RuntimeErrorAction
SampleRate
SamplesAcquiredAction
SamplesAcquiredActionCount
SamplesPerTrigger
3-14
Configuring and Returning Properties
StartAction
StopAction
Tag
Timeout
TimerAction
TimerPeriod
TriggerAction
TriggerChannel
TriggerCondition: [ {None} ]
TriggerConditionValue
TriggerDelay
TriggerDelayUnits: [ {Seconds} | Samples ]
TriggerRepeat
TriggerType: [ Manual | {Immediate} | Software ]
UserData
WINSOUND specific properties:
BitsPerSample
StandardSampleRates: [ Off | {On} ]
To return all common properties and their current values for a device object,
you must supply the device object to get. For example, all common properties
for ai are shown below. The base properties are listed first, followed by the
device-specific properties.
get(ai)
BufferingConfig = [512 30]
BufferingMode = Auto
Channel = [2x1 aichannel]
ChannelSkew = 0
ChannelSkewMode = None
ClockSource = Internal
DataMissedAction = daqaction
EventLog = []
InitialTriggerTime = [0 0 0 0 0 0]
InputOverRangeAction =
InputType = AC-Coupled
LogFileName = logfile.daq
Logging = Off
LoggingMode = Memory
LogToDiskMode = Overwrite
3-15
3
The Data Acquisition Session
ManualTriggerHwOn = Start
Name = winsound0-AI
Running = Off
RuntimeErrorAction = daqaction
SampleRate = 8000
SamplesAcquired = 0
SamplesAcquiredAction =
SamplesAcquiredActionCount = 1024
SamplesAvailable = 0
SamplesPerTrigger = 8000
StartAction =
StopAction =
Tag =
Timeout = 1
TimerAction =
TimerPeriod = 0.1
TriggerAction =
TriggerChannel = [1x0 aichannel]
TriggerCondition = None
TriggerConditionValue = 0
TriggerDelay = 0
TriggerDelayUnits = Seconds
TriggerRepeat = 0
TriggersExecuted = 0
TriggerType = Immediate
Type = Analog Input
UserData = []
WINSOUND specific properties:
BitsPerSample = 16
StandardSampleRates = On
To display the current value for one property, you supply the property name to
get.
get(ai,'SampleRate')
ans =
8000
To display the current values for multiple properties, you include the property
names as elements of a cell array.
3-16
Configuring and Returning Properties
get(ai,{'StandardSampleRates','Running'})
ans =
'On'
'Off'
You can also use the dot notation to display a single property value.
ai.TriggerType
ans =
Immediate
Channel and Line Properties
To return all configurable channel (line) property names and their possible
values for a single channel (line) contained by a device object, you must use the
Channel (Line) property. For example, to display the configurable channel
properties for the first channel contained by ai
set(ai.Channel(1))
ChannelName
HwChannel
InputRange
SensorRange
Units
UnitsRange
All channel properties and their current values for the first channel contained
by ai are shown below.
get(ai.Channel(1))
ChannelName = Left
HwChannel = 1
Index = 1
InputRange = [-1 1]
NativeOffset = 1.5259e-005
NativeScaling = 3.0518e-005
Parent = [1x1 analoginput]
SensorRange = [-1 1]
Type = Channel
Units = Volts
UnitsRange = [-1 1]
As described in the preceding section, you can also return values for a specified
number of channel properties with the get function or the dot notation.
3-17
3
The Data Acquisition Session
Configuring Property Values
You configure property values with the set function or the dot notation. In
practice, you can configure many of the properties at any time while the device
object exists. However, some properties are not configurable while the object is
running. Use the propinfo function, or refer to Chapter 10, “Base Property
Reference” for information about when a property is configurable.
The syntax used to configure common and channel/line properties is described
below. The examples are based on the analog input object ai created in
“Returning Property Names and Property Values” on page 3-14.
Common Properties
You can configure a single property value using the set function
set(ai,'TriggerType','Manual')
or the dot notation
ai.TriggerType = 'Manual';
To configure values for multiple properties, you can supply multiple property
name/property value pairs to set.
set(ai,'SampleRate',44100,'Name','Test1-winsound')
Note that you can configure only one property value at a time using the dot
notation.
Channel and Line Properties
To configure channel (line) properties for one or more channels (lines)
contained by a device object, you must use the Channel (Line) property. For
example, to configure the SensorRange property for the first channel contained
by ai, you can use the set function
set(ai.Channel(1),'SensorRange',[-2 2])
or the dot notation
ai.Channel(1).SensorRange = [-2 2];
3-18
Configuring and Returning Properties
To configure values for multiple channel or line properties, you supply multiple
property name/property value pairs to set.
set(ai.Channel(1),'SensorRange',[-2 2],'ChannelName','Chan1')
To configure multiple property values for multiple channels
chs = ai.Channel(1:2);
set(chs,{'SensorRange','ChannelName'},{[-2 2],'Chan1';[0 4],
'Chan2'});
Specifying Property Names
Device object property names are presented in this guide using mixed case.
While this makes the names easier to read, you can use any case you want
when specifying property names. Additionally, you need use only enough
letters to identify the property name uniquely, so you can abbreviate most
property names. For example, you can configure the SampleRate property any
of these ways.
set(ai,'SampleRate',44100);
set(ai,'samplerate',44100);
set(ai,'sampler',44100);
However, when you include property names in an M-file, you should use the
full property name. This practice can prevent problems with future releases of
the Data Acquisition Toolbox if a shortened name is no longer unique because
of the addition of new properties.
Default Property Values
If you do not explicitly define a value for a property, then the default value is
used. All configurable properties have default values. However, the default
value for a given property may vary based on the hardware you are using.
Additionally, some default values are calculated by the engine and depend on
the values set for other properties. If the hardware driver adaptor specifies a
default value for a property, then that value takes precedence over the value
defined by the toolbox.
3-19
3
The Data Acquisition Session
If a property has a finite set of string values, then the default value is enclosed
by {} (curly braces). For example, the default value for the LoggingMode
property is Memory.
set(ai,'LoggingMode')
[ Disk | {Memory} | Disk&Memory ]
You can also use the propinfo function, or refer to Chapter 10, “Base Property
Reference” or Chapter 11, “Device-Specific Property Reference” to find the
default value for any property.
daqpropedit: A Graphical Property Editor
The toolbox provides the Data Acquisition Property Editor, which is a graphical
user interface (GUI) for accessing properties. You launch the property editor
with the daqpropedit function. The GUI is designed so that you can:
• List all existing device objects as well as the channels or lines they contain.
• Configure property values.
• Display the names and current values for configurable properties.
• Display property characteristics.
• Display property help.
For example, to configure property values for the analog input object ai using
daqpropedit
ai = analoginput('winsound');
addchannel(ai,1:2);
daqpropedit(ai)
3-20
Configuring and Returning Properties
The Data Acquisition Property Editor is shown below.
List of device objects, channels,
and lines
Property to configure and its
current value
List of configurable properties
and their current values
Property characteristics
Property help
3-21
3
The Data Acquisition Session
Acquiring and Outputting Data
After you configure the device object, you can acquire or output data. Acquiring
and outputting data involves these three steps:
1 Starting the device object
2 Logging data or sending data
3 Stopping the device object
As data is being transferred between MATLAB 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:
• 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, since they do
not store data in the engine, the logging and sending states do not exist.
3-22
Acquiring and Outputting Data
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);
Since 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” on page 5-20 or “Configuring Analog Output Triggers” on
page 6-21.
3-23
3
The Data Acquisition Session
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 line 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,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 timeout 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.
3-24
Cleaning Up
Cleaning Up
When you no longer need a device object, you should clean up the MATLAB
environment by removing the object from memory (the engine) and from the
workspace. These are the steps you take to end a data acquisition session.
You remove device objects from memory with the delete function. For
example, to delete the analog input object ai created in the preceding section
delete(ai)
A deleted device object is invalid, which means that you cannot connect it to the
hardware. In this case, you should remove the object from the MATLAB
workspace. To remove device objects and other variables from the MATLAB
workspace, use the clear command.
clear ai
If you use clear on a device object that is connected to hardware, the object is
removed from the workspace but remains connected to the hardware. You can
restore cleared device objects to MATLAB with the daqfind function.
3-25
3
The Data Acquisition Session
3-26
4
Getting Started with
Analog Input
Overview
. . . . . . . . . . . . . . . . . . . . . 4-2
Creating an Analog Input Object . . . . . . . . . . . 4-3
Adding Channels to an Analog Input Object . . . . . 4-4
Referencing Individual Hardware Channels . . . . . . . . 4-6
Example: Adding Channels for a Sound Card . . . . . . . 4-7
Configuring Analog Input Properties
The Sampling Rate . . . . . . . . . .
Trigger Types . . . . . . . . . . . .
The Samples to Acquire per Trigger . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Acquiring Data . . . . . . .
Starting the Analog Input Object
Logging Data . . . . . . . .
Stopping the Analog Input Object
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 4-13
. 4-13
. 4-14
. 4-14
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4-9
4-9
4-11
4-12
Analog Input Examples . . . . . . . . . . . . . . . 4-15
Acquiring Data with a Sound Card . . . . . . . . . . . 4-15
Acquiring Data with a National Instruments Board . . . . 4-19
Evaluating the Analog Input Object Status . . . . . . 4-22
Status Properties . . . . . . . . . . . . . . . . . . 4-22
The Display Summary . . . . . . . . . . . . . . . . 4-23
4
Getting Started with Analog Input
Overview
Analog input (AI) subsystems convert real-world analog input signals from a
sensor into bits that can be read by your computer. Perhaps the most important
of all the subsystems commonly available, AI subsystems are typically
multi-channel devices offering 12 or 16 bits of resolution. The Data Acquisition
Toolbox provides access to analog input devices through an analog input object.
The purpose of this chapter is to show you how to perform simple analog input
tasks using just a few functions and properties. After reading this chapter, you
should be able to use the Data Acquisition Toolbox to configure your own
analog input session. Topics include:
• Creating an analog input object
• Adding channels to an analog input object
• Configuring analog input properties
• Acquiring data
• Analog input examples
• Evaluating the analog input object status
4-2
Creating an Analog Input Object
Creating an Analog Input Object
You create an analog input object with the analoginput function. analoginput
accepts the adaptor name and the hardware device ID as input arguments. For
a list of supported adaptors, refer to “The Hardware Driver Adaptor” on
page 2-7. The device ID refers to the number associated with your board when
it is installed. 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 input object is associated with one board and one analog input
subsystem. For example, to create an analog input object associated with a
National Instruments board with device ID 1
ai = analoginput('nidaq',1);
The analog input object ai now exists in the MATLAB workspace. You can
display the class of ai with the whos command.
whos ai
Name
ai
Size
Bytes
1x1
1332
Class
analoginput object
Grand total is 52 elements using 1332 bytes
Once the analog input 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 4-1: Descriptive Analog Input 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 ai with the get function.
get(ai,{'Name','Type'})
ans =
'nidaq1-AI'
'Analog Input'
4-3
4
Getting Started with Analog Input
Adding Channels to an Analog Input Object
After creating the analog input object, you must add hardware channels to it.
As shown by the figure in “Adding Channels or Lines” on page 3-8, 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 MATLAB Indices” on page 3-9, a channel
group consists of a mapping between hardware channel IDs and MATLAB
indices (see below).
When adding channels to an analog input 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 input 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 ai created in the preceding section
chans = addchannel(ai,0:1);
The output argument chans is a channel object that reflects the channel array
contained by ai. You can display the class of chans with the whos command.
whos chans
Name
chans
Size
2x1
Bytes
512
Class
aichannel 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” on page 4-6, you can also access
channels with the Channel property.
4-4
Adding Channels to an Analog Input Object
Once you add channels to an analog input 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 4-2: Descriptive Analog Input 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 analoginput]
'Channel'
[1]
[2]
[1x1 analoginput]
'Channel'
If you are using scanning hardware, then the MATLAB indices define the scan
order; index 1 is sampled first, index 2 is sampled second, and so on.
Note The number of channels you can add to a device object depends on the
specific board you are using. Some boards support adding channels in any
order and adding the same channel multiple times, while other boards do not.
Additionally, each channel may have its own input range, which is verified
with each acquired sample. The collection of channels you add to a device
object is sometimes referred to as a channel gain list or a channel gain queue.
For scanning hardware, these channels define the scan order.
4-5
4
Getting Started with Analog Input
Referencing Individual Hardware Channels
As described in the preceding section, you can access channels with the
Channel property or with a channel object. To reference individual channels,
you must specify either MATLAB indices or descriptive channel names.
MATLAB Indices
Every hardware channel contained by an analog input object has an associated
MATLAB index that is used to reference the channel. When adding channels
with the addchannel function, index assignments can be made automatically
or manually. In either case, the channel indices start at 1 and increase
monotonically up to the number of channel group members.
For example, the analog input object ai created in the preceding section had
the MATLAB indices 1 and 2 automatically assigned to the hardware channels
0 and 1, respectively. To manually swap the hardware channel order, you
supply the appropriate index to chans and use the HwChannel property.
chans(1).HwChannel = 1;
chans(2).HwChannel = 0;
Alternatively, you can use the Channel property.
ai.Channel(1).HwChannel = 1;
ai.Channel(2).HwChannel = 0;
Note that you can also use addchannel to specify the required channel order.
chans = addchannel(ai,[1 0]);
Descriptive Channel Names
Choosing a unique, descriptive name can be a useful way to identify and
reference channels – particularly for large channel groups. You can associate
descriptive names with hardware channels using the addchannel function. For
example, suppose you want to add 16 single-ended channels to ai, and you
want to associate the name TrigChan with the first channel in the group.
ai.InputType = 'SingleEnded';
addchannel(ai,0,'TrigChan');
addchannel(ai,1:15);
4-6
Adding Channels to an Analog Input Object
Alternatively, you can use the ChannelName property.
ai.InputType = 'SingleEnded';
addchannel(ai,0:15);
ai.Channel(1).ChannelName = 'TrigChan';
You can now use the channel name to reference the channel.
ai.TrigChan.InputRange = [-10 10];
Example: Adding Channels for a Sound Card
Suppose you create the analog input object ai for a sound card.
ai = analoginput('winsound');
Most sound cards have just two hardware channels that you can add. If one
channel is added, the sound card is said to be in mono mode. If two channels
are added, the sound card is said to be in stereo mode. However, the rules for
adding these two channels differ from those of other data acquisition devices.
These rules are described below.
Mono Mode
If you add one channel to ai, the sound card is said to be in mono mode and the
channel added must have a hardware ID of 1.
addchannel(ai,1);
At the software level, mono mode means that data is acquired from channel 1.
At the hardware level, you generally cannot determine the actual channel
configuration and data can be acquired from channel 1, channel 2, or both
depending on your sound card. Channel 1 is automatically assigned the
descriptive channel name Mono.
ai.Channel.ChannelName
ans =
Mono
4-7
4
Getting Started with Analog Input
Stereo Mode
If you add two channels to ai, the sound card is said to be in stereo mode. You
can add two channels using two calls to addchannel provided channel 1 is
added first.
addchannel(ai,1);
addchannel(ai,2);
Alternatively, you can use one call to addchannel provided channel 1 is
specified as the first element of the hardware ID vector.
addchannel(ai,1:2);
Stereo mode means that data is acquired from both hardware channels.
Channel 1 is automatically assigned the descriptive name Left and channel 2
is automatically assigned the descriptive name Right.
ai.Channel.ChannelName
ans =
'Left'
'Right'
While in stereo mode, if you want to delete one channel, then that channel must
be channel 2. If you try to delete channel 1, an error is returned.
delete(ai.Channel(2))
The sound card is now in mono mode.
4-8
Configuring Analog Input Properties
Configuring Analog Input Properties
After hardware channels are added to the analog input object, you should
configure property values. As described in “Configuring and Returning
Properties” on page 3-12, the Data Acquisition Toolbox supports two basic
types of properties for analog input 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 input
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, define the trigger type, and define
the samples to be acquired per trigger. Analog input properties related to the
basic setup are given below.
Table 4-3: Analog Input Basic Setup Properties
Property Name
Description
SampleRate
Specify the per-channel rate at which analog data
is converted to digital data.
SamplesPerTrigger
Specify the number of samples to acquire for each
channel group member for each trigger that occurs.
TriggerType
Specify the type of trigger to execute.
The Sampling Rate
You control the rate at which an analog input subsystem converts analog data
to digital data 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)
ai = analoginput('nidaq',1);
addchannel(ai,0:1);
set(ai,'SampleRate',100000)
4-9
4
Getting Started with Analog Input
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 in Chapter 10, “Base Property
Reference.”
• 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
Chapter 11, “Device-Specific Property Reference” for more information.
For hardware that supports simultaneous sampling of channels (sound cards
and Agilent Technologies devices), the maximum sampling rate for each
channel is given by the maximum board rate. For scanning hardware (most
National Instruments and ComputerBoards devices), the per-channel
sampling rate is given by the maximum hardware rate divided by the number
of channels contained by the device object.
After setting a value for SampleRate, you should find out the actual rate set by
the engine.
ActualRate = get(ai,'SampleRate');
Alternatively, you can use the setverify function, which sets a property value
and returns the actual value set.
ActualRate = setverify(ai,'SampleRate',100000);
You can find the range of valid sampling rates for your hardware with the
propinfo function.
ValidRates = propinfo(ai,'SampleRate');
ValidRates.ConstraintValue
ans =
1.0e+005 *
0.0000
2.0000
4-10
Configuring Analog Input Properties
Trigger Types
For analog input objects, a trigger is defined as an event that initiates data
logging to memory or to a disk file. Defining an analog input trigger involves
specifying the trigger type with the TriggerType property. The TriggerType
values that are supported for all hardware are given below.
Table 4-4: Analog Input TriggerType Property Values
TriggerType Value
Description
{Immediate}
The trigger occurs just after the start function is
issued.
Manual
The trigger occurs just after you manually issue the
trigger function.
Software
The trigger occurs when the associated trigger
condition is satisfied. Trigger conditions are given
by the TriggerCondition property.
Many devices have additional hardware trigger types, which are available to
you through the TriggerType property. For example, to return all the trigger
types for the analog input object ai created in the preceding section
set(ai,'TriggerType')
[ Manual | {Immediate} | Software | 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” on page 5-37, or the TriggerType
reference pages in Chapter 10, “Base Property Reference.”
Note Triggering can be a complicated issue and it has many associated
properties. For detailed information about triggering, refer to “Configuring
Analog Input Triggers” on page 5-20.
4-11
4
Getting Started with Analog Input
The Samples to Acquire per Trigger
When a trigger executes, a predefined number of samples are acquired for each
channel group member and logged to the engine or a disk file. You specify the
number of samples to acquire per trigger with the SamplesPerTrigger
property.
The default value of SamplesPerTrigger is calculated by the engine such that
1 second of data is collected, and is based on the default value of SampleRate.
In general, to calculate the acquisition time for each trigger, you apply the
formula
acquisition time (seconds) = samples per trigger / sampling rate (in Hz)
For example, to acquire 5 seconds of data per trigger for each channel
contained by ai
set(ai,'SamplesPerTrigger',500000)
To continually acquire data, you set SamplesPerTrigger to inf.
set(ai,'SamplesPerTrigger',inf)
A continuous acquisition will stop only if you issue the stop function, or an
error occurs.
4-12
Acquiring Data
Acquiring Data
After you configure the analog input object, you can acquire data. Acquiring
data involves these three steps:
1 Starting the analog input object
2 Logging data
3 Stopping the analog input object
Starting the Analog Input Object
You start an analog input 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);
Since 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. However, you cannot use peekdata in
conjunction with hardware triggers since the device is idle until the hardware
trigger is received.
4-13
4
Getting Started with Analog Input
Logging Data
While the analog input object is running, you can log acquired data to the
engine (memory) or to a disk file. However, before you can log data a trigger
must occur. You configure an analog input trigger with the TriggerType
property. For a detailed description of triggers, refer to “Configuring Analog
Input Triggers” on page 5-20.
When the trigger occurs, 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 all logged samples for each channel contained by ai
data = getdata(ai);
getdata blocks the MATLAB command line until all the requested data is
returned to the workspace. You can extract data any time after the trigger
occurs. You can also return sample-time pairs with getdata. For example, to
extract 500 sample-time pairs for each channel contained by ai
[data,time] = getdata(ai,500);
time is an m-by-1 array containing relative time values for all m samples. Time
is measured relative to the time the first sample is logged, and is measured
continuously until the acquisition stops. getdata is described in more detail in
Chapter 9, “Function Reference.”
You can log data to disk with the LoggingMode property. You can replay data
saved to disk with the daqread function. Refer to “Logging Information to Disk”
on page 8-6 for more information about LoggingMode and daqread.
Stopping the Analog Input Object
An analog input object can stop under one of these conditions:
• You issue the stop function.
• The requested number of samples is acquired.
• A run-time hardware error occurs.
• A timeout occurs.
When the device object stops, the Running and Logging 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.
4-14
Analog Input Examples
Analog Input Examples
This section illustrates how to perform basic data acquisition tasks using
analog input subsystems and the Data Acquisition Toolbox. For most data
acquisition applications, you must follow these basic steps:
1 Install and connect the components of your data acquisition hardware. At a
minimum, this involves connecting a sensor 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 acquire data.
3 Analyze the acquired data using MATLAB.
Simple data acquisition applications using a sound card and a National
Instruments board are given below.
Acquiring Data with a Sound Card
Suppose you must verify that the fundamental (lowest) frequency of a tuning
fork is 440 Hz. To perform this task, you will use a microphone and a sound
card to collect sound level data. You will then perform a fast Fourier transform
(FFT) on the acquired data to find the frequency components of the tuning fork.
The setup for this task is shown below.
Data Source
Sensor
Sound Card
Data Sink
Figure
A/D
MATLAB
workspace
4-15
4
Getting Started with Analog Input
Configuring the Data Acquisition Session
For this example, you will acquire 1 second of sound level data on one sound
card channel. Since the tuning fork vibrates at a nominal frequency of 440 Hz,
you can configure the sound card to its lowest sampling rate of 8000 Hz. Even
at this lowest rate, you should not experience any aliasing effects since the
tuning fork will not have significant spectral content above 4000 Hz, which is
the Nyquist frequency. After you set the tuning fork vibrating and place it near
the microphone, you will trigger the acquisition one time using a manual
trigger.
You can run this example by typing daqdoc4_1 at the MATLAB command line.
1. Create a device object – Create the analog input object AI for a sound card.
The installed adaptors and hardware IDs are found with daqhwinfo.
AI = analoginput('winsound');
2. Add channels – Add one channel to AI.
chan = addchannel(AI,1);
3. Configure property values – Assign values to the basic setup properties,
and create the variables blocksize and Fs, which are used for subsequent
analysis. The actual sampling rate is retrieved since it may be set by the engine
to a value that differs from the specified value.
duration = 1; %1 second acquisition
set(AI,'SampleRate',8000)
ActualRate = get(AI,'SampleRate');
set(AI,'SamplesPerTrigger',duration*ActualRate)
set(AI,'TriggerType','Manual')
blocksize = get(AI,'SamplesPerTrigger');
Fs = ActualRate;
4. Acquire data – Start AI, issue a manual trigger, and extract all data from
the engine. Before start is issued, you should begin inputting data from the
tuning fork into the sound card.
start(AI)
trigger(AI)
data = getdata(AI);
4-16
Analog Input Examples
5. Clean up – When you no longer need AI, you should remove it from memory
and from the MATLAB workspace.
delete(AI)
clear AI
Analyzing the Data
For this example, analysis consists of finding the frequency components of the
tuning fork and plotting the results. To do so, the function daqdocfft was
created. This function calculates the FFT of data, and requires the values of
SampleRate and SamplesPerTrigger as well as data as inputs.
[f,mag] = daqdocfft(data,Fs,blocksize);
daqdocfft outputs the frequency and magnitude of data, which you can then
plot. daqdocfft is shown below.
function [f,mag] = daqdocfft(data,Fs,blocksize)
%
[F,MAG]=DAQDOCFFT(X,FS,BLOCKSIZE) calculates the FFT of X
%
using sampling frequency FS and the SamplesPerTrigger
%
provided in BLOCKSIZE
xfft = abs(fft(data));
mag = 20*log10(xfft);
mag = mag(1:blocksize/2);
f = (0:length(mag)-1)*Fs/blocksize;
f = f(:);
The results are given below.
plot(f,mag)
grid on
ylabel('Magnitude (dB)')
xlabel('Frequency (Hz)')
4-17
4
Getting Started with Analog Input
title('Frequency Components of Tuning Fork')
daqdoc2_1
Frequency Components of Tuning Fork
60
50
40
Magnitude (dB)
30
20
10
0
−10
−20
−30
0
500
1000
1500
2000
Frequency (Hz)
2500
3000
3500
4000
The plot shows the fundamental frequency around 440 Hz and the first
overtone around 880 Hz. A simple way to find actual fundamental frequency is
[ymax,maxindex]= max(mag);
maxindex
maxindex =
441
The answer is 441 Hz.
Note The fundamental frequency is not always the frequency component
with the largest amplitude. A more sophisticated approach involves fitting the
observed frequencies to a harmonic series to find the fundamental frequency.
4-18
Analog Input Examples
Acquiring Data with a National Instruments Board
Suppose you must verify that the nominal frequency of a sine wave generated
by a function generator is 1.00 kHz. To perform this task, you will input the
function generator signal into a National Instruments board. You will then
perform a fast Fourier transform (FFT) on the acquired data to find the
nominal frequency of the generated sine wave. The setup for this task is shown
below.
Data Source
National Instruments Board
Data Sink
Figure
01.00
A/D
MATLAB
workspace
Configuring the Data Acquisition Session
For this example, you will acquire 1 second of data on one input channel. The
board is set to a sampling rate of 10 kHz, which is well above the frequency of
interest. After you connect the input signal to the board, you will trigger the
acquisition one time using a manual trigger.
You can run this example by typing daqdoc4_2 at the MATLAB command line.
1. Create a device object – Create the analog input object AI for a National
Instruments board. The installed adaptors and hardware IDs are found with
daqhwinfo.
AI = analoginput('nidaq',1);
2. Add channels – Add one channel to AI.
chan = addchannel(AI,0);
4-19
4
Getting Started with Analog Input
3. Configure property values – Assign values to the basic setup properties,
and create the variables blocksize and Fs, which are used for subsequent
analysis. The actual sampling rate is retrieved since it may be set by the engine
to a value that differs from the specified value.
duration = 1; %1 second acquisition
set(AI,'SampleRate',10000)
ActualRate = get(AI,'SampleRate');
set(AI,'SamplesPerTrigger',duration*ActualRate)
set(AI,'TriggerType','Manual')
blocksize = get(AI,'SamplesPerTrigger');
Fs = ActualRate;
4. Acquire data – Start AI, issue a manual trigger, and extract all data from
the engine. Before start is issued, you should begin inputting data from the
function generator into the data acquisition board.
start(AI)
trigger(AI)
data = getdata(AI);
5. Clean up – When you no longer need AI, you should remove it from memory
and from the MATLAB workspace.
delete(AI)
clear AI
Analyzing the Data
For this experiment, analysis consists of finding the frequency of the input
signal and plotting the results. You can find the signal frequency with
daqdocfft.
[f,mag] = daqdocfft(data,Fs,blocksize);
This function, which is shown in “Analyzing the Data” on page 4-17, calculates
the FFT of data, and requires the values of SampleRate and
SamplesPerTrigger as well as data as inputs. daqdocfft outputs the
frequency and magnitude of data, which you can then plot.
4-20
Analog Input Examples
The results are given below.
plot(f,mag)
grid on
ylabel('Magnitude (dB)')
xlabel('Frequency (Hz)')
title('Frequency Output by Function Generator')
daqdoc2_2
Frequency Output by Function Generator
80
60
Magnitude (dB)
40
20
0
−20
−40
−60
0
500
1000
1500
2000
2500
3000
Frequency (Hz)
3500
4000
4500
5000
This plot shows the nominal frequency around 1000 Hz. A simple way to find
actual frequency is shown below.
[ymax,maxindex]= max(mag);
maxindex
maxindex =
994
The answer is 994 Hz.
4-21
4
Getting Started with Analog Input
Evaluating the Analog Input Object Status
You can evaluate the status of an analog input object by:
• Returning the values of certain properties
• Invoking the display summary
Status Properties
The properties associated with the status of your analog input object allow you
to evaluate:
• If the device object is running
• If data is being logged to the engine or to a disk file
• How much data has been acquired
• How much data is available to be extracted from the engine
The analog input status properties are given below.
Table 4-5: Analog Input Status Properties
Property Name
Description
Logging
Indicate if data is being logged to memory or to a
disk file.
Running
Indicate if the device object is running.
SamplesAcquired
Indicate the number of samples acquired per
channel.
SamplesAvailable
Indicate the number of samples available per
channel in the data acquisition engine.
When you issue the start function, Running is automatically set to On. When
the trigger executes, Logging is automatically set to On and SamplesAcquired
keeps a running count of the total number of samples per channel that have
been logged to the engine or a disk file. SamplesAvailable tells you how many
samples per channel are available to be extracted from the engine with the
getdata function.
4-22
Evaluating the Analog Input Object Status
When the requested number of samples are acquired, SamplesAcquired
reflects this number, and both Running and Logging are automatically set to
Off. When you extract all the samples from the engine, SamplesAvailable is 0.
The Display Summary
You can invoke the display summary by typing the analog input object at the
command line. The displayed information reflects many of the basic setup
properties described in “Configuring Analog Input Properties” on page 4-9, 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:
• Acquisition parameters
- The sampling rate
- The number of samples to acquire per trigger
- The acquisition duration for each trigger
- The destination for logged data
• Trigger parameters
- The trigger type
- The number of triggers, including the number of triggers already executed
• The engine status
- Whether the engine is logging data, waiting to start, or waiting to trigger
- The number of samples acquired since starting
- The number of samples available to be extracted with getdata
Channel Summary Information
The channel display summary includes property values associated with:
• The hardware channel mapping
• The channel name
• The engineering units
4-23
4
Getting Started with Analog Input
The display summary for the example given in “Acquiring Data with a Sound
Card” on page 4-15 before start is issued is shown below.
Display Summary of Analog Input (AI) Object Using 'AudioPCI Record'.
Acquisition Parameters:
General display
summary
Trigger Parameters:
Engine status:
8000 samples per second on each channel.
8000 samples per trigger on each channel.
1 sec. of data to be logged per trigger.
Log data to 'Memory' on trigger.
1 'Manual' trigger(s) on TRIGGER.
Waiting for START.
0 samples acquired since starting.
0 samples available for GETDATA.
AI object contains channel(s):
Channel display
summary
Index: ChannelName: HwChannel: InputRange: SensorRange: UnitsRange: Units:
1
'Mono'
1
[-1 1]
[-1 1]
[-1 1]
'Volts
You can use the Channel property to display only the channel summary
information.
AI.Channel
4-24
5
Doing More with Analog
Input
Overview
. . . . . . . . . . . . . . . . . . . . . 5-2
Configuring and Sampling Input Channels
Input Channel Configuration . . . . . . . .
Sampling Rate . . . . . . . . . . . . . .
Channel Skew . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5-3
5-4
5-6
5-7
Managing Acquired Data . .
Previewing Data . . . . . . .
Extracting Data from the Engine
Returning Time Information . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5-9
5-9
5-13
5-18
Configuring Analog Input Triggers . . . .
Defining a Trigger: Trigger Types and Conditions
Executing the Trigger . . . . . . . . . . . .
Trigger Delays . . . . . . . . . . . . . . .
Repeating Triggers . . . . . . . . . . . . .
How Many Triggers Occurred? . . . . . . . .
When Did the Trigger Occur? . . . . . . . . .
Device-Specific Hardware Triggers . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5-20
5-21
5-26
5-26
5-30
5-36
5-37
5-37
Configuring Events and Actions . . . . . .
Event Types . . . . . . . . . . . . . . . .
Recording and Retrieving Event Information . .
Creating and Executing Action Functions . . . .
Examples: Using Action Properties and Functions
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 5-46
. 5-46
. 5-49
. 5-52
. 5-53
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Linearly Scaling the Data: Engineering Units . . . . . 5-56
Example: Performing a Linear Conversion . . . . . . . . 5-57
5
Doing More with Analog Input
Overview
This chapter presents the complete analog input functionality available to you
with the Data Acquisition Toolbox. Properties and functions are presented in a
way that reflects the typical procedures you will use to configure your analog
input data acquisition session. Topics include:
• Configuring and sampling input channels
• Managing acquired data
• Configuring analog input triggers
• Configuring events and actions
• Linearly scaling the data
5-2
Configuring and Sampling Input Channels
Configuring and Sampling Input Channels
The hardware you are using has characteristics that satisfy your specific
application needs. Some of the most important hardware characteristics are
related to configuring:
• The input channel type
• The sampling rate
• The channel skew (scanning hardware only)
Properties associated with configuring and sampling input channels are given
below.
Table 5-1: Analog Input Properties Related to Sampling Channels
Property Name
Description
ChannelSkew
Specify the time between consecutive scanned
hardware channels.
ChannelSkewMode
Specify how the channel skew is determined.
InputType
Specify the analog input hardware channel
configuration.
SampleRate
Specify the per-channel rate at which analog data is
converted to digital data.
5-3
5
Doing More with Analog Input
Input Channel Configuration
You can configure your hardware input channels with the InputType property.
The device-specific values for this property are given below.
Table 5-2: InputType Property Values
Vendor
InputType Value
National
Instruments
{Differential}|SingleEnded|
NonReferencedSingleEnded
ComputerBoards
{Differential}|SingleEnded
Agilent Technologies
Differential
Sound Cards
AC-Coupled
The InputType value determines the number of hardware channels you can
add to a device object. You can return the channel IDs with the daqhwinfo
function. For example, suppose you create the analog input object ai for a
National Instruments board. To display the differential channel IDs
ai = analoginput('nidaq',1);
hwinfo = daqhwinfo(ai);
hwinfo.DifferentialIDs
ans =
0
1
2
3
4
5
6
7
In contrast, the single-ended channel IDs would be numbered 0 through 15.
Note If the InputType value is changed, and that change decreases the
number of channels contained by the analog input object, then a warning is
returned and all channels are deleted.
5-4
Configuring and Sampling Input Channels
National Instruments Devices
For National Instruments devices, InputType can be Differential,
SingleEnded, or NonReferencedSingleEnded. Channels configured for
differential input are not connected to a fixed reference such as earth, and
input signals are measured as the difference between two terminals. Channels
configured for single-ended input are connected to a common ground, and input
signals are measured with respect to this ground. Channels configured for
nonreferenced single-ended input are connected to their own ground reference,
and input signals are measured with respect to this reference. The ground
reference is tied to the negative input of the instrumentation amplifier.
The number of channels that you can add to a device object depends on the
InputType property value. Most National Instruments boards have 16 or 64
single-ended inputs and 8 or 32 differential inputs, which are interleaved in
banks of 8. This means that for a 64 channel board with single-ended inputs,
you can add all 64 channels. However, if the channels are configured for
differential input, you can only add channels 0-7, 16-23, 32-39, and 48-55.
ComputerBoards Devices
For ComputerBoards devices, InputType can be Differential or SingleEnded.
Channels configured for differential input are not connected to a fixed
reference such as earth, and the input signals are measured as the difference
between two terminals. Channels configured for single-ended input are
connected to a common ground, and input signals are measured with respect to
this ground.
Agilent Technologies Devices
For Agilent Technologies devices, the only valid InputType value is
Differential. Channels configured for differential input are not connected to
a fixed reference such as earth, and the input signals are measured as the
difference between two terminals.
Sound Cards
For sound cards, the only valid InputType value is AC-Coupled. When input
channels are AC-coupled, they are connected so that constant (DC) signal
levels are suppressed, and only nonzero AC signals are measured.
5-5
5
Doing More with Analog Input
Sampling Rate
The sampling rate is defined as the per-channel rate (in samples/second) that
an analog input subsystem converts analog data to digital data. You specify the
sampling rate with the SampleRate property.
The maximum rate at which channels are sampled depends on the type of
hardware you are using. If you are using simultaneous sample and hold (SS/H)
hardware such as a sound card, then the maximum sampling rate for each
channel is given by the maximum board rate. For example, suppose you create
the analog input object ai for a sound card and configure it for stereo operation.
If the device has a maximum rate of 48.0 kHz, then the maximum sampling
rate per channel is 48.0 kHz.
ai = analoginput('winsound');
addchannel(ai,1:2);
set(ai,'SampleRate',48000)
If you are using scanning hardware such as a National Instruments board,
then the maximum sampling rate your hardware is rated at typically applies
for one channel. Therefore, the maximum sampling rate per channel is given
by the formula
Maximum board rate
Maximum sampling rate per channel = -------------------------------------------------------------------------------Number of channels scanned
For example, suppose you create the analog input object ai for a National
Instruments board and add 10 channels to it. If the device has a maximum rate
of 100 kHz, then the maximum sampling rate per channel is 10 kHz.
ai = analoginput('nidaq',1);
set(ai,'InputType','SingleEnded')
addchannel(ai,0:9);
set(ai,'SampleRate',10000)
Typically, you can achieve this maximum rate only under ideal conditions. In
practice, the sampling rate depends on several characteristics of the analog
input subsystem including the settling time, the gain, and the channel skew.
Channel skew is discussed in the next section.
5-6
Configuring and Sampling Input Channels
Note Whenever the SampleRate value is changed, the BufferingConfig
property value is recalculated by the engine if the BufferingMode property is
set to Auto. Since BufferingConfig indicates the memory used by the engine,
you should monitor this property closely.
Channel Skew
Many data acquisition devices have one A/D converter that is multiplexed to all
input channels. If you sample multiple input channels from scanning
hardware, then each channel is sampled sequentially following this procedure:
1 A single input channel is sampled.
2 The analog signal is converted to a digital value.
3 The process is repeated for every input channel being used.
Since these channels cannot be sampled simultaneously, a time gap exists
between consecutively sampled channels. This time gap is called the channel
skew. The channel skew and the sample period is illustrated below.
Group
scan 1
Group
scan 2
Group
scan n
...
Channels
Sample period
Channel skew
Time
5-7
5
Doing More with Analog Input
As shown in the preceding figure, a scan occurs when all channels in a group
are sampled once and the scan rate is defined as the rate at which every
channel in the group is sampled. The properties associated with configuring
the channel skew are given below.
Table 5-3: Channel Skew Properties
Property Name
Description
ChannelSkew
Specify the time between consecutive scanned
hardware channels.
ChannelSkewMode
Specify how the channel skew is determined.
ChannelSkew and ChannelSkewMode are configurable only for scanning
hardware and not for simultaneous sample and hold (SS/H) hardware. For SS/
H hardware, ChannelSkewMode can only be None, and ChannelSkew can only be
0. The values for ChannelSkewMode are given below.
Table 5-4: ChannelSkewMode Property Values
ChannelSkewMode
Value
Description
None
No channel skew is defined. This is the only valid
value for simultaneous sample and hold (SS/H)
hardware.
Equisample
The channel skew is automatically calculated as
[(sampling rate)(number of channels)]-1.
Manual
The channel skew must be set with the
ChannelSkew property.
Minimum
The channel skew is given by the smallest value
supported by the hardware.
If ChannelSkewMode is Minimum or Equisample, then ChannelSkew indicates the
appropriate read-only value. If ChannelSkewMode is set to Manual, you must
specify the channel skew with ChannelSkew.
5-8
Managing Acquired Data
Managing Acquired Data
At the core of any analog input application lies the data you acquire from a
sensor and input into your computer for subsequent analysis. The role of the
analog input subsystem is to convert analog data to digitized data that can be
read by the computer. There are two ways to manage acquired data:
• Preview the data with the peekdata function.
• Extract the data from the engine with the getdata function.
After data is extracted from the engine, you can analyze it, save it to disk, etc.
In addition to these two functions, there are several properties associated with
managing acquired data. These properties are listed below.
Table 5-5: Analog Input Data Management Properties
Property Name
Description
SamplesAcquired
Indicate the number of samples acquired per
channel.
SamplesAvailable
Indicate the number of samples available per
channel in the data acquisition engine.
SamplesPerTrigger
Specify the number of samples to acquire for each
channel group member for each trigger that occurs.
Previewing Data
Before you extract and analyze acquired data, you may want to examine
(preview) the data as it is being acquired. Previewing the data allows you to
determine if the hardware is performing as expected and if your acquisition
process is configured correctly. Once you are convinced that your system is in
order, you may still want to monitor the data even as it is being analyzed or
saved to disk.
Previewing data is managed with the peekdata function. For example, to
preview the most recent 1000 samples acquired for the analog input object ai
data = peekdata(ai,1000);
5-9
5
Doing More with Analog Input
After start is issued, you can call peekdata. peekdata is a nonblocking
function since it immediately returns control to MATLAB. Therefore, samples
may be missed or repeated.
When a peekdata call is processed, the most recent samples requested are
immediately returned, but the data is not extracted from the engine. In other
words, peekdata provides a “snapshot” of the most recent requested samples.
This situation is illustrated below.
Time
...
Take a snapshot of the most
recent requested data
Data stored in engine
If another peekdata call is issued, then once again, only the most recent
requested samples are returned. This situation is illustrated below.
Time
...
Take another snapshot of the
most recent requested data
Data stored in engine
5-10
Managing Acquired Data
Rules for Using peekdata
Using peekdata to preview data follows these rules:
• You can call peekdata before a trigger executes. Therefore, peekdata is
useful for previewing data before it is logged to the engine or a disk file.
• In most cases, you will call peekdata while the device object is running.
However, you can call peekdata once after the device object stops running.
• If the specified number of preview samples is greater than the number of
samples currently acquired, all available samples are returned with a
warning message stating that the requested number of samples were not
available.
For more information about peekdata, refer to its reference pages in Chapter
9, “Function Reference.”
Example: Polling the Data Block
Under certain circumstances, you may want to poll the data block. Polling the
data block is useful when calling peekdata since this function does not block
execution control. For example, you can issue peekdata calls based on the
number of samples acquired by polling the SamplesAcquired property.
You can run this example by typing daqdoc5_1 at the MATLAB command line.
1. Create a device object – Create the analog input object AI for a sound card.
The available adaptors and hardware IDs are found with daqhwinfo.
AI = analoginput('winsound');
%AI = analoginput('nidaq',1);
%AI = analoginput('cbi',1);
2. Add channels – Add one hardware channel to AI.
addchannel(AI,1);
%addchannel(AI,0); % For NI and CBI
3. Configure property values – Define a 10 second acquisition, set up a plot,
and store the plot handle and title handle in the variables P and T, respectively.
duration = 10; % Ten second acquisition
ActualRate = get(AI,'SampleRate');
set(AI,'SamplesPerTrigger',duration*ActualRate)
figure
5-11
5
Doing More with Analog Input
set(gcf,'doublebuffer','on') %Reduce plot flicker
P = plot(zeros(1000,1));
T = title([sprintf('Number of peekdata calls: '), num2str(0)]);
xlabel('Samples'), axis([0 1000 -1 1]), grid on
4. Acquire data – Start AI and update the display for each 1000 samples
acquired by polling SamplesAcquired. The drawnow command forces MATLAB
to update the plot. Since peekdata is used, all acquired data may not be
displayed.
start(AI)
i = 1;
while AI.SamplesAcquired < AI.SamplesPerTrigger
while AI.SamplesAcquired < 1000*i
end
data = peekdata(AI,1000);
set(P,'ydata',data);
set(T,'String',[sprintf('Number of peekdata calls: '),
num2str(i)]);
drawnow
i = i + 1;
end
while strcmp(AI.Running,'On')
end
5. Clean up – When you no longer need AI, you should remove it from memory
and from the MATLAB workspace.
delete(AI)
clear AI
As you run this example, you may not preview all 80,000 samples stored in the
engine. This is because the engine may store data faster than it can be
displayed, and peekdata does not guarantee that all requested samples are
processed.
5-12
Managing Acquired Data
Extracting Data from the Engine
Many data acquisition applications require that data is acquired at a fixed
(often high) rate, and that the data is 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. If acquired data is not extracted in a timely fashion, it may be
overwritten.
Data is extracted from the engine with the getdata function. For example, to
extract 1000 samples for the analog input object ai
data = getdata(ai,1000);
In addition to returning acquired data, getdata can return relative time,
absolute time, and event information. As shown below, data is an m-by-n array
containing acquired data where m is the number of samples and n is the
number of channels.
d11 d12
d1n
d21 d22
d2n
d31 d32 ... d3n
.
.
.
.
.
.
dm1 dm2
.
.
.
Extracted data. Each column
represents a separate input channel.
dmn
getdata is considered a blocking function since it returns control to MATLAB
only when the requested data is available. Therefore, samples are not missed
or repeated. When a trigger executes, acquired data fills the engine. When a
getdata call is processed, the requested samples are returned when the data is
available, and then extracted from the engine.
5-13
5
Doing More with Analog Input
As shown below, if a fraction of the data stored in the engine is extracted, then
getdata always extracts the oldest data.
Time
...
Extract the requested data
Data stored in engine
If another getdata call is issued, then once again, the oldest samples are
extracted.
Time
...
Extract the requested data
Data stored in engine
Data has been extracted from the engine
5-14
Managing Acquired Data
Rules for Using getdata
Using getdata to extract data stored in the engine follows these rules:
• If the requested number of samples is greater than the samples to be
acquired, then an error is returned.
• If the requested data is not returned in the expected amount of time, an error
is returned. The expected time to return data is given by the time it takes the
engine to fill one data block plus the time specified by the Timeout property.
• You can issue ^C (Control+C) while getdata is blocking. This will not stop
the acquisition but will return control to MATLAB.
• The SamplesAcquired property keeps a running count of the total number of
samples per channel that have been acquired.
• The SamplesAvailable property tells you how many samples you can extract
from the engine per channel.
• MATLAB supports math operations only for the double data type. Therefore,
if you extract data using the native data type of your hardware (typically
int16), you must convert the data to doubles before performing math
operations.
For more information about getdata, refer to its reference pages in Chapter 9,
“Function Reference.”
Example: Previewing and Extracting Data
Suppose you have a data acquisition application that is particularly time
consuming. By previewing the data, you can ascertain whether the acquisition
is proceeding as expected without acquiring all the data. If it is not, then you
can abort the session and diagnose the problem. This example illustrates how
you might use peekdata and getdata together in such an application.
You can run this example by typing daqdoc5_2 at the MATLAB command line.
1. Create a device object – Create the analog input object AI for a sound card.
The installed adaptors and hardware IDs are found with daqhwinfo.
AI = analoginput('winsound');
%AI = analoginput('nidaq',1);
%AI = analoginput('cbi',1);
5-15
5
Doing More with Analog Input
2. Add channels – Add one hardware channel to AI.
chan = addchannel(AI,1);
%chan = addchannel(AI,0); % For NI and CBI
3. Configure property values – Define a 10-second acquisition, set up the plot,
and store the plot handle in the variable P. The amount of data to display is
given by preview.
duration = 10; % Ten second acquisition
set(AI,'SampleRate',8000)
ActualRate = get(AI,'SampleRate');
set(AI,'SamplesPerTrigger',duration*ActualRate)
preview = duration*ActualRate/100;
subplot(211)
set(gcf,'doublebuffer','on')
P = plot(zeros(preview,1)); grid on
xlabel('Samples')
ylabel('Signal Level (Volts)')
4. Acquire data – Start AI and update the display using peekdata every time
an amount of data specified 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
Extract all the acquired data from the engine, and plot the data.
data = getdata(AI);
subplot(212), plot(data), grid on
title('All Acquired Data')
xlabel('Samples')
ylabel('Signal level (volts)')
5-16
Managing Acquired Data
5. Clean up – When you no longer need AI, you should remove it from memory
and from the MATLAB workspace.
delete(AI)
clear AI
The data is shown below.
daqdoc5_2
Preview Data
Signal Level (Volts)
0.2
0.1
0
−0.1
−0.2
−0.3
0
100
200
300
400
Samples
500
600
700
5
6
7
800
All Acquired Data
0.3
Signal level (volts)
0.2
0.1
0
−0.1
−0.2
−0.3
−0.4
0
1
2
3
4
Samples
8
4
x 10
5-17
5
Doing More with Analog Input
Returning Time Information
You can return relative time and absolute time information with the getdata
function. Relative time is associated with the extracted data. Absolute time is
associated with the first trigger executed.
Relative Time
To return data and relative time information for the analog input object ai
[data,time] = getdata(ai);
time is an m-by-1 array of relative time values where m is the number of
samples returned. time = 0 corresponds to the first sample logged by the data
acquisition engine, and time is measured continuously until the acquisition is
stopped.
The relationship between the samples acquired and the relative time for each
sample is shown below for m samples and n channels.
Data array. Each column
represents one channel
d11 d12
d1n
t1
d21 d22
d2n
t2
d31 d32 ... d3n
t3
.
.
.
.
.
.
dm1 dm2
5-18
Relative time array
.
.
.
dmn
.
.
.
tm
Managing Acquired Data
Absolute Time
To return data, relative time information, and the absolute time of the first
trigger for the analog input object ai
[data,time,abstime] = getdata(ai);
The absolute time is returned using MATLAB’s clock format.
[year month day hour minute seconds]
The absolute time from the getdata call is
abstime
abstime =
1.0e+003 *
1.9990
0.0020
0.0190
0.0130
0.0260
0.0208
To convert the clock vector to a more convenient form
t = fix(abstime);
sprintf('%d:%d:%d',t(4),t(5),t(6))
ans =
13:26:20
The absolute time of the first trigger is also recorded by the
InitialTriggerTime property.
Note that absolute times are recorded by the EventLog property for each trigger
executed. You can always find the absolute time associated with a data sample
by adding its relative time to the absolute time of the associated trigger. Refer
to “Recording and Retrieving Event Information” on page 5-49 for more
information about returning absolute time information with the EventLog
property.
5-19
5
Doing More with Analog Input
Configuring Analog Input Triggers
An analog input trigger is defined as an event that initiates data logging. You
can log data to the engine (memory) and to a disk file. As shown in the figure
below, when a trigger occurs, the Logging property is automatically set On and
data is stored in the specified target.
Logging = Off
Logging = On
Time
Trigger occurs
Log data to engine
and disk file
When defining a trigger, you must specify the trigger type. Additionally, you
may need to specify one or more of these parameters:
• A trigger condition and trigger condition value
• The number of times to repeat the trigger
• A trigger delay
• An action function to execute when the trigger event occurs
Properties associated with analog input triggers are given below.
Table 5-6: Analog Input Trigger Properties
5-20
Property Name
Description
InitialTriggerTime
Indicate the absolute time of the first trigger.
ManualTriggerHwOn
Specify that the hardware device starts when a
manual trigger is issued.
TriggerAction
Specify the M-file action function to execute when
a trigger occurs.
Configuring Analog Input Triggers
Table 5-6: Analog Input Trigger Properties (Continued)
Property Name
Description
TriggerChannel
Specify the channels serving as trigger sources.
TriggerCondition
Specify the condition that must be satisfied before
a trigger executes.
TriggerCondition
Value
Specify one or more voltage values that must be
satisfied before a trigger executes.
TriggerDelay
Specify the delay value for data logging.
TriggerDelayUnits
Specify the units in which trigger delay data is
measured.
TriggerRepeat
Specify the number of additional times the trigger
executes.
TriggersExecuted
Indicate the number of triggers that execute.
TriggerType
Specify the type of trigger to execute.
Except for TriggerAction, these trigger-related properties are discussed in the
following sections. TriggerAction is discussed in “Configuring Events and
Actions” on page 5-46.
Defining a Trigger: Trigger Types and Conditions
Defining a trigger for an analog input object involves specifying the trigger type
with the TriggerType property. You can think of the trigger type as the source
of the trigger. For some trigger types, you may need to specify a trigger
condition and a trigger condition value. Trigger conditions are specified with
the TriggerCondition property, while trigger condition values are specified
with the TriggerConditionValue property.
5-21
5
Doing More with Analog Input
The analog input TriggerType and TriggerCondition values are given below.
Table 5-7: Analog Input TriggerType and TriggerCondition Values
TriggerType
Value
TriggerCondition
Value
Description
{Immediate}
None
The trigger occurs just after you issue
the start function.
Manual
None
The trigger occurs just after you
manually issue the trigger function.
Software
{Rising}
The trigger occurs when the signal has
a positive slope when passing through
the specified value.
Falling
The trigger occurs when the signal has
a negative slope when passing through
the specified value.
Leaving
The trigger occurs when the signal
leaves the specified range of values.
Entering
The trigger occurs when the signal
enters the specified range of values.
For some devices, additional trigger types and trigger conditions are available.
Refer to the TriggerType and TriggerCondition reference pages in Chapter
10, “Base Property Reference” for these device-specific values.
Trigger types are grouped into two main categories:
• Device-independent triggers
• Device-specific hardware triggers
The trigger types shown above are device-independent triggers since they are
available for all supported hardware. For these trigger types, the action that
initiates the trigger event involves satisfying a trigger condition in the engine
(software trigger type), or issuing a toolbox function (start or trigger).
5-22
Configuring Analog Input Triggers
Conversely, device-specific hardware triggers depend on the specific hardware
device you are using. For these trigger types, the action that initiates the
trigger event involves an external analog or digital signal.
Device-specific hardware triggers for National Instruments, ComputerBoards,
and Agilent Technologies devices are discussed in “Device-Specific Hardware
Triggers” on page 5-37. Device-independent triggers are discussed below.
Immediate Trigger. If TriggerType is Immediate (the default value), the trigger
occurs immediately after the start function is issued. You can configure an
analog input object for continuous acquisition by use an immediate trigger and
setting SamplesPerTrigger or TriggerRepeat to inf. Trigger repeats are
discussed in “Repeating Triggers” on page 5-30.
Manual Trigger. If TriggerType is Manual, the trigger occurs just after you issue
the trigger function. A manual trigger may provide you with more control over
the data that is logged. For example, if the acquired data is noisy, you can
preview the data using peekdata, and then manually execute the trigger after
you observe that the signal is well-behaved.
Software Trigger. If TriggerType is Software, the trigger occurs when a signal
satisfying the specified condition is detected on one of the hardware channels
specified by the TriggerChannel property. The trigger condition is specified as
either a voltage value and slope, or a range of voltage values using the
TriggerCondition and TriggerConditionValue properties.
Example: Voice Activation Using a Software Trigger
This example demonstrates how to configure an acquisition with a sound card
based on voice activation. The sample rate is set to 44.1 kHz and data is logged
after an acquired sample has a value greater than or equal to 0.2 volt and a
rising (positive) slope. A portion of the acquired data is then extracted from the
engine and plotted.
You can run this example by typing daqdoc5_3 at the MATLAB command line.
1. Create a device object – Create the analog input object AIVoice for a sound
card. The installed adaptors and hardware IDs are found with daqhwinfo.
AIVoice = analoginput('winsound');
%AIVoice = analoginput('nidaq',1);
%AIVoice = analoginput('cbi',1);
5-23
5
Doing More with Analog Input
2. Add channels – Add one hardware channel to AIVoice.
chan = addchannel(AIVoice,1);
%chan = addchannel(AIVoice,0); % For NI and CBI
3. Configure property values – Define a 2-second acquisition and configure a
software trigger. The source of the trigger is chan, and the trigger executes
when a rising voltage level has a value of at least 0.2 volt.
duration = 2; % two second acquisition
set(AIVoice,'SampleRate',44100)
ActualRate = get(AIVoice,'SampleRate');
set(AIVoice,'SamplesPerTrigger',ActualRate*duration)
set(AIVoice,'TriggerChannel',chan)
set(AIVoice,'TriggerType','Software')
set(AIVoice,'TriggerCondition','Rising')
set(AIVoice,'TriggerConditionValue',0.2)
4. Acquire data – Start AIVoice, acquire the specified number of samples, and
extract the first 1000 samples from the engine as sample-time pairs. Display
the number of samples remaining in the engine.
start(AIVoice)
while strcmp(AIVoice.Running,'On')
end
[data,time] = getdata(AIVoice,1000);
remsamp = num2str(AIVoice.SamplesAvailable);
disp(['Number of samples remaining in engine: ', remsamp])
Plot all extracted data.
plot(time,data)
drawnow
xlabel('Time (sec.)')
ylabel('Signal Level (Volts)')
grid on
5. Clean up – When you no longer need AIVoice, you should remove it from
memory and from the MATLAB workspace.
delete(AIVoice)
clear AIVoice
5-24
Configuring Analog Input Triggers
Note that when using software triggers, you must specify the TriggerType
value before the TriggerCondition value. The output from this example is
shown below.
daqdoc3_4
Voice Activation
0.3
0.2
Signal Level (Volts)
0.1
0
−0.1
−0.2
−0.3
−0.4
0
0.005
0.01
0.015
0.02
0.025
Time (sec.)
The first logged sample has a signal level value of at least 0.2 volt, and this
value corresponds to time = 0. Note that after you issue the getdata function,
87,200 samples remain in the engine.
AIVoice.SamplesAvailable
ans =
87200
5-25
5
Doing More with Analog Input
Executing the Trigger
For an analog input trigger to occur, you must follow these steps:
1 Configure the appropriate trigger properties.
2 Issue the start function.
3 Issue the trigger function if TriggerType value is Manual.
Once the trigger occurs, data logging is initiated. The device object and
hardware device stop executing when the requested samples are acquired, a
run-time error occurs, or you issue the stop function.
Note After a trigger occurs, the number of samples specified by
SamplesPerTrigger is acquired for each channel group member before the
next trigger can occur.
Trigger Delays
Trigger delays allow you to control exactly when data is logged after a trigger
occurs. You can log data either before the trigger or after the trigger. Logging
data before the trigger occurs is called pretriggering, while logging data after a
trigger occurs is called postriggering.
You configure trigger delays with the TriggerDelay property. Pretriggers are
specified by a negative TriggerDelay value, while postriggers are specified by
a positive TriggerDelay value. You can delay data logging in time or in
samples using the TriggerDelayUnits property. When TriggerDelayUnits is
set to Samples, data logging is delayed by the specified number of samples.
When the TriggerDelayUnits property is set to Seconds, data logging is
delayed by the specified number of seconds.
5-26
Configuring Analog Input Triggers
Capturing Pretrigger Data
In some circumstances, you may want to capture data before the trigger occurs.
Such data is called pretrigger data. When capturing pretrigger data, the
SamplesPerTrigger property value includes the data captured before and after
the trigger occurs. Capturing pretrigger data is illustrated in below.
Trigger samples
Pretrigger samples
Trigger occurs
SamplesPerTrigger
Data stored in engine
You can capture pretrigger data for manual triggers and software triggers. If
TriggerType is Manual, and the trigger function is issued before the trigger
delay passes, then a warning is returned and the trigger is ignored (the trigger
event does not occur).
You cannot capture pretrigger data for immediate triggers or device-specific
hardware triggers.
Note Pretrigger data has negative relative time values associated with it.
This is because time = 0 corresponds to the time the trigger event occurs and
data logging is initiated.
5-27
5
Doing More with Analog Input
Capturing Postrigger Data
In some circumstances, you may want to capture data after the trigger occurs.
Such data is called postrigger data. When capturing postrigger data, the
SamplesPerTrigger property value and the number of postrigger samples are
equal. Capturing postrigger data is illustrated below.
Postrigger samples
Trigger occurs
Data stored in engine
SamplesPerTrigger
You can capture postrigger using any supported trigger type.
Example: Voice Activation and Pretriggers
This example modifies daqdoc5_3 such that 500 pretrigger samples are
acquired. You can run this example by typing daqdoc5_4 at the MATLAB
command line.
1. Create a device object – Create the analog input object AIVoice for a sound
card. The installed adaptors and hardware IDs are found with daqhwinfo.
AIVoice = analoginput('winsound');
%AIVoice = analoginput('nidaq',1);
%AIVoice = analoginput('cbi',1);
2. Add channels – Add one hardware channel to AIVoice.
chan = addchannel(AIVoice,1);
%chan = addchannel(AIVoice,0); % For NI and CBI
5-28
Configuring Analog Input Triggers
3. Configure property values – Define a 2-second acquisition, and configure a
software trigger. The source of the trigger is chan, and the trigger executes
when a rising voltage level has a value of at least 0.2 volt. Additionally, 500
pretrigger samples are collected.
duration = 2; % two second acquisition
set(AIVoice,'SampleRate',44100)
ActualRate = get(AIVoice,'SampleRate');
set(AIVoice,'SamplesPerTrigger',ActualRate*duration)
set(AIVoice,'TriggerChannel',chan)
set(AIVoice,'TriggerType','Software')
set(AIVoice,'TriggerCondition','Rising')
set(AIVoice,'TriggerConditionValue',0.2)
set(AIVoice,'TriggerDelayUnits','Samples')
set(AIVoice,'TriggerDelay',-500)
4. Acquire data – Start AIVoice, acquire the specified number of samples, and
extract the first 1000 samples from the engine as sample-time pairs.
start(AIVoice);
while strcmp(AIVoice.Running,'On')
end
[data,time] = getdata(AIVoice,1000);
Plot all the extracted data.
plot(time,data)
xlabel('Time (sec.)')
ylabel('Signal Level (Volts)')
grid on
5. Clean up – When you no longer need AIVoice, you should remove it from
memory and from the MATLAB workspace.
delete(AIVoice)
clear AIVoice
5-29
5
Doing More with Analog Input
The output from this example is shown below. Note that the pretrigger data
constitutes half of the 1000 samples extracted from the engine. Additionally,
pretrigger data has negative time associated with it since time = 0 corresponds
to the time the trigger event occurs and data logging is initiated.
daqdoc3_5
Voice Activation with Pretriggering
0.3
0.2
Signal Level (Volts)
0.1
0
−0.1
−0.2
−0.3
−0.4
−0.015
−0.01
−0.005
0
Time (sec.)
0.005
0.01
0.015
Repeating Triggers
You can configure triggers to occur once (one-shot acquisition) or multiple
times. You control trigger repeats with the TriggerRepeat property. If
TriggerRepeat is set to its default value of 0, then the trigger occurs once. If
TriggerRepeat is set to a positive integer value, then the trigger is repeated
the specified number of times. If TriggerRepeat is set to inf, then the trigger
repeats continuously and you can stop the device object only by issuing the
stop function.
5-30
Configuring Analog Input Triggers
Example: Voice Activation and Repeating Triggers
This example modifies daqdoc5_3 such that two triggers are issued. The
specified amount of data is acquired for each trigger and stored in separate
variables. The Timeout value is set to five seconds. Therefore, if getdata does
not return the specified number of samples in the time given by the TimeOut
property plus the time required to acquire the data, the acquisition will be
aborted.
You can run this example by typing daqdoc5_5 at the MATLAB command line.
1. Create a device object – Create the analog input object AIVoice for a sound
card. The installed adaptors and hardware IDs are found with daqhwinfo.
AIVoice = analoginput('winsound');
%AIVoice = analoginput('nidaq',1);
%AIVoice = analoginput('cbi',1);
2. Add channels – Add one hardware channel to AIVoice.
chan = addchannel(AIVoice,1);
%chan = addchannel(AIVoice,0); % For NI and CBI
3. Configure property values – Define a 1-second total acquisition time and
configure a software trigger. The source of the trigger is chan, and the trigger
executes when a rising voltage level has a value of at least 0.2 volt.
Additionally, the trigger is repeated once when the trigger condition is met.
duration = 0.5; % One-half second acquisition for each trigger
set(AIVoice,'SampleRate',44100)
ActualRate = get(AIVoice,'SampleRate');
set(AIVoice,'Timeout',5)
set(AIVoice,'SamplesPerTrigger',ActualRate*duration)
set(AIVoice,'TriggerChannel',chan)
set(AIVoice,'TriggerType','Software')
set(AIVoice,'TriggerCondition','Rising')
set(AIVoice,'TriggerConditionValue',0.2)
set(AIVoice,'TriggerRepeat',1)
5-31
5
Doing More with Analog Input
4. Acquire data – Start AIVoice, acquire the specified number of samples,
extract all the data from the first trigger as sample-time pairs, and extract all
the data from the second trigger as sample-time pairs. Note that you can
extract the data acquired from both triggers with the command
getdata(AIVoice,44100).
start(AIVoice)
while strcmp(AIVoice.Running,'On')
end
[d1,t1] = getdata(AIVoice);
[d2,t2] = getdata(AIVoice);
Plot the data for both triggers.
subplot(211), plot(t1,d1), grid on, hold on
axis([t1(1)-0.05 t1(end)+0.05 -0.8 0.8])
xlabel('Time (sec.)'), ylabel('Signal level (Volts)'),
title('Voice Activation First Trigger')
subplot(212), plot(t2,d2), grid on
axis([t2(1)-0.05 t2(end)+0.05 -0.8 0.8])
xlabel('Time (sec.)'), ylabel('Signal level (Volts)')
title('Voice Activation Second Trigger')
5. Clean up – When you no longer need AIVoice, you should remove it from
memory and from the MATLAB workspace.
delete(AIVoice)
clear AIVoice
5-32
Configuring Analog Input Triggers
The data acquired for both triggers is shown below.
daqdoc3_6
Voice Activation First Trigger
Signal level (Volts)
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
0
0.1
0.2
0.3
0.4
0.5
Time (sec.)
Voice Activation Second Trigger
Signal level (Volts)
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
0.5
0.6
0.7
0.8
Time (sec.)
0.9
1
As described in “Extracting Data from the Engine” on page 5-13, if you do not
specify the amount of data to extract from the engine with getdata, then the
amount of data returned is given by the SamplesPerTrigger property. You can
return data from multiple triggers with one call to getdata by specifying the
appropriate number of samples. When you return data that spans multiple
triggers, a NaN is inserted in the data stream between trigger events. Therefore,
an extra “sample” (the NaN) is stored in the engine and returned by getdata.
Identifying these NaNs allows you to locate where and when each trigger was
issued in the data stream.
5-33
5
Doing More with Analog Input
The figure below illustrates the data stored by the engine during a
multiple-trigger acquisition. The data acquired for each trigger is given by the
SamplesPerTrigger property value. The relative trigger times are shown on
the Time axis where first trigger time corresponds to t 1 (0 seconds by
definition), the second trigger time corresponds to t2, and so on.
Logging
Trigger n
Trigger 2
Trigger 1
SamplesPerTrigger
ì
t2
t1
Data
Off
N
a
N
Data
On
N
a ...
N
Time
tn
Data stored in engine
The following code modifies daqdoc5_5 so that multiple-trigger data is
extracted from the engine with one call to getdata.
returndata = ActualRate*duration*(AIVoice.TriggerRepeat + 1);
start(AIVoice)
[d,t] = getdata(AIVoice,returndata);
Plot the data.
plot(t,d)
xlabel('Time (sec.)')
ylabel('Signal Level (Volts)')
title('Voice Activation for Both Triggers')
grid on
5-34
Configuring Analog Input Triggers
The multiple-trigger data is shown below.
Voice Activation for Both Triggers
0.3
0.2
Signal Level (Volts)
0.1
0
−0.1
−0.2
−0.3
−0.4
0
0.2
0.4
0.6
0.8
Time (sec.)
1
1.2
1.4
You can find the relative trigger times by searching for NaNs in the returned
data. You can find the index location of the NaN in d or t using the isnan
function.
index = find(isnan(d))
index =
22051
With this information, you can find the relative time for the second trigger.
t2time = t(index+1)
t2time =
0.5980
5-35
5
Doing More with Analog Input
How Many Triggers Occurred?
You can find out how many triggers occurred with the TriggersExecuted
property value. The trigger number for each trigger executed is also recorded
by the EventLog property. A convenient way to access event log information is
with the showdaqevents function.
For example, suppose you create the analog input object ai for a sound card
and add one channel to it. ai is configured to acquire 40,000 samples with five
triggers using the default sampling rate of 8000 Hz.
ai = analoginput('winsound');
ch = addchannel(ai,1);
set(ai,'TriggerRepeat',4);
start(ai)
TriggersExecuted returns the number of triggers executed.
ai.TriggersExecuted
ans =
5
showdaqevents returns information for all the events that occurred while ai
was executing.
showdaqevents(ai)
1 Start
2 Trigger#1
3 Trigger#2
4 Trigger#3
5 Trigger#4
6 Trigger#5
7 Stop
(
(
(
(
(
(
(
10:22:04,
10:22:04,
10:22:05,
10:22:06,
10:22:07,
10:22:08,
10:22:09,
0 )
0 )
8000 )
16000 )
24000 )
32000 )
40000 )
Channel:
Channel:
Channel:
Channel:
Channel:
For more information about recording and retrieving events, refer to
“Recording and Retrieving Event Information” on page 5-49.
5-36
N/A
N/A
N/A
N/A
N/A
Configuring Analog Input Triggers
When Did the Trigger Occur?
You can find the absolute time of the first trigger event with the
InitialTriggerTime property value. The absolute time is returned using
MATLAB’s clock format.
[year month day hour minute seconds]
For example, the absolute time of the first trigger event for the preceding
example is
abstime = ai.InitialTriggerTime
abstime =
1.0e+003 *
1.9990
0.0040
0.0170
0.0100
0.0220
0.0041
To convert the clock vector to a more convenient form, you can use the sprintf
function.
t = fix(abstime);
sprintf('%d:%d:%d', t(4),t(5),t(6))
ans =
10:22:4
You can also use the showdaqevents function to return the absolute time of
each trigger event. For more information about trigger events, refer to
“Recording and Retrieving Event Information” on page 5-49.
Device-Specific Hardware Triggers
Many data acquisition devices possess the ability to accept a hardware trigger.
Hardware triggers are processed directly by the hardware and can be either a
digital signal or an analog signal. Hardware triggers are often used when speed
is required since a hardware device can process an input signal much faster
than software.
The device-specific hardware triggers are presented to you as additional
property values. Hardware triggers for National Instruments,
ComputerBoards, and Agilent Technologies devices are discussed below and in
Chapter 10, “Base Property Reference.”
Note that the available hardware trigger support depends on the board you are
using. Refer to your hardware documentation for detailed information about its
triggering capabilities.
5-37
5
Doing More with Analog Input
National Instruments
When using National Instruments (NI) hardware, there are additional trigger
types and trigger conditions available to you. These device-specific property
values fall into two categories: hardware digital triggering and hardware
analog triggering.
The device-specific trigger types and trigger conditions are described below and
in Chapter 10, “Base Property Reference.”
Table 5-8: Analog Input TriggerType and TriggerCondition Property Values for NI Hardware
5-38
TriggerType
Value
TriggerCondition
Value
Description
HwDigital
None
The trigger occurs when the falling edge of a digital
(TTL) signal is detected.
HwAnalogChannel
or HwAnalogPin
{AboveHighLevel}
The trigger occurs when the analog signal is above
the specified value.
BelowLowLevel
The trigger occurs when the analog signal is below
the specified value.
HighHysteresis
The trigger occurs when the analog signal is greater
than the specified high value with hysteresis given by
the specified low value.
InsideRegion
The trigger occurs when the analog signal is inside
the specified region.
LowHysteresis
The trigger occurs when the analog signal is less than
the specified low value with hysteresis given by the
specified high value.
Configuring Analog Input Triggers
Hardware Digital Triggering. If TriggerType is HwDigital, the trigger occurs when
the falling edge of a digital (TTL) signal is detected. The following example
illustrates how to configure a hardware digital trigger.
ai = analoginput('nidaq',1);
addchannel(ai,0:7);
set(ai,'TriggerType','HwDigital')
The diagram below illustrates how you connect a digital trigger signal to an
MIO-16E Series board. PFI0/TRIG1 corresponds to pin 11.
TTL signal
A/D
PFI0/TRIG1
MIO-16E Series board
Hardware Analog Triggering. If TriggerType is HwAnalogPin, the trigger is given
by a low-range analog signal (typically between -10 to 10 volts). For example,
to trigger your acquisition when the trigger signal is between -4 volts and 4
volts
ai = analoginput('nidaq',1);
addchannel(ai,0:7);
set(ai,'TriggerType','HwAnalogPin')
set(ai,'TriggerCondition','InsideRegion')
set(ai,'TriggerConditionValue',[-4.0 4.0])
If TriggerType is HwAnalogChannel, the trigger is given by an analog signal
and the trigger channel is defined as the first channel in the channel group
(MATLAB index of one). The valid range of the analog trigger signal is given
by the full-scale range of the trigger channel. The following example illustrates
how to configure such a trigger where the trigger channel is assigned the
5-39
5
Doing More with Analog Input
descriptive name TrigChan and the default TriggerCondition property value
is used.
ai = analoginput('nidaq',1);
addchannel(ai,0:7);
set(ai.Channel(1),'ChannelName','TrigChan')
set(ai,'TriggerType','HwAnalogChannel')
set(ai,'TriggerConditionValue',0.2)
The diagram below illustrates how you can connect analog trigger signals to an
MIO-16E Series board.
Analog channel
Analog trigger
ACH0
A/D
PFI0/TRIG1
MIO-16E Series board
5-40
Configuring Analog Input Triggers
ComputerBoards
When using ComputerBoards (Measurement Computing Corporation)
hardware, there are additional trigger types and trigger conditions available to
you. These device-specific property values fall into two categories: hardware
digital triggering and hardware analog triggering.
The device-specific trigger types and trigger conditions are described below and
in Chapter 10, “Base Property Reference.”
Table 5-9: Analog Input TriggerType and TriggerCondition Values for CBI Hardware
TriggerType
Value
TriggerCondition
Value
Description
HwDigital
GateHigh
The trigger occurs as long as the digital signal is high.
GateLow
The trigger occurs as long as the digital signal is low.
TrigHigh
The trigger occurs when the digital signal is high.
TrigLow
The trigger occurs when the digital signal is low.
TrigPosEdge
The trigger occurs when the positive (rising) edge of
the digital signal is detected.
{TrigNegEdge}
The trigger occurs when the negative (falling) edge of
the digital signal is detected.
5-41
5
Doing More with Analog Input
Table 5-9: Analog Input TriggerType and TriggerCondition Values for CBI Hardware (Continued)
TriggerType
Value
TriggerCondition
Value
Description
HwAnalog
{TrigAbove}
The trigger occurs when the analog signal makes a
transition from below the specified value to above.
TrigBelow
The trigger occurs when the analog signal makes a
transition from above the specified value to below.
GateNegHys
The trigger occurs when the analog signal is more
than the specified high value. The acquisition stops if
the analog signal is less than the specified low value.
GatePosHys
The trigger occurs when the analog signal is less than
the specified low value. The acquisition stops if the
analog signal is more than the specified high value.
GateAbove
The trigger occurs as long as the analog signal is more
than the specified value.
GateBelow
The trigger occurs as long as the analog signal is less
than the specified value.
GateInWindow
The trigger occurs as long as the analog signal is
within the specified range of values.
GateOutWindow
The trigger occurs as long as the analog signal is
outside the specified range of values.
Hardware Digital Triggering. If TriggerType is HwDigital, the trigger is given by
a digital (TTL) signal. For example, to trigger your acquisition when the
positive edge of a digital signal is detected
ai = analoginput('cbi',1);
addchannel(ai,0:7);
set(ai,'TriggerType','HwDigital')
set(ai,'TriggerCondition','TrigPosEdge')
5-42
Configuring Analog Input Triggers
The diagram below illustrates how you connect a digital trigger signal to a
PCI-DAS1602/16 board. A/D External Trigger corresponds to pin 45.
TTL signal
A/D External
Trigger
A/D
PCI-DAS1602/16 board
Hardware Analog Triggering. If TriggerType is HwAnalog, the trigger is given by
an analog signal. For example, to trigger your acquisition when the trigger
signal is between -4 volts and 4 volts
ai = analoginput('cbi',1);
addchannel(ai,0:7);
set(ai,'TriggerType','HwAnalog');
set(ai,'TriggerCondition','GateInWindow');
set(ai,'TriggerConditionValue',[-4.0 4.0]);
The diagram below illustrates how you connect an analog trigger signal to a
PCI-DAS1602/16 board. AI Ch 0-7 corresponds to pins 2-17, while Analog
Trigger In corresponds to pin 43.
Analog channels
Analog trigger
AI Ch 0-7
A/D
Analog Trigger In
PCI-DAS1602/16 board
5-43
5
Doing More with Analog Input
Agilent Technologies
When using Agilent Technologies hardware, there are additional trigger types
and trigger conditions available to you. These device-specific property values
fall into two categories: hardware digital triggering and hardware analog
triggering.
The device-specific trigger types and trigger conditions are described below and
in Chapter 10, “Base Property Reference.”
Table 5-10: Analog Input TriggerType and TriggerCondition Property Values for Agilent Hardware
TriggerType
Value
TriggerCondition
Value
Description
HwDigital
{PositiveEdge}
The trigger occurs when the positive (rising) edge of a
digital signal is detected.
NegativeEdge
The trigger occurs when the negative (falling) edge of
a digital signal is detected.
{Rising}
The trigger occurs when the analog signal has a
positive slope when passing through the specified
range of values.
Falling
The trigger occurs when the analog signal has a
negative slope when passing through the specified
range of values.
Leaving
The trigger occurs when the analog signal leaves the
specified range of values.
Entering
The trigger occurs when the analog signal enters the
specified range of values.
HwAnalog
Note that when TriggerType is HwAnalog, the trigger condition values are all
specified as two-element vectors. Setting two trigger levels prevents the
module from triggering repeatedly due to a noisy signal.
5-44
Configuring Analog Input Triggers
Hardware Digital Triggering. If TriggerType is HwDigital, the trigger is given by
a digital (TTL) signal. For example, to trigger your acquisition when the
negative edge of a digital signal is detected
ai = analoginput('hpe1432',8);
addchannel(ai,1:16);
set(ai,'TriggerType','HwDigital');
set(ai,'TriggerCondition','NegativeEdge');
Hardware Analog Triggering. If TriggerType is HwAnalog, the trigger is given by
an analog signal. For example, to trigger your acquisition when the trigger
signal is between -4 volts and 4 volts
ai = analoginput('hpe1432',8);
addchannel(ai,1:16);
set(ai,'TriggerType','HwAnalog');
set(ai,'TriggerCondition','Entering');
set(ai,'TriggerConditionValue',[-4.0 4.0]);
set(ai,'TriggerChannel',ai.Channel(1:4));
5-45
5
Doing More with Analog Input
Configuring Events and Actions
You can enhance the power and flexibility of your analog input application by
utilizing events. An event occurs at a particular time after a condition is met
and may result in one or more actions.
While the analog input object is running, you can use events to display a
message, display data, analyze data, or perform just about any other action.
Actions are controlled through action properties and action functions. All event
types have an associated action property. Action functions are M-file functions
that you construct to suit your specific data acquisition needs.
You execute an action when a particular event occurs by specifying the name
of the M-file action function as the value for the associated action property.
Note that daqaction is the default value for some action properties.
Event Types
The analog input event types and associated action properties are described
below.
Table 5-11: Analog Input Action Properties
Event Type
Property Name
Data missed
DataMissedAction
Input overrange
InputOverRangeAction
Run-time error
RuntimeErrorAction
Samples acquired
SamplesAcquiredAction
SamplesAcquiredActionCount
Start
StartAction
Stop
StopAction
Timer
TimerAction
TimerPeriod
Trigger
5-46
TriggerAction
Configuring Events and Actions
Data Missed Event. A data missed event is generated immediately after acquired
data is missed. In most cases, data is missed because:
• The engine cannot keep up with the rate of acquisition.
• The driver wrote new data into the hardware’s FIFO buffer before the
previously acquired data was read. You can usually avoid this problem by
increasing the size of the memory block with the BufferingConfig property.
This event executes the action function specified for the DataMissedAction
property. The default value for DataMissedAction is daqaction, which
displays the event type and the device object name. When a data missed event
occurs, the analog input object is automatically stopped.
Input Overrange Event. An input overrange event is generated immediately after
an overrange condition is detected for any channel group member. An
overrange condition occurs when an input signal exceeds the range specified by
the InputRange property.
This event executes the action function specified for the
InputOverRangeAction property. Overrange detection is enabled only when an
action function is specified for InputOverRangeAction, and the analog input
object is running.
Run-time Error Event. A run-time error event is generated immediately after a
run-time error occurs. Additionally, a toolbox error message is automatically
displayed to the MATLAB workspace. If an error occurs that is not explicitly
handled by the toolbox, then the hardware-specific error message is displayed.
This event executes the action function specified for RuntimeErrorAction. The
default value for RuntimeErrorAction is daqaction, which displays the event
type, the time the event occurred, the device object name, and the error
message.
Run-time errors include hardware errors and timeouts. Run-time errors do not
include configuration errors such as setting an invalid property value.
Samples Acquired Event. A samples acquired event is generated immediately
after a predetermined number of samples is acquired.
This event executes the action function specified for the
SamplesAcquiredAction property every time the number of samples specified
by SamplesAcquiredActionCount is acquired for each channel group member.
5-47
5
Doing More with Analog Input
You should use SamplesAcquiredAction if you must access each sample that is
acquired. However, if you are performing a CPU-intensive task with the data,
then system performance may be adversely affected. If you do not have this
requirement, you may want to use the TimerAction property.
Start Event. A start event is generated immediately after the start function is
issued. This event executes the action function specified for StartAction.
When the StartAction M-file has finished executing, Running is automatically
set to On and the device object and hardware device begin executing.
Stop Event. A stop event is generated immediately after the device object and
hardware device stop running. This occurs when:
• The stop function is issued.
• The requested number of samples is acquired.
• A run-time error occurs.
A stop event executes the action function specified for StopAction. Under most
circumstances, the action function is not guaranteed to complete execution
until sometime after the device object and hardware device stop running, and
the Running property is set to Off.
Timer Event. A timer event is generated whenever the time specified by the
TimerPeriod property passes. This event executes the action function specified
for TimerAction. Time is measured relative to when the device object starts
running.
Some timer events may not be processed if your system is significantly slowed
or if the TimerPeriod value is too small. For example, a common application for
timer events is to display data. However, since displaying data is a
CPU-intensive task, some of these events may be dropped. To guarantee that
events are not dropped, use the SamplesAcquiredAction property.
Trigger Event. A trigger event is generated immediately after a trigger occurs.
This event executes the action function specified for the TriggerAction
property. Under most circumstances, the action function is not guaranteed to
complete execution until sometime after Logging is set to On.
5-48
Configuring Events and Actions
Recording and Retrieving Event Information
While the analog input object is running, certain information is automatically
recorded in the EventLog property for some of the event types listed in the
preceding section. EventLog is a structure that contains two fields: Type and
Data. The Type field contains the event type. The Data field contains
event-specific information. Events are recorded in the order in which they
occur. The first EventLog entry reflects the first event recorded, the second
EventLog entry reflects the second event recorded, and so on.
The event types recorded in EventLog for analog input objects, as well as the
values for the Type and Data fields, are given below.
Table 5-12: Analog Input Event Information Stored in EventLog
Event Type
Type Field Value
Data Field Value
Data missed
DataMissed
RelSample
Input overrange
OverRange
RelSample
Channel
OverRange
Run-time error
Error
AbsTime
RelSample
String
Start
Start
AbsTime
RelSample
Stop
Stop
AbsTime
RelSample
Trigger
Trigger
AbsTime
RelSample
Channel
Trigger
5-49
5
Doing More with Analog Input
Samples acquired events and timer events are not stored in EventLog.
Note Unless a run-time error occurs, EventLog records a start event, trigger
event, and stop event for each data acquisition session.
The Data field values are described below.
The AbsTime Field. AbsTime is used by the run-time error, start, stop, and trigger
events to indicate the absolute time the event occurred. The absolute time is
returned using MATLAB’s clock format.
day-month-year hour:minute:second
The Channel Field. Channel is used by the input overrange event and the trigger
event. For the input overrange event, Channel indicates the index number of
the input channel that experienced an overrange signal. For the trigger event,
Channel indicates the index number for each input channel serving as a trigger
source.
The OverRange Field. OverRange is used by the input overrange event, and can be
On or Off. If OverRange is On, then the input channel experienced an overrange
signal. If OverRange is Off, then the input channel no longer experienced an
overrange signal.
The RelSample Field. RelSample is used by all events stored in EventLog to
indicate the sample number that was acquired when the event occurred.
RelSample is 0 for the start event and for the first trigger event regardless of
the trigger type. RelSample is NaN for any event that occurs before the first
trigger executes.
The String Field. String is used by the run-time error event to store the
descriptive message that is generated when a run-time error occurs. This
message is also displayed at the MATLAB command line.
The Trigger Field. Trigger is used by the trigger event to indicate the trigger
number. For example, if three trigger events occur, then Trigger is 3 for the
third trigger event. The total number of triggers executed is given by the
TriggersExecuted property.
5-50
Configuring Events and Actions
Example: Retrieving Event Information
Suppose you want to examine the events logged for the example given by
“Example: Voice Activation Using a Software Trigger” on page 5-23. You can do
this by accessing the EventLog property.
events = AIVoice.EventLog
events =
3x1 struct array with fields:
Type
Data
By examining the contents of the Type field, you can list the events that
occurred while AIVoice was running.
{events.Type}
ans =
'Start'
'Trigger'
'Stop'
To display information about the trigger event, you must access the Data field,
which stores the absolute time the trigger occurred, the number of samples
acquired when the trigger occurred, the index of the trigger channel, and the
trigger number.
trigdata = events(2).Data
trigdata =
AbsTime: [1999 4 15 18 12 5.8615]
RelSample: 0
Channel: 1
Trigger: 1
Alternatively, you can use the showdaqevents function to display event
information.
showdaqevents(events,2)
2 Trigger#1
( 18:12:05, 0 )
Channel: 1
5-51
5
Doing More with Analog Input
Creating and Executing Action Functions
When using action functions, you should be aware of these execution rules:
• Action functions execute in the order in which they are issued.
• All action functions except those associated with timer events are
guaranteed to execute.
• Action function execution may be delayed if the action involves a
CPU-intensive task such as updating a figure.
You can specify the action function to be executed when a specific event type
occurs by including the name of the M-file as the value for the associated action
property. For example, to execute the action function myaction for the analog
input object ai every time 1000 samples are acquired
ai.SamplesAcquiredActionCount = 1000;
ai.SamplesAcquiredAction = 'myaction';
M-file action functions require at least two input arguments. The first
argument is the device object. The second argument is a variable that captures
the event information given in Table 5-12, Analog Input Event Information
Stored in EventLog, on page 5-49. This event information pertains only to the
event that caused the action function to execute. The function header for
myaction is shown below.
function myaction(obj,event)
You can pass additional parameters to the action function by including them
as elements of a cell array. For example, to pass the MATLAB variable time to
myaction
time = datestr(now,0);
ai.SamplesAcquiredActionCount = 1000;
ai.SamplesAcquiredAction = {'myaction',time};
The corresponding function header is
function myaction(obj,event,time)
If you pass additional parameters to the action function, then they must be
included in the function header after the two required arguments.
5-52
Configuring Events and Actions
Specifying a Toolbox Function as an Action
In addition to specifying your own action function, you can specify the start,
stop, or trigger toolbox functions as actions. For example, to configure ai to
stop running when an overrange condition occurs
ai.InputOverRangeAction = 'stop';
Examples: Using Action Properties and Functions
This section provides examples that show you how to create action functions
and configure action properties.
Displaying Event Information with an Action Function
This example illustrates how action functions allow you to easily display event
information. The example uses daqaction to display information for trigger,
run-time error, and stop events. The default SampleRate and
SamplesPerTrigger values are used, which results in a 1-second acquisition for
each trigger executed.
You can run this example by typing daqdoc5_6 at the MATLAB command line.
1. Create a device object – Create the analog input object AI for a sound card.
The installed adaptors and hardware IDs are found with daqhwinfo.
AI = analoginput('winsound');
%AI = analoginput('nidaq',1);
%AI = analoginput('cbi',1);
2. Add channels – Add one hardware channel to AI.
chan = addchannel(AI,1);
%chan = addchannel(AI,0); % For NI and CBI
3. Configure property values – Repeat the trigger three times, find the time
for the acquisition to complete, and define daqaction as the M-file to execute
when a trigger, run-time error, or stop event occurs.
set(AI,'TriggerRepeat',3)
time = (AI.SamplesPerTrig/AI.SampleRate)*(AI.TriggerRepeat+1);
set(AI,'TriggerAction','daqaction')
set(AI,'RuntimeErrorAction','daqaction')
set(AI,'StopAction','daqaction')
5-53
5
Doing More with Analog Input
4. Acquire data – Start AI and wait for it to stop running. The pause command
allows the output from daqaction to be displayed.
start(AI)
pause(time+1)
5. Clean up – When you no longer need AI, you should remove it from memory
and from the MATLAB workspace.
delete(AI)
clear AI
Passing Additional Parameters to an Action Function
This example illustrates how additional arguments are passed to the action
function. Timer events are generated every 0.5 second to display data using the
action function daqdoc5_7plot.
You can run this example by typing daqdoc5_7 at the MATLAB command line.
1. Create a device object – Create the analog input object AI for a sound card.
The installed adaptors and hardware IDs are found with daqhwinfo.
AI = analoginput('winsound');
%AI = analoginput('nidaq',1);
%AI = analoginput('cbi',1);
2. Add channels – Add one hardware channel to AI.
chan = addchannel(AI,1);
%chan = addchannel(AI,0); % For NI and CBI
3. Configure property values – Define a 10-second acquisition and execute
the M-file daqdoc5_7plot every 0.5 seconds. Note that the variables bsize, P,
and T are passed to the action function.
duration = 10; % Ten second duration
set(AI,'SampleRate',22050)
ActualRate = get(AI,'SampleRate');
set(AI,'SamplesPerTrigger',duration*ActualRate)
set(AI,'TimerPeriod',0.5)
bsize = (AI.SampleRate)*(AI.TimerPeriod);
figure
P = plot(zeros(bsize,1));
T = title(['Number of action functions calls: ', num2str(0)]);
5-54
Configuring Events and Actions
xlabel('Samples'), ylabel('Signal (Volts)')
grid on
set(gcf,'doublebuffer','on')
set(AI,'TimerAction',{'daqdoc5_7plot',bsize,P,T})
4. Acquire data – Start AI. The drawnow command in daqdoc5_7plot forces
MATLAB to update the display.
start(AI)
pause(duration+0.5)
5. Clean up – When you no longer need AI, you should remove it from memory
and from the MATLAB workspace.
delete(AI)
clear AI
5-55
5
Doing More with Analog Input
Linearly Scaling the Data: Engineering Units
The Data Acquisition Toolbox provides you with a way to linearly scale analog
input signals from your sensor. You can associate this scaling with specific
engineering units such as volts or Newtons that you may want to apply to your
data. When specifying engineering units, there are three important
considerations:
• The expected data range produced by your sensor. This range depends on the
physical phenomena you are measuring and the maximum output range of
the sensor.
• The range of your analog input hardware. For many devices, this range is
specified by the gain and polarity. You can return valid input ranges with the
daqhwinfo function.
• The engineering units associated with your acquisition. By default, most
analog input hardware converts data to voltage values. However, after the
data is digitized, you may want to define a linear scaling that represents
specific engineering units when data is returned to MATLAB.
The properties associated with engineering units and linearly scaling acquired
data are given below.
Table 5-13: Analog Input Engineering Units Properties
Property Name
Description
SensorRange
Specify the range of data you expect from your sensor.
InputRange
Specify the range of the analog input subsystem.
Units
Specify the engineering units label.
UnitsRange
Specify the range of data as engineering units.
Note If supported by the hardware, you can set the engineering units
properties on a per-channel basis. Therefore, you can configure different
engineering unit conversions for each hardware channel.
5-56
Linearly Scaling the Data: Engineering Units
Linearly scaled acquired data is given by the formula
scaled value = (A/D value)(units range)/(sensor range)
Note The above formula assumes you are using symmetric units range and
sensor range values, and represents the simplest scenario. If your units range
or sensor range values are asymmetric, then you must also include the
appropriate offset in the formula.
The A/D value is constrained by the InputRange property, which reflects the
gain and polarity of your hardware channels, and is usually returned as a
voltage value. You should choose an input range that utilizes the maximum
dynamic range of your A/D subsystem. The best input range is the one that
most closely encompasses the expected sensor range. If the sensor signal is
larger than the input range, then the hardware will usually clip (saturate) the
signal.
The units range is given by the UnitsRange property, while the sensor range is
given by the SensorRange property. UnitsRange is specified as a voltage value,
while SensorRange is specified as an engineering unit such as Newtons or g’s
(1 g = 9.80 m/s/s). These property values control the scaling of data when it is
extracted from the engine with the getdata function. You can find the
appropriate units range and sensor range from your sensor’s specification
sheet.
For example, suppose SensorRange is [-1 1] and UnitsRange is [-10 10]. If
an A/D value is 2.5, then the scaled value is (2.5)(20/2) or 25, in the appropriate
units.
Example: Performing a Linear Conversion
This example illustrates how to configure the engineering units properties for
an analog input object connected to a National Instruments PCI-6024E board.
An accelerometer is connected to a device which is undergoing a vibration test.
Your job is to measure the acceleration and the frequency components of the
device while it is vibrating. The accelerometer has a range of ±50 g’s, a voltage
sensitivity of 99.7 mV/g, and a resolution of 0.00016 g.
5-57
5
Doing More with Analog Input
The accelerometer signal is input to a Tektronix TDS 210 digital oscilloscope,
and to channel 0 of the data acquisition board. By observing the signal on the
scope, the maximum expected range of data from the sensor is ±200 mV, which
corresponds to approximately ±2 g’s. Given this constraint, you should
configure the board’s input range to the ±500 mV, which is the closest input
range that encompasses the expected data range.
You can run this example by typing daqdoc5_8 at the MATLAB command line.
1. Create a device object – Create the analog input object AI for a National
Instruments board. The installed adaptors and hardware IDs are found with
daqhwinfo.
AI = analoginput('nidaq',1);
2. Add channels – Add one hardware channel to AI.
chan = addchannel(AI,0);
3. Configure property values – Configure the sampling rate to 200 kHz and
define a two second acquisition.
duration = 2;
ActualRate = setverify(AI,'SampleRate',200000);
set(AI,'SamplesPerTrigger',duration*ActualRate)
Configure the engineering units properties. This example assumes you are
using a National Instruments PCI-6024E board or an equivalent hardware
device. SensorRange is set to the maximum accelerometer range in volts, and
UnitsRange is set to the corresponding range in g’s.
set(chan,'SensorRange',[-5 5])
set(chan,'InputRange',[-0.5 0.5])
set(chan,'UnitsRange',[-50 50])
set(chan,'Units','g''s (1g = 9.80 m/s/s)')
4. Acquire data – Start the acquisition and wait until all the data is acquired.
start(AI)
while strcmp(AI.Running,'On')
end
5-58
Linearly Scaling the Data: Engineering Units
Extract and plot all the acquired data.
data = getdata(AI);
subplot(2,1,1),plot(data)
Calculate and display the frequency information.
Fs = ActualRate;
blocksize = duration*ActualRate;
[f,mag]= daqdocfft(data,Fs,blocksize);
subplot(2,1,2),plot(f,mag)
5. Clean up – When you no longer need AI, you should remove it from memory
and from the MATLAB workspace.
delete(AI)
clear AI
5-59
5
Doing More with Analog Input
5-60
6
Analog Output
Overview
. . . . . . . . . . . . . . . . . . . . . 6-2
Getting Started with Analog Output . .
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
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 6-3
. 6-3
. 6-4
. 6-6
. 6-9
. 6-10
. 6-14
Managing Output Data . . . . . . . . . . . . . . . 6-17
Queuing Data with putdata . . . . . . . . . . . . . . 6-17
Example: Queuing Data with putdata . . . . . . . . . . 6-19
Configuring Analog Output Triggers
Defining a Trigger: Trigger Types . . .
Executing the Trigger . . . . . . . .
How Many Triggers Occurred? . . . .
When Did the Trigger Occur? . . . . .
Device-Specific Hardware Triggers . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
6-21
6-22
6-23
6-23
6-24
6-25
Configuring Events and Actions . . . . . . . . .
Event Types . . . . . . . . . . . . . . . . . . .
Recording and Retrieving Event Information . . . . .
Examples: Using Action Properties and Action Functions
.
.
.
.
.
.
.
.
6-27
6-27
6-29
6-31
Linearly Scaling the Data: Engineering Units . . . . . 6-34
Example: Performing a Linear Conversion . . . . . . . . 6-35
Starting Multiple Device Objects
. . . . . . . . . . 6-37
6
Analog Output
Overview
Analog output subsystems convert digital data stored on your computer to a
real-world analog signal. These devices perform the inverse conversion of
analog input subsystems. Typical plug-in acquisition boards offer two output
channels with 12 bits of resolution, with special hardware available to support
multiple channel analog output operations. The Data Acquisition Toolbox
provides access to analog output subsystems through an analog output object.
The purpose of this chapter is to show you how to perform data acquisition
tasks using your analog output hardware. Topics include:
• Getting started with analog output
• Managing output data
• Configuring analog output triggers
• Configuring events and actions
• Linearly scaling the data
• Starting multiple device objects
6-2
Getting Started with Analog Output
Getting Started with Analog Output
The purpose of this section is to show you how to use the Data Acquisition
Toolbox to perform basic tasks with your analog output (AO) hardware. This is
accomplished by describing the most important properties and functions
required for an analog output data acquisition session. In addition, several
device-specific examples are provided as well as ways to evaluate the status of
the analog output object.
After reading this section, you will be able to perform basic analog output tasks
suited to your own data acquisition applications.
Creating an 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 Hardware Driver
Adaptor” on page 2-7. The device ID refers to the number associated with your
board when it is installed. 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',1);
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
ao
Size
Bytes
1x1
1334
Class
analogoutput object
Grand total is 53 elements using 1334 bytes
6-3
6
Analog Output
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 =
'nidaq1-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 “Adding Channels or Lines” on page 3-8, 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 MATLAB Indices” on page 3-9, a channel
group consists of a mapping between hardware channel IDs and MATLAB
indices (see below).
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);
6-4
Getting Started with Analog Output
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
chans
Size
2x1
Bytes
512
Class
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” on page 4-6, 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” on page 4-6 for more information.
6-5
6
Analog Output
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” on page 3-12, the Data Acquisition Toolbox 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',1);
addchannel(ao,0:1);
set(ao,'SampleRate',100000)
6-6
Getting Started with Analog Output
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 in Chapter 10, “Base Property
Reference.”
• 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
Chapter 11, “Device-Specific Property Reference” 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
6-7
6
Analog Output
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” on page 6-25, or the TriggerType
reference pages in Chapter 10, “Base Property Reference.”
6-8
Getting Started with Analog Output
Outputting 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
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” on page 6-17 and in Chapter 9, “Function Reference.”
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” on page 6-8
and “Configuring Analog Output Triggers” on page 6-21.
6-9
6
Analog Output
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 timeout 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. 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.
6-10
Getting Started with Analog Output
Outputting Data with a Sound Card
In this example, sine wave data is generated in MATLAB, output to the D/A
converter on the sound card, and sent to a speaker. The setup is shown below.
Data Source
D/A Converter
MATLAB
variable
D/A
Speaker
You can run this example by typing daqdoc6_1 at the MATLAB command line.
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,len))';
putdata(AO,data)
6-11
6
Analog Output
4. Output data – Start AO, issue a manual trigger, and wait for the device object
to stop running.
start(AO)
trigger(AO)
while strcmp(AO.Running,'On')
end
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 MATLAB, output to the D/A
converter on a National Instruments board, and displayed with an oscilloscope.
The setup is shown below.
Data Source
D/A Converter
MATLAB
variable
Scope
D/A
You can run this example by typing daqdoc6_2 at the MATLAB command line.
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',1);
2. Add channels – Add one channel to AO.
chan = addchannel(AO,0);
6-12
Getting Started with Analog Output
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,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)
while strcmp(AO.Running,'On')
end
5. Clean up – When you no longer need AO, you should remove it from memory
and from the MATLAB workspace.
delete(AO)
clear AO
6-13
6
Analog Output
Evaluating the Analog Output Object Status
You can evaluate the status of an analog output 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,
6-14
Getting Started with Analog Output
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 the analog output object at the
command line. The information displayed reflects many of the basic setup
properties described in “Configuring Analog Output Properties” on page 6-6,
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
6-15
6
Analog Output
The display summary shown below is for the example given in “Outputting
Data with a Sound Card” on page 6-11 prior to issuing the start function.
Display Summary of Analog Output (AO) Object Using 'AudioPCI Playback'.
Output Parameters:
8000 samples per second on each channel.
Trigger Parameters:
General display
summary
1 'Immediate' trigger on START.
Engine status:
Waiting for START.
0 total sec. of data currently queued for START
0 samples currently queued by PUTDATA.
0 samples sent to output device since START.
AO object contains channel(s):
Channel display
summary
Index:
ChannelName:
HwChannel:
OutputRange:
UnitsRange:
Units:
1
'Mono'
1
[-1 1]
[-1 1]
'Volts
You can use the Channel property to display only the channel summary
information.
AO.Channel
6-16
Managing Output Data
Managing Output Data
At the core of any analog output application lies the data you want to send from
a computer to an output device such as an actuator. The role of the analog
output subsystem is to convert digitized data to analog data for subsequent
output.
Before you can output data to the analog output subsystem, it must be queued
in the engine. Queuing data is managed with the putdata function. In addition
to this function, there are several properties associated with managing output
data. These properties are given below.
Table 6-6: Analog Output Data Management Properties
Property Name
Description
MaxSamplesQueued
Indicate the maximum number of samples that can
be queued in the engine.
RepeatOutput
Specify the number of additional times queued data
is output.
Timeout
Specify an additional waiting time to queue data.
Queuing Data with putdata
Before data can be sent to the analog output hardware, you must queue it in
the engine. Queuing data is managed with the putdata function. One column
of data is required for each channel contained by the analog output object. 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])
6-17
6
Analog Output
A data source consisting of m samples and n channels is illustrated below.
d11 d12
d1n
d21 d22
d2n
d31 d32 ... d3n
.
.
.
.
.
.
dm1 dm2
.
.
.
Data source. Each column represents
a separate output channel.
dmn
Rules for Using putdata
Using putdata to queue data in the engine follows these rules:
• You must queue data in the engine before starting the analog output object.
• If the value of the RepeatOutput property is greater than 0, then all queued
data is automatically requeued until the RepeatOutput value is reached. You
must configure RepeatOutput before start is issued.
• While the analog output object is running, you can continue to queue data
unless RepeatOutput is greater than 0.
• You can queue data in the engine until the value specified by the
MaxSamplesQueued property is reached, or the limitations of your hardware
or computer are reached.
For more information about putdata, refer to its reference pages in Chapter 9,
“Function Reference.”
Rules for Queuing Data
Data to be queued in the engine follows these rules:
• Data is output as soon as a trigger occurs.
• An error is returned if a NaN is included in the data stream.
6-18
Managing Output Data
• You can use the native data type of the hardware. Note that MATLAB
supports math operations only for the double data type. Therefore, to use
math functions on native data, you must convert it to doubles.
• If the data is not within the range of the UnitsRange property, then it is
clipped to the maximum or minimum value specified by UnitsRange. Refer
to “Linearly Scaling the Data: Engineering Units” on page 6-34 for more
information about clipping.
Example: Queuing Data with putdata
This example illustrates how you can use putdata to queue 8000 samples, and
then output the data a total of five times using the RepeatOutput property.
You can run this example by typing daqdoc6_3 at the MATLAB command line.
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');
%AO = analogoutput('nidaq',1);
%AO = analogoutput('cbi',1);
2. Add channels – Add one channel to AO.
chans = addchannel(AO,1);
%chans = addchannel(AO,0); % For NI and CBI
3. Configure property values – Define an output time of one second, assign
values to the basic setup properties, generate data to be queued, and issue two
putdata calls. Since the queued data is repeated four times and two putdata
calls are issued, a total of 10 seconds of data is output.
duration = 1;
set(AO,'SampleRate',8000)
ActualRate = get(AO,'SampleRate');
len = ActualRate*duration;
set(AO,'RepeatOutput',4)
data = sin(linspace(0,2*pi,len))';
putdata(AO,data)
putdata(AO,data)
6-19
6
Analog Output
4. Output data – Start AO and wait for the device object to stop running.
start(AO)
while strcmp(AO.Running,'On')
end
5. Clean up – When you no longer need AO, you should remove it from memory
and from the MATLAB workspace.
delete(AO)
clear AO
6-20
Configuring Analog Output Triggers
Configuring Analog Output Triggers
An analog output trigger is defined as an event that initiates the output of
data. As shown in the figure below, when a trigger occurs, the Sending property
is automatically set to On and queued data is output from the engine to the
hardware subsystem.
Sending = Off
Sending = On
Time
Queue data
in engine
Trigger occurs
Output data
to hardware
Properties associated with analog output triggers are given below.
Table 6-7: Analog Output Trigger Properties
Property Name
Description
InitialTriggerTime
Indicate the absolute time of the first trigger.
TriggerAction
Specify the M-file action function to execute when
a trigger occurs.
TriggersExecuted
Indicate the number of triggers that execute.
TriggerType
Specify the type of trigger to execute.
Except for TriggerAction, these trigger-related properties are discussed in the
following sections. TriggerAction is discussed in “Configuring Events and
Actions” on page 6-27.
6-21
6
Analog Output
Defining a Trigger: Trigger Types
Defining a trigger for an analog output object involves specifying the trigger
type with the TriggerType property. You can think of the trigger type as the
source of the trigger. The analog output TriggerType values are given below.
Table 6-8: Analog Output TriggerType Property Values
TriggerType Value
Description
{Immediate}
The trigger occurs just after you issue the start
function.
Manual
The trigger occurs just after you manually issue the
trigger function.
Trigger types can be grouped into two main categories:
• Device-independent triggers
• Device-specific hardware triggers
The trigger types shown above are device-independent triggers since they are
available for all supported hardware. For these trigger types, the action that
initiates the trigger event involves issuing a toolbox function (start or
trigger). Conversely, device-specific hardware triggers depend on the specific
hardware device you are using. For these trigger types, the action that initiates
the trigger event involves an external digital signal.
Device-specific hardware triggers for National Instruments and Agilent
Technologies devices are discussed in “Device-Specific Hardware Triggers” on
page 6-25. Device-independent triggers are discussed below.
Immediate Trigger. If TriggerType is Immediate (the default value), the trigger
occurs immediately after the start function is issued. You can configure an
analog output object for continuous output, by using an immediate trigger and
setting RepeatOutput to inf.
Manual Trigger. If TriggerType is Manual, the trigger occurs immediately after
the trigger function is issued.
6-22
Configuring Analog Output Triggers
Executing the Trigger
For an analog output trigger to occur, you must follow these steps:
1 Queue data in the engine.
2 Configure the appropriate trigger properties.
3 Issue the start function.
4 Issue the trigger function if TriggerType is Manual.
Once the trigger occurs, queued data is output to the hardware, and the device
object stops executing when all the queued data is output.
Note Only one trigger event can occur for analog output objects.
How Many Triggers Occurred?
For analog output objects, only one trigger can occur. You can determine if the
trigger event occurred by returning the value of the TriggersExecuted
property. If TriggersExecuted is 0, then the trigger event did not occur. If
TriggersExecuted is 1, then the trigger event occurred. Event information is
also recorded by the EventLog property. A convenient way to access event log
information is with the showdaqevents function.
For example, suppose you create the analog output object ao for a sound card
and add one channel to it. ao is configured to output 8,000 samples using the
default sampling rate of 8000 Hz.
ao = analogoutput('winsound');
addchannel(ao,1);
data = sin(linspace(0,1,8000))';
putdata(ao,data)
start(ao)
6-23
6
Analog Output
TriggersExecuted returns the number of triggers executed.
ao.TriggersExecuted
ans =
1
You can use showdaqevents to return information for all events that occurred
while ao was executing.
showdaqevents(ao)
1 Start
2 Trigger
3 Stop
( 10:43:25, 0 )
( 10:43:25, 0 )
( 10:43:26, 8000 )
For more information about recording and retrieving event information, refer
to “Recording and Retrieving Event Information” on page 6-29.
When Did the Trigger Occur?
You can return the absolute time of the trigger with the InitialTriggerTime
property. Absolute time is returned as a clock vector in the form
[year month day hour minute seconds]
For example, the absolute time of the trigger event for the preceding example is
abstime = ao.InitialTriggerTime
abstime =
1.0e+003 *
1.9990
0.0040
0.0170
0.0100
0.0430
0.0252
To convert the clock vector to a more convenient form, you can use the sprintf
function.
t = fix(abstime);
sprintf('%d:%d:%d', t(4),t(5),t(6))
ans =
10:43:25
As shown in the preceding section, you can also evaluate the absolute time of
the trigger event with the showdaqevents function.
6-24
Configuring Analog Output Triggers
Device-Specific Hardware Triggers
Most data acquisition devices possess the ability to accept a hardware trigger.
Hardware triggers are processed directly by the hardware and are typically
transistor-transistor logic (TTL) signals. Hardware triggers are used when
speed is required since a hardware device can process an input signal much
faster than software.
The device-specific hardware triggers are presented to you as additional
property values. Hardware triggers for National Instruments and Agilent
Technologies devices are discussed below and in Chapter 10, “Base Property
Reference.”
Note that the available hardware trigger support depends on the board you are
using. Refer to your hardware documentation for detailed information about its
triggering capabilities.
National Instruments
When using National Instruments hardware, there is an additional analog
output trigger type available to you: digital triggering.
If TriggerType is set to HwDigital, the trigger is given by an external TTL
signal that is input directly into the hardware device. The following example
illustrates how to configure a hardware digital trigger.
ao = analogoutput('nidaq',1);
addchannel(ao,0:1);
set(ao,'TriggerType','HwDigital')
With this trigger configuration, ao will not start outputting data until the TTL
signal is detected by the hardware on the appropriate pin.
6-25
6
Analog Output
The diagram below illustrates how you can connect a digital trigger signal to
an MIO-16E Series board. PFI6/WFTRIG corresponds to pin 5.
TTL signal
D/A
PFI6/WFTRIG
MIO-16E Series board
Agilent Technologies
When using Agilent Technologies hardware, there are additional analog output
trigger types that you must be aware of: digital triggering on a positive edge
and digital triggering on a negative edge.
If TriggerType is HwDigitalPos, the trigger source is the positive edge of a
digital signal. If TriggerType is HwDigitalNeg, the trigger source is the
negative edge of a digital signal.
In both cases, the digital signal is an external TTL signal that is input directly
into the hardware device. The example below illustrates how to configure such
a trigger.
ao = analogoutput('hpe1432',8);
addchannel(ao,1);
set(ao,'TriggerType','HwDigitalPos')
With this trigger configuration, ao will not start outputting data until the TTL
signal is detected by the hardware.
6-26
Configuring Events and Actions
Configuring Events and Actions
You can enhance the power and flexibility of your analog output application by
utilizing events. An event occurs at a particular time after a condition is met
and may result in one or more actions.
While the analog output object is running, you can use events to display a
message, display data, analyze data, or perform just about any other action.
Actions are controlled through action properties and action functions. All event
types have an associated action property. Action functions are M-file functions
that you construct to suit your specific data acquisition needs.
You execute an action when a particular event occurs by specifying the name
of the M-file action function as the value for the associated action property.
Refer to “Creating and Executing Action Functions” on page 5-52 to learn how
to create action functions. Note that daqaction is the default value for some
action properties.
Event Types
The analog output event types and associated action properties are described
below.
Table 6-9: Analog Output Action Properties
Event Type
Property Name
Run-time error
RuntimeErrorAction
Samples output
SamplesOutputAction
SamplesOutputActionCount
Start
StartAction
Stop
StopAction
Timer
TimerAction
TimerPeriod
Trigger
TriggerAction
6-27
6
Analog Output
Run-time Error Event. A run-time error event is generated immediately after a
run-time error occurs. This event executes the action function specified for
RuntimeErrorAction. Additionally, a toolbox error message is automatically
displayed to the MATLAB workspace. If an error occurs that is not explicitly
handled by the toolbox, then the hardware-specific error message is displayed.
The default value for RunTimeErrorAction is daqaction, which displays the
event type, the time the event occurred, the device object name, and the error
message.
Run-time errors include hardware errors and timeouts. Run-time errors do not
include configuration errors such as setting an invalid property value.
Samples Output Event. A samples output event is generated immediately after the
number of samples specified by the SamplesOutputActionCount property is
output for each channel group member. This event executes the action function
specified for SamplesOutputAction.
Start Event. A start event is generated immediately after the start function is
issued. This event executes the action function specified for StartAction.
When the action function has finished executing, Running is automatically set
to On and the device object and hardware device begin executing.
Stop Event. A stop event is generated immediately after the device object and
hardware device stop running. This occurs when:
• The stop function is issued.
• The requested number of samples is output.
• A run-time error occurs.
A stop event executes the action function specified for StopAction. Under most
circumstances, the action function is not guaranteed to complete execution
until sometime after the device object and hardware device stop running, and
the Running property is set to Off.
Timer Event. A timer event is generated whenever the time specified by the
TimerPeriod property passes. This event executes the action function specified
for TimerAction. Time is measured relative to when the device object starts
running.
Some timer events may not be processed if your system is significantly slowed
or if the TimerPeriod value is too small. For example, a common application for
6-28
Configuring Events and Actions
timer events is to display data. However, since displaying data is a
CPU-intensive task, some of these events may be dropped. To guarantee that
events are not dropped, you may want to use the SamplesOutputAction
property.
Trigger Event. A trigger event is generated immediately after a trigger occurs.
This event executes the action function specified for TriggerAction. Under
most circumstances, the action function is not guaranteed to complete
execution until sometime after Sending is set to On.
Recording and Retrieving Event Information
While the analog output object is running, certain information is automatically
recorded in the EventLog property for some of the event types listed in the
preceding section. EventLog is a structure that contains two fields: Type and
Data. The Type field contains the event type. The Data field contains
event-specific information. Events are recorded in the order in which they
occur. The first EventLog entry reflects the first event recorded, the second
EventLog entry reflects the second event recorded, and so on.
The event types recorded in EventLog for analog output objects, as well as the
values for the Type and Data fields, are given below.
Table 6-10: Analog Output Event Information Stored in EventLog
Event Type
Type Field Value
Data Field Value
Run-time error
Error
AbsTime
RelSample
String
Start
Start
AbsTime
RelSample
Stop
Stop
AbsTime
RelSample
Trigger
Trigger
AbsTime
RelSample
6-29
6
Analog Output
Samples output events and timer events are not stored in EventLog.
Note Unless a run-time error occurs, EventLog records a start event, a
trigger event, and stop event for each data acquisition session.
The Data field values are described below.
The AbsTime Field. AbsTime is used by all analog output events stored in
EventLog to indicate the absolute time the event occurred. The absolute time
is returned using MATLAB’s clock format.
day-month-year hour:minute:second
The RelSample Field. RelSample is used by all events stored in EventLog to
indicate the sample number that was output when the event occurred.
RelSample is 0 for the start event and for the first trigger event regardless of
the trigger type. RelSample is NaN for any event that occurs before the trigger
executes.
The String Field. String is used by the run-time error event to store the
descriptive message that is generated when a run-time error occurs. This
message is also displayed at the MATLAB command line.
Example: Retrieving Event Information
Suppose you want to examine the events logged for the example given by
“Example: Queuing Data with putdata” on page 6-19. You can do this by
accessing the EventLog property.
events = AO.EventLog
events =
3x1 struct array with fields:
Type
Data
By examining the contents of the Type field, you can list the events that were
recorded while AO was running.
{events.Type}
ans =
'Start'
6-30
'Trigger'
'Stop'
Configuring Events and Actions
To display information about the trigger event, you must access the Data field
which stores the absolute time the trigger occurred and the number of samples
output when the trigger occurred.
trigdata = events(2).Data
trigdata =
AbsTime: [1999 4 16 9 53 19.9508]
RelSample: 0
Alternatively, you can use the showdaqevents function to display event
information.
showdaqevents(events,2)
2 Trigger
( 09:53:19, 0 )
Examples: Using Action Properties and Action
Functions
Examples showing how to create action functions and configure action
properties are given below.
Displaying the Number of Samples Output
This example illustrates how to generate samples output events. You can run
this example by typing daqdoc6_4 at the MATLAB command line. The
daqdoc6_4disp action function displays the number of events that were output
from the engine whenever the samples output event occurred.
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');
%AO = analogoutput('nidaq',1);
%AO = analogoutput('cbi',1);
2. Add channels – Add two channels to AO.
chans = addchannel(AO,1:2);
%chans = addchannel(AO,0:1); % For NI and CBI
6-31
6
Analog Output
3. Configure property values – Configure the trigger to repeat four times,
specify daqdoc6_4disp as the M-file action function to execute whenever 8000
samples are output, generate data to be queued, and queue the data with one
call to putdata.
set(AO,'SampleRate',8000)
ActualRate = get(AO,'SampleRate');
set(AO,'RepeatOutput',4)
set(AO,'SamplesOutputActionCount',8000)
freq = get(AO,'SamplesOutputActionCount');
set(AO,'SamplesOutputAction','daqdoc6_4disp')
data = sin(linspace(0,2*pi,3*freq))';
putdata(AO,[data data])
4. Output data – Start AO.
start(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
Displaying EventLog Information
This example illustrates how action functions allow you to easily display
information stored in the EventLog property. You can run this example by
typing daqdoc6_5 at the MATLAB command line. The daqdoc6_5disp action
function displays the absolute time and relative sample associated with the
start, trigger, and stop events.
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');
%AO = analogoutput('nidaq',1);
%AO = analogoutput('cbi',1);
2. Add channels – Add one channel to AO.
chan = addchannel(AO,1);
%chan = addchannel(AO,0); % For NI and CBI
6-32
Configuring Events and Actions
3. Configure property values – Specify daqdoc6_5disp as the M-file action
function to execute when the start, trigger, and stop events occur, generate
data to be queued, and queue the data with one call to putdata.
set(AO,'SampleRate',8000)
ActualRate = get(AO,'SampleRate');
set(AO,'StartAction','daqdoc6_5disp')
set(AO,'TriggerAction','daqdoc6_5disp')
set(AO,'StopAction','daqdoc6_5disp')
data = sin(linspace(0,2*pi,ActualRate));
data = [data data data];
time = (length(data)/AO.SampleRate);
putdata(AO,data')
4. Output data – Start AO.
start(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
6-33
6
Analog Output
Linearly Scaling the Data: Engineering Units
The Data Acquisition Toolbox provides you with a way to linearly scale data as
it is being queued in the engine. You can associate this scaling with specific
engineering units such as volts or Newtons that you may want to apply to your
data.
The properties associated with engineering units and linearly scaling output
data are given below.
Table 6-11: Analog Output Engineering Units Properties
Property Name
Description
OutputRange
Specify the range of the analog output hardware
subsystem.
Units
Specify the engineering units label.
UnitsRange
Specify the range of data as engineering units.
For many devices, the output range is expressed in terms of the gain and
polarity.
Note You can set the engineering units properties on a per-channel basis.
Therefore, you can configure different engineering unit conversions for each
hardware channel.
Linearly scaled output data is given by the formula
scaled value = (original value)(output range)/(units range)
The units range is given by the UnitsRange property, while the output range is
given by the OutputRange property. UnitsRange controls the scaling of data
when it is queued in the engine with the putdata function. OutputRange
specifies the gain and polarity of your D/A subsystem. You should choose an
output range that encompasses the output signal, and that utilizes the
maximum dynamic range of your hardware.
6-34
Linearly Scaling the Data: Engineering Units
For sound cards, you may have to adjust the volume control to obtain the
full-scale output range of the device. Refer to “Troubleshooting Sound Cards”
on page A-12 to learn how to access the volume control for your sound card.
For example, suppose OutputRange is [-10 10], and UnitsRange is [-5 5]. If
a queued value is 2.5, then the scaled value is (2.5)(20/10) or 5, in the
appropriate units.
Note The data acquisition engine always clips out-of-range values. Clipping
means that an out-of-range value is fixed to either the minimum or maximum
value that is representable by the hardware. Clipping is equivalent to
saturation.
Example: Performing a Linear Conversion
This example illustrates how to configure the engineering units properties for
an analog output object connected to a National Instruments PCI-6024E board.
The queued data consists of a 4 volt peak-to-peak sine wave. The UnitsRange
property is configured so that queued data is scaled to the OutputRange
property value, which is fixed at ±10 volts. This scaling utilizes the maximum
dynamic range of the analog output hardware.
You can run this example by typing daqdoc6_6 at the MATLAB command line.
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',1);
2. Add channels – Add one hardware channel to AO.
chan = addchannel(AO,0);
3. Configure property values – Create the data to be queued.
freq = 2;
w = 2*pi*freq;
t = linspace(0,10,10000);
data = 2*sin(w*t)';
6-35
6
Analog Output
Configure the sampling rate to 2 kHz, configure the trigger to repeat two times,
and scale the data to cover the full output range of the D/A converter. Since the
peak-to-peak amplitude of the queued data is 4, UnitsRange is set to [-2 2],
which scales the output data to 20 volts peak-to-peak.
set(AO,'SampleRate',2000)
set(AO,'RepeatOutput',2)
set(chan,'UnitsRange',[-2 2])
Queue the data with one call to putdata.
putdata(AO,data)
4. Output data – Start AO and wait until all the data is output.
start(AO)
while strcmp(AO.Running,'On')
end
5. Clean up – When you no longer need AO, you should remove it from memory
and from the MATLAB workspace.
delete(AO)
clear AO
6-36
Starting Multiple Device Objects
Starting Multiple Device Objects
With the Data Acquisition Toolbox, you can start multiple device objects. You
may find this feature useful when simultaneously using your hardware’s
analog output (AO) and analog input (AI) subsystems. For example, suppose
you create the analog input object ai and the analog output object ao for a
sound card, and add one channel to each device object.
ai = analoginput('winsound');
addchannel(ai,1);
ao = analogoutput('winsound');
addchannel(ao,1);
You should use manual triggers when starting multiple device objects since
this trigger type executes faster than other trigger types with the exception of
hardware triggers. Additionally, to synchronize the input and output of data,
you should configure the ManualTriggerHwOn property to Trigger for ai.
set([ai ao],'TriggerType','Manual')
set(ai,'ManualTriggerHwOn','Trigger')
Configure ai for continuous acquisition, call the action function qmoredata
whenever 1000 samples are output, and call daqaction when ai and ao stop
running.
set(ai,'SamplesPerTrigger',inf)
set(ao,'SamplesOutputAction',{'qmoredata',ai})
set(ao,'SamplesOutputActionCount',1000)
set([ai ao],'StopAction','daqaction')
As shown below, the action function qmoredata extracts data from the engine
and then queues it for output.
function qmoredata(obj,event,ai)
data = getdata(ai,1000);
putdata(obj,data)
6-37
6
Analog Output
Queue data in the engine, start the device objects, and execute the manual
triggers.
data = zeros(4000,1);
putdata(ao,data)
start([ai ao])
trigger([ai ao])
Note Device objects cannot execute simultaneously unless you use an
external hardware trigger.
You can determine the starting time for each device object with the
InitialTriggerTime property. The difference, in seconds, between the
starting times for ai and ao is
aitime = ai.InitialTriggerTime
aotime = ao.InitialTriggerTime
delta = abs(aotime - aitime);
sprintf('%d',delta(6))
ans =
2.288818e-005
Note that this number depends on the specific platform you are using. To stop
both device objects
stop([ai ao])
The output from daqaction is shown below.
Stop event occurred at 13:00:25 for the object: winsound0-AO.
Stop event occurred at 13:00:25 for the object: winsound0-AI.
6-38
7
Digital Input/Output
Overview
. . . . . . . . . . . . . . . . . . . . . 7-2
Creating a Digital I/O Object
. . . . . . . . . . . . 7-3
Adding Lines to a Digital I/O Object . . . . . . . . . 7-4
Line and Port Characteristics . . . . . . . . . . . . . 7-5
Referencing Individual Hardware Lines . . . . . . . . . 7-8
Writing and Reading Digital I/O Line Values
Writing Digital Values . . . . . . . . . . .
Reading Digital Values . . . . . . . . . . .
Example: Writing and Reading Digital Values . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Generating Timer Events . . . . . .
Timer Events . . . . . . . . . . . .
Starting and Stopping a Digital I/O Object
Example: Generating Timer Events . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 7-15
. 7-15
. 7-16
. 7-17
.
.
.
.
.
.
.
.
.
.
.
.
7-10
7-10
7-12
7-13
Evaluating the Digital I/O Object Status . . . . . . . 7-18
The Display Summary . . . . . . . . . . . . . . . . 7-18
7
Digital Input/Output
Overview
Digital I/O (DIO) subsystems are designed to input and output digital values
to and from hardware. These values are typically handled either as single bits
or lines, or as a port, which typically consists of eight lines. While most popular
data acquisition boards include some digital I/O capability, it is usually limited
to simple operations and special dedicated hardware is required for performing
advanced digital I/O operations. The Data Acquisition Toolbox provides access
to digital I/O subsystems through a digital I/O object.
Note The Data Acquisition Toolbox does not directly support buffered digital
I/O or handshaking (latching). However, you can write your own M-code to
support this functionality. Buffered digital I/O means that the data associated
with a digital I/O subsystem is stored in the engine. Handshaking allows your
digital I/O subsystem to input or output data after receiving a digital pulse.
The purpose of this chapter is to show you how to perform data acquisition
tasks using your digital I/O hardware. Topics include:
• Creating a digital I/O object
• Adding lines to a digital I/O object
• Writing and reading digital I/O line values
• Generating timer events
• Evaluating the digital I/O object status
7-2
Creating a Digital I/O Object
Creating a Digital I/O Object
You create a digital I/O object with the digitalio function. digitalio accepts
the adaptor name and the hardware device ID as input arguments. For a list
of supported adaptors, refer to “The Hardware Driver Adaptor” on page 2-7.
The device ID refers to the number associated with your board when it is
installed. Some vendors refer to the device ID as the device number or the
board number. Use the daqhwinfo function to determine the available adaptors
and device IDs.
Each digital I/O object is associated with one board and one digital I/O
subsystem. For example, to create a digital I/O object associated with a
National Instruments board with device ID 1
dio = digitalio('nidaq',1);
The digital I/O object dio now exists in the MATLAB workspace. You can
display the class of dio with the whos command.
whos dio
Name
Size
Bytes
dio
1x1
1308
Class
digitalio object
Grand total is 40 elements using 1308 bytes
Once the digital I/O 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 Digital I/O 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 dio with the get function.
get(dio,{'Name','Type'})
ans =
'nidaq1-DIO'
'Digital IO
7-3
7
Digital Input/Output
Adding Lines to a Digital I/O Object
After creating the digital I/O object, you must add lines to it. As shown by the
figure in “Adding Channels or Lines” on page 3-8, you can think of a device
object as a container for lines. The collection of lines contained by the device
object is referred to as a line group. A line group consists of a mapping between
hardware line IDs and MATLAB indices (see below).
When adding lines to a digital I/O object, you must follow these rules:
• The lines must reside on the same hardware device. You cannot add lines
from different devices, or from different subsystems on the same device.
• You can add a line only once to a given digital I/O object. However, a line can
be added to as many different digital I/O objects as you desire.
• You can add lines that reside on different ports to a given digital I/O object.
You add lines to a digital I/O object with the addline function. addline
requires the device object, at least one hardware line ID, and the direction
(input or output) of each added line as input arguments. You can optionally
specify port IDs, descriptive line names, and an output argument. For example,
to add eight output lines from port 0 to the device object dio created in the
preceding section
hwlines = addline(dio,0:7,'out');
The output argument hwlines is a line object that reflects the line array
contained by dio. You can display the class of hwlines with the whos command.
whos hwlines
Name
hwlines
Size
8x1
Bytes
536
Class
dioline object
Grand total is 13 elements using 536 bytes
You can use hwlines to easily access lines. For example, you can easily
configure or return property values for one or more lines. As described in XXX,
you can also access lines with the Line property.
7-4
Adding Lines to a Digital I/O Object
Once you add lines to a digital I/O object, the properties listed below are
automatically assigned values. These properties provide descriptive
information about the lines based on their class type and ID.
Table 7-2: Descriptive Digital I/O Line Properties
Property Name
Description
HwLine
Specify the hardware line ID.
Index
Indicate the MATLAB index of a hardware line.
Parent
Indicate the parent (device object) of a line.
Type
Indicate a line.
You can display the values of these properties for chans with the get function.
get(hwlines,{'HwLine','Index','Parent','Type'})
ans =
[0]
[1]
[1x1 digitalio]
'Line'
[1]
[2]
[1x1 digitalio]
'Line'
[2]
[3]
[1x1 digitalio]
'Line'
[3]
[4]
[1x1 digitalio]
'Line'
[4]
[5]
[1x1 digitalio]
'Line'
[5]
[6]
[1x1 digitalio]
'Line'
[6]
[7]
[1x1 digitalio]
'Line'
[7]
[8]
[1x1 digitalio]
'Line'
Line and Port Characteristics
As described in the preceding section, when you add lines to a digital I/O object,
they must be configured for either input or output. You read values from an
input line and write values to an output line. Whether a given hardware line is
addressable for input or output depends on the port is resides on. You can
classify digital I/O ports into these two groups based on your ability to address
lines individually:
• Port-configurable devices – You cannot address the lines associated with a
port-configurable device individually. This means that you must configure
7-5
7
Digital Input/Output
all the lines for either input or output. If you attempt to mix the two
configurations, an error is returned.
You can add any number of available port-configurable lines to a digital I/O
object. However, the engine will address all lines behind the scenes. For
example, if one line is added to a DIO object, then you automatically get all
lines. This means that if a digital I/O object contains lines from a
port-configurable device, and you write a value to one or more of those lines,
then all the lines are written to even if they are not contained by the device
object.
• Line-configurable devices – You can address the lines associated with a
line-configurable device individually. This means that you can configure
individual lines for either input or output. Additionally, you can read and
write values on a line-by-line basis. Note that for National Instruments E
Series hardware, port 0 is always line-configurable, while all other ports are
port-configurable.
You can return the line and port characteristics with the daqhwinfo function.
For example, National Instruments AT-MIO-16DE-10 board has four ports and
eight digital I/O lines per port. To return the digital I/O characteristics for this
board
hwinfo = daqhwinfo(dio);
To display the line and port characteristics for the first port
hwinfo.Port(1)
ans =
ID:
LineIDs:
Direction:
Config:
0
[0 1 2 3 4 5 6 7]
'in/out'
'line'
To display the line and port characteristics for the second port
hwinfo.Port(2)
ans =
ID:
LineIDs:
Direction:
Config:
7-6
2
[0 1 2 3 4 5 6 7]
'in/out'
'port'
Adding Lines to a Digital I/O Object
To display the line and port characteristics for the third port
hwinfo.Port(3)
ans =
ID:
LineIDs:
Direction:
Config:
3
[0 1 2 3 4 5 6 7]
'in/out'
'port'
To display the line and port characteristics for the fourth port
hwinfo.Port(4)
ans =
ID:
LineIDs:
Direction:
Config:
4
[0 1 2 3 4 5 6 7]
'in/out'
'port'
This information tells you that you can configure all 32 lines for either input or
output, and that the first port is line-configurable while the remaining ports
are port-configurable.
7-7
7
Digital Input/Output
Referencing Individual Hardware Lines
As described in the preceding section, you can access lines with the Line
property or with a line object. To reference individual lines, you must specify
either MATLAB indices or descriptive line names.
MATLAB Indices
Every hardware line contained by a digital I/O object has an associated
MATLAB index that is used to reference the line. When adding lines with the
addline function, index assignments are made automatically. The line indices
start at 1 and increase monotonically up to the number of line group
members.The first line indexed in the line group represents the least
significant bit (LSB), and the highest indexed line represents the most
significant bit (MSB). Unlike adding channels with the addchannel function,
you cannot manually assign line indices with addline.
For example, the digital I/O object dio created in the preceding section had the
MATLAB indices 1 through 8 automatically assigned to the hardware lines 0
through 7, respectively. To manually swap the hardware line order so that line
ID 1 is the LSB, you supply the appropriate index to hwlines and use the
HwLine property.
hwlines(1).HwLine = 1;
hwlines(2).HwLine = 0;
Alternatively, you can use the Line property.
dio.Line(1).HwLine = 1;
dio.Line(2).HwLine = 0;
Descriptive Line Names
Choosing a unique, descriptive name can be a useful way to identify and
reference lines – particularly for large line groups. You can associate
descriptive names with hardware lines using the addline function. For
example, suppose you want to add 8 lines to dio, and you want to associate the
name TrigLine with the first line added.
addline(dio,0,'out','TrigLine');
addline(dio,1:7,'out');
7-8
Adding Lines to a Digital I/O Object
Alternatively, you can use the LineName property.
addline(dio,0:7,'out');
dio.Line(1).LineName = 'TrigLine';
You can now use the line name to reference the line.
dio.TrigLine.Direction = 'in';
Example: Adding Lines for National Instruments Hardware
This example illustrates various ways you can add lines to a digital I/O object
associated with a National Instruments AT-MIO-16DE-10 board. This board is
a multiport device whose characteristics are described in “Line and Port
Characteristics” on page 7-5.
To add eight input lines to dio from port 0
addline(dio,0:7,'in');
To add four input lines and four output lines to dio from port 0
addline(dio,0:7,{'in','in','in','in','out','out','out','out'});
Suppose you want to add the first line from port 0 and port 2 configured for
input, and the second line from the same ports configured for output. There are
three ways to do this. The first way requires only one call to addline since it
uses the hardware line IDs, and not the port IDs.
addline(dio,[0 1 8 9],{'in','out','in','out'});
The second way requires two calls to addline, and specifies one line ID and
multiple port IDs for each call.
addline(dio,0,[0 2],'in');
addline(dio,1,[0 2],'out');
The third way requires two calls to addline, and specifies multiple line IDs and
one port ID for each call.
addline(dio,0:1,0,{'in','out'});
addline(dio,0:1,2,{'in','out'});
7-9
7
Digital Input/Output
Writing and Reading Digital I/O Line Values
After you add lines to a digital I/O object, you can:
• Write values to lines
• Read values from lines
Note Unlike analog input and analog output objects, you do not control the
behavior of digital I/O objects by configuring properties. This is because
buffered digital I/O is not supported, and data is not stored in the engine.
Instead, you either write values directly to, or read value directly from one or
more hardware lines.
Writing Digital Values
You write values to one or more digital I/O lines with the putvalue function.
putvalue requires the digital I/O object and the values to be written as input
arguments. You can specify the values to be written as a decimal value or as a
binary vector (binvec). A binary vector is a logical array that is constructed with
the least significant bit (LSB) in the first column and the most significant bit
(MSB) in the last column. For example, the decimal value 23 is written in
binvec notation as [1 1 1 0 1] = 20 + 21 + 22 + 24. You may find that binvecs are
easier to work with than decimal values since there is a clear association
between a given line and the value (1 or 0) that is written to it. You can convert
decimal values to binvec values with the dec2binvec function
For example, suppose you create the digital I/O object dio and add eight output
lines to it from port 0.
dio = digitalio('nidaq',1);
addline(dio,0:7,'out');
To write a value of 23 to the eight lines contained by dio, you can write to the
device object.
data = 23;
putvalue(dio,data)
7-10
Writing and Reading Digital I/O Line Values
Alternatively, you can write to individual lines through the Line property.
putvalue(dio.Line(1:8),data)
To write a binary vector of values using the device object and the Line property
bvdata = dec2binvec(data,8);
putvalue(dio,bvdata)
putvalue(dio.Line(1:8),bvdata)
The second input argument supplied to dec2binvec specifies the number of bits
used to represent the decimal value. Since the preceding commands write to all
eight lines contained by dio, an eight element binary vector is required. If you
do not specify the number of bits, then the minimum number of bits needed to
represent the decimal value is used.
Alternatively, you can create the binary vector without using dec2binvec.
bvdata = logical([1 1 1 0 1 0 0 0]);
putvalue(dio,bvdata)
Rules for Writing Digital Values
Writing values to digital I/O lines follows these rules:
• If the digital I/O object contains lines from a port-configurable device, then
the data acquisition engine writes to all port-configurable lines even if they
are not contained by the device object.
• When writing decimal values:
- If the value is too large to be represented by the lines contained by the
device object, then an error is returned.
- You can write to a maximum of 32 lines. To write to more than 32 lines,
you must use a binvec value.
• When writing binvec values:
- You can write to any number of lines.
- There must be an element in the binary vector for each line you write to.
• You can always read from a line configured for output. Reading values is
discussed on “Reading Digital Values” on page 7-12.
• An error is returned if you write a negative value, or if you write to a line
configured for input.
7-11
7
Digital Input/Output
Reading Digital Values
You can read values from one or more digital I/O lines with the getvalue
function. getvalue requires the digital I/O object as an input argument. You
can optionally specify an output argument, which represents the returned
values as a binary vector. Binary vectors are described in “Writing Digital
Values” on page 7-10.
For example, suppose you create the digital I/O object dio and add eight input
lines to it from port 0.
dio = digitalio('nidaq',1);
addline(dio,0:7,'in');
To read the current value of all the lines contained by dio and return the result
to out
portval = getvalue(dio)
portval =
1
1
1
0
1
0
0
0
To read the current values of the first four lines contained by dio and return
the result to out
lineval = getvalue(dio.Line(1:5))
lineval =
1
1
1
0
1
You can convert a binvec to a decimal value with the binvec2dec function. For
example, to convert the binary vector lineval to a decimal value
out = binvec2dec(lineval)
out =
23
7-12
Writing and Reading Digital I/O Line Values
Rules for Reading Digital Values
Reading values from digital I/O lines follows these rules:
• If the digital I/O object contains lines from a port-configurable device, then
all lines are read even if they are not contained by the device object.
However, only values from the lines contained by the digital I/O object are
returned.
• You can always read from a line configured for output.
• For National Instruments hardware, lines configured for input return a
value of 1 by default.
• getvalue always returns a binary vector (binvec). To convert the binvec to a
decimal value, use the binvec2dec function.
Example: Writing and Reading Digital Values
This example illustrates how to read and write digital values using a
line-configurable subsystem. With line-configurable subsystems, you can
transfer values on a line-by-line basis.
You can run this example by typing daqdoc7_1 at the MATLAB command line.
1. Create a device object – Create the digital I/O object dio for a National
Instruments board. The installed adaptors and hardware IDs are found with
daqhwinfo.
dio = digitalio('nidaq',1);
2. Add lines – Add eight output lines from port 0 (line-configurable).
addline(dio,0:7,'out');
3. Read and write values – Write a value of 13 to the first four lines as a
decimal number and as a binary vector, and read back the values.
data = 13;
putvalue(dio.Line(1:4),data)
val1 = getvalue(dio);
bvdata = dec2binvec(data);
putvalue(dio.Line(1:4),bvdata)
val2 = getvalue(dio);
7-13
7
Digital Input/Output
Write a value of 3 to the last four lines as a decimal number and as a binary
vector, and read back the values.
data = 3;
putvalue(dio.Line(5:8),data)
val3 = getvalue(dio.Line(5:8));
bvdata = dec2binvec(data,4);
putvalue(dio.Line(5:8),bvdata)
val4 = getvalue(dio.Line(5:8));
Read values from the last four lines but switch the most significant bit (MSB)
and the least significant bit (LSB).
val5 = getvalue(dio.Line(8:-1:5));
4. Clean up – When you no longer need dio, you should remove it from memory
and from the MATLAB workspace.
delete(dio)
clear dio
7-14
Generating Timer Events
Generating Timer Events
The fact that analog input and analog output objects make use of data stored
in the engine and clocked I/O leads to the concept of a “running” device object
and the generation of events.
However, since the Data Acquisition Toolbox does not support buffered digital
I/O operations, digital I/O objects do not store data in the engine. Additionally,
reading and writing line values are not clocked at a specific rate in the way that
data is sampled by an analog input or analog output subsystem. Instead,
values are either written directly to digital lines with putvalue, or read directly
from digital lines with getvalue.
Therefore, the concept of a running digital I/O object does not make sense in
the same way that it does for analog input and analog output objects. However,
you can “run” a digital I/O object to perform one task: generate timer events.
You can use timer events to update and display the state of the digital I/O
object. For an example of this, refer to the diopanel demo.
Timer Events
The only event supported by digital I/O objects is a timer event. Timer events
occur after a specified period of time has passed. Properties associated with
generating timer events are given below.
Table 7-3: Digital I/O Timer Event Properties
Property Name
Description
Running
Indicates if the device object is running.
TimerAction
Specifies the M-file action function to execute
whenever a predefined period of time passes.
TimerPeriod
Specifies the period of time between timer events.
A timer event is generated whenever the time specified by TimerPeriod passes.
This event executes the action function specified for TimerAction. Time is
measured relative to when the device object starts running (Running is On).
Starting a digital I/O object is discussed in the next section.
7-15
7
Digital Input/Output
Some timer events may not be processed if your system is significantly slowed
or if the TimerPeriod value is too small. For example, a common application for
timer events is to display data. However, since displaying data can be a
CPU-intensive task, some of these events may be dropped. For digital I/O
objects, timer events are typically used to display the state of the device object.
Refer to the diopanel demo for an example that generates timer events to
update the state of a digital I/O object.
To see how to construct an action function, refer to “Creating and Executing
Action Functions” on page 5-52 or the example below.
Starting and Stopping a Digital I/O Object
You use the start function to start a digital I/O object. For example, to start
the digital I/O object dio
start(dio)
After start is issued, the Running property is automatically set to On, and
timer events can be generated. If you attempt to start a digital I/O object that
does not contain any lines or that is already running, then an error is returned.
A digital I/O object will stop executing under these conditions:
• The stop function is issued.
• An error occurred in the system.
When the device object stops, Running is automatically set to Off.
7-16
Generating Timer Events
Example: Generating Timer Events
This example illustrates how to generate timer events for a digital I/O object.
The action function daqaction displays the event type and device object name.
Note that you must issue a stop command to stop the execution of the digital
I/O object.
You can run this example by typing daqdoc7_2 at the MATLAB command line.
1. Create a device object – Create the digital I/O object dio for a National
Instruments board. The installed adaptors and hardware IDs are found with
daqhwinfo.
dio = digitalio('nidaq',1);
2. Add lines – Add eight input lines from port 0 (line-configurable).
addline(dio,0:7,'in');
3. Configure property values – Configure the timer event to call daqaction
every five seconds.
set(dio,'TimerAction','daqaction')
set(dio,'TimerPeriod',5.0)
Start the digital I/O object. You must issue a stop command when you no
longer want to generate timer events.
start(dio)
4. Clean up – When you no longer need dio, you should remove it from memory
and from the MATLAB workspace.
delete(dio)
clear dio
7-17
7
Digital Input/Output
Evaluating the Digital I/O Object Status
At any time after a digital I/O object is created, you can evaluate its status by:
• Returning the value of the Running property
• Invoking the display summary
The Display Summary
You can invoke the display summary by typing the digital I/O object at the
command line. The displayed information 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 line summary
information.
General Summary Information
The general display summary includes the device object type and the hardware
device name, followed by the port parameters. The port parameters include the
port ID, and whether the associated lines are configurable for reading or
writing.
Line Summary Information
The line display summary includes property values associated with:
• The hardware line mapping
• The line name
• The port ID
• The line direction
7-18
Evaluating the Digital I/O Object Status
The display summary for the example given in “Example: Writing and Reading
Digital Values” on page 7-13 is shown below.
Display Summary of DigitalIO (DIO) Object Using 'PCI-6024E'.
General display
summary
Port Parameters:
Port 0 is line configurable for reading and writing
Engine status:
Engine not required.
DIO object contains line(s):
Line display
summary
Index:
LineName:
HwLine:
Port:
Direction:
1
''
0
0
'In'
2
''
1
0
'In'
3
''
2
0
'In'
4
''
3
0
'In'
5
''
4
0
'In'
6
''
5
0
'In'
7
''
6
0
'In'
8
''
7
0
'In'
You can use the Line property to display only the line summary information.
DIO.Line
7-19
7
Digital Input/Output
7-20
8
Saving and Loading the
Session
Overview
. . . . . . . . . . . . . . . . . . . . . 8-2
Saving and Loading Device Objects . . . . . . . . . 8-3
Saving Device Objects to an M-File . . . . . . . . . . . 8-3
Saving Device Objects to a MAT-File . . . . . . . . . . 8-5
Logging Information to Disk . . . . .
Specifying a Filename . . . . . . . . . .
Retrieving Logged Information . . . . . .
Example: Logging and Retrieving Information
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
8-6
8-7
8-8
8-10
8
Saving and Loading the Session
Overview
During a data acquisition session, you may want to save your work to one or
more disk files in order to document or debug your application, post-process
data, and so on. The components of a data acquisition session that you can save
to disk are divided into two separate parts:
• Device objects and their associated property values
• Information associated with acquiring data with an analog input object
including:
- Acquired data
- Event information
- Device object and channel information
- Hardware information
You can save specific components of your session to an M-file using the
obj2mfile function, to a MAT-file using the save command, or to a binary
''.daq'' file using the LoggingMode property.
8-2
Saving and Loading Device Objects
Saving and Loading Device Objects
You can save a device object to disk using two possible formats:
• As an M-file using the obj2mfile function
• As a MAT-file using the save command
For analog input objects, you can also save acquired data, hardware
information, and so on to a log file. Refer to “Logging Information to Disk” on
page 8-6 for more information.
Saving Device Objects to an M-File
You can save a device object to an M-file using the obj2mfile function.
obj2mfile provides you with these options:
• Save all property values, or save only those property values that differ from
their default values.
Read-only property values are not saved. Therefore, read-only properties use
their default values when you load the device object into the MATLAB
workspace. To determine if a property is read-only, use the propinfo
function or examine the property reference pages.
• Save property values using the set syntax, the dot notation, or named
referencing (if defined).
If the UserData property is not empty, or if action properties are set to a cell
array of values, then the data stored in these properties is written to a
MAT-file when the device object is saved. The MAT-file has the same name
as the M-file containing the device object code.
For example, suppose you create the analog input object ai for a sound card,
add two channels to it, and configure several property values.
ai = analoginput('winsound');
addchannel(ai,1:2,{'Temp1';'Temp2'});
time = now;
set(ai,'SampleRate',11025,'TriggerRepeat',4)
set(ai,'TriggerAction',{'myaction',time})
start(ai)
8-3
8
Saving and Loading the Session
The following command saves ai and the modified property values to the M-file
myai.m. Since the TriggerAction property is set to a cell array of values, its
value is automatically written to the MAT-file myai.mat.
obj2mfile(ai,'myai.m');
Created: d:\v6\myfiles\myai.m
Created: d:\v6\myfiles\myai.mat
Use the type command to display myai.m at the command line.
Loading the Device Object
To load a device object that was saved as an M-file into the MATLAB
workspace, type the name of the M-file at the command line. For example, to
load ai from the M-file myai.m
ai = myai
Note that the read-only properties such as SamplesAcquired and
SamplesAvailable are restored to their default values.
get(ai,{'SamplesAcquired','SamplesAvailable'})
ans =
[0]
[0]
When loading ai into the workspace, the MAT-file myai.mat is automatically
loaded and the TriggerAction property value is restored.
ai.TriggerAction
ans =
'myaction'
8-4
[7.3071e+005]
Saving and Loading Device Objects
Saving Device Objects to a MAT-File
You can save a device object to a MAT-file just as you would any workspace
variable – using the save command. For example, to save the analog input
object ai and the variable time defined in the preceding section to the MAT-file
myai1.mat
save myai1 ai time
Read-only property values are not saved. Therefore, read-only properties use
their default values when you load the device object into the MATLAB
workspace. To determine if a property is read-only, use the propinfo function
or examine the property reference pages.
Loading the Device Object
To load a device object that was saved to a MAT-file into the MATLAB
workspace, use the load command. For example, to load ai and time from
MAT-file myai1.mat
load myai1
8-5
8
Saving and Loading the Session
Logging Information to Disk
While an analog input object is running, you can log this information to a disk
file:
• Acquired data
• Event information
• Device object and channel information
• Hardware information
Logging information to disk provides a permanent record of your data
acquisition session, and is an easy way to debug your application.
As shown below, you can think of the logged information as a stream of data
and events.
Start
Trigger n
Trigger 2
Trigger 1
N
a
N
Data
Data
Stop
N
a ...
N
Time
Data logged to file
The properties associated with logging information to a disk file are given
below.
Table 8-1: Analog Input Logging Properties
8-6
Property Name
Description
LogFileName
Specify the name of the disk file to which information is
logged.
Logging
Indicate if data is being logged.
Logging Information to Disk
Table 8-1: Analog Input Logging Properties (Continued)
Property Name
Description
LoggingMode
Specify the destination for acquired data.
LogToDiskMode
Specify whether data, device object information, and
hardware information is saved to one disk file or to
multiple disk files.
You can initiate logging by setting LoggingMode to Disk or Disk&Memory. A new
log file is created each time you issue the start function, and each different
analog input object must log information to a separate log file. Writing to disk
is performed as soon as possible after the current data block is filled.
You can choose whether a log file is overwritten or if multiple log files are
created with the LogToDiskMode property. If LogToDiskMode is Overwrite, the
log file is overwritten. If LogToDiskMode is Index, new log files are created, each
with an indexed name based on the value of LogFileName.
Specifying a Filename
You specify the name of the log file with the LogFileName property. You can
specify any value for LogFileName, including a directory path, provided the
filename is supported by your operating system. Additionally, if
LogToDiskMode is Index, then the log filename also follows these rules:
• Indexed log filenames are identified by a number. This number precedes the
filename extension and is incremented by one for successive log files.
• If no number is specified as part of the initial log filename, then the first log
file does not have a number associated with it. For example, if LogFileName
is myfile.daq, then myfile.daq is the name of the first log file,
myfile01.daq is the name of the second log file, and so on.
• LogFileName is updated after the log file is written (after the stop event
occurs).
• If the specified log filename already exists, then the existing file is
overwritten.
8-7
8
Saving and Loading the Session
Retrieving Logged Information
You retrieve logged information with the daqread function. You can retrieve
any part of the information stored in a log file with one call to daqread.
However, you will probably use daqread in one of these two ways:
• Retrieving data and time information
• Retrieving event, device object, channel, and hardware information
Retrieving Data and Time Information
You can characterize logged data by the sample number or the time the sample
was acquired. To retrieve data and time information, you use the syntax shown
below
[data,time,abstime] = daqread('file','P1',V1,'P2',V2,...);
where:
• data is the retrieved data. Data is returned as an m-by-n matrix where m is
the number of samples and n is the number of channels.
• time (optional) is the relative time associated with the retrieved data. Time
is returned as an m-by-1 matrix where m is the number of samples.
• abstime (optional) is the absolute time of the first trigger. Absolute time is
returned as a clock vector.
• file is the name of the log file.
• 'P1',V2,'P2',V2,…(optional) are the property name/property value pairs,
which allow you to select the amount of data to retrieve, among other things
(see below).
daqread returns data and time information in the same format as getdata. If
data from multiple triggers is retrieved, each trigger is separated by a NaN.
8-8
Logging Information to Disk
You select the amount of data returned and the format of that data with the
properties given below.
Table 8-2: daqread Properties
Property Name
Description
Samples
Specify the sample range.
Time
Specify the relative time range.
Triggers
Specify the trigger range.
Channels
Specify the channel range. Channel names can be
specified as a cell array.
DataFormat
Specify the data format as doubles or native.
TimeFormat
Specify the time format as vector or matrix.
The Samples, Time, and Triggers properties are mutually exclusive. If none of
these three properties is specified, then all the data is returned.
Retrieving Event, Device Object, Channel, and Hardware Information
You can retrieve event, device object, channel, and hardware information,
along with data and time information, using the syntax shown below.
[data,time,abstime,events,daqinfo] =
daqread('file','P1',V1,'P2',V2,...);
events is a structure containing event information associated with the logged
data. The events retrieved depend on the value of the Samples, Time, or
Triggers property. At a minimum, the trigger event associated with the
selected data is returned. The entire event log is returned to events only if
Samples, Time, or Triggers is not specified.
daqinfo is a structure that stores device object, channel, and hardware
information in two fields: ObjInfo and HwInfo. ObjInfo is a structure
containing property values for the device object and any channels it contains.
The property values are returned in the same format as returned by get.
HwInfo is a structure containing hardware information. The hardware
information is identical to the information returned by daqhwinfo(obj).
8-9
8
Saving and Loading the Session
Alternatively, you can return only object, channel, and hardware information
with the command
daqinfo = daqread('file','info');
Note When you retrieve object information, the entire event log is returned
to daqinfo.ObjInfo.EventLog regardless of the number of samples retrieved.
Example: Logging and Retrieving Information
This example illustrates how to log information to a disk file and then retrieve
the logged information to MATLAB using various calls to daqread.
A sound card is configured for stereo acquisition, data is logged to memory and
to a disk file, four triggers are issued, and 2 seconds of data are collected for
each trigger at a sampling rate of 8 kHz. You can run this example by typing
daqdoc8_1 at the MATLAB command line.
1. Create a device object – Create the analog input object ai for a sound card.
The installed adaptors and hardware IDs are found with daqhwinfo.
ai = analoginput('winsound');
%ai = analoginput('nidaq',1);
%ai = analoginput('cbi',1);
2. Add channels – Add two hardware channels to ai.
ch = addchannel(ai,1:2);
%ch = addchannel(ai,0:1); % For NI and CBI
3. Configure property values – Define a 2 second acquisition for each trigger,
set the trigger to repeat three times, and log information to the file file00.daq.
duration = 2; % Two seconds of data for each trigger
set(ai,'SampleRate',8000)
ActualRate = get(ai,'SampleRate');
set(ai,'SamplesPerTrigger',duration*ActualRate)
set(ai,'TriggerRepeat',3)
set(ai,'LogFileName','file00.daq')
set(ai,'LoggingMode','Disk&Memory')
8-10
Logging Information to Disk
4. Acquire data – Start ai, wait for ai to stop running, and extract all the data
stored in the log file as sample-time pairs.
start(ai)
while strcmp(ai.Running,'On')
end
[data,time] = daqread('file00.daq');
Plot the data and label the figure axes.
subplot(211), plot(data)
title('Logging and Retrieving Data')
xlabel('Samples'), ylabel('Signal (Volts)')
subplot(212), plot(time,data)
xlabel('Time (seconds)'), ylabel('Signal (Volts)')
5. Clean up – When you no longer need ai, you should remove it from memory
and from the MATLAB workspace.
delete(ai)
clear ai
Retrieving Data Based on Samples
You can retrieve data based on samples using the Samples property. To retrieve
samples 1000 to 2000 for both sound card channels
[data,time] = daqread('file00.daq','Samples',[1000 2000]);
Plot the data and label the figure axes.
subplot(211), plot(data);
xlabel('Samples'), ylabel('Signal (Volts)')
subplot(212), plot(time,data);
xlabel('Time (seconds)'), ylabel('Signal (Volts)')
Retrieving Data Based on Channels
You can retrieve data based on channels using the Channels property. To
retrieve samples 1000 to 2000 for the second sound card channel
[data,time] = daqread('file00.daq','Samples',[1000 2000],
'Channels',2);
8-11
8
Saving and Loading the Session
Plot the data and label the figure axes.
subplot(211), plot(data);
xlabel('Samples'), ylabel('Signal (Volts)')
subplot(212), plot(time,data);
xlabel('Time (seconds)'); ylabel('Signal (Volts)')
Alternatively, you can retrieve data for the second sound card channel by
specifying the channel name.
[data,time] = daqread('file00.daq','Samples',[1000 2000],
'Channels',{'Right'});
Retrieving Data Based on Triggers
You can retrieve data based on triggers using the Triggers property. To
retrieve all the data associated with the second and third triggers for both
sound card channels
[data,time] = daqread('file00.daq','Triggers',[2 3]);
Plot the data and label the figure axes.
subplot(211), plot(data);
xlabel('Samples'), ylabel('Signal (Volts)')
subplot(212), plot(time,data);
xlabel('Time (seconds)'), ylabel('Signal (Volts)')
Retrieving Data Based on Time
You can retrieve data based on time using the Time property. Time must be
specified in seconds and Time=0 corresponds to the first logged sample. To
retrieve the first 25% of the data acquired for the first trigger
[data,time] = daqread('file00.daq','Time',[0 0.5]);
Plot the data and label the figure axes.
subplot(211), plot(data);
xlabel('Samples'), ylabel('Signal (Volts)')
subplot(212), plot(time, data);
xlabel('Time (seconds)'), ylabel('Signal (Volts)')
8-12
Logging Information to Disk
Retrieving Event, Object, Channel, and Hardware Information
You can retrieve event, object, channel, and hardware information by
specifying the appropriate arguments to daqread. For example, to retrieve all
event information, you must return all the logged data.
[data,time,abstime,events,info] = daqread('file00.daq');
{events.Type}
ans =
'Start' 'Trigger' 'Trigger' 'Trigger' 'Trigger' 'Stop'
If you retrieve part of the data, then only the events associated with the
requested data are returned.
[data,time,abstime,events,info] = daqread('file00.daq',
'Trigger',[1 3]);
{events.Type}
ans =
'Trigger' 'Trigger' 'Trigger'
You can retrieve the entire event log as well as object and hardware
information by including info as an input argument to daqread.
daqinfo = daqread('file00.daq','info')
daqinfo =
ObjInfo: [1x1 struct]
HwInfo: [1x1 struct]
To return the event log information
eventinfo = daqinfo.ObjInfo.EventLog
eventinfo =
6x1 struct array with fields:
Type
Data
8-13
8
Saving and Loading the Session
8-14
9
Function Reference
Overview . . . . . . . . . . . . . . . . . . . . . 9-2
Getting Command Line Function Help . . . . . . . . . . 9-2
Functions Grouped by Category . . . . . . . . . . . 9-4
Functions Listed Alphabetically . . . . . . . . . . . 9-8
9
Function Reference
Overview
This section provides descriptions of all toolbox functions that you can use
directly. In “Functions Grouped by Category” on page 9-4, the functions are
summarized according to usage. In “Functions Listed Alphabetically” on
page 9-8, the functions are described in detail.
Getting Command Line Function Help
To get command line function help, you should use the daqhelp function. For
example, to get help for the addchannel function, type
daqhelp addchannel
Alternatively, you can use the help command.
help addchannel
However, the Data Acquisition Toolbox provides “overloaded” versions of
several MATLAB functions. That is, it provides toolbox-specific
implementations of these functions using the same function name.
To get command line help for an overloaded toolbox function using the help
command, you must supply one of two possible class directories to help.
help daqdevice/function_name
help daqchild/function_name
Note that the same help information is returned regardless of the class
directory specified.
For example, the Data Acquisition Toolbox provides an overloaded version of
the delete function. To obtain help for the MATLAB version of this function,
type
help delete
9-2
Overview
You can determine if a function is overloaded by examining the last section of
the help. For delete, the help contains the following overloaded versions (not
all are shown).
Overloaded methods
help char/delete.m
help scribehandle/delete.m
help scribehgobj/delete.m
.
.
.
help daqdevice/delete.m
help daqchild/delete.m
So, to obtain help on the toolbox version of this function, type
help daqdevice/delete
For more information on overloaded functions and class directories, refer to
“MATLAB Classes and Objects” in the Help browser.
9-3
9
Function Reference
Functions Grouped by Category
This section contains brief descriptions of all toolbox functions. The functions
and the device objects they are associated with are categorized according to
usage. The supported device objects include analog input (AI), analog output
(AO), and digital I/O (DIO).
A number of other MATLAB M-file helper functions are provided with this
toolbox to support the functions listed below. These helper functions are not
documented since they are not intended for direct use.
Creating Device Objects
analoginput
Create an analog input object.
analogoutput
Create an analog output object.
digitalio
Create a digital I/O object.
Adding Channels and Lines
addchannel
Add hardware channels to an analog input or analog
output object.
addline
Add hardware lines to a digital I/O object.
addmuxchannel
Add hardware channels when using a multiplexer board.
Getting and Setting Properties
9-4
get
Return device object properties.
set
Configure or display device object properties.
setverify
Configure and return the specified property.
AI
AO
DIO
AI
AO
DIO
AI
AO
DIO
Functions Grouped by Category
Executing the Object
start
Start a device object.
stop
Stop a device object.
trigger
Manually execute a trigger.
waittilstop
Wait for the device object to stop running.
Working with Data
flushdata
Remove data from the data acquisition engine.
getdata
Extract data, time, and event information from the data
acquisition engine.
getsample
Immediately acquire one sample.
getvalue
Read values from lines.
peekdata
Preview most recent acquired data.
putdata
Queue data in the engine for eventual output.
putsample
Immediately output one sample.
putvalue
Write values to lines.
Getting Information and Help
daqhelp
Display help for device objects, constructors, adaptors,
functions, and properties.
daqhwinfo
Display data acquisition hardware information.
AI
AO
DIO
AI
AO
DIO
AI
AO
DIO
9-5
9
Function Reference
Getting Information and Help (Continued)
daqpropedit
Invoke the property editor graphical user interface.
propinfo
Return property characteristics for device objects,
channels, or lines.
General Purpose
9-6
binvec2dec
Convert binary vector to decimal value.
clear
Remove device objects from the MATLAB workspace.
daqaction
An action function that displays event information for
the specified event.
daqfind
Return device objects, channels, or lines from the data
acquisition engine to the MATLAB workspace.
daqmem
Allocate or display memory resources.
daqread
Read a Data Acquisition Toolbox (.daq) file.
daqschool
Interface for displaying toolbox tutorials.
daqregister
Register or unregister a hardware driver adaptor.
daqreset
Remove device objects and data acquisition DLLs from
memory.
dec2binvec
Convert decimal value to binary vector.
delete
Remove device objects, channels, or lines from the data
acquisition engine.
disp
Display summary information for device objects,
channels, or lines.
ischannel
Check for channels.
isdioline
Check for lines.
AI
AO
DIO
AI
AO
DIO
Functions Grouped by Category
General Purpose (Continued)
isvalid
Determine if device objects, channels, or lines are valid.
length
Return the length of a device object, channel group, or
line group.
load
Load device objects, channels, or lines into the MATLAB
workspace.
makenames
Generate a list of descriptive channel or line names.
muxchanidx
Return multiplexed scanned channel index.
obj2mfile
Convert device objects, channels, or lines to MATLAB
code.
save
Save device objects to a MAT-file.
showdaqevents
Display event log information.
size
Return the size of a device object, channel group, or line
group.
AI
AO
DIO
9-7
9
Function Reference
Functions Listed Alphabetically
This section contains detailed descriptions of all toolbox functions. Each
function reference page contains some or all of this information:
• The function name
• The purpose of the function
• The function syntax
All valid input argument and output argument combinations are shown. In
some cases, an ellipsis (. . .) is used for the input arguments. This means that
all preceding input argument combinations are valid for the specified output
argument(s).
• A description of each argument
• A description of the function
• Additional remarks about usage
• An example of usage
• Related functions or properties
9-8
addchannel
Purpose
Syntax
Arguments
Description
9addchannel
Add hardware channels to an analog input or analog output object
chans
chans
chans
chans
=
=
=
=
addchannel(obj,hwch)
addchannel(obj,hwch,index)
addchannel(obj,hwch,'names')
addchannel(obj,hwch,index,'names')
obj
An analog input or analog output object.
hwch
Specifies the numeric IDs of the hardware channels added to
the device object. Any MATLAB vector syntax can be used.
index
The MATLAB indices to associate with the hardware
channels. Any MATLAB vector syntax can be used provided
the vector elements are monotonically increasing.
'names'
A descriptive channel name or cell array of descriptive
channel names.
chans
A column vector of channels with the same length as hwch.
chans = addchannel(obj,hwch) adds the hardware channels specified by
hwch to the device object obj. The MATLAB indices associated with the added
channels are assigned automatically. chans is a column vector of channels.
chans = addchannel(obj,hwch,index) adds the hardware channels specified
by hwch to the device object obj. index specifies the MATLAB indices to
associate with the added channels.
chans = addchannel(obj,hwch,'names') adds the hardware channels
specified by hwch to the device object obj. The MATLAB indices associated with
the added channels are assigned automatically. names is a descriptive channel
name or cell array of descriptive channel names.
chans = addchannel(obj,hwch,index,'names') adds the hardware channels
specified by hwch to the device object obj. index specifies the MATLAB indices
to associate with the added channels. names is a descriptive channel name or
cell array of descriptive channel names.
9-9
addchannel
Remarks
Rules for Adding Channels
• The numeric values you supply for hwch depend on the hardware you access.
For National Instruments and ComputerBoards hardware, channels are
“zero-based” (begin at zero). For Agilent Technologies hardware and sound
cards, channels are “one-based” (begin at one).
• Hardware channel IDs are stored in the HwChannel property and the
associated MATLAB indices are stored in the Index property.
• You can add individual hardware channels to multiple device objects.
• For for sound cards and Agilent Technologies devices, you cannot add a
hardware channel multiple times to the same device object.
• For Agilent Technologies devices, added channels must be in increasing
order.
• You can configure sound cards in one of two ways: mono mode or stereo mode.
For mono mode, hwch must be 1. For stereo mode, the first hwch value
specified must be 1.
Note If you are using National Instruments AMUX-64T multiplexer boards,
you must use the addmuxchannel function to add channels.
More About MATLAB Indices
Every hardware channel contained by a device object has an associated
MATLAB index that is used to reference the channel. Index assignments are
made either automatically by addchannel or explicitly with the index
argument and follow these rules:
• If index is not specified and no hardware channels are contained by the
device object, then the assigned indices automatically start at one and
increase monotonically. If hardware channels have already been added to
the device object, then the assigned indices automatically start at the next
highest index value and increase monotonically.
• If index is specified but the indices are previously assigned, then the
requested assignment takes precedence and the previous assignment is
reindexed to the next available values. If the lengths of hwch and index are
9-10
addchannel
not equal, then an error is returned and no channels are added to the device
object.
• The resulting indices begin at one and increase monotonically up to the size
of the channel group.
• If you are using scanning hardware, then the indices define the scan order.
• Sound cards cannot be reindexed.
Rules for Adding Channels to National Instruments 1200 Series Boards
When using National Instruments 1200 Series hardware, you need to modify
the above rules in these ways:
• Channel IDs are given in reverse order with addchannel. For example, to add
eight single-ended channels to the analog input object ai
addchannel(ai,7:-1:0);
• The scan order is from the highest ID to the lowest ID (which must be 0).
• There cannot be any gaps in the channel group.
• When channels are configured in differential mode, the hardware IDs are 0,
2, 4, and 6.
More About Descriptive Channel Names
You can assign hardware channels descriptive names, which are stored in the
ChannelName property. Choosing a unique descriptive name can be a useful
way to identify and reference channels. For a single call to addchannel, you
can:
• Specify one channel name that applies to all channels that are to be added
• Specify a different name for each channel to be added
If the number of names specified in a single addchannel call is more than one
but not equal to the number of channels to be added, then an error is returned.
If a channel is to be referenced by its name, then that name must not contain
symbols. If you are naming a large number of channels, then the makenames
function may be useful. If a channel is not assigned a descriptive name, then it
must be referenced by index.
A sound card configured in mono mode is automatically assigned the name
Mono, while a sound card configured in stereo mode is automatically assigned
9-11
addchannel
the names Left for the first channel and Right for the second channel. You can
change these default channel names when the device object is created, or any
time after the channel is added.
Example
National Instruments
Suppose you create the analog input object AI1 for a National Instruments
board, and add the first four hardware channels (channels 0-3) to it.
AI1 = analoginput('nidaq',1);
addchannel(AI1,0:3);
The channels are automatically assigned the indices 1-4. If you want to add the
first four hardware channels to AI1 and assign descriptive names to the
channels
addchannel(AI1,0:3,{'chan1','chan2','chan3','chan4'});
Note that you can use the makenames function to create a cell array of channel
names. If you add channels 4, 5, and 7 to the existing channel group
addchannel(AI1,[4 5 7]);
the new channels are automatically assigned the indices 5-7. Suppose instead
you add channels 4, 5, and 7 to the channel group and explicitly assign them
indices 1-3.
addchannel(AI1,[4 5 7],1:3);
The new channels are assigned the indices 1-3, and the previously defined
channels are reindexed as indices 4-7. However, if you assigned channels 4, 5,
and 7 to indices 6-8, an error is returned since there is a gap in the indices
(index 5 has no associated hardware channel).
9-12
addchannel
Sound Card
Suppose you create the analog input object AI1 for a sound card. Most sound
cards have only two channels that can be added to a device object. To configure
the sound card to operate in mono mode, you must specify hwch as 1.
AI1 = analoginput('winsound');
addchannel(AI1,1);
The ChannelName property is automatically assigned the value Mono. You can
now configure the sound card to operate in stereo mode by adding the second
channel.
addchannel(AI1,2);
The ChannelName property is assigned the values Left and Right for the two
hardware channels. Alternatively, you can configure the sound card to operate
in stereo mode with one call to addchannel.
addchannel(AI1,1:2);
See Also
Functions
delete, makenames
Properties
ChannelName, HwChannel, Index
9-13
addline
Purpose
Syntax
Arguments
Description
9addline
Add hardware lines to a digital I/O object
lines
lines
lines
lines
=
=
=
=
addline(obj,hwline,'direction')
addline(obj,hwline,port,'direction')
addline(obj,hwline,'direction','names')
addline(obj,hwline,port,'direction','names')
obj
A digital I/O object.
hwline
The numeric IDs of the hardware lines added to the device
object. Any MATLAB vector syntax can be used.
'direction'
The line directions can be In or Out, and can be specified as a
single value or a cell array of values.
port
The numeric IDs of the digital I/O port.
'names'
A descriptive line name or cell array of descriptive line
names.
lines
A row vector of lines with the same length as hwline.
lines = addline(obj,hwline,'direction') adds the hardware lines
specified by hwline to the digital I/O object obj. direction configures the lines
for either input or output. lines is a row vector of lines.
lines = addline(obj,hwline,port,'direction') adds the hardware lines
specified by hwline from the port specified by port to the digital I/O object obj.
lines = addline(obj,hwline,'direction','names') adds the hardware
lines specified by hwline to the digital I/O object obj. names is a descriptive line
name or cell array of descriptive line names.
lines = addline(obj,hwline,port,'direction','names') adds the
hardware lines specified by hwline from the port specified by port to the digital
I/O object obj. direction configures the lines for either input or output. names
is a descriptive line name or cell array of descriptive line names.
9-14
addline
Remarks
Rules for Adding Lines
• The numeric values you supply for hwline depend on the hardware you
access. For National Instruments and ComputerBoards hardware, line IDs
are “zero-based” (begin at zero).
• You can add a line only once to a given digital I/O object.
• Hardware line IDs are stored in the HwLine property and the associated
MATLAB indices are stored in the Index property.
• For a single call to addline, you can add multiple lines from one port or the
same line ID from multiple ports. You cannot add multiple lines from
multiple ports.
• If a port ID is not explicitly referenced, lines are added first from port 0, then
from port 1, and so on.
• You can specify the line directions as a single value or a cell array of values.
If a single direction is specified, then all added lines have that direction. If
supported by the hardware, you can configure individual lines by supplying
a cell array of directions.
More About MATLAB Indices
Every hardware line contained by a device object has an associated MATLAB
index that is used to reference the line. Index assignments are made
automatically by addline and follow these rules:
• If no hardware lines are contained by the device object, then the assigned
indices automatically start at one and increase monotonically. If hardware
lines have already been added to the device object, then the assigned indices
automatically start at the next highest index value and increase
monotonically.
• The resulting indices begin at one and increase monotonically up to the size
of the line group.
• The first indexed line represents the least significant bit (LSB) and the
highest indexed line represents the most significant bit (MSB).
9-15
addline
More About Descriptive Line Names
You can assign hardware lines descriptive names, which are stored in the
LineName property. Choosing a unique descriptive name can be a useful way to
identify and reference lines. For a single call to addline, you can:
• Specify one line name that applies to all lines that are to be added
• Specify a different name for each line to be added
If the number of names specified in a single addline call is more than one but
differs from the number of lines to be added, then an error is returned. If a line
is to be referenced by its name, then that name must not contain symbols. If
you are naming a large number of lines, then the makenames function may be
useful. If a line is not assigned a descriptive name, then it must be referenced
by index.
Example
Create the digital I/O object dio and add the first four hardware lines (line IDs
0-3) from port 0.
dio = digitalio('nidaq',1);
addline(dio,0:3,'in');
These lines are automatically assigned the indices 1-4. If you want to add the
first four hardware lines to dio and assign descriptive names to the lines
addline(dio,0:3,'in',{'line1','line2','line3','line4'});
Note that you can use the makenames function to create a cell array of line
names. You can add the first four hardware lines (line IDs 0-3) from port 1 to
the existing line group.
addline(dio,0:3,1,'out');
The new lines are automatically assigned the indices 5-8.
See Also
Functions
delete, makenames
Properties
HwLine, Index, LineName
9-16
addmuxchannel
Purpose
9addmuxchannel
Add hardware channels when using a multiplexer board
Syntax
addmuxchannel(obj)
addmuxchannel(obj,chanids)
chans = addmuxchannel(...)
Arguments
obj
An analog input object associated with a National
Instruments board.
chanids
The hardware channel IDs.
chans
The channels that are added to obj.
Description
addmuxchannel(obj) adds as many channels to obj as is physically possible
based on the number of National Instruments AMUX-64T multiplexer (mux)
boards specified by the NumMuxBoards property. For one mux board, 64
channels are added. For two mux boards, 128 channels are added. For four mux
boards, 256 channels are added.
addmuxchannel(obj,chanids) adds the channels specified by chanids to obj.
chanids refers to the hardware channel IDs of the data acquisition board.
The actual number of channels added to obj depends on the number of mux
boards used. For example, suppose you are using a data acquisition board with
16 channels connected to one mux board. If chanid is 0, then addmuxchannel
adds four channels. Refer to the AMUX-64T User Manual for more information
about adding mux channels based on hardware channel IDs and the number of
mux boards used.
chans = addmuxchannel(...) returns the channels added to chans.
Remarks
Before using addmuxchannel, you must set the NumMuxBoards property to the
appropriate value. You can use as many as four mux boards with one analog
input object. addmuxchannel deletes all channels contained by obj before new
channels are added.
See Also
Functions
muxchanidx
9-17
analoginput
Purpose
Syntax
Arguments
Description
9analoginput
Create an analog input object
AI = analoginput('adaptor')
AI = analoginput('adaptor',ID)
'adaptor'
Name of the hardware driver adaptor. The supported
adaptors are nidaq, cbi, hpe1432, and winsound.
ID
The hardware device identifier. ID is optional if the device
object is associated with a sound card having an ID of 0.
AI
The analog input object.
AI = analoginput('adaptor') creates the analog input object AI for a sound
card having an ID of 0 (adaptor must be winsound). This is the only case where
ID is not required.
AI = analoginput('adaptor',ID) creates the analog input object AI for the
specified adaptor and for the hardware device with device identifier ID. ID can
be specified as an integer or a string.
Remarks
More About Creating Analog Input Objects
• When an analog input object is created, it does not contain any hardware
channels. To execute the device object, hardware channels must be added
with the addchannel function.
• You can create multiple analog input objects that are associated with a single
analog input subsystem. However, you can typically execute only one of them
at a time.
• The analog input object exists in the data acquisition engine and in the
MATLAB workspace. If you create a copy of the device object, it references
the original device object in the engine.
• If ID is a numeric value, then you can specify it as an integer or a string. If
ID contains any non-numeric characters, then you must specify it as a string
(see the Agilent Technologies example below).
• The Name property is automatically assigned a descriptive name that is
produced by concatenating adaptor, ID, and -AI. You can change this name
at any time.
9-18
analoginput
More About the Hardware Device Identifier
When data acquisition devices are installed, they are assigned a unique
number which identifies the device in software. The device identifier is
typically assigned automatically and can usually be manually changed using a
vendor-supplied device configuration utility. National Instruments refers to
this number as the device number while Agilent Technologies refers to it is as
the device ID.
For sound cards, the device identifier is typically not exposed to you through
the Microsoft Windows environment. However, the Data Acquisition Toolbox
automatically associates each sound card with an integer ID value. There are
two cases to consider:
• If you have one sound card installed, then ID is 0. You are not required to
specify ID when creating an analog input object associated with this device.
• If you have multiple sound cards installed, the first one installed has an ID
of 0, the second one installed has an ID of 1, and so on. You must specify ID
when creating analog input objects associated with devices not having an ID
of 0.
There are two ways you can determine the ID for a particular device:
• Type daqhwinfo('adaptor').
• Execute the vendor-supplied device configuration utility.
Example
National Instruments
To create an analog input object for a National Instruments board defined as
device number 1
AI = analoginput('nidaq',1);
Agilent Technologies
To create an analog input object for an Agilent Technologies module with
device identifier 1 residing in VXI chassis 0
AI = analoginput('hpe1432','vxi0::1::instr');
Alternatively, you can use the syntax
AI = analoginput('hpe1432',1,0);
9-19
analoginput
The HP driver allows you to span multiple hardware devices. To create an
analog input object that spans two HP devices with device identifiers 1 and 2
residing in VXI chassis 0
AI = analoginput('hpe1432','vxi0::1,2::instr');
Alternatively, you can use the syntax
AI = analoginput('hpe1432',[1,2],0);
See Also
Functions
addchannel, daqhwinfo
Properties
Name
9-20
analogoutput
Purpose
Syntax
Arguments
Description
9analogoutput
Create an analog output object
AO = analogoutput('adaptor')
AO = analogoutput('adaptor',ID)
'adaptor'
Name of the hardware driver adaptor. The supported
adaptors are nidaq, cbi, hpe1432, and winsound.
ID
The hardware device identifier. ID is optional if the device
object is associated with a sound card having an ID of 0.
AO
The analog output object.
AO = analogoutput('adaptor') creates the analog output object AO for a
sound card having an ID of 0 (adaptor must be winsound). This is the only case
where ID is not required.
AO = analogoutput('adaptor',ID) creates the analog output object AO for
the specified adaptor and for the hardware device with device identifier ID. ID
can be specified as an integer or a string.
Remarks
More About Creating Analog Output Objects
• When an analog output object is created, it does not contain any hardware
channels. To execute the device object, hardware channels must be added
with the addchannel function.
• You can create multiple analog output objects that are associated with a
single analog output subsystem. However, you can typically execute only one
of them at a time.
• The analog output object exists in the data acquisition engine and in the
MATLAB workspace. If you create a copy of the device object, it references
the original device object in the engine.
• If ID is a numeric value, then you can specify it as an integer or a string. If
ID contains any non-numeric characters, then you must specify it as a string
(see the Agilent Technologies example below).
• The Name property is automatically assigned a descriptive name that is
produced by concatenating adaptor, ID, and -AO. You can change this name
at any time.
9-21
analogoutput
More About the Hardware Device Identifier
When data acquisition devices are installed, they are assigned a unique
number which identifies the device in software. The device identifier is
typically assigned automatically and can usually be manually changed using a
vendor-supplied device configuration utility. National Instruments refers to
this number as the device number while Agilent Technologies refers to it is as
the device ID.
For sound cards, the device identifier is typically not exposed to you through
the Microsoft Windows environment. However, the Data Acquisition Toolbox
automatically associates each sound card with an integer ID value. There are
two cases to consider:
• If you have one sound card installed, then ID is 0. You are not required to
specify ID when creating an analog output object associated with this device.
• If you have multiple sound cards installed, the first one installed has an ID
of 0, the second one installed has an ID of 1, and so on. You must specify ID
when creating analog output objects associated with devices not having an
ID of 0.
There are two ways you can determine the ID for a particular device:
• Type daqhwinfo('adaptor').
• Execute the vendor-supplied device configuration utility.
Example
National Instruments
To create an analog output object for a National Instruments board defined as
device number 1
AO = analogoutput('nidaq',1);
Agilent Technologies
To create an analog output object for an Agilent Technologies module with
device identifier 1 residing in VXI chassis 0
AO = analogoutput('hpe1432','vxi0::1::instr');
Alternatively, you can use the syntax
AO = analogoutput('hpe1432',1,0);
9-22
analogoutput
The HP driver allows you to span multiple hardware devices. To create an
analog output object that spans two HP devices with device identifiers 1 and 2
residing in VXI chassis 0
AO = analogoutput('hpe1432','vxi0::1,2::instr');
Alternatively, you can use the syntax
AO = analogoutput('hpe1432',[1,2],0);
See Also
Functions
addchannel, daqhwinfo
Properties
Name
9-23
binvec2dec
Purpose
9binvec2dec
Convert binary vector to decimal value
Syntax
out = binvec2dec(bin)
Arguments
bin
A binary vector.
out
A double array.
Description
out = binvec2dec(bin) converts the binary vector bin to the equivalent
decimal number and stores the result in out. All nonzero binary vector
elements are interpreted as a 1.
Remarks
A binary vector (binvec) is constructed with the least significant bit (LSB) in
the first column and the most significant bit (MSB) in the last column. For
example, the decimal number 23 is written as the binvec value [1 1 1 0 1].
Example
To convert the binvec value [1 1 1 0 1] to a decimal value
binvec2dec([1 1 1 0 1])
ans =
23
See Also
Functions
dec2binvec
9-24
clear
Purpose
9clear
Remove device objects from the MATLAB workspace
Syntax
clear obj
clear obj.Channel(index)
clear obj.Line(index)
Arguments
obj
A device object or array of device objects.
obj.Channel(index)
One or more channels contained by obj.
obj.Line(index)
One or more lines contained by obj.
Description
clear obj removes obj and all associated channels or lines from the MATLAB
workspace, but not from the data acquisition engine.
clear obj.Channel(index) removes the specified channels contained by obj
from the MATLAB workspace, but not from the data acquisition engine.
clear obj.Line(index) removes the specified lines contained by obj from the
MATLAB workspace, but not from the data acquisition engine.
Remarks
Clearing device objects, channels, and lines follows these rules:
• clear does not remove device objects, channels, or lines from the data
acquisition engine. Use the delete function for this purpose.
• If multiple references to a device object exist in the workspace, clearing one
reference will not invalidate the remaining references.
• You can restore cleared device objects to the MATLAB workspace with the
daqfind function.
If you use the help command to display the M-file help for clear, then you
must supply the pathname shown below.
help daq/private/clear
9-25
clear
Example
Create the analog input object ai, copy ai to a new variable aicopy, and then
clear the original device object from the MATLAB workspace.
ai = analoginput('winsound');
ch = addchannel(ai,1:2);
aicopy = ai;
clear ai
Retrieve ai from the engine with daqfind, and demonstrate that ai is identical
to aicopy.
ainew = daqfind;
isequal(aicopy,ainew)
ans =
1
See Also
Functions
daqfind, delete
9-26
daqaction
Purpose
9daqaction
An action function that displays event information for the specified event
Syntax
daqaction(obj,event)
Arguments
obj
A device object.
event
A variable that captures the event information contained by
the EventLog property.
Description
daqaction(obj,event) is an example action function that displays
information to the MATLAB command window. For all events, the information
includes the event type and the name of the device object that caused the event
to occur. For events that record the absolute time in EventLog, the event time
is also displayed. For run-time error events, the error message is also
displayed.
Remarks
You specify daqaction as the action function to be executed for any event by
specifying it as the value for the associated action property. For analog input
objects, daqaction is the default value for the DataMissedAction and
RuntimeErrorAction properties. For analog output objects, daqaction is the
default value for the RuntimeErrorAction property.
You can use the showdaqevents function to easily display event information
captured by the EventLog property.
Example
Create the analog input object ai and call the action function daqaction when
a trigger event occurs.
ai = analoginput('winsound');
addchannel(ai,1);
set(ai,'TriggerRepeat',3)
set(ai,'TriggerAction','daqaction')
start(ai)
See Also
Functions
showdaqevents
Properties
DataMissedAction, EventLog, RuntimeErrorAction
9-27
daqfind
Purpose
9daqfind
Return device objects, channels, or lines from the data acquisition engine to the
MATLAB workspace
Syntax
out
out
out
out
Arguments
'PropertyName'
A device object, channel, or line property name.
PropertyValue
A device object, channel, or line property value.
obj
A device object, array of device objects, channels, or lines.
S
A structure with field names that are property names
and field values that are property values.
out
An array or cell array of device objects, channels, or lines.
Description
=
=
=
=
daqfind
daqfind('PropertyName',PropertyValue,...)
daqfind(S)
daqfind(obj,'PropertyName',PropertyValue,...)
out = daqfind returns all device objects that exist in the data acquisition
engine. The output out is an array.
out = daqfind('PropertyName',PropertyValue,...) returns all device
objects, channels, or lines that exist in the data acquisition engine and have the
specified property names and property values. The property name/property
value pairs can be specified as a cell array.
out = daqfind(S) returns all device objects, channels, or lines that exist in
the data acquisition and have the property names and property values
specified by S. S is a structure with field names that are property names and
field values that are property values.
out = daqfind(obj,'PropertyName',PropertyValue,...) returns all device
object, channels, or lines listed by obj that have the specified property names
and property values.
9-28
daqfind
Remarks
More About Finding Device Objects, Channels, or Lines
daqfind is particularly useful in these circumstances:
• A device object is cleared from the MATLAB workspace, and it needs to be
retrieved from the data acquisition engine.
• You need to locate device objects, channels, or lines that have particular
property names and property values.
Rules for Specifying Property Names and Property Values
• You can use property name/property value string pairs, structures, and cell
array pairs in the same call to daqfind. However, in a single call to daqfind,
you can specify only device object properties or channel/line properties.
• You must use the same format as returned by get. For example, if get
returns the ChannelName property value as Left, you must specify Left as
the property value in daqfind (case matters). However, case does not matter
when you specify enumerated property values. For example, daqfind will
find a device object with a Running property value of On or on.
Example
You can use daqfind to return a cleared device object.
ai = analoginput('winsound');
ch = addchannel(ai,1:2);
set(ch,{'ChannelName'},{'Joe';'Jack'})
clear ai
ainew = daqfind;
To return the channel associated with the descriptive name Jack
ch2 = daqfind(ainew,'ChannelName','Jack');
To return the device object with a sampling rate of 8000 Hz and the descriptive
name winsound0-AI, you can pass a structure to daqfind.
S.Name = 'winsound0-AI';
S.SampleRate = 8000;
daqobj = daqfind(S);
See Also
Functions
clear, get, propinfo
9-29
daqhelp
Purpose
Syntax
Arguments
Description
9daqhelp
Display help for device objects, constructors, adaptors, functions, and
properties
daqhelp
out = daqhelp('name')
out = daqhelp(obj)
out = daqhelp(obj,'name')
'name'
A device object, constructor, adaptor, function, or property
name.
obj
A device object.
out
Contains the specified help text.
daqhelp displays a complete listing of Data Acquisition Toolbox constructors
and functions along with a brief description of each.
out = daqhelp('name') returns help for the device object, constructor,
adaptor, function, or property specified by name. The help text is returned to
out.
out = daqhelp(obj) returns a complete listing of functions and properties for
the device object obj to out. Help for obj's constructor is also displayed.
out = daqhelp(obj,'name') returns help for name for the specified device
object obj to out. name can be a constructor, adaptor, property, or function
name.
Remarks
More About Displaying Help
• When displaying property help, the names in the See Also section that
contain all upper-case letters are function names. The names that contain a
mixture of upper and lower-case letters are property names.
• When displaying function help, the See Also section contains only function
names.
9-30
daqhelp
Rules for Specifying Names
For the daqhelp('name') syntax:
• If name is the name of a device object constructor, a complete listing of the
device object’s functions and properties is displayed along with a brief
description of each function and property. The help for the device object's
constructor is also displayed.
• You can display object-specific function information by specifying name as
object/function. For example, to display the help for an analog input object's
getdata function, name is analoginput/getdata.
• You can display object-specific property information by specifying name as
obj.property. For example, to display the help for an analog input object's
SampleRate property, name is analoginput.SampleRate.
For the daqhelp(obj,'name') syntax:
• If name is the name of a device object constructor and the .m extension is
included, the constructor help is displayed.
• If name is the name of a function or property, the function or property help is
displayed.
Example
The following commands are some of the ways you can use daqhelp to obtain
help on device objects, constructors, adaptors, functions, and properties.
daqhelp('analogoutput');
out = daqhelp('analogoutput.m');
daqhelp set
daqhelp analoginput/peekdata
daqhelp analoginput.TriggerDelayUnits
The following commands are some of the ways you can use daqhelp to obtain
information about functions and properties for an existing device object.
ai = analoginput('winsound');
daqhelp(ai,'InitialTriggerTime')
out = daqhelp(ai,'getsample');
See Also
Functions
propinfo
9-31
daqhwinfo
Purpose
9daqhwinfo
Display data acquisition hardware information
Syntax
out
out
out
out
Arguments
'adaptor'
Name of the hardware driver adaptor. The supported
adaptors are nidaq, cbi, hpe1432, and winsound.
obj
A device object or array of device objects.
'FieldName'
A single field name or a cell array of field names.
out
A structure containing the requested hardware information.
Description
=
=
=
=
daqhwinfo
daqhwinfo('adaptor')
daqhwinfo(obj)
daqhwinfo(obj,'FieldName')
out = daqhwinfo returns general hardware-related information as a structure
to out. The returned information includes installed adaptors, the toolbox and
MATLAB version, and the toolbox name.
out = daqhwinfo('adaptor') returns hardware-related information for the
specified adaptor. The returned information includes the adaptor DLL name,
the board names and IDs, and the device object constructor syntax.
out = daqhwinfo(obj) returns hardware-related information for the device
object obj. If obj is an array of device objects, then out is a 1-by-n cell array of
structures where n is the length of obj. The returned information depends on
the device object type, and may include the maximum and minimum sampling
rates, the channel gains, the hardware channel or line IDs, and the vendor
driver version.
out = daqhwinfo(obj,'FieldName') returns the hardware-related
information specified by FieldName for the device object obj. FieldName can be
a single field name or a cell array of field names. out is an m-by-n cell array
where m is the length of obj and n is the length of FieldName. You can return
a list of valid field names with the daqhwinfo(obj) syntax.
9-32
daqhwinfo
Example
To display all installed adaptors
out = daqhwinfo;
out.InstalledAdaptors
ans =
'cbi'
'hpe1432'
'nidaq'
'winsound'
To display the device object constructor names for all installed winsound
devices
out = daqhwinfo('winsound');
out.ObjectConstructorName
ans =
'analoginput('winsound',0)'
'analogoutput('winsound',0)'
Create the analog input object ai for a sound card. To display the input ranges
for ai
ai = analoginput('winsound');
out = daqhwinfo(ai);
out.InputRanges
ans =
-1
1
To display the minimum and maximum sampling rates for ai
out = daqhwinfo(ai,{'MinSampleRate','MaxSampleRate'})
out =
[8000]
[44100]
9-33
daqmem
Purpose
9daqmem
Allocate or display memory resources
Syntax
out = daqmem
out = daqmem(obj)
daqmem(obj,maxmem)
Arguments
obj
A device object or array of device objects.
maxmem
The amount of memory to allocate.
out
A structure containing information about memory resources.
Description
9-34
out = daqmem returns the structure out, which contains several fields
describing the memory resources associated with your platform and the Data
Acquisition Toolbox. The fields are described below.
Field
Description
MemoryLoad
Specifies a number between 0 and 100 that gives a
general idea of current memory utilization. 0 indicates
no memory use and 100 indicates full memory use.
TotalPhys
Indicates the total number of bytes of physical memory.
AvailPhys
Indicates the number of bytes of physical memory
available.
TotalPageFile
Indicates the total number of bytes that can be stored in
the paging file. Note that this number does not represent
the actual physical size of the paging file on disk.
AvailPageFile
Indicates the number of bytes available in the paging
file.
TotalVirtual
Indicates the total number of bytes that can be described
in the user mode portion of the virtual address space of
the calling process.
daqmem
Field
Description
AvailVirtual
Indicates the number of bytes of unreserved and
uncommitted memory in the user mode portion of the
virtual address space of the calling process.
UsedDaq
The total memory used by all device objects.
Note that all the above fields, except for UsedDaq, are identical to the fields
returned by Windows’ MemoryStatus function.
out = daqmem(obj) returns a 1-by-N structure out containing two fields:
UsedBytes and MaxBytes for the device object obj. N is the number of device
objects specified by obj. UsedBytes returns the number of bytes used by obj.
MaxBytes returns the maximum number of bytes that can be used by obj.
daqmem(obj,maxmem) sets the maximum memory that can be allocated for obj
to the value specified by maxmem.
Remarks
More About Allocating and Displaying Memory Resources
• For analog output objects, daqmem(obj,maxmem) controls the value of the
MaxSamplesQueued property.
• If you manually configure the BufferingConfig property, then this value
supersedes the values specified by daqmem(obj,maxmem) and the
MaxSamplesQueued property.
Example
Create the analog input object aiwin for a sound card and the analog input
object aini for a National Instruments board, and add two channels to each
device object.
aiwin = analoginput('winsound');
addchannel(aiwin,1:2);
aini = analoginput('nidaq',1);
addchannel(aini,0:1);
9-35
daqmem
To display the total memory used by all existing device objects
out = daqmem;
out.UsedDaq
ans =
69120
To configure the maximum memory used by aiwin to 640 KB
daqmem(aiwin,640000)
To configure the maximum memory used by each device object with one call to
daqmem
daqmem([aiwin aini],[640000 480000])
See Also
Properties
BufferingConfig, MaxSamplesQueued
9-36
daqpropedit
Purpose
Syntax
Arguments
Description
9daqpropedit
Invoke the property editor graphical user interface
daqpropedit
daqpropedit(obj)
obj
A device object.
daqpropedit(obj) invokes the property editor graphical user interface (GUI)
for the device object obj. The channels or lines contained by obj are displayed
as well.
Remarks
Using daqpropedit, you can perform these tasks for device objects, channels,
and lines:
• List all existing device objects as well as the channels or lines they contain.
This is identical to using the daqfind function.
• Configure property values. This is identical to using the set function or the
dot notation.
• Display the names and current values for configurable properties. This is
identical to using the get function or the dot notation.
• Display property characteristics. This is identical to using the propinfo
function.
• Display property help. This is identical to using the daqhelp function.
Example
Create the analog input object ai for a sound card and add one channel to it.
ai = analoginput('winsound');
addchannel(ai,1:2);
To configure property values for ai using daqpropedit
daqpropedit(ai)
9-37
daqpropedit
The Data Acquisition Property Editor is shown below.
List of device objects, channels,
and lines
Property to configure and its
current value
List of configurable properties
and their current values
Property characteristics
Property help
See Also
Functions
daqfind, daqhelp, get, propinfo, set
9-38
daqread
Purpose
Syntax
Arguments
Description
9daqread
Read a Data Acquisition Toolbox (.daq) file
data = daqread('file')
data = daqread('file','PropertyName',PropertyValue,...)
[data,time] = daqread(...)
[data,time,abstime] = daqread(...)
[data,time,abstime,events] = daqread(...)
[data,time,abstime,events,daqinfo] = daqread(...)
daqinfo = daqread('file','info')
'file'
A Data Acquisition Toolbox (.daq) file.
'PropertyName'
A daqread property name.
PropertyValue
A daqread property value.
'info'
Specifies that device object and hardware
information are to be returned.
data
An m-by-n array where m is the number of samples
and n is the number of channels.
time
An m-by-1 array of relative time values where m is
the number of samples.
abstime
The absolute time of the first trigger.
events
A structure containing event information.
daqinfo
A structure containing device object and hardware
information.
data = daqread('file') reads all the data from file. data is an m-by-n data
matrix where m is the number of samples and n is the number of channels. If
data includes data from multiple triggers, then m is increased by the number
of triggers due to the addition of NaN’s.
9-39
daqread
data = daqread('file','PropertyName',PropertyValue,...) reads the
specified data from file. The amount of data returned and the format of the
data is specified with the properties shown below.
Property Name
Description
Samples
Specify the sample range.
Time
Specify the relative time range.
Triggers
Specify the trigger range.
Channels
Specify the channel range. Channel names can be
specified as a cell array.
DataFormat
Specify the data format as doubles or native.
TimeFormat
Specify the time format as vector or matrix.
The Samples, Time, and Triggers properties are mutually exclusive.
[data,time] = daqread(...) returns sample-time pairs. time is a vector
with the same length as data and contains the relative time for each sample.
Relative time is measured with respect to the first trigger that occurs.
[data,time,abstime] = daqread(...) returns sample-time pairs and the
absolute time of the first trigger. abstime is returned as a clock vector.
[data,time,abstime,events] = daqread(...) returns sample-time pairs,
the absolute time of the first trigger, and a log of events. events contains the
appropriate events based on the Samples, Time, or Triggers value specified.
The entire event log is returned only if Samples, Time, or Triggers is not
specified.
[data,time,abstime,events,daqinfo] = daqread(...) returns
sample-time pairs, the absolute time, the event log, and the structure daqinfo,
which contains two fields: ObjInfo and HwInfo. ObjInfo is a structure
containing property name/property value pairs and HwInfo is a structure
containing hardware information. The entire event log is returned to
daqinfo.ObjInfo.EventLog.
9-40
daqread
daqinfo = daqread('file','info') returns the structure daqinfo, which
contains two fields: ObjInfo and HwInfo. ObjInfo is a structure containing
property name/property value pairs and HwInfo is a structure containing
hardware information. The entire event log is returned to
daqinfo.ObjInfo.EventLog.
Remarks
More About .daq Files
• The format used by daqread to return data, relative time, absolute time, and
event information is identical to the format used by the getdata function.
• If data from multiple triggers is read, then the size of the resulting data
array is increased by the number of triggers issued since each trigger is
separated by a NaN.
• ObjInfo.EventLog always contains the entire event log regardless of the
value specified by Samples, Time, or Triggers.
• Data Acquisition Toolbox (.daq) files are created by specifying a value for the
LogFileName property (or accepting the default value), and configuring the
LoggingMode property to Disk or Disk&Memory.
Example
Suppose you configure the analog input object ai for a National Instruments
board as shown below. The object acquires one second of data for four channels,
and saves the data to the output file data.daq.
ai = analoginput('nidaq',1);
chans = addchannel(ai,0:3);
set(ai,'SampleRate',1000)
ActualRate = get(ai,'SampleRate');
set(ai,'SamplesPerTrigger',ActualRate)
set(ai,'LoggingMode','Disk&Memory')
set(ai,'LogFileName','data.daq')
start(ai)
After the data has been collected and saved to a disk file, you can retrieve the
data and other acquisition-related information using daqread. To read all the
sample-time pairs from data.daq
[data,time] = daqread('data.daq');
9-41
daqread
To read samples 500 to 1000 for all channels from data.daq
data = daqread('data.daq','Samples',[500 1000]);
To read the first 0.5 seconds of data for channels 1 and 2 from data.daq
data = daqread('data.daq','Time',[0 0.5],'Channels',[1 2]);
To obtain the channel property information from data.daq
daqinfo = daqread('data.daq','info');
chaninfo = daqinfo.ObjInfo.Channel;
To obtain a list of event types and event data contained by data.daq
daqinfo = daqread('data.daq','info');
events = daqinfo.ObjInfo.EventLog;
event_type = {events.Type};
event_data = {events.Data};
See Also
Functions
getdata
Properties
EventLog, LogFileName, LoggingMode, LogToDiskMode
9-42
daqregister
Purpose
9daqregister
Register or unregister a hardware driver adaptor
Syntax
daqregister('adaptor')
daqregister('adaptor','unload')
out = daqregister(...)
Arguments
'adaptor'
Name of the hardware driver adaptor. The supported
adaptors are nidaq, cbi, hpe1432, and winsound.
'unload'
Specifies that the hardware driver adaptor is to be unloaded.
out
Captures the message returned by daqregister.
Description
daqregister('adaptor') registers the hardware driver adaptor specified by
adaptor. For third-part adaptors, adaptor must include the full pathname.
daqregister('adaptor','unload’) unregisters the hardware driver adaptor
specified by adaptor. For third-part adaptors, adaptor must include the full
pathname.
out = daqregister(...) captures the resulting message in out.
Remarks
A hardware driver adaptor must be registered so the data acquisition engine
can make use of its services. Unless an adaptor is unloaded, registration is
required only once.
For adaptors that are included with the toolbox, registration occurs
automatically when you first create a device object. However, you may need to
register third-party adaptors manually. In either case, you must install the
associated hardware driver before registration can occur.
Example
The following command registers the sound card adaptor provided with the
toolbox.
daqregister('winsound');
The following command registers the third-party adaptor myadaptor.dll. Note
that you must supply the full pathname to daqregister.
daqregister('D:/MATLABR12/toolbox/daq/myadaptors/
myadaptor.dll');
9-43
daqreset
Purpose
9daqreset
Remove device objects and data acquisition DLLs from memory
Syntax
daqreset
Description
daqreset removes all device objects existing in the engine, and unloads all data
acquisition DLLs loaded by the engine (including the adaptor and engine DLL
files).
You should use daqreset to return MATLAB to the known initial state of
having no device objects and no data acquisition DLLs loaded in memory.
When MATLAB is returned to this state, the data acquisition hardware is
reset.
See Also
Functions
clear, delete
9-44
daqschool
Purpose
9daqschool
Interface for displaying toolbox tutorials
Syntax
daqschool
Description
daqschool launches the Data Acquisition Toolbox Tutorials interface, which is
shown below.
Refer to “Demos” on page 2-13 for a list of demos included with daqschool.
9-45
dec2binvec
Purpose
Syntax
Arguments
Description
9dec2binvec
Convert decimal value to binary vector
out = dec2binvec(dec)
out = dec2binvec(dec,bits)
dec
A decimal value. dec must be nonnegative.
bits
Number of bits used to represent the decimal number.
out
A logical array containing the binary vector.
out = dec2binvec(dec) converts the decimal value dec to an equivalent
binary vector and stores the result as a logical array in out.
out = dec2binvec(dec,bits) converts the decimal value dec to an equivalent
binary vector consisting of at least the number of bits specified by bits.
Remarks
More About Binary Vectors
A binary vector (binvec) is constructed with the least significant bit (LSB) in
the first column and the most significant bit (MSB) in the last column. For
example, the decimal number 23 is written as the binvec value [1 1 1 0 1].
More About Specifying the Number of Bits
• If bits is greater than the minimum number of bits required to represent the
decimal value, then the result is padded with zeros.
• If bits is less than the minimum number of bits required to represent the
decimal value, then the minimum number of required bits is used.
• If bits is not specified, then the minimum number of bits required to
represent the number is used.
Example
To convert the decimal value 23 to a binvec value
dec2binvec(23)
ans =
1
1
9-46
1
0
1
dec2binvec
To convert the decimal value 23 to a binvec value using six bits
dec2binvec(23,6)
ans =
1
1
1
0
1
0
To convert the decimal value 23 to a binvec value using four bits, then the
result uses five bits. This is the minimum number required to represent the
number.
dec2binvec(23,4)
ans =
1
1
1
See Also
0
1
Functions
binvec2dec
9-47
delete
Purpose
9delete
Remove device objects, channels, or lines from the data acquisition engine
Syntax
delete(obj)
delete(obj.Channel(index))
delete(obj.Line(index))
Arguments
obj
A device object or array of device objects.
obj.Channel(index)
One or more channels contained by obj.
obj.Line(index)
One or more lines contained by obj.
Description
delete(obj) removes the device object specified by obj from the engine. If obj
contains channels or lines, they are removed as well. If obj is the last object
accessing the driver, then the driver and associated adaptor are unloaded.
delete(obj.Channel(index)) removes the channels specified by index and
contained by obj from the engine. As a result, the remaining channels may be
reindexed.
delete(obj.Line(index)) removes the lines specified by index and contained
by obj from the engine. As a result, the remaining lines may be reindexed.
Remarks
Deleting device objects, channels, and lines follows these rules:
• delete removes device objects, channels, or lines from the data acquisition
engine but not from the MATLAB workspace. To remove variables from the
workspace, use the clear function.
• If multiple references to a device object exist in the workspace, then
removing one device object from the engine invalidates the remaining
references. These remaining references should be cleared from the
workspace with the clear function.
• If you delete a device object while it is running, then a warning is issued
before it is deleted. You cannot delete a device object while it is logging or
sending data.
You should use delete at the end of a data acquisition session. You can quickly
delete all existing device objects with the command delete(daqfind).
9-48
delete
If you use the help command to display the M-file help for delete, then you
must supply the pathname shown below.
help daq/daqdevice/delete
Example
National Instruments
Create the analog input object ai for a National Instruments board, add
hardware channels 0-7 to it, and make a copy of hardware channels 0 and 1.
ai = analoginput('nidaq',1);
addchannel(ai,0:7);
ch = ai.Channel(1:2);
To delete hardware channels 0 and 1
delete(ch)
These channels are deleted from the data acquisition engine and are no longer
associated with ai. The remaining channels are reindexed such that the
indices begin at 1 and increase monotonically to 6. To delete ai
delete(ai)
Sound Card
Create the analog input object AI1 for a sound card, and configure it to operate
in stereo mode.
AI1 = analoginput('winsound');
addchannel(AI1,1:2);
You can now configure the sound card for mono mode by deleting hardware
channel 2.
delete(AI1.Channel(2))
If hardware channel 1 is deleted instead, an error is returned.
See Also
Functions
clear, daqreset
9-49
digitalio
Purpose
9digitalio
Create a digital I/O object
Syntax
DIO = digitalio('adaptor',ID)
Arguments
'adaptor'
Name of the hardware driver adaptor. The supported
adaptors are nidaq and cbi.
ID
The hardware device identifier.
DIO
The digital I/O object.
Description
DIO = digitalio('adaptor',ID) creates the digital I/O object DIO for the
specified adaptor and for the hardware device with device identifier ID. ID can
be specified as an integer or a string.
Remarks
More About Creating Digital I/O Objects
• When a digital I/O object is created, it does not contain any hardware lines.
To execute the device object, hardware lines must be added with the addline
function.
• You can create multiple digital I/O objects that are associated with a single
digital I/O subsystem. However, you can typically execute only one of them
at a time.
• The digital I/O object exists in the data acquisition engine and in the
MATLAB workspace. If you create a copy of the device object, it references
the original device object in the engine.
• The Name property is automatically assigned a descriptive name that is
produced by concatenating adaptor, ID, and -DIO. You can change this name
at any time.
More About the Hardware Device Identifier
When data acquisition devices are installed, they are assigned a unique
number, which identifies the device in software. The device identifier is
typically assigned automatically and can usually be manually changed using a
vendor-supplied device configuration utility. National Instruments refers to
this number as the device number.
9-50
digitalio
There are two ways you can determine the ID for a particular device:
• Type daqhwinfo('adaptor').
• Execute the vendor-supplied device configuration utility.
Example
To create a digital I/O object for a National Instruments device defined as
device number 1
DIO = digitalio('nidaq',1);
See Also
Functions
addline, daqhwinfo
Properties
Name
9-51
disp
Purpose
9disp
Display summary information for device objects, channels, or lines
Syntax
disp(obj)
disp(obj.Channel(index))
disp(obj.Line(index))
Arguments
obj
A device object.
obj.Channel(index)
One or more channels contained by obj.
obj.Line(index)
One or more lines contained by obj.
Description
disp(obj) displays summary information for the specified device object obj,
and any channels or lines contained by obj. Typing obj at the command line
produces the same summary information.
disp(obj.Channel(index)) displays summary information for the specified
channels contained by obj. Typing obj.Channel(index) at the command line
produces the same summary information.
disp(obj.Line(index)) displays summary information for the specified lines
contained by obj. Typing obj.Line(index) at the command line produces the
same summary information.
Remarks
You can invoke disp by typing the device object at the MATLAB command line
or by excluding the semicolon when creating a device object, when adding
channel or lines, or when configuring property values using the dot notation.
Example
All the commands shown below produce summary information for the device
object AI or the channels contained by AI.
AI = analoginput('winsound')
chans = addchannel(AI,1:2)
AI.SampleRate = 44100
AI.Channel(1).ChannelName = 'CH1'
chans
9-52
flushdata
Purpose
Syntax
Arguments
Description
9flushdata
Remove data from the data acquisition engine
flushdata(obj)
flushdata(obj,'mode')
obj
An analog input object or array of analog input objects.
'mode'
Specifies how much data is removed from the engine.
flushdata(obj) removes all data from the data acquisition engine and resets
the SamplesAvailable property to zero.
flushdata(obj,'mode') removes data from the data acquisition engine
depending on the value of mode. If mode is all, all data is removed from the
engine and the SamplesAvailable property is set to 0. This is the same as
flushdata(obj). If mode is triggers, then data is removed from the engine
only when the data corresponds to an integral number of triggers. triggers is
a valid choice only when the TriggerRepeat property is greater than 0 and the
SamplesPerTrigger property is not inf.
Example
Create the analog input object ai for a National Instruments board and add
hardware channels 0-7 to it.
ai = analoginput('nidaq',1);
addchannel(ai,0:7);
A two-second acquisition is configured and the device object is executed.
set(ai,'SampleRate',2000)
duration = 2;
ActualRate = get(ai,'SampleRate');
set(ai,'SamplesPerTrigger',ActualRate*duration)
start(ai)
Four thousand samples will be acquired for each channel group member. To
extract 1000 samples from the data acquisition engine for each channel
data = getdata(ai,1000);
9-53
flushdata
You can use flushdata to remove the remaining 3000 samples from the data
acquisition engine.
flushdata(ai)
ai.SamplesAvailable
ans =
0
See Also
Functions
getdata
Properties
SamplesAvailable, SamplesPerTrigger, TriggerRepeat
9-54
get
Purpose
Syntax
Arguments
Description
9get
Return device object properties
out = get(obj)
out = get(obj.Channel(index))
out = get(obj.Line(index))
out = get(obj,'PropertyName')
out = get(obj.Channel(index),'PropertyName')
out = get(obj.Line(index),'PropertyName')
get(...)
obj
A device object or array of device objects.
obj.Channel(index)
One or more channels contained by obj.
obj.Line(index)
One or more lines contained by obj.
'PropertyName'
A property name or a cell array of property names.
out = get(obj) returns the structure out, where each field name is the name
of a property of obj and each field contains the value of that property.
out = get(obj.Channel(index)) returns the structure out, where each field
name is the name of a channel property of obj and each field contains the value
of that property.
out = get(obj.Line(index)) returns the structure out, where each field
name is the name of a line property of obj and each field contains the value of
that property.
out = get(obj,'PropertyName') returns the value of the property specified
by PropertyName to out. If PropertyName is replaced by a 1-by-n or n-by-1 cell
array of strings containing property names, then get returns a 1-by-n cell
array of values to out. If obj is an array of data acquisition objects, then out
will be an m-by-n cell array of property values where m is equal to the length
of obj and n is equal to the number of properties specified.
out = get(obj.Channel(index),'PropertyName') returns the value of
PropertyName to out for the specified channels contained by obj. If multiple
9-55
get
channels and multiple property names are specified, then out is an m-by-n cell
array where m is the number of channels and n is the number of properties.
out = get(obj.Line(index),'PropertyName') returns the value of
PropertyName to out for the specified lines contained by obj. If multiple lines
and multiple property names are specified, then out is an m-by-n cell array
where m is the number of lines and n is the number of properties.
get(...) displays all property names and their current values for the specified
device object, channel, or line. Base properties are displayed first followed by
device-specific properties.
Remarks
If you use the help command to display the M-file help for get, then you must
supply the pathname shown below.
help daq/daqdevice/get
Example
Create the analog input object ai for a sound card and configure it to operate
in stereo mode.
ai = analoginput('winsound');
addchannel(ai,1:2);
The commands shown below are some of the ways you can use get to return
property values.
chan = get(ai,'Channel');
out = get(ai,{'SampleRate','TriggerDelayUnits'});
out = get(ai);
get(chan(1),'Units')
get(chan,{'Index','HwChannel','ChannelName'})
See Also
Functions
set, setverify
9-56
getdata
Purpose
Syntax
Arguments
Description
9getdata
Extract data, time, and event information from the data acquisition engine
data = getdata(obj)
data = getdata(obj,samples)
data = getdata(obj,'type')
data = getdata(obj,samples,'type')
[data,time] = getdata(...)
[data,time,abstime] = getdata(...)
[data,time,abstime,events] = getdata(...)
obj
An analog input object.
samples
The number of samples to extract. If samples is not specified,
the number of samples extracted is given by the
SamplesPerTrigger property.
'type'
Specifies the format of the extracted data as double (the
default) or as native.
data
An m-by-n array where m is the number of samples
extracted and n is the number of channels contained by obj.
time
An m-by-1 array of relative time values where m is the
number of samples extracted. Relative time is measured
with respect to the first sample logged by the engine.
abstime
The absolute time of the first trigger returned as a clock
vector. This value is identical to the value stored by the
InitialTriggerTime property.
events
A structure containing a list of events that occurred up to the
time of the getdata call.
data = getdata(obj) extracts the number of samples specified by the
SamplesPerTrigger property for each channel contained by obj. data is an
m-by-n array where m is the number of samples extracted and n is the number
of channels.
data = getdata(obj,samples) extracts the number of samples specified by
samples for each channel contained by obj.
9-57
getdata
data = getdata(obj,'type') extracts data in the specified format. If type is
specified as native, the data is returned in the native data format of the device.
If type is specified as double (the default), the data is returned as doubles.
data = getdata(obj,samples,'type') extracts the number of samples
specified by samples in the format specified by type for each channel contained
by obj.
[data,time] = getdata(...) returns data as sample-time pairs. time is an
m-by-1 array of relative time values where m is the number of samples
returned. Relative time is measured with respect to the first sample logged by
the engine.
[data,time,abstime] = getdata(...) extracts data as sample-time pairs
and returns the absolute time of the trigger. The absolute time is returned as
a clock vector and is identical to the value stored by the InitialTriggerTime
property.
[data,time,abstime,events] = getdata(...) extracts data as sample-time
pairs, returns the absolute time of the trigger, and returns a structure
containing a list of events that occurred up to the getdata call. The possible
events that can be returned are identical to those stored by the EventLog
property.
Remarks
More About getdata
• In most circumstances, getdata returns all requested data and does not miss
any samples. In the unlikely event that the engine cannot keep pace with the
hardware device, it is possible that data is missed. If data is missed, the
DataMissedAction property is called and the device object is stopped.
• getdata is a blocking function since it returns execution control to the
MATLAB workspace only when the requested number of samples are
extracted from the engine for each channel group member.
• You can issue ^C (Control+C) while getdata is blocking. This will not stop
the acquisition but will return control to MATLAB.
• The amount of data that you can extract from the engine is given by the
SamplesAvailable property.
9-58
getdata
More About Extracting Data From the Engine
• Once the requested data is extracted from the engine, the SamplesAvailable
property value is automatically reduced by the number of samples returned.
• If the requested number of samples is greater than the samples to be
acquired, then an error is returned.
• If the requested data is not returned in the expected amount of time, an error
is returned. The expected time to return data is given by the time it takes the
engine to fill one data block plus the time specified by the Timeout property.
• If multiple triggers are included in a single getdata call, a NaN is inserted
into the returned data and time arrays and the absolute time returned is
given by the first trigger.
• MATLAB supports math operations only for the double data type. Therefore,
to use math functions on native data, you must convert it to doubles.
Example
Create the analog input object ai for a National Instruments board and add
hardware channels 0-3 to it.
ai = analoginput('nidaq',1);
addchannel(ai,0:3);
Configure a one second acquisition with SampleRate set to 1000 samples per
second and SamplesPerTrigger set to 1000 samples per trigger.
set(ai,'SampleRate',1000)
set(ai,'SamplesPerTrigger',1000)
start(ai)
The following getdata command blocks execution control until all sample-time
pairs, the absolute time of the trigger, and any events that occurred during the
getdata call are returned.
[data,time,abstime,events] = getdata(ai);
data is returned as a 1000-by-4 array of doubles, time is returned as a
1000-by-1 vector of relative times, abstime is returned as a clock vector, and
events is returned as a 3-by-1 structure array.
9-59
getdata
The three events returned are the start event, the trigger event, and the stop
event. To return specific event information about the stop event, you must
access the Type and Data fields.
EventType = events(3).Type;
EventData = events(3).Data;
See Also
Functions
flushdata, getsample, peekdata
Properties
DataMissedAction, EventLog, SamplesAvailable, SamplesPerTrigger,
Timeout
9-60
getsample
Purpose
9getsample
Immediately acquire one sample
Syntax
sample = getsample(obj)
Arguments
obj
An analog input object.
sample
A row vector containing one sample for each channel
contained by obj.
Description
sample = getsample(obj) immediately returns a row vector containing one
sample for each channel contained by obj.
Remarks
Using getsample is a good way to test your analog input configuration.
Additionally:
• getsample does not store samples in, or extract samples from, the data
acquisition engine.
• You can execute getsample at any time after channels have been added to
obj.
• Except for sound cards, you can use getsample on an analog input object that
is not running (Running is Off). For sound cards, the device object must be
running.
Example
Create the analog input object ai and add eight channels to it.
ai = analoginput('nidaq',1);
ch = addchannel(ai,0:7);
The following command returns one sample for each channel.
sample = getsample(ai);
See Also
Functions
getdata, peekdata
9-61
getvalue
Purpose
Syntax
Arguments
Description
9getvalue
Read values from lines
out = getvalue(obj)
out = getvalue(obj.Line(index))
obj
A digital I/O object.
obj.Line(index)
One or more lines contained by obj.
out
A binary vector.
out = getvalue(obj) returns the current value from all lines contained by
obj as a binary vector to out.
out = getvalue(obj.Line(index)) returns the current value from the lines
specified by obj.Line(index).
Remarks
More About Reading Values from Lines
• By default, out is returned as a binary vector (binvec). A binvec value is
constructed with the least significant bit (LSB) in the first column and the
most significant bit (MSB) in the last column. For example, the decimal
number 23 is written as the binvec value [1 1 1 0 1].
• You can convert a binvec value to a decimal value with the binvec2dec
function.
• If obj contains lines from a port-configurable device, the data acquisition
engine will automatically read from all the lines even if they are not
contained by the device object.
Example
Create the digital I/O object dio and add eight input lines to it.
dio = digitalio('nidaq',1);
lines = addline(dio,0:7,'in');
To return the current values from all lines contained by dio as a binvec value
out = getvalue(dio);
See Also
Functions
binvec2dec
9-62
ischannel
Purpose
9ischannel
Check for channels
Syntax
out = ischannel(obj.Channel(index))
Arguments
obj.Channel(index)
One or more channels contained by obj.
out
A logical value.
Description
out = ischannel(obj.Channel(index)) returns a logical 1 to out if
obj.Channel(index) is a channel. Otherwise, a logical 0 is returned.
Remarks
ischannel does not determine if channels are valid (associated with
hardware). To check for valid channels, use the isvalid function.
Typically, you use ischannel directly only when you are creating your own
M-files.
Example
Suppose you create the function myfunc for use with the Data Acquisition
Toolbox. If myfunc is passed one or more channels as an input argument, then
the first thing you should do in the function is check if the argument is a
channel.
function myfunc(chan)
% Determine if a channel was passed.
if ~ischannel(chan)
error('The argument passed is not a channel.');
end
You can examine the Data Acquisition Toolbox M-files for examples that use
ischannel.
See Also
Functions
isvalid
9-63
isdioline
Purpose
9isdioline
Check for lines
Syntax
out = isdioline(obj.Line(index))
Arguments
obj.Line(index)
One or more lines contained by obj.
out
A logical value.
Description
out = isdioline(obj.Line(index)) returns a logical 1 to out if
obj.Line(index) is a line. Otherwise, a logical 0 is returned.
Remarks
isdioline does not determine if lines are valid (associated with hardware). To
check for valid lines, use the isvalid function.
Typically, you use isdioline directly only when you are creating your own
M-files.
Example
Suppose you create the function myfunc for use with the Data Acquisition
Toolbox. If myfunc is passed one or more lines as an input argument, then the
first thing you should do in the function is check if the argument is a line.
function myfunc(line)
% Determine if a line was passed.
if ~isdioline(line)
error('The argument passed is not a line.');
end
You can examine the Data Acquisition Toolbox M-files for examples that use
isdioline.
See Also
Functions
isvalid
9-64
isvalid
Purpose
9isvalid
Determine if device objects, channels, or lines are valid
Syntax
out = isvalid(obj)
out = isvalid(obj.Channel(index))
out = isvalid(obj.Line(index))
Arguments
obj
A device object or array of device objects.
obj.Channel(index)
One or more channels contained by obj.
obj.Line(index)
One or more lines contained by obj.
out
A logical array.
Description
out = isvalid(obj) returns a logical 1 to out if obj is a valid device object.
Otherwise, a logical 0 is returned.
out = isvalid(obj.Channel(index)) returns a logical 1 to out if the
channels specified by obj.Channel(index) are valid. Otherwise, a logical 0 is
returned.
out = isvalid(obj.Line(index)) returns a logical 1 to out if the lines
specified by obj.Line(index) are valid. Otherwise, a logical 0 is returned.
Remarks
Invalid device objects, channels, and lines are no longer associated with any
hardware and should be cleared from the workspace with the clear function.
Typically, you use isvalid directly only when you are creating your own
M-files.
Example
Create the analog input object ai for a National Instruments board and add
eight channels to it.
ai = analoginput('nidaq',1);
ch = addchannel(ai,0:7);
To verify the device object is valid
isvalid(ai)
ans =
1
9-65
isvalid
To verify the channels are valid
isvalid(ch)'
ans =
1
1
1
1
1
1
1
1
If you delete a channel, then isvalid returns a logical 0 in the appropriate
location
delete(ai.Channel(3))
isvalid(ch)'
ans =
1
1
0
1
1
1
1
1
Typically, you will use isvalid directly only when you are creating your own
M-files. Suppose you create the function myfunc for use with the Data
Acquisition Toolbox. If myfunc is passed the previously defined device object ai
as an input argument
myfunc(ai)
the first thing you should do in the function is check if ai is a valid device
object.
function myfunc(obj)
% Determine if an invalid handle was passed.
if ~isvalid(obj)
error('Invalid data acquisition object passed.');
end
You can examine the Data Acquisition Toolbox M-files for examples that use
isvalid.
See Also
Functions
clear, delete, ischannel, isdioline
9-66
length
Purpose
9length
Return the length of a device object, channel group, or line group
Syntax
out = length(obj)
out = length(obj.Channel)
out = length(obj.Line)
Arguments
obj
A device object or array of device objects.
obj.Channel
The channels contained by obj.
obj.Line
The lines contained by obj.
out
A double.
Description
out = length(obj) returns the length of the device object obj to out.
out = length(obj.Channel) returns the length of the channel group
contained by obj.
out = length(obj.Line) returns the length of the line group contained by
obj.
Example
Create the analog input object ai for a National Instruments board and add
eight channels to it.
ai = analoginput('nidaq',1);
aich = addchannel(ai,0:7);
Create the analog output object ao for a National Instruments board, add one
channel to it, and create the device object array aiao.
ao = analogoutput('nidaq',1);
aoch = addchannel(ao,0);
aiao = [ai ao]
Index:
1
2
Subsystem:
Analog Input
Analog Output
Name:
nidaq1-AI
nidaq1-AO
9-67
length
To find the length of aiao
length(aiao)
ans =
2
To find the length of the analog input channel group
length(aich)
ans =
8
See Also
Functions
size
9-68
load
Purpose
9load
Load device objects, channels, or lines into the MATLAB workspace
Syntax
load file
load file obj1 obj2. . .
out = load('file','obj1','obj2',. . .)
Arguments
file
The MAT-file name.
obj1 obj2... Device objects, an array of device objects, channels, or lines.
out
Description
A structure containing the loaded device objects.
load file returns all variables from the MAT-file file into the MATLAB
workspace.
load file obj1 obj2... returns the specified device objects from the
MAT-file file into the MATLAB workspace.
out = load('file','obj1','obj2',...) returns the specified device objects
from the MAT-file file as a structure to out instead of directly loading them
into the workspace. The field names in out match the names of the loaded
device objects. If no device objects are specified, then all variables existing in
the MAT-file are loaded.
Remarks
Loading device objects follows these rules:
• Unique device objects are loaded into the MATLAB workspace as well as the
engine.
• If a loaded device object already exists in the engine but not the MATLAB
workspace, the loaded device object automatically reconnects to the engine
device object.
• If a loaded device object already exists in the workspace or the engine but has
different properties than the loaded object, then these rules are followed:
- The read-only properties are automatically reset to their default values.
- All other property values are given by the loaded object and a warning is
issued stating that property values of the workspace object have been
updated.
9-69
load
• If the workspace device object is running, then it is stopped before loading
occurs.
• If identical device objects are loaded, then they point to the same device
object in the engine. For example, if you saved the array
x = [ai1 ai1 ai2]
only ai1 and ai2 are created in the engine, and x(1) will equal x(2).
• Values for read-only properties are restored to their default values upon
loading. For example, the EventLog property is restored to an empty vector.
Use the propinfo function to determine if a property is read only.
• Values for the BufferingConfig property when the BufferingMode property
is set to Auto, and the MaxSamplesQueued property may not be restored to the
same value since both these property values are based on available memory.
Note load is not used to read in acquired data that has been saved to a log
file. You should use the daqread function for this purpose.
If you use the help command to display the M-file help for load, then you must
supply the pathname shown below.
help daq/private/load
Example
This example illustrates the behavior of load when the loaded device object has
properties that differ from the workspace object.
ai = analoginput('winsound');
addchannel(ai,1:2);
save ai
ai.SampleRate = 10000;
load ai
Warning: Loaded object has updated property values.
See Also
Functions
daqread, propinfo, save
9-70
makenames
Purpose
9makenames
Generate a list of descriptive channel or line names
Syntax
names = makenames('prefix',index)
Arguments
'prefix'
A string that constitutes the first part of the name.
index
Numbers appended to the end of prefix – any MATLAB
vector syntax can be used to specify index as long as the
numbers are positive.
names
An m-by-1 cell array of channel names where m is the length
of index.
Description
names = makenames('prefix',index) generates a cell array of descriptive
channel or line names by concatenating prefix and index.
Remarks
You can pass names as an input argument to the addchannel or addline
function.
If names contains more than one descriptive name, then the size of names must
agree with the number of hardware channels specified in addchannel, or the
number of hardware lines specified in addline.
If the channels or lines are to be referenced by name, then prefix must begin
with a letter and contain only letters, numbers, and underscores. Otherwise
the names can contain any character.
Example
Create the analog input object AI. You can use makenames to define descriptive
names for each channel that is to be added to AI.
AI = analoginput('nidaq',1);
names = makenames('chan',1:8);
names is an eight-element cell array of channel names chan1, chan2,..., chan8.
You can now pass names as an input argument to the addchannel function.
addchannel(AI,0:7,names);
See Also
Functions
addchannel, addline
9-71
muxchanidx
Purpose
Syntax
Arguments
Description
9muxchanidx
Return multiplexed scanned channel index
scanidx = muxchanidx(obj,muxboard,muxidx)
scanidx = muxchanidx(obj,absmuxidx)
obj
An analog input object associated with a National
Instruments board.
muxboard
The multiplexer board.
muxidx
The index number of the multiplexed channel.
absmuxidx
The absolute index number of the multiplexed channel.
scanidx
The scanning index number of the multiplexed channel.
scanidx = muxchanidx(obj,muxboard,muxidx) returns the scanning index
number of the multiplexed channel specified by muxidx. The multiplexer (mux)
board is specified by muxboard. For each mux board, muxidx can range from
0-31 for differential inputs and 0-63 for single-ended inputs. muxboard and
muxidx are vectors of equal length.
scanidx = muxchanidx(obj,absmuxidx) returns the scanning index number
of the multiplexed channel specified by absmuxidx. absmuxidx is the absolute
index of the channel independent of the mux board.
For single-ended inputs, the first mux board has absolute index values that
range between 0 and 63, the second mux board has absolute index values that
range between 64 and 127, the third mux board has absolute index values that
range between 128 and 191, the fourth mux board has absolute index values
that range between 192 and 255. For example, the absolute index value of the
second single-ended channel on the fourth mux board (muxboard is 4 and
muxidx is 1) is 193.
Remarks
scanidx identifies the column number of the data returned by getdata and
peekdata.
Refer to the AMUX-64T User Manual for more information about adding mux
channels based on hardware channel IDs and the number of mux boards used.
9-72
muxchanidx
Example
Create the analog input object ai for a National Instruments board that is
connected to four AMUX-64T multiplexers, and add 256 channels to ai using
addmuxchannel.
ai = analoginput('nidaq',1);
ai.InputType = 'SingleEnded';
ai.NumMuxBoards = 4;
addmuxchannel(ai);
The following two commands return a scanned index value of 14.
scanidx = muxchanidx(ai,4,1);
scanidx = muxchanidx(ai,193);
See Also
Functions
addmuxchannel
9-73
obj2mfile
Purpose
Syntax
Arguments
Description
9obj2mfile
Convert device objects, channels, or lines to MATLAB code
obj2mfile(obj,'file')
obj2mfile(obj,'file','syntax')
obj2mfile(obj,'file','all')
obj2mfile(obj,'file','syntax','all')
obj
A device object, array of device objects, channels, or lines.
'file'
The file that the MATLAB code is written to. The full
pathname can be specified. If an extension is not specified,
the .m extension is used.
'syntax'
Syntax of the converted MATLAB code. By default, the set
syntax is used. If dot is specified, then the subscripted
referencing syntax is used. If named is specified, then named
referencing is used (if defined).
'all'
If all is specified, all properties are written to file. If all is
not specified, only properties that are not set to their default
values are written to file.
obj2mfile(obj,'file') converts obj to the equivalent MATLAB code using
the set syntax and saves the code to file. By default, only those properties
that are not set to their default values are written to file.
obj2mfile(obj,'file','syntax') converts obj to the equivalent MATLAB
code using syntax and saves the code to file. The values for syntax can be set,
dot, or named. set uses the set syntax, dot uses subscripted assignment (dot
notation), and named uses named referencing (if defined).
obj2mfile(obj,'file','all') converts obj to the equivalent MATLAB code
using the set syntax and saves the code to file. all specifies that all
properties are written to file.
obj2mfile(obj,'file','syntax','all') converts obj including all of obj’s
properties to the equivalent MATLAB code using syntax and saves the code to
file.
9-74
obj2mfile
Remarks
If UserData is not empty or if any of the action properties are set to a cell array
of values, then the data stored in those properties is written to a MAT-file when
the object is converted and saved. The MAT-file has the same name as the
M-file containing the object code (see the example below).
You can recreate the saved device objects by typing the name of the M-file at
the command line. You can also recreate channels or lines, by typing the name
of the M-file with a device object as the only input.
Example
Create the analog input object ai for a sound card, add two channels, and set
values for several properties.
ai = analoginput('winsound');
addchannel(ai,1:2);
set(ai,'Tag','myai','TriggerRepeat',4)
set(ai,'StartAction',{'myaction',2,magic(10)})
The following command writes MATLAB code to the files myai.m and myai.mat.
obj2mfile(ai,'myai.m','dot')
myai.m contains code that recreates the analog input code shown above using
the dot notation for all properties that have their default values changed. Since
StartAction is set to a cell array of values, this property appears in myai.m as
ai.StartAction = startaction;
and is saved in myai.mat as
startaction = {'myaction',2,magic(10)};
To recreate ai and assign the device object to a new variable ainew
ainew = myai;
The associated MAT-file, myai.mat, is automatically loaded.
9-75
peekdata
Purpose
9peekdata
Preview most recent acquired data
Syntax
data = peekdata(obj,samples)
Arguments
obj
An analog input object.
samples
The number of samples to preview for each channel
contained by obj.
data
An m-by-n matrix where m is the number of samples and n is
the number of channels.
Description
data = peekdata(obj,samples) returns the latest number of samples
specified by samples to data.
Remarks
More About Using peekdata
• Unlike getdata, peekdata is a nonblocking function that immediately
returns control to MATLAB. Since peekdata does not block execution
control, data may be missed or repeated.
• peekdata takes a “snapshot” of the most recent acquired data and does not
remove samples from the data acquisition engine. Therefore, the
SamplesAvailable property value is not affected when peekdata is called.
Rules for Using peekdata
• You can call peekdata before a trigger executes. Therefore, peekdata is
useful for previewing data before it is logged to the engine or to a disk file.
• In most cases, you will call peekdata while the device object is running.
However, you can call peekdata once after the device object stops running.
• If samples is greater than the number of samples currently acquired, all
available samples are returned with a warning message stating that the
requested number of samples were not available.
9-76
peekdata
Example
Create the analog input object ai for a National Instruments board, add eight
input channels, and configure ai for a two second acquisition.
ai = analoginput('nidaq',1);
addchannel(ai,0:7);
set(ai,'SampleRate',2000)
set(ai,'SamplesPerTrigger',4000)
After issuing the start function, you can preview the data.
start(ai)
data = peekdata(ai,100);
peekdata returns 100 samples to data for all eight channel group members. If
100 samples are not available, then whatever samples are available will be
returned and a warning message is issued. The data is not removed from the
data acquisition engine.
See Also
Functions
getdata, getsample
Properties
SamplesAvailable
9-77
propinfo
Purpose
Syntax
Arguments
Description
9-78
9propinfo
Return property characteristics for device objects, channels, or lines
out = propinfo(obj)
out = propinfo(obj,'PropertyName')
obj
A device object, channels, or lines.
'PropertyName'
A valid obj property name.
out
A structure whose field names are the property
names for obj (if PropertyName is not specified).
out = propinfo(obj) returns the structure out whose field names are the
property names for obj. Each property name in out contains the fields shown
below.
Field Name
Description
Type
The property data type. Possible values are action
function, any, double, and string.
Constraint
The type of constraint on the property value. Possible
values are action function, bounded, enum, and none.
ConstraintValue
The property value constraint. The constraint can be
a range of valid values or a list of valid string values.
DefaultValue
The property default value.
ReadOnly
If the property is read-only, a 1 is returned.
Otherwise, a 0 is returned.
ReadOnlyRunning
If the property is read-only while the device object is
running, a 1 is returned. Otherwise, a 0 is returned.
DeviceSpecific
If the property is device-specific, a 1 is returned. If a 0
is returned, the property is supported for all device
objects of a given type.
propinfo
out = propinfo(obj,'PropertyName') returns the structure out for the
property specified by PropertyName. If PropertyName is a cell array of strings,
a cell array of structures is returned for each property.
Example
Create the analog input object ai for a sound card and configure it to operate
in stereo mode.
ai = analoginput('winsound');
addchannel(ai,1:2);
To capture all property information for all common ai properties
out = propinfo(ai);
To display the default value for the SampleRate property
out.SampleRate.DefaultValue
ans =
8000
To display all the property information for the InputRange property
propinfo(ai.Channel,'InputRange')
ans =
Type: 'double'
Constraint: 'Bounded'
ConstraintValue: [-1 1]
DefaultValue: [-1 1]
ReadOnly: 0
ReadOnlyRunning: 1
DeviceSpecific: 0
See Also
Functions
daqhelp
9-79
putdata
Purpose
9putdata
Queue data in the engine for eventual output
Syntax
putdata(obj,data)
Arguments
obj
An analog output object.
data
The data to be queued in the engine.
Description
putdata(obj,data) queues the data specified by data in the engine for
eventual output to the analog output subsystem. data must consist of a column
of data for each channel contained by obj.
Remarks
More About Queueing Data
• Data must be queued in the engine before obj is executed.
• putdata is a blocking function since it returns execution control to the
MATLAB workspace only when the requested number of samples are queued
in the engine for each channel group member.
• If the value of the RepeatOutput property is greater than 0, then all queued
data is automatically requeued until the RepeatOutput value is reached.
RepeatOutput must be configured before start is issued.
• After obj executes, you can continue to queue data unless RepeatOutput is
greater than 0.
• You can queue data in the engine until the value specified by the
MaxSamplesQueued property is reached, or the limitations of your hardware
or computer are reached.
More About Outputting Data
• Data is output as soon as a trigger occurs.
• An error is returned if a NaN is included in the data stream.
• You can specify data as the native data type of the hardware. Note that
MATLAB supports math operations only for the double data type. Therefore,
to use math functions on native data, you must convert it to doubles.
• If the output data is not within the range specified by the OutputRange
property, then the data is clipped.
9-80
putdata
• The SamplesOutput property keeps a running count of the total number of
samples that have been output per channel.
• The SamplesAvailable property tells you how many samples are ready to be
output from the engine per channel. After data is output, SamplesAvailable
is automatically reduced by the number of samples sent to the hardware.
Example
Create the analog output object ao for a National Instruments board, add two
output channels to it, and generate 10 seconds of data to be output.
ao = analogoutput('nidaq',1);
ch = addchannel(ao,0:1);
set(ao,'SampleRate',1000)
data = linspace(0,1,10000)';
Before you can output data, it must be queued in the engine using putdata.
putdata(ao,[data data])
start(ao)
See Also
Functions
putsample
Properties
MaxSamplesQueued, OutputRange, RepeatOutput, SamplesAvailable,
SamplesOutput, Timeout, UnitsRange
9-81
putsample
Purpose
9putsample
Immediately output one sample
Syntax
putsample(obj,data)
Arguments
obj
An analog output object.
data
The data to be queued in the engine.
Description
putsample(obj,data) immediately outputs the row vector data, which
consists of one sample for each channel contained by obj.
Remarks
Using putsample is a good way to test your analog output configuration.
Additionally:
• putsample does not store samples in the data acquisition engine.
• putsample can be executed at any time after channels have been added to
obj.
• putsample is not supported for sound cards.
Example
Create the analog output object ao for a National Instruments board and add
two hardware channels to it.
ao = analogoutput('nidaq',1);
ch = addchannel(ao,0:1);
To call putsample for ao
putsample(ao,[1 1])
See Also
Functions
putdata
9-82
putvalue
Purpose
Syntax
Arguments
Description
9putvalue
Write values to lines
putvalue(obj,data)
putvalue(obj.Line(index),data)
obj
A digital I/O object.
obj.Line(index)
One or more lines contained by obj.
data
A decimal value or binary vector.
putvalue(obj,data) writes data to the hardware lines contained by the
digital I/O object obj.
putvalue(obj.Line(index),data) writes data to the hardware lines specified
by obj.Line(index).
Remarks
More About Writing Values to Lines
• You can specify data as either a decimal value or a binary vector. A binary
vector (or binvec) is constructed with the least significant bit (LSB) in the
first column and the most significant bit (MSB) in the last column. For
example, the decimal number 23 is written as the binary vector [1 1 1 0 1].
• If obj contains lines from a port-configurable device, then all lines will be
written to even if they are not contained by the device object.
• An error will be returned if data is written to an input line.
• An error is returned if you attempt to write a negative value.
• If a decimal value is written to a digital I/O object and the value is too large
to be represented by the hardware, then an error is returned.
Example
Create the digital I/O object dio and add four output lines to it.
dio = digitalio('nidaq',1);
lines = addline(dio,0:3,'out');
Write the value 8 as a decimal value and as a binary vector
putvalue(dio,8)
putvalue(dio,[0 0 0 1])
9-83
save
Purpose
Syntax
Arguments
Description
9save
Save device objects to a MAT-file
save file
save file obj1 obj2...
file
The MAT-file name.
obj1 obj2...
One or more device objects or an array of device objects.
save file saves all MATLAB variables to the MAT-file file. If an extension
is not specified for file, then a .MAT extension is used.
save file obj1 obj2... saves the specified device objects to file.
Remarks
Saving device objects follows these rules:
• You can use save in the functional form as well as the command form shown
above. When using the functional form, you must specify the filename and
device objects as strings.
• Samples associated with a device object are not stored in the MAT-file. You
can bring these samples into the MATLAB workspace with the getdata
function, and then save them to the MAT-file using a separate variable
name. You can also log samples to disk by configuring the LoggingMode
property to Disk or Disk&Memory.
• Values for read-only properties are restored to their default values upon
loading. For example, the EventLog property is restored to an empty vector.
Use the propinfo function to determine if a property is read only.
• Values for the BufferingConfig property when the BufferingMode property
is set to Auto, and the MaxSamplesQueued property may not be restored to the
same value since both these property values are based on available memory.
If you use the help command to display the M-file help for save, then you must
supply the pathname shown below.
help daq/private/save
See Also
Functions
getdata, load, propinfo
9-84
set
Purpose
Syntax
Arguments
Description
9set
Configure or display device object properties
set(obj)
props = set(obj)
set(obj,'PropertyName')
props = set(obj,'PropertyName')
set(obj,'PropertyName',PropertyValue,...)
set(obj,PN,PV)
set(obj,S)
obj
A device object, array of device objects, channels, or lines.
'PropertyName'
A property name.
PropertyValue
A property value.
PN
A cell array of property names.
PV
A cell array of property values.
S
A structure whose field names are device object, channel,
or line properties.
props
A structure array whose field names are the property
names for obj, or a cell array of possible values.
set(obj) displays all configurable properties for obj. If a property has a finite
list of possible string values, then these values are also displayed.
props = set(obj) returns all configurable properties to props. props is a
structure array with fields given by the property names, and possible property
values contained in cell arrays. if the property does not have a finite set of
possible values, then the cell array is empty.
set(obj,'PropertyName') displays the valid values for the property specified
by PropertyName. PropertyName must have a finite set of possible values.
props = set(obj,'PropertyName') returns the valid values for
PropertyName to props. props is a cell array of possible values or an empty cell
array if the property does not have a finite set of possible values.
9-85
set
set(obj,'PropertyName',PropertyValue,...) sets multiple property values
with a single statement. Note that you can use structures, property name/
property value string pairs, and property name/property value cell array pairs
in the same call to set.
set(obj,PN,PV) sets the properties specified in the cell array of strings PN to
the corresponding values in the cell array PV. PN must be a vector. PV can be
m-by-n where m is equal to the specified number of device objects, channels, or
lines and n is equal to the length of PN.
set(obj,S) where S is a structure whose field names are device object
properties, sets the properties named in each field name with the values
contained in the structure.
Remarks
If you use the help command to display the M-file help for set, then you must
supply the pathname shown below.
help daq/daqdevice/set
Example
Create the analog input object ai for a sound card and configure it to operate
in stereo mode.
ai = analoginput('winsound');
addchannel(ai,1:2);
To display all of ai’s configurable properties and their valid values
set(ai)
To set the value for the SampleRate property to 10000
set(ai,'SampleRate',10000)
The following two commands set the value for the SampleRate and InputType
properties using one call to set.
set(ai,'SampleRate',10000,'TriggerType','Manual')
set(ai,{'SampleRate','TriggerType'},{10000,'Manual'})
9-86
set
You can also set different channel property values for multiple channels.
ch = ai.Channel(1:2);
set(ch,{'UnitsRange','ChannelName'},{[-1 1] 'Name1'; [-2 2]
'Name2'})
See Also
Functions
get, setverify
9-87
setverify
Purpose
9setverify
Configure and return the specified property
Syntax
Actual = setverify(obj,'PropertyName',PropertyValue)
Actual = setverify(obj.Channel(index),'PropertyName',PropertyValue)
Actual = setverify(obj.Line(index),'PropertyName',PropertyValue)
Arguments
obj
A device object or array of device objects.
'PropertyName'
A property name.
PropertyValue
A property value.
obj.Channel(index)
One or more channels contained by obj.
obj.Line(index)
One or more lines contained by obj.
Actual
The actual value for the specified property.
Description
Actual = setverify(obj,'PropertyName',PropertyValue) sets
PropertyName to PropertyValue for obj, and returns the actual property value
to Actual.
Actual =
setverify(obj.Channel(index),'PropertyName',PropertyValue) sets
PropertyName to PropertyValue for the channels specified by index, and
returns the actual property value to Actual.
Actual = setverify(obj.Line(index),'PropertyName',PropertyValue)
sets PropertyName to PropertyValue for the lines specified by index, and
returns the actual property value to Actual.
Remarks
setverify is equivalent to the commands
set(obj,'PropertyName',PropertyValue)
Actual = get(obj,'PropertyName')
Using setverify is not required for setting property values, but it does provide
a convenient way to verify the actual property value set by the data acquisition
engine.
9-88
setverify
setverify is particularly useful when setting the SampleRate, InputRange,
and OutputRange properties since these properties can only be set to specific
values accepted by the hardware. You can use the propinfo function to obtain
information about the valid values for these properties.
If a property value is specified but does not match a valid value, then:
• If the specified value is within the range of supported values:
- For the SampleRate and InputRange properties, the value is automatically
rounded up to the next highest supported value.
- For all other properties, the value is automatically selected to be the
nearest supported value.
• If the value is not within the range of supported values, an error is returned
and the current property value remains unchanged.
Example
Create the analog input object ai for a National Instruments AT-MIO-16DE-10
board, add eight hardware channels to it, and set the sample rate to 10,000 Hz
using setverify.
ai = analoginput('nidaq',1);
ch = addchannel(ai,0:7);
ActualRate = setverify(ai,'SampleRate',10000);
Suppose you use setverify to set the input range for all channels contained by
ai to -8 to 8 volts.
ActualInputRange = setverify(ai.Channel,'InputRange',[-8 8]);
The InputRange value was actually rounded up to -10 to 10 volts.
ActualInputRange{1}
ans =
-10
10
See Also
Functions
get, propinfo, set
Properties
InputRange, OutputRange, SampleRate
9-89
showdaqevents
Purpose
Syntax
Arguments
Description
9showdaqevents
Display event log information
showdaqevents(obj)
showdaqevents(obj,index)
showdaqevents(struct)
showdaqevents(struct,index)
out = showdaqevents(...)
obj
An analog input or analog output object.
index
The event index.
struct
An event structure.
out
A one column cell array of event information.
showdaqevents(obj) displays a summary of the event log for obj.
showdaqevents(obj,index) displays a summary of the events specified by
index for obj.
showdaqevents(struct) displays a summary of the events stored in the
structure struct.
showdaqevents(struct,index) displays a summary of the events specified by
index stored in the structure struct.
out = showdaqevents(...) outputs the event information to a one column cell
array out. Each element of out is a string that contains the event information
associated with that index value.
Remarks
9-90
You can pass a structure of event information to showdaqevents. This structure
can be obtained from the getdata function, the daqread function, or the
EventLog property.
showdaqevents
Example
Create the analog input object ai for a sound card, add two channels to it, and
configure ai to execute three triggers.
ai = analoginput('winsound');
ch = addchannel(ai,1:2);
set(ai,'TriggerRepeat',2)
Start ai and display the trigger event information with showdaqevents.
start(ai)
showdaqevents(ai,2:4)
2 Trigger#1
3 Trigger#2
4 Trigger#3
See Also
( 17:07:06, 0 )
( 17:07:07, 8000 )
( 17:07:08, 16000 )
Channel: N/A
Channel: N/A
Channel: N/A
Functions
daqread, getdata
Properties
EventLog
9-91
size
Purpose
9size
Return the size of a device object, channel group, or line group
Syntax
d = size(obj)
[m1,m2,m3,...,mn] = size(obj)
m = size(obj,dim)
d = size(obj.Channel)
[m1,m2,m3,...,mn] = size(obj.Channel)
m = size(obj.Channel,dim)
d = size(obj.Line)
[m1,m2,m3,...,mn] = size(obj.Line)
m = size(obj.Line,dim)
Arguments
obj
A device object or array of device objects.
dim
The dimension.
obj.Channel
The channels contained by obj.
obj.Line
The lines contained by obj.
d
A two-element row vector containing the number of rows
and columns in obj.
m1,m2,m3,...,mn Each dimension of obj is captured in a separate variable.
m
Description
The length of the dimension specified by dim.
d = size(obj) returns the two-element row vector d = [m,n] containing the
number of rows and columns in obj.
[m1,m2,m3,...,mn] = size(obj) returns the length of the first n dimensions
of obj to separate output variables. For example, [m,n] = size(obj) returns
the number of rows to m and the number of columns to n.
m = size(obj,dim) returns the length of the dimension specified by the scalar
dim. For example, size(obj,1) returns the number of rows.
d = size(obj.Channel) returns the two-element row vector d = [m,n]
containing the number of rows and columns in the channel group obj.Channel.
9-92
size
[m1,m2,m3,...,mn] = size(obj.Channel) returns the length of the first n
dimensions of the channel group obj.Channel to separate output variables. For
example, [m,n] = size(obj.Channel) returns the number of rows to m and the
number of columns to n.
m = size(obj.Channel,dim) returns the length of the dimension specified by
the scalar dim. For example, size(obj.Channel,1) returns the number of
rows.
d = size(obj.Line) returns the two-element row vector d = [m,n] containing
the number of rows and columns in the line group obj.Line.
[m1,m2,m3,...,mn] = size(obj.Line) returns the length of the first n
dimensions of the line group obj.Line to separate output variables. For
example, [m,n] = size(obj.Line) returns the number of rows to m and the
number of columns to n.
m = size(obj.Line,dim) returns the length of the dimension specified by the
scalar dim. For example, size(obj.Line,1) returns the number of rows.
Example
Create the analog input object ai for a National Instruments board and add
eight channels to it.
ai = analoginput('nidaq',1);
ch = addchannel(ai,0:7);
To find the size of the device object
size(ai)
ans =
1
1
To find the size of the channel group
size(ch)
ans =
8
See Also
1
Functions
length
9-93
start
Purpose
9start
Start a device object
Syntax
start(obj)
Arguments
obj
Description
start(obj) initiates the execution of the device object obj.
Remarks
When start is issued for an analog input or analog output object:
A device object or an array of device objects.
• The M-file action function specified for StartAction is executed.
• The Running property is set to On.
• The start event is recorded in the EventLog property.
• Data existing in the engine is flushed.
Although an analog input or analog output object may be executing, data
logging or sending is not necessarily initiated. Data logging or sending requires
a trigger event to occur, and depends on the TriggerType property value.
For any device object, you can specify start as the value for an action property.
ai.StopAction = 'start';
Note You typically execute a digital I/O object to periodically update and
display its state. Refer to the diopanel demo for an example of this.
See Also
Functions
stop, trigger
Properties
EventLog, Running, Sending, TriggerType
9-94
stop
Purpose
9stop
Stop a device object
Syntax
stop(obj)
Arguments
obj
Description
stop(obj) terminates the execution of the device object obj.
Remarks
An analog input object automatically stops when the requested samples are
acquired or data is missed. An analog output object automatically stops when
the queued data is output. These two device objects can also stop executing
under one of these conditions:
A device object or an array of device objects.
• The Timeout property value is reached.
• A run-time error occurs.
For analog input objects, stop must be used when the TriggerRepeat property
or SamplesPerTrigger property is set to inf. For analog output objects, stop
must be used when the RepeatOutput property is set to inf. When stop is
issued for either of these device objects:
• The Running property is set to Off.
• The Logging property or Sending property is set to Off.
• The M-file action function specified for StopAction is executed.
• The stop event is recorded in the EventLog property.
For any device object, you can specify stop as the value for an action property.
ao.TimerAction = 'stop';
Note Issuing stop is the only way to stop an executing digital I/O object. You
typically execute a digital I/O object to periodically update and display its
state. Refer to the diopanel demo for an example.
9-95
stop
See Also
Functions
start, trigger
Properties
EventLog, Logging, RepeatOutput, Running, SamplesPerTrigger, Sending,
Timeout, TriggerRepeat
9-96
trigger
Purpose
9trigger
Manually execute a trigger
Syntax
trigger(obj)
Arguments
obj
Description
trigger(obj) manually executes a trigger.
Remarks
After trigger is issued:
An analog input or analog output object or an array of these
device objects.
• The absolute time of the trigger event is recorded by the
InitialTriggerTime property.
• The Logging property or Sending property is set to On.
• The M-file action function specified by TriggerAction is executed.
• The trigger event is recorded in the EventLog property.
You can issue trigger only if TriggerType is set to Manual, Running is On, and
Logging is Off.
You can specify trigger as the value for an action property.
ai.StartAction = 'trigger';
See Also
Functions
start, stop
Properties
InitialTriggerTime, Logging, Running, Sending, TriggerAction,
TriggerType
9-97
waittilstop
Purpose
9waittilstop
Wait for the device object to stop running
Syntax
waittilstop(obj,waittime)
Arguments
obj
A device object or an array of device objects.
waittime
The maximum time to wait for obj to stop running.
Description
waittilstop(obj,waittime) blocks the MATLAB command line, and waits
for obj to stop running. You specify the maximum waiting time, in seconds,
with waittime. waittime overrides the value specified for the Timeout
property. If obj is an array of device objects, then waittilstop may wait up to
the specified time for each device object in the array.
waittilstop is particularly useful if you want to guarantee that the specified
data is acquired before another task is performed.
Remarks
If obj is not running when waittilstop is issued, or if an error occurs while
obj is running, then waittilstop immediately relinquishes control of the
command line.
When obj stops running, its Running property is automatically set to Off. obj
can stop running under one of the these conditions:
• The requested number of samples is acquired (analog input) or sent out
(analog output).
• The stop function is issued.
• A run-time error occurs.
• The Timeout property value is reached (waittime supersedes this value).
It is not guaranteed that the StopAction property is called before
waittilstop returns. The stop action event is recorded by the EventLog
property.
9-98
waittilstop
Example
Create the analog input object ai for a National Instruments board, add eight
channels to it, and configure a 25 second acquisition.
ai = analoginput('nidaq',1);
ch = addchannel(ai,0:7);
ai.SampleRate = 2000;
ai.TriggerRepeat = 4;
ai.SamplesPerTrigger = 10000;
You can use waittilstop to block the MATLAB command line until all the
requested data is acquired. Since the expected acquisition time is 25 seconds,
the waittime argument is 26. If the acquisition does not complete within this
time, then a timeout occurs.
start(ai)
waittilstop(ai,26)
See Also
Properties
EventLog, Running, StopAction, Timeout
9-99
waittilstop
9-100
10
Base Property Reference
Overview . . . . . . . . . . . . . . . . . . . . . 10-2
Getting Command Line Property Help . . . . . . . . . . 10-2
Properties Grouped by Category
Analog Input Properties . . . . .
Analog Output Properties . . . .
Digital I/O Properties . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 10-3
. 10-3
. 10-8
10-12
Properties Listed Alphabetically . . . . . . . . . . 10-14
10
Base Property Reference
Overview
This section provides descriptions of all toolbox base properties. Base
properties apply to all supported hardware subsystems of a given type (analog
input, analog output, etc.). For example, the SampleRate property is supported
for all analog input subsystems regardless of the vendor.
In “Properties Grouped by Category” on page 10-3, the properties are
summarized according to subsystem type and usage. In “Properties Listed
Alphabetically” on page 10-14, the properties are described in detail.
Getting Command Line Property Help
To get command line property help, you should use the daqhelp function. For
example, to get help for the SampleRate property
daqhelp SampleRate
Note You can use daqhelp without creating a device object.
You can also get property characteristics, such as the default property value,
using the propinfo function. For example, suppose you create the analog input
object ai for a sound card and you want to find the default value for the
SampleRate property.
ai = analoginput('winsound');
out = propinfo(ai,'SampleRate');
out.DefaultValue
ans =
8000
10-2
Properties Grouped by Category
Properties Grouped by Category
This section contains brief descriptions of all toolbox base properties. The
properties are categorized according to these subsystems:
• Analog input properties
• Analog output properties
• Digital I/O properties
Depending on the hardware device you are using, additional property names or
property values may be present. The additional property names are described
in Chapter 11, “Device-Specific Property Reference.” For example, only analog
input and analog output objects associated with a sound card have a
BitsPerSample property. The additional property values are also
device-specific but are included in this chapter. For example, all supported
devices have an InputType property, but the value AC-Coupled is unique to
analog input objects associated with a sound card.
Analog Input Properties
Analog input base properties are divided into two main categories: common
properties and channel properties. Common properties apply to every channel
contained by the analog input object, while channel properties can be
configured for individual channels.
Common Properties
The analog input common properties are grouped into the following categories
based on usage.
Analog Input Basic Setup Properties
SamplesPer
Trigger
Specify the number of samples to acquire for each
channel group member for each trigger that occurs.
SampleRate
Specify the per-channel rate at which analog data is
converted to digital data.
TriggerType
Specify the type of trigger to execute.
10-3
10
Base Property Reference
Analog Input Logging Properties
LogFileName
Specify the name of the disk file to which information
is logged.
Logging
Indicate if data is being logged to memory or to a disk
file.
LoggingMode
Specify the destination for acquired data.
LogToDiskMode
Specify whether data, events, and hardware
information are saved to one disk file or to multiple
disk files.
Analog Input Trigger Properties
10-4
InitialTrigger
Time
Indicate the absolute time of the first trigger.
ManualTrigger
HwOn
Specify that the hardware device starts when a
manual trigger is issued.
TriggerAction
Specify the M-file action function to execute when a
trigger occurs.
TriggerChannel
Specify the channels serving as trigger sources.
TriggerCondition
Specify the condition that must be satisfied before a
trigger executes.
TriggerCondition
Value
Specify one or more voltage values that must be
satisfied before a trigger executes.
TriggerDelay
Specify the delay value for data logging.
TriggerDelay
Units
Specify the units in which trigger delay data is
measured.
Properties Grouped by Category
Analog Input Trigger Properties (Continued)
TriggerRepeat
Specify the number of additional times the trigger
executes.
TriggersExecuted
Indicate the number of triggers that execute.
TriggerType
Specify the type of trigger to execute.
Analog Input Status Properties
Logging
Indicate if data is being logged to memory or to a disk
file.
Running
Indicate if the device object is running.
SamplesAcquired
Indicate the number of samples acquired per
channel.
SamplesAvailable
Indicate the number of samples available per
channel in the engine.
Analog Input Hardware Configuration Properties
ChannelSkew
Specify the time between consecutive scanned
hardware channels.
ChannelSkewMode
Specify how the channel skew is determined.
ClockSource
Specify the clock used to govern the hardware
conversion rate.
InputType
Specify the analog input hardware channel
configuration.
SampleRate
Specify the per-channel rate at which analog data is
converted to digital data.
10-5
10
Base Property Reference
Analog Input Action Properties
10-6
DataMissedAction
Specify the M-file action function to execute when
data is missed.
InputOverRange
Action
Specify the M-file action function to execute when
acquired data exceeds the valid hardware range.
RuntimeError
Action
Specify the M-file action function to execute when a
run-time error occurs.
SamplesAcquired
Action
Specify the M-file action function to execute every
time a predefined number of samples is acquired for
each channel group member.
SamplesAcquired
ActionCount
Specify the number of samples to acquire for each
channel group member before a samples acquired
event is generated.
StartAction
Specify the M-file action function to execute just
before the device object starts running.
StopAction
Specify the M-file action function to execute just after
the device object stops running.
TimerAction
Specify the M-file action function to execute
whenever a predefined period of time passes.
TimerPeriod
Specify the period of time between timer events.
TriggerAction
Specify the M-file action function to execute when a
trigger occurs.
Properties Grouped by Category
Analog Input General Purpose Properties
BufferingConfig
Specify the per-channel allocated memory.
BufferingMode
Specify how memory is allocated.
Channel
Contain hardware channels added to the device
object.
EventLog
Store information for specific events.
Name
Specify a descriptive name for the device object.
Tag
Specify a device object label.
Timeout
Specify an additional waiting time to extract data.
Type
Indicate the device object type.
UserData
Store data that you want to associate with a device
object.
Channel Properties
The analog input channel properties are given below.
Analog Input Channel Properties
ChannelName
Specify a descriptive channel name.
HwChannel
Specify the hardware channel ID.
Index
Indicate the MATLAB index of a hardware channel.
InputRange
Specify the range of the analog input subsystem.
NativeOffset
Indicate the offset to use when converting data from
native format to doubles.
NativeScaling
Indicate the scaling to use when converting data
from native format to doubles.
10-7
10
Base Property Reference
Analog Input Channel Properties (Continued)
Parent
Indicate the parent (device object) of a channel.
SensorRange
Specify the range of data you expect from your
sensor.
Type
Indicate a channel.
Units
Specify the engineering units label.
UnitsRange
Specify the range of data as engineering units.
Analog Output Properties
Analog output base properties are divided into two main categories: common
properties and channel properties. Common properties apply to every channel
contained by the analog output object, while channel properties can be
configured for individual channels.
Common Properties
The analog output common properties are grouped into the following categories
based on usage.
Analog Output Basic Setup Properties
SampleRate
Specify the per-channel rate at which digital data is
converted to analog data.
TriggerType
Specify the type of trigger to execute.
Analog Output Trigger Properties
10-8
InitialTrigger
Time
Indicate the absolute time of the first trigger.
TriggerAction
Specify the M-file action function to execute when a
trigger occurs.
Properties Grouped by Category
Analog Output Trigger Properties (Continued)
TriggersExecuted
Indicate the number of triggers that execute.
TriggerType
Specify the type of trigger to execute.
Analog Output Status Properties
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 to the hardware device.
Analog Output Hardware Configuration Properties
ClockSource
Specify the clock used to govern the hardware
conversion rate.
SampleRate
Specify the per-channel rate at which digital data is
converted to analog data.
Analog Output Data Management Properties
MaxSamplesQueued
Indicate the maximum number of samples that can
be queued in the engine.
10-9
10
Base Property Reference
Analog Output Data Management Properties (Continued)
RepeatOutput
Specify the number of additional times queued data
is output.
Timeout
Specify an additional waiting time to queue data.
Analog Output Action Properties
10-10
RuntimeError
Action
Specify the M-file action function to execute when a
run-time error occurs.
SamplesOutput
Action
Specify the M-file action function to execute every
time a predefined number of samples is output for
each channel group member.
SamplesOutput
ActionCount
Specify the number of samples to output for each
channel group member before a samples output event
is generated.
StartAction
Specify the M-file action function to execute just
before the device object starts running.
StopAction
Specify the M-file action function to execute just after
the device object stops running.
TimerAction
Specify the M-file action function to execute
whenever a predefined period of time passes.
TimerPeriod
Specify the period of time between timer events.
TriggerAction
Specify the M-file action function to execute when a
trigger occurs.
Properties Grouped by Category
Analog Output General Purpose Properties
BufferingConfig
Specify the per-channel allocated memory.
BufferingMode
Specify how memory is allocated.
Channel
Contain hardware channels added to the device
object.
EventLog
Store information for specific events.
Name
Specify a descriptive name for the device object.
OutOfDataMode
Specify how the value held by the analog output
subsystem is determined.
Tag
Specify a device object label.
Type
Indicate the device object type.
UserData
Store data that you want to associate with a device
object.
Channel Properties
The analog output channel properties are given below.
Analog Output Channel Properties
ChannelName
Specify a descriptive channel name.
DefaultChannel
Value
Specify the value held by the analog output
subsystem.
HwChannel
Specify the hardware channel ID.
Index
Indicate the MATLAB index of a hardware channel.
NativeOffset
Indicate the offset to use when converting data from
native format to doubles.
10-11
10
Base Property Reference
Analog Output Channel Properties (Continued)
NativeScaling
Indicate the scaling to use when converting data
from native format to doubles.
OutputRange
Specify the range of the analog output hardware
subsystem.
Parent
Indicate the parent (device object) of a channel.
Type
Indicate a channel.
Units
Specify the engineering units label.
UnitsRange
Specify the range of data as engineering units.
Digital I/O Properties
Digital I/O base properties are divided into two main categories: common
properties and line properties. Common properties apply to every line
contained by the digital I/O object, while line properties can be configured for
individual lines.
Common Properties
The digital I/O common properties are given below.
Digital I/O Common Properties
10-12
Line
Contain hardware lines added to the device object.
Name
Specify a descriptive name for the device object.
Running
Indicate if the device object is running.
Tag
Specify a device object label.
TimerAction
Specify the M-file action function to execute
whenever a predefined period of time passes.
TimerPeriod
Specify the period of time between timer events.
Properties Grouped by Category
Digital I/O Common Properties (Continued)
Type
Indicate the device object type.
UserData
Store data that you want to associate with a device
object.
Line Properties
The digital I/O line properties are given below.
Digital I/O Line Properties
Direction
Specify whether a line is used for input or output.
HwLine
Specify the hardware line ID.
Index
Indicate the MATLAB index of a hardware line.
LineName
Specify a descriptive line name.
Parent
Indicate the parent (device object) of a line.
Port
Specify the port ID.
Type
Indicate a line.
10-13
10
Base Property Reference
Properties Listed Alphabetically
This section contains detailed descriptions of all toolbox device-specific
properties. Each property reference page contains some or all of this
information:
• The property name
• A description of the property
• The property characteristics, including:
- Usage – the device objects the property can be used with, and whether it
is a common property, or a channel or line property
Common properties apply to all channels or lines contained by the device
object, while channel (line) properties can be set on a per-channel
(per-line) basis. The device objects supported by the Data Acquisition
Toolbox include analog input (AI), analog output (AO), and digital I/O
(DIO) objects.
- Access – whether the property is read/write or read-only
Read/write property values can be returned with the get command and
configured with the set command. Read-only property values can be
returned with the get command but cannot be configured with the set
command.
- Data type – the property data type
The supported data types include action function, double, string, Channel,
Line, and any.
- Read-only when running – whether a property value can be configured
when the device object is running
• Valid property values including the default value
When property values are given by a predefined list, the default value is
usually indicated by {} (curly braces). Default values for some properties are
calculated by the data acquisition engine, while others are determined by the
hardware driver. If there are device-specific values, they are listed
separately.
• An example using the property
• Related properties and functions
10-14
BufferingConfig
10Alphabetical Listing of Base Properties
Purpose
Specify the per-channel allocated memory
Description
BufferingConfig is a two-element vector that specifies the per-channel
allocated memory. The first element of the vector specifies the block size, while
the second element of the vector specifies the number of blocks. The total
allocated memory (in bytes) is given by
10BufferingConfig
(block size).(number of blocks).(number of channels).(native data type)
You can determine the native data type with daqhwinfo.
You can allocate memory automatically or manually. If BufferingMode is Auto,
the BufferingConfig values are automatically set by the engine. If
BufferingMode is Manual, then you must manually set the BufferingConfig
values. If you change the BufferingConfig values, BufferingMode is
automatically set to Manual.
When memory is automatically allocated by the engine, the block-size value
depends on the sampling rate and is typically a binary number. The number of
blocks is initially set to a value of 30 but can dynamically increase to
accommodate the memory requirements. In most cases, the number of blocks
used results in a per-channel memory that is somewhat greater than the
SamplesPerTrigger value. When you manually allocate memory, the number
of blocks is not dynamic and care must be taken to ensure there is sufficient
memory to store the acquired data. If the number of samples acquired or
queued exceeds the allocated memory, then an error is returned.
You can easily determine the memory allocated and available memory for each
device object with the daqmem function.
Characteristics
Usage
AI, AO, Common
Access
Read/write
Data type
Two-element vector of doubles
Read-only
when running
Yes
10-15
BufferingConfig
Values
The default value is determined by the engine, and is based on the number of
channels contained by the device object and the sampling rate. The
BufferingMode value determines whether the values are automatically
updated as data is acquired. For analog output objects, the default number of
blocks is zero.
Example
Create the analog input object ai for a sound card and add two channels to it.
ai = analoginput('winsound');
addchannel(ai,1:2);
The block size and number of blocks are given by BufferingConfig, while the
native data type for the sound card is given by daqhwinfo.
ai.BufferingConfig
ans =
512
30
out = daqhwinfo(ai);
out.NativeDataType
ans =
int16
With this information, the total allocated memory is calculated to be 61,440
bytes. This number is stored by daqmem.
out = daqmem(ai);
out.UsedBytes
ans =
61440
The allocated memory is more than sufficient to store 8000 two-byte samples
for two channels. If more memory was required, then the number of blocks
would dynamically grow since BufferingMode is set to Auto.
See Also
Functions
daqhwinfo, daqmem
Properties
BufferingMode, SampleRate, SamplesPerTrigger
10-16
BufferingMode
Purpose
10BufferingMode
Description
BufferingMode can be set to Auto or Manual. If BufferingMode is set to Auto,
the data acquisition engine automatically allocates the required memory. If
BufferingMode is set to Manual, you must manually allocate memory with the
BufferingConfig property.
Specify how memory is allocated
If BufferingMode is set to Auto and the SampleRate value is changed, then the
BufferingConfig values may be recalculated by the engine. Specifically, you
can increase (decrease) the block size if SampleRate is increased (decreased). If
BufferingMode is set to Auto and you change the BufferingConfig values,
then BufferingMode is automatically set to Manual. If BufferingMode is set to
Manual, then you cannot set the number of blocks to a value less than three.
For most data acquisition applications, you should set BufferingMode to Auto
and have memory allocated by the engine since this minimizes the chance of an
out-of-memory condition.
Characteristics
Values
See Also
Usage
AI, AO, Common
Access
Read/write
Data type
String
Read-only
when running
Yes
{Auto}
Memory is allocated by the data acquisition engine.
Manual
Memory is allocated manually.
Functions
daqmem
Properties
BufferingConfig
10-17
Channel
Purpose
10Channel
Description
Channel is a vector of all the hardware channels contained by an analog input
(AI) or analog output (AO) object. Since a newly created AI or AO object does
not contain hardware channels, Channel is initially an empty vector. The size
of Channel increases as channels are added with the addchannel function, and
decreases as channels are removed using the delete function.
Contain hardware channels added to a device object
Channel is used to reference one or more individual channels. To reference a
channel, you must know its MATLAB index, which is given by the Index
property. For example, you must use Channel with the appropriate indices
when configuring channel property values.
For scanning hardware, the scan order follows the MATLAB index. Therefore,
the hardware channel associated with index 1 is sampled first, the hardware
channel associated with index 2 is sampled second, and so on. To change the
scan order, you can specify a permutation of the indices with Channel.
Characteristics
Usage
AI, AO, Common
Access
Read/write
Data type
Vector of channels
Read-only
when running
Yes
Values
Values are automatically defined when channels are added to the device object
with the addchannel function. The default value is an empty column vector.
Example
Create the analog input object ai for a National Instruments card and add
three hardware channels to it.
ai = analoginput('nidaq',1);
addchannel(ai,0:2);
To set a property value for the first channel added (ID = 0), you must reference
the channel by its index using the Channel property.
chans = ai.Channel(1);
set(chans,'InputRange',[-10 10])
10-18
Channel
Based on the current configuration, the hardware channels are scanned in
order from 0 to 2. To swap the scan order of channels 0 and 1, you can specify
the appropriate permutation of the MATLAB indices with Channel.
ai.Channel([1 2 3]) = ai.Channel([2 1 3]);
See Also
Functions
addchannel, delete
Properties
HwChannel, Index
10-19
ChannelName
Purpose
10ChannelName
Description
ChannelName specifies a descriptive name for a hardware channel. If a channel
name is defined, then you can reference that channel by its name. If a channel
name is not defined, then the channel must be referenced by its index. Channel
names are not required to be unique.
Specify a descriptive channel name
You can also define descriptive channel names when channels are added to a
device object with the addchannel function.
Characteristics
Usage
AI, AO, Channel
Access
Read/write
Data type
String
Read-only
when running
Yes
Values
The default value is an empty string. To reference a channel by name, it must
contain only letters, numbers, and underscores and must begin with a letter.
Example
Create the analog input object ai for a sound card and add two channels to it.
ai = analoginput('winsound');
addchannel(ai,1:2);
To assign a descriptive name to the first channel contained by ai
Chan1 = ai.Channel(1)
set(Chan1,'ChannelName','Joe')
You can now reference this channel by name instead of by index.
set(ai.Joe,'Units','Decibels')
See Also
Functions
addchannel
10-20
ChannelSkew
Purpose
10ChannelSkew
Description
ChannelSkew applies only to scanning hardware and not to simultaneous
sample and hold (SS/H) hardware.
Specify the time between consecutive scanned hardware channels
For scanning hardware, ChannelSkew is configurable only when
ChannelSkewMode is set to Manual. If ChannelSkewMode is set to Minimum or
Equisample, then ChannelSkew is automatically set to the appropriate
device-specific read-only value. For SS/H hardware, the only valid
ChannelSkew value is zero. SS/H hardware includes Agilent Technologies
devices and sound cards.
The ChannelSkew value is specified in seconds.
Characteristics
Values
See Also
Usage
AI, Common
Access
Read/write (depends on ChannelSkewMode value)
Data type
Double
Read-only
when running
Yes
For all supported hardware, the default value is zero. For SS/H hardware, the
only valid value is zero. For scanning hardware, the value depends on
ChannelSkewMode.
Properties
ChannelSkewMode
10-21
ChannelSkewMode
Purpose
10ChannelSkewMode
Description
For simultaneous sample and hold (SS/H) hardware, ChannelSkewMode is None.
For scanning hardware, ChannelSkewMode can be Minimum, Equisample, or
Manual (National Instruments only). SS/H hardware includes Agilent
Technologies devices and sound cards, while scanning hardware includes most
National Instruments and ComputerBoards devices. Note that some supported
boards from these vendors are SS/H. Examples include the 6110E board and
the DAS4020/12 board, respectively.
Specify how the channel skew is determined
If ChannelSkewMode is Minimum, then the minimum channel skew supported by
the hardware is used. If ChannelSkewMode is Equisample, the channel skew is
given by [(sampling rate)(number of channels)]-1. If ChannelSkewMode is
Manual, then you must specify the channel skew with the ChannelSkew
property.
Characteristics
Values
10-22
Usage
AI, Common
Access
Read/write
Data type
String
Read-only
when running
Yes
National Instruments
{Minimum}
The channel skew is set to the minimum supported
value.
Equisample
The channel skew is given by [(sampling rate)(number of
channels)]-1.
Manual
The channel skew is given by ChannelSkew.
ChannelSkewMode
ComputerBoards
{Minimum}
The channel skew is set to the minimum supported
value.
Equisample
The channel skew is given by [(sampling rate)(number of
channels)]-1.
Agilent Technologies and Sound Cards
{None}
See Also
This is the only supported value for SS/H hardware.
Properties
ChannelSkew, SampleRate
10-23
ClockSource
Purpose
10ClockSource
Description
For all supported hardware except ComputerBoards analog output
subsystems, ClockSource can be set to Internal, which specifies that the
acquisition rate is governed by the internal hardware clock.
Specify the clock used to govern the hardware conversion rate
For subsystems without a hardware clock, you must use software clocking to
govern the sampling rate. Software clocking allows a maximum sampling rate
of 500 Hz and a minimum sampling rate of 0.0002 Hz. An error is returned if
more than 1 sample of jitter is detected. Note that you may not be able to attain
rates over 100 Hz on all systems, especially Windows 9X.
Characteristics
Values
Usage
AI, AO, Common
Access
Read/write
Data type
String
Read-only
when running
Yes
National Instruments
{Internal}
The internal hardware clock is used.
External
Externally control the channel clock (AO only).
ExternalSample
Ctrl
Externally control the channel clock. This value
overrides the ChannelSkew property value (AI only).
ExternalScan
Ctrl
Externally control the scan clock. This value overrides
the SampleRate property value (AI only).
ExternalSample
AndScanCtrl
Externally control the channel and scan clocks. This
value overrides the ChannelSkew and SampleRate
property values (AI only).
For an analog output object, a ClockSource value of Internal is analogous to
a value of Update.
10-24
ClockSource
ComputerBoards
{Internal}
The internal hardware clock is used (AI only).
Software
The computer clock is used.
External
Externally control the channel clock (AI only).
Agilent Technologies
{Internal}
The internal hardware clock is used.
External
The external sample clock, positive true.
Inverted
External
The external sample clock, negative true.
VXIBus/3
The VXI bus clock, divided by 3, provided by some other
clock master
VXIBusSample
The VXI bus sample clock
Sound Cards
{Internal}
See Also
The internal hardware clock is used.
Properties
ChannelSkew, SampleRate
10-25
DataMissedAction
Purpose
10DataMissedAction
Description
A data missed event is generated immediately after acquired data is missed.
This event executes the action function specified for DataMissedAction. The
default value for DataMissedAction is daqaction, which displays the event
type and the device object name.
Specify the M-file action function to execute when data is missed
In most cases, data is missed because:
• The engine cannot keep up with the rate of acquisition.
• The driver wrote new data into the hardware’s FIFO buffer before the
previously acquired data was read. You can usually avoid this problem by
increasing the size of the memory block with the BufferingConfig property.
Data missed event information is stored in the Type and Data fields of the
EventLog property. The Type field value is DataMissed. The Data field value is
RelSample, which is the last sample acquired when the event occurred.
When a data missed event occurs, the analog input object is automatically
stopped.
Characteristics
Usage
AI, Common
Access
Read/write
Data type
String
Read-only
when running
No
Values
The default value is daqaction.
See Also
Functions
daqaction
Properties
EventLog
10-26
DefaultChannelValue
Purpose
10DefaultChannelValue
Description
DefaultChannelValue specifies the value to write to the analog output (AO)
subsystem when data is finished being output from the engine.
Specify the value held by the analog output subsystem
DefaultChannelValue is used only when OutOfDataMode is set to
DefaultValue. This property guarantees that a known value is held by the AO
subsystem if a run-time error occurs. Note that sound cards do not have an
OutOfDataMode property.
Characteristics
Usage
AO, Channel
Access
Read/write
Data type
Double
Read-only
when running
Yes
Values
The default value is zero.
Example
Create the analog output object ao and add two channels to it.
ao = analogoutput('nidaq',1);
addchannel(ao,0:1);
You can configure ao so that when it stops outputting data, a value of 1 volt is
held for both channels.
ao.OutOfDataMode = 'DefaultValue';
ao.Channel.DefaultChannelValue = 1.0;
See Also
Properties
OutOfDataMode
10-27
Direction
Purpose
10Direction
Description
When adding hardware lines to a digital I/O object with addline, you must
configure the line direction. The line direction can be In or Out, and is
automatically stored in Direction. If a line direction is In, you can only read a
value from that line. If a line direction is Out, you can write or read a line value.
Specify whether a line is used for input or output
For line-configurable devices, you can change individual line directions using
Direction. For port-configurable devices, you cannot change individual line
directions.
Characteristics
Values
Example
Usage
DIO, Line
Access
Read/write
Data type
String
Read-only
when running
Yes
{In}
The line can be read from.
Out
The line can be read from or written to.
Create the digital I/O object dio and add two input lines and two output lines
to it.
dio = digitalio('nidaq',1);
addline(dio,0:3,{'In','In','Out','Out'});
To configure all lines for output.
dio.Line(1:2).Direction = 'Out';
See Also
Functions
addline
10-28
EventLog
Purpose
10EventLog
Description
Eventlog is a structure array that stores information related to specific analog
input (AI) or analog output (AO) events. Event information is stored in the Type
and Data fields of EventLog. Type stores the event type. The logged event types
are shown below.
Store information for specific events
Event Type
Description
Data missed
Data is missed by the engine.
Input overrange
A signal exceeds the hardware input range.
Run-time error
A run-time error is encountered. Run-time
errors include timeouts and hardware
errors.
Start
The start function is issued.
Stop
The device object stops executing.
Trigger
A trigger executes.
AI
AO
Timer events, samples available events (AI), and samples output events (AO)
are not logged.
Data stores event-specific information associated with the event type in several
fields. For all stored events, Data contains the RelSample field, which returns
the input or output sample number at the time the event occurred. For the
start, stop, run-time error, and trigger events, Data contains the AbsTime field,
which returns the absolute time (as a clock vector) the event occurred. Other
event-specific fields are included in Data. For a description of these fields, refer
to “Configuring Events and Actions” in Chapter 5 for analog input objects,
“Configuring Events and Actions” in Chapter 6 for analog output objects, or the
appropriate reference pages in this chapter.
EventLog can store a maximum of 1000 events. If this value is exceeded, then
the most recent 1000 events are stored. You can use the showdaqevents
function to easily display stored event information.
10-29
EventLog
Characteristics
Usage
AI, AO, Common
Access
Read-only
Data type
Structure array
Read-only
when running
N/A
Values
Values are automatically added as events occur. The default value is an empty
structure array.
Example
Create the analog input object ai and add four channels to it.
ai = analoginput('nidaq',1);
chans = addchannel(ai,0:3);
Acquire 1 second of data and display the logged event types.
start(ai)
events = ai.EventLog;
{events.Type}
ans =
'Start'
'Trigger'
'Stop
To examine the data associated with the trigger event
events(2).Data
ans =
AbsTime:
RelSample:
Channel:
Trigger:
See Also
Functions
showdaqevents
10-30
[1999 2 12 14 54 52.5456]
0
[]
1
HwChannel
Purpose
10HwChannel
Description
All channels contained by a device object have a hardware channel ID and an
associated MATLAB index. The channel ID is given by HwChannel and the
MATLAB index is given by the Index property. The HwChannel value is defined
when hardware channels are added to a device object with the addchannel
function.
Specify the hardware channel ID
The beginning channel ID value depends on the hardware device. For National
Instruments hardware, channel IDs are zero-based (begin at zero). For Agilent
Technologies hardware and sound cards, channel IDs are one-based (begin at
one).
For scanning hardware, the scan order follows the MATLAB index. Therefore,
the hardware channel associated with index 1 is sampled first, the hardware
channel associated with index 2 is sampled second, and so on. To change the
scan order, you can assign the channel IDs to different indices using
HwChannel.
Characteristics
Usage
AI, AO, Channel
Access
Read/write
Data type
Double
Read-only
when running
Yes
Values
Values are automatically defined when channels are added to the device object
with the addchannel function. The default value is one.
Example
Create the analog input object ai for a National Instruments board and add the
first three hardware channels to it.
ai = analoginput('nidaq',1);
addchannel(ai,0:2);
10-31
HwChannel
Based on the current configuration, the hardware channels are scanned in
order from 0 to 2. To swap the scan order of channels 0 and 1, you can assign
these channels to the appropriate indices using HwChannel.
ai.Channel(1).HwChannel = 1;
ai.Channel(2).HwChannel = 0;
See Also
Functions
addchannel
Properties
Channel, Index
10-32
HwLine
Purpose
10HwLine
Description
All lines contained by a digital I/O object have a hardware ID and an associated
MATLAB index. The hardware ID is given by HwLine and the MATLAB index
is given by the Index property. The HwLine value is defined when hardware
lines are added to a digital I/O object with the addline function.
Specify the hardware line ID
The beginning line ID value depends on the hardware device. For National
Instruments hardware, line IDs are zero-based (begin at zero).
Characteristics
Usage
DIO, Line
Access
Read/write
Data type
Double
Read-only
when running
Yes
Values
Values are automatically defined when lines are added to the digital I/O object
with the addline function. The default value is one.
Example
Suppose you create the digital I/O object dio and add four hardware lines to it.
dio = digitalio('nidaq',1);
addline(dio,0:3,'out');
addline automatically assigns the indices 1-4 to these hardware lines. You can
swap the hardware lines associated with index 1 and index 2 with HwLine.
dio.Line(1).HwLine = 1;
dio.Line(2).HwLine = 0;
See Also
Functions
addline
Properties
Line, Index
10-33
Index
Purpose
10Index
Description
Every hardware channel (line) contained by a device object has an associated
MATLAB index that is used to reference that channel (line). For example, to
configure property values for an individual channel, you must reference the
channel through the Channel property using the appropriate Index value.
Likewise, to configure property values for an individual line, you must
reference the line through the Line property using the appropriate Index
value.
Indicate the MATLAB index of a hardware channel or line
For channels (lines), you can assign indices automatically with the addchannel
(addline) function. Channel (line) indices always begin at 1 and increase
monotonically up to the number of channels (lines) contained by the device
object. For channels, index assignments can also be made manually with the
addchannel function.
For scanning hardware, the scan order follows the MATLAB index. Therefore,
the hardware channel associated with index 1 is sampled first, the hardware
channel associated with index 2 is sampled second, and so on. To change the
scan order, you can assign the channel IDs to different indices using the
HwChannel or Channel property.
Index provides a convenient way to access channels and lines
programmatically.
Characteristics
Values
10-34
Usage
AI, AO, Channel; DIO, Line
Access
Read-only
Data type
Double
Read-only
when running
N/A
Values are automatically defined when channels (lines) are added to the device
object with the addchannel (addline) function. The default value is one.
Index
Example
Create the analog input object ai for a sound card and add two hardware
channels to it.
ai = analoginput('winsound');
chans = addchannel(ai,1:2);
You can access the MATLAB indices for these channels with Index.
Index1 = chans(1).Index;
Index2 = chans(2).Index;
See Also
Functions
addchannel, addline
Properties
Channel, HwChannel, HwLine, Line
10-35
InitialTriggerTime
Purpose
10InitialTriggerTime
Description
For all trigger types, InitialTriggerTime records the time when Logging or
Sending is set to On. The absolute time is recorded as a clock vector.
Indicate the absolute time of the first trigger
You can return the InitialTriggerTime value with the getdata function, or
with the Data.AbsTime field of the EventLog property.
Characteristics
Usage
AI, AO, Common
Access
Read-only
Data type
Six-element vector of doubles
Read-only
when running
N/A
Values
The value is automatically updated when the trigger executes. The default
value is a vector of zeros.
Example
Create the analog input object ai for a sound card and add two hardware
channels to it.
ai = analoginput('winsound');
chans = addchannel(ai,1:2);
After starting ai, the trigger immediately executes and the trigger time is
recorded.
start(ai)
abstime = ai.InitialTriggerTime
abstime =
1.0e+003 *
1.9990
0.0020
0.0190
0.0130
To convert the clock vector to a more convenient form
t = fix(abstime);
sprintf('%d:%d:%d', t(4),t(5),t(6))
ans =
13:26:20
10-36
0.0260
0.0208
InitialTriggerTime
See Also
Functions
getdata
Properties
EventLog, Logging, Sending
10-37
InputOverRangeAction
Purpose
10InputOverRangeAction
Description
An input overrange event is generated immediately after an overrange
condition is detected for any channel group member. This event executes the
action function specified for InputOverRangeAction.
Specify the M-file action function to execute when acquired data exceeds the
valid hardware range
An overrange condition occurs when an input signal exceeds the range
specified by the InputRange property. Overrange detection is enabled only if
the analog input object is running and an action function is specified for
InputOverRangeAction.
Input overrange event information is stored in the Type and Data fields of the
EventLog property. The Type field value is OverRange. The Data field values are
given below.
Characteristics
Data Field Value
Description
RelSample
The acquired sample number when the event occurred.
Channel
The index of the channel that experienced an
overrange signal.
OverRange
Indicates if the channel went from overrange to in
range, or from in range to overrange.
Usage
AI, Common
Access
Read/write
Data type
String
Read-only
when running
No
Values
The default value is an empty string.
See Also
Properties
EventLog, InputRange
10-38
InputRange
Purpose
10InputRange
Description
InputRange is a two-element vector that specifies the range of voltages that can
be accepted by the analog input (AI) subsystem. You should configure
InputRange so that the maximum dynamic range of your hardware is utilized.
Specify the range of the analog input subsystem
If an input signal exceeds the InputRange value, then an overrange condition
occurs. Overrange detection is enabled only if the analog input object is
running and a value is specified for the InputOverRangeAction property. For
many devices, the input range is expressed in terms of the gain and polarity.
AI subsystems have a finite number of InputRange values that you can set. If
an input range is specified but does not match a valid range, then the next
highest supported range is automatically selected by the engine. If InputRange
exceeds the range of valid values, then an error is returned. Use the daqhwinfo
function to return the input ranges supported by your board.
Since the engine can set the input range to a value that differs from the value
you specify, you should return the actual input range for each channel using
the get function or the device object display summary. Alternatively, you can
use the setverify function, which sets the InputRange value and then returns
the actual value that is set.
Note If your hardware supports a channel gain list, then you can configure
InputRange for individual channels. Otherwise, InputRange must have the
same value for all channels contained by the analog input object.
You should use InputRange in conjunction with the SensorRange property.
These two properties should be configured such that the maximum precision is
obtained and the full dynamic range of the sensor signal is covered.
10-39
InputRange
Characteristics
Usage
AI, Channel
Access
Read/write
Data type
Two-element vector of doubles
Read-only
when running
Yes
Values
The default value is supplied by the hardware driver.
Example
Create the analog input object ai for a National Instruments board, and add
two hardware channels to it.
ai = analoginput('nidaq',1);
addchannel(ai,0:1);
You can return the input ranges supported by the board with the InputRanges
field of the daqhwinfo function.
out = daqhwinfo(ai);
out.InputRanges
ans =
-0.0500
0.0500
-0.5000
0.5000
-5.0000
5.0000
-10.0000
10.0000
To configure both channels contained by ai to accept input signals between -10
volts and 10 volts
ai.Channel.InputRange = [-10 10];
Alternatively, you can use the setverify function.
ActualRange = setverify(ai.Channel,'InputRange',[-10 10]);
See Also
Functions
daqhwinfo, setverify
Properties
InputOverRangeAction, SensorRange, Units, UnitsRange
10-40
InputType
Purpose
10InputType
Description
For National Instruments devices, InputType can be SingleEnded,
Differential, or NonReferencedSingleEnded. For ComputerBoards devices,
InputType can be SingleEnded, or Differential, for Agilent Technologies
devices, InputType can only be Differential. For sound cards, InputType can
only be AC-Coupled.
Specify the analog input hardware channel configuration
If channels have been added to a National Instruments or ComputerBoards
analog input object and you change the InputType value, then the channels are
automatically deleted if the hardware reduces the number of available
channels.
Characteristics
Values
Usage
AI, Common
Access
Read/write
Data type
String
Read-only
when running
Yes
National Instruments
{Differential}
Channels are configured for differential input.
SingleEnded
Channels are configured for single-ended input.
NonReferenced
SingleEnded
This channel configuration is used when the input
signal has its own ground reference, which is tied to the
negative input of the instrumentation amplifier.
ComputerBoards
{Differential}
Channels are configured for differential input.
SingleEnded
Channels are configured for single-ended input.
10-41
InputType
Agilent Technologies
{Differential}
Channels are configured for differential input.
Sound Cards
{AC-Coupled}
10-42
The input is coupled so that constant (DC) signal levels
are suppressed.
Line
Purpose
10Line
Description
Line is a vector of all the hardware lines contained by a digital I/O (DIO) object.
Since a newly created DIO object does not contain hardware lines, Line is
initially an empty vector. The size of Line increases as lines are added with the
addline function, and decreases as lines are removed with the delete function.
Contain hardware lines added to the device object
You can use Line to reference one or more individual lines. To reference a line,
you must know its MATLAB index and hardware ID. The MATLAB index is
given by the Index property, while the hardware ID is given by the HwLine
property.
Characteristics
Usage
DIO, Common
Access
Read/write
Data type
Vector of lines
Read-only
when running
Yes
Values
Values are automatically defined when lines are added to the DIO object with
the addline function. The default value is an empty column vector.
Example
Create the digital I/O object dio and add four input lines to it.
dio = digitalio('nidaq',1);
addline(dio,0:3,'In');
To set a property value for the first line added (ID = 0), you can reference the
line by its index using the Line property.
line1 = dio.Line(1);
set(line1,'Direction','Out')
See Also
Functions
addline, delete
Properties
HwLine, Index
10-43
LineName
Purpose
10LineName
Description
LineName specifies a descriptive name for a hardware line. If a line name is
defined, then you can reference that line by its name. If a line name is not
defined, then the line must be referenced by its index. Line names are not
required to be unique.
Specify a descriptive line name
You can also define descriptive line names when lines are added to a digital I/
O object with the addline function.
Characteristics
Usage
DIO, Line
Access
Read/write
Data type
String
Read-only
when running
Yes
Values
The default value is an empty string. To reference a line by name, it must
contain only letters, numbers, and underscores and must begin with a letter.
Example
Create the digital I/O object dio and add four hardware lines to it.
dio = digitalio('nidaq',1);
addline(dio,0:3,'out');
To assign a descriptive name to the first line contained by dio
line1 = dio.Line(1);
set(line1,'LineName','Joe')
You can now reference this line by name instead of index.
set(dio.Joe,'Direction','In')
See Also
Functions
addline
10-44
LogFileName
Purpose
10LogFileName
Description
You can log acquired data, device object property values and event information,
and hardware information to a disk file by setting the LoggingMode property to
Disk or Disk&Memory.
Specify the name of the disk file to which information is logged
You may specify any value for LogFileName as long as it conforms to the
MATLAB naming conventions: the name cannot start with a number and
cannot contain spaces. If no extension is specified as part of LogFileName, then
daq is used. The default value for LogFileName is logfile.daq.
You can choose whether an output file is overwritten or if multiple log files are
created with the LogToDiskMode property. Setting LogToDiskMode to
Overwrite causes the output file to be overwritten. Setting LogToDiskMode to
Index causes new data files to be created, each with an indexed name based on
the value of LogFileName.
Characteristics
Usage
AI, Common
Access
Read/write
Data type
String
Read-only
when running
Yes
Values
The default value is logfile.daq.
See Also
Properties
Logging, LoggingMode, LogToDiskMode
10-45
Logging
Purpose
10Logging
Description
Along with the Running property, Logging reflects the state of an analog input
object. Logging can be On or Off.
Indicate if data is being logged to memory or to a disk file
Logging is automatically set to On when a trigger occurs. When Logging is On,
acquired data is being stored in memory or to a disk file.
Logging is automatically set to Off when the requested samples are acquired,
an error occurs, or a stop function is issued. When Logging is Off, you can still
preview data with the peekdata function provided Running is On. However,
peekdata does not guarantee that all the requested data is returned.
To guarantee that acquired data contains no gaps, is must be logged to memory
or to a disk file. Data stored in memory is extracted with the getdata function,
while data stored to disk is returned with the daqread function. The
destination for logged data is controlled with the LoggingMode property.
Characteristics
Values
See Also
Usage
AI, Common
Access
Read-only
Data type
String
Read-only
when running
N/A
{Off}
Data is not logged to memory or a disk file.
On
Data is logged to memory or a disk file.
Functions
daqread, getdata, peekdata, stop
Properties
LoggingMode, Running
10-46
LoggingMode
Purpose
10LoggingMode
Description
LoggingMode can be set to Disk, Memory, or Disk&Memory. If LoggingMode is set
to Disk, then acquired data (as well as device object and hardware information)
is streamed to a disk file. If LoggingMode is set to Memory, then acquired data
is stored in the data acquisition engine. If LoggingMode is set to Disk&Memory,
then acquired data is stored in the data acquisition engine and is streamed to
a disk file.
Specify the destination for acquired data
When logging to the engine, you must extract the data with the getdata
function. If the data is not extracted, it may be overwritten.
When logging to disk, you can specify the log filename with the LogFileName
property, and you can control the number of log files created with the
LogToDiskMode property. You can return data stored in a disk file to the
MATLAB workspace with the daqread function.
Characteristics
Values
See Also
Usage
AI, Common
Access
Read/write
Data type
String
Read-only
when running
Yes
Disk
Acquired data is logged to a disk file.
{Memory}
Acquired data is logged to memory.
Disk&Memory
Acquired data is logged to a disk file and to memory.
Functions
daqread, getdata
Properties
LogFileName, LogToDiskMode
10-47
LogToDiskMode
Purpose
10LogToDiskMode
Description
LogToDiskMode can be set to Overwrite or Index. If LogToDiskMode is set to
Overwrite, then the log file is overwritten each time start is issued. If
LogToDiskMode is set to Index, a different disk file is created each time start
Specify whether data, events, and hardware information are saved to one disk
file or to multiple disk files
is issued and these rules are followed:
• The first log filename is specified by the initial value of LogFileName.
• If the specified file already exists, it is overwritten and no warning is issued.
• LogFileName is automatically updated with a numeric identifier after each
file is written. For example, if LogFileName is initially specified as data.daq,
then data.daq is the first filename, data01.daq is the second filename, and
so on.
Separate analog input objects are logged to separate files. You can return data
stored in a disk file to the MATLAB workspace with the daqread function. If an
error occurs during data logging, an error message is returned and data logging
is stopped.
Characteristics
Values
See Also
Usage
AI, Common
Access
Read/write
Data type
String
Read-only
when running
Yes
Index
Multiple log files are written, each with an indexed
filename based on the LogFileName property.
{Overwrite}
The log file is overwritten.
Functions
daqread
Properties
LogFileName, LoggingMode
10-48
ManualTriggerHwOn
Purpose
10ManualTriggerHwOn
Description
ManualTriggerHwOn can be set to Start or Trigger. If ManualTriggerHwOn is
Start, then the hardware device associated with your device object starts
running after you issue the start function. If ManualTriggerHwOn is Trigger,
Specify that the hardware device starts when a manual trigger is issued
then the hardware device associated with your device object starts running
after you execute a manual trigger with the trigger function. You can use
trigger only when you configure the TriggerType property to Manual.
You should configure ManualTriggerHwOn to Trigger when you want to
synchronize the input and output of data, or you require more control over
when an analog input device starts. Note that you cannot use peekdata or
acquire pretrigger data when you use this value. Additionally, you should not
use this value with repeated triggers since the subsequent behavior is
undefined.
Characteristics
Values
Example
Usage
AI, Common
Access
Read/write
Data type
String
Read-only
when running
Yes
{Start}
Start the hardware after the start function is issued.
Trigger
Start the hardware after the trigger function is issued.
Create the analog input object ai and the analog output object ao for a sound
card and add two channels to each device object.
ai = analoginput('winsound');
addchannel(ai,1:2);
ao = analogoutput('winsound');
addchannel(ao,1:2);
10-49
ManualTriggerHwOn
To operate the sound card in full duplex mode, and to minimize the time
between when ai starts and ao starts, you configure ManualTriggerHwOn to
Trigger for ai and TriggerType to Manual for both ai and ao.
set([ai ao],'TriggerType','Manual')
ai.ManualTriggerHwOn = 'Trigger';
The analog input and analog output hardware devices will both start after you
issue the trigger function. For a detailed example that uses
ManualTriggerHwOn, refer to “Starting Multiple Device Objects” on page 6-37.
See Also
Functions
peekdata, start, trigger
Properties
TriggerType
10-50
MaxSamplesQueued
Purpose
10MaxSamplesQueued
Description
MaxSamplesQueued indicates the maximum number of samples allowed in the
analog output queue. The default value is calculated by the engine, and is
based on the memory resources of your system. You can override the default
value of MaxSamplesQueued with the daqmem function.
Indicate the maximum number of samples that can be queued in the engine
The value of MaxSamplesQueued can affect the behavior of putdata. For
example, if the queued data exceeds the value of MaxSamplesQueued, then
putdata becomes a blocking function until there is enough space in the queue
to add the additional data.
Characteristics
Usage
AO, Common
Access
Read-only
Data type
Double
Read-only
when running
N/A
Values
The value is calculated by the data acquisition engine.
See Also
Functions
daqmem, putdata
10-51
Name
Purpose
10Name
Description
When a device object is created, a descriptive name is automatically generated
and stored in Name. This name is produced by concatenating the name of the
adaptor, the device ID, and the device object type. You can change the value of
Name at any time.
Characteristics
Specify a descriptive name for the device object
Usage
AI, AO, DIO, Common
Access
Read/write
Data type
String
Read-only
when running
No
Values
The value is defined after the device object is created.
Example
Create the analog input object ai for a sound card.
ai = analoginput('winsound');
The descriptive name for ai is given by
ai.Name
ans =
winsound0-AI
10-52
NativeOffset
Purpose
10NativeOffset
Description
NativeOffset, along with NativeScaling, is used to convert data from your
hardware’s native format to doubles using the formula
Indicate the offset to use when converting data from native format to doubles
data = (native data)(native scaling) + native offset
For analog input objects, you return data from the engine in native format
using the getdata function. Additionally, if you log native data to a .daq file,
then you can read back that data using the daqread function. For analog output
objects, you queue native data in the engine using the putdata function. You
may want to return or queue data in native format to conserve memory and to
increase speed.
The NativeOffset value for a given channel may change if you change the
UnitsRange, SensorRange, or InputRange property values for that channel.
You can return the native data type of your hardware device with the
daqhwinfo function.
Characteristics
Usage
AI, AO, Channel
Access
Read-only
Data type
Double
Read-only
when running
N/A
Values
The default value is device-specific.
Example
Create the analog input object ai for a National Instruments board, and add
eight channels to it.
ai = analoginput('nidaq',1);
addchannel(ai,0:7);
Start ai, collect one second of data for each channel, and extract the data from
the engine using the native format of the device.
start(ai)
nativedata = getdata(ai,1000,'native');
10-53
NativeOffset
You can return the native data type of the board with the daqhwinfo function.
out = daqhwinfo(ai);
out.NativeDataType
ans =
int16
Convert the data to doubles using the NativeScaling and NativeOffset
properties.
scaling = get(ai.Channel(1),'NativeScaling');
offset = get(ai.Channel(1),'NativeOffset');
data = double(nativedata)*scaling + offset;
See Also
Functions
daqhwinfo, daqread, getdata, putdata
Properties
InputRange, NativeScaling, SensorRange, UnitsRange
10-54
NativeScaling
Purpose
10NativeScaling
Description
NativeScaling, along with NativeOffset, is used to convert data from your
hardware’s native format to doubles using the formula
Indicate the scaling to use when converting data from native format to doubles
data = (native data)(native scaling) + native offset
For analog input objects, you return data from the engine in native format
using the getdata function. Additionally, if you log native data to a .daq file,
then you can read back that data using the daqread function. For analog output
objects, you queue native data in the engine using the putdata function. You
may want to return or queue data in native format to conserve memory and to
increase speed.
The NativeScaling value for a given channel may change if you change the
UnitsRange, SensorRange, or InputRange property values for that channel.
You can return the native data type of your hardware device with the
daqhwinfo function.
Characteristics
Usage
AI, AO, Channel
Access
Read-only
Data type
Double
Read-only
when running
N/A
Values
The default value is device-specific.
See Also
Functions
daqhwinfo, daqread, getdata, putdata
Properties
InputRange, NativeOffset, SensorRange, UnitsRange
10-55
OutputRange
Purpose
10OutputRange
Description
OutputRange is a two-element vector that specifies the range of voltages that
can be output by the analog output (AO) subsystem. You should configure
OutputRange so that the maximum dynamic range of your hardware is utilized.
For many devices, the output range is expressed in terms of the gain and
polarity.
Specify the range of the analog output hardware subsystem
AO subsystems have a finite number of OutputRange values that you can set.
If an output range is specified but does not match a valid range, then the next
highest supported range is automatically selected by the engine. If
OutputRange exceeds the range of valid values, then an error is returned. Use
the daqhwinfo function to return the output ranges supported by your board.
Since the engine can set the output range to a value that differs from the value
you specify, you should return the actual output range for each channel using
the get function or the device object display summary. Alternatively, you can
use the setverify function, which sets the OutputRange value and then
returns the actual value that is set.
Characteristics
Usage
AO, Channel
Access
Read/write
Data type
Two-element vector of doubles
Read-only
when running
Yes
Values
The default value is determined by the hardware driver.
Example
Create the analog output object ao for a National Instruments board and add
two hardware channels to it.
ao = analogoutput('nidaq',1);
addchannel(ao,0:1);
10-56
OutputRange
You can return the output ranges supported by the board with the
OutputRanges field of the daqhwinfo function.
out = daqhwinfo(ao);
out.OutputRanges
ans =
0.0000
10.0000
-10.0000
10.0000
To configure both channels contained by ao to output signals between -10 volts
and 10 volts
ao.Channel.OutputRange = [-10 10];
Alternatively, you can use the setverify function to configure and return the
OutputRange value.
ActualRange = setverify(ao.Channel,'OutputRange',[-10 10]);
See Also
Functions
daqhwinfo, setverify
Properties
Units, UnitsRange
10-57
Parent
Purpose
10Parent
Description
The parent of a channel (line) is defined as the device object that contains the
channel (line).
Indicate the parent (device object) of a channel or line
You can create a copy of the device object containing a particular channel or
line by returning the value of Parent. You can treat this copy like any other
device object. For example, you can configure property values, add channels or
lines to it, and so on.
Characteristics
Usage
AI, AO, Channel; DIO, Line
Access
Read-only
Data type
Device object
Read-only
when running
N/A
Values
The value is defined when channels or lines are added to the device object.
Example
Create the analog input object ai for a National Instruments board and add
three hardware channels to it.
ai = analoginput('nidaq',1);
chans = addchannel(ai,0:2);
To return the parent for channel 2
parent = ai.Channel(2).Parent;
parent is an exact copy of ai.
isequal(ai,parent)
ans =
1
10-58
Port
Purpose
10Port
Description
Hardware lines are often grouped together as a port. Digital I/O subsystems
can consist of multiple ports and typically have eight lines per port. When
adding hardware lines to a digital I/O object with addline, you can specify the
port ID. The port ID is stored in the Port property. If the port ID is not
specified, then the smallest port ID value is automatically used.
Characteristics
Specify the port ID
Usage
DIO, Line
Access
Read-only
Data type
Double
Read-only
when running
N/A
Values
The port ID is defined when line are added to the digital I/O object with
addline.
Example
Create the digital I/O object dio and add two hardware channels to it.
dio = digitalio('nidaq',1);
addline(dio,0:1,'In');
You can use Port property to return the port IDs associated with the lines
contained by dio.
dio.Line.Port
ans =
[0]
[0]
See Also
Functions
addline
10-59
RepeatOutput
Purpose
10RepeatOutput
Description
To send data to an analog output subsystem, it must first be queued in the data
acquisition engine with the putdata function. If you want to continuously
output the same data, you can use multiple calls to putdata. However, since
each putdata call consumes memory, a long output sequence can quickly bring
your system to halt.
Specify the number of additional times queued data is output
As an alternative to putdata, you can continuously output previously queued
data using RepeatOutput. Since RepeatOutput requeues the data, additional
memory resources are not consumed. While the data is being output, you
cannot add additional data to the queue.
Characteristics
Usage
AO, Common
Access
Read/write
Data type
Double
Read-only
when running
Yes
Values
The default value is zero.
Example
Create the analog output object ao for a sound card and add one channel to it.
ao = analogoutput('winsound');
chans = addchannel(ao,1);
To queue one second of data
data = sin(linspace(0,10,8000))';
putdata(ao,data)
To continuously output data for 10 seconds
set(ao,'RepeatOutput',9)
See Also
Functions
putdata
10-60
Running
Purpose
10Running
Description
Along with the Logging or Sending property, Running reflects the state of an
analog input or analog output object. Running can be On or Off.
Indicate if the device object is running
Running is automatically set to On once the start function is issued. When
Running is On, you can acquire data from an analog input device or send data
to an analog output device after the trigger occurs. For digital I/O objects,
Running is typically used to indicate if time-based events are being generated.
Running is automatically set to Off once the stop function is issued, the
specified data is acquired or sent, or a run-time error occurs. When Running is
Off, you cannot acquire or send data. However, you can acquire one sample
with the getsample function, or send one sample with the putsample function.
Characteristics
Values
See Also
Usage
AI, AO, DIO, Common
Access
Read-only
Data type
String
Read-only
when running
N/A
{Off}
The device object is not running.
On
The device object is running.
Functions
getsample, putsample, start
Properties
Logging, Sending
10-61
RuntimeErrorAction
Purpose
10RuntimeErrorAction
Description
A run-time error event is generated immediately after a run-time error occurs.
This event executes the action function specified for RuntimeErrorAction.
Additionally, a toolbox error message is automatically displayed to the
MATLAB workspace. If an error occurs that is not explicitly handled by the
toolbox, then the hardware-specific error message is displayed.
Specify the M-file action function to execute when a run-time error occurs
The default value for RunTimeErrorAction is daqaction, which displays the
event type, the time the event occurred, and the device object name along with
the error message.
Run-time error event information is stored in the Type and Data fields of the
EventLog property. The Type field value is Error. The Data field values are
given below.
Data Field Value
Description
AbsTime
The absolute time (as a clock vector) the event
occurred.
RelSample
The acquired (AI) or output (AO) sample number when
the event occurred.
String
The descriptive error message.
Run-time errors include hardware errors and timeouts. Run-time errors do not
include configuration errors such as setting an invalid property value.
Characteristics
Values
10-62
Usage
AI, AO, Common
Access
Read/write
Data type
String
Read-only
when running
No
The default value is daqaction.
RuntimeErrorAction
See Also
Functions
daqaction
Properties
EventLog, Timeout
10-63
SampleRate
Purpose
10SampleRate
Description
SampleRate specifies the per-channel rate (in samples/second) that an analog
input (AI) or analog output (AO) subsystem converts data. AI subsystems
convert analog data to digital data, while AO subsystems convert digital data
to analog data.
Specify the per-channel rate at which analog data is converted to digital data,
or digital data is converted to analog data
AI and AO subsystems have a finite (though often large) number of valid
sampling rates. If you specify a sampling rate that does not match one of the
valid values, then the data acquisition engine automatically selects the next
highest supported sampling rate that is within 1% of the requested rate. If
there is no valid sampling rate within this tolerance, the next highest value is
selected. If a higher value is not available, then an error is returned.
Since the engine can set the sampling rate to a value that differs from the value
you specify, you should return the actual sampling rate using the get function
or the device object display summary. Alternatively, you can use the setverify
function, which sets the SampleRate value and then returns the actual value
that is set. To find out the range of sampling rates supported by your board, use
the propinfo function. Additionally, since the actual sampling rate depends on
the number of channels contained by the device object and the ChannelSkew
property value (AI only), SampleRate should be the last property you set before
starting the device object.
Characteristics
Values
10-64
Usage
AI, AO, Common
Access
Read/write
Data type
Double
Read-only
when running
Yes
The default value is obtained from the hardware driver.
SampleRate
Example
Create the analog input object ai for a sound card and add two channels to it.
ai = analoginput('winsound');
addchannel(ai,1:2);
You can find out the range of valid sampling rates with the ConstraintValue
field of the propinfo function.
rates = propinfo(ai,'SampleRate');
rates.ConstraintValue
ans =
8000
48000
To configure the per-channel sampling rate to 48 kHz
set(ai,'SampleRate',48000)
Alternatively, you can use the setverify function to configure and return the
SampleRate value.
ActualRate = setverify(ai,'SampleRate',48000);
See Also
Functions
propinfo, setverify
Properties
ChannelSkew
10-65
SamplesAcquired
Purpose
10SamplesAcquired
Description
SamplesAcquired is continuously updated to reflect the current number of
samples acquired by an analog input object. It is reset to zero after a start
function is issued.
Indicate the number of samples acquired per channel
Use the SamplesAvailable property to find out how many samples are
available to be extracted from the engine.
Characteristics
Values
See Also
Usage
AI, Common
Access
Read-only
Data type
Double
Read-only
when running
N/A
The value is continuously updated to reflect the current number of samples
acquired. The default value is zero.
Functions
start
Properties
SamplesAvailable
10-66
SamplesAcquiredAction
Purpose
10SamplesAcquiredAction
Description
A samples acquired event is generated immediately after the number of
samples specified by the SamplesAcquiredActionCount property is acquired
for each channel group member. This event executes the action function
specified for SamplesAcquiredAction.
Specify the M-file action function to execute every time a predefined number of
samples is acquired for each channel group member
You should use SamplesAcquiredAction if you must access each sample that is
acquired. If you do not have this requirement, you may want to use the
TimerAction property.
Samples acquired event information is not stored in the EventLog property.
Characteristics
Usage
AI, Common
Access
Read/write
Data type
String
Read-only
when running
No
Values
The default value is an empty string.
See Also
Properties
EventLog, SamplesAcquiredActionCount, TimerAction
10-67
SamplesAcquiredActionCount
Purpose
10SamplesAcquiredActionCount
Description
A samples acquired event is generated immediately after the number of
samples specified by SamplesAcquiredActionCount is acquired for each
channel group member. This event executes the action function specified by the
SamplesAcquiredAction property.
Characteristics
Values
See Also
Specify the number of samples to acquire for each channel group member
before a samples acquired event is generated
Usage
AI, Common
Access
Read/write
Data type
Double
Read-only
when running
Yes
The default value is 1024.
Properties
SamplesAcquiredAction
10-68
SamplesAvailable
Purpose
10SamplesAvailable
Description
For analog input (AI) objects, SamplesAvailable indicates the number of
samples that can be extracted from the engine for each channel group member
with the getdata function. For analog output (AO) objects, SamplesAvailable
indicates the number of samples that have been queued with the putdata
function, and can be sent (output) to each channel group member.
Indicate the number of samples available per channel in the engine
After data has been extracted (AI) or output (AO), the SamplesAvailable value
is reduced by the appropriate number of samples. For AI objects,
SamplesAvailable is reset to zero after a start function is issued.
For AI objects, use the SamplesAcquired property to find out how many
samples have been acquired since the start function was issued. For AO
objects, use the SamplesOutput property to find out how many samples have
been output since the start function was issued.
Characteristics
Usage
AI, AO, Common
Access
Read-only
Data type
Double
Read-only
when running
N/A
Values
The value is automatically updated based on the number of samples acquired
(analog input) or sent (analog output). The default value is zero.
See Also
Functions
start
Properties
SamplesAcquired, SamplesOutput
10-69
SamplesOutput
Purpose
10SamplesOutput
Description
SamplesOutput is continuously updated to reflect the current number of
samples output by an analog output object. It is reset to zero after the device
objects stops and data has been queued with the putdata function.
Indicate the number of samples output per channel from the engine
Use the SamplesAvailable property to find out how many samples are
available to be output from the engine.
Characteristics
Values
See Also
Usage
AO, Common
Access
Read-only
Data type
Double
Read-only
when running
N/A
The value is continuously updated to reflect the current number of samples
output. The default value is zero.
Functions
putdata
Properties
SamplesAvailable
10-70
SamplesOutputAction
Purpose
10SamplesOutputAction
Description
A samples output event is generated immediately after the number of samples
specified by the SamplesOutputActionCount property is output for each
channel group member. This event executes the action function specified for
SamplesOutputAction.
Specify the M-file action function to execute every time a predefined number of
samples is output for each channel group member
Samples output event information is not stored in the EventLog property.
Characteristics
Usage
AO, Common
Access
Read/write
Data type
String
Read-only
when running
No
Values
The default value is an empty string.
See Also
Properties
EventLog, SamplesOutputActionCount
10-71
SamplesOutputActionCount
Purpose
10SamplesOutputActionCount
Description
A samples output event is generated immediately after the number of samples
specified by SamplesOutputActionCount is output for each channel group
member. This event executes the action function specified by the
SamplesOutputAction property.
Characteristics
Values
See Also
Specify the number of samples to output for each channel group member before
a samples output event is generated
Usage
AO, Common
Access
Read/write
Data type
Double
Read-only
when running
Yes
The default value is 1024.
Properties
SamplesOutputAction
10-72
SamplesPerTrigger
Purpose
10SamplesPerTrigger
Description
SamplesPerTrigger specifies the number of samples to acquire for each analog
input channel group member for each trigger that occurs. If
SamplesPerTrigger is set to Inf, then the analog input object continually
acquires data until a stop function is issued or an error occurs.
Specify the number of samples to acquire for each channel group member for
each trigger that occurs
The default value of SamplesPerTrigger is calculated by the data acquisition
engine such that one second of data is acquired. This calculation is based on the
value of SampleRate.
Characteristics
Usage
AI, Common
Access
Read/write
Data type
Double
Read-only
when running
Yes
Values
The default value is set by the engine such that one second of data is acquired.
Example
Create the analog input object ai for a sound card and add two channels to it.
ai = analoginput('winsound');
addchannel(ai,1:2);
By default, a one second acquisition in which 8000 samples are acquired for
each channel is defined. To define a two second acquisition at the same
sampling rate
set(ai,'SamplesPerTrigger',16000)
See Also
Functions
stop
Properties
SampleRate
10-73
Sending
Purpose
10Sending
Description
Along with the Running property, Sending reflects the state of an analog output
object. Sending can be On or Off.
Indicate if data is being sent to the hardware device
Sending is automatically set to On when a trigger occurs. When Sending is On,
queued data is being output to the analog output subsystem.
Sending is automatically set to Off when the queued data has been output, an
error occurs, or a stop function is issued. When Sending is Off, data is not
being output to the analog output subsystem although you can output a single
sample with the putsample function.
Characteristics
Values
See Also
Usage
AO, Common
Access
Read-only
Data type
String
Read-only
when running
N/A
{Off}
Data is not being sent to the analog output hardware.
On
Data is being sent to the analog output hardware.
Functions
putsample
Properties
Running
10-74
SensorRange
Purpose
10SensorRange
Description
You use SensorRange to scale your data to reflect the range you expect from
your sensor. You can find the appropriate sensor range from your sensor’s
specification sheet. For example, an accelerometer might have a sensor range
of ±5 volts, which corresponds to ±50 g’s (1 g = 9.80 m/s/s).
Specify the range of data you expect from your sensor
The data is scaled while it is extracted from the engine with the getdata
function according to the formula
scaled value = (A/D value)(units range)/(sensor range)
The A/D value is constrained by the InputRange property, which reflects the
gain and polarity of your hardware channels. The units range is given by the
UnitsRange property
Characteristics
Values
See Also
Usage
AI, Channel
Access
Read/write
Data type
Two-element vector of doubles
Read-only
when running
No
The default value is determined by the default value of the InputRange
property.
Functions
getdata
Properties
InputRange, Units, UnitsRange
10-75
StartAction
Purpose
10StartAction
Description
A start event is generated immediately after the start function is issued. This
event executes the action function specified for StartAction. When the action
function has finished executing, Running is automatically set to On and the
device object and hardware device begin executing.
Specify the M-file action function to execute just before the device object starts
running
Start event information is stored in the Type and Data fields of the EventLog
property. The Type field value is Start. The Data field values are given below.
Characteristics
Values
See Also
Data Field Value
Description
AbsTime
The absolute time (as a clock vector) the event
occurred.
RelSample
The acquired (AI) or output (AO) sample number when
the event occurred.
Usage
AI, AO, Common
Access
Read/write
Data type
String
Read-only
when running
No
The default value is an empty string.
Functions
start
Properties
EventLog, Running
10-76
StopAction
Purpose
10StopAction
Description
A stop event is generated immediately after the device object and hardware
device stop executing. This occurs when:
Specify the M-file action function to execute just after the device object stops
running
• A stop function is issued.
• For analog input (AI) objects, the requested number of samples to acquire
was reached or data was missed. For analog output (AO) objects, the
requested number of samples to output was reached.
• A run-time error occurred.
A stop event executes the action function specified for StopAction. Under most
circumstances, the action function is not guaranteed to complete execution
until sometime after the device object and hardware device stop, and the
Running property is set to Off.
Stop event information is stored in the Type and Data fields of the EventLog
property. The Type field value is Stop. The Data field values are given below.
Characteristics
Values
Data Field Value
Description
AbsTime
The absolute time (as a clock vector) the event
occurred.
RelSample
The acquired (AI) or output (AO) sample number when
the event occurred.
Usage
AI, AO, Common
Access
Read/write
Data type
String
Read-only
when running
No
The default value is an empty string.
10-77
StopAction
See Also
Functions
stop
Properties
EventLog, Running
10-78
Tag
Purpose
10Tag
Description
Tag provides a means to identify device objects with a label. Using the daqfind
function and the Tag value, you can identify and retrieve a device object that
Specify a device object label
was cleared from the MATLAB workspace.
Characteristics
Usage
AI, AO, DIO, Common
Access
Read/write
Data type
String
Read-only
when running
No
Values
The default value is an empty string.
Example
Create the analog input object ai for a sound card and add two channels to it.
ai = analoginput('winsound');
addchannel(ai,1:2);
Assign ai a label using Tag.
set(ai,'Tag','Sound')
If ai is cleared from the workspace, you can use daqfind and the Tag value to
identify and retrieve the device object.
clear ai
aicell = daqfind('Tag','Sound');
ai = aicell{1};
See Also
Functions
daqfind
10-79
Timeout
Purpose
10Timeout
Description
The Timeout value (in seconds) is added to the time required to extract data
from the engine or queue data to the engine. Since data is extracted with the
getdata function, and queued with the putdata function, Timeout is associated
only with these two “blocking” functions.
Specify an additional waiting time to extract or queue data
If the requested data is not extracted or queued after waiting the required time,
then a timeout condition occurs and control is immediately returned to
MATLAB. A timeout is one of the conditions for stopping an acquisition. When
a timeout occurs, the action function specified by RuntimeErrorAction is
called.
Timeout is not associated with hardware timeout conditions. Possible
hardware timeout conditions include:
• Triggering on a voltage level and that level never occurs
• Externally clocking an acquisition and the external clock signal never occurs
• Losing the hardware connection
To check for hardware timeouts, you may need to poll the appropriate property
value.
Characteristics
Usage
AI, AO, Common
Access
Read/write
Data type
Double
Read-only
when running
Yes
Values
The default value is one second.
See Also
Functions
getdata, putdata
Properties
RunTimeErrorAction
10-80
TimerAction
Purpose
10TimerAction
Description
A timer event is generated whenever the time specified by the TimerPeriod
property passes. This event executes the action function specified for
TimerAction. Time is measured relative to when the device object starts
running.
Specify the M-file action function to execute whenever a predefined period of
time passes
Some timer events may not be processed if your system is significantly slowed
or if the TimerPeriod value is too small. For example, a common application for
timer events is to display data. However, since displaying data is a
CPU-intensive task, some of these events may be dropped. To guarantee that
events are not dropped, you may want to use the SamplesAcquiredAction
property (analog input) or the SamplesOutputAction property (analog output).
For digital I/O objects, timer events are typically used to update and display the
state of the device object.
Timer event information is not stored in the EventLog property.
Characteristics
Values
See Also
Usage
AI, AO, DIO, Common
Access
Read/write
Data type
String
Read-only
when running
No
The default value is an empty string.
Properties
EventLog, SamplesAcquiredAction, SamplesOutputAction, TimerPeriod
10-81
TimerPeriod
Purpose
10TimerPeriod
Description
TimerPeriod specifies the time, in seconds, that must pass before the action
function specified for TimerAction is called. Time is measured relative to when
the hardware device starts running.
Specify the period of time between timer events
Some timer events may not be processed if your system is significantly slowed
or if the TimerPeriod value is too small. For example, a common application for
timer events is to display data. However, since displaying data is a
CPU-intensive task, some of these events may be dropped.
Characteristics
Values
See Also
Usage
AI, AO, DIO, Common
Access
Read/write
Data type
Double
Read-only
when running
No
The default value is 0.1 second.
Properties
TimerAction
10-82
TriggerAction
Purpose
10TriggerAction
Description
A trigger event is generated immediately after a trigger occurs. This event
executes the action function specified for TriggerAction. Under most
circumstances, the action function is not guaranteed to complete execution
until sometime after Logging is set to On for analog input (AI) objects, or
Sending is set to On for analog output (AO) objects.
Specify the M-file action function to execute when a trigger occurs
Trigger event information is stored in the Type and Data fields of the EventLog
property. The Type field value is Trigger. The Data field values are given
below.
Characteristics
Values
See Also
Data Field Value
Description
AbsTime
The absolute time (as a clock vector) the event
occurred.
RelSample
The acquired (AI) or output (AO) sample number when
the event occurred.
Channel
The index number for each input channel serving as a
trigger source (AI only).
Trigger
The trigger number (AI only).
Usage
AI, AO, Common
Access
Read/write
Data type
String
Read-only
when running
No
The default value is an empty string.
Functions
trigger
Properties
EventLog, Logging
10-83
TriggerChannel
Purpose
10TriggerChannel
Description
TriggerChannel specifies the channels serving as trigger sources. The trigger
channel(s) must be specified before the trigger type. You may need to configure
the TriggerCondition and TriggerConditionValue properties in conjunction
with TriggerChannel.
Specify the channels serving as trigger sources
For all supported vendors, if TriggerType is Software, then you must acquire
data from the channel being used for the trigger source. For National
Instruments hardware, if TriggerType is HwAnalogChannel, then
TriggerChannel must be the first element of the channel group. The exception
is if you are using the PCI-6110 or PCI-6111 board. In this case, you can specify
any channel for the TriggerChannel value.
Characteristics
Usage
AI, Common
Access
Read/write
Data type
Vector of channels
Read-only
when running
Yes
Values
The default value is an empty vector.
Example
Create the analog input object ai, add two channels, and define the trigger
source as channel 2.
ai = analoginput('winsound');
ch = addchannel(ai,1:2);
set(ai,'TriggerChannel',ch(2))
set(ai,'TriggerType','Software')
See Also
Properties
TriggerCondition, TriggerConditionValue, TriggerType
10-84
TriggerCondition
Purpose
10TriggerCondition
Description
The available trigger conditions depend on the value of TriggerType. If
TriggerType is Immediate or Manual, the only available TriggerCondition is
None. If TriggerType is Software, then TriggerCondition can be Rising,
Falling, Leaving, or Entering. These trigger conditions require one or more
voltage values to be specified for the TriggerConditionValue property.
Specify the condition that must be satisfied before a trigger executes
Based on the hardware you are using, additional trigger conditions may be
available.
Characteristics
Values
Usage
AI, Common
Access
Read/write
Data type
String
Read-only
when running
Yes
All Supported Hardware
The following trigger condition is used when TriggerType is Immediate or
Manual.
{None}
No trigger condition is required.
The following trigger conditions are available when TriggerType is Software.
{Rising}
The trigger occurs when the signal has a positive slope
when passing through the specified value.
Falling
The trigger occurs when the signal has a negative slope
when passing through the specified value.
Leaving
The trigger occurs when the signal leaves the specified
range of values.
Entering
The trigger occurs when the signal enters the specified
range of values.
10-85
TriggerCondition
National Instruments
The following trigger condition is used when TriggerType is HwDigital.
{None}
No trigger condition is required.
The following trigger conditions are available when TriggerType is
HwAnalogChannel or HwAnalogPin.
{AboveHighLevel}
The trigger occurs when the analog signal is above
the specified value.
BelowLowLevel
The trigger occurs when the analog signal is below
the specified value.
InsideRegion
The trigger occurs when the analog signal is inside
the specified region.
LowHysteresis
The trigger occurs when the analog signal is less
than the specified low value with hysteresis given by
the specified high value.
HighHysteresis
The trigger occurs when the analog signal is greater
than the specified high value with hysteresis given
by the specified low value.
ComputerBoards
The following trigger conditions are available when TriggerType is HwDigital.
10-86
GateHigh
The trigger occurs as long as the digital signal is high.
GateLow
The trigger occurs as long as the digital signal is low.
TrigHigh
The trigger occurs when the digital signal is high.
TrigLow
The trigger occurs when the digital signal is low.
TrigPosEdge
The trigger occurs when the positive (rising) edge of
the digital signal is detected.
{TrigNegEdge}
The trigger occurs when the negative (falling) edge of
the digital signal is detected.
TriggerCondition
The following trigger conditions are available when TriggerType is HwAnalog.
{TrigAbove}
The trigger occurs when the analog signal makes a
transition from below the specified value to above.
TrigBelow
The trigger occurs when the analog signal makes a
transition from above the specified value to below.
GateNegHys
The trigger occurs when the analog signal is more
than the specified high value. The acquisition stops if
the analog signal is less than the specified low value.
GatePosHys
The trigger occurs when the analog signal is less than
the specified low value. The acquisition stops if the
analog signal is more than the specified high value.
GateAbove
The trigger occurs as long as the analog signal is more
than the specified value.
GateBelow
The trigger occurs as long as the analog signal is less
than the specified value.
GateInWindow
The trigger occurs as long as the analog signal is
within the specified range of values.
GateOutWindow
The trigger occurs as long as the analog signal is
outside the specified range of values.
Agilent Technologies
The following trigger conditions are available when TriggerType is HwDigital.
{PositiveEdge}
The trigger occurs when the positive (rising) edge of a
digital signal is detected.
NegativeEdge
The trigger occurs when the negative (falling) edge of
a digital signal is detected.
10-87
TriggerCondition
The following trigger conditions are available when TriggerType is HwAnalog.
{Rising}
The trigger occurs when the analog signal has a positive
slope when passing through the specified range of
values.
Falling
The trigger occurs when the analog signal has a
negative slope when passing through the specified range
of values.
Leaving
The trigger occurs when the analog signal leaves the
specified range of values.
Entering
The trigger occurs when the analog signal enters the
specified range of values.
Note that when TriggerType is HwAnalog, the trigger condition values are all
specified as two-element vectors. Setting two trigger levels prevents the
module from triggering repeatedly due to a noisy signal.
See Also
Properties
TriggerChannel, TriggerConditionValue, TriggerType
10-88
TriggerConditionValue
Purpose
10TriggerConditionValue
Description
TriggerConditionValue is used when TriggerType is Software, and is ignored
when TriggerCondition is None.
Specify one or more voltage values that must be satisfied before a trigger
executes
To execute a software trigger, the values specified for TriggerCondition and
TriggerConditionValue must be satisfied. When TriggerCondition is Rising
or Falling, TriggerConditionValue accepts a single value. When
TriggerCondition is Entering or Leaving, TriggerConditionValue accepts a
two-element vector of values.
Characteristics
Usage
AI, Common
Access
Read/write
Data type
Double (or a two-element vector of doubles)
Read-only
when running
Yes
Values
The default value is zero.
Example
Create the analog input object ai and add one channel to it.
ai = analoginput('winsound');
ch = addchannel(ai,1);
The trigger executes when a signal with a negative slope passing through 0.2
volts is detected on channel 1.
set(ai,'TriggerChannel',ch)
set(ai,'TriggerType','Software')
set(ai,'TriggerCondition','Falling')
set(ai,'TriggerConditionValue',0.2)
See Also
Properties
TriggerCondition, TriggerType
10-89
TriggerDelay
Purpose
10TriggerDelay
Description
You can define both pretriggers and postriggers. Pretriggers are specified with
a negative TriggerDelay value while postriggers are specified with a positive
TriggerDelay value. You can delay a trigger in units of time or samples with
the TriggerDelayUnits property. Pretriggers are not defined for hardware
triggers or when TriggerType is Immediate.
Specify the delay value for data logging
Pretrigger samples are included as part of the total samples acquired per
trigger as specified by the SamplesPerTrigger property. If sample-time pairs
are returned to the workspace with the getdata function, then the pretrigger
samples are identified with negative time values.
Characteristics
Usage
AI, Common
Access
Read/write
Data type
Double
Read-only
when running
Yes
Values
The default value is zero.
Example
Create the analog input object ai and add one channel to it.
ai = analoginput('winsound');
ch = addchannel(ai,1);
Configure ai to acquire 44,100 samples per trigger with 11,025 samples (0.25
seconds) acquired as pretrigger data.
set(ai,'SampleRate',44100)
set(ai,'TriggerType','Manual')
set(ai,'SamplesPerTrigger',44100)
set(ai,'TriggerDelay',-0.25)
See Also
Properties
SamplesPerTrigger, TriggerDelayUnits
10-90
TriggerDelayUnits
Purpose
10TriggerDelayUnits
Description
TriggerDelayUnits can be Seconds or Samples. If TriggerDelayUnits is
Seconds, then data logging is delayed by the specified time for each channel
group member. If TriggerDelayUnits is Samples, then data logging is delayed
Specify the units in which trigger delay data is measured
by the specified number of samples for each channel group member.
The trigger delay value is given by the TriggerDelay property.
Characteristics
Values
See Also
Usage
AI, Common
Access
Read/write
Data type
String
Read-only
when running
Yes
{Seconds}
The trigger is delayed by the specified number of
seconds.
Samples
The trigger is delayed by the specified number of
samples.
Properties
TriggerDelay
10-91
TriggerRepeat
Purpose
10TriggerRepeat
Description
You can configure a trigger to occur once (one-shot acquisition) or multiple
times. If TriggerRepeat is set to its default value of zero, then the trigger
executes once. If TriggerRepeat is set to a positive integer value, then the
trigger executes the specified number of times. If TriggerRepeat is set to inf
then the trigger executes continuously until a stop function is issued or an
error occurs.
Specify the number of additional times the trigger executes
You can quickly evaluate how many triggers have executed by examining the
TriggersExecuted property or by invoking the display summary for the device
object. The display summary is invoked by typing the device object name at the
MATLAB command line.
Characteristics
Usage
AI, Common
Access
Read/write
Data type
Double
Read-only
when running
Yes
Values
The default value is zero.
See Also
Functions
disp, stop
Properties
TriggersExecuted, TriggerType
10-92
TriggersExecuted
Purpose
10TriggersExecuted
Description
You can find out how many triggers executed by returning the value of
TriggersExecuted. The trigger number for each trigger executed is also
recorded by the Data.Trigger field of the EventLog property.
Characteristics
Indicate the number of triggers that execute
Usage
AI, AO, Common
Access
Read-only
Data type
Double
Read-only
when running
N/A
Values
The default value is zero.
Example
Create the analog input object ai and add one channel to it.
ai = analoginput('winsound');
ch = addchannel(ai,1);
Configure ai to acquire 40,000 samples with five triggers using the default
sampling rate of 8000 Hz.
set(ai,'TriggerRepeat',4)
start(ai)
TriggersExecuted returns the number of triggers executed.
ai.TriggersExecuted
ans =
5
See Also
Properties
EventLog
10-93
TriggerType
Purpose
10TriggerType
Description
TriggerType can be Immediate, Manual, or Software. If TriggerType is
Immediate, the trigger occurs immediately after the start function is issued. If
TriggerType is Manual, the trigger occurs immediately after the trigger
function is issued. If TriggerType is Software, the trigger occurs when the
Specify the type of trigger to execute
associated trigger condition is satisfied (AI only).
For a given hardware device, additional trigger types may be available. Some
trigger types require trigger conditions and trigger condition values. Trigger
conditions are specified with the TriggerCondition property, while trigger
condition values are specified with the TriggerConditionValue property.
When a trigger occurs for an analog input object, data logging is initiated and
the Logging property is automatically set to On. When a trigger occurs for an
analog output object, data sending is initiated and the Sending property is
automatically set to On.
Characteristics
Values
10-94
Usage
AI, AO, Common
Access
Read/write
Data type
String
Read-only
when running
Yes
All Supported Hardware
{Immediate}
The trigger executes immediately after start is issued.
Pretrigger data cannot be captured.
Manual
The trigger executes immediately after the trigger
function is issued.
Software
The trigger executes when the associated trigger
condition is satisfied. Trigger conditions are given by the
TriggerCondition property. (AI only).
TriggerType
National Instruments
HwDigital
The trigger source is the falling edge of an external
digital signal. Pretrigger data cannot be captured.
HwAnalogChannel
The trigger source is an external analog signal (AI
only).
HwAnalogPin
The trigger source is a low-range external analog
signal (AI only).
For 1200 Series hardware, HwDigital is the only device-specific TriggerType
value for analog input subsystems. Analog output subsystems do not support
any device-specific TriggerType values.
ComputerBoards
HwDigital
The trigger source is an external digital signal (AI only).
Pretrigger data cannot be captured.
HwAnalog
The trigger source is an external analog signal (AI only).
Agilent Technologies
See Also
HwDigital
The trigger source is an external digital signal (AI only).
Pretrigger data cannot be captured.
HwAnalog
The trigger source is an external analog signal (AI only).
HwDigitalPos
The trigger source is the positive edge of an external
digital signal (AO only).
HwDigitalNeg
The trigger source is the negative edge of an external
digital signal (AO only).
Functions
start, trigger
Properties
Logging, Sending, TriggerCondition, TriggerConditionValue
10-95
Type
Purpose
10Type
Description
Type is associated with device objects, channels, and lines. For device objects,
Type can be Analog Input, Analog Output, or Digital I/O. Once a device
object is created, the value of Type is automatically defined.
Indicate the device object type, a channel, or a line
For channels, the only value of Type is Channel. For lines, the only value of
Type is Line. The value is automatically defined when channels or lines are
added to the device object.
Characteristics
Values
Usage
AI, AO, Common, Channel; DIO, Common, Line
Access
Read-only
Data type
String
Read-only
when running
N/A
Device Objects
For device objects, Type has these possible values
Analog Input
The device object type is analog input.
Analog Output
The device object type is analog output.
Digital IO
The device object type is digital I/O.
The value is automatically defined after the device object is created.
Channels and Lines
For channels, the only value of Type is Channel. For lines, the only value of
Type is Line. The value is automatically defined when channels or lines are
added to the device object.
10-96
Units
Purpose
10Units
Description
Units is a string that specifies the engineering units label to associate with
your data. You should use Units in conjunction with the UnitsRange property.
Characteristics
Values
See Also
Specify the engineering units label
Usage
AI, AO, Channel
Access
Read/write
Data type
String
Read-only
when running
No
The default value is Volts.
Properties
UnitsRange
10-97
UnitsRange
Purpose
10UnitsRange
Description
You use UnitsRange to scale your data to reflect particular engineering units.
Specify the range of data as engineering units
For analog input objects, the data is scaled while it is extracted from the engine
with the getdata function according to the formula
scaled value = (A/D value)(units range)/(sensor range)
The A/D value is constrained by the InputRange property, which reflects the
gain and polarity of your analog input channels. The sensor range is given by
the SensorRange property, which reflects the range of data you expect from
your sensor.
For analog output objects, the data is scaled when it is queued in the engine
with the putdata function according to the formula
scaled value = (original value)(output range)/(units range)
The output range is constrained by the OutputRange property, which specifies
the gain and polarity of your analog output channels.
For both objects, you can also use the Units property to associate a meaningful
label with your data.
Characteristics
Values
See Also
Usage
AI, AO, Channel
Access
Read/write
Data type
Two-element vector of doubles
Read-only
when running
No
The default value is determined by the default value of the InputRange or the
OutputRange property.
Functions
getdata, putdata
Properties
InputRange, OutputRange, SensorRange, Units
10-98
UserData
Purpose
10UserData
Description
UserData stores data that you want to associate with the device object.
Characteristics
Store data that you want to associate with a device object
Usage
AI, AO, DIO, Common
Access
Read/write
Data type
Any type
Read-only
when running
No
Values
The default value is an empty vector.
Example
Create the analog input object ai and add two channels to it.
ai = analoginput('nidaq',1);
addchannel(ai,0:1);
Suppose you want to access filter coefficients during the acquisition. You can
create a structure to store these coefficients, which can then be stored in
UserData.
coeff.a = 1.0;
coeff.b = -1.25;
set(ai,'UserData',coeff)
10-99
UserData
10-100
11
Device-Specific Property
Reference
Overview . . . . . . . . . . . . . . . . . . . . . 11-2
Getting Command Line Property Help . . . . . . . . . . 11-2
Properties Listed by Vendor .
National Instruments Properties
ComputerBoards Properties . .
Agilent Technologies Properties .
Sound Card Properties . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 11-3
. 11-3
. 11-4
. 11-4
. 11-5
Properties Listed Alphabetically . . . . . . . . . . . 11-6
11
Device-Specific Property Reference
Overview
The following sections provide descriptions of all toolbox device-specific
properties. Device-specific properties apply only to hardware devices of a
specific type or from a specific vendor. For example, the BitsPerSample
property is supported only for sound cards, while the NumMuxBoards property is
supported only for National Instruments devices.
In “Properties Listed by Vendor” on page 11-3, the properties are summarized
according to vendor. In “Properties Listed Alphabetically” on page 11-6, the
properties are described in detail.
Getting Command Line Property Help
To get command line property help, you should use the daqhelp function. For
example, to get help for the sound card’s BitsPerSample property
daqhelp BitsPerSample
Note You can use daqhelp without creating a device object.
You can also get property characteristics, such as the default property value,
using the propinfo function. For example, suppose you create the analog input
object ai for a sound card and want to find the default value for the
BitsPerSample property.
ai = analoginput('winsound');
out = propinfo(ai,'BitsPerSample');
out.DefaultValue
ans =
16
11-2
Properties Listed by Vendor
Properties Listed by Vendor
This section contains brief descriptions of all toolbox device-specific properties.
The properties are grouped according to these supported vendors:
• National Instruments properties
• ComputerBoards properties
• Agilent Technologies properties
• Sound card properties (multi-vendor)
You can display device-specific properties with the set function. The
device-specific properties are displayed after the base properties.
Note Some device-specific property values are not available for all devices.
Refer to your hardware documentation for detailed information about
device-specific behavior.
National Instruments Properties
The device-specific National Instruments properties for analog input (AI) and
analog output (AO) objects are given below.
Property Name
Description
Device
Objects
DriveAISenseTo
Ground
Specify if AISENSE is driven to onboard
ground.
AI
NumMuxBoards
Specify the number of external multiplexer
devices connected.
AI
OutOfDataMode
Specify how the value held by the analog
output subsystem is determined
AO
TransferMode
Specify how data is transferred from the
data acquisition device to system memory.
AI, AO
11-3
11
Device-Specific Property Reference
ComputerBoards Properties
The device-specific ComputerBoards (Measurement Computing Corporation)
properties for analog input (AI) and analog output (AO) objects are given below.
Property Name
Description
Device
Objects
OutOfDataMode
Specify how the value held by the analog
output subsystem is determined
AO
TransferMode
Specify how data is transferred from the
data acquisition device to system memory.
AI, AO
Agilent Technologies Properties
The device-specific Agilent Technologies properties for analog input (AI) and
analog output (AO) objects are given below.
11-4
Property Name
Description
Device
Objects
COLA
Specify whether the source constant-level
output is enabled or disabled.
AO
Coupling
Specify the input coupling mode.
AI
GroundingMode
Specify the input channel grounding mode.
AI
InputMode
Specify the channel input mode.
AI
InputSource
Specify the input to the A/D converter.
AI
RampRate
Specify the source ramp-up and ramp-down
rate.
AO
SourceMode
Specify the source mode.
AO
SourceOutput
Specify the source output.
AO
Properties Listed by Vendor
Property Name
Description
Device
Objects
Span
Specify the measurement bandwidth in Hz.
AI, AO
Sum
Specify whether the source sum input is
enabled or disabled.
AO
Sound Card Properties
The device-specific sound card properties for analog input (AI) and analog
output (AO) objects are given below.
Property Name
Description
Device
Objects
BitsPerSample
Specify the number of bits the sound card
uses to represent each sample.
AI, AO
StandardSample
Rates
Specify whether the valid sample rates
snap to a small set of standard values, or if
you can set the sample rate to any value
within the allowed bounds.
AI, AO
11-5
11
Device-Specific Property Reference
Properties Listed Alphabetically
This section contains detailed descriptions of all toolbox device-specific
properties. Each property reference page contains some or all of this
information:
• The property name
• A description of the property
• The property characteristics, including:
- Vendor – the vendors that support the property
- Usage – whether it is a common property, or a channel or line property and
which device objects the property is associated with
Common properties apply to all channels or lines contained by the device
object. Channel (line) properties can be set on a per-channel (per-line)
basis. The device objects supported by the Data Acquisition Toolbox
include analog input (AI), analog output (AO), and digital I/O (DIO)
objects.
- Access – whether the property is read/write or read-only
Read/write property values can be returned with the get command, and
configured with the set command.
Read-only property values can be returned with the get command, but
cannot be configured with the set command.
- Data type – the property data type
The supported data types include action function, double, string, Channel,
Line, and any.
- Read-only when running – whether a property value can be configured
while the device object is running
• Valid property values including the default value
When property values are given by an enumerated list, the default value is
usually indicated by {}. Default values for some properties are calculated by
the data acquisition engine, while others are determined by the hardware
driver. If there are device-specific enumerated values, they are listed
separately.
• An example using the property
• Related properties and functions
11-6
BitsPerSample
Purpose
11BitsPerSample
Description
BitsPerSample can be 8 or 16. If BitsPerSample is 8, the sound card represents
each sample with 8 bits. This means that each sample can be represented by
any number between 0 and 255. If BitsPerSample is 16, the sound card
represents each sample with 16 bits. This means that each sample can be
represented by any number between 0 and 65,535.
Specify the number of bits the sound card uses to represent each sample
For older Sound Blaster cards configured for full duplex operation, you may not
be able to set BitsPerSample to 16 bits for both the analog input and analog
output subsystems. Instead, you need to set one subsystem for 8 bits, and the
other subsystem for 16 bits.
Note Sound cards with greater than 16 bits are not supported by the toolbox.
Characteristics
Values
Vendor
Sound cards
Usage
AI, AO, Common
Access
Read/write
Data type
Double
Read-only
when running
Yes
8
Represent data with 8 bits.
{16}
Represent data with 16 bits.
11-7
COLA
Purpose
11COLA
Description
COLA can be Off or On. If COLA is Off, the source constant level output is
disabled. If COLA is ON, the source constant level output is enabled.
Specify whether the source constant-level output is enabled or disabled
For the Option 1D4 single-channel source, the source COLA output is shared
with the source sum input. Only one of these two may be enabled at any one
time. For prototype Option 1D4 sources only, one of the two must be enabled at
all times, and the default is for the constant-level output to be enabled.
Characteristics
Values
11-8
Vendor
Agilent Technologies
Usage
AO, Channel
Access
Read/write
Data Type
String
Read-only
while Running
Yes
{Off}
The source constant level output is disabled.
On
The source constant level output is enabled.
Coupling
Purpose
11Coupling
Description
Coupling can be DC or AC. If Coupling is DC, the input is connected directly to
the amplifier. If Coupling is AC, a series capacitor is inserted between the input
connector and the amplifier. For source channels, Coupling is generally not
used since it is usually not possible to AC couple the output of a source.
Specify the input coupling mode
After a hardware reset, Coupling is automatically set to DC.
Characteristics
Values
Vendor
Agilent Technologies
Usage
AI, Channel
Access
Read/write
Data type
String
Read-only
while Running
Yes
{DC}
The input is connected directly to the amplifier.
AC
A series capacitor is inserted between the input
connector and the amplifier.
11-9
DriveAISenseToGround
Purpose
11DriveAISenseToGround
Purpose
DriveAISenseToGround can be On or Off. If DriveAISenseToGround is Off, then
AISENSE is not driven to onboard ground. If DriveAISenseToGround is On,
then AISENSE is driven to onboard ground. AISENSE serves as the hardware
reference node when channels are configured in nonreferenced single-ended
(NRSE) mode.
Specify if AISENSE is driven to onboard ground
Channels are configured with the InputType property. If InputType is
NonReferencedSingleEnded, then the hardware device uses AISENSE for the
negative input of the amplifier, regardless of the DriveAISenseToGround value.
If InputType is Differential or SingleEnded, then the hardware device drives
AISENSE to onboard ground only if DriveAISenseToGround is On.
Characteristics
Values
See Also
Vendor
National Instruments
Usage
AI, Common
Access
Read/write
Data type
String
Read-only
when running
Yes
{Off}
Do not drive AISENSE to onboard ground.
On
Drive AISENSE to onboard ground.
Properties
InputType
11-10
GroundingMode
Purpose
11GroundingMode
Description
GroundingMode can be Grounded or Floating. If GroundingMode is Grounded,
the low side of the channel is grounded. If GroundingMode is Floating, the low
side of the channel floats thereby making the input a differential input.
GroundingMode can be set only for input channels. Source channels are never
floating, and are always grounded.
Specify the input channel grounding mode
If a smart break-out box is attached to the channel, then the grounding mode
is automatically set to the appropriate value. If a dumb break-out box (or no
break-out box) is attached to the channel, the grounding mode is given by the
GroundingMode value. In this case, no hardware settings are changed and no
errors are generated.
Characteristics
Values
Vendor
Agilent Technologies
Usage
AI, Channel
Access
Read/write
Data type
String
Read-only
while Running
Yes
{Grounded}
The input channel is grounded.
Floating
The input channel is floating.
11-11
InputMode
Purpose
11InputMode
Description
InputMode can be set to Voltage, ICP, Charge, Mic, or 200VoltMic. You can set
InputMode to Charge only if a charge break-out box is attached to the specified
channel. Your can set InputMode to Mic or 200VoltMic only if a microphone
Specify the channel input mode
break-out box is attached to the specified channel. For each input mode, the
full-scale setting is configured with the InputRange property.
There is no ICP current source inside the E1432 device. Instead, you can attach
a break-out box containing an ICP current source to the input. When this ICP
break-out box is attached, setting InputMode to ICP enables the ICP current
source in the break-out box. If there is no ICP break-out box attached to the
input, then setting InputMode to ICP does nothing.
Note If a channel is not connected to a smart break-out box, then changing
its input mode causes the input mode for all channels within the device to
change. If there is a smart break-out box present, then you can set the input
mode on a per-channel basis.
Characteristics
11-12
Vendor
Agilent Technologies
Usage
AI, Channel
Access
Read/write
Data Type
String
Read-only
while Running
Yes
InputMode
Values
See Also
{Voltage}
The input mode is set to volts.
ICP
The input mode is set to ICP.
Charge
The input mode is set to charge-amp.
Mic
The input mode is set to microphone.
200VoltMic
The input mode is set to microphone with 200 volt
supply turned on.
Properties
Coupling, InputRange, InputType
11-13
InputSource
Purpose
11InputSource
Description
For input channels, InputSource can be SwitchBox, CALIN, Ground, and
BOBCALIN. The BOBCALIN value is valid only when a smart break-out box (BoB)
is connected to the input. Smart BoB’s include a charge break-out box or a
microphone break-out box. When a smart break-out box is attached to an
E1432 or E1433 module, additional input modes are available. These
additional input modes are available through the InputMode property.
Specify the input to the A/D converter
After a hardware reset, InputSource is automatically set to SwitchBox.
Characteristics
Values
See Also
Vendor
Agilent Technologies
Usage
AI, Channel
Access
Read/write
Data Type
String
Read-only
while Running
Yes
{SwitchBox}
Select the front panel connector.
CALIN
Select the module’s CALIN line.
Ground
Ground the input.
BOBCALIN
Select the module’s CALIN line via the CAL connection
in a break-out box.
Properties
InputMode
11-14
NumMuxBoards
Purpose
11NumMuxBoards
Description
NumMuxBoards specifies the number of AMUX-64T multiplexer devices
connected to your hardware. NumMuxBoards can be 0, 1, 2, or 4. If you are using
a 1200 Series board, then NumMuxBoards can only be 0.
Characteristics
Values
Specify the number of external multiplexer devices connected
Vendor
National Instruments
Usage
AI, Common
Access
Read/write
Data type
Double
Read-only
when running
No
{0}, 1, 2, or 4
The number of AMUX-64T multiplexer devices
connected.
11-15
OutOfDataMode
Purpose
11OutOfDataMode
Description
When queued data is output to the analog output (AO) subsystem, the
hardware typically holds a value. For National Instruments and
ComputerBoards devices, the value held is determined by OutOfDataMode.
Specify how the value held by the analog output subsystem is determined
OutOfDataMode can be Hold or DefaultValue. If OutOfDataMode is Hold, then
the last value output is held by the AO subsystem. If OutOfDataMode is
DefaultValue, then the value specified by the DefaultChannelValue property
is held by the AO subsystem.
Characteristics
Values
Example
Vendor
National Instruments, ComputerBoards
Usage
AO, Common
Access
Read/write
Data type
String
Read-only
while Running
Yes
{Hold}
Hold the last output value.
DefaultValue
Hold the value specified by DefaultChannelValue.
Create the analog output object ao and add two channels to it.
ao = analogoutput('nidaq',1);
addchannel(ao,0:1);
You can configure ao so that when queued data is finished being output, a value
of 1 volt is held for both channels.
ao.OutOfDataMode = 'DefaultValue';
ao.Channel.DefaultChannelValue = 1.0;
See Also
Properties
DefaultChannelValue
11-16
RampRate
Purpose
11RampRate
Purpose
For input channels, RampRate is not generally used. For source channels,
RampRate is usually used to ensure that the source signal starts and stops
smoothly.
Characteristics
Values
Specify the source ramp-up and ramp-down rate
Vendor
Agilent Technologies
Usage
AO, Channel
Access
Read/write
Data Type
Double
Read-only
while Running
Yes
You can set RampRate to any value between 0 and 100 seconds.
11-17
SourceMode
Purpose
11SourceMode
Description
If SourceMode is set to Arbitrary, the host program must provide the data to
use for the arbitrary source signal.
Specify the source mode
Note that there is no Off source mode. To turn a source channel off, you must
make it inactive. When the source is inactive, it is normally low impedance to
ground. To make the source high impedance, set the SourceOutput property to
Open.
Characteristics
Values
See Also
Vendor
Agilent Technologies
Usage
AO, Channel
Access
Read/write
Data Type
String
Read-only
while Running
Yes
{Arbitrary}
An arbitrary source signal.
Properties
SourceOutput
11-18
SourceOutput
Purpose
11SourceOutput
Description
SourceOutput can be Normal, Grounded, Open, CALOUT, or SRC&CALOUT.
Specify the source output
If SourceOutput is Normal, the normal source output is used. This output is
defined by the source mode and other source parameters.
If SourceOutput is Grounded, the source output connector remains grounded
while the source D/A converter is internally connected to the CALOUT line in
the module.
If SourceOutput is Open, the source remains open-circuited even when the
source is started. The impedance on the output is only about 1 kilohm because
the power-fail decay circuit is still connected to the output.
If SourceOutput is CALOUT, the source output is connected to the module’s
internal CALOUT line. This allows the module’s CALOUT line to be driven by
an external signal applied at the source output connector.
If SourceOutput is SRC&CALOUT, the source output is connected to the module’s
internal CALOUT line, and the source D/A converter is also connected to the
CALOUT line. This is a combination of the Grounded and CALOUT values, and is
useful for multi-mainframe calibration.
Characteristics
Vendor
Agilent Technologies
Usage
AO, Channel
Access
Read/write
Data Type
String
Read-only
while Running
Yes
11-19
SourceOutput
Values
11-20
{Normal}
Normal source output.
Grounded
The source output connector remains grounded while
the source D/A converter is internally connected to the
CALOUT line in the module.
Open
The source remains open-circuited even when the source
is started.
CALOUT
The source output is connected to the module’s internal
CALOUT line.
SRC&CALOUT
The source output connector remains grounded while
the source D/A converter is internally connected to the
CALOUT line in the module. The source output is also
connected to the module’s internal CALOUT line.
Span
Purpose
11Span
Description
For an input channel, span specifies the maximum frequency at which valid
alias-protected data is received. Frequencies above this value are filtered out.
For a source channel, Span specifies the maximum frequency at which the
output signal will correctly track the signal that the source is attempting to
generate.
Specify the measurement bandwidth (in Hz)
The valid values for Span depend of the current clock frequency. You should set
the clock frequency before setting Span. Normally, the maximum valid span is
the clock frequency divided by 2.56. Valid spans are given by the maximum
span divided by powers of two, and the maximum span divided by five and by
powers of two. The ratio between the span and the maximum span is called the
decimation factor.
For the E1432 module, the maximum number of decimate-by-two passes
allowed is nine. Therefore, the maximum decimation factor is 5.29, and the
minimum valid span is (clock frequency)/(2.56.5.29). If the clock frequency is
larger than 51.2 kHz, then the module is unable to do a decimation factor of
one. In this case, the minimum decimation factor is two and the maximum
valid span is (clock frequency/5.12.
For the E1433 module, the maximum number of decimate-by-two passes
allowed is 12, so the maximum decimation factor is 5.212. Due to limits in the
module’s DSP processor, when the clock frequency is set higher than 102,400
Hz, it is unable to do any decimation. In this case, the only valid span is (clock
frequency)/2.56. If you attempt to use decimation when the clock frequency is
above 102,400 Hz, then an error may occur when the measurement starts.
For the Option 1D4 source board, the maximum number of decimate-by-two
passes allowed is 16, and the maximum decimation factor is 5.216.
The effective sample rate is defined as the rate at which data is received from
an input or used by a source, and is normally equal to 2.56 times the span. If
the data is oversampled, then the effective sample rate is 5.12 times the span.
If the digital filters in a module have a cutoff that is sharper than 1/2.56, then
some of the frequencies above the maximum span may contain valid
alias-protected data. This is the case with the E1432 and E1433 modules,
which have a top span filter cutoff of (clock frequency)/2.226, which is 23 kHz
when the clock frequency is 51.2 kHz, 88.3 kHz when the clock frequency is
11-21
Span
196.608 kHz. However, Span ignores the extra bandwidth so that the maximum
span is always 1/2.56 times the effective sample rate.
Span applies to an entire E1432 module rather than to one of its channels. After
a hardware reset, each module is automatically set to the maximum legal span.
Characteristics
Vendor
Agilent Technologies
Usage
AI, AO, Common
Access
Read/write
Data Type
Double
Read-only
while Running
Yes
Values
Normally, the maximum valid span is given by the clock frequency divided by
2.56. Valid spans are given by the maximum span divided by powers of two,
and the maximum span divided by five and by powers of two. The value set for
Span automatically updates the SampleRate value.
See Also
Properties
SampleRate
11-22
StandardSampleRates
Purpose
11StandardSampleRates
Description
StandardSampleRates can be On of Off. If StandardSampleRates is Off, then it
is possible to set the sample rate to any value within the bounds supported by
the hardware. For most sound cards, the lower bound is 8.000 kHz, while the
upper bound is 44.0 kHz. For newer sound cards, an upper bound of 96.0 kHz
may be supported. The specified sample rate is rounded up to the next integer
value.
Specify whether the valid sample rates snap to a small set of standard values,
or if you can set the sample rate to any value within the allowed bounds
If StandardSampleRates is On, then the available sample rates snap to a small
set of standard values. The standard values are 8.000 kHz, 11.025 kHz, 22.050
kHz, and 44.100 kHz. If you specify a sampling rate that is within one percent
of a standard value, then the sampling rate snaps to that standard value. If you
specify a sampling rate that is not within one percent of a standard value, then
the sampling rate rounds up to the closest standard value.
Regardless of the StandardSampleRates value, if you specify a sampling rate
that is outside the allowed limits, then an error is returned.
Characteristics
Values
Vendor
Sound cards
Usage
AI, AO, Common
Access
Read/write
Data type
String
Read-only
when running
Yes
{On}
The sample rate can be set only to a small set of
standard values.
Off
If supported by the hardware, the sample rate can be set
to any value within the allowed bounds, up to a
maximum of 96.0 kHz.
11-23
Sum
Purpose
11Sum
Description
Sum can be Off or On. If Sum is Off, the sum input is disabled. If Sum is On, the
sum input is enabled. The signal on the sum input is internally added to the
output that the source would otherwise produce.
Specify whether the source sum input is enabled or disabled
For the Option 1D4 single-channel source, the source sum input is shared with
the source COLA output. Only one of these two may be enabled at any one time.
For prototype Option 1D4 sources, one of the two must be enabled at all times.
By default, the constant-level output is enabled and the sum input is disabled.
Characteristics
Values
11-24
Vendor
Agilent Technologies
Usage
AO, Channel
Access
Read/write
Data Type
String
Read-only
while Running
No
{Off}
Disable the source sum input.
On
Enable the source sum input.
TransferMode
Purpose
11TransferMode
Description
For National Instruments hardware, TransferMode can be Interrupts or
SingleDMA for both analog input and analog output subsystems. If
TransferMode is Interrupts, then data is transferred from the hardware
first-in, first-out memory buffer (FIFO) to system memory using interrupts. If
TransferMode is SingleDMA, then data is transferred from the hardware FIFO
to system memory using a single direct memory access (DMA) channel. Some
boards also support a TransferMode of DualDMA for analog input subsystems.
For example, the AT-MIO-16E-1 board supports this transfer mode. If
TransferMode is DualDMA, then data is transferred from the hardware FIFO to
system memory using two DMA channels. Depending on your system
resources, data transfer via interrupts can significantly degrade system
performance.
Specify how data is transferred from the data acquisition device to system
memory
For ComputerBoards hardware, TransferMode can be Default,
InterruptPerPoint, DMA, or InterruptPerBlock. If TransferMode is Default,
the transfer mode is automatically selected by the driver based on the board
type and the sampling rate. If TransferMode is InterruptPerPoint, a single
conversion is transferred for each interrupt. You should use this property value
if your sampling rate is less the 5 kHz or you specify a small block size for
memory buffering (as defined by the BufferingConfig property). If
TransferMode is DMA, data is transferred using a single DMA channel. If
TransferMode is InterruptPerBlock, a block of data is transferred for each
interrupt. You should use this property value if your sampling rate is greater
than 5 kHz and you are using a board that has a fast maximum sampling rate.
Note that a data block is defined by the board, and usually corresponds to half
the FIFO size.
Note If your sampling rate is greater than around 5 kHz, you should avoid
using interrupts if possible. The recommended TransferMode setting for your
application will be described in your hardware documentation, and depends
on the specific board you are using and your platform configuration.
11-25
TransferMode
Characteristics
Values
Vendor
National Instruments, ComputerBoards
Usage
AI, AO, Common
Access
Read/write
Data type
String
Read-only
when running
Yes
National Instruments
Interrupts
Transfer data using interrupts.
SingleDMA
Transfer data using a single DMA channel.
DualDMA
Transfer data using two DMA channels.
This default property value is supplied by the driver. For most devices that
support data transfer via interrupts and DMA, SingleDMA is the default value.
ComputerBoards
11-26
{Default}
The transfer mode is automatically selected by the
driver based on the board type and the sampling rate.
InterruptPer
Point
Transfer single data points using interrupts.
DMA
Transfer data using a single DMA channel (AI only).
InterruptPer
Block
Transfer a block of data using interrupts (AI only).
A
Troubleshooting Your
Hardware
Overview
. . . . . . . . . . . . . . . . . . . . . A-2
Troubleshooting National Instruments Hardware . . . A-3
What Driver Are You Using? . . . . . . . . . . . . . . A-3
Is Your Hardware Functioning Properly? . . . . . . . . . A-5
Troubleshooting ComputerBoards Hardware . . . . . A-6
What Driver Are You Using? . . . . . . . . . . . . . . A-6
Is Your Hardware Functioning Properly? . . . . . . . . . A-8
Troubleshooting Agilent Technologies Hardware . . . A-9
What Driver Are You Using? . . . . . . . . . . . . . . A-9
Is Your Hardware Functioning Properly? . . . . . . . . . A-10
Troubleshooting Sound Cards .
Microphone and Sound Card Types
Testing with a Microphone . . . .
Testing with a CD Player . . . .
Running in Full Duplex Mode . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. A-12
. A-15
. A-16
. A-16
. A-18
Other Things to Try . . . . . . . . . . . . . . . . A-19
Registering the Hardware Driver Adaptor . . . . . . . . A-19
Contacting The MathWorks . . . . . . . . . . . . . . A-20
A
Troubleshooting Your Hardware
Overview
This appendix describes simple tests you can perform to troubleshoot your
National Instruments, ComputerBoards, Agilent Technologies, and Windows
sound card hardware. The tests involve using software provided by the vendor
or the operating system (sound cards), and does not involve using the Data
Acquisition Toolbox.
To accurately test your hardware, you should use these tools to match the
requirements of your data acquisition session. For example, you should select
the appropriate sampling rate, number of channels, acquisition mode
(continuous or single-point), and input range.
Note If you cannot access your board using the vendor’s software, then you
will not be able to do so with the Data Acquisition Toolbox.
If these tests do not help you, then you may need to register the hardware
driver adaptor or contact The MathWorks for support. Contact information is
provided in “Contacting The MathWorks” on page A-20 as well as in the
beginning of this guide. If the problem is with your hardware, then you should
contact the hardware vendor.
A-2
Troubleshooting National Instruments Hardware
Troubleshooting National Instruments Hardware
If you are having trouble using the Data Acquisition Toolbox with a supported
National Instruments board, the reason may be that:
• You are using a hardware driver that is incompatible with the toolbox.
• Your hardware is not functioning properly.
What Driver Are You Using?
The Data Acquisition Toolbox is compatible only with specific versions of the
NI-DAQ driver, and is not guaranteed to work with any other versions. For a
list of the NI-DAQ driver versions that are compatible with the Data
Acquisition Toolbox, refer to the product page on the MathWorks Web site at
http://www.mathworks.com/products/daq/.
If you think your driver is incompatible with the Data Acquisition Toolbox,
then you should verify that your hardware is functioning properly before
updating drivers. If your hardware is functioning properly, then you are
probably using unsupported drivers. Visit the National Instruments Web site
at http://www.natinst.com/ for the latest NI-DAQ drivers.
You can find out which version of NI-DAQ you are using with National
Instruments’ Measurement & Automation Explorer. You should be able to
access this program through the Windows Desktop. The driver version is
available through the Help menu.
Help->About Measurement & Automation Explorer->System
Info->Software
A-3
A
Troubleshooting Your Hardware
For example, the version of NI-DAQ used by a PCI-6024E board is shown
below.
A-4
Troubleshooting National Instruments Hardware
Is Your Hardware Functioning Properly?
To troubleshoot your National Instruments hardware, you should use the Test
Panel. The Test Panel allows you to test each subsystem supported by your
board, and is installed as part of the NI-DAQ driver software. You can access
the Test Panel by right-clicking on the appropriate device in the Measurement
& Automation Explorer and choosing Test Panel.
For example, suppose you want to verify that the analog input subsystem on
your PCI-6024E board is operating correctly. To do this, you should connect a
known signal – such as that produced by a function generator – to one or more
channels using a screw terminal panel. The result of such a test is shown below
for channel 1.
If the Test Panel does not provide you with the expected results for the
subsystem under test, and you are sure that your test setup is configured
correctly, then the problem is probably with the hardware.
To get support for your National Instruments hardware, visit their Web site at
http://www.natinst.com/.
A-5
A
Troubleshooting Your Hardware
Troubleshooting ComputerBoards Hardware
If you are having trouble using the Data Acquisition Toolbox with a supported
ComputerBoards (Measurement Computing Corporation) board, the reason
may be that:
• You are using a hardware driver that is incompatible with the toolbox.
• Your hardware is not functioning properly.
What Driver Are You Using?
The Data Acquisition Toolbox is compatible only with specific versions of the
the Universal Library drivers or the associated release of the InstaCal
software, and is not guaranteed to work with any other versions. For a list of
the driver versions that are compatible with the Data Acquisition Toolbox,
refer to the product page on the MathWorks Web site at http://
www.mathworks.com/products/daq/.
If you think your driver is incompatible with the Data Acquisition Toolbox,
then you should verify that your hardware is functioning properly before
updating drivers. If your hardware is functioning properly, then you are
probably using unsupported drivers. Visit the ComputerBoards Web site at
http://www.computerboards.com/ for the latest drivers.
Suppose you are using InstaCal software with your hardware. You can access
this software through the Windows Start button.
Start->Programs->ComputerBoards->InstaCal
The driver version is available through the Help menu.
Help->About InstaCal
A-6
Troubleshooting ComputerBoards Hardware
For example, the version of InstaCal used by a PCI-DAS4020/12 board is
shown below.
A-7
A
Troubleshooting Your Hardware
Is Your Hardware Functioning Properly?
To troubleshoot your ComputerBoards hardware, you should use the test
feature provided by InstaCal. To access this feature, select the board you want
to test from the PC Board List, and select Analog from the Test menu.
For example, suppose you want to verify that the analog input subsystem on
your PCI-DAS4020/12 board is operating correctly. To do this, you should
connect a known signal – such as that produced by a function generator – to
one of the channels using a BNC cable. The result of such a test is shown below
for channel 0.
If InstaCal does not provide you with the expected results for the subsystem
under test, and you are sure that your test setup is configured correctly, then
the problem is probably with the hardware.
To get support for your ComputerBoards hardware, visit their Web site at
http://www.computerboards.com/.
A-8
Troubleshooting Agilent Technologies Hardware
Troubleshooting Agilent Technologies Hardware
If you are having trouble using the Data Acquisition Toolbox with a supported
Agilent Technologies device, the reason may be that:
• You are using a hardware driver that is incompatible with the toolbox.
• Your hardware is not functioning properly.
What Driver Are You Using?
The Data Acquisition Toolbox is compatible only with specific versions of the
HP E1432 driver, and is not guaranteed to work with any other versions. You
can find out which driver version you are using with the Soft Front Panel,
which is described in the next section.
If you think your driver is incompatible with the Data Acquisition Toolbox,
then you should verify that your hardware is functioning properly before
updating drivers. If your hardware is functioning properly, then you are
probably using unsupported drivers. Visit the Agilent Web site at http://
agilent.com/ for the latest drivers.
For a list of the HP E1432 driver versions that are compatible with the Data
Acquisition Toolbox, refer to the product page on the MathWorks Web site at
http://www.mathworks.com/products/daq/.
A-9
A
Troubleshooting Your Hardware
Is Your Hardware Functioning Properly?
To troubleshoot your Agilent hardware, you should use the HP E1432 Soft
Front Panel. The Soft Front Panel allows you to test each module supported by
the HP E1432 driver software, and is installed as part of this software. You can
access the Soft Front Panel through the Windows Start button.
Start->Programs->hpe1432->HP E1432 Soft Front Panel
For example, suppose you want to verify that the HP E1432 module is
operating correctly. To do this, you should connect a known signal – such as
that produced by a function generator – to the module. You then configure the
input parameters as shown below.
A-10
Troubleshooting Agilent Technologies Hardware
The result of such a test is shown below for channel 1.
If the Soft Front Panel does not provide you with the expected results for the
module under test, and you are sure that your test setup is configured
correctly, then the problem is probably with the hardware.
To get support for your Agilent Technologies hardware, visit their Web site at
http://www.agilent.com/.
A-11
A
Troubleshooting Your Hardware
Troubleshooting Sound Cards
You can verify that your sound card is functioning properly by recording data
and then playing back the recorded data. Recording data uses the sound card’s
analog input subsystem, while playing back data uses the sound card’s analog
output subsystem. Successful completion of these two tasks indicates your
sound card works properly. The data to be recorded can come from two sources:
• A microphone
• A CD player
The first thing you should do is enable your sound card’s ability to record and
play data. This is done using the Microsoft Windows Multimedia Properties
dialog box. You can access this dialog box using the Windows Start button.
Start->Settings->Control Panel->Multimedia
The Multimedia Properties dialog box for a Windows NT 4.0 platform is
shown below, and is configured for both playback and recording.
A-12
Troubleshooting Sound Cards
You can record data and then play it back using the Windows Sound Recorder
panel. To access this application
Start->Programs->Accessories->Multimedia->Sound Recorder
The figure below shows how to record and play data.
Play button
Record button
You must also make sure that your microphone or CD player is enabled for
recording and playback using the Windows Volume Control panel. To access
this application
Start->Programs->Accessories->Multimedia->Volume Control
The Volume Control panel is shown below. The CD, microphone, and line
devices are enabled for playback when the Mute check box is unchecked for the
CD Balance, Microphone Balance, and Line Balance volume controls,
respectively. You can play .WAV files by leaving the Mute check box unchecked
for the Wave Balance volume control.
A-13
A
Troubleshooting Your Hardware
If the CD, microphone, or Wave Output controls do not appear in the Volume
Control panel, you must modify the playback properties by selecting
Properties from the Options menu. The Properties dialog box is shown below
for playback devices. Select the appropriate device check box to enable
playback.
To check if the CD and microphone are enabled for recording, select the
Recording radio button in the Properties dialog box, and then select the
appropriate device check box to enable recording. The Properties dialog box is
shown below for recording devices.
A-14
Troubleshooting Sound Cards
The Recording Control panel is shown below. You enable the CD or
microphone for recording when the Select check box is checked for the CD
Balance or Microphone Balance controls, respectively.
Microphone and Sound Card Types
Your microphone will be one of two possible types: powered or unpowered. You
can use powered microphones only with Sound Blaster or Sound
Blaster-compatible microphone inputs. You can use unpowered microphones
with any sound card microphone input. Many laptops must use unpowered
microphones since they do not have Sound Blaster compatible sound cards.
As shown below, you can easily identify these two microphone types by their
jacks.
Unpowered microphone jack
Powered microphone jack
You can find out which sound card brand you have installed by selecting the
Devices tab on the Multimedia Properties dialog box. Refer to
“Troubleshooting Sound Cards” on page A-12 for a picture of this dialog box.
A-15
A
Troubleshooting Your Hardware
Testing with a Microphone
To test your sound card with a microphone, follow these steps:
1 Plug the microphone into the appropriate sound card jack. For a Sound
Blaster sound card, this jack is labeled MIC IN.
2 Record audio data by selecting the Record button on the Sound Recorder
and then speak into the microphone. While recording, the green line in the
Sound Recorder should indicate that data is being captured. If this is the
case, then the analog input subsystem on your sound card is functioning
properly.
3 After recording the audio data, save it to disk. The data is automatically
saved as a .WAV file.
4 Play the saved .WAV file. While playing, the green line in the Sound
Recorder should indicate that data is being captured. If this is the case,
then the analog output subsystem on your sound card is functioning
properly.
If you are not able to record or play data, make sure that the sound card and
input devices are enabled for recording and playback as described in the
beginning of this section.
Testing with a CD Player
To test your sound card with a CD player, follow these steps:
1 Check that your CD is physically connected to your sound card.
- Open your computer and locate the back of the CD player.
- If there is a wire connecting the Audio Out CD port with the sound card,
you can record audio data from your CD. If there is no wire connecting your
CD and sound card, you must either make this connection or use the
microphone to record data.
A-16
Troubleshooting Sound Cards
2 Put an audio CD into your CD player. The Windows CD Player application
should be automatically invoked and begin playing the CD. If this doesn’t
occur, then you must access the application manually.
Start->Programs->Accessories->Multimedia->CD Player
The figure below shows how to play a CD with the CD Player application.
Play button
3 While the CD is playing, record audio data by selecting the Record button
on the Sound Recorder. While recording, the green line in the Sound
Recorder should indicate that data is being captured. If this is the case,
then the analog input subsystem on your sound card is functioning properly.
Note that the CD player converts digital audio data to analog audio data.
Therefore, the CD sends analog data to the sound card.
4 After recording the audio data, save it to disk. The data is automatically
saved as a .WAV file.
5 Play the saved .WAV file. While playing, the green line in the Sound
Recorder should indicate that data is being captured. If this is the case,
then the analog output subsystem on your sound card is functioning
properly.
If you are not able to record or play data, make sure that the sound card and
input devices are enabled for recording and playback as described in the
beginning of this section.
A-17
A
Troubleshooting Your Hardware
Running in Full Duplex Mode
The term full duplex refers to a system that can send and receive information
simultaneously. For sound cards, full duplex means that the device can acquire
input data via an analog input subsystem while outputting data via an analog
output subsystem at the same time.
Note that full tells you nothing about the bit resolution or the number of
channels used in each direction. Therefore, sound cards can simultaneously
receive and send data using 8 or 16 bits while in mono or stereo mode. A
common restriction of full duplex mode is that both subsystems must be
configured for the same sampling rate.
If you try to run your card in full duplex mode and the following error is
returned
?? Error using ==> daqdevice/start
Device 'Winsound' already in use.
then your sound card is not configured properly, it does not support this mode,
or you don’t have the correct driver installed.
If your card supports full duplex mode, then you may need to enable this
feature through the Multimedia Properties dialog box. Refer to
“Troubleshooting Sound Cards” on page A-12 for a picture of this dialog box. If
you are unsure about the full duplex capabilities of your sound card, refer to its
specification sheet or user manual. It is usually very easy to update your
hardware drivers to the latest version by visiting the vendor’s Web site.
A-18
Other Things to Try
Other Things to Try
If troubleshooting your hardware does not help you, then you may need to
register the hardware driver adaptor or contact The MathWorks for support.
Registering the Hardware Driver Adaptor
When you first create a device object, the associated hardware driver adaptor
is automatically registered so that the data acquisition engine can make use of
its services.
The hardware driver adaptors included with the toolbox are all located in the
daq/private directory. The full name for each adaptor is shown below.
Table A-1: Supported Vendors and Full Adaptor Names
Vendor
Full Adaptor Name
National Instruments
mwnidaq.dll
ComputerBoards
mwcbi.dll
Agilent Technologies
mwhpe1432.dll
Windows sound cards
mwwinsound.dll
If for some reason, a toolbox adaptor is not automatically registered, then you
need to register it manually using the daqregister function. For example, to
manually register the sound card adaptor
daqregister('winsound');
If you are using a third-party adaptor, then you may need to register it
manually. If so, you must supply the full pathname to daqregister. For
example, to register the third-party adaptor myadaptor.dll
daqregister('D:/MATLABR12/toolbox/daq/myadaptors/myadaptor.dll')
Note You must install the associated hardware driver before adaptor
registration can occur.
A-19
A
Troubleshooting Your Hardware
Contacting The MathWorks
If you need support from The MathWorks, visit our Web site at
http://www.mathworks.com/support/ or e-mail us at
[email protected]
Before contacting The MathWorks, you should run the daqsupport function.
This function returns diagnostic information such as:
• The versions of the MathWorks products you are using
• Your MATLAB path
• The characteristics of your hardware
The output from daqsupport is automatically saved to a text file, which you can
use to help troubleshoot your problem. For example, if you are having trouble
with your sound card, type
daqsupport('winsound')
A-20
B
Managing Your Memory
Resources
Overview
. . . . . . . . . . . . . . . . . . . . . B-2
How Much Memory Do You Need? . . . . . . . . . . B-3
Example: Managing Memory Resources
. . . . . . . B-4
B
Managing Your Memory Resources
Overview
When data is acquired from an analog input subsystem or output to an analog
output subsystem, it must be temporarily stored in computer memory.
The Data Acquisition Toolbox allocates memory in terms of data blocks. A data
block is defined as the smallest “slice” of memory that the data acquisition
engine can usefully manipulate. For example, acquired data is logged to a disk
file using an integral number of data blocks. A representation of allocated
memory using n data blocks is shown below.
block 1
block 2
block 3
...
block n
The Data Acquisition Toolbox strives to make memory allocation as simple as
possible. For this reason, the data block size and number of blocks are
automatically calculated by the engine. This calculation is based on the
parameters of your acquisition such as the sampling rate, and is meant to apply
to most common data acquisition applications. Additionally, as data is
acquired, the number of blocks dynamically increases up to a predetermined
limit. However, the engine cannot guarantee that the appropriate block size,
number of blocks, or total memory is allocated under these conditions:
• You select certain property values. For example, if the samples to acquire per
trigger is significantly less than the FIFO buffer of your hardware.
• You acquire data at the limits of your hardware, your computer, or the
toolbox. In particular, if you are acquiring data at very high sampling rates,
then the allocated memory must be carefully evaluated to guarantee that
samples are not lost.
You are free to override the memory allocation rules used by the engine and
manually change the block size and number of blocks provided the device object
is not running. However, you should do so only after careful consideration since
system performance may be adversely affected, which may result in lost data.
You can manage memory resources using the BufferingConfig property and
the daqmem function. With BufferingConfig, you can configure and return the
block size and number of blocks used by a device object. With daqmem, you can
return the current state of the memory resources used by a device object, and
configure the maximum memory that one or more device objects can use.
B-2
How Much Memory Do You Need?
How Much Memory Do You Need?
The memory (in bytes) required for data storage depends on these factors:
• The number of hardware channels you use
• The number of samples you need to store in the engine
• The data type size of each sample
The memory required for data storage is given by the formula
memory required = samples stored × channel number × data type
Of course, the number of samples you need to store in the engine at any time
depends on your particular needs. The memory used by a device object is given
by the formula
memory used = block size × block number × channel number × data type
The block size and block number is given by the BufferingConfig property.
The data type is given by the NativeDataType field of the daqhwinfo function.
You can display the memory resources used by (and available to) a device object
with the daqmem function. For analog input objects, memory is used when
channels are added. For analog output objects, memory is used when data is
queued in the engine. For both device objects, the memory used can
dynamically change based on the number of samples acquired or queued.
B-3
B
Managing Your Memory Resources
Example: Managing Memory Resources
Suppose you create the analog input object ai for a sound card, add two
channels to it, and configure a four second acquisition using a sampling rate of
11.025 kHz.
ai = analoginput('winsound');
addchannel(ai,1:2);
set(ai,'SampleRate',11025);
set(ai,'SamplesPerTrigger',44100);
You return the default block size and number of blocks with the
BufferingConfig property.
get(ai,'BufferingConfig')
ans =
1024
30
You return the memory resources with the daqmem function.
daqmem(ai)
ans =
UsedBytes: 122880
MaxBytes: 18011136
The UsedBytes field tells you how much memory is currently used by ai, while
the MaxBytes field tells you the maximum memory that ai can use to store
acquired data. Note that the value returned for MaxBytes depends on the total
available computer memory, and may be different for your platform.
You can verify the UsedBytes value with the formula given in the previous
section. However, you must first find the size (in bytes) of each sample using
the daqhwinfo function.
hwinfo = daqhwinfo(ai);
hwinfo.NativeDataType
ans =
int16
The value of the NativeDataType field tells you that each sample requires two
bytes. Therefore, the initial allocated memory is 122,880 bytes. However, if you
want to keep all the acquired data in memory, then 176,400 bytes are required.
B-4
Example: Managing Memory Resources
The Data Acquisition Toolbox will accommodate this memory requirement by
dynamically increasing the number of data blocks after you start ai.
start(ai)
After all the data is acquired, you can examine the final number of data blocks
used by ai.
ai.BufferingConfig
ans =
1024
44
The final total memory used is
daqmem(ai)
ans =
UsedBytes: 180224
MaxBytes: 18011136
Note that this was more than enough memory to store all the acquired data
B-5
B
Managing Your Memory Resources
B-6
C
Glossary
C
Glossary
C-2
Accuracy
A determination of how close a measurement comes to the true value.
Acquiring data
The process of inputting an analog signal from a sensor into an analog input
subsystem, and then converting the signal into bits that the computer can read.
Action function
An M-file function that you construct to suit your specific data acquisition
needs. If you supply the action function as the value for an action property,
then the function is executed when the event associated with the action
property occurs.
Action property
A property associated with a specific event type. When an event occurs, the
engine examines the associated action property. If an action function is given
as the value for the action property, then that function is executed. All event
types have an action property.
Actuator
A device that converts data output from your computer into a physical variable.
Adaptor
The interface between the data acquisition engine and the hardware driver.
The adaptor’s main purpose is to update the engine with properties that are
unique to the hardware device.
A/D converter
An analog input subsystem.
Analog input
subsystem
Hardware that converts real-world analog input signals into bits that a
computer can read. This is also referred to as an AI subsystem, an A/D
converter, or an ADC.
Analog output
subsystem
Hardware that converts digital data to a real-world analog signal. This is also
referred to as an AO subsystem, a D/A converter, or a DAC.
Bandwidth
The range of frequencies present in the signal being measured. You can also
think of bandwidth as being related to the rate of change of the signal. A slowly
varying signal has a low bandwidth, while a rapidly varying signal has a high
bandwidth.
Base property
A property that applies to all supported hardware subsystems of a given type
(analog input, analog output, etc.). For example, the SampleRate property is
supported for all analog input subsystems regardless of the vendor.
Channel
A component of an analog input subsystem or an analog output subsystem that
you read data from, or write data to.
Channel group
The collection of channels contained by an analog input object or an analog
output object. For scanning hardware, the channel group defines the scan
order.
Channel
property
A property that applies to individual channels.
Channel skew
The time gap between consecutively sampled channels. Channel skew exists
only for scanning hardware.
Common
property
A property that applies to every channel or line contained by a device object.
Configuration
The process of supplying the device object with the resources and information
necessary to carry out the desired tasks. Configuration consists of two steps:
adding channels or lines, and setting property values to establish the desired
behavior
Counter/timer
subsystem
Hardware that is used for event counting, frequency and period measurement,
and pulse train generation. This subsystem is not supported by the Data
Acquisition Toolbox.
D/A converter
A digital to analog subsystem.
Data acquisition
session
A process that encompasses all the steps you must take to acquire data using
an analog input object, output data using an analog output object, or read
values from or write values to digital I/O lines. These steps are broken down
into initialization, configuration, execution, and termination.
Data block
The smallest “slice” of memory that the data acquisition engine can usefully
manipulate.
Device object
A MATLAB object that allows you to access a hardware device.
Device-specific
property
BitsPerSample property is supported only for sound cards.
Differential
input
A property that applies only for specific hardware devices. For example, the
Input channel configuration where there are two signal wires associated with
each input signal — one for the input signal and one for the reference (return)
signal. The measurement is the difference in voltage between the two wires,
which helps reduce noise and any voltage common to both wires.
C-3
C
Glossary
C-4
Digital I/O
subsystem
Hardware that sends or receives digital values (logic levels). This is also
referred to as a DIO subsystem.
DMA
Direct memory access (DMA) is a system of transferring data whereby samples
are automatically stored in system memory while the processor does something
else.
Engine
A MEX-file dynamic link library (DLL) file that stores the device objects and
associated property values that control your data acquisition application,
controls the synchronization of events, and controls the storage of acquired or
queued data.
Engineering
units properties
Channel properties that allow you to linearly scale input or output data.
Event
An event occurs at a particular time after a condition is met and may result in
one or more actions. Many event types are automatically generated by the
toolbox, while others are generated only after you configure specific properties.
Execution
The process of starting the device object and hardware device. While an analog
input object is executing, you can acquire data. While an analog output object
is executing, you can output data.
FIFO buffer
The first-in first-out (FIFO) memory buffer, which is used by data acquisition
hardware to temporarily store data.
Full duplex
A system that can send and receive information simultaneously. For sound
cards, full duplex means that the device can acquire input data via an analog
input subsystem while outputting data via an analog output subsystem at the
same time.
Input range
The span of input values for which an A/D conversion is valid.
Interrupts
The slowest but most common method to move acquired data from the
hardware to system memory. Interrupt signals can be generated when one
sample is acquired or when multiple samples are acquired.
Line
A component of a digital I/O subsystem that you can read digital values from,
or write digital value to.
Line group
The collection of lines contained by a digital I/O object.
Line properties
Properties that are configured for individual lines.
Logging
A state of the Data Acquisition Toolbox where an analog input object stores
acquired data to memory or a log file.
Noise
Any measurement that is not part of the phenomena of interest.
Onboard clock
A timer chip on the hardware board which is programmed to generate a pulse
train at the desired rate. In most cases, the onboard clock controls the sampling
rate of the board.
Output range
The span of output values for which a D/A conversion is valid.
Postrigger data
Data that is acquired and stored in the engine after the trigger event occurs.
Precision
A determination of how exactly a result is determined without reference to
what the result means.
Pretrigger data
Data that is acquired and stored in the engine before the trigger event occurs.
Properties
A characteristic of the toolbox or the hardware driver that you can configure to
suit your needs. The property types supported by the toolbox include base
properties, device-specific properties, common properties, and channel or line
properties.
Quantization
The process of converting an infinitely precise analog signal to a binary
number. This process is performed by an A/D converter.
Queuing data
The process of storing data in the engine for eventual output to an analog
output subsystem.
Running
A state of the Data Acquisition Toolbox where a device object is executing.
Sample rate
The per-channel rate (in samples/second) that an analog input or analog output
subsystem converts data.
Sampling
The process whereby an A/D converter or a D/A converter takes a “snapshot” of
the data at discrete times. For most applications, the time interval between
samples is kept constant (e.g., sample every millisecond) unless externally
clocked.
C-5
C
Glossary
C-6
Scanning
hardware
Data acquisition hardware that samples a single input signal, converts that
signal to a digital value, and then repeats the process for every input channel
used.
Sending
A state of the Data Acquisition Toolbox where an analog output object is
outputting (sending) data from the engine to the hardware.
Sensor
A device that converts a physical variable into a signal that you can input into
your data acquisition hardware.
Signal
conditioning
The process of making a sensor signal compatible with the data acquisition
hardware. Signal conditioning includes amplification, filtering, electrical
isolation, and multiplexing.
Single-ended
input
Input channel configuration where there is one signal wire associated with
each input signal, and all input signals are connected to the same ground.
Single-ended measurements are more susceptible to noise than differential
measurements due to differences in the signal paths.
SS/H hardware
Data acquisition hardware that simultaneously samples all input signals, and
then holds the values until the A/D converter digitizes all the signals.
Subsystem
A data acquisition hardware component that performs a specific task. The Data
Acquisition Toolbox supports analog input, analog output, and digital I/O
subsystems.
Trigger event
An analog input trigger event initiates data logging to memory or a disk file.
An analog output trigger event initiates the output of data from the engine to
the hardware.
Index
The following abbreviations are used in this index:
Agilent – Agilent Technologies
AI – analog input
AO – analog output
CBI – ComputerBoards
DIO – digital I/O
HP – Hewlett-Packard
NI – National Instruments
A
A/D converter 1-7
input range 5-56
sampling rate 4-9
absolute time 5-19
accuracy 1-30
acquiring data 3-22
continuous
samples per trigger 5-23
simultaneous input and output 6-37
trigger repeats 5-30
single point 9-61
action function 5-52
action properties
AI object 5-46
AO object 6-27
saving property values to a MAT-file 8-3
actuator 1-4
adaptor kit 2-7
adaptors
registering A-19
supported hardware 2-7
third-party A-19
addchannel
AI object 4-4
AO object 6-4
addline 7-4
addmuxchannel 9-17
Agilent Technologies hardware
channel configuration 5-5
decimation factor 11-21
driver A-9
properties 11-4
trigger types
AI object 5-44
AO object 6-26
troubleshooting A-9
AISENSE 11-10
alias 1-37
AMUX-64T
adding channels 9-17
channel indices 9-72
analog input object
acquisition
continuous 5-23
single point 9-61
adding channels 4-4
creating 4-3
display summary 4-23
engineering units 5-56
events and actions 5-46
extracting data 5-13
logging
data 4-14
information to disk 8-6
previewing data 5-9
properties
basic setup 4-9
channel 10-7
common 10-3
configuring 3-18
sampling rate 4-9
starting 4-13
I-1
Index
status evaluation 4-22
stopping 4-14
triggers
configuring 5-20
types 4-11
analog output object
adding channels 6-4
creating 6-3
display summary 6-15
engineering units 6-34
events and actions 6-27
output
continuous 6-22
single point 9-82
properties
basic setup 6-6
channel 10-11
common 10-8
configuring 3-18
queueing data for output 6-9
sampling rate 6-6
starting 6-9
status evaluation 6-14
stopping 6-10
triggers
configuring 6-21
types 6-8
analog triggers
Agilent hardware 5-45
CBI hardware 5-43
NI hardware 5-39
analoginput 4-3
Agilent hardware 9-19
NI hardware 4-19
sound card 4-16
analogoutput 6-3
Agilent hardware 9-22
I-2
NI hardware 6-12
sound card 6-11
antialiasing filter 1-34
array
data returned by getdata 5-13
device object 3-5
B
bandwidth 1-10
base properties 3-13
binary vector 7-10
binvec2dec 7-12
block. See data block
blocking function
getdata 5-13
putdata 6-9
board ID 4-3
buffer
configuration 10-15
extracting data 5-14
previewing data 5-10
queuing data 6-17
C
calibration 1-3
Channel 4-6
channel gain list 4-5
channel group
AI object 4-4
AO object 6-4
channel names 4-7
channel properties 3-12
AI object 10-7
AO object 10-11
channel skew 5-7
Index
ChannelName 4-7
channels 3-8
adding
AI object 4-4
AO object 6-4
descriptive names 4-6
input configuration 5-4
mapping to hardware IDs 3-9
referencing 4-6
ChannelSkew 5-8
ChannelSkewMode 5-8
cleaning up the MATLAB environment
clear 3-25
delete 3-25
with daqfind 9-48
clear 3-25
clipping 6-35
clock 5-37
clocked acquisition 1-23
common properties 3-12
AI object 10-3
AO object 10-8
DIO object 10-12
ComputerBoards hardware
channel configuration 5-5
driver A-6
properties 11-4
trigger types (AI) 5-41
troubleshooting A-6
configuring property values
dot notation 3-18
set 3-18
constructor 3-4
Contents 2-12
continuous acquisition
example using AI and AO 6-37
samples per trigger 5-23
trigger repeats 5-30
continuous output 6-22
creation function 3-4
custom adaptors 2-7
D
D/A converter 1-7
output range 6-34
sampling rate 6-6
daqaction
AI example 5-53
default property value
data missed event (AI) 5-47
run-time error event
AI object 5-47
AO object 6-28
daqfind 3-25
daqhelp 2-20
daqhwinfo 2-17
daqmem B-4
daqpropedit 3-20
daqread 8-8
daqregister A-19
daqreset 9-44
daqschool 2-13
daqsupport A-20
data
extracting from engine 5-13
previewing 5-9
queuing for output 6-17
data acquisition session 3-2
acquiring data (AI) 4-13
adding channels
AI object 4-4
AO object 6-4
adding lines 7-4
I-3
Index
cleaning up 3-25
configuring properties
AI object 4-9
AO object 6-6
creating a device object
AI object 4-3
AO object 6-3
DIO object 7-3
loading 8-3
outputting data (AO) 6-9
saving 8-3
data block B-2
polling 5-11
data flow
acquired data 2-4
output data 2-6
data missed event 5-47
DataMissedAction 5-47
debugging your hardware A-20
daqsupport A-20
dec2binvec 7-10
delete 3-25
demos 2-13
descriptive names
channels 4-6
lines 7-8
device ID 4-3
device object 3-4
array 3-5
simultaneous input and output 6-37
configuring property values 3-18
copying 3-6
creating
AI object 4-3
AO object 6-3
DIO object 7-3
invalid 3-7
I-4
loading 8-3
saving 8-3
specifying property names 3-19
starting 3-23
stopping 3-24
device-specific properties 3-13
Agilent hardware 11-4
CBI hardware 11-4
NI hardware 11-3
sound cards 11-5
differential inputs 1-24
digital I/O object
adding lines 7-4
creating 7-3
display summary 7-18
port types 7-5
properties
common 10-12
line 10-13
reading values 7-12
starting 7-16
status evaluation 7-18
stopping 7-16
writing values 7-10
digital triggers
Agilent hardware
AI object 5-45
AO object 6-26
CBI hardware (AI) 5-42
NI hardware
AI object 5-39
AO object 6-25
digital values
reading 7-12
writing 7-10
digitalio 7-3
disk logging 10-47
Index
display summary
AI object 4-23
AO object 6-15
DIO object 7-18
DMA 1-28
NI hardware 11-25
documentation examples 2-12
dot notation
configuring property values 3-18
returning property values 3-17
saving property values to an M-file 8-3
driver
Agilent hardware A-9
CBI hardware A-6
NI hardware A-3
E
E1432 driver A-9
engine 2-4
extracting data from 5-13
queuing data to 6-17
engineering units
AI object 5-56
AO object 6-34
event types
data missed (AI) 5-47
input overrange (AI) 5-47
run-time error
AI object 5-47
AO object 6-28
samples acquired (AI) 5-47
samples output (AO) 6-28
start
AI object 5-48
AO object 6-28
stop
AI object 5-48
AO object 6-28
timer
AI object 5-48
AO object 6-28
trigger
AI object 5-48
AO object 6-29
EventLog
AI object 5-49
AO object 6-29
events 2-3
AI object 5-46
AO object 6-27
displaying with showdaqevents
AI object 5-36
AO object 6-24
example index 2-12
examples
acquiring data
NI hardware 4-19
sound card 4-15
adding lines 7-9
generating timer events (DIO) 7-17
logging and retrieving information (AI) 8-10
outputting data with a sound card 6-11, 6-12
performing a linear conversion
AI object 5-57
AO object 6-35
polling the data block (AI) 5-11
previewing and extracting data 5-15
reading and writing DIO values 7-13
retrieving event information
AI object 5-51
AO object 6-30
using action properties
AI object 5-53
I-5
Index
AO object 6-31
using putdata 6-19
voice activation (AI)
pretriggers 5-28
repeating triggers 5-31
software trigger 5-23
execution
AI object 4-13
AO object 6-9
DIO object 7-15
external clock 1-23
clock sources 10-24
extracting data 5-13
daqfind 9-28
daqhelp 9-30
daqhwinfo 9-32
daqmem 9-34
daqpropedit 9-37
daqread 9-39
daqregister 9-43
daqreset 9-44
daqschool 9-45
dec2binvec 9-46
delete 9-48
digitalio 9-50
disp 9-52
flushdata 9-53
get 9-55
I-6
F
getdata 9-57
fft 4-17
getsample 9-61
FIFO 1-27
getvalue 9-62
TransferMode 11-25
ischannel 9-63
filtering 1-34
finding device objects 9-28
floating signal 1-24
flow of data
acquired 2-4
output 2-6
flushdata 9-53
full duplex A-18
BitsPerSample 11-7
functions
addchannel 9-9
addline 9-14
addmuxchannel 9-17
analoginput 9-18
analogoutput 9-21
binvec2dec 9-24
clear 9-25
daqaction 9-27
isdioline 9-64
isvalid 9-65
length 9-67
load 9-69
makenames 9-71
muxchanidx 9-72
obj2mfile 9-74
peekdata 9-76
propinfo 9-78
putdata 9-80
putsample 9-82
putvalue 9-83
save 9-84
set 9-85
setverify 9-88
showdaqevents 9-90
size 9-92
start 9-94
Index
stop 9-95
trigger 9-97
waittilstop 9-98
help 2-20
holding the last output value 11-16
HP E1432 driver A-9
HwChannel
G
gain 1-22
engineering units (AI) 5-56
gain list 4-5
get 3-15
getdata 5-13
event information 9-59
native data 10-53
time information 5-18
getsample 9-61
getvalue 7-12
graphical property editor 3-20
grounded signal 1-24
H
hardware
initializing 9-44
resources 2-17
scanning 1-17
setting up 1-4
simultaneous sample and hold 1-19
supported vendors 2-7
hardware ID
channel 4-4
device (board) 4-3
line 7-4
mapping to channels 3-9
port 7-4
hardware triggers
AI object 5-37
AO object 6-25
AI object 4-5
AO object 6-5
HwLine 7-5
I
ID
channel 4-4
HwChannel 4-6
device (board) 4-3
line 7-4
HwLine 7-8
mapping to channels 3-9
port 7-4
immediate trigger
AI object 5-23
AO object 6-22
Index
AI object 4-5
AO object 6-5
DIO object 7-5
indexing
channel array 4-6
line array 7-8
initializing the hardware 9-44
InitialTriggerTime 5-19
input overrange event 5-47
input range 1-22
engineering units 5-57
InputOverRangeAction 5-47
InputType 5-4
InstaCal A-6
hardware configuration 2-17
I-7
Index
internal clock 1-23
interrupts 1-27
NI hardware 11-25
invalid device object 3-7
ischannel 9-63
isdioline 9-64
isnan 5-35
isvalid 9-65
J
jitter 1-23
L
least significant bit (DIO) 7-8
Line 7-8
line group 7-4
line names 7-9
line object 7-4
line properties 3-12
line-configurable device 7-6
LineName 7-9
lines 3-8
adding 7-4
descriptive names 7-8
referencing 7-8
load 8-5
loading device objects
MAT-file 8-5
M-file 8-4
LogFileName 8-7
Logging 5-20
logging
data to memory 3-22
information to disk (AI) 8-6
file name specification 8-7
I-8
multiple files 8-7
retrieving data with daqread 8-8
LoggingMode 8-7
LogToDiskMode 8-7
M
makenames 9-71
managing data
acquired 5-9
output 6-17
manual trigger
AI object 5-23
AO object 6-22
mapping channels to hardware IDs 3-9
MAT-file
device objects, saving to 8-5
properties, saving to 8-3
maximum samples queued 10-51
MaxSamplesQueued 6-18
Measurement and Automation Explorer A-3
hardware configuration 2-17
memory resources B-2
mono mode 4-7
most significant bit (DIO) 7-8
multifunction boards 1-6
multiple device objects
array 3-5
starting 6-37
stopping 6-38
multiplexing 1-12
mux board
adding channels 9-17
channel indices 9-72
muxchanidx 9-72
Index
N
Name
AI object 4-3
AO object 6-4
DIO object 7-3
National Instruments hardware
AISENSE 11-10
channel configuration 5-5
data transfer mechanisms 11-25
driver A-3
properties 11-3
trigger types
AI object 5-38
AO object 6-25
troubleshooting A-3
native data
getdata 9-57
offset 10-53
putdata 9-80
scaling 10-55
NI-DAQ driver A-3
noise 1-33
Nyquist frequency 4-16
Nyquist theorem 1-35
O
obj2mfile 8-3
object constructor 3-4
onboard clock 1-23
one-shot acquisition 5-30
online help 2-20
output range 6-34
outputting data 3-22
continuous 6-22
holding the last value 11-16
single point 9-82
overloaded functions 9-2
overrange condition 1-22
P
PC clock 1-23
peekdata 5-9
polarity 1-22
engineering units (AI) 5-56
polling the data block 5-11
port characteristics 7-5
port-configurable device 7-5
postriggers 5-28
precision 1-31
pretriggers 5-27
previewing data 5-9
properties
BitsPerSample 11-7
BufferingConfig 10-15
BufferingMode 10-17
Channel 10-18
ChannelName 10-20
ChannelSkew 10-21
ChannelSkewMode 10-22
ClockSource 10-24
COLA 11-8
Coupling 11-9
DataMissedAction 10-26
DefaultChannelValue 10-27
Direction 10-28
DriveAISenseToGround 11-10
EventLog 10-29
GroundingMode 11-11
HwChannel 10-31
HwLine 10-33
Index 10-34
InitialTriggerTime 10-36
I-9
Index
InputMode 11-12
StandardSampleRates 11-23
InputOverRangeAction 10-38
StartAction 10-76
InputRange 10-39
StopAction 10-77
InputSource 11-14
Sum 11-24
InputType 10-41
Tag 10-79
Line 10-43
Timeout 10-80
LineName 10-44
TimerAction 10-81
Logging 10-46
TimerPeriod 10-82
LoggingMode 10-47
TransferMode 11-25
LogToDiskMode 10-48
TriggerAction 10-83
ManualTriggerHwOn 10-49
TriggerChannel 10-84
MaxSamplesQueued 10-51
TriggerCondition 10-85
Name 10-52
TriggerConditionValue 10-89
NativeOffset 10-53
TriggerDelay 10-90
NativeScaling 10-55
TriggerDelayUnits 10-91
NumMuxBoards 11-15
TriggerRepeat 10-92
OutOfDataMode 11-16
TriggersExecuted 10-93
OutputRange 10-56
TriggerType 10-94
Parent 10-58
Type 10-96
Port 10-59
Units 10-97
RampRate 11-17
UnitsRange 10-98
RepeatOutput 10-60
Running 10-61
SampleRate 10-64
SamplesAcquired 10-66
SamplesAcquiredAction 10-67
SamplesAcquiredActionCount 10-68
SamplesAvailable 10-69
SamplesOutput 10-70
SamplesOutputAction 10-71
SamplesOutputActionCount 10-72
SamplesPerTrigger 10-73
Sending 10-74
SensorRange 10-75
SourceMode 11-18
SourceOutput 11-19
Span 11-21
I-10
UserData 10-99
property characteristics 2-21
property types
base 3-13
channel 3-12
AI object 10-7
AO object 10-11
common 3-12
AI object 10-3
AO object 10-8
DIO object 10-12
device-specific 3-13
Agilent hardware 11-4
CBI hardware 11-4
NI hardware 11-3
sound cards 11-5
Index
line 3-12
DIO object 10-13
property values
configuring 3-18
default 3-19
graphical property editor 3-20
saving 8-3
specifying names 3-19
propinfo 2-21
putdata 6-17
putsample 9-82
putvalue 7-10
run-time error event
AI object 5-47
AO object 6-28
RuntimeErrorAction 10-62
AI object 5-47
AO object 6-28
S
SampleRate 5-6
samples acquired event 5-47
samples output event 6-28
SamplesAcquired 5-15
SamplesAcquiredAction 5-47
Q
SamplesAcquiredActionCount 5-47
quantization 1-20
queuing data for output 6-17
maximum number of samples 10-51
Quick Reference Guide 2-13
SamplesAvailable 5-15
SamplesOutput 6-14
SamplesOutputAction 6-28
SamplesOutputActionCount 6-28
SamplesPerTrigger 4-12
R
reading digital values 7-12
Readme 2-12
read-only properties 2-21
registering your adaptor A-19
relative time 5-18
repeating triggers 5-30
RepeatOutput 6-18
resetting the hardware 9-44
retrieving data from a log file 8-8
returning property values
dot notation 3-17
get 3-15
set 3-14
Running 3-23
running device objects 3-22
postrigger data 5-28
pretrigger data 5-27
sampling 1-16
sampling rate
AI subsystem 5-6
AO subsystem 6-6
saturation 6-35
save 8-5
saving
device objects
MAT-file 8-5
M-file 8-3
information to disk (AI) 8-6
property values to a MAT-file 8-3
scaling the data
AI object 5-56
AO object 6-34
I-11
Index
scanning hardware 1-17
channel order
channels
scan order 4-5
Sending 6-21
sending data 3-22
sensors 1-8
range 10-75
session 3-2
loading 8-3
saving 8-3
set
configuring property values 3-18
returning property values 3-14
saving property values to an M-file 8-3
settling time 1-31
setverify 4-10
showdaqevents 5-36
AI object 5-51
AO object 6-31
signal conditioning 1-11
simultaneous input and output 6-37
simultaneous sample and hold hardware 1-19
single-ended inputs 1-25
single-point
acquisition 9-61
output 9-82
skew 5-7
software clock 1-23
CBI hardware 10-24
software trigger 5-23
sound cards
channel configuration 5-5
device-specific properties 11-5
mono mode 4-7
standard sample rates 11-23
stereo mode 4-8
I-12
troubleshooting A-12
start 3-23
start event
AI object 5-48
AO object 6-28
StartAction
AI object 5-48
AO object 6-28
starting multiple device objects 6-37
state
logging 3-22
running 3-22
sending 3-22
status evaluation
AI object 4-22
AO object 6-14
DIO object 7-18
stereo mode 4-8
stop 3-24
stop event
AI object 5-48
AO object 6-28
StopAction
AI object 5-48
AO object 6-28
synchronizing triggers 10-49
T
third-party adaptors A-19
time
absolute 5-19
initial trigger 5-19
relative 5-18
Timeout 5-31
timer event
AI object 5-48
Index
synchronizing for AI and AO 10-49
times
AI object 5-37
AO object 6-24
initial trigger 5-19
trigger conditions (AI) 5-21
trigger types
AI object 5-21
AO object 6-22
AO object 6-28
DIO object 7-15
TimerAction
AI object 5-48
AO object 6-28
DIO object 7-15
TimerPeriod
AI object 5-48
AO object 6-28
DIO object 7-15
toolbox components
data acquisition engine 2-4
hardware driver adaptor 2-7
M-files 2-3
transducer 1-4
trigger
TriggersExecuted
AI object 5-36
AO object 6-24
TriggerType
AI object 5-21
AO object 6-22
Type
AI object 5-23
AO object 6-22
trigger event
AI object 5-48
AO object 6-29
TriggerAction
AI object 5-48
AO object 6-29
TriggerCondition 5-21
AI object 4-3, 4-5
AO object 6-4, 6-5
DIO object 7-3, 7-5
U
undersampling 1-35
Universal Library driver A-6
UserData
saving values to a MAT-file 8-3
TriggerConditionValue 5-21
TriggerDelay 5-26
TriggerDelayUnits 5-26
triggered acquisition 5-20
triggered output 6-21
TriggerRepeat 5-30
triggers
delays 5-26
postriggers 5-28
pretriggers 5-27
repeating 5-30
samples acquired for each trigger 4-12
V
verifying property values 4-10
voice activation example 5-23
W
waittilstop 9-98
writing digital values 7-10
I-13
Index
I-14
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement