Skip to main content

TCP/IP Data Source

The TCP/IP data source allows Mango to communicate directly over raw TCP sockets with devices or services that use custom text-based or binary protocols. It opens a TCP connection to a specified host and port, sends commands, receives responses, and uses regular expressions to parse meaningful data from the responses. This data source is useful for integrating with devices that expose a simple command-response protocol over TCP but do not use a standardized industrial protocol like Modbus or BACnet.

This is a polling data source: for each queryable data point, Mango sends the point's read command at every poll interval and parses the response. Points can also be configured as settable, allowing Mango to send write commands to the remote device.

Overview​

PropertyValue
ModulemangoAutomation-TcpIp
ProtocolTCP/IP (raw socket)
DirectionBidirectional
Typical UseCommunicating with devices via raw TCP socket connections

Prerequisites​

  • A device or service that accepts TCP socket connections and communicates using a text-based or binary command-response protocol.
  • The device's IP address (or hostname) and TCP port number.
  • Knowledge of the protocol syntax: what commands to send, what delimiter terminates messages, and the format of responses.
  • An understanding of regular expressions for parsing response strings.

Configuration​

Data Source Settings​

SettingDescription
NameA descriptive name for the data source.
Update periodHow often Mango sends read commands to the device and processes responses.
HostThe IP address or hostname of the device to connect to.
PortThe TCP port on which the device is listening.
DelimiterA message terminator appended after every read command. Escape sequences are supported (e.g., \r for carriage return, \n for line feed, \r\n for CRLF). The delimiter tells the device where the command ends.
TimeoutMilliseconds to wait for a complete response. A timeout of 0 means no timeout (wait indefinitely). If a response is received without an EOF or connection close, it is not processed until the timeout is reached.
Configuration is in hexWhen checked, all configuration values (commands, delimiters) are interpreted as hexadecimal byte strings. Each pair of hex characters (e.g., 0F) is converted to the corresponding byte value (0-255). This is primarily useful for binary protocols where commands are not representable as printable text.

Understanding the Delimiter​

The delimiter serves a dual purpose:

  1. It is appended to outgoing commands to signal the end of the command to the remote device.
  2. It helps Mango identify complete responses from the device.

Common delimiters:

  • \r\n (CRLF) -- standard for many text protocols
  • \r (CR) -- common for serial-to-TCP converters
  • \n (LF) -- common for Unix-style protocols

If the device protocol does not use a delimiter and instead relies on connection close or fixed-length responses, set the timeout to an appropriate value so that Mango knows when to stop waiting for more data.

Hex Mode​

When Configuration is in hex is enabled, all string values in the data source and data point configuration are treated as hexadecimal. For example, a read command of 01030000 would send the bytes 0x01, 0x03, 0x00, 0x00 over the socket. This mode is generally only applicable to data points with the String data type, as the hex codes are converted from two-character representations into raw byte values.

Data Point Configuration​

SettingDescription
Data typeThe Mango data type (Binary, Numeric, Alphanumeric, Multistate).
QueryableWhen checked, Mango sends the read command for this point at every poll interval.
Read commandThe command string sent to the device to request data for this point. The data source's delimiter is appended automatically.
Value regexA regular expression applied to the response to extract the point's value. Use capture groups (parentheses) to isolate the desired portion.
Value indexThe capture group number from the regex that contains the point's value. Group 0 is the entire match; group 1 is the first set of parentheses.
SettableWhen checked, allows writing values to the device.
Write commandThe command string sent when a value is set on this point. The special placeholder %VALUE% is replaced with the value being written.

Read Command and Response Flow​

At each poll cycle:

  1. Mango sends the read command followed by the delimiter over the TCP socket.
  2. Mango waits for the response, either until the delimiter is received, the connection closes, or the timeout is reached.
  3. The value regex is applied to the response string.
  4. The capture group at value index is extracted and converted to the configured data type.

Write Command​

When a value is set on a settable point, Mango sends the write command with %VALUE% replaced by the set value. For example, if the write command is SET TEMP %VALUE% and the value set is 72.5, Mango sends SET TEMP 72.5 followed by the delimiter.

Common Patterns​

Simple Query-Response Device​

Many devices support a simple text protocol where you send a command and receive a response. For example, a temperature controller that responds to READ TEMP\r\n with TEMP=72.5\r\n:

  • Read command: READ TEMP
  • Delimiter: \r\n
  • Value regex: TEMP=([0-9.]+)
  • Value index: 1
  • Data type: Numeric

Multiple Data Points from One Device​

Create separate data points for each value you need to read, each with its own read command and regex. For example:

PointRead CommandValue RegexValue Index
TemperatureGET TEMPTEMP:([0-9.]+)1
HumidityGET HUMHUM:([0-9.]+)1
StatusGET STATUSSTATUS:(\w+)1

Binary Protocol Communication​

For devices that communicate using binary protocols, enable Configuration is in hex and use hexadecimal strings for commands. For example, to send the bytes 0x01 0x03 0x00 0x00 0x00 0x01:

  • Configuration is in hex: Checked
  • Read command: 010300000001

The response is also interpreted as hex bytes, and the regex operates on the hex string representation.

Writing to a Device​

To control a relay that accepts commands like SET RELAY1 ON and SET RELAY1 OFF:

  • Settable: Checked
  • Write command: SET RELAY1 %VALUE%

Setting the point to "ON" sends SET RELAY1 ON\r\n to the device.

Connecting to a Serial-to-Ethernet Converter​

Many legacy serial devices are made network-accessible using serial-to-Ethernet converters (e.g., Moxa NPort, Lantronix). Configure the TCP/IP data source with the converter's IP address and virtual serial port number. The commands and responses are identical to what would be sent over a direct serial connection.

Troubleshooting​

Connection Failures​

  1. Wrong host or port -- verify the IP address and port number. Test connectivity with telnet <host> <port> or nc <host> <port> from the Mango server.
  2. Firewall blocking -- ensure the firewall allows outbound TCP connections from the Mango server to the device's port.
  3. Device not listening -- the device or serial converter may not be configured to accept TCP connections, or the service may not be running.
  4. Connection reset -- some devices drop idle connections. If the device expects persistent connections, ensure the poll period is short enough to keep the connection alive.

No Data or Timeout​

  1. Timeout too short -- if the device is slow to respond, increase the timeout value.
  2. Timeout is zero -- a timeout of 0 means Mango waits indefinitely. This can cause the data source to hang if the device never sends a response. Set a reasonable timeout value.
  3. Wrong delimiter -- if the delimiter does not match the device's expected command terminator, the device may not recognize the command. Check the device documentation for the correct line ending.
  4. Response has no EOF -- if the device sends a response without closing the connection and without a recognizable end-of-message marker, Mango waits for the timeout before processing. Increase the timeout or configure a proper delimiter.

Wrong Values​

  1. Regex does not match -- test the regex against a sample response. Remember that the regex is applied to the complete response string including any delimiters or whitespace.
  2. Wrong capture group -- verify the value index matches the correct parenthesized group in the regex.
  3. Hex mode mismatch -- if the device sends binary data but hex mode is not enabled (or vice versa), the data will be misinterpreted.
  4. Data type mismatch -- ensure the extracted string can be converted to the configured Mango data type. For example, a Numeric point requires the regex to extract only digits and decimal points.

Performance Concerns​

  1. Many points on one device -- each queryable point sends its own read command per poll cycle. If there are many points and the device is slow to respond, the total poll time may exceed the poll period. Consider increasing the poll period or reducing the number of points.
  2. Connection overhead -- the TCP/IP data source opens a new connection for each poll cycle. If the device has limited connection capacity, this may cause failures. Some devices benefit from longer poll periods to reduce connection frequency.