This section provides details and examples exploring binary 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.
These functions are used when reading and writing binary data:
Function | Purpose |
---|---|
fread | Read binary data from the server. |
fwrite | Write binary data to the server. |
These properties are associated with reading and writing binary data:
Property | Purpose |
---|---|
ValuesReceived | Specifies the total number of values read from the server. |
ValuesSent | Specifies the total number of values sent to the server. |
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. |
ByteOrder | Specifies the byte order of 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.
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);
You may need to configure the OutputBufferSize
of the TCP/IP
object. 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
If the command specified in fwrite
contains more than 512
bytes, an error is returned and no data is written to the server. In this example
4000 bytes will be written to the server. Therefore, the
OutputBufferSize
is increased to
4000
.
t.OutputBufferSize = 4000; t.OutputBufferSize ans = 4000
You may need to configure the ByteOrder
of the TCP/IP object.
The ByteOrder
property specifies the byte order of the server. By
default ByteOrder
is bigEndian
.
t.ByteOrder ans = 'bigEndian'
If the server's byte order is little-endian, the ByteOrder
property of the object can be configured to littleEndian
:
t.ByteOrder = 'littleEndian' t.ByteOrder ans = 'littleEndian'
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
You use the fwrite
function to write binary data to the server.
For example, the following command will send a sine wave to the server.
Construct the sine wave to be written to the server.
x = (0:999) .* 8 * pi / 1000; data = sin(x);
Write the sine wave to the server.
fwrite(t, data, 'float32');
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
.
Note
When performing a write operation, you should think of the transmitted 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 ValuesSent
property indicates the total number of values
written to the server since the object was connected to the server.
t.ValuesSent ans = 1000
The InputBufferSize
property specifies the maximum number of
bytes that you can read from the server. By default,
InputBufferSize
is 512
.
t.InputBufferSize ans = 512
Next, the waveform stored in the function generator's memory will be read. The
waveform contains 4000 bytes. Configure the InputBufferSize
to
hold 4000 bytes. Note, the InputBufferSize
can be configured only
when the object is not connected to the server.
fclose(t); t.InputBufferSize = 4000; t.InputBufferSize ans = 4000
Now that the property is configured correctly, you can reopen the connection to the server:
fopen(t);
You use the fread
function to read binary data from the
server.
The fread
function blocks the MATLAB command line until one of the following occurs:
A timeout occurs as specified by the Timeout
property
The specified number of values is read
The InputBufferSize
number of values is read
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 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.
For reading float32
binary data, send the waveform again.
Closing the object clears any available data from earlier writes.
fwrite(t, data, 'float32');
Now read the same waveform as a float32
array.
data = fread(t, 1000, 'float32');
The ValuesReceived
property indicates the total number of
values read from the server.
t.ValuesReceived ans = 1000
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');