This tutorial explores ASCII read and write operations with a VISA object.
The information obtained for this tutorial was prerecorded. Therefore, you do not need an actual instrument to learn about VISA ASCII read and write operations.
The instruments used include an Agilent E1406A command module in VXI slot 0 and an Agilent E1441A instrument in VXI slot 1.
The HP E1406A is a GPIB controller and it is connected to a GPIB board. The HP E1441A is a function/arbitrary waveform generator. The GPIB controller will communicate with the HP E1441A function generator over the VXI backplane.
The VISA object supports seven interfaces:
This tutorial explores ASCII read and write operations using a VISA-GPIB-VXI object. However, ASCII read and write operations for VISA-GPIB, VISA-VXI, VISA-GPIB-VXI, VISA-TCPIP, and VISA-USB objects are identical to each other. Therefore, you can use the same commands. The only difference is the resource name specified in the VISA constructor.
ASCII read and write operations for the VISA-serial object are identical to ASCII read and write operations for the serial port object. Therefore, to learn how to perform ASCII read and write operations for the VISA-serial object, you should refer to the Serial Port ASCII Read/Write tutorial.
ASCII read and write operations for the VISA-RSIB object are identical to the ASCII read and write operations for the VISA-GPIB, VISA-VXI, VISA-GPIB-VXI, VISA-TCPIP, and VISA-USB objects, except the VISA-RSIB object does not support the EOSCharCode and EOSMode properties.
These functions are used when reading and writing text:
FPRINTF - Write text to instrument.
FSCANF - Read data from instrument and format as
text.These properties are associated with reading and writing text:
ValuesReceived - Specifies the total number of values
read from the instrument.
ValuesSent - Specifies the total number of values
sent to the instrument.
InputBufferSize - Specifies the total number of bytes
that can be queued in the input buffer
at one time.
OutputBufferSize - Specifies the total number of bytes
that can be queued in the output buffer
at one time.
EOSMode - Configures the End-Of-String termination
mode.
EOSCharCode - Specifies the End-Of-String terminator.
EOIMode - Enables or disables the assertion of
the EOI line at the end of a write
operation.To begin, create a VISA-GPIB-VXI object. The HP E1441A instrument is configured with a logical address of 80 and is in the first chassis.
>> v = visa('agilent', 'GPIB-VXI0::80::INSTR')VISA-GPIB-VXI Object Using AGILENT Adaptor: VISA-GPIB-VXI0-80
Communication Address
ChassisIndex: 0
LogicalAddress: 80 Communication State
Status: closed
RecordStatus: off Read/Write State
TransferStatus: idle
BytesAvailable: 0
ValuesReceived: 0
ValuesSent: 0Before you can perform a read or write operation, you must connect the VISA-GPIB-VXI object to the instrument with the FOPEN function. If the object was successfully connected, its Status property is automatically configured to open.
>> fopen(v) >> v
VISA-GPIB-VXI Object Using AGILENT Adaptor: VISA-GPIB-VXI0-80
Communication Address
ChassisIndex: 0
LogicalAddress: 80 Communication State
Status: open
RecordStatus: off Read/Write State
TransferStatus: idle
BytesAvailable: 0
ValuesReceived: 0
ValuesSent: 0You use the FPRINTF function to write ASCII data to the instrument. For example, the 'Volt 2' command changes the signal's peak-to-peak voltage to 4 volts.
>> fprintf(v, 'Volt 2')
By default, FPRINTF operates in synchronous mode. This means that the function blocks until one of the following occurs:
By default, FPRINTF writes ASCII data using the %s\n format. You can also specify the format of the command written by providing a third input argument to FPRINTF. The accepted format conversion characters include: d, i, o, u, x, X, f, e, E, g, G, c, and s.
For example,
>> fprintf(v, '%s', 'Volt 3')
The OutputBufferSize property specifies the maximum number of bytes that can be written to the instrument at once. By default, OutputBufferSize is 512.
>> get(v, 'OutputBufferSize')
ans =
512
If the command specified in FPRINTF contains more than 512 bytes, an error is returned and no data is written to the instrument.
By default, the End or Identify (EOI) line is asserted when the last byte is written to the instrument. This behavior is controlled by the EOIMode property. When EOIMode is set to on, the EOI line is asserted when the last byte is written to the instrument. When EOIMode is set to off, the EOI line is not asserted when the last byte is written to the instrument.
All occurrences of \n in the command written to the instrument are replaced with the EOSCharCode property value if EOSMode is set to write or read&write.
The ValuesSent property is updated by the number of values written to the instrument. Note that by default EOSMode is set to none. Therefore, EOSCharCode is not sent as the last byte of the write.
>> fprintf(v, 'Volt 2') >> get(v, 'ValuesSent')
ans =
18
The FSCANF function reads ASCII data from the instrument. For example, the 'Volt?' command returns the signal's peak-to-peak voltage.
>> fprintf(v, 'Volt?') >> data = fscanf(v)
data =
+2.00000E+00
FSCANF blocks until one of the following occurs:
By default, FSCANF reads ASCII data using the %c format. You can also specify the format of the data read by providing a second input argument to FSCANF. The accepted format conversion characters include: d, i, o, u, x, X, f, e, E, g, G, c, and s.
For example, the following command will return the voltage as a double:
>> fprintf(v, 'Volt?') >> data = fscanf(v, '%g')
data =
2
>> isnumeric(data)
ans =
1
The InputBufferSize property specifies the maximum number of bytes that you can read from the instrument. By default, InputBufferSize is 512.
>> get(v, 'InputBufferSize')
ans =
512
The ValuesReceived property is updated by the number of values read from the instrument. Note the last value received is a linefeed.
>> fprintf(v, 'Volt?') >> data = fscanf(v)
data =
+2.00000E+00
>> get(v, 'ValuesReceived')
ans =
39
To terminate the data transfer based on receiving EOSCharCode, you should set the EOSMode property to read or read&write and the EOSCharCode property to the ASCII code for which the read operation should terminate. For example, if you set EOSMode to read and EOSCharCode to 10, then one of the ways that the read terminates is when the linefeed character is received.
Configure the VISA-GPIB-VXI object to terminate the read operation when the 'E' character is received.
The first read terminates when the 'E' character is received.
>> set(v, 'EOSMode', 'read')
>> set(v, 'EOSCharCode', double('E'))
>> fprintf(v, 'Volt?')
>> data = fscanf(v)data =
+2.00000E
If you perform a second read operation, it terminates when the EOI line is asserted.
>> data = fscanf(v)
data =
+00
If you are finished with the VISA-GPIB-VXI object, disconnect it from the instrument, remove it from memory, and remove it from the workspace.
>> fclose(v) >> delete(v) >> clear v