Properties

Note

The MATLAB^® instrument driver functions makemid, midedit, and midtest will be removed in a future release. Use the ividev interface from the Instrument Control Toolbox™ Support Package for IVI^® and VXIplug&play Drivers instead. For more information, see IVI and VXIplug&play Drivers.

Properties: Overview

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.

Property Components

The behavior of the property is defined by the following components.

Set Code

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

Get Code

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.

Note

The code used for your property's get code and set code cannot include calls to the fclose or fopen functions on the interface object being used to access your instrument.

Accepted Property Values

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.

Property Value Dependencies

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.

Default Value

The default value of the property is the value that the property is configured to when the object is created.

Read-Only Value

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 `set` function.
While Open	The property can only be configured with the `set` function when the device object is not connected to the instrument. A device object is disconnected from the instrument with the `disconnect` function.
Always	The property cannot be configured with the `set` function.

Help Text

The help text provides information on the property. This information is returned with the instrhelp function.

instrhelp(obj,'PropertyName')

Examples of Properties

This section includes several examples of creating, setting, and reading properties, with steps for verifying the behavior of these properties.

Creating a Double-Bounded Property

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 Help 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 Help tabs.

info = propinfo(obj,'DisplayContrast')

info = 

  struct with fields:

                 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])
```

Creating an Enumerated Property

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 Help 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)

    ConfirmationFcn = 
    DriverName = tektronix_tds210_ex.mdd
    DriverType = MATLAB interface object
    InstrumentModel = 
    Interface = [1x1 gpib]
    LogicalName = GPIB0-2
    Name = scope-tektronix_tds210_ex
    ObjectVisibility = on
    RsrcName = 
    Status = closed
    Tag = 
    Timeout = 10
    Type = scope
    UserData = []

    SCOPE specific properties:
    CursorType = none
    DisplayContrast = 50

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)

    ConfirmationFcn: string -or- function handle -or- cell array
    Name: 
    ObjectVisibility: [ {on} | off ]
    Tag: 
    Timeout: 
    UserData: 

    SCOPE specific properties:
    CursorType: [ {none} | voltage | time ]
    DisplayContrast: [ 1.0 to 100.0 ]

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'

There is no enumerated value named 'horizontal'.

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 Help tabs.

info = propinfo(obj,'CursorType')

info = 

  struct with fields:

                 Type: 'string'
           Constraint: 'enum'
      ConstraintValue: {3×1 cell}
         DefaultValue: 'none'
             ReadOnly: 'never'
    InterfaceSpecific: 1

info.ConstraintValue

ans =

  3×1 cell array

    {'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])
```

A MATLAB Code Style Property

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 Set code text field.

The following MATLAB software code is added to the Get code 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 Help 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)

    ConfirmationFcn = 
    DriverName = tektronix_tds210_ex.mdd
    DriverType = MATLAB interface object
    InstrumentModel = 
    Interface = [1x1 gpib]
    LogicalName = GPIB0-2
    Name = scope-tektronix_tds210_ex
    ObjectVisibility = on
    RsrcName = 
    Status = closed
    Tag = 
    Timeout = 10
    Type = scope
    UserData = []

    SCOPE specific properties:
    CursorDelta = 0
    CursorType = none
    DisplayContrast = 50

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)

    ConfirmationFcn: string -or- function handle -or- cell array
    Name: 
    ObjectVisibility: [ {on} | off ]
    Tag: 
    Timeout: 
    UserData: 

    SCOPE specific properties:
    CursorType: [ {none} | voltage | time ]
    DisplayContrast: [ 1.0 to 100.0 ]

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 Help tabs.

info = propinfo(obj,'CursorDelta')

info = 

  struct with fields:

                 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])
```