Writing and Reading Data

Rules for Completing Write and Read Operations

Completing Write Operations

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.

Completing Read Operations

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.

Writing and Reading Text Data

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.

Reading and Writing Binary Data

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
```

Viewing the Bitmap Data

To view the bitmap data, you should follow these steps:

Open a disk file.
Write the data to the disk file.
Close the disk file.
Read the data using the imread function.
Scale and display the data using the imagesc function.

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.

Parsing Input Data Using scanstr

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
```

Understanding EOI and EOS

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
```

Instrument Control Toolbox Documentation

Support

Try MATLAB, Simulink, and Other Products

Get trial now