You can make the programming of instruments through device objects
easier and more consistent by using properties. A property can be
used to query or set an instrument setting or attribute. For example,
an oscilloscope's trigger level may be controlled with a property
called TriggerLevel
, which you can read or control
with the get
or set
function.
Even if two different scopes have different trigger syntax, you can
use the same property name, TriggerLevel
, to
control them, because each scope will have its own instrument driver.
Another advantage of properties is that you can define them with certain acceptable values (enumerated) or limits (bounded) that can be checked before the associated commands are sent to the instrument.
The behavior of the property is defined by the following components.
The set
code defines the code that is executed
when the property is configured with the set
function.
The set
code can be defined as an instrument command
that will be written to the instrument or it can be defined as MATLAB® software
code.
If the set
code is MATLAB code, it can
include any number of commands or MATLAB software code wrapped
around instrument commands to provide additional processing or analysis.
If the set
code is defined as an instrument
command, then the command written to the instrument will be the instrument
command concatenated with a space and the value specified in the call
to set
. For example, the set
code
for the DisplayContrast
property is defined as
the instrument command DISplay:CONTRast
. When the set
function below is evaluated, the
instrument command sent to the instrument will be DISplay:CONTRast
54
.
set(obj, 'DisplayContrast', 54);
The get
code defines the code that is executed
when the property value is queried with the get
function. The get
code
can be defined as an instrument command that will be written to the
instrument or it can be defined as MATLAB software code.
You can define the values that the property can be set to so that only valid values are written to the instrument and an error would be returned before an invalid value could be written to the instrument.
A property value can be defined as a double, a character vector, or a Boolean.
A property value that is defined as a double can be
restricted to accept only doubles within a certain range or a list
of enumerated doubles. For example, a property could be defined to
accept a double within the range of [0 10]
or a
property could be defined to accept one of the values [1,7,8,10]
.
A property value that is defined as a character vector
can be restricted to accept a list of enumerated character vectors.
For example, a property could be defined to accept the character vectors min
and max
.
Additionally, a property can be defined to accept multiple property
value definitions. For example, a property could be defined to accept
a double ranging between [0 10]
or the character
vectors min
and max
.
A property value can be dependent upon another property's value.
For example, in controlling a power supply, the property VoltageLevel
can
be configured to the following values:
A double ranging between 0 and 10 when the value of
property VoltageOutputRange
is high
A double ranging between 0 and 5 when the value of
property VoltageOutputRange
is low
When VoltageLevel
is configured, the value
of VoltageOutputRange
is queried. If the value
of VoltageOutputRange
is high
,
then VoltageLevel
can be configured to a double
ranging between 0 and 10. If the value of VoltageOutputRange
is low
,
then VoltageLevel
can be configured to a double
ranging between 0 and 5.
The default value of the property is the value that the property is configured to when the object is created.
The read-only value of the property defines when the property can be configured. Valid options are described below.
Read-Only Value | Description |
---|---|
Never | The property can be configured at all times with the |
While Open | The property can only be configured with the |
Always | The property cannot be configured with the |
The help text provides information on the property. This information
is returned with the instrhelp
function.
instrhelp(obj, 'PropertyName')
This section includes several examples of creating, setting, and reading properties, with steps for verifying the behavior of these properties.
This example creates a property that will configure the Tektronix® TDS
210 oscilloscope's LCD display contrast. The oscilloscope display
can be configured to a value in the range [1 100]
.
In the MATLAB instrument driver editor,
Select the Properties
node
in the tree.
Enter the property name, DisplayContrast
,
in the Name text field and click
the Add button. The new property's name, DisplayContrast
,
appears in the Property Name table.
Expand the Properties
node
in the tree to display all the defined properties.
Select the DisplayContrast
node
from the properties displayed in the tree.
Select the Code tab to define the set
and get
commands
for the DisplayContrast
property.
Select Instrument Commands
in the Property style field.
Enter DISplay:CONTRast?
in the Get command text field.
Enter DISplay:CONTRast
in the Set command text field.
Select the Property Values tab to define the allowed property values.
Select Double
in the Data Type field.
Select Bounded
in the Constraint field.
Enter 1.0
in the Minimum field.
Enter 100.0
in the Maximum field.
Select the General tab to finish defining the property behavior.
Enter 50
in the Default
value text field.
Select never
in the Read only field.
In the Help text field,
enter Sets or queries the contrast of the LCD display
.
Click the Save button.
Verifying the Behavior of the Property. This procedure verifies the behavior of the property. In this
example, the driver name is tektronix_tds210_ex.mdd
.
Communication with the Tektronix TDS 210 oscilloscope at primary
address 2 is done via a Measurement
Computing™ Corporation GPIB
board at board index 0. From the MATLAB command line,
Create the device object, obj
,
using the icdevice
function.
g = gpib('mcc', 0, 2); obj = icdevice('tektronix_tds210_ex.mdd', g);
View DisplayContrast
property
and its current value.
obj.DisplayContrast ans = 50
Calling set
on
the DisplayContrast
property lists the values
to which you can set the property.
set(obj, 'DisplayContrast') [ 1.0 to 100.0 ]
Try setting the property to values inside and outside of the specified range.
obj.DisplayContrast = 17 obj.DisplayContrast ans = 17 obj.DisplayContrast = 120 ??? Invalid value for DisplayContrast. Valid values: a value between 1.0 and 100.0.
View the help you wrote.
instrhelp(obj,'DisplayContrast') DISPLAYCONTRAST [ 1.0 to 100.0 ] Sets or queries the contrast of the LCD display.
List the DisplayContrast
characteristics
that you defined in the Property Values and General tabs.
info = propinfo(obj,'DisplayContrast') info = Type: 'double' Constraint: 'bounded' ConstraintValue: [1 100] DefaultValue: 50 ReadOnly: 'never' InterfaceSpecific: 1
Connect to your instrument
to verify the set
and get
code.
connect(obj)
When you issue the get
function
in the MATLAB software, the tektronix_tds210_ex.mdd
driver
actually sends the DISplay:CONTRast?
command to
the instrument.
obj.DisplayContrast ans = 17
When
you issue the set
function in the MATLAB software,
the tektronix_tds210_ex.mdd
driver actually sends
the DISplay:CONTRast 34
command to the instrument.
obj.DisplayContrast = 34)
Finally, disconnect from the instrument and delete the objects.
disconnect(obj) delete([obj g])
This example creates a property that will select and display the Tektronix TDS 210 oscilloscope's cursor. The oscilloscope allows two types of cursor. It supports a horizontal cursor that measures the vertical units in volts, divisions, or decibels, and a vertical cursor that measures the horizontal units in time or frequency. In the MATLAB instrument driver editor,
Select the Properties
node
in the tree.
Enter the property name, CursorType
,
in the Name text field and click
the Add button. The new property's name CursorType
appears
in the Property Name table.
Expand the Properties
node
to display all the defined properties.
Select the CursorType
node
from the properties displayed in the tree.
Select the Code tab
to define the set
and get
commands
for the CursorType
property.
Select Instrument Commands
in the Property style field.
Enter CURSor:FUNCtion?
in the Get Command text field.
Enter CURSor:FUNCtion
in the Set Command text field.
Select the Property Values tab to define the allowed property values.
Select String
in the Data Type field.
Select Enumeration
in the Constraint field.
Enter none
in the New property value text field and click the Add button.
Then enter OFF
in the Instrument
Value table field.
Similarly add the property value voltage
,
with instrument value HBArs
.
Similarly add the property value time
,
with instrument value VBArs
.
Select the General tab to finish defining the property behavior.
Enter none
in the Default value text field.
Select never
in the Read only field.
In the Help text field,
enter Specifies the type of cursor
.
Click the Save button.
Verifying the Behavior of the Property. This procedure verifies the behavior of the property. In this
example, the driver name is tektronix_tds210_ex.mdd
.
Communication with the Tektronix TDS 210 oscilloscope at primary
address 2 is done via a Measurement
Computing Corporation GPIB
board at board index 0. From the MATLAB command line,
Create the device object, obj
,
using the icdevice
function.
g = gpib('mcc', 0, 2); obj = icdevice('tektronix_tds210_ex.mdd', g);
View the CursorType
property's
current value. Calling get
on the object lists
all its properties.
get(obj)
Calling get
on the CursorType
property
lists its current value.
obj.CursorType ans = none
View acceptable values for the CursorType
property.
Calling set
on the object lists all its settable
properties.
set(obj)
Calling set
on the CursorType
property
lists the values to which you can set the property.
set(obj, 'CursorType') [ {none} | voltage | time ]
Try setting the property to valid and invalid values.
obj.CursorType = 'voltage'; obj.CursorType ans = voltage obj.CursorType = 'horizontal' ??? The 'horizontal' enumerated value is invalid.
View the help you wrote.
instrhelp(obj,'CursorType') CURSORTYPE [ {none} | voltage | time ] Specifies the type of cursor.
List the CursorType
characteristics
that you defined in the Property Values and General tabs.
info = propinfo(obj,'CursorType') info = Type: 'string' Constraint: 'enum' ConstraintValue: {3x1 cell} DefaultValue: 'none' ReadOnly: 'never' InterfaceSpecific: 1 info.ContraintValue ans = 'none' 'voltage' 'time'
Connect to your instrument to verify the set
and get
code.
connect(obj)
When you issue the set
function in the MATLAB software,
the tektronix_tds210_ex.mdd
driver actually sends
the CURSor:FUNCtion VBArs
command to the instrument.
obj.CursorType = 'time'
When you issue the get
function in the MATLAB software,
the tektronix_tds210_ex.mdd
driver actually sends
the CURSor:FUNCtion?
command to the instrument.
obj.CursorType ans = time
Finally disconnect from the instrument and delete the objects.
disconnect(obj) delete([obj g])
This example creates a property that will return the difference
between two cursors of the Tektronix TDS 210 oscilloscope. The
oscilloscope allows two types of cursor. It supports a horizontal
cursor that measures the vertical units in volts, divisions, or decibels,
and a vertical cursor that measures the horizontal units in time or
frequency. The previous example created a property, CursorType
,
that selects and displays the oscilloscope's cursor. In the MATLAB instrument
driver editor,
Select the Properties
node
in the tree.
Enter the property name, CursorDelta
,
in the New Property text field and
click Add. The new property's name, CursorDelta
,
appears in the Property Name table.
Expand the Properties
node
to display all the defined properties.
Select the CursorDelta
node
from the properties displayed in the tree.
Select the Code tab
to define the set and get commands for the CursorDelta
property.
Select M-Code
in the Property style field.
Since the CursorDelta
property
is read-only, no MATLAB software code will be added to the MATLAB Set Function text field.
The following MATLAB software code is added to the MATLAB Get Function text field.
% Extract the interface object. interface = obj.Interface; % Determine the type of cursor being displayed. type = obj.CursorType % Based on the cursor type, query the instrument. switch (type) case 'none' propertyValue = 0; case 'voltage' propertyValue = query(interface, 'CURSor:HBArs:DELTa?'); propertyValue = str2double(propertyValue); case 'time' propertyValue = query(interface, 'CURSor:VBArs:DELTa?'); propertyValue = str2double(propertyValue); end
Select the Property Values tab to define the allowed property values.
Select Double
in the Data Type field.
Select None
in the Constraint field.
Select the General tab to finish defining the property behavior.
Enter 0
in the Default
value text field.
Select always
in the Read only field.
In the Help text field,
enter Returns the difference between the two cursors
.
Click the Save button.
Verifying the Behavior of the Property. This procedure verifies the behavior of the property. In this
example, the driver name is tektronix_tds210_ex.mdd
.
Communication with the Tektronix TDS 210 oscilloscope at primary
address 2 is done via a Measurement
Computing Corporation GPIB
board at board index 0. From the MATLAB command line,
Create the device object, obj
,
using the icdevice
function.
g = gpib('mcc', 0, 2); obj = icdevice('tektronix_tds210_ex.mdd', g);
View the CursorDelta
property's
current value. Calling get
on the object lists
all its properties.
get(obj)
View the CursorDelta
property’s
current value.
obj.CursorDelta ans = 0
Calling set
on the object
lists all its settable properties. Note that as a read-only property, CursorDelta
is
not listed in the output.
set(obj)
Setting the property to a value results in an error message.
obj.CursorDelta = 4) ??? Changing the 'CursorDelta' property of device objects is not allowed.
View the help you wrote.
instrhelp(obj,'CursorDelta') CURSORDELTA (double) (read only) Returns the difference between the two cursors.
List the CursorDelta
characteristics
that you defined in the Property Values and General tabs.
info = propinfo(obj,'CursorDelta') info = Type: 'double' Constraint: 'none' ConstraintValue: [] DefaultValue: 0 ReadOnly: 'always' InterfaceSpecific: 1
Connect to your instrument to verify the get
code.
connect(obj)
When you issue the get
function in the MATLAB software,
the tektronix_tds210_ex.mdd
driver actually executes
the MATLAB software code that was specified.
obj.CursorDelta ans = 1.6000
Finally, disconnect from the instrument and delete the objects.
disconnect(obj) delete([obj g])