Creating a TCP/IP Object :: Controlling Instruments Using TCP/IP and UDP (Instrument Control Toolbox™)

Learn more about Instrument Control Toolbox

Creating a TCP/IP Object

On this page…
TCP/IP Object TCP/IP Object Display Example: Communicating with a Remote Host Example: Server Drops the Connection

On this page…

Example: Communicating with a Remote Host

TCP/IP Object

You create a TCP/IP object with the tcpip function. tcpip requires the name of the remote host as an input argument. In most cases, you need to specify the remote port value. If you do not specify the remote port, then 80 is used. As described in Configuring Properties During Object Creation, you can also configure property values during object creation.

Each TCP/IP object is associated with one instrument. For example, to create a TCP/IP object for a Sony/Tektronix AWG520 Arbitrary Waveform Generator,

t = tcpip('sonytekawg.yourdomain.com',4000);

Note that the port number is fixed and is found in the instrument's documentation.

The TCP/IP object t now exists in the MATLAB workspace. You can display the class of t with the whos command.

whos t
  Name      Size                   Bytes  Class

  t         1x1                      640  tcpip object

Grand total is 16 elements using 640 bytes

Once the TCP/IP object is created, the following properties are automatically assigned values. These general-purpose properties provide information about the TCP/IP object based on the object type, the remote host, and the remote port.

TCP/IP Descriptive Properties

Property Name	Description
`Name`	Specify a descriptive name for the TCP/IP object.
`RemoteHost`	Specify the remote host.
`RemotePort`	Specify the remote host port for the connection.
`Type`	Indicate the object type.

You can display the values of these properties for t with the get function.

get(t,{'Name','RemoteHost','RemotePort','Type'})
ans = 
    [1x31 char]    [1x24 char]    [4000]    'tcpip'

TCP/IP Object Display

The TCP/IP object provides you with a convenient display that summarizes important configuration and state information. You can invoke the display summary these three ways:

Type the TCP/IP object variable name at the command line.
Exclude the semicolon when creating a TCP/IP object.
Exclude the semicolon when configuring properties using the dot notation.

You can also display summary information via the Workspace browser by right-clicking an instrument object and selecting Display Summary from the context menu.

The display summary for the TCP/IP object t is given below.

TCP/IP Object : TCP/IP-sonytekawg.yourdomain.com

Communication Settings
   RemotePort:         4000
   RemoteHost:         sonytekawg.yourdomain.com
   Terminator:         'LF'

Communication State
   Status:             closed
   RecordStatus:       off

Read/Write State
   TransferStatus:     idle
   BytesAvailable:     0
   ValuesReceived:     0
   ValuesSent:         0

Example: Communicating with a Remote Host

In this example, you read a page from the MathWorks Web site using a TCP/IP object:

Create and configure an instrument object — First you create a TCP/IP object in the MATLAB workspace. Port 80 is the standard port for Web servers.
```
t = tcpip('www.yourdomain.com', 80);
```
By default, the TCP/IP object has an InputBufferSize of 512, which means it can only read 512 bytes at a time. The MathWorks Web page data is much greater than 512 bytes, so you need to set a larger value for this property.
```
set(t, 'InputBufferSize', 30000);
```
Connect the object — Next, you open the connection to the server. If the server is not present or is not accepting connections you would get an error here.
```
fopen(t);
```
Write and read data — You can now communicate with the server using the functions fprintf, fscanf, fwrite, and fread.
To ask a Web server to send a Web page, you use the GET command. You can ask for the main Web page from www.yourdomain.com using 'GET /'.
```
fprintf(t, 'GET /');
```
The server receives the command and sends back the Web page. You can see if any data was sent back by looking at the BytesAvailable property of the object.
```
get(t, 'BytesAvailable')
```
Now you can start to read the Web page data. By default, fscanf reads one line at a time. You can read lines of data until the BytesAvailable value is 0. Note that you will not see a rendered web page; the HTML file data will scroll by on the screen.
```
while (get(t, 'BytesAvailable') > 0)
    A = fscanf(t),
end
```
Disconnect and clean up — If you want to do more communication, you can continue to read and write data here. If you are done with the object, close it and delete it.
```
fclose(t);
delete(t);
clear t
```

Example: Server Drops the Connection

This example shows what happens when a TCP/IP object loses its connection with a remote server. The server 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.

The AWG can drop the connection because it is taken off line, it is powered down, and so on:

Create an instrument object — Create a TCP/IP object for the AWG.
```
t = tcpip('sonytekawg.yourdomain.com', 4000);
```
Connect to the instrument — Connect to the remote instrument.
```
fopen(t)
```
Write and read data — Write a command to the instrument and read back the result.
```
fprintf(t,'*IDN?')
fscanf(t)
ans =
SONY/TEK,AWG520,0,SCPI:95.0 OS:2.0 USR:2.0
```
Assume that the server drops the connection. If you attempt to read from the instrument, a timeout occurs and a warning is displayed.
```
fprintf(t,'*IDN?')
fscanf(t)

Warning: A timeout occurred before the Terminator was reached.
(Type "warning off instrument:fscanf:unsuccessfulRead" to 
suppress this warning.)
ans =
     ''
```
At this point, the object and the instrument are still connected.
```
get(t,'Status')
ans =
open
```
If you attempt to write to the instrument again, an error message is returned and the connection is automatically closed.
```
fprintf(t,'*IDN?')
??? Error using ==> fprintf
Connection closed by RemoteHost. Use FOPEN to connect to 
RemoteHost.
```
Note that if the TCP/IP object is connected to the local host, the warning message is not displayed. Instead, the error message is displayed following the next read operation after the connection is dropped.
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
```

TCP/IP and UDP Overview

Creating a UDP Object

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