Writing and Reading Data :: Controlling Instruments Using TCP/IP and UDP (Instrument Control Toolbox™)

Learn more about Instrument Control Toolbox

Writing and Reading Data

On this page…
Rules for Completing Write and Read Operations Example: Writing and Reading Data with a TCP/IP Object Example: Writing and Reading Data with an UDP Object

On this page…

Rules for Completing Write and Read Operations

Example: Writing and Reading Data with a TCP/IP Object

Example: Writing and Reading Data with an UDP Object

Rules for Completing Write and Read Operations

The rules for completing synchronous and asynchronous read and write operations are described below.

For a general overview about writing and reading data, as well as a list of all associated functions and properties, refer to Communicating with Your Instrument.

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.

In addition to these rules, you can stop an asynchronous write operation at any time with the stopasync function.

A text command is processed by the instrument only when it receives the required terminator. For TCP/IP and UDP objects, each occurrence of \n in the ASCII command is replaced with the Terminator property value. Because the default format for fprintf is %s\n, all commands written to the instrument will end with the Terminator value. The default value of Terminator is the line feed character. The terminator required by your instrument will be described in its documentation.

Completing Read Operations

A read operation with fgetl, fgets, fscanf, or readasync completes when one of these conditions is satisfied:

The terminator specified by the Terminator property is read. For UDP objects, DatagramTerminateMode must be off.
The time specified by the Timeout property passes.
The input buffer is filled.
The specified number of values is read (fscanf and readasync only). For UDP objects, DatagramTerminateMode must be off.
A datagram is received (for UDP objects, only when DatagramTerminateMode is on).

A read operation with fread completes when one of these conditions is satisfied:

The time specified by the Timeout property passes.
The input buffer is filled.
The specified number of values is read. For UDP objects, DatagramTerminateMode must be off.
A datagram is received (for UDP objects, only when DatagramTerminateMode is on).

Note Set the terminator property to '' (null), if appropriate, to ensure efficient throughput of binary data.

In addition to these rules, you can stop an asynchronous read operation at any time with the stopasync function.

Example: Writing and Reading Data with a TCP/IP Object

This example illustrates how to use text and binary read and write operations with a TCP/IP object connected to a remote instrument. In this example, you create a vector of waveform data in the MATLAB workspace, upload the data to the instrument, and then read back the waveform.

The instrument is a Sony/Tektronix AWG520 Arbitrary Waveform Generator (AWG). Its address is sonytekawg.yourdomain.com and its port is 4000. The AWG's host IP address is 192.168.1.10 and is user configurable in the instrument. The associated host name is given by your network administrator. The port number is fixed and is found in the instrument's documentation:

Create an instrument object — Create a TCP/IP object associated with the AWG.
```
t = tcpip('sonytekawg.yourdomain.com',4000);
```
Connect to the instrument — Before establishing a connection, the OutputBufferSize must be large enough to hold the data being written. In this example, 2577 bytes are written to the instrument. Therefore, the OutputBufferSize is set to 3000.
```
set(t,'OutputBufferSize',3000)
```
You can now connect t to the instrument.
```
fopen(t)
```
Write and read data — Since the instrument's byte order is little-endian, configure the ByteOrder property to littleEndian.
```
set(t,'ByteOrder','littleEndian')
```
Create the sine wave data.
```
x = (0:499).*8*pi/500;
data = sin(x);
marker = zeros(length(data),1);
marker(1) = 3;
```
Instruct the instrument to write the file sin.wfm with Waveform File format, a total length of 2544 bytes, and a combined data and marker length of 2500 bytes.
```
fprintf(t,'%s',['MMEMORY:DATA "sin.wfm",#42544MAGIC 1000' 13 10])
fprintf(t,'%s','#42500')
```
Write the sine wave to the instrument.
```
for (i = 1:length(data)),
	fwrite(t,data(i),'float32');
	fwrite(t,marker(i));
end
```
Instruct the instrument to use a clock frequency of 100 MS/s for the waveform.
```
fprintf(t,'%s',['CLOCK 1.0000000000e+008' 13 10 10])
```
Read the waveform stored in the function generator's hard drive. The waveform contains 2000 bytes plus markers, header, and clock information. To store this data, close the connection and configure the input buffer to hold 3000 bytes.
```
fclose(t)
set(t,'InputBufferSize',3000)
```
Reopen the connection to the instrument.
```
fopen(t)
```
Read the file sin.wfm from the function generator.
```
fprintf(t,'MMEMORY:DATA? "sin.wfm" ')
data = fread(t,t.BytesAvailable);
```
The next set of commands reads the same waveform as a float32 array. To begin, write the waveform to the AWG.
```
fprintf(t,'MMEMORY:DATA? "sin.wfm" ')
```
Read the file header as ASCII characters.
```
header1 = fscanf(t)
header1 =
#42544MAGIC 1000
```
Read the next six bytes, which specify the length of data.
```
header2 = fscanf(t,'%s',6)
header2 =
#42500
```
Read the waveform using float32 precision and read the markers using uint8 precision. Note that one float32 value consists of four bytes. Therefore, the following commands read 2500 bytes.
```
data = zeros(500,1);
marker = zeros(500,1);
for i = 1:500,
	data(i) = fread(t,1,'float32');
	marker(i) = fread(t,1,'uint8');
end
```
Read the remaining data, which consists of clock information and termination characters.
```
clock = fscanf(t);
cleanup = fread(t,2);
```
Disconnect and clean up — When you no longer need t, you should disconnect it from the host, and remove it from memory and from the MATLAB workspace.
```
fclose(t)
delete(t)
clear t
```

Example: Writing and Reading Data with an UDP Object

This example illustrates how to use text read and write operations with a UDP object connected to a remote instrument.

The instrument used is an echo server on a Linux-based PC. An echo server is a service available from the operating system that returns (echoes) received data to the sender. The host name is daqlab11 and the port number is 7. The host name is assigned by your network administrator.

Create an instrument object — Create a UDP object associated with daqlab11.
```
u = udp('daqlab11',7);
```
Connect to the instrument — Connect u to the echo server.
```
fopen(u)
```
Write and read data — You use the fprintf function to write text data to the instrument. For example, write the following string to the echo server.
```
fprintf(u,'Request Time')
```
UDP sends and receives data in blocks that are called datagrams. Each time you write or read data with a UDP object, you are writing or reading a datagram. For example, the string sent to the echo server constitutes a datagram with 13 bytes — 12 ASCII bytes plus the line feed terminator.
You use the fscanf function to read text data from the echo server.
```
fscanf(u)
ans =
Request Time
```
The DatagramTerminateMode property indicates whether a read operation terminates when a datagram is received. By default, DatagramTerminateMode is on and a read operation terminates when a datagram is received. To return multiple datagrams in one read operation, set DatagramTerminateMode to off.
The following commands write two datagrams. Note that only the second datagram sends the terminator character.
```
fprintf(u,'%s','Request Time')
fprintf(u,'%s\n','Request Time')
```
Since DatagramTerminateMode is off, fscanf reads across datagram boundaries until the terminator character is received.
```
set(u,'DatagramTerminateMode','off')
data = fscanf(u)
data =
Request TimeRequest Time
```
Disconnect and clean up — When you no longer need u, you should disconnect it from the host, and remove it from memory and from the MATLAB workspace.
```
fclose(u)
delete(u)
clear u
```

Creating a UDP Object

Events and Callbacks

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit