visa

(To be removed) Create VISA object

expand all in page

    visa will be removed in a future release. Use visadev instead. For more information on updating your code, see Version History.

    Description

    A visa object represents a connection to a VISA resource.

    Creation

    Syntax

    obj = visa('vendor','rsrcname')
    obj = visa('vendor','rsrcname',Name,Value)

    Description

    obj = visa('vendor','rsrcname') creates the VISA object obj with a resource name given by rsrcname for the vendor specified by vendor.

    You must first configure your VISA resources in the vendor's tool first, and then you create these VISA objects. Use instrhwinfo to find the commands to configure the objects:

    vinfo = instrhwinfo('visa','keysight');
vinfo.ObjectConstructorName

    If an invalid vendor or resource name is specified, an error is returned and the VISA object is not created. For a list of supported values for vendor see Supported Vendor and Resource Names.

    example

    obj = visa('vendor','rsrcname',Name,Value) specifies options using one or more name-value arguments in addition to the input arguments in previous syntax.

    Properties

    expand all

    Common Properties for All Interface Objects

    Byte order of instrument, specified as littleEndian or bigEndian. If ByteOrder is littleEndian, then the instrument stores the first byte in the first memory address. If ByteOrder is bigEndian, then the instrument stores the last byte in the first memory address.

    For example, suppose the hexadecimal value 4F52 is to be stored in instrument memory. Because this value consists of two bytes, 4F and 52, two memory locations are used. Using big-endian format, 4F is stored first in the lower storage address. Using little-endian format, 52 is stored first in the lower storage address.

    Note

    You should configure ByteOrder to the appropriate value for your instrument before performing a read or write operation. Refer to your instrument documentation for information about the order in which it stores bytes.

    You can set this property on interface objects such as TCP/IP or GPIB. In this example, a TCP/IP object, Tobj, is set to bigEndian by default, and you change it to littleEndian.

    Tobj.ByteOrder = 'littleEndian'

    The possible values are as follows.

    littleEndian

    The byte order of the instrument is little-endian.

    Default for serial, gpib, and visa objects.

    bigEndian

    The byte order of the instrument is big-endian.

    Default for tcpip and udp objects.

    Example

    This example shows how to set the byte order for a TCP/IP object. Create a TCP/IP object associated with the host 127.0.0.1 and port 4000. Change the byte order from the default of bigEndian to littleEndian.

    t = tcpip('127.0.0.1', 4000);
t.ByteOrder = 'littleEndian';

    This property is read-only.

    Number of bytes currently available to be read from the input buffer. The property value is continuously updated as the input buffer is filled, and is set to 0 after the fopen function is issued.

    You can make use of BytesAvailable only when reading data asynchronously. This is because when reading data synchronously, control is returned to the MATLAB® Command Window only after the input buffer is empty. Therefore, the BytesAvailable value is always 0.

    The BytesAvailable value can range from zero to the size of the input buffer. Use the InputBufferSize property to specify the size of the input buffer. Use the ValuesReceived property to return the total number of values read.

    Callback function to execute when a bytes-available event occurs. A bytes-available event occurs when the number of bytes specified by the BytesAvailableFcnCount property is available in the input buffer, or after a terminator is read, as determined by the BytesAvailableFcnMode property.

    Note

    A bytes-available event can be generated only for asynchronous read operations.

    If the RecordStatus property value is on, and a bytes-available event occurs, the record file records this information:

    • The event type as BytesAvailable

    • The time the event occurred using the format day-month-year hour:minute:second:millisecond

    Note

    You cannot use ASCII values larger than 127 characters. The function is limited to 127 binary characters.

    Example

    Create the serial port object s on a Windows® machine for a Tektronix® TDS 210 two-channel oscilloscope connected to the serial port COM1.

    s = serial('COM1');

    Configure s to execute the callback function instrcallback when 40 bytes are available in the input buffer.

    s.BytesAvailableFcnCount = 40;
s.BytesAvailableFcnMode = 'byte';
s.BytesAvailableFcn = @instrcallback;

    Connect s to the oscilloscope.

    fopen(s)

    Write the *IDN? command, which instructs the scope to return identification information. Because the default value for the ReadAsyncMode property is continuous, data is read as soon as it is available from the instrument.

    fprintf(s,'*IDN?')

    The resulting output from instrcallback is shown below.

    BytesAvailable event occurred at 18:33:35 for the object: 
Serial-COM1.

    56 bytes are read and instrcallback is called once. The resulting display is shown above.

    s.BytesAvailable
    ans =
    56

    Suppose you remove 25 bytes from the input buffer and issue the MEASUREMENT? command, which instructs the scope to return its measurement settings.

    out = fscanf(s,'%c',25);
fprintf(s,'MEASUREMENT?')

    The resulting output from instrcallback is shown below.

    BytesAvailable event occurred at 18:33:48 for the object: 
Serial-COM1.

BytesAvailable event occurred at 18:33:48 for the object: 
Serial-COM1.

    There are now 102 bytes in the input buffer, 31 of which are left over from the *IDN? command. instrcallback is called twice; once when 40 bytes are available and once when 80 bytes are available.

    s.BytesAvailable
    ans =
    102

    This property is read-only.

    Number of bytes that must be available in the input buffer before a bytes-available event is generated.

    Use the BytesAvailableFcnMode property to specify whether the bytes-available event occurs after a certain number of bytes are available or after a terminator is read.

    The bytes-available event executes the callback function specified for the BytesAvailableFcn property.

    You can configure BytesAvailableFcnCount only when the object is disconnected from the instrument. You disconnect an object with the fclose function. A disconnected object has a Status property value of closed.

    This property is read-only.

    For serial port, TCPIP, UDP, or VISA-serial objects, you can configure BytesAvailableFcnMode to be terminator or byte. For all other instrument objects, you can configure BytesAvailableFcnMode to be eosCharCode or byte.

    If BytesAvailableFcnMode is terminator, a bytes-available event occurs when the terminator specified by the Terminator property is read. If BytesAvailableFcnMode is eosCharCode, a bytes-available event occurs when the End-Of-String character specified by the EOSCharCode property is read. If BytesAvailableFcnMode is byte, a bytes-available event occurs when the number of bytes specified by the BytesAvailableFcnCount property is available.

    The bytes-available event executes the callback function specified for the BytesAvailableFcn property.

    You can configure BytesAvailableFcnMode only when the object is disconnected from the instrument. You disconnect an object with the fclose function. A disconnected object has a Status property value of closed.

    The possible values for Serial, TCPIP, UDP, and VISA-serial objects are as follows. The default value is enclosed in braces ({}).

    {terminator}

    A bytes-available event is generated when the terminator is reached.

    byte

    A bytes-available event is generated when the specified number of bytes available.

    The possible values for GPIB, VISA-GPIB, VISA-VXI, and VISA-GPIB-VXI objects are as follows. The default value is enclosed in braces ({}).

    {eosCharCode}

    A bytes-available event is generated when the EOS (End-Of-String) character is reached.

    byte

    A bytes-available event is generated when the specified number of bytes is available.

    This property is read-only.

    Number of bytes currently in the output buffer waiting to be written to the instrument. The property value is continuously updated as the output buffer is filled and emptied, and is set to 0 after the fopen function is issued.

    You can make use of BytesToOutput only when writing data asynchronously. This is because when writing data synchronously, control is returned to the MATLAB Command Window only after the output buffer is empty. Therefore, the BytesToOutput value is always 0.

    Use the ValuesSent property to return the total number of values written to the instrument.

    Note

    If you attempt to write out more data than can fit in the output buffer, then an error is returned and BytesToOutput is 0. You specify the size of the output buffer with the OutputBufferSize property.

    Callback function to execute when an error event occurs.

    Note

    An error event is generated only for asynchronous read and write operations.

    An error event is generated when a timeout occurs. A timeout occurs if a read or write operation does not successfully complete within the time specified by the Timeout property. An error event is not generated for configuration errors such as setting an invalid property value.

    If the RecordStatus property value is on, and an error event occurs, the record file records this information:

    • The event type as Error

    • The error message

    • The time the event occurred using the format day-month-year hour:minute:second:millisecond

    This property is read-only.

    Total number of bytes that can be stored in the software input buffer during a read operation.

    A read operation is terminated if the amount of data stored in the input buffer equals the InputBufferSize value. You can read text data with the fgetl, fgets, or fscanf functions. You can read binary data with the fread function.

    You can configure InputBufferSize only when the instrument object is disconnected from the instrument. You disconnect an object with the fclose function. A disconnected object has a Status property value of closed.

    If you configure InputBufferSize while there is data in the input buffer, then that data is flushed.

    Example

    This example shows how to set the input buffer size for a serial port object. The InputBufferSize property specifies the total number of bytes that can be stored in the software input buffer during a read operation. By default, InputBufferSize is 512 bytes. There could be a case when you would want to increase it to higher than the default size.

    Create a serial port object associated with the COM1 port. Set the input buffer size to 768 bytes.

    s = serial('COM1');
s.InputBufferSize = 768;

    Descriptive name for an instrument object.

    When you create an instrument object, a descriptive name is automatically generated and stored in Name. However, you can change this value at any time. As shown below, the components of Name reflect the instrument object type and the input arguments you supply to the creation function.

    Instrument Object

    Default Value of Name

    GPIB

    GPIB and BoardIndex-PrimaryAddress-SecondaryAddress

    Serial Port

    Serial and Port

    TCPIP

    TCPIP and RemoteHost

    UDP

    UDP and RemoteHost

    VISA-serial

    VISA-Serial and Port

    VISA-GPIB

    VISA-GPIB and BoardIndex-PrimaryAddress-SecondaryAddress

    VISA-VXI

    VISA-VXI and ChassisIndex-LogicalAddress

    VISA-GPIB-VXI

    VISA-GPIB-VXI and ChassisIndex-LogicalAddress

    VISA-TCPIP

    VISA-TCPIP and BoardIndex-RemoteHost-LANName

    VISA-RSIB

    VISA-RSIB and RemoteHost

    VISA-USB

    VISA-USB and BoardIndex-ManufacturerID- ModelCode-SerialNumber-InterfaceIndex

    If the secondary address is not specified when a GPIB or VISA-GPIB object is created, then Name does not include this component.

    If you change the value of any property that is a component of Name (for example, Port or PrimaryAddress), then Name is automatically updated to reflect those changes.

    Way for application developers to prevent end-user access to the instrument objects created by their application. When an object's ObjectVisibility property is set to off, instrfind and instrreset do not return or delete those objects.

    Objects that are not visible are still valid. If you have access to the object (for example, from within the file that creates it), then you can set and get its properties and pass it to any function that operates on instrument objects.

    The possible values are as follows. The default value is enclosed in braces ({}).

    {on}

    Object is visible to instrfind and instrreset

    off

    Object is not visible from the command line (except by instrfindall)

    Example

    The following statement creates an instrument object with its ObjectVisibility property set to off.

    g = gpib('mcc',0,2,'ObjectVisibility','off');
instrfind
    ans =
     []

    However, since the object is in the workspace (g), you can access it.

    g.ObjectVisibility

    ans =

	off

    This property is read-only.

    Total number of bytes that can be stored in the software output buffer during a write operation.

    An error occurs if the output buffer cannot hold all the data to be written. You write text data with the fprintf function. You write binary data with the fwrite function.

    You can configure OutputBufferSize only when the instrument object is disconnected from the instrument. You disconnect an object with the fclose function. A disconnected object has a Status property value of closed.

    Example

    This example shows how to set the output buffer size for a serial port object. The OutputBufferSize property specifies the maximum number of bytes that can be written to the instrument at once. By default, OutputBufferSize is 512 bytes. There could be a case when you would want to limit it to less than the default size.

    Create a serial port object associated with the COM1 port. Set the output buffer size to 256 bytes.

    s = serial('COM1');
s.OutputBufferSize = 256;

    Callback function to execute when an output-empty event occurs. An output-empty event is generated when the last byte is sent from the output buffer to the instrument.

    Note

    An output-empty event can be generated only for asynchronous write operations.

    If the RecordStatus property value is on, and an output-empty event occurs, the record file records this information:

    • The event type as OutputEmpty

    • The time the event occurred using the format day-month-year hour:minute:second:millisecond

    You can configure ReadAsyncMode to be continuous or manual. If ReadAsyncMode is continuous, the object continuously queries the instrument to determine if data is available to be read. If data is available, it is automatically read and stored in the input buffer. If issued, the readasync function is ignored.

    If ReadAsyncMode is manual, the object will not query the instrument to determine if data is available to be read. Instead, you must manually issue the readasync function to perform an asynchronous read operation. Because readasync checks for the terminator, this function can be slow. To increase speed, you should configure ReadAsyncMode to continuous.

    Note

    If the instrument is ready to transmit data, then it will do so regardless of the ReadAsyncMode value. Therefore, if ReadAsyncMode is manual and a read operation is not in progress, then data can be lost. To guarantee that all transmitted data is stored in the input buffer, you should configure ReadAsyncMode to continuous.

    You can determine the amount of data available in the input buffer with the BytesAvailable property. For either ReadAsyncMode value, you can bring data into the MATLAB workspace with one of the synchronous read functions such as fscanf, fgetl, fgets, or fread.

    This property is available only for Serial, TCPIP, UDP, and VISA-serial objects. The possible values are as follows. The default value is enclosed in braces ({}).

    {continuous}

    Continuously query the instrument to determine if data is available to be read.

    manual

    Manually read data from the instrument using the readasync function.

    You can configure RecordDetail to be compact or verbose. If RecordDetail is compact, the number of values written to the instrument, the number of values read from the instrument, the data type of the values, and event information are saved to the record file. If RecordDetail is verbose, the data transferred to and from the instrument is also saved to the record file.

    The verbose record file structure is shown in Recording Information to Disk.

    The possible values are as follows. The default value is enclosed in braces ({}).

    {compact}

    The number of values written to the instrument, the number of values read from the instrument, the data type of the values, and event information are saved to the record file.

    verbose

    The data written to the instrument, and the data read from the instrument are also saved to the record file.

    This property is read-only.

    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. A object that is not recording has a RecordStatus property value of off.

    You specify the record filename with the RecordName property. The indexed filename follows a prescribed set of rules. Refer to Specifying a File Name for a description of these rules.

    The possible values are as follows. The default value is enclosed in braces ({}).

    {overwrite}

    The record file is overwritten.

    append

    Data is appended to the record file.

    index

    Multiple record files are written, each with an indexed filename.

    Example

    Suppose you create the serial port object s on a Windows machine associated with the serial port COM1.

    s = serial('COM1');
fopen(s)

    Specify the record filename with the RecordName property, configure RecordMode to index, and initiate recording.

    s.RecordName = 'myrecord.txt';
s.RecordMode = 'index';
record(s)

    The record filename is automatically updated with an indexed filename after recording is turned off.

    record(s,'off')
s.RecordName

    ans =
myrecord01.txt

    Disconnect s from the instrument, and remove s from memory and from the MATLAB workspace.

    fclose(s)
delete(s)
clear s

    This property is read-only.

    Name of the record file. You can specify any value for RecordName — including a directory path — provided the filename is supported by your operating system.

    The MATLAB software supports any filename supported by your operating system. However, if you access the file through the MATLAB workspace, you might need to specify the filename using single quotes. For example, suppose you name the record file my record.txt. To type this file at the MATLAB Command Window, you must include the name in quotes.

    type('my record.txt')

    You can specify whether data and event information are saved to one disk file or to multiple disk files with the RecordMode property. If RecordMode is index, then the filename follows a prescribed set of rules. Refer to Specifying a File Name for a description of these rules.

    You can configure RecordName 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.

    This property is read-only.

    You can configure RecordStatus to be off or on with the record function. If RecordStatus is off, then data and event information are not saved to a record file. If RecordStatus is on, then data and event information are saved to the record file specified by RecordName.

    Use the record function to initiate or complete recording. RecordStatus is automatically configured to reflect the recording state.

    The possible values are as follows. The default value is enclosed in braces ({}).

    {off}

    Data and event information are not written to a record file

    on

    Data and event information are written to a record file

    This property is read-only.

    Status can be open or closed. If Status is closed, the object is not connected to the instrument. If Status is open, the object is connected to the instrument.

    Before you can write or read data, you must connect the object to the instrument with the fopen function. You use the fclose function to disconnect an object from the instrument.

    The possible values are as follows. The default value is enclosed in braces ({}).

    {closed}

    The object is not connected to the instrument.

    open

    The object is connected to the instrument.

    Value that uniquely identifies an instrument object.

    Tag is particularly useful when constructing programs that would otherwise need to define the instrument object as a global variable, or pass the object as an argument between callback routines.

    You can return the instrument object with the instrfind function by specifying the Tag property value.

    Example

    Suppose you create a serial port object on a Windows machine associated with the serial port COM1.

    s = serial('COM1');
fopen(s);

    You can assign s a unique label using Tag.

    s.Tag = 'MySerialObj'

    You can access s in the MATLAB workspace or in a file using the instrfind function and the Tag property value.

    s1 = instrfind('Tag','MySerialObj');

    For serial, TCPIP, UDP, and VISA-serial objects, you can configure Terminator to an integer value ranging from 0 to 127, to the equivalent ASCII character, or to empty (''). For example, to configure Terminator to a carriage return, you specify the value to be CR or 13. To configure Terminator to a line feed, you specify the value to be LF or 10. For serial port objects, you can also set Terminator to CR/LF or LF/CR. If Terminator is CR/LF, the terminator is a carriage return followed by a line feed. If Terminator is LF/CR, the terminator is a line feed followed by a carriage return. Note that there are no integer equivalents for these two values.

    Additionally, you can set Terminator to a 1-by-2 cell array. The first element of the cell is the read terminator and the second element of the cell array is the write terminator.

    When performing a write operation using the fprintf function, all occurrences of \n are replaced with the Terminator value. Note that %s\n is the default format for fprintf. A read operation with fgetl, fgets, or fscanf completes when the Terminator value is read. The terminator is ignored for binary operations.

    You can also use the terminator to generate a bytes-available event when the BytesAvailableFcnMode is set to terminator.

    An integer value ranging from 0 to 127, the equivalent ASCII character, or empty (''). For serial port objects, CR/LF and LF/CR are also accepted values. You specify different read and write terminators as a 1-by-2 cell array.

    Example

    This example shows how to set the terminator for a serial port object.

    Create a serial port object associated with the COM1 port. The oscilloscope you are connecting to over the serial port is configured to a baud rate of 9600 and a carriage return terminator, so set the serial port object to those values.

    s = serial('COM1');
s.Baudrate = 9600;
s.Terminator = 'CR';

    Maximum time (in seconds) to wait to complete a read or write operation.

    If a timeout occurs, then the read or write operation aborts. Additionally, if a timeout occurs during an asynchronous read or write operation, then:

    • An error event is generated.

    • The callback function specified for ErrorFcn is executed.

    Note

    Timeouts are rounded upwards to full seconds.

    You can configure the Timeout to be the maximum time in seconds to wait to complete a read or write operation for most interfaces.

    Example

    Create a GPIB object g associated with a National Instruments GPIB controller with board index 0, and an instrument with primary address 1.

    g = gpib('ni',0,1);

    You might want to configure the timeout value to a half minute to account for slow data transfer.

    g.Timeout = 30;

    Then when you connect to the instrument and do a data read and write, the timeout value of 30 seconds is used.

    Callback function to execute when a timer event occurs. A timer event occurs when the time specified by the TimerPeriod property passes. Time is measured relative to when the object is connected to the instrument with fopen.

    Note

    A timer event can be generated at any time during the instrument control session.

    If the RecordStatus property value is on, and a timer event occurs, the record file records this information:

    • The event type as Timer

    • The time the event occurred using the format day-month-year hour:minute:second:millisecond

    Some timer events might not be processed if your system is significantly slowed or if the TimerPeriod value is too small.

    Time, in seconds, that must pass before the callback function specified for TimerFcn is called. Time is measured relative to when the object is connected to the instrument with fopen.

    Some timer events might not be processed if your system is significantly slowed or if the TimerPeriod value is too small.

    The default value is 1 second. The minimum value is 0.01 second.

    This property is read-only.

    TransferStatus can be idle, read, write, or read&write. If TransferStatus is idle, then no asynchronous read or write operations are in progress. If TransferStatus is read, then an asynchronous read operation is in progress. If TransferStatus is write, then an asynchronous write operation is in progress. If TransferStatus is read&write, then both an asynchronous read and an asynchronous write operation are in progress.

    You can write data asynchronously using the fprintf or fwrite functions. You can read data asynchronously using the readasync function, or by configuring ReadAsyncMode to continuous (serial, TCPIP, UDP, and VISA-serial objects only). For detailed information about asynchronous read and write operations, refer to Communicating with Your Instrument.

    While readasync is executing for any instrument object, TransferStatus might indicate that data is being read even though data is not filling the input buffer. However, if ReadAsyncMode is continuous, TransferStatus indicates that data is being read only when data is actually filling the input buffer.

    The possible values are as follows. The default value is enclosed in braces ({}).

    {idle}

    No asynchronous operations are in progress.

    read

    An asynchronous read operation is in progress.

    write

    An asynchronous write operation is in progress.

    read&write

    Asynchronous read and write operations are in progress.

    This property is read-only.

    Type of the object. Type is automatically defined after the instrument object is created with the serial, gpib, or visa function.

    Using the instrfind function and the Type value, you can quickly identify instrument objects of a given type.

    gpib

    The object type is GPIB.

    serial

    The object type is serial port.

    tcpip

    The object type is TCPIP.

    udp

    The object type is UDP.

    visa-gpib

    The object type is VISA-GPIB.

    visa-vxi

    The object type is VISA-VXI.

    visa-gpib-vxi

    The object type is VISA-GPIB-VXI.

    visa-serial

    The object type is VISA-serial.

    The value is automatically determined when the instrument object is created.

    Example

    Create a serial port object on a Windows machine associated with the serial port COM1. The value of the Type property is serial, which is the object class.

    s = serial('COM1');
s.Type

    ans =
serial

    Data to store that you want to associate with an instrument object. The object does not use this data directly, but you can access it using dot notation.

    Example

    Create the serial port object on a Windows machine associated with the serial port COM1.

    s = serial('COM1');

    You can associate data with s by storing it in UserData.

    coeff.a = 1.0;
coeff.b = -1.25;
s.UserData = coeff

    This property is read-only.

    Total number of values read from the instrument. The value is updated after each successful read operation, and is set to 0 after the fopen function is issued. If the terminator is read from the instrument, then this value is reflected by ValuesReceived.

    If you are reading data asynchronously, use the BytesAvailable property to return the number of bytes currently available in the input buffer.

    When performing a read operation, the received data is represented by values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.

    Suppose you create a serial port object on a Windows machine associated with the serial port COM1.

    s = serial('COM1');
fopen(s)

    If you write the RS232? command, and then read back the response using fscanf, ValuesReceived is 17 because the instrument is configured to send the LF terminator.

    fprintf(s,'RS232?')
out = fscanf(s)
    out =
9600;0;0;NONE;LF

    s.ValuesReceived

    ans =
    17

    This property is read-only.

    Total number of values written to the instrument. The value is updated after each successful write operation, and is set to 0 after the fopen function is issued. If you are writing the terminator, then ValuesSent reflects this value.

    If you are writing data asynchronously, use the BytesToOutput property to return the number of bytes currently in the output buffer.

    When performing a write operation, the transmitted data is represented by values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.

    Example

    Create a serial port object on a Windows machine associated with the serial port COM1.

    s = serial('COM1');
fopen(s)

    If you write the *IDN? command using the fprintf function, then ValuesSent is 6 because the default data format is %s\n, and the terminator was written.

    fprintf(s,'*IDN?')
s.ValuesSent

    ans =
    6

    VISA Properties

    This property is read-only.

    Alias for the resource name for a VISA instrument. When you create a VISA object, you can specify either the resource name for a VISA instrument or an alias for the resource name. If an alias is specified, Alias is automatically assigned the value specified in the VISA function. If a resource name is specified and the resource name has an alias, Alias is updated with the alias value. If the resource name does not have an alias, Alias is an empty character vector.

    You set the alias for a resource name using vendor-supplied tools. You do not set an alias in the MATLAB workspace. When you create the VISA object in the MATLAB workspace, the Alias property of the object takes on the value of the resource name alias. You do not directly set the value of this property.

    NI™ Measurement & Automation Explorer (NI MAX) is one example of a graphical interface tool for setting a VISA alias in NI-VISA. In this tool, select Tools > NI-VISA > Alias Editor to edit, add, or clear aliases. When you have your aliases defined, you can use them in the MATLAB workspace to access your resources.

    This property is read-only.

    Index number of the VXI chassis associated with your instrument.

    When you create a VISA-VXI or VISA-GPIB-VXI object, ChassisIndex is automatically assigned the value specified in the visa function. For both object types, the Name and RsrcName properties are automatically updated to reflect the ChassisIndex value.

    You can configure ChassisIndex only when the object is disconnected from the instrument. You disconnect a connected object with the fclose function. A disconnected object has a Status property value of closed.

    This property is available only for VISA-VXI and VISA-GPIB-VXI objects.

    Example

    Suppose you create a VISA-GPIB-VXI object associated with chassis 0 and logical address 32.

    v = visa('keysight','GPIB-VXI0::32::INSTR');

    The ChassisIndex, Name, and RsrcName properties reflect the VXI chassis index number.

    v.ChassisIndex
    ans = 
    [0]    
    v.Name
    ans = 
    'VISA-GPIB-VXI0-32' 
    v.RsrcName
    ans = 
    'GPIB-VXI0::32::INSTR'

    This property is read-only.

    USB interface number.

    The Name and RsrcName properties are automatically updated to reflect the InterfaceIndex value.

    You can configure InterfaceIndex only when the object is disconnected from the instrument. You disconnect a connected object with the fclose function. A disconnected object has a Status property value of closed.

    This property is available only for VISA-USB objects.

    You configure InterruptFcn to execute a callback function when an interrupt event occurs. An interrupt event is generated when a VXI bus signal or a VXI bus interrupt is received from the instrument.

    Note

    An interrupt event can be generated at any time during the instrument control session.

    If the RecordStatus property value is on, and an interrupt event occurs, the record file records

    • The event type as Interrupt

    • The time the event occurred using the format day-month-year hour:minute:second:millisecond

    This property is available only for VISA-VXI objects.

    LAN (Local Area Network) device name.

    The Name and RsrcName properties are automatically updated to reflect the LANName value.

    You can configure LANName only when the object is disconnected from the instrument. You disconnect a connected object with the fclose function. A disconnected object has a Status property value of closed.

    This property is available only for VISA-TCPIP objects.

    This property is read-only.

    Logical address of the VXI instrument. You must include the logical address as part of the resource name during object creation using the visa function.

    The Name and RsrcName properties are automatically updated to reflect the LogicalAddress value.

    You can configure LogicalAddress only when the object is disconnected from the instrument. You disconnect a connected object with the fclose function. A disconnected object has a Status property value of closed.

    This property is available only for VISA-VXI and VISA-GPIB-VXI objects.

    This property is read-only.

    Manufacturer ID of the USB instrument.

    The Name and RsrcName properties are automatically updated to reflect the ManufacturerID value.

    You can configure ManufacturerID only when the object is disconnected from the instrument. You disconnect a connected object with the fclose function. A disconnected object has a Status property value of closed.

    This property is available only for VISA-USB objects.

    This property is read-only.

    Base address of the mapped memory used for low level read and write operations.

    The memory address is returned as a character vector representing a hexadecimal value. For example, if the mapped memory base is 200000, then MappedMemoryBase returns 200000H. If no memory is mapped, MappedMemoryBase is 0H.

    Use the memmap function to map the specified amount of memory in the specified address space (A16, A24, or A32) with the specified offset. Use the memunmap function to unmap the memory space.

    This property is available only for VISA-VXI and VISA-GPIB-VXI objects.

    This property is read-only.

    Amount of memory mapped for low-level read and write operations.

    Use the memmap function to map the specified amount of memory in the specified address space (A16, A24, or A32) with the specified offset. Use the memunmap function to unmap the memory space.

    This property is available only for VISA-VXI and VISA-GPIB-VXI objects.

    Example

    Create the VISA-VXI object vv associated with a VXI chassis with index 0, and a Keysight® E1432A digitizer with logical address 130.

    vv = visa('keysight','VXI0::130::INSTR');
fopen(vv)

    Map 16 bytes in the A16 address space with no offset, and then return the size of the mapped memory.

    memmap(vv,'A16',0,16)
vv.MappedMemorySize
    ans =
     16

    This property is read-only.

    Base address of the A24 or A32 space. The value is returned as a character vector representing a hexadecimal value.

    All VXI instruments have an A16 address space that is 16 bits wide. There are also 24- and 32-bit wide address spaces known as A24 and A32. Some instruments require the additional memory associated with the A24 or A32 address space when the 64 bytes of A16 space are insufficient for performing necessary functions. A bit in the A16 address space is set allowing the instrument to recognize commands to its A24 or A32 space.

    An instrument cannot use both the A24 and A32 address space. The address space is given by the MemorySpace property. If MemorySpace is A16, then MemoryBase is 0H.

    This property is available only for VISA-VXI and VISA-GPIB-VXI objects.

    Example

    Create the VISA-VXI object vv associated with a VXI chassis with index 0, and a Keysight E1432A digitizer with logical address 130.

    vv = visa('keysight','VXI0::130::INSTR');
fopen(vv)

    The MemorySpace property indicates that the A24 memory space is supported.

    vv.MemorySpace
    ans =
A16/A24

    The base address of the A24 space is:

    vv.MemoryBase
    ans =
'200000H'

    You can configure MemoryIncrement to be block or FIFO. If MemoryIncrement is block, the memread and memwrite functions increment the offset after every read and write operation, and data is transferred from or to consecutive memory elements. If MemoryIncrement is FIFO, the memread and memwrite functions do not increment the VXI register offset, and data is always read from or written to the same memory element.

    This property is available only for VISA-VXI and VISA-GPIB-VXI objects. The possible values are as follows. The default value is enclosed in braces ({}).

    {block}

    Increment the VXI register offset.

    FIFO

    Do not increment the VXI register offset.

    Example

    Create the VISA-VXI object v associated with a VXI chassis with index 0, and an instrument with logical address 8.

    v = visa('ni','VXI0::8::INSTR');
fopen(v)

    Configure the hardware for a FIFO read and write operation.

    v.MemoryIncrement = 'FIFO'

    Write two values to the VXI register starting at offset 16. Because MemoryIncrement is FIFO, the VXI register offset does not change and both values are written to offset 16.

    memwrite(v,[1984 2000],16,'uint32','A16')

    Read the value at offset 16. The value returned is the second value written with the memwrite function.

    memread(v,16,'uint32')
    ans =
2000

    Read two values starting at offset 16. Note that both values are read at offset 16.

    memread(v,16,'uint32','A16',2);
    ans =
2000
2000

    Configure the hardware for a block read and write operation.

    v.MemoryIncrement = 'block'

    Write two values to the VXI register starting at offset 16. The first value is written to offset 16 and the second value is written to offset 20 because a uint32 value consists of four bytes.

    memwrite(v,[1984 2000],16,'uint32','A16')

    Read the value at offset 16. The value returned is the first value written with the memwrite function.

    memread(v,16,'uint32')
    ans =
1984

    Read two values starting at offset 16. The first value is read at offset 16 and the second value is read at offset 20.

    memread(v,16,'uint32','A16',2);
    ans =
1984
2000

    This property is read-only.

    Size of the memory requested by the instrument in the A24 or A32 address space.

    Some instruments use the A24 or A32 address space when the 64 bytes of A16 space are not enough for performing necessary functions. An instrument cannot use both the A24 and A32 address space. The address space is given by the MemorySpace property. If MemorySpace is A16, then MemorySize is 0.

    This property is available only for VISA-VXI and VISA-GPIB-VXI objects.

    Example

    Create the VISA-VXI object vv associated with a VXI chassis with index 0, and a Keysight E1432A digitizer with logical address 130.

    vv = visa('keysight','VXI0::130::INSTR');
fopen(vv)

    The MemorySpace property indicates that the A24 memory space is supported.

    vv.MemorySpace
    ans =
A16/A24

    The size of the A24 space is:

    vv.MemorySize
    ans =
262144

    This property is read-only.

    Address space requested by the instrument. MemorySpace can be A16, A16/A24, or A16/A32. If MemorySpace is A16, the instrument uses only the A16 address space. If MemorySpace is A16/A24, the instrument uses the A16 and A24 address space. If MemorySpace is A16/A32, the instrument uses the A16 and A32 address space.

    All VXI instruments have an A16 address space that is 16 bits wide. There are also 24- and 32-bit wide address spaces known as A24 and A32, respectively. Some instruments use this memory when the 64 bytes of A16 space are not enough for performing necessary functions. An instrument cannot use both the A24 and A32 address space.

    The size of the memory is given by the MemorySize property. The base address of the memory is given by the MemoryBase property.

    This property is available only for VISA-VXI and VISA-GPIB-VXI objects. The possible values are as follows. The default value is enclosed in braces ({}).

    {A16}

    The instrument uses the A16 address space.

    A16/A24

    The instrument uses the A16 and A24 address space.

    A16/A32

    The instrument uses the A16 and A32 address space.

    Example

    Create the VISA-VXI object vv associated with a VXI chassis with index 0, and a Keysight E1432A digitizer with logical address 130.

    vv = visa('keysight','VXI0::130::INSTR');
fopen(vv)

    Return the memory space supported by the instrument.

    vv.MemorySpace
    ans =
A16/A24

    This value indicates that the instrument supports A24 memory space in addition to the A16 memory space.

    This property is read-only.

    Model code of the USB instrument.

    The Name and RsrcName properties are automatically updated to reflect the ModelCode value.

    You can configure ModelCode only when the object is disconnected from the instrument. You disconnect a connected object with the fclose function. A disconnected object has a Status property value of closed.

    This property is available only for VISA-USB objects.

    This property is read-only.

    RsrcName indicates the resource name for a VISA instrument. When you create a VISA object, RsrcName is automatically assigned the value specified in the visa function.

    The resource name is a symbolic name for the instrument. The resource name you supply to visa depends on the interface and has the format shown below. The components in brackets are optional and have a default value of 0, except port_number, which has a default value of 1.

    Interface

    Resource Name

    VXI

    VXI[chassis]::VXI_logical_address::INSTR

    GPIB-VXI

    GPIB-VXI[chassis]::VXI_logical_address::INSTR

    GPIB

    GPIB[board]::primary_address[::secondary_address]::INSTR

    TCPIP

    TCPIP[board]::remote_host[::lan_device_name]::INSTR

    RSIB

    RSIB::remote_host::INSTR

    Serial

    ASRL[port_number]::INSTR

    USB

    USB[board]::manid::model_code::serial_No[::interface_No]::INSTR

    If you change the BoardIndex, ChassisIndex, InterfaceIndex, LANName, LogicalAddress, ManufacturerID, ModelCode, Port, PrimaryAddress, RemoteHost, SecondaryAddress, or SerialNumber property value, RsrcName is automatically updated to reflect the change.

    This property is available only for VISA-GPIB, VISA-VXI, VISA-GPIB-VXI, and VISA-serial objects.

    Example

    To create a VISA-GPIB object associated with a GPIB controller with board index 0 and an instrument with primary address 1, you supply the following resource name to the visa function.

    vg = visa('ni','GPIB0::1::INSTR');

    To create a VISA-VXI object associated with a VXI chassis with index 0 and an instrument with logical address 130, you supply the following resource name to the visa function.

    vv = visa('keysight','VXI0::130::INSTR');

    To create a VISA-GPIB-VXI object associated with a VXI chassis with index 0 and an instrument with logical address 80, you supply the following resource name to the visa function.

    vgv = visa('keysight','GPIB-VXI0::80::INSTR');

    To create a VISA-serial object associated with the COM1 serial port, you supply the following resource name to the visa function.

    vs = visa('ni','ASRL1::INSTR');

    This property is read-only.

    Index of the USB instrument on the USB hub.

    The Name and RsrcName properties are automatically updated to reflect the SerialNumber value.

    You can configure SerialNumber only when the object is disconnected from the instrument. You disconnect a connected object with the fclose function. A disconnected object has a Status property value of closed.

    This property is available only for VISA-USB objects.

    This property is read-only.

    Physical slot of the VXI instrument. Slot can be any value between 0 and 12.

    The property value is defined when the instrument object is connected.

    This property is available only for VISA-VXI and VISA-GPIB-VXI objects.

    Execute a callback function when a trigger event occurs. A trigger event is generated when a trigger occurs in software, or on one of the VXI hardware trigger lines. You configure the trigger type with the TriggerType property.

    Note

    A trigger event can be generated at any time during the instrument control session.

    If the RecordStatus property value is on, and a trigger event occurs, the record file records:

    • The event type as Trigger.

    • The time the event occurred using the format day-month-year hour:minute:second:millisecond.

    This property is available only for VISA-VXI objects.

    You can configure TriggerLine to be TTL0 through TTL7, ECL0, or ECL1. You can use only one trigger line at a time.

    You can specify the trigger type with the TriggerType property. When TriggerType is hardware, the line triggered is given by the TriggerLine value. When the TriggerType is software, the TriggerLine value is ignored.

    You execute a trigger for a VISA-VXI object with the trigger function.

    This property is available only for VISA-VXI objects.

    You can configure TriggerType to be software or hardware. If TriggerType is software, then a software trigger is used. If TriggerType is hardware, then the trigger line specified by the TriggerLine property is used.

    You execute a trigger for a VISA-VXI object with the trigger function.

    This property is available only for VISA-VXI objects. The possible values are as follows. The default value is enclosed in braces ({}).

    {hardware}

    A hardware trigger is used.

    software

    A software trigger is used.

    Serial and VISA-Serial Properties

    Bit transmit rate in bits per second. The transferred bits include the start bit, the data bits, the parity bit (if used), and the stop bits. However, only the data bits are stored.

    The baud rate is the rate at which information is transferred in a communication channel. In the serial port context, "9600 baud" means that the serial port is capable of transferring a maximum of 9600 bits per second. If the information unit is one baud (one bit), then the bit rate and the baud rate are identical. If one baud is given as 10 bits, (for example, eight data bits plus two framing bits), the bit rate is still 9600 but the baud rate is 9600/10, or 960. You always configure BaudRate as bits per second. Therefore, in the above example, set BaudRate to 9600.

    Note

    Both the computer and the instrument must be configured to the same baud rate before you can successfully read or write data.

    Your system computes the acceptable rates by taking the baud base, which is determined by your serial port, and dividing it by a positive whole number divisor. The system will try to find the best match by modifying the divisor. For example, if: 

    baud base = 115200 bits per second
divisors = 1,2,3,4,5….
Possible BaudRates = 115200, 57600, 38400, 28800, 23040….

    Your system may further limit the available baud rates to conform to specific conventions or standards. In the above example, for instance, 23040 bits/sec may not be available on all systems.

    Example

    This example shows how to set the baud rate for a serial port object.

    Create a serial port object associated with the COM1 port. The oscilloscope you are connecting to over the serial port is configured to a baud rate of 115200 and a carriage return terminator, so set the serial port object to those values.

    s = serial('COM1');
s.Baudrate = 115200;
s.Terminator = 'CR';

    You can configure DataBits to be 5, 6, 7, or 8. Data is transmitted as a series of five, six, seven, or eight bits with the least significant bit sent first. At least seven data bits are required to transmit ASCII characters. Eight bits are required to transmit binary data. Five and six bit data formats are used for specialized communication equipment.

    Note

    Both the computer and the instrument must be configured to transmit the same number of data bits.

    In addition to the data bits, the serial data format consists of a start bit, one or two stop bits, and possibly a parity bit. You specify the number of stop bits with the StopBits property, and the type of parity checking with the Parity property.

    You can configure DataTerminalReady to be on or off. If DataTerminalReady is on, the Data Terminal Ready (DTR) pin is asserted. If DataTerminalReady is off, the DTR pin is unasserted.

    In normal usage, the DTR and Data Set Ready (DSR) pins work together, and are used to signal if instruments are connected and powered. However, there is nothing in the RS-232 or the RS-485 standard that states the DTR pin must be used in any specific way. For example, DTR and DSR might be used for handshaking. You should refer to your instrument documentation to determine its specific pin behavior.

    You can return the value of the DSR pin with the PinStatus property. Handshaking is described in Control Pins.

    The possible values are as follows. The default value is enclosed in braces ({}).

    {on}

    The DTR pin is asserted.

    off

    The DTR pin is unasserted.

    You can configure FlowControl to be none, hardware, or software. If FlowControl is none, then data flow control (handshaking) is not used. If FlowControl is hardware, then hardware handshaking is used to control data flow. If FlowControl is software, then software handshaking is used to control data flow.

    Hardware handshaking typically utilizes the Request to Send (RTS) and Clear to Send (CTS) pins to control data flow. Software handshaking uses control characters (Xon and Xoff) to control data flow. To learn more about hardware and software handshaking, refer to Use Serial Port Control Pins.

    You can return the value of the CTS pin with the PinStatus property. You can specify the value of the RTS pin with the RequestToSend property. However, if FlowControl is hardware, and you specify a value for RequestToSend, then that value might not be honored.

    If you set the FlowControl property to hardware on a serial object, and a hardware connection is not detected, the fwrite and the fprintf functions will return an error message. This occurs if a device is not connected, or a connected device is not asserting that is ready to receive data. Check your remote device's status and flow control settings to see if hardware flow control is causing errors in MATLAB.

    Note

    If you want to check to see if the device is asserting that it is ready to receive data, set the FlowControl to none. Once you connect to the device check the PinStatus structure for ClearToSend. If ClearToSend is off, there is a problem on the remote device side. If ClearToSend is on, there is a hardware FlowControl device prepared to receive data and you can execute fprintf and fwrite.

    Although you might be able to configure your instrument for both hardware handshaking and software handshaking at the same time, the toolbox does not support this behavior.

    The possible values are as follows. The default value is enclosed in braces ({}).

    {none}

    No flow control is used.

    hardware

    Hardware flow control is used.

    software

    Software flow control is used.

    You can configure Parity to be none, odd, even, mark, or space. If Parity is none, parity checking is not performed and the parity bit is not transmitted. If Parity is odd, the number of mark bits (1s) in the data is counted, and the parity bit is asserted or unasserted to obtain an odd number of mark bits. If Parity is even, the number of mark bits in the data is counted, and the parity bit is asserted or unasserted to obtain an even number of mark bits. If Parity is mark, the parity bit is asserted. If Parity is space, the parity bit is unasserted.

    Parity checking can detect errors of one bit only. An error in two bits might cause the data to have a seemingly valid parity, when in fact it is incorrect. To learn more about parity checking, refer to Parity Bit.

    In addition to the parity bit, the serial data format consists of a start bit, between five and eight data bits, and one or two stop bits. You specify the number of data bits with the DataBits property, and the number of stop bits with the StopBits property.

    The possible values are as follows. The default value is enclosed in braces ({}).

    {none}

    No parity checking

    odd

    Odd parity checking

    even

    Even parity checking

    mark

    Mark parity checking

    space

    Space parity checking

    Example

    This example shows how to set the parity for a serial port object.

    Create a serial port object associated with the COM1 port. The default setting for Parity is none, so if you want to use parity checking, change the value to the type you want to use, for example, odd.

    s = serial('COM1');
s.Parity = 'odd';

    This property is read-only.

    PinStatus is a structure array that contains the fields CarrierDetect, ClearToSend, DataSetReady and RingIndicator. These fields indicate the state of the Carrier Detect (CD), Clear to Send (CTS), Data Set Ready (DSR) and Ring Indicator (RI) pins, respectively. Refer to Control Pins to learn more about these pins.

    PinStatus can be on or off for any of these fields. A value of on indicates the associated pin is asserted. A value of off indicates the associated pin is unasserted. For serial port objects, a pin status event occurs when any of these pins changes its state. A pin status event executes the file specified by PinStatusFcn.

    In normal usage, the Data Terminal Ready (DTR) and DSR pins work together, while the Request To Send (RTS) and CTS pins work together. You can specify the state of the DTR pin with the DataTerminalReady property. You can specify the state of the RTS pin with the RequestToSend property.

    Refer to Connect Two Modems for an example that uses PinStatus.

    The possible values are as follows. The default value is instrument dependent.

    off

    The associated pin is asserted

    on

    The associated pin is asserted

    This property is read-only.

    You configure Port to be the name of a serial port on your platform. Port specifies the physical port associated with the object and the instrument.

    When you create a serial port or VISA-serial object, Port is automatically assigned the port name specified for the serial or visa function.

    You can configure Port only when the object is disconnected from the instrument. You disconnect an object with the fclose function. A disconnected object has a Status property value of closed.

    The value is determined when the instrument object is created.

    Example

    Suppose you create a serial port and VISA-serial object associated with serial port COM1. 

    s = serial('COM1') 
vs = visa('ni','ASRL1::INSTR')

    The Port property values are given below.

    [s vs].Port
    ans = 
    'COM1'
    'ASRL1'

    You can configure RequestToSend to be on or off. If RequestToSend is on, the Request to Send (RTS) pin is asserted. If RequestToSend is off, the RTS pin is unasserted.

    In normal usage, the RTS and Clear to Send (CTS) pins work together, and are used as standard handshaking pins for data transfer. In this case, RTS and CTS are automatically managed by the DTE and DCE. However, there is nothing in the RS-232, or the RS-484 standard that states the RTS pin must to be used in any specific way. Therefore, if you manually configure the RequestToSend value, it is probably for nonstandard operations.

    If your instrument does not use hardware handshaking in the standard way, and you need to manually configure RequestToSend, then you should configure the FlowControl property to none. Otherwise, the RequestToSend value that you specify might not be honored. Refer to your instrument documentation to determine its specific pin behavior.

    You can return the value of the CTS pin with the PinStatus property. Handshaking is described in Control Pins.

    The possible values are as follows. The default value is enclosed in braces ({}).

    {on}

    The RTS pin is asserted.

    off

    The RTS pin is unasserted.

    You can configure StopBits to be 1, 1.5, or 2 for serial port objects, or 1 or 2 for VISA-serial objects. If StopBits is 1, one stop bit is used to indicate the end of data transmission. If StopBits is 2, two stop bits are used to indicate the end of data transmission. If StopBits is 1.5, the stop bit is transferred for 150% of the normal time used to transfer one bit.

    Note

    Both the computer and the instrument must be configured to transmit the same number of stop bits.

    In addition to the stop bits, the serial data format consists of a start bit, between five and eight data bits, and possibly a parity bit. You specify the number of data bits with the DataBits property, and the type of parity checking with the Parity property.

    The possible values for Serial Port objects are as follows. The default value is enclosed in braces ({}).

    {1}

    One stop bit is transmitted to indicate the end of a byte.

    1.5

    The stop bit is transferred for 150% of the normal time used to transfer one bit.

    2

    Two stop bits are transmitted to indicate the end of a byte.

    The possible values for VISA-serial objects are as follows. The default value is enclosed in braces ({}).

    {1}

    One stop bit is transmitted to indicate the end of a byte.

    2

    Two stop bits are transmitted to indicate the end of a byte

    Example

    This example shows how to set the StopBits for a serial port object.

    Create a serial port object associated with the COM1 port. The default setting for StopBits is 1 for serial port objects. Change the value to use two stop bits to indicate the end of data transmission.

    s = serial('COM1');
s.StopBits = 2;

    GPIB and VISA Properties

    This property is read-only.

    Index number of the GPIB board, USB board, or TCP/IP board associated with your instrument. When you create a GPIB, VISA-GPIB, VISA-GPIB-VXI, VISA-TCPIP, or VISA-USB object, BoardIndex is automatically assigned the value specified in the gpib or visa function.

    For GPIB objects, the Name property is automatically updated to reflect the BoardIndex value. For VISA-GPIB, VISA-GPIB-VXI, VISA-TCPIP, or VISA-USB objects, the Name and RsrcName properties are automatically updated to reflect the BoardIndex value.

    You can configure BoardIndex only when the object is disconnected from the instrument. You disconnect a connected object with the fclose function. A disconnected object has a Status property value of closed.

    Example

    Suppose you create a VISA-GPIB object associated with board 4, primary address 1, and secondary address 8.

    vg = visa('keysight','GPIB4::1::8::INSTR');

    The BoardIndex, Name, and RsrcName properties reflect the GPIB board index number.

    vg.BoardIndex
    ans = 
    [4]    
    vg.Name
    ans = 
    'VISA-GPIB4-1-8'    
    vg.RsrcName
    ans = 
		'GPIB4::1::8::INSTR'

    You can configure EOIMode to be on or off. If EOIMode is on, the End Or Identify (EOI) line is asserted at the end of a write operation. If EOIMode is off, the EOI line is not asserted at the end of a write operation. EOIMode applies to both binary and text write operations. This property is for GPIB, VISA-GPIB, VISA-VXI, and VISA-GPIB-VXI objects.

    The possible values are as follows. The default value is enclosed in braces ({}).

    {on}

    The EOI line is asserted at the end of a write operation.

    off

    The EOI line is not asserted at the end of a write operation.

    You can configure EOSCharCode to an integer value ranging from 0 to 255, or to the equivalent ASCII character. For example, to configure EOSCharCode to a carriage return, you specify the value to be CR or 13. This property is for GPIB, VISA-GPIB, VISA-VXI, VISA-GPIB-VXI, and VISA-USB objects.

    EOSCharCode replaces \n wherever it appears in the ASCII command sent to the instrument. Note that %s\n is the default format for the fprintf function.

    For many practical applications, you will configure both EOSCharCode and the EOSMode property. EOSMode specifies when the EOS character is used. If EOSMode is write or read&write (writing is enabled), the EOI line is asserted every time the EOSCharCode value is written to the instrument. If EOSMode is read or read&write (reading is enabled), then the read operation might terminate when the EOSCharCode value is detected. For GPIB objects, the CompareBits property specifies the number of bits that must match the EOS character to complete a read or write operation.

    To see how EOSCharCode and EOSMode work together, refer to EOSMode.

    An integer value ranging from 0 to 255 or the equivalent ASCII character. The default value is LF, which corresponds to a line feed.

    For GPIB, VISA-GPIB, VISA-VXI, VISA-GPIB-VXI, and VISA-USB objects, you can configure EOSMode to be none, read, write, or read&write.

    If EOSMode is none, the End-Of-String (EOS) character is ignored. If EOSMode is read, the EOS character is used to terminate a read operation. If EOSMode is write, the EOS character is appended to the ASCII command being written whenever \n is encountered. When the EOS character is written to the instrument, the End Or Identify (EOI) line is asserted. If EOSMode is read&write, the EOS character is used in both read and write operations.

    The EOS character is specified by the EOSCharCode property. For GPIB objects, the CompareBits property specifies the number of bits that must match the EOS character to complete a read operation, or to assert the EOI line.

    The possible values are as follows. The default value is enclosed in braces ({}).

    {none}

    The EOS character is ignored.

    read

    The EOS character is used for each read operation.

    write

    The EOS character is used for each write operation.

    read&write

    The EOS character is used for each read and write operation.

    Rules for Completing a Read Operation

    For any EOSMode value, the read operation completes when:

    • The EOI line is asserted.

    • Specified number of values is read.

    • A timeout occurs.

    Additionally, if EOSMode is read or read&write (reading is enabled), then the read operation can complete when the EOSCharCode property value is detected.

    Rules for Completing a Write Operation

    Regardless of the EOSMode value, a write operation completes when:

    • The specified number of values is written.

    • A timeout occurs.

    Additionally, if EOSMode is write or read&write, the EOI line is asserted each time the EOSCharCode property value is written to the instrument.

    Example

    Suppose you input a nominal voltage signal of 2.0 volts into a function generator, and read back the voltage value using fscanf.

    g = gpib('ni',0,1); 
fopen(g) 
fprintf(g,'Volt?') 
out = fscanf(g) 
    out = 
+2.00000E+00

    The EOSMode and EOSCharCode properties are configured to terminate the read operation when an E character is encountered.

    g.EOSMode = 'read'
g.EOSCharCode = 'E' 
fprintf(g,'Volt?')
out = fscanf(g)
    out = 
+2.00000

    This property is read-only.

    For GPIB, VISA-GPIB, and VISA-GPIB-VXI objects, you configure PrimaryAddress to be the GPIB primary address associated with your instrument. The primary address can range from 0 to 30, and you must specify it during object creation using the gpib or visa function. For VISA-GPIB-VXI objects, PrimaryAddress is read-only, and the value is returned automatically by the VISA interface after the object is connected to the instrument with the fopen function.

    For GPIB and VISA-GPIB objects, the Name property is automatically updated to reflect the PrimaryAddress value. For VISA-GPIB objects, the RsrcName property is automatically updated to reflect the PrimaryAddress value.

    You can configure PrimaryAddress only when the GPIB or VISA-GPIB object is disconnected from the instrument. You disconnect a connected object with the fclose function. A disconnected object has a Status property value of closed.

    PrimaryAddress can range from 0 to 30. The value is determined when the instrument object is created.

    Example

    This example creates a VISA-GPIB object associated with board 0, primary address 1, and secondary address 8, and then returns the primary address.

    vg = visa('keysight','GPIB0::1::8::INSTR');
vg.PrimaryAddress
    ans =
     1

    This property is read-only.

    For GPIB, VISA-GPIB, and VISA-GPIB-VXI objects, you configure SecondaryAddress to be the GPIB secondary address associated with your instrument. You can initially specify the secondary address during object creation using the gpib or visa function. For VISA-GPIB-VXI objects, SecondaryAddress is read-only, and the value is returned automatically by the VISA interface after the object is connected to the instrument with the fopen function.

    For GPIB objects, SecondaryAddress can range from 96 to 126, or it can be 0 indicating that no secondary address is used. For VISA-GPIB objects, SecondaryAddress can range from 0 to 30. If your instrument does not have a secondary address, then SecondaryAddress is 0.

    For GPIB and VISA-GPIB objects, the Name property is automatically updated to reflect the SecondaryAddress value. For VISA-GPIB objects, the RsrcName property is automatically updated to reflect the SecondaryAddress value.

    You can configure SecondaryAddress only when the GPIB or VISA-GPIB object is disconnected from the instrument. You disconnect a connected object with the fclose function. A disconnected object has a Status property value of closed.

    For GPIB objects, SecondaryAddress can range from 96 to 126, or it can be 0. For VISA-GPIB objects, SecondaryAddress can range from 0 to 30. The default value is 0.

    Example

    This example creates a VISA-GPIB object associated with board 0, primary address 1, and secondary address 8, and then returns the secondary address.

    vg = visa('keysight','GPIB0::1::8::INSTR');
vg.SecondaryAddress
    ans =
     8

    TCP/IP, UDP, and VISA Properties

    Remote host name or IP dotted decimal address. An example dotted decimal address is 144.212.100.10.

    For TCPIP objects, you can configure RemoteHost only when the object is disconnected from the hardware. You disconnect a connected object with the fclose function. A disconnected object has a Status property value of closed.

    For UDP objects, you can configure RemoteHost at any time. If the object is open, a warning is issued if the remote address is invalid.

    Examples

    collapse all

    Create a VISA-serial object connected to serial port COM1 using National Instruments™ VISA interface.

    vs = visa('ni','ASRL1::INSTR');

    Create a VISA-GPIB object connected to board 0 with primary address 1 and secondary address 30 using Keysight VISA interface.

    vg = visa('keysight','GPIB0::1::30::INSTR');

    Create a VISA-VXI object connected to a VXI instrument located at logical address 8 in the first VXI chassis.

    vv = visa('keysight','VXI0::8::INSTR');

    Create a VISA-GPIB-VXI object connected to a GPIB-VXI instrument located at logical address 72 in the second VXI chassis.

    vgv = visa('keysight','GPIB-VXI1::72::INSTR');

    Create a VISA-RSIB object connected to an instrument configured with IP address 192.168.1.33.

    vr = visa('ni', 'RSIB::192.168.1.33::INSTR')

    Create a VISA-TCPIP object connected to an instrument configured with IP address 216.148.60.170.

    vt = visa('tek', 'TCPIP::216.148.60.170::INSTR')

    Create a VISA-USB object connected to a USB instrument with manufacturer ID 0x1234, model code 125, and serial number A22-5.

    vu = visa('keysight', 'USB::0x1234::125::A22-5::INSTR')

    Tips

    At any time, you can use the instrhelp function to view a complete listing of properties and functions associated with VISA objects.

    instrhelp visa

    You can specify the property names and property values using any format supported by the set function. For example, you can use property name/property value cell array pairs. Additionally, you can specify property names without regard to case, and you can make use of property name completion. For example, the following commands are all valid.

    v = visa('ni','GPIB0::1::INSTR','SecondaryAddress', 96);
v = visa('ni','GPIB0::1::INSTR','secondaryaddress', 96);
v = visa('ni','GPIB0::1::INSTR','SECOND', 96);

    Before you can communicate with the instrument, it must be connected to obj with the fopen function. A connected VISA object has a Status property value of open. An error is returned if you attempt a read or write operation while obj is not connected to the instrument. You cannot connect multiple VISA objects to the same instrument.

    When you create a VISA-GPIB object, these properties are automatically configured:

    • Type is given by visa-gpib.

    • Name is given by concatenating VISA-GPIB with the board index, the primary address, and the secondary address.

    • BoardIndex, PrimaryAddress, SecondaryAddress, and RsrcName are given by the values specified during object creation.

    When you create a VISA-GPIB-VXI object, these properties are automatically configured:

    • Type is given by visa-gpib-vxi.

    • Name is given by concatenating VISA-GPIB-VXI with the chassis index and the logical address specified in the visa function.

    • ChassisIndex, LogicalAddress, and RsrcName are given by the values specified during object creation.

    • BoardIndex, PrimaryAddress, and SecondaryAddress are given by the visa driver after the object is connected to the instrument with fopen.

    When you create a VISA-RSIB object, these properties are automatically configured:

    • Type is given by visa-rsib.

    • Name is given by concatenating VISA-RSIB with the remote host specified in the visa function.

    • RemoteHost and RsrcName are given by the values specified during object creation.

    When you create a VISA-serial object, these properties are automatically configured:

    • Type is given by visa-serial.

    • Name is given by concatenating VISA-Serial with the port specified in the visa function.

    • Port and RsrcName are given by the values specified during object creation.

    When you create a VISA-TCPIP object, these properties are automatically configured:

    • Type is given by visa-tcpip.

    • Name is given by concatenating VISA-TCPIP with the board index, remote host, and LAN device name specified in the visa function.

    • BoardIndex, RemoteHost, LANNAme, and RsrcName are given by the values specified during object creation.

    When you create a VISA-USB object, these properties are automatically configured:

    • Type is given by visa-usb.

    • Name is given by concatenating VISA-USB with the board index, manufacturer ID, model code, serial number, and interface number specified in the visa function.

    • BoardIndex, ManufacturerID, ModelCode, SerialNumber, InterfaceIndex, and RsrcName are given by the values specified during object creation.

    When you create a VISA-VXI object, these properties are automatically configured:

    • Type is given by visa-vxi.

    • Name is given by concatenating VISA-VXI with the chassis index and the logical address specified in the visa function.

    • ChassisIndex, LogicalAddress, and RsrcName are given by the values specified during object creation.

    Version History

    Introduced before R2006a

    expand all

    See Also

    Topics