Write and Read Data

Before Performing Write or Read Operations

Communicating with your instrument involves writing and reading data. For example, you might write a text command to a function generator that queries its peak-to-peak voltage, and then read back the voltage value as a double-precision array.

Before performing a write or read operation, consider the following:

The Instrument Control Toolbox™ automatically manages the data transferred between the MATLAB^® workspace and the instrument. For many common applications, you can ignore the buffering and data flow process. However, if you are transferring a large number of values or debugging your application, you might need to be aware of how this process works.
For many instruments, writing text data means writing string commands that change instrument settings, prepare the instrument to return data or status information, and so on. You can use the writeline function to write text data and the write terminator value is automatically appended to the data being written.
Writing binary data means writing numerical values to the instrument such as calibration or waveform data. You can use the write function to write numeric or text data.
You can also write binary data as a block of values. Use the writebinblock function to write a binblock of data.
Read operations in the Instrument Control Toolbox are synchronous. A synchronous operation blocks access to the command line until the read operation completes execution.
- When you call read, the function suspends MATLAB execution until the specified number of values is read or a timeout occurs.
- When you call readline, the function suspends MATLAB execution until a terminator is read or a timeout occurs.
- When you call readbinblock, the function suspends MATLAB execution until the number of values specified in the binblock is read or a timeout occurs.

Writing Data

Functions Associated with Writing Data

Function Name	Description
`write`	Write binary data to the instrument
`writeline`	Write a line of ASCII data to the instrument
`writebinblock`	Write one binblock of data to the instrument
`writeread`	Write command and read response

Note

The writebinblock function is not available for the udpport interface. The writeread function is not available for the tcpserver and udpport interfaces.

Properties Associated with Writing Data

Property Name	Description
`Timeout`	Allowed time to complete write and read operations
`Terminator`	Terminator character for writing and reading text data
`NumBytesWritten`	Total number of bytes written

You can modify the value of Timeout using dot notation and Terminator using the configureTerminator function. NumBytesWritten is a read-only property.

Writing Text Data Versus Writing Binary Data

For many instruments, writing text data means writing string commands that change instrument settings, prepare the instrument to return data or status information, and so on. Writing binary data means writing numerical values to the instrument such as calibration or waveform data.

You can write text data with the writeline function. The writeline function formats the data as a string and automatically appends the terminator. You can write binary data with the write function. The write function writes data as uint8 by default, but you can specify other data types using a name-value argument.

The following example illustrates writing text data and binary data to a Tektronix^® TDS 210 oscilloscope. The text data consists of string commands, while the binary data is a waveform that is to be downloaded to the scope and stored in its memory:

Create an instrument object — Create the VISA-GPIB object g associated with a National Instruments™ GPIB controller with board index 0 and an instrument with primary address 1.
```
g = visadev("GPIB0::1::0::INSTR");
```
Write data — Write string commands using writeline to configure the scope to store binary waveform data in memory location A.
```
writeline(g,"DATA:DESTINATION REFA");
writeline(g,"DATA:ENCDG SRPbinary");
writeline(g,"DATA:WIDTH 1");
writeline(g,"DATA:START 1");
```
Create the waveform data.
```
t = linspace(0,25,2500);
data = round(sin(t)*90 + 127);
```
Write the binary waveform data to the scope using write.
```
cmd = double('CURVE #42500');
write(g,[cmd data]);
```
The NumBytesWritten property indicates the total number of bytes that were written to the instrument.
```
g.NumBytesWritten
```
```
ans =

        2581
```
Disconnect and clean up — Use clear to disconnect the instrument from the VISA-GPIB object g and to clear it from the MATLAB workspace when you are done working with it.
```
clear g
```

Reading Data

Functions Associated with Reading Data

Function Name	Description
`read`	Read binary data from the instrument
`readline`	Read a line of ASCII data from the instrument
`readbinblock`	Read one binblock of data from the instrument
`writeread`	Write ASCII command and read response

Note

The readbinblock function is not available for the udpport interface. The writeread function is not available for the tcpserver and udpport interfaces.

Properties Associated with Reading Data

Property Name	Description
`Timeout`	Allowed time to complete write and read operations
`Terminator`	Terminator character for writing and reading text data
`NumBytesAvailable`	Number of bytes available to read

You can modify the value of Timeout using dot notation and Terminator using the configureTerminator function. NumBytesAvailable is a read-only property.

Reading Text Data Versus Reading Binary Data

For many instruments, reading text data means reading string data that reflect instrument settings, status information, and so on. Reading binary data means reading numerical values from the instrument.

You can read text data with the readline function. The readline function reads data until the first occurrence of the terminator and returns it as a string without the terminator. You can read binary data with the read function. The read function returns a specified number of values as uint8 data by default, but you can specify other data types using a name-value argument.

The following example illustrates reading text data and binary data from a Tektronix TDS 210 oscilloscope, which is displaying a periodic input signal with a nominal frequency of 1.0 kHz.

Create an instrument object — Create the VISA-GPIB object g associated with a National Instruments GPIB controller with board index 0 and an instrument with primary address 1.
```
g = visadev("GPIB0::1::0::INSTR");
```
Write and read data — Write the *IDN? command to the instrument using writeline, and then read back the result of the command using readline.
```
writeline(g,"*IDN?")
g.NumBytesAvailable
```
```
ans =

     56
```
```
idn = readline(g)
```
```
idn =

     "TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04"
```
You can also use the writeread function to perform the same operation. Write the command to your instrument and read the response.
```
idn = writeread(g,"*IDN?")
```
```
idn =

     "TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04"
```
Note
The writeread function is not available for the tcpserver and udpport interfaces.
Configure the scope to return the period of the input signal. Use read to read the period as a string.
```
writeline(g,"MEASUREMENT:MEAS1:TYPE PERIOD")
writeline(g,"MEASUREMENT:MEAS1:VALUE?")
period = read(g,9,"string")
```
```
period = 

    "1.006E-3
     "
```
Disconnect and clean up — Use clear to disconnect the instrument from the VISA-GPIB object g and to clear it from the MATLAB workspace when you are done working with it.
```
clear g
```