Read and Write ASCII Data over TCP/IP

This section provides details and examples exploring ASCII read and write operations with a TCP/IP object.

Note

Most bench-top instruments (oscilloscopes, function generators, etc.) that provide network connectivity do not use raw TCP socket communication for instrument command and control. Instead, it is supported through the VISA standard. For more information on using VISA to communicate with your instrument, see VISA Overview.

Functions and Properties

These functions are used when reading and writing text:

FunctionPurpose
fprintfWrite text to the server.
fscanfRead data from the server and format as text.

These properties are associated with reading and writing text:

PropertyPurpose
ValuesReceivedSpecifies the total number of values read from the server.
ValuesSentSpecifies the total number of values sent to the server.
InputBufferSizeSpecifies the total number of bytes that can be queued in the input buffer at one time.
OutputBufferSizeSpecifies the total number of bytes that can be queued in the output buffer at one time.
TerminatorCharacter used to terminate commands sent to the server.

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.

Configuring and Connecting to the Server

For this example, we will use an echo server that is provided with the toolbox. The echo server allows you to experiment with the basic functionality of the TCP/IP objects without connecting to an actual device. An echo server is a service that returns to the sender's address and port, the same bytes it receives from the sender.

echotcpip('on', 4000)

You need to create a TCP/IP object. In this example, create a TCP/IP object associated with the host 127.0.0.1 (your local machine), port 4000. In general, the host name or address and the host port will be defined by the device and your network configuration.

t = tcpip('127.0.0.1', 4000);

Before you can perform a read or write operation, you must connect the TCP/IP object to the server with the fopen function.

fopen(t)

If the object was successfully connected, its Status property is automatically configured to open.

t.Status
ans = 
    open

Writing ASCII Data

You use the fprintf function to write ASCII data to the server.

fprintf(t, 'Hello World 123');

By default, the fprintf function operates in a synchronous mode. This means that fprintf 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 fprintf function writes ASCII data using the %s\n format. All occurrences of \n in the command being written to the server are replaced with the Terminator property value. When using the default format, %s\n, all commands written to the server will end with the Terminator character.

For the previous command, the linefeed (LF) is sent after 'Hello World 123' is written to the server, thereby indicating the end of the command.

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, the data command previously shown can be written to the server using three calls to fprintf.

fprintf(t, '%s', 'Hello');
fprintf(t, '%s', ' World');
fprintf(t, '%s\n', ' 123');

The Terminator character indicates the end of the command and is sent after the last call to fprintf.

ASCII Write Properties

The OutputBufferSize property specifies the maximum number of bytes that can be written to the server at once. By default, OutputBufferSize is 512.

t.OutputBufferSize
ans = 
    512

The ValuesSent property indicates the total number of values written to the server since the object was connected to the server.

t.ValuesSent
ans = 
    32

Reading ASCII Data

You use the fscanf function to read ASCII data from the server. For example, to read back the data returned from the echo server for our first fprintf command:

data = fscanf(t)
data = 
    Hello World 123

By default, the fscanf function reads data using the '%c' format and blocks the MATLAB command line until one of the following occurs:

  • The terminator is received as specified by the Terminator property

  • A timeout occurs as specified by the Timeout property

  • The input buffer is filled

  • The specified number of values is read

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.

The following commands return a numeric value as a double.

Clear anything still in the input buffer from the previous commands.

flushinput(t);

Send the data to the server.

fprintf(t, '0.8000');

Read the response.

data = fscanf(t, '%f')
data = 
    0.8000
isnumeric(data)
ans = 
    1

ASCII Read Properties

The InputBufferSize property specifies the maximum number of bytes you can read from the server. By default, InputBufferSize is 512.

t.InputBufferSize
ans = 
    512

The ValuesReceived property indicates the total number of values read from the server, including the terminator.

t.ValuesReceived
ans = 
    32

Cleanup

If you are finished with the TCP/IP object, disconnect it from the server, remove it from memory, and remove it from the workspace. If you are using the echo server, turn it off.

fclose(t);
delete(t);
clear t
echotcpip('off');