Documentation

Base and Interface-Specific Properties

You establish the desired instrument object behavior by configuring property values. You can configure property values using the set function or the dot notation, or by specifying property name/property value pairs during object creation. You can return property values using the get function or the dot notation.

Interface objects possess two types of properties:

Returning Property Names and Property Values

Once the instrument object is created, you can set configurable properties. Additionally, if a property has a finite set of character vector values, then set also returns these values.

For example, the configurable properties for the GPIB object g are shown below. The base properties are listed first, followed by the GPIB-specific properties.

g = gpib('ni',0,1);
set(g)
    ByteOrder: [ {littleEndian} | bigEndian ] 
    BytesAvailableFcn
    BytesAvailableFcnCount
    BytesAvailableFcnMode: [ {eosCharCode} | byte ]
    ErrorFcn
    InputBufferSize
    Name
    OutputBufferSize
    OutputEmptyFcn
    RecordDetail: [ {compact} | verbose ]
    RecordMode: [ {overwrite} | append | index ]
    RecordName
    Tag
    Timeout
    TimerFcn
    TimerPeriod
    UserData
    
    GPIB specific properties:
    BoardIndex
    CompareBits
    EOIMode: [ {on} | off ]
    EOSCharCode
    EOSMode: [ {none} | read | write | read&write ]
    PrimaryAddress
    SecondaryAddress

You can display one or more properties and their current values to a variable or to the command line.

For example, all the properties and their current values for the GPIB object g are shown below. The base properties are listed first, followed by the GPIB-specific properties.

get(g)
    ByteOrder = littleEndian
    BytesAvailable = 0
    BytesAvailableFcn = 
    BytesAvailableFcnCount = 48
    BytesAvailableFcnMode = eosCharCode
    BytesToOutput = 0
    ErrorFcn = 
    InputBufferSize = 512
    Name = GPIB0-1
    OutputBufferSize = 512
    OutputEmptyFcn = 
    RecordDetail = compact
    RecordMode = overwrite
    RecordName = record.txt
    RecordStatus = off
    Status = closed
    Tag = 
    Timeout = 10
    TimerFcn = 
    TimerPeriod = 1
    TransferStatus = idle
    Type = gpib
    UserData = []
    ValuesReceived = 0
    ValuesSent = 0

    GPIB specific properties:
    BoardIndex = 0
    BusManagementStatus = [1x1 struct]
    CompareBits = 8
    EOIMode = on
    EOSCharCode = LF
    EOSMode = none
    HandshakeStatus = [1x1 struct]
    PrimaryAddress = 1
    SecondaryAddress = 0

To display the current value for one property, you supply the property name to get.

g.OutputBufferSize
ans =
   512

To display the current values for multiple properties, you include the property names as elements of a cell array.

g.BoardIndex
ans = 
    [0]  

g.TransferStatus
ans = 
    'idle'

You can also use the dot notation to display a single property value.

g.PrimaryAddress
ans =
     1

Configuring Property Values

You can configure property values using the object

g.EOSMode = 'read'

To configure values for multiple properties, you can set each one as follows.

g.EOSCharCode = 'CR'
g.Name = 'Test1-gpib'

Note that you can configure only one property value at a time using the dot notation.

In practice, you can configure many of the properties at any time while the instrument object exists — including during object creation. However, some properties are not configurable while the object is connected to the instrument or when recording information to disk. Use the propinfo function, or refer to the properties documentation to understand when you can configure a property.

Specifying Property Names

Instrument object property names are presented using mixed case. While this makes property 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 EOSMode property in any of these ways.

g.EOSMode = 'read'
g.eosmode = 'read'
g.EOSM = 'read'

However, when you include property names in a file, you should use the full property name. This practice can prevent problems with future releases of the Instrument Control 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.

If a property has a finite set of character vector values, then the default value is enclosed by {} (curly braces). For example, the default value for the EOSMode property is none.

g.EOSMode
ans =

none

You can also use the propinfo function, or refer to the functions documentation to find the default value for any property.

Using Tab Completion for Functions

To get a list of options you can use on the function, press the Tab key after entering a function on the MATLAB command line. The list expands, and you can scroll to choose a property or value. For example, when you create a gpib object, you can get a list of installed vendors:

g = gpib('

When you press Tab after the parentheses and single quote, as shown here, the list of installed GPIB vendors displays, such as keysight, ics, mcc, and ni.

The format for the GPIB object constructor function is:

g = gpib('vendor',boardindex,primaryaddress) 

When you press Tab where a field should appear, you get the list of options for that field. The other interface objects, such as Bluetooth, Serial, TCP/IP, etc., also include this capability on their object constructor functions.

You can also get the values for property-value pairs. For example, to get the possible terminator values when creating a serial object, type:

s = serial('COM1','Terminator',' 

Press Tab after typing the single quote after Terminator to get the possible values for that property, as shown here.

Many of the other toolbox functions also have tab completion. For example, when using the fread function you can specify the precision type using tab completion.

data = fread(s,256,' 

Press Tab after typing the single quote after the size (256 values in this example), since precision is the next argument the fread function takes, to get the possible values for the precision types, such as 'double', 'int16', etc.

When the list of possible values is long, a scroll bar appears in the pop-up window, as shown in this example.

Property Inspector

The Property Inspector enables you to inspect and set properties for one or more instrument objects. It provides a list of all properties and displays their current values.

Settable properties in the list are associated with an editing device that is appropriate for the values accepted by the particular property. For example, a callback configuration GUI to set ErrorFcn, a pop-up menu to set RecordMode, and a text field to specify the TimerPeriod. The values for read-only properties are grayed out.

You open the Property Inspector with the inspect function. Alternatively, you can open the Property Inspector via the Workspace browser by right-clicking an instrument object and selecting Call Property Inspector from the context menu, or by double-clicking the object.