gpib
(To be removed) Create GPIB object
gpib
will be removed in a future release. Use visadev
instead. For more information on updating your code, see Compatibility Considerations.
Description
A gpib
object represents a connection to GPIB
hardware.
Creation
Syntax
Description
obj = gpib('vendor',boardindex,primaryaddress)
creates the GPIB
object obj
associated with the board specified by
boardindex
, and the instrument specified by
primaryaddress
. The GPIB hardware is supplied by
vendor
. The following vendors are supported.
keysight
— Keysight® (formerly Agilent Technologies®) hardwareics
— ICS Electronics™ hardwaremcc
— Measurement Computing™ hardwareni
— National Instruments™ hardwareadlink
— ADLINK Technology hardware
obj = gpib('vendor',boardindex,primaryaddress,Name,Value)
specifies options using one or more name-value arguments in addition to the input
arguments in previous syntax. If an invalid property name or property value is specified,
an error is returned and obj
is not created.
Properties
Common Properties for All Interface Objects
ByteOrder
— Byte order of instrument
littleEndian
| bigEndian
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.
| The byte order of the instrument is little-endian. Default for |
| The byte order of the instrument is big-endian. Default for |
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';
BytesAvailable
— Number of bytes available in input buffer
0
(default) | double
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.
BytesAvailableFcn
— Callback function to execute when bytes-available event occurs
callback function
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
BytesAvailableFcnCount
— Number of bytes that must be available in input buffer to generate bytes-available event
48
(default) | double
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
.
BytesAvailableFcnMode
— Whether bytes-available event is generated after specified number of bytes are available in input buffer or after terminator is read
terminator
| byte
| eosCharCode
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 ({}
).
| A bytes-available event is generated when the terminator is reached. |
| 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 ({}
).
| A bytes-available event is generated when the EOS (End-Of-String) character is reached. |
| A bytes-available event is generated when the specified number of bytes is available. |
BytesToOutput
— Number of bytes currently in output buffer
0 (default) | double
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.
ErrorFcn
— Callback function to execute when error event occurs
callback function
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
InputBufferSize
— Size of input buffer in bytes
512
(default) | double
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;
Name
— Descriptive name for instrument object
character vector
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 |
|
Serial Port |
|
TCPIP |
|
UDP |
|
VISA-serial |
|
VISA-GPIB |
|
VISA-VXI |
|
VISA-GPIB-VXI |
|
VISA-TCPIP |
|
VISA-RSIB |
|
VISA-USB |
|
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.
ObjectVisibility
— Access to instrument object
on
(default) | off
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 ({}
).
| Object is visible to |
| Object is not visible from the command line (except by |
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
OutputBufferSize
— Size of output buffer in bytes
512
(default) | double
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;
OutputEmptyFcn
— Callback function to execute when output buffer is empty
callback function
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
ReadAsyncMode
— Whether asynchronous read operation is continuous or manual
continuous
(default) | manual
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 ({}
).
| Continuously query the instrument to determine if data is available to be read. |
| Manually read data from the instrument using the |
RecordDetail
— Amount of information saved to record file
compact
(default) | verbose
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 ({}
).
| 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. |
| The data written to the instrument, and the data read from the instrument are also saved to the record file. |
RecordMode
— Whether data and event information are saved to one or to multiple record files
overwrite
(default) | append
| index
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 ({}
).
| The record file is overwritten. |
| Data is appended to the record file. |
| 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
RecordName
— Name of record file
record.txt
(default) | character vector
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
.
RecordStatus
— Status of whether data and event information are saved to record file
off
(default) | on
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 ({}
).
| Data and event information are not written to a record file |
| Data and event information are written to a record file |
Status
— Status of whether object is connected to instrument
closed
(default) | open
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 ({}
).
| The object is not connected to the instrument. |
| The object is connected to the instrument. |
Tag
— Label to associate with instrument object
character vector
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');
Terminator
— Terminator character
ASCII value
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';
Timeout
— Waiting time to complete read or write operation
10
(default) | double
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.
TimerFcn
— Callback function to execute when predefined period passes
callback function
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.
TimerPeriod
— Period between timer events
1
(default) | double
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.
TransferStatus
— Status of whether asynchronous read or write operation is in progress
idle
(default) | read
| write
| read&write
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 ({}
).
| No asynchronous operations are in progress. |
| An asynchronous read operation is in progress. |
| An asynchronous write operation is in progress. |
| Asynchronous read and write operations are in progress. |
Type
— Instrument object type
character vector
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.
| The object type is GPIB. |
| The object type is serial port. |
| The object type is TCPIP. |
| The object type is UDP. |
| The object type is VISA-GPIB. |
| The object type is VISA-VXI. |
| The object type is VISA-GPIB-VXI. |
| 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
UserData
— Data to associate with instrument object
any type
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
ValuesReceived
— Total number of values read from instrument
0
(default) | double
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
ValuesSent
— Total number of values written to instrument
0 (default) | double
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
GPIB Properties
BusManagementStatus
— State of GPIB bus management lines
structure
This property is read-only.
Structure array that contains the fields Attention
,
InterfaceClear
, RemoteEnable
,
ServiceRequest
, and EndOrIdentify
. These fields
indicate the state of the Attention (ATN), Interface Clear (IFC), Remote Enable (REN),
Service Request (SRQ) and End Or Identify (EOI) GPIB lines.
BusManagementStatus
can be on
or
off
for any of these fields. If
BusManagementStatus
is on
, the associated line
is asserted. If BusManagementStatus
is off
, the
associated line is unasserted.
The default value is instrument dependent.
Example
Create the GPIB object g
associated with a National Instruments board, and connect g
to a Tektronix TDS 210 oscilloscope.
g = gpib('ni',0,0);
fopen(g)
Write the *STB?
command, which queries the instrument's status
byte register, and then return the state of the bus management lines with the
BusManagementStatus
property.
fprintf(g,'*STB?')
g.BusManagementStatus
ans = Attention: 'off' InterfaceClear: 'off' RemoteEnable: 'on' ServiceRequest: 'off' EndOrIdentify: 'on'
REN is asserted because the system controller placed the scope in the remote enable mode, while EOI is asserted to mark the end of the command.
Now read the result of the *STB?
command, and return the state
of the bus management lines.
out = fscanf(g)
out = 0
g.busmanagementstatus
ans = Attention: 'off' InterfaceClear: 'off' RemoteEnable: 'on' ServiceRequest: 'off' EndOrIdentify: 'off'
fclose(g)
delete(g)
clear g
CompareBits
— Number of bits that must match EOS character to complete read operation or to assert EOI line
8
(default) | 7
You can configure CompareBits
to be 7
or
8
. If CompareBits
is 7
, the
read operation completes when a byte that matches the low seven bits of the
End-Of-String (EOS) character is received. The End Or Identify (EOI) line is asserted
when a byte that matches the low seven bits of the EOS character is written. If
CompareBits
is 8
, the read operation completes
when a byte that matches all eight bits of the EOS character is received. The EOI line
is asserted when a byte that matches all eight bits of the EOS character is written.
You can specify the EOS character with the EOSCharCode
property. You can specify when the EOS character is used (read operation, write
operation, or both) with the EOSMode
property.
The possible values are as follows. The default value is enclosed in braces
({}
).
| Compare all eight EOS bits. |
| Compare the lower seven EOS bits. |
HandshakeStatus
— State of GPIB handshake lines
structure
Structure array that contains the fields DataValid
,
NotDataAccepted
, and NotReadyForData
. These
fields indicate the state of the Data Valid (DAV), Not Data Accepted (NDAC) and Not
Ready For Data (NRFD) GPIB lines, respectively.
HandshakeStatus
can be on
or
off
for any of these fields. A value of on
indicates the associated line is asserted. A value of off
indicates
the associated line is unasserted.
The default value is instrument dependent.
GPIB and VISA Properties
BoardIndex
— Index number of interface board
double
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'
EOIMode
— Whether EOI line is asserted at end of write operation
on
(default) | off
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 ({}
).
| The EOI line is asserted at the end of a write operation. |
| The EOI line is not asserted at the end of a write operation. |
EOSCharCode
— EOS character
ASCII value
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.
EOSMode
— When EOS character is written or read
none
(default) | read
| write
| read&write
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 ({}
).
| The EOS character is ignored. |
| The EOS character is used for each read operation. |
| The EOS character is used for each write operation. |
| 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
PrimaryAddress
— Primary address of GPIB instrument
double
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
SecondaryAddress
— Secondary address of GPIB instrument
double
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
Examples
Create GPIB Object
This example creates the GPIB object g1
associated with a
National Instruments board at index 0 with primary address 1, and then connects
g1
to the instrument.
g1 = gpib('ni',0,1);
fopen(g1)
The Type
, Name
,
BoardIndex
, and PrimaryAddress
properties
are automatically configured.
g1.Type
ans = gpib
g1.Name
ans = GPIB0-1
g1.BoardIndex
ans = 0
g1.PrimaryAddress
ans = 1
To specify the secondary address during object creation,
g2 = gpib('ni',0,1,'SecondaryAddress',96);
Tips
At any time, you can use the instrhelp
function to view a complete
listing of properties and functions associated with GPIB objects.
instrhelp gpib
When you create a GPIB object, these property value are automatically configured:
Type
is given bygpib
.Name
is given by concatenatingGPIB
with the board index and the primary address specified in thegpib
function. If the secondary address is specified, then this value is also used inName
.BoardIndex
andPrimaryAddress
are given by the values supplied to thegpib
function.
Note
You do not use the GPIB board primary address in the GPIB object constructor syntax. You use the board index, and the instrument address.
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, these
commands are all valid:
g = gpib('ni',0,1,'SecondaryAddress',96); g = gpib('ni',0,1,'secondaryaddress',96); g = gpib('ni',0,1,'SECOND',96);
Before you can communicate with the instrument, it must be connected to
obj
with the fopen
function. A connected GPIB object has
a Status
property value of open
. An error is returned
if you attempt to perform a read or write operation while obj
is not
connected to the instrument.
You cannot connect multiple GPIB objects to the same instrument. A GPIB instrument is uniquely identified by its board index, primary address, and secondary address.
Version History
Introduced before R2006aR2022a: Warns
gpib
will be removed in a future release. Use visadev
instead.
This example shows how to connect to a GPIB instrument using the recommended functionality.
Functionality | Use This Instead |
---|---|
g = gpib('ni',0,1,'SecondaryAddress',0); fopen(g) |
v = visadev('GPIB0::1::0::INSTR'); |
The recommended interface has additional capabilities and improved performance. See Transition Your Code to VISA-GPIB Interface for more information about using the recommended functionality.
Commande MATLAB
Vous avez cliqué sur un lien qui correspond à cette commande MATLAB :
Pour exécuter la commande, saisissez-la dans la fenêtre de commande de MATLAB. Les navigateurs web ne supportent pas les commandes MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)