Transcription
Data Acquisition Toolbox Quick Reference GuideGetting StartedThese components are shown below.If you have a sound card installed, you can run thefollowing code, which collects one second of data.MATLABai start(ai)data getdata(ai);plot(data)delete(ai)clear ai Interactive commands and dataData Acquisition ToolboxM-file functionsData acquisition engineTo list all the toolbox functions and demos, typeDisk fileHardware driver adaptorshelp daqProperties, data, and eventsTo display the command line help for a function, typedaqhelp function nameHardware driverProperties, data, and eventsToolbox ComponentsSensorsThe Data Acquisition Toolbox components aredescribed below.ComponentPurposeM-filesCreate device objects, acquire oroutput data, configure propertyvalues, and evaluate your acquisitionstatus and resources.EngineStore device objects and theirproperty values, control the storage ofacquired or queued data, and controlthe synchronization of events.AdaptorsPass properties, data, and eventsbetween the hardware and theengine.HardwareActuatorsDevice ObjectsDevice objects allow you to access specific hardwaresubsystems. The device objects supported by the toolboxinclude analog input (AI), analog output (AO), and digitalI/O (DIO) objectDIOsubsystemToolbox deviceobjectsHardwaresubsystems
The Data Acquisition SessionAdding Channels or LinesA complete data acquisition session consists of five steps:Before you can use a device object, you must add at leastone channel or line to it. To add channels to a deviceobject, you must use the addchannel function. Forexample, to add two channels to ai:1 Creating a device object2 Adding channels or lines to the device objectchans addchannel(ai,1:2);3 Configuring property values to control the behavior ofYou can think of a device object as a channel or linecontainer, the added channels as a channel group, andthe added lines as a line group.your data acquisition application4 Acquiring data (AI) or outputting data (AO)The relationship between an analog input object and thechannels it contains is shown below.5 Cleaning upAnalog Input ObjectCreating a Device ObjectContainer(device object)To create a device object, you must call the appropriatecreation function (constructor). As shown below, creationfunctions are named for the device object they create.Channel 1Channel 2Subsystem TypeCreation FunctionAnalog inputanaloginput('adaptor',ID);Analog outputanalogoutput('adaptor',ID);Digital I/Odigitalio('adaptor',ID);Channel 3.Channel groupChannel nID is the hardware device identifier. This is an optionalargument for sound cards with an ID of 0. adaptor is thename of the hardware driver adaptor. The supportedadaptors are shown below.For digital I/O objects, this diagram looks the sameexcept that lines replace channels.Configuring PropertiesHardware VendorAdaptor NameAdvantech advantechMeasurement Computing mccYou can control the behavior of your data acquisitionapplication by configuring properties. The rulesassociated with configuring properties includeNational Instruments nidaq Property names are not case sensitive.Parallel portparallelMicrosoft Windows soundwinsound You can abbreviate property names. set(ai) returns all settable properties for ai, whileset(ai.Channel(index)) returns all settableproperties for the specified channel.card get(ai) returns the current property values for ai,while get(ai.Channel(index)) returns the currentproperty values for the specified channel.For example, to create the analog input object ai for asound card:ai analoginput('winsound');2
Property TypesIssuing a TriggerToolbox properties are divided into these two main types:To log data to the engine or a disk file (AI), or to outputdata from the engine (AO), a trigger must occur. Thetrigger types supported for all hardware are given below. Common properties that apply to every channel or linecontained by a device object Channel/line properties that you can configure forindividual channels or linesTrigger TypeDescriptionImmediateThe trigger occurs just after you issuestart. This is the default trigger type. Base properties that apply to all supported hardwaresubsystems of a given type (AI, AO, DIO)ManualThe trigger occurs after you manuallyissue the trigger function. Device-specific properties that apply to the specifichardware you are usingSoftwareThe trigger occurs when a signalsatisfying the specified condition isdetected. You must specify a channelas a trigger source.Common and channel/line properties are divided intothese two types:(AI only)set and get display the base properties followed by thedevice-specific properties.After the trigger occurs, the Logging (AI) or Sending (AO)property is automatically set to On.Property SyntaxYou can configure and return property values threeways: the get or set functions, dot notation, or namedindexing.Stopping a Device ObjectA device object stops when the requested data is acquired(AI) or output (AO), a run-time error occurs, or you issuethe stop function.The get and set syntax is similar to the HandleGraphics get and set syntax.out p(ai)The dot notation has the following syntax:Managing Dataout ai.SampleRate;ai.SampleRate 11025;Previewing DataNamed indexing allows you to associate a descriptivename with a channel or line. For example, to associatethe name Chan1 with the first channel contained by ai:While an AI object is running, you can preview acquireddata with the peekdata function. For example, to preview1000 samples for ai:set(ai.Channel(1),'ChannelName','Chan1');out ai.Chan1.UnitsRange;ai.Chan1.UnitsRange [0 10];out peekdata(ai,1000);peekdata returns execution control immediately toMATLAB and does not extract data from the engine.Extracting DataAcquiring or Outputting DataAt any time after data is acquired by an AI object, you canextract it from the engine with the getdata function. Forexample, to extract 1000 samples for ai:To acquire (AI) or output (AO) data, you must1 Start the device object.out getdata(ai,1000);2 Log or send data.3 Stop the device object.getdata returns execution control to MATLAB onlywhen all requested samples are returned.Starting the Device ObjectOutputting DataTo start the device object, use the start function.To output data, you must first queue it in the engine withthe putdata function. For example, to queue 1000samples for the analog output object ao:start(ai)After the device object is started, the Running (AI) orSending (AO) property is automatically set to On.putdata(ao,[1:1000]')Once data is queued, you can start the AO object.3
Reading and Writing Digital ValuesDeleting and Clearing Device ObjectsTransferring digital values to and from a DIO subsystemis not clocked at a specific rate in the way that data issampled by an analog input subsystem. Instead, valuesare either written directly to digital lines with putvalue,or read directly from digital lines with getvalue.The delete function removes the specified device objectfrom the engine but not from the MATLAB workspace.delete(ai)ai still exists in the MATLAB workspace, but is aninvalid object since it is no longer associated withhardware. You should remove invalid device objects withthe clear command.Additionally, DIO objects do not store data in the engine.Therefore, they do not require starting or triggering. Forexample, to write the value 23 to eight DIO lines:clear aidio ata 23;putvalue(dio,data)getvalue(dio)If you clear a valid device object, the object no longerexists in the workspace, but does exist in the engine. Youcan return device objects from the engine with thedaqfind function.out daqfind;ai out(1);Events and CallbacksAn event occurs at a particular time after a condition ismet. Unless an error occurs, all AI and AO dataacquisition sessions contain a start, trigger, and stopevent.Saving and Loading Device ObjectsYou can save a device object to a MAT-file with the savecommand.You can access event information with the EventLogproperty:Events ai.EventLog;EventTypes {Events.Type}EventTypes 'Start''Trigger'save aiYou can load a device object into the MATLAB workspace with the load command.load ai'Stop'You can convert a device object to equivalent MATLABcode with the obj2code function.When an event occurs, you can execute an M-file callbackfunction. You can select the callback function to beexecuted by specifying the name of the M-file as the valuefor the associated callback property.obj2code(ai,'ai save')You can recreate the device object by running the M-file.For example, the following commands configure ai sothat the M-file daqcallback is executed when a trigger,run-time error, or stop event occurs.ai ai back)Logging Information to DiskFor an AI object, you can log acquired data, events, deviceobjects, and hardware information to a disk file usingthese properties.To see how you construct a callback function, typetype ,'Index')You can retrieve information from an existing log fileusing the daqread function. To retrieve all logged data:data daqread('data.daq');To retrieve only object and hardware information:daqinfo daqread('data.daq','info');4
Getting Information and HelpYou can obtain information or help about installedhardware, driver adaptors, device objects, functions, orproperties using the functions shown below.FunctionDescriptiondaqhelpDisplay help for device objects,constructors, adaptors, functions, andproperties.daqhwinfoDisplay data acquisition hardwareinformation.propinfoReturn property characteristics fordevice objects, channels, or lines.PDF and HTML versions of the Data AcquisitionToolbox User’s Guide are available through the Helpbrowser.5
FunctionsToolbox functions and the device objects they are associated with are organized into the groups shown below. Thesupported device objects include analog input (AI), analog output (AO), and digital I/O (DIO).Creating Device ObjectsanaloginputCreate an analog input object.analogoutputCreate an analog output object.digitalioCreate a digital I/O object.AIAODIO333Adding Channels and LinesaddchannelAdd hardware channels to an analog input or analog output object.addlineAdd hardware lines to a digital I/O object.Getting and Setting PropertiesAIAO33DIO3AIAODIOgetReturn device object properties.333setConfigure or display device object properties.333setverifyConfigure and return the specified property.333AIAODIOExecuting the ObjectstartStart a device object.333stopStop a device object.333triggerManually execute a trigger.33waitWait for the device object to stop running.33AIAOWorking with DataflushdataRemove data from the data acquisition engine.3getdataExtract data, time, and event information from the data acquisition engine.3getsampleImmediately acquire one sample.3getvalueRead values from lines.peekdataPreview most recent acquired data.putdataQueue data in the engine for eventual output.DIO3363
Working with DataputsampleImmediately output one sample.putvalueWrite values to lines.AIAODIO33Getting Information and HelpAIAODIOdaqhelpDisplay help for device objects, constructors, adaptors, functions, andproperties.333daqhwinfoDisplay data acquisition hardware information.333propinfoReturn property characteristics for device objects, channels, or lines.333AIAODIOGeneral Purpose3binvec2decConvert binary vector to decimal value.clearRemove device objects from the MATLAB workspace.333daqcallbackA callback function that displays event information for the specified event.333daqfindReturn device objects, channels, or lines from the data acquisition engineto the MATLAB workspace.333daqmemAllocate or display memory resources.33daqreadRead a Data Acquisition Toolbox (.daq) file.3daqregisterRegister or unregister a hardware driver adaptor.333daqresetRemove device objects and data acquisition DLLs from memory.333dec2binvecConvert decimal value to binary vector.deleteRemove device objects, channels, or lines from the data acquisition engine.333dispDisplay summary information for device objects, channels, or lines.333ischannelCheck for channels.333isdiolineCheck for lines.333isvalidDetermine whether device objects, channels, or lines are valid.333lengthReturn the length of a device object, channel group, or line group.333loadLoad device objects, channels, or lines into the MATLAB workspace.333makenamesGenerate a list of descriptive channel or line names.333obj2mfileConvert device objects, channels, or lines to MATLAB code.333saveSave device objects to a MAT-file.333showdaqeventsDisplay event log information.33sizeReturn the size of a device object, channel group, or line group.33733
Analog Input Base PropertiesAnalog 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 beconfigured for individual channels.Common PropertiesAnalog Input Basic Setup PropertiesSamplesPerTriggerSpecify the number of samples to acquire for each channel group member for eachtrigger that occurs.SampleRateSpecify the per-channel rate at which analog data is converted to digital data.TriggerTypeSpecify the type of trigger to execute.Analog Input Logging PropertiesLogFileNameSpecify the name of the disk file to which information is logged.LoggingIndicate whether data is being logged to memory or to a disk file.LoggingModeSpecify the destination for acquired data.LogToDiskModeSpecify whether data, events, and hardware information are saved to one disk file or tomultiple disk files.Analog Input Trigger PropertiesInitialTriggerTimeIndicate the absolute time of the first trigger.ManualTriggerHwOnSpecify that the hardware device starts when a manual trigger is issued.TriggerFcnSpecify the M-file callback function to execute when a trigger occurs.TriggerChannelSpecify the channel serving as a trigger source.TriggerConditionSpecify the condition that must be satisfied before a trigger executes.TriggerConditionValueSpecify one or more voltage values that must be satisfied before a trigger executes.TriggerDelaySpecify the delay value for data logging.TriggerDelayUnitsSpecify the units in which trigger delay data is measured.TriggerRepeatSpecify the number of additional times the trigger executes.TriggersExecutedIndicate the number of triggers that execute.TriggerTypeSpecify the type of trigger to execute.8
Analog Input Status PropertiesLoggingIndicate whether data is being logged to memory or to a disk file.RunningIndicate whether the device object is running.SamplesAcquiredIndicate the number of samples acquired per channel.SamplesAvailableIndicate the number of samples available per channel in the engine.Analog Input Hardware Configuration PropertiesChannelSkewSpecify the time between consecutive scanned hardware channels.ChannelSkewModeSpecify how the channel skew is determined.ClockSourceSpecify the clock used to govern the hardware conversion rate.InputTypeSpecify the analog input hardware channel configuration.SampleRateSpecify the per-channel rate at which analog data is converted to digital data.Analog Input Callback PropertiesDataMissedFcnSpecify the M-file callback function to execute when data is missed.InputOverRangeFcnSpecify the M-file callback function to execute when acquired data exceeds the validhardware range.RuntimeErrorFcnSpecify the M-file callback function to execute when a run-time error occurs.SamplesAcquiredFcnSpecify the M-file callback function to execute every time a predefined number ofsamples is acquired for each channel group member.SamplesAcquiredFcnCountSpecify the number of samples to acquire for each channel group member before asamples acquired event is generated.StartFcnSpecify the M-file callback function to execute just before the device object startsrunning.StopFcnSpecify the M-file callback function to execute just after the device object stops running.TimerFcnSpecify the M-file callback function to execute whenever a predefined period of timepasses.TimerPeriodSpecify the period of time between timer events.TriggerFcnSpecify the M-file callback function to execute when a trigger occurs.9
Analog Input General Purpose PropertiesBufferingConfigSpecify the per-channel allocated memory.BufferingModeSpecify how memory is allocated.ChannelContain hardware channels added to the device object.EventLogStore information for specific events.NameSpecify a descriptive name for the device object.TagSpecify a device object label.TimeoutSpecify an additional waiting time to extract data.TypeIndicate the device object type.UserDataStore data that you want to associate with a device object.Channel PropertiesAnalog Input Channel PropertiesChannelNameSpecify a descriptive channel name.HwChannelSpecify the hardware channel ID.IndexIndicate the MATLAB index of a hardware channel.InputRangeSpecify the range of the analog input subsystem.NativeOffsetIndicate the offset to use when converting between the native data format and doubles.NativeScalingIndicate the scaling to use when converting between the native data format and doubles.ParentIndicate the parent (device object) of a channel.SensorRangeSpecify the range of data you expect from your sensor.TypeIndicate a channel.UnitsSpecify the engineering units label.UnitsRangeSpecify the range of data as engineering units.10
Analog Output Base PropertiesAnalog 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 beconfigured for individual channels.Common PropertiesAnalog Output Basic Setup PropertiesSampleRateSpecify the per-channel rate at which digital data is converted to analog data.TriggerTypeSpecify the type of trigger to execute.Analog Output Trigger PropertiesInitialTriggerTimeIndicate the absolute time of the first trigger.TriggerFcnSpecify the M-file callback function to execute when a trigger occurs.TriggersExecutedIndicate the number of triggers that execute.TriggerTypeSpecify the type of trigger to execute.Analog Output Status PropertiesRunningIndicate whether the device object is running.SamplesAvailableIndicate the number of samples available per channel in the engine.SamplesOutputIndicate the number of samples output per channel from the engine.SendingIndicate whether data is being sent to the hardware device.Analog Output Hardware Configuration PropertiesClockSourceSpecify the clock used to govern the hardware conversion rate.SampleRateSpecify the per-channel rate at which digital data is converted to analog data.Analog Output Data Management PropertiesMaxSamplesQueuedIndicate the maximum number of samples that can be queued in the engine.RepeatOutputSpecify the number of additional times queued data is output.TimeoutSpecify an additional waiting time to queue data.11
Analog Output Callback PropertiesRuntimeErrorFcnSpecify the M-file callback function to execute when a run-time error occurs.SamplesOutputFcnSpecify the M-file callback function to execute every time a predefined number ofsamples is output for each channel group member.SamplesOutputFcnCountSpecify the number of samples to output for each channel group member before asamples output event is generated.StartFcnSpecify the M-file callback function to execute just before the device object startsrunning.StopFcnSpecify the M-file callback function to execute just after the device object stops running.TimerFcnSpecify the M-file callback function to execute whenever a predefined period of timepasses.TimerPeriodSpecify the period of time between timer events.TriggerFcnSpecify the M-file callback function to execute when a trigger occurs.Analog Output General Purpose PropertiesBufferingConfigSpecify the per-channel allocated memory.BufferingModeSpecify how memory is allocated.ChannelContain hardware channels added to the device object.EventLogStore information for specific events.NameSpecify a descriptive name for the device object.OutOfDataModeSpecify how the value held by the analog output subsystem is determined.TagSpecify a device object label.TypeIndicate the device object type.UserDataStore data that you want to associate with a device object.12
Channel PropertiesAnalog Output Channel PropertiesChannelNameSpecify a descriptive channel name.DefaultChannelValueSpecify the value held by the analog output subsystem.HwChannelSpecify the hardware channel ID.IndexIndicate the MATLAB index of a hardware channel.NativeOffsetIndicate the offset to use when converting between the native data format and doubles.NativeScalingIndicate the scaling to use when converting between the native data format and doubles.OutputRangeSpecify the range of the analog output hardware subsystem.ParentIndicate the parent (device object) of a channel.TypeIndicate a channel.UnitsSpecify the engineering units label.UnitsRangeSpecify the range of data as engineering units.13
Digital I/O Base PropertiesDigital I/O base properties are divided into two main categories: common properties and line properties. Commonproperties apply to every line contained by the digital I/O object, while line properties can be configured for individuallines.Common PropertiesDigital I/O Common PropertiesLineContain hardware lines added to the device object.NameSpecify a descriptive name for the device object.RunningIndicate whether the device object is running.TagSpecify a device object label.TimerFcnSpecify the M-file callback function to execute whenever a predefined period of timepasses.TimerPeriodSpecify the period of time between timer events.TypeIndicate the device object type.UserDataStore data that you want to associate with a device object.Line PropertiesDigital I/O Line PropertiesDirectionSpecify whether a line is used for input or output.HwLineSpecify the hardware line ID.IndexIndicate the MATLAB index of a hardware line.LineNameSpecify a descriptive line name.ParentIndicate the parent (device object) of a line.PortSpecify the port ID.TypeIndicate a line. COPYRIGHT 1999 - 2008 by The MathWorks, Inc. MATLAB and Simulink are registered trademarks of The MathWorks, Inc. Seewww.mathworks.com/trademarks for a list of additional trademarks. Other product or brand names may be trademarks or registeredtrademarks of their respective holders.MathWorks products are protected by one or more U.S. patents. Please see www.mathworks.com/patents for more information.14
Data Acquisition Toolbox Quick Reference Guide Component Purpose M-files Create device objects, acquire or output data, configure property values, and evaluate your acquisition status and resources. Engine Store device
