Working with TCP connections

This chapter describes how to open and manage a TCP connection using the command interface. For example, a external micro controller opens a TCP channel and sends data. There are a couple of text commands to manage a TCP connection. Whether to use text or binary commands is up to the user - whatever is more comfortable.
 
See ( here) to get details on how open and manage a TCP connection automatically using scripting. For example, a sensor simply sends data but can't be modified to send commands. 

TCP/IP fundamentals

This document assumes you are familiar with TCP/IP fundamentals. For further information on TCP/IP please search the internet or follow the external links:

• Wikipedia: TCP/IP ( more)
• PDF state diagram  ( more)

Open TCP connections

A TCP connection can be established two ways:

1.) Waiting for a incoming connection (Avisaro is TCP server)
Use the text command "LISTEN" ( more) or the binary command "PCMD_NET_LISTENTCP" ( more) to create a 'TCP socket' in listen mode. Specify a internal 'handle' number - this handle number adresses this TCP socket. Also specify a TCP port number.

2.) Connection to a server (Avisaro is TCP client)
Use the text command "CONNECT" ( more) or the binary command "PCMD_NET_CONNTCP" ( more) to actively connect to a TCP server. Specify a internal 'handle' number, the other TCP adress and port number.

Once the TCP socket with its handle number is declared, you can query the module whether the TCP connection was established successfully. There a different strategies to do so:

1) Listen/Connect and Wait: The "LISTEN" and "CONNECT" command offer the optional parameter "WAIT". When this parameter is used, the command returns when the connection was established. Use this option together with the Listen command with care, since the module waits forever with no connection being established. For connect there is a timeout.

2) Checking handle status: Using the text  command "SSTAT" ( more) or the binary "PCMD_NET_SSTAT" ( more) one can check the status of the TCP socket. This method is the cleanest, but it requires some parsing of the status responce.

3) Polling with stream command: The command "STREAM" ( more) is usually used to start data transmission. When the connection is not established yet, this command returns an error. It turns out to be pratical to use this command to do two things at a time: start data transmission / receiving when this command returns positive, otherwise wait and try later again.

Sending and receiving data

Once the connection is established, it can be used to send and receive data.

Sending data using text command "STREAM":

The "STREAM" command ( more) redirects inputs to be send to the TCP connection. So all data (RS232, CAN, SPI, I2C, ..) are send to the TCP partner. All data received through the TCP connection can be received using the data connection. It is required to read those data from the Avisaro product - otherwise buffer fill up and the connection stalls.

The STREAM command allows data to be send only over one TCP connection.

To switch back to issue commands, use the Stop Sequence ( more). By default, this is "+++" - but can also be changed. Make sure the stop sequence does not appear in the data stream.

Sending data using binary commands "PCMD_NET_PUTPACKET" and "PCMD_NET_GETPACKET":

The binary send and receive commands are more powerfull since more than one connection can be served and it is easier to switch between commands and data. The drawback is the formatting efford for those commands. Use "PCMD_NET_PUTPACKET"  ( more) to send data and the "PCMD_NET_GETPACKET" ( more) to receive data.

Closing TCP/IP connection

When done with sending and receiving data, the TCP connection can be closed.

Closing using text command "CLOSE":

The "CLOSE" command ( more) closes the TCP connection. Use the handle number to specify which connection should be closed.

Closing using binary command "PCMD_FCLOSE":

The binary command "PCMD_FCLOSE" ( more) closes the TCP connection. Use the handle number to specify which connection should be closed.

Example: Listening for incoming TCP connection

This example is using text commands to start listening for an incoming connection, sending some data and finally closing the connection again. This example works for any data interface (RS232, CAN, I2C, SPI, ...):

 

Send from your application	Send from Avisaro device	Comment
listen 101 23		Set socket with handle number 101 to listen on port 23
	>
stream 101		Try to establish stream to send data.
	ERR 28 >	This error is expected since connection is not established yet.
stream 101
	ERR 28 >	... still not established.
stream 101		Oh, good - no error - connection is established
THIS DATA WAS SEND FROM SERVER TO AVISARO		Data is send back ...
	THIS DATA WAS SEND FROM AVISARO TO THE SERVER	... and forth.
+++		Sending stop sequence to return to command mode
	>
close 101		Close connection
	>

 

Some details:

• The ">" is the return prompt of the Avisaro module. Each > is headed by a <cr> <lf>. It can be changed i.e. to "OK" if so desired
• All commands are terminated by <cr> <lf> ("enter") - this is not shown expliciately here