Maintained TCP Connection - Version 2.1.1#

Module Summary#

Maintains and monitors a TCP connection with a remote host and fires Triggers on changes.

Module Status#

This IO Module is stable and has been tested internally.

If you encounter any issues with this module, or have any feedback regarding its operation, please contact our support team.

Release Notes#

Version 2.1#

  •  Add option to Send String to send alternative string, with trigger variable insertion.

  •  Added Last Action Message Sent status variable.

  •  Added Termination Characters instance property.

  •  Updated documentation.

  •  Bug fixes.

Version 2.0#

  •  Initial implementation:

  •  Connected Trigger.

  •  Disconnected Trigger.

  •  Host Not Found Trigger.

  •  Error Detected Trigger.

  •  Message Received Trigger.

  •  Connect To Host Action.

  •  Disconnect From Host Action.

  •  Send String Action.

  •  Status variables.

Minor point releases (eg. 1.1.x) will be for small fixes and may not be listed here.

Configuration#

Note: The module establishes a TCP connection with a remote device running a TCP server service. All client communication is handled internally within the module itself and therefore should not be configured in the Network tab. The IP and port combination should also not be used elsewhere outside of the module, including in other module instances.

Operation#

Instance Properties#

The Host Name or IP Address and Port are that of the remote host.

If Connect At Startup is checked, the Controller will try to establish a connection as soon as it boots up, otherwise, the Connect To Host Action must be used first.

If Auto Attempt Reconnect is checked, if the Controller detects a disconnect with the host, it will automatically try to re-establish the connection at 10 second intervals.

Poll String and Send Interval are optional. If the Send Interval is set to anything but Disabled, the Controller will send the Poll String at that interval (if a connection is established).

The Termination Characters are appended to every string that is sent. This can be any number of characters with null represented by \0, carriage return by \r, new line by \n etc.

If both Poll String and Termination Characters are left blank but Send Interval is enabled, a single carriage return character will be sent. If Termination Characters is defined by Poll String is blank, the Termination Characters will be used.

Line ending must be explicitly declared, for example is the Poll String is mypollstring a carriage ending or newline may want to be appended in escaped format so, mypollstring\r or mypollstring\n.

Checking the Log Comms checkbox will provide more detailed log messages for TCP connection statuses. This is intended for diagnostics and problem solving and should ideally be disabled during normal operation.

Status Variables#

The IO Modules tab of the web interface provides status variables to shows information about the module and monitor its state.

Destination    The Host Name or IP address and port number set in the Instance properties.
Current State    The current state of the TCP socket with a timestamp.
Last Error    The last error that was detected with a timestamp. If the socket is connected, the error will be erased.
Last Poll Message Sent    The poll message and a timestamp of when it was last sent.
Last Action Message Sent    The last message that was sent from an action and a timestamp of when it was last sent.
Last Message Received    The last string received from the remote host.

Triggers#

Connected#

Fires when the TCP socket is successfully established and connected.

Trigger variables:

  •  Variable 1: IP Address (string).

  •  Variable 2: Port Number (integer)

Disconnected#

Fires when the TCP socket is disconnected for any reason.

Trigger variables:

  •  Variable 1: IP Address (string).

  •  Variable 2: Port Number (integer)

Host Not Found#

Fires when a connection can not be established because the host can not be found.

Trigger variables:

  •  Variable 1: IP Address (string).

  •  Variable 2: Port Number (integer)

Error Detected#

Fires when a TCP error has been detected for any reason. If the error causes a disconnect, the Disconnected Trigger will also fire (if one exists in the project).

Trigger variables:

  •  Variable 1: IP Address (string).

  •  Variable 2: Port Number (integer)

  •  Variable 3: Error Description (string)

Message Received#

Fires when a message is received from the host. If String is empty, any received message will fire the Trigger. If a String is set, the Trigger will only fire if the received message string matched the Trigger String.

Trigger variables:

  •  Variable 1: IP Address (string).

  •  Variable 2: Port Number (integer)

  •  Variable 3: Message Received (string)

Note: String captures are not supported.

Actions#

Connect To Host#

Initialises a TCP connection to the remote host. This can be used at any time but is required if Auto Attempt Reconnect is not enabled in the Instance properties.

If Auto Attempt Reconnect is enabled and the previous disconnect occurred because of a Disconnect From Host Action, this will resume auto-reconnects.

Disconnect From Host#

Tears down a TCP connection if one is already established. This will also stop Auto Attempt Reconnect if disabled but the Connect To Host Action can be used to resume this.

Send String#

Sends a String to the Host. If the field is left blank, the default Poll String will be used instead.

It is possible to insert trigger variables in to a string using variable indexes surrounded by capture tags, for example:

Trigger variables are:

  •  Variable 1: MY_VARIABLE

  •  Variable 2: 65535

If the String property is: hello_<1>world<2>_ the resulting string would be: hello_MY_VARIABLE_world_65535.

Note: This will only work for the Action String property and not the instance Poll String

Support#

If you encounter any issues with this module, please contact our support team.