Configuring and Returning Properties :: Data Acquisition Session (Data Acquisition Toolbox™)

Learn more about Data Acquisition Toolbox

Configuring and Returning Properties

On this page…
Overview Property Types Returning Property Names and Property Values Configuring Property Values Specifying Property Names Default Property Values The Property Inspector

On this page…

Overview

Property Types

Returning Property Names and Property Values

Configuring Property Values

Specifying Property Names

Default Property Values

The Property Inspector

Overview

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

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

For digital I/O objects, the diagram would look the same except that lines would be substituted for channels.

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.

For a complete description of all properties, refer to Base Properties — Alphabetical List or Device-Specific Properties — Alphabetical List.

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} ]
        DataMissedFcn
        InputOverRangeFcn
        InputType: [ {AC-Coupled} ]
        LogFileName
        LoggingMode: [ Disk | {Memory} | Disk&Memory ]
        LogToDiskMode: [ {Overwrite} | Index ]
        ManualTriggerHwOn: [ {Start} | Trigger ]
        Name
        RuntimeErrorFcn
        SampleRate
        SamplesAcquiredFcn
        SamplesAcquiredFcnCount
        SamplesPerTrigger
        StartFcn
        StopFcn
        Tag
        Timeout
        TimerFcn
        TimerPeriod
        TriggerFcn
        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
        DataMissedFcn = @daqcallback
        EventLog = []
        InitialTriggerTime = [0 0 0 0 0 0]
        InputOverRangeFcn = 
        InputType = AC-Coupled
        LogFileName = logfile.daq
        Logging = Off
        LoggingMode = Memory
        LogToDiskMode = Overwrite
        ManualTriggerHwOn = Start
        Name = winsound0-AI
        Running = Off
        RuntimeErrorFcn = @daqcallback
        SampleRate = 8000
        SamplesAcquired = 0
        SamplesAcquiredFcn = 
        SamplesAcquiredFcnCount = 1024
        SamplesAvailable = 0
        SamplesPerTrigger = 8000
        StartFcn = 
        StopFcn = 
        Tag = 
        Timeout = 1
        TimerFcn = 
        TimerPeriod = 0.1
        TriggerFcn = 
        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.

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.

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 Base Properties — Alphabetical List 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.

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];

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 software 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 might 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.

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 Base Properties — Alphabetical List or Device-Specific Properties — Alphabetical List to find the default value for any property.

The Property Inspector

The Property Inspector is a graphical user interface (GUI) for accessing toolbox object properties. The Property Inspector is designed so you can

Display the names and current values for object properties
Display possible values for enumerated properties
Configure the property values

You open the Property Inspector with the inspect function, or via the Workspace browser by double-clicking an object.

For example, create the analog input object ai for a sound card and add both hardware channels.

ai = analoginput('winsound');
addchannel(ai,1:2);

Open the Property Inspector from the command line.

inspect(ai)

For more information on the Property Inspector, see the inspect reference page.

Hardware Channels or Lines

Acquiring and Outputting Data

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit