Instrument Control Toolbox 2.9

Configuring Instrument Object Properties

Contents

• Overview
• Accessing Properties
• Configuring Properties
• Getting Property Help and Other Information
• Cleanup

Overview

In this demo you will learn how to configure object properties with the Instrument Control toolbox and MATLAB

Instrument Control Toolbox objects contain properties that configure elements of the object's communication and behavior. Some properties are common to all interfaces or drivers and others are specific to a particular interface or driver, such as GPIB interfaces or Tektronix TDS210 oscilloscope drivers.

Accessing Properties

To access a complete list of an object's properties and their current values, use the get function with the object.

% Create a gpib object.
obj = gpib('iotech', 0, 1);

% List the gpib object's properties and their current values.
get(obj)

    ByteOrder = littleEndian
    BytesAvailable = 0
    BytesAvailableFcn = 
    BytesAvailableFcnCount = 48
    BytesAvailableFcnMode = eosCharCode
    BytesToOutput = 0
    ErrorFcn = 
    InputBufferSize = 512
    Name = GPIB0-1
    ObjectVisibility = on
    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 access a specific property value, use the get function with the object and property name.

bufferSize = get(obj, 'InputBufferSize')

bufferSize =

   512

valuesReceived = get(obj, 'ValuesReceived')

valuesReceived =

     0

Alternatively, we can access a specific property value by using the dot (.) notation.

bufferSize = obj.InputBufferSize

bufferSize =

   512

valuesReceived = obj.ValuesReceived

valuesReceived =

     0

Configuring Properties

Enumerated properties have a defined set of possible values. To list the enumerated values of a property, use the set function with the object and property name. The property's default value is listed in braces.

set(obj, 'RecordMode')

[ {overwrite} | append | index ]

To access a complete list of an object's configurable properties, use the set function with the object.

% List the gpib object's configurable properties.
set(obj)

    ByteOrder: [ {littleEndian} | bigEndian ] 
    BytesAvailableFcn: string -or- function handle -or- cell array
    BytesAvailableFcnCount
    BytesAvailableFcnMode: [ {eosCharCode} | byte ]
    ErrorFcn: string -or- function handle -or- cell array
    InputBufferSize
    Name
    ObjectVisibility: [ {on} | off ] 
    OutputBufferSize
    OutputEmptyFcn: string -or- function handle -or- cell array
    RecordDetail: [ {compact} | verbose ]
    RecordMode: [ {overwrite} | append | index ]
    RecordName
    Tag
    Timeout
    TimerFcn: string -or- function handle -or- cell array
    TimerPeriod
    UserData
    
    GPIB specific properties:
    BoardIndex
    CompareBits
    EOIMode: [ {on} | off ]
    EOSCharCode
    EOSMode: [ {none} | read | write | read&write ]
    PrimaryAddress
    SecondaryAddress
 

To configure an object's property value, use the set function with the object, property name, and property value.

set(obj, 'Timeout', 2)

set(obj, 'ByteOrder', 'littleEndian')

Alternatively, we can configure a specific property value by using the dot (.) notation.

obj.Timeout = 2;

obj.ByteOrder = 'littleEndian';

Getting Property Help and Other Information

To obtain a property's description, use the instrhelp function with the object and property name. You can also use instrhelp for function help.

instrhelp(obj, 'RecordMode')

   RECORDMODE  [ append | {overwrite} | index ]

   Specify whether data and event information are saved to one record 
   file or to multiple record files.
   
   You can configure RecordMode to be overwrite, append, or index. If
   RecordMode is overwrite, then the record file is overwritten each time
   recording is initiated. If RecordMode is append, then data is appended
   to the record file each time recording is initiated. If RecordMode is
   index, a different record file is created each time recording is initiated,
   each with an indexed filename.
   
   You can configure RecordMode only when the object is not recording. 
   You terminate recording with the RECORD function. An object that is 
   not recording has a RecordStatus property value of off.
   
   You specify the record filename with the RecordName property.
   
   See also RECORD, RecordDetail, RecordName, RecordStatus.

To obtain information on a property's attributes, use the propinfo function with the object and property name.

propinfo(obj, 'RecordMode')

ans = 

                 Type: 'string'
           Constraint: 'enum'
      ConstraintValue: {3x1 cell}
         DefaultValue: 'overwrite'
             ReadOnly: 'whileRecording'
    InterfaceSpecific: 0

Cleanup

When you no longer need the instrument object, remove it from memory and clear the MATLAB workspace of its associated variable.

delete(obj);
clear obj