Data Acquisition Toolbox 2.8
Acquire and send out data from plug-in data acquisition boards
The Data Acquisition Toolbox provides a complete set of tools for analog input, analog output, and digital I/O from a variety of PC-compatible data acquisition hardware. The toolbox lets you configure your external hardware devices, read data into MATLAB for immediate analysis, and send out data. You can customize your acquisitions, access the built-in features of hardware devices, and incorporate the analysis and visualization features of MATLAB and related toolboxes into your design. Together, MATLAB and the Data Acquisition Toolbox offer a single, integrated environment to support the entire data acquisition and analysis process. You can analyze or visualize your data, save it for post-processing, and make iterative updates to your test setup based on your analysis results.

KEY FEATURES

Controls and communicates with a variety of industry-standard data acquisition devices Acquires live, measured data directly into MATLAB for immediate analysis Provides a single integrated environment for data acquisition, analysis, and visualization Performs one shot or continuous data acquisition Configures and accesses analog input, analog output, and digital I/O Streams data into a graphical display using the SoftScope software oscilloscope Directly interfaces to device-specific features, such as singlechannel and multichannel acquisitions and single-point and buffered analog I/O Controls acquisitions with hardware and software triggers Provides a consistent software interface for easy substitution of hardware boards and vendors
Using the Data Acquisition Toolbox to acquire an input signal from a data acquisition board directly into MATLAB. The acquired data is displayed simultaneously as a time-domain signal, an instantaneous FFT, and a waterfall plot, making use of MATLAB signal processing and visualization capabilities.
INDEPENDENT ACQUISITION AND ANALYSIS
While the Data Acquisition Toolbox is collecting data, MATLAB can analyze and visualize data.
The Data Acquisition Toolbox supports three device objects: analog input, analog output, and digital I/O. The toolbox automatically performs A/D and D/A data conversions for receiving or sending data.

MATLAB

Data Acquisition Toolbox

Hardware

Supported Hardware Devices and Vendors
The Data Acquisition Toolbox supports PC-compatible data acquisition hardware from multiple vendors, including Advantech, Measurement Computing, and National Instruments, as well as Microsoft Windows compatible sound cards and the PC parallel port. The Data Acquisition Toolbox is also compatible with hardware from several data acquisition vendors via third-party adaptors. For up-to-date information on supported third-party boards, visit www.mathworks.com/ products/daq.
Communicating with Unsupported Devices
The Data Acquisition Toolbox provides an adaptor kit that enables you to build custom interfaces to hardware not supported by the toolbox. For more information, refer to the Data Acquisition Toolbox documentation.

Using Device Objects

Device objects provide a gateway to the hardwares functionality and enable you to control the behavior of your acquisition. For example, you can execute any supported analog input task via an analog input object created in MATLAB.
Working with the Data Acquisition Toolbox
You can execute Data Acquisition Toolbox functions from the command line or through MATLAB programs. Based on MATLAB object technology, the toolbox provides functions for creating device objects that are directly associated with your hardware. These objects include base properties that apply to all supported hardware, such as sample rate, trigger settings, and channel properties. They also include device-specific properties that let you access the specific features and capabilities of your hardware.

Analog Input

The analog input functions let you acquire signals from your hardware. You can create an analog input object, add channels to the object, acquire data to memory, read data into the workspace, and preview the most recently acquired data.

Analog Output

Analog output functions let you send signals out to your hardware. You can create an analog output object, add channels, queue data sets to be output, and generate analog signals.
Two channels of live audio data displayed and analyzed using the SoftScope software oscilloscope interface. SoftScopes measurement capabilities find the peak voltage of data streaming in through channel 1.

Digital I/O

Digital I/O functions enable you to generate or read digital signals using your hardware. You can create digital I/O objects, add lines, send data to the hardware, and read data into the workspace.

Data Source

Sensor

Microphone

Figure

Channels and Lines

Data Acquisition Toolbox channels and lines are mapped to your hardwares channels and lines. The toolbox supports an unlimited number of channels/lines, enabling you to use as many as your hardware permits.

Sound Card

MATLAB Workspace
Controlling Your Acquisition
The Data Acquisition Toolbox supports a wide range of functions for controlling your acquisition. For example, you can set event information, evaluate the acquisition status, define triggers and callbacks, preview data while the device is running, and perform analysis on-the-fly. The toolbox also supports several hardware-specific properties that can be displayed and customized to your specifications.
Setup for a data acquisition and analysis session. The Data Acquisition Toolbox enables MATLAB to interface with the data acquisition boards, such as sound cards.

Using SoftScope

SoftScope is a graphical user interface for selecting and configuring data acquisition sources and then acquiring, viewing, and analyzing data using a familiar, oscilloscope-like interface. SoftScope lets you quickly verify hardware operation and perform live data analysis using a library of built-in measure-ment functions. You can extend SoftScope with your own analysis functions and export data from SoftScope to the MATLAB workspace.

Handling Errors

The Data Acquisition Toolbox provides a consistent set of error and warning messages. If a hardware error message is not handled by the toolbox, an external error is reported with the vendor-specific hardware error message.

Managing Data

Functions are provided for previewing and extracting your data for analysis. The toolbox streams data into MATLAB in double-precision floating-point format, enabling you to work with the data just as you would with any other matrix in MATLAB. You can also stream in data using a native hardware format.
Converting Engineering Units
The Data Acquisition Toolbox automatically converts acquired data into values that represent specific engineering units (for example, volts or Newtons). The toolbox directly supports linear scaling and offsets. In addition, you can use MATLAB to apply nonlinear calibration curves. You can set engineering unit conversions for each data channel.
Incorporating Events and Callbacks
Most data acquisition tasks are initiated by events. An event occurs at a specific time after a condition is met. Event types supported by the Data Acquisition Toolbox include: Start and stop Number of samples acquired Errors Triggers Number of samples output Events may result in one or more callbacks. All the preceding event types execute an M-file function that you specify.

Logging Data

Functions are available for logging data to disk, memory, or both while the analog input object is running. You can log data, events, and errors. In addition, functions are provided for extracting data from toolbox-generated log files.
Evaluating Your Acquisition
You can evaluate the status of your acqui-sition and the available data acquisition resources, including installed hardware, hard-ware drivers, and adaptors, by displaying: Device object and channel status Hardware information Data acquisition engine information
% Create an analog input object to communicate with the % data acquisition device. ai = analoginput(winsound); addchannel(ai, 1); % Configure the object to acquire 2 seconds of data at 8000 Hz. Fs = 8000; duration = 2; set(ai, SampleRate, Fs); set(ai, SamplesPerTrigger, duration*Fs); % Start the acquisition and retrieve the data. start(ai); data = getdata(ai); % Determine the frequency components of the data. xfft = abs(fft(data)); mag = 20*log10(xfft); mag = mag(1:end/2); plot(mag); % Clean-up delete(ai); clear ai;
A script illustrating the four steps of a typical MATLAB data acquisition session: creation, configuration, acquisition, and clean-up. A few lines of code let you acquire 2 seconds of data from a data acquisition board, calculate the frequency components of the data, and plot the results in MATLAB.

Required Products

Platform and System Requirements
For platform and system requirements, visit www.mathworks.com/products/daq

Related Products

Signal Processing Toolbox. Perform signal processing, analysis, and algorithm development. Curve Fitting Toolbox. Perform model fitting and analysis Instrument Control Toolbox. Control and communicate with test and measurement instruments Image Acquisition Toolbox. Acquire images and video from industry-standard hardware MATLAB Report Generator. Automatically generate documentation for MATLAB applications and data MATLAB Compiler. Convert MATLAB applications into stand-alone applications and software components
For demos, application examples, tutorials, user stories, and pricing: Visit www.mathworks.com Contact The MathWorks directly US & Canada 508-647-7000 Benelux France Germany Italy Korea Spain Sweden Switzerland UK +31 (0)+33 (0)14 +49 (0)750 +39 (011) +82 (0)5114 ++46 (8)00 +41 (0)+44 (0)200
Visit www.mathworks.com to obtain contact information for authorized MathWorks representatives in countries throughout Asia Pacific, Latin America, the Middle East, Africa, and the rest of Europe.
Tel: 508.647.7000 info@mathworks.com www.mathworks.com

9701v/05

2005 by The MathWorks, Inc. MATLAB, Simulink, Stateflow, Handle Graphics, Real-Time Workshop, and xPC TargetBox are registered trademarks of The MathWorks, Inc. Other product or brand names are trademarks or registered trademarks of their respective holders.

B-31 B-32 B-34 B-36 B-37 B-38 B-38 B-39 B-39 B-40
IChannelList. GetChannelContainer. GetChannelStruct. GetNumberOfChannels. CreateChannel (proposed). DeleteChannel. DeleteAllChannels.
B-41 B-41 B-42 B-43 B-44 B-44 B-45

Engine Structures

The BUFFER_ST Structure. C-3 The NESTABLEPROP Structure. C-5
Sample Property and daqhwinfo Tables
Table of daqhwinfo Properties. Adaptor daqhwinfo Table. Analog Input daqhwinfo Table. Analog Output daqhwinfo Table. Digital I/O daqhwinfo Table.

D-3 D-3 D-3 D-5 D-6

Property Info Tables. D-7 Analog Input Subsystem Properties. D-7 Analog Output Subsystem Properties. D-9 Digital I/O Subsystem Properties. D-10

viii Contents

Overview. Who Should Read This Document? What Knowledge Is Required?. What Effort Is Required?. Tools. 1-2 1-2 1-2 1-2 1-3
Writing an Adaptor Versus Writing a MEX File What Is the Adaptor Kit?
Toolbox Architecture. 1-9 Using This Manual. 1-11

Overview

Who Should Read This Document?
You should read this document if you want to Develop an adaptor to support hardware that is not currently supported by the Data Acquisition Toolbox Add new features to an existing adaptor The Data Acquisition Toolbox Adaptor Kit addresses the needs of individuals who want to interface the toolbox to a single board, and manufacturers wanting to interface the toolbox to a range of hardware. Although this document is aimed primarily at supporting a single board, hardware manufacturers should use this document as the basis for developing a multiple-board adaptor, generalizing the single-board support issues appropriately.
What Knowledge Is Required?
To build an adaptor, you should have a working knowledge of C++, Microsofts Component Object Model (COM), and the Active Template Library (ATL) The functionality of your hardware device, and its associated Application Programming Interface (API) Data Acquisition Toolbox concepts, functionality, and terminology as described in the Data Acquisition Toolbox Users Guide

What Effort Is Required?

The effort required to produce an adaptor depends on the capabilities of the hardware device and your acquisition requirements. The simplest type of adaptor supports only single-sample acquisition or burst acquisition, and uses software clocking. You can create this type of adaptor by modifying the demo adaptor.
Note Some hardware does not support single-sample acquisition and, as a result, it does not support software clocking. In this case, you cannot build this simple type of adaptor.
The next level of complexity is an adaptor that implements hardware clocking and buffering, but works only for a limited number of similar hardware devices. In this case, you can decrease development time by hard-coding some configuration information or by limiting the hardware features that you use. For example, you might decide to ignore some triggering functionality. The greatest level of complexity is an adaptor that provides complete support to a line of data acquisition devices. To develop an adaptor of this type typically requires a minimum of four months.

The analoginput M-file calls the data acquisition engine to construct the analoginput object. When the constructor is first called, the engine must determine what COM object to create. It does this by enumerating all class IDs of objects that implement CATID {6FE55F7B-AF1A-11D3-A53600902757EA8D} (MATLAB Data Acquisition Adaptor), and then asks for the short name of that GUID. In this case, the engine matches the short name to the winsound adaptor. The engine then constructs an mwAdaptor object and calls the objects OpenDevice method for creating the analog input object. The adaptors OpenDevice method is responsible for creating a new device and initializing it. Typically, this is done by creating a new COM object that implements the appropriate interfaces. After creating the new object, the engine interface can then be used to identify the characteristics of the current driver or device to the MATLAB user. You can also create device-specific properties at this time. The adaptor can also register an interest in some properties by setting the User value of the property. This value serves two purposes: Any value other than 0 causes the engine to call the SetProperty
method when the property is changed, and the value can be used in the SetProperty method to identify the property being modified. The Open method creates any device-specific properties and defines any device-specific values for existing properties. For example, the winsound adaptor has two device-specific properties: BitsPerSample and StandardSampleRates. Both these properties are created with the CreateProperty method of the IPropContainer interface. When the property is created, a pointer to the IProp interface for the property just created is returned that allows you to call IProp methods. The IProp methods allow you to configure your property. For example, the IProp interface contains methods that allow you to display the possible settings of the property, the default value of the property, and the current value of the property.
Configuring the Sampling Rate
The following command configures the sound card to a sampling rate of 11.025 kHz.
set(ai,'SampleRate',11025)
The set M-file calls the data acquisition engine. In the Open method the adaptor requested a notify on change for the SampleRate property, and so the engine notifies the adaptor when you set the property to a new value. The data acquisition engine calls the adaptors SetProperty method with two input arguments. The first input argument is a pointer to the IProp interface for the property being set. The second input argument is the value that the property is being set to. Therefore, in this example, the first input argument is a pointer to the SampleRate IProp interface, and the second input argument contains a pointer to 11025. From within the adaptors SetProperty method, you can determine which property is being set by examining the user value passed into the function. This value can be compared to the values for each property that you have registered with the engine.

Creating a Digital I/O Object
The following command creates the DIO object dio associated with a National Instruments board.
dio = digitalio('nidaq',1);
A digital I/O (DIO) device need not implement all the interfaces that are required for an analog input or analog output device. When the device is opened, it must fill in the portdirections, portids, portlineconfig, and portlinemask properties with the correct values. Given these values, the engine maintains the line information and generates the correct calls to SetPortDirection, ReadValues, and WriteValues. The standard property and child (line) property methods are supported. However, the adaptors implemented so far have not needed to use them. The object should initialize its properties to the correct values before returning. For a DIO object, the daqhwinfo property structure must initialize values for portdirections, portids, portlineconfig, and portlinemasks.
Adding Lines to the Digital I/O Object
The following command adds four input lines from the default port (port 0) to the DIO object dio.
lin = addline(dio,0:3,'in');
The addline command works the same as the addchannel command for AI and AO objects in that the adaptors ChildChange method is called. However, most
adaptors need not implement ChildChange, because typically no adaptor actions are necessary when adding or removing lines. The following command adds four output lines to the DIO object dio.
lout = addline(dio,4:7,'out');
After the lines are added, a call to SetPortDirection(0,0xf0) is made to set the port direction to output. The following command demonstrates that you can also add lines in reverse order.
p = addline(dio,7:-1:0,1,'in');

Reading Line Values

The following command reads the values from lines 0 to 3 of port 0 and stores the values in the MATLAB variable data.

data = getvalue(lin);

The engine issues the command ReadValues(1,PortList,Data) to the device, which must then return the values from the specified ports. The adaptor does not keep track of exactly what lines have been added, and returns all line values in Data.

Adaptor Kit provides functionality that makes registering and checking a user value intuitive. For more information on attaching to properties, see Attaching to a Property in Chapter 4. For all analog input properties that are attached to by an adaptor, the engine calls the SetProperty method of the analog input interface, passing it the user value and the new value that the user has specified. For all analog input channel properties that are registered by an adaptor, the engine calls the SetChannelProperty method of the analog input interface, passing similar information. For instance, modifying the InputRange of a channel calls the SetChannelProperty. The SetProperty method can check the user value (using the USER_VAL macro defined by the Adaptor Kit) to determine which property has been modified. You should perform one of the following functions in the SetProperty or SetChannelProperty methods: Error, if the new value is invalid. The following example, from the Keithley adaptor, checks whether the hardware supports the requested TransferMode property, and errors out appropriately:
if (User == USER_VAL(pTransferMode)) { if((long)(*val) == TRANSFER_DMA) { SelectDriverLINX(m_driverHandle); if(!(DoesDeviceSupportDMA(m_pSR))) { return Error(_T("Keithley: This device does not support DMA Transfers.")); } m_usingDMA = true; } else { m_usingDMA = false; } }
Change the new value if the property needs to be quantized or set to values that the hardware can implement. The following example from the
Measurement Computing adaptor calls UpdateRateandSkew to quantize the sample rate and change the channel skew when the user changes the sample rate:
else if (User==USER_VAL(pSampleRate)) { RETURN_HRESULT(UpdateRateAndSkew(pChannelSkewMode,*val)); _RequestedRate=*val; *val=pSampleRate; }
Change the values, defaults, and/or ranges of other properties based on the new value. The following example from the Measurement Computing adaptor modifies the TriggerCondition property based on changes to the TriggerType property:
else if (User==USER_VAL(pTriggerType)) { if (static_cast<long>(*val)==HW_DIGITAL_TRIG) { pTriggerCondition->ClearEnumValues(); pTriggerCondition->AddMappedEnumValue(GATE_HIGH, L"GateHigh"); pTriggerCondition->AddMappedEnumValue(GATE_LOW, L"GateLow"); pTriggerCondition->AddMappedEnumValue(TRIG_HIGH, L"TrigHigh"); pTriggerCondition->AddMappedEnumValue(TRIG_LOW, L"TrigLow"); pTriggerCondition=TRIG_NEG_EDGE; pTriggerCondition.SetDefaultValue(TRIG_NEG_EDGE); } else if (static_cast<long>(*val)==HW_ANALOG_TRIG) { pTriggerCondition->ClearEnumValues(); pTriggerCondition->AddMappedEnumValue(GATE_NEG_HYS, L"GateNegHys"); pTriggerCondition->AddMappedEnumValue(GATE_POS_HYS, L"GatePosHys"); pTriggerCondition->AddMappedEnumValue(GATE_ABOVE, L"GateAbove"); pTriggerCondition->AddMappedEnumValue(GATE_BELOW,

to handle channel addition and removal.
7 Implement the PutSingleValue method if software clocking is to be used. 8 Implement the PutSingleValues method if the device driver supports easy
Typically, this step involves writing buffering routines and message
handlers, and can often use the multithreading built during implementation of the analog input subsystem. As the steps outlined above are no different from those implementing the analog input subsystem, only the differences in implementation are discussed directly in this stage.
Step 4.1 Select Property Values, Ranges, and Defaults for Analog Output
In order to control the behavior of a task (such as duration and volume of acquisition, type of triggering, clocking, and event callbacks) the MATLAB user modifies the properties of the Data Acquisition Toolbox analogoutput object representing the data acquisition hardware he/she is using. The adaptor must use the property values during acquisition tasks to control driver settings, return messages, and start and stop acquisition. The adaptor must also provide the data acquisition engine with appropriate properties, ranges, and default values for the specific hardware referenced by the adaptor. Successfully creating an adaptor therefore requires careful thought about the existing common analog output subsystem properties, and the addition of adaptor-specific properties where appropriate. For the analog output subsystem, you should construct the same propinfo table you compiled for the analog input subsystem. Properties that should be considered in the table are given in Appendix D, Sample Property and daqhwinfo Tables. The propinfo table should reflect the state of the desired output from a call to the propinfo method of the analoginput object. Thus, when you run
propinfo(analogoutput(<adaptor>))
the result should be the data presented in the propinfo table. The output of the MATLAB code given above provides a test to confirm that these properties have been created and initialized successfully.
The outcome of Step 4.1 is a document that forms the blueprint for the implementation of properties in later steps of this stage.
Step 4.2 Add the Demo Analog Output Code to Your Project
This step is exactly the same as for the analog input subsystem, except that you import the analog output code (demoaout.cpp and demoaout.h) and change the input to output as appropriate.
Step 4.3 Modify the OpenDevice Method of the Adaptor Class

The ATTACH_PROP macro works together with the property templates from the Adaptor Kit. To use the ATTACH_PROP macro, you need to define a local (typically private) variable using the property templates from the Adaptor Kit. The variable name must begin with a p, and should then have a descriptive name after the p. For example, the local variable for the ClockSource property would be named pClockSource. Table 4-1 lists, with examples of their use, the property templates defined in the Adaptor Kit. Of these templates, the most commonly used are the CLocalProp (for obtaining properties that are seldom used) and TRemoteProp class (for obtaining properties that change default values and/or ranges, or attaching to properties).
Table 4-1: Adaptor Kit Defined Property Classes and Templates Type CLocalProp Description and Typical Usage Example
Virtual base class. All other property classes derive from this class. Use this class when obtaining an IPropRoot interface for seldom-accessed properties Class with added SetRange and SetDefaultValue methods. Used by template classes. Base template for properties that should hide the IPropRoot interface. Enumerated property class. Use this class to check an enumerated property value. Use CachedEnumProp for modifying enum values. Template class for defining remote properties. Use this class if you need to change default values and set new ranges for a property. Template for cached properties. Use instead of TRemoteProp if a property value should be tested locally prior to updating in engine. Then use SetLocal to set local values and SetRemote to set remote values (= operator sets both local and remote values). Template for array properties. Although adaptors cannot create array properties, the engine defines some array properties that might be required in the adaptor. See derived types in Table 4-2.
All SetProperty methods None. Use Template classes. See Table 4-2.
pOutOfDataMode in Keithley analog output

CRemoteProp

CEnumProp

TRemoteProp

pSamplesPerTrigger in Keithley analog input

Passing Arrays to MATLAB Using Safe Arrays
Some adaptor properties need to return an array of data to MATLAB. One example is the ObjectConstructorNames property, defined by the adaptors AdaptorInfo method, which must return an Mx3 cell array of object constructor strings. Another example is the InputRange property, also returned in SetDaqHwInfo as an Mx2 matrix of valid input ranges. This data must be passed to MATLAB as a CComVariant containing a SafeArray. This section explains how to pass array information to MATLAB. This section provides only some sample code on how Safe Arrays may be used in the adaptor, as an example for you to follow. For a complete discussion on SafeArrays, consult your Visual C++ documentation. The following sample code provides a template for creating and using SafeArrays with your adaptor. In this particular code sample, the ObjectConstructorNames property is being created for a parallel port adaptor.
Note Some code has been removed from the final adaptor implementation for conciseness. In practice, the ObjectConstructorName is typically populated at the same time as the BoardNames and BoardIDs properties, which are all SafeArrays. See the Keithley or Measurement Computing adaptors for examples.
// Create constructor string Array (NumOfPorts x 3 DAQ Subsystems) // Build up subsystems arrays -- up to 3 subsystems per board VARIANT varSubSystem; CComBSTR *subsystems; SAFEARRAY *pSubSys; SAFEARRAYBOUND arrayBounds[2]; // Define array bounds arrayBounds[0].lLbound = 0; //Rows arrayBounds[0].cElements = numports; arrayBounds[1].lLbound = 0; // Columns arrayBounds[1].cElements = 3; // Construct a SafeArray pSubSys = SafeArrayCreate(VT_BSTR, 2, arrayBounds); if (pSubSys!=NULL) {
// Associate SafeArray with Variant varSubSystem.parray = pSubSys; varSubSystem.vt = VT_ARRAY | VT_BSTR; hRes = SafeArrayAccessData(pSubSys, (void **)&subsystems); if (SUCCEEDED(hRes)) { // Define Constructor strings and IDs wchar_t str[40]; // Loop through each found port for (int i=0; i<numports; i++) { //This adaptor only supports digitalIO so set //the first (AI, AO) to null: subsystems[i].Append(""); subsystems[i+numports]=(BSTR)NULL; // And set the Digital I/O string swprintf(str, L"digitalio('%s','LPT%c')", (wchar_t*)ConstructorName, BoardIDs[i]); subsystems[i+2*numports]=str; }//end for // Send Constructor names to DAQENGINE hRes = Container->put_MemberValue( L"objectconstructorname", varSubSystem); } // Destroy SubSystem SafeArray SafeArrayUnaccessData (pSubSys); SafeArrayDestroy (pSubSys); } return hRes;

Understanding Engine Buffers
For analog input and analog output tasks, the Data Acquisition Toolbox engine makes use of buffers of data to manage the data transfer, event notification, and memory management tasks. Engine buffers are responsible for storing data from an analog input task, prior to a users requesting that data with a getdata function call, and for queuing data for an analog output task with putdata. Thus, data interaction between the adaptor and the engine takes place through engine buffers. Engine buffers for any task are a predetermined size, presented to the user through the BufferingConfig property. Although the engine attempts to size buffers appropriately for the desired sample rate, the user can set the size of engine buffers by modifying the BufferingConfig property directly. Although it is possible to restrict the size of the engine buffers (see, for instance, the hpe1432 adaptor, which limits the maximum size of engine buffers) the adaptor should not expect strict control over engine buffer sizes, as this would limit functionality for the user. Buffer interaction between the engine and the adaptor takes place through
BUFFER_ST structures, defined as follows (a full description of this structure is
given in Appendix C, Engine Structures):
typedef struct tagBUFFER { long Size; // In bytes long ValidPoints; // In raw points //(MATLAB samples is ValidPoints/channels) unsigned char *ptr; DWORD dwAdaptorData; // Reserved by the engine for use by adaptor unsigned long Flags; // Flag values are defined in unsigned long Reserved; // Reserved for future use by the engine hyper StartPoint; // Count of points since start double StartTime; // Time of the start of the buffer from GetTime double EndTime; // Time of the end of the buffer from GetTime } BUFFER_ST;
The buffer size is set by the BufferingConfig property. However, because acquisition tasks might not necessarily stop at a buffer boundary, the ValidPoints field contains the number of valid points (samples multiplied by the number of channels) contained (for analog output) or expected (for analog input) in the buffer of data passed by the engine. The data is stored as
interleaved samples in the memory space pointed to by ptr; the first channel of sample N is followed by the second channel of sample N, until all channels are filled, and channel 1 of sample N+1 follows. The Flags field contains, among others, a flag to indicate whether the buffer is the last buffer in the current task (Flags & BUFFER_IS_LAST).

eval(['hAI = ', info.ObjectConstructorName{1}]) AdaptorInfo uses the pointer to the IPropContainer interface (passed by the engine as a single parameter) to call the put_MemberValue method to modify
the structure. For example:
hRes = Container->put_MemberValue( L"adaptordllname", CComVariant(name) );
The approach you should use to implement the AdaptorInfo function depends on the complexity of the adaptor DLL you are building. The implementation given in the demo adaptor example (as well as any adaptor based upon it) automatically correctly loads the first two fields of the DAQHWINFO structure: AdaptorName and AdaptorDllName. The third field, AdaptorDllVersion, is loaded by the engine based on the following line in the resource file demo.rc:
VALUE "FileVersion", "<******>\0".
This line is located in the block StringFileInfo. You should replace "<******>" with a string that reflects the version number. The information for the other three fields is not as readily available. There are two possibilities for their realization, depending on your goal: For a simple adaptor that is associated with only one type of hardware device, this information can be hard coded. This approach is employed in the demo adaptor. If the adaptor DLL is intended to communicate with a variety of devices sharing the same hardware driver, you must use the API calls provided by the driver. Once this information is obtained, it is communicated to the engine with a call to put_MemberValue. For an example of this implementation, refer to the AdaptorInfo function in the winsound adaptor. The sole purpose of the AdaptorInfo function is to present information to the user. It is not used by the engine internally and is called only as a response to your requests. This is the way you obtain information about the installed hardware as well as the adaptors. Prior to using this method, you must register the adaptors of interest, and the hardware drivers for the data acquisition boards must be installed.
HRESULT OpenDevice( [in] REFID DevIID, [in] long nParams, [in] VARIANT *Param, [in] REFID EngineIID, [in] IUnknown *pEngine, [out] void **ppIDevice )
The OpenDevice method constructs an instance of an adaptor and initializes the hardware device. Additionally, it makes the engine and the adaptor exchange pointers, which enables subsequent calls to each others methods.
OpenDevice is called by the engine when you request the construction of a data
acquisition object. For example, it is called when you issue the
analoginput('demo',1) command. OpenDevice then calls the Open function,

BOOL IsHidden; prop->get_IsHidden(&IsHidden);

put_IsHidden

HRESULT put_IsHidden(BOOL IsHidden)

IsHidden BOOL

The put_IsHidden method allows you to hide a property from users. A hidden property is not displayed with the get and set displays. A hidden propertys value can be obtained or modified only if you pass the name of the property to the get or set toolbox function. A value of false indicates that the property is not hidden and a value of true indicates that the property is hidden. For example, to create a hidden property called MyHiddenProperty:
pRoot->CreateProperty(L"MyHiddenProperty", NULL, &prop); prop->put_IsHidden(true);
IPropContainer interface: CreateProperty

get_IsReadonlyRunning

HRESULT get_IsReadonlyRunning( BOOL *pVal)

pVal BOOL*

The get_IsReadonlyRunning method determines whether a propertys value can be modified while the object is running. For example, the SampleRate property cannot be modified while the object is running. However, the Tag property can be modified whether the object is running or not. A value of false indicates that the property can be modified while the object is running, while a value of true indicates that the property cannot be modified while the object is running. For example, the following code fragment determines whether the SampleRate property can be modified while the object is running.
bool pVal; engine->GetProperty(L"SampleRate", &prop); prop->get_IsReadonlyRunning(&pVal);

put_IsReadonlyRunning

HRESULT put_IsReadonlyRunning( BOOL pVal)

pVal BOOL

The put_IsReadonlyRunning method allows you to configure a property so that it cannot be set while the object is running. A value of false indicates that the property can be modified while the object is running, while a value of true indicates that the property cannot be modified while the object is running. For example, the StandardSampleRates property cannot be modified while the object is running.
pRoot->CreateProperty(L"StandardSampleRates", NULL, &prop); prop->put_IsReadonlyRunning(true);
If you try to set the property while the object is running, you receive the following error:
set(ai, 'StandardSampleRates', 'off') ??? Error using ==> daqdevice/set The property: 'StandardSampleRates' is read-only while running.

IPropRoot interface: put_User

put_User

HRESULT put_User(long newVal)

newVal long

The put_User method sets the User for a property. When certain properties are modified by you, the adaptor needs to configure the hardware appropriately. The adaptor is notified of property value changes for any property that the adaptor has registered with the data acquisition engine. The adaptor registers a property by passing to the engine the address of a local data member for the property. The address of a local data member is called a User. For example, the following code registers the SampleRate property:
engine->GetProperty(L"SampleRate", &prop); prop->put_User((long)&_sampleRate);
where _sampleRate is a variable that contains the current value of the SampleRate property. To set the SampleRate property to a new value
set(obj, 'SampleRate', 11025);
When a property that has been registered by the adaptor is set by you, the data acquisition engine calls the adaptors SetProperty or SetChannelProperty method. The User value of the property is then passed to the method.
IDaqEngine interface: GetProperty IPropRoot interface: put_User

get_Name

HRESULT get_Name (BSTR *pVal)

pVal BSTR*

The get_Name method allows you to determine the name of the property. This can be useful when you are creating an error or warning message.

put_Name

HRESULT put_Name (BSTR pVal)

pVal BSTR

The put_Name method sets the name of a property.

IsValidValue

HRESULT IsValidValue([in] VARIANTREF value)

Value to check.

The IsValidValue function returns an error if the value is not valid, and returns S_OK if the value is valid.

IDaqEngine

The IDaqEngine interface methods provide a variety of different engine services. For example, there are methods for creating channel properties, posting events, and buffer management. IDaqEngine methods are generally called from within The adaptors Open method for creating an adaptor-specific property The adaptors Open, SetProperty, or SetChannelProperty methods for obtaining a pointer to an IPropContainer or IPropValue interface for the property being modified The adaptors ChildChange method for obtaining an IPropContainer interface for an existing channel Any adaptor method for posting warnings The adaptor routines for obtaining buffers of data to output or to fill with acquired data To execute an IDaqEngine interface method, you must have a pointer to the IDaqEngine interface. The first step in a MATLAB data acquisition session is to create the analog input, analog output, or digital I/O object with the

The following code fragment creates a property called MyProperty2 that has a default value of On and can be set to either On or Off. MyProperty2 cannot be modified while the object is running.
CreateProperty(L"MyProperty2", &CComVariant(true), &NewProp); NewProp->put_IsReadonlyRunning(true);
Note that by passing an initial value of true, a Boolean property is created. A Boolean property can be set to either On or Off, where a value of true maps to a property value of On and an integer value of 1, and a value of false maps to a property value of Off and an integer value of 0. The following example creates a property called MyProperty3 that can be set to Celsius, Fahrenheit, or Kelvin. The property has a default value of Fahrenheit and a current value of Celsius.
CreateProperty(L"MyProperty3", NULL, &NewProp); NewProp->AddMappedEnumValue(0,CComBSTR(L"Celsius")); NewProp->AddMappedEnumValue(1,CComBSTR(L"Fahrenheit")); NewProp->AddMappedEnumValue(2,CComBSTR(L"Kelvin")); NewProp->put_DefaultValue(CComVariant(1)); NewProp->put_Value(CComVariant(0));
Note that by passing an initial value of NULL, you create an enumerated property. The interface method AddMappedEnumValue is used to add enumerated values to the property.
IDaqMappedEnum interface: AddMappedEnumValue, put_IsReadonlyRunning, put_DefaultValue, put_Value, setRange

GetMemberInterface

HRESULT GetMemberInterface(LPCOLESTR MemberName, REFIID RequestedInterface, void **Interface)
MemberName Requested Interface
The property name. The interface that is used.

Interface

The requested interface if found, or NULL otherwise.
The GetMemberInterface method returns an interface pointer to an existing property. Note that the CmwDevice methods GetProperty and GetChannelProperty supply a simplified interface to this function. The code for GetProperty is given here as an example of the use of this function.
template <class T> HRESULT GetProperty(LPCWSTR name, T** prop) { RETURN_HRESULT(_EnginePropRoot->GetMemberInterface( name,__uuidof(T),(void**)prop)); return S_OK; }

put_MemberValue

HRESULT put_MemberValue(LPCOLESTR MemberName, VARIANTREF newVal)

MemberName newVal

The property name. A reference to the new value.
The put_MemberValue method sets the value of a property. put_MemberValue is typically used when setting the value of a property contained by the daqhwinfo property structure. The first input argument contains the name of the property that is being modified. The second input argument contains the new value for the property being modified. This function is a shortcut for retrieving an IPropValue interface for the given property and accessing its value. For example, the following command sets the AdaptorName field of the

daqhwinfo structure to winsound. GetHwInfo()->put_MemberValue(L"adaptorname",CComVariant(L"winsou nd"));
The following command sets the TotalChannels field of the daqhwinfo structure to 2.
GetHwInfo()->put_MemberValue(L"totalchannels",CComVariant(2L));

get_MemberValue

HRESULT get_MemberValue(LPCOLESTR MemberName, VARIANT *pVal)

MemberName

The requested property name.
The propertys current value.
The get_MemberValue method returns the current value of a property. This function is a shortcut for retrieving an IPropValue interface for the given property and accessing its value. For the sound card, up to two channels can be added. If one channel is added, sound is recorded and played in mono. If two channels are added, sound is recorded and played in stereo. By default, if one channel is added to the winsound object, the channel is assigned a ChannelName of Mono. If a second channel is added, and you have not renamed the first channel, the two channels have the names Left and Right. The following code fragment determines the first channels ChannelName property value:
CComVariant pVal; CComQIPtr<IPropContainer> pCont; GetChannelContainer(0, &pCont); pCont->get_MemberValue(L"channelname", &pVal);
Note: engine is a pointer to the IDaqEngine interface that was obtained from the adaptors Open method. The IPropContainer interface for the first channel is returned to pCont.
IChannelList interface: GetChannelContainer

IChannel

IChannel is the interface to an individual channel. An IChannel interface is acquired by calling IChannelList::GetChannelContainer. An IChannel
interface should not be stored for a device that is not running. Deleting a channel invalidates the IChannel interface for that channel. An IChannel object implements all methods of IPropContainer plus the methods described below.

get_PropValue

HRESULT get_PropValue(REFIID MemberIID, IPropRoot* Member, [out, retval] VARIANT *pVal)

MemberIID Member

IID of the interface passed in as Member. It must be derived from IPropRoot. An interface to the channel property whose value is desired.
The value of the member property for the given channel.
The get_PropValue function retrieves the value of a property for a given channel. This function is more efficient than using get_MemberValue because it does not require looking up the string name of the property.

put_PropValue

HRESULT put_PropValue(REFIID riid, IPropRoot* Member, VARIANTREF NewVal)