A write operation using fprintf
or fwrite
completes
when one of these conditions is satisfied:
The specified data is written.
The time specified by the Timeout
property
passes.
Additionally, you can stop an asynchronous write operation at
any time with the stopasync
function.
An instrument determines if a write operation is complete based
on the EOSMode
, EOIMode
,
and EOSCharCode
property values. If EOSMode
is
configured to either write
or read&write
,
each occurrence of \n
in a text command is replaced
with the End-Of-String (EOS) character specified by the EOSCharCode
value.
Therefore, when you use the default fprintf
format
of %s\n
, all text commands written to the instrument
will end with that value. The default EOSCharCode
value
is LF
, which corresponds to the line feed character.
The EOS character required by your instrument will be described in
its documentation.
If EOIMode
is on
, then
the End Or Identify (EOI) line is asserted when the last byte is written
to the instrument. The last byte can be part of a binary data stream
or a text data stream. If EOSMode
is configured
to either write
or read&write
,
then the last byte written is the EOSCharCode
value
and the EOI line is asserted when the instrument receives this byte.
A read operation with fgetl
, fgets
, fread
, fscanf
,
or readasync
completes when one of these conditions
is satisfied:
The EOI line is asserted.
The terminator specified by the EOSCharCode
property
is read. This can occur only when the EOSMode
property
is configured to either read
or read&write
.
The time specified by the Timeout
property
passes.
The specified number of values is read (fread
, fscanf
,
and readasync
only).
The input buffer is filled (if the number of values is not specified).
In addition to these rules, you can stop an asynchronous read
operation at any time with the stopasync
function.
These functions are used when reading and writing text:
Function | Purpose |
---|---|
fprintf | Write text to an instrument. |
fscanf | Read data from an instrument and format as text. |
These properties are associated with reading and writing text:
Property | Purpose |
---|---|
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 mode at the end of a write operation. |
Note
To get a list of options you can use on a function, press the Tab key after entering a function on the MATLAB® command line. The list expands, and you can scroll to choose a property or value. For information about using this advanced tab completion feature, see Using Tab Completion for Functions.
The following example illustrates how to communicate with a GPIB instrument by writing and reading text data.
The instrument is a Tektronix® TDS 210 two-channel oscilloscope. Therefore, many of the commands used are specific to this instrument. A sine wave is input into channel 2 of the oscilloscope, and your job is to measure the peak-to-peak voltage of the input signal:
Create an instrument
object — Create the 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);
Connect to the instrument —
Connect g
to the oscilloscope, and return the default
values for the EOSMode
and EOIMode
properties.
fopen(g) get(g,{'EOSMode','EOIMode'}) ans = 'none' 'on'
Using these property values, write operations complete when the last byte is written to the instrument, and read operations complete when the EOI line is asserted by the instrument.
Write and read data —
Write the *IDN?
command to the instrument using fprintf
, and then read back the result
of the command using fscanf
.
fprintf(g,'*IDN?') idn = fscanf(g) idn = TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04
Determine the measurement source. Possible measurement sources include channel 1 and channel 2 of the oscilloscope.
fprintf(g,'MEASUREMENT:IMMED:SOURCE?') source = fscanf(g) source = CH1
The scope is configured to return a measurement from channel 1. Because the input signal is connected to channel 2, you must configure the instrument to return a measurement from this channel.
fprintf(g,'MEASUREMENT:IMMED:SOURCE CH2') fprintf(g,'MEASUREMENT:IMMED:SOURCE?') source = fscanf(g) source = CH2
You can now configure
the scope to return the peak-to-peak voltage, request the value of
this measurement, and then return the voltage value to the IEEE® software
using fscanf
.
fprintf(g,'MEASUREMENT:MEAS1:TYPE PK2PK') fprintf(g,'MEASUREMENT:MEAS1:VALUE?') ptop = fscanf(g) ptop = 2.0199999809E0
Disconnect and clean
up — When you no longer need g
,
you should disconnect it from the instrument, and remove it from memory
and from the IEEE workspace.
fclose(g) delete(g) clear g
ASCII Write Properties
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.
The EOI line can also be asserted when a terminator is written
to the instrument. The terminator is defined by the EOSCharCode
property.
When EOSMode
is configured to write
or read&write
,
the EOI line is asserted when the EOSCharCode
property
value 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
.
These functions are used when reading and writing binary data:
Function | Purpose |
---|---|
fread | Read binary data from an instrument. |
fwrite | Write binary data to an instrument. |
These properties are associated with reading and writing binary data:
Property | Purpose |
---|---|
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. |
Note
To get a list of options you can use on a function, press the Tab key after entering a function on the MATLAB command line. The list expands, and you can scroll to choose a property or value. For information about using this advanced tab completion feature, see Using Tab Completion for Functions.
You use the fwrite
function to write binary
data to an instrument.
By default, the fwrite
function operates
in a synchronous mode. This means that fwrite
blocks
the MATLAB command line until one of the following occurs:
All the data is written
A timeout occurs as specified by the Timeout
property
By default the fwrite
function writes binary
data using the uchar
precision. However, other
precisions can also be used. For a list of supported precisions, see
the function reference page for fwrite
.
You use the fread
function to read binary
data from the instrument.
The fread
function blocks the MATLAB command
line until one of the following occurs:
A timeout occurs as specified by the Timeout
property
The input buffer is filled
The specified number of values is read
The EOI line is asserted
The terminator is received as specified by the EOSCharCode
property
(if defined)
By default the fread
function reads binary
data using the uchar
precision. However, other
precisions can also be used. For a list of supported precisions, see
the function reference page for fread
.
Note
When performing a read or write operation, you should think
of the received data in terms of values rather than bytes. A value
consists of one or more bytes. For example, one uint32
value
consists of four bytes.
The following example illustrates how you can download the TDS 210 oscilloscope screen display to the IEEE software. The screen display data is transferred to the IEEE software and saved to disk using the Windows® bitmap format. This data provides a permanent record of your work, and is an easy way to document important signal and scope parameters:
Create an instrument
object — Create the 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);
Configure property values — Configure the input buffer to accept a reasonably large number of bytes, and configure the timeout value to two minutes to account for slow data transfer.
g.InputBufferSize = 50000; g.Timeout = 120;
Connect
to the instrument — Connect g
to
the oscilloscope.
fopen(g)
Write and read data — Configure the scope to transfer the screen display as a bitmap.
fprintf(g,'HARDCOPY:PORT GPIB') fprintf(g,'HARDCOPY:FORMAT BMP') fprintf(g,'HARDCOPY START')
Asynchronously transfer the data from the instrument to the input buffer.
readasync(g)
Wait until the read operation completes, and then transfer the data to the IEEE workspace as unsigned 8-bit integers.
g.TransferStatus ans = idle out = fread(g,g.BytesAvailable,'uint8');
Disconnect and clean
up — When you no longer need g
,
you should disconnect it from the instrument, and remove it from memory
and from the IEEE workspace.
fclose(g) delete(g) clear g
To view the bitmap data, you should follow these steps:
Note that the MATLAB software file I/O versions of the fopen
, fwrite
,
and fclose
functions are
used.
fid = fopen('test1.bmp','w'); fwrite(fid,out,'uint8'); fclose(fid) a = imread('test1.bmp','bmp');
Display the image.
imagesc(a)
Use a gray colormap since the instrument only generates grayscale images.
c = colormap(gray); colormap(flipud(c));
The resulting bitmap image is shown below.
This example illustrates how to use the scanstr
function to parse data that
you read from a Tektronix TDS 210 oscilloscope. scanstr
is
particularly useful when you want to parse a string into one or more
cell array elements, where each element is determined to be either
a double or a character vector:
Create an instrument
object — Create the 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);
Connect to the instrument —
Connect g
to the oscilloscope.
fopen(g)
Write and read data — Return identification information to separate elements of a cell array using the default delimiters.
fprintf(g,'*IDN?'); idn = scanstr(g) idn = 'TEKTRONIX' 'TDS 210' [ 0] 'CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04'
Disconnect and clean
up — When you no longer need g
,
you should disconnect it from the instrument, and remove it from memory
and from the MATLAB workspace.
fclose(g) delete(g) clear g
This example illustrates how the EOI line and the EOS character
are used to complete read and write operations, and how the EOIMode
, EOSMode
,
and EOSCharCode
properties are related to each
other. In most cases, you can successfully communicate with your instrument
by accepting the default values for these properties.
The default value for EOIMode
is on
,
which means that the EOI line is asserted when the last byte is written
to the instrument. The default value for EOSMode
is none
,
which means that the EOSCharCode
value is not written
to the instrument, and read operations will not complete when the EOSCharCode
value
is read. Therefore, when you use the default values for EOIMode
and EOSMode
,
Write operations complete when the last byte is written to the instrument.
Read operations complete when the EOI line is asserted by the instrument.
Create an instrument
object — Create the 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);
Connect to the instrument —
Connect g
to the oscilloscope.
fopen(g)
Write and read data —
Configure g
so that the EOI line is not asserted
after the last byte is written to the instrument, and the EOS character
is used to complete write operations. The default format for fprintf
is %s\n
,
where \n
is replaced by the EOS character as given
by EOSCharCode
.
g.EOIMode = 'off'; g.EOSMode = 'write'; fprintf(g,'*IDN?') out = fscanf(g) out = TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04
Although EOSMode
is configured
so that read operations will not complete after receiving the EOS
character, the preceding read operation succeeded because the EOI
line was asserted.
Now configure g
so that the EOS character
is not used to complete read or write operations. Because the EOI
line is not asserted and the EOS character is not written, the instrument
cannot interpret the *IDN?
command and a timeout
occurs.
g.EOSMode = 'none'; fprintf(g,'*IDN?') out = fscanf(g) Warning: GPIB: NI: An I/O operation has been canceled mostly likely due to a timeout.
Now configure g
so
that the read operation terminates after the “X” character
is read. The EOIMode
property is configured to on
so
that the EOI line is asserted after the last byte is written. The EOSMode
property
is configured to read
so that the read operation
completes when the EOSCharCode
value is read.
g.EOIMode = 'on'; g.EOSMode = 'read'; g.EOSCharCode = 'X'; fprintf(g,'*IDN?') out = fscanf(g) out = TEKTRONIX
Note that
the rest of the identification string remains in the instrument's
hardware buffer. If you do not want to return this data during the
next read operation, you should clear it from the instrument buffer
with the clrdevice
function.
clrdevice(g)
Disconnect and clean
up — When you no longer need g
,
you should disconnect it from the instrument, and remove it from memory
and from the MATLAB workspace.
fclose(g) delete(g) clear g