TcpSocket

The TcpSocket object allows Q-SYS cores to make client TCP/IP connections to devices on the network.

The functions in the v2 TcpSocket communication library allow an Event-Based scheme to simplify scripting. Also, the v2 TCP Socket functionality allows for connection monitoring and automatic reconnect, buffer searches and custom EOL sequences. Asynchronous callbacks are no longer necessary as the Event Handler functionality now takes care of that behind the scenes.

For an example of the how the Event-Handled TcpSocket functions, see "Button to Send Text String to Simple TCP/IP Socket".

Callbacks

Optional callback functions may be defined instead of using the singular EventHandler. Depending upon the application, defining separate functions for each event may be preferable. The choice to use either a single EventHandler to capture all socket events or separate callback functions is up to the programmer. There is no need to change a functioning script because this new functionality exists and you may choose to never use it. But some programmers may feel that the callback method better matches their logical style.

Reference Tables

New()

Purpose:    Static class method. Creates a new instance of the Socket class.

Return Value:   socket

Type: TcpSocket object

Definition: The newly created socket

Connect( ipAddress/hostname, port )

Purpose:    Attempts to connect to the specified ip/host name and port. The Connect() function should be considered as a means to start the process to open a socket.

Parameter: ipAddress,hostname

Type: string

Definition: The IP Address or FQDN (fully qualified domain name) which represents the remote host

port

Type: integer, 0 - 65535

Definition: The port to connect to on the remote host

Disconnect()

Purpose:    Disconnects the socket

Write( data )

Purpose:    Writes specified data to the socket. Calling Write() should be avoided until the socket triggers its "Connected" event. Raises error if socket is not connected.

Parameter: data

Type: string

Definition: The data to write to the socket

Read( length )

Purpose:    Attempts to read up to 'length' bytes from socket. These bytes are removed from the buffer, leaving any remaining bytes beyond the 'length' specified.

Parameter: length

Type: integer

Definition: The number of bytes of data to read from the socket buffer. Returns Nil if the buffer is empty.

Return Value:   string

Definition: String containing the number of bytes requested or the number of bytes available, whichever comes first.

ReadLine( EOL, <custom> )

Purpose:    Attempts to read a 'line' from the socket buffer. 'EOL' is defined in the table above. 'custom' is an optional string only used by 'EOL.Custom'.

Parameter: EOL

Type: predefined keyword

Definition: One of six predefined keywords in the form of 'EOL.<keyword>'. The keywords are shown in the TcpSocket.EOL table above.

<custom>

Type: string

Definition: Conditionally optional. A string literal containing the custom end of line character combination to search for. This field is only valid when using the EOL.Custom keyword for the first argument.

Return Value:   string

Definition: Nil if the EOL was not found, otherwise returns the string up to the EOL sequence

Search( str, [start_pos] )

Purpose:    Searches the socket buffer for string 'str' (starting at integer 'start_pos' ) and returns the index of where 'str' is found.

Parameter: str

Type: string

Definition: The string to search for

[start_pos]

Type: integer

Definition: Optional. The index of where to start in the socket buffer. Default is index 1

Return Value:   integer

Definition: Nil if the search string was not found, otherwise returns the integer index of where the search string was found.

Example

Button to Send Text String to Simple TCP/IP Socket (v2)

This script automatically connects to the remote socket server. When a user presses a button, the script sends a text string. Any received text is displayed in the debug window if terminated with a <CR><LF>. The script will automatically attempt to reconnect after 5 seconds if the socket is closed,.

Using Single EventHandler

address = "192.168.1.100"
port = 1234
sock = TcpSocket.New()
sock.ReadTimeout = 0
sock.WriteTimeout = 0
sock.ReconnectTimeout = 5

sendData = 'Hello\x0d\x0a'

sock.EventHandler = function(sock, evt, err)
  if evt == TcpSocket.Events.Connected then
    print( "socket connected" )
  elseif evt == TcpSocket.Events.Reconnect then
    print( "socket reconnecting..." )
  elseif evt == TcpSocket.Events.Data then
    print( "socket has data" )
    message = sock:ReadLine(TcpSocket.EOL.Any)
    while (message ~= nil) do
      print( "reading until CrLf got "..message )
      message = sock:ReadLine(TcpSocket.EOL.Any)
    end
  elseif evt == TcpSocket.Events.Closed then
    print( "socket closed by remote" )
  elseif evt == TcpSocket.Events.Error then
    print( "socket closed due to error", err )
  elseif evt == TcpSocket.Events.Timeout then
    print( "socket closed due to timeout" )
  else
    print( "unknown socket event", evt ) --should never happen
  end
end

Controls.Inputs[1].EventHandler = function()
  sock:Write(sendData)
end

sock:Connect(address, port)

Using Separate Callback Functions

address = "192.168.1.100"
port = 1234
sock = TcpSocket.New()
sock.ReadTimeout = 0
sock.WriteTimeout = 0
sock.ReconnectTimeout = 5

sendData = 'Hello\x0d\x0a'

sock.Connected = function(sock)
  print("TCP socket is connected")
end
sock.Reconnect = function(sock)
  print("TCP socket is reconnecting")
end
sock.Data = function(sock)
  print("TCP socket has data:",sock:Read(sock.BufferLength) )
end
sock.Closed = function(sock)
  print("TCP socket was closed by the remote end")
end
sock.Error = function(sock, err)
  print("TCP socket had an error:",err)
end
sock.Timeout = function(sock, err)
  print("TCP socket timed out",err)
end

Controls.Inputs[1].EventHandler = function()
  sock:Write(sendData)
end

sock:Connect(address, port)