Serial Data Source

The Serial data source is a general-purpose serial port reader that allows Mango to receive and parse data from devices communicating over RS-232 or RS-485 serial connections. Unlike polling-based data sources, the Serial data source is event-driven: it processes data only when a serial message is received from the connected device. Messages are parsed using regular expressions to extract point values, making it flexible enough to work with a wide variety of custom serial protocols.

This data source is commonly used with industrial sensors, meters, legacy PLCs, barcode scanners, GPS receivers, weather stations, and any device that transmits data over a serial port using a custom text or binary protocol.

Overview

Property	Value
Module	mangoAutomation-Serial
Protocol	RS-232/RS-485/RS-422
Direction	Bidirectional
Typical Use	Serial port communication with devices

Prerequisites

• A serial port available on the Mango server (RS-232 or RS-485). This can be a physical serial port, a USB-to-serial adapter, or a virtual serial port.
• The serial port must be recognized by the operating system (e.g., /dev/ttyS0 or /dev/ttyUSB0 on Linux, COM1 on Windows).
• Knowledge of the device's serial communication parameters: baud rate, data bits, stop bits, and parity.
• Understanding of the device's message format: what messages look like, how they are terminated, and how to identify and extract values using regular expressions.
• Appropriate serial cable and any required RS-232/RS-485 converters.

Configuration

Data Source Settings

Setting	Description
Name	A descriptive name for the data source.
Serial port	The system serial port to use (e.g., /dev/ttyUSB0, COM3).
Baud rate	Communication speed in bits per second. Must match the device (common values: 9600, 19200, 38400, 57600, 115200).
Data bits	Number of data bits per character (typically 8).
Stop bits	Number of stop bits (typically 1).
Parity	Error-checking mode: None, Even, or Odd. Must match the device.
Read timeout	Milliseconds the data source waits before considering the current buffer contents as a complete message. Timeouts less than 1 ms are not allowed. Used only when a terminator is not configured.
Use terminator	Whether messages end with a specific byte pattern (see below).
Message terminator	The byte pattern that marks the end of a message (e.g., \r, \n, \r\n). Only used when "Use terminator" is checked.
Message regex	A regular expression applied to each incoming message to identify and route it to the correct data point.
Point identifier group	The capture group number from the message regex that contains the point identifier.
Configuration in hex	When checked, all regex matching and configuration values operate on the hexadecimal representation of the binary data (see below).
Log I/O	When checked, all serial communications are logged to a file for debugging. The log file name is displayed below the checkbox.
Maximum message size	If the serial input buffer reaches this size without a complete message being identified, the buffer is discarded to prepare for new messages.

Message Completion

The data source needs to know when a complete message has been received. There are two mechanisms:

Using a Terminator

When Use terminator is checked, the data source scans incoming bytes for the configured terminator pattern. As soon as the terminator is found, the accumulated bytes (including the terminator) are treated as a complete message and passed to the regex matching engine.

This is the preferred method when the device uses a consistent message terminator (e.g., carriage return, line feed, or a specific byte sequence).

Using a Read Timeout

When Use terminator is unchecked, the data source waits for serial silence lasting at least the read timeout duration. Once the timeout expires without receiving any new bytes, the buffer contents are treated as a complete message.

This method is useful for devices that do not use a consistent terminator but instead send burst messages with pauses between them.

Message Regex and Point Routing

The message regex is applied to each complete message. It serves two purposes:

1. Validation: If the regex does not match, the message is discarded.
2. Point identification: The capture group specified by point identifier group extracts a string that is compared against each data point's point identifier. The data point whose identifier matches receives the message for value extraction.

Remember that regex group 0 is the entire match, group 1 is the first set of parentheses, group 2 is the second, and so on.

Hex Mode

When Configuration in hex is checked, the raw binary data received on the serial port is converted to its hexadecimal string representation before regex matching. This is necessary when the device sends binary (non-UTF-8) data. All regex patterns, point identifiers, and value extraction operate on the hex string.

For example, a raw binary message 0x01 0x03 0x02 0x00 0x00 0xB8 0x44 becomes the hex string 01030200000b844, and the regex patterns match against this string.

Data Point Configuration

Setting	Description
Data type	The Mango data type (Binary, Numeric, Alphanumeric, Multistate). The extracted value is converted from its string representation to this type.
Point identifier	A string that is compared against the message regex's point identifier group to determine if a given message belongs to this point. Must be an exact match.
Value regex	A regular expression applied to the entire message to extract this point's value.
Value group	The capture group number from the value regex that contains the point's value.

Data Type Conversion

Data Type	Hex Mode	Non-Hex Mode
Alphanumeric	The extracted hex string as-is	Raw UTF-8 string
Binary	0 = false, 1 = true	Case-insensitive true or false strings
Multistate	2 or 4 bytes converted to integer	String representation parsed as integer (e.g., "124" becomes 124)
Numeric	4 bytes (float) or 8 bytes (double) converted to floating point	String representation parsed as float (e.g., "1234.3" becomes 1234.3)

Common Patterns

Example: Modbus-Like Hex Protocol

A device sends binary messages where the first byte is the device address and the remaining bytes are data.

Data Source Settings:

• Read timeout: 5 ms
• Use terminator: No
• Message regex: ([0-9]{2}).*
• Point identifier group: 1
• Configuration in hex: No (the hex message is already in string form)
• Maximum message size: 1024

Example message (hex): 0103020000b844

Data Point:

• Point identifier: 01 (matches device address in first byte pair)
• Value regex: [0-9]{2}(.*)
• Value group: 1
• Captured value: 03020000b844

Example: UTF-8 Text Protocol

A device sends text messages with a prefix identifier, a keyword, and a value, terminated by carriage return.

Data Source Settings:

• Read timeout: 1000 ms
• Use terminator: Yes
• Message terminator: \r
• Message regex: ([0-9]{2})HelloWorld.*\r
• Point identifier group: 1
• Configuration in hex: No
• Maximum message size: 1024

Example message: 01HelloWorldtrue\r

Data Point:

• Point identifier: 01
• Value regex: [0-9]{2}HelloWorld(.*)\r
• Value group: 1
• Captured value: true

GPS Receiver

GPS receivers commonly output NMEA sentences over serial. Each sentence starts with $GP and a sentence type code, followed by comma-separated fields, and ending with a checksum and \r\n.

• Use terminator: Yes, \r\n
• Message regex: \$GP(\w{3}),.*
• Point identifier group: 1

Create data points for each NMEA sentence type (e.g., identifier GGA for fix data, RMC for recommended minimum) with value regexes that extract specific fields.

Barcode Scanner

Many barcode scanners output the scanned code as a string followed by a carriage return.

• Use terminator: Yes, \r
• Message regex: (.*)
• Point identifier group: 1
• Data type: Alphanumeric

Since each scan is a single value, a single data point can capture all scans.

Test String Utility

The data source includes a test utility that accepts an example message and compares it against the current configuration. Enter an expected message and the utility displays:

• Whether the message regex matches.
• Which point identifier was extracted.
• Whether any existing data points match the identifier.
• The extracted value for each matching point.

Errors are displayed in red. This is invaluable for debugging regex patterns before connecting to the actual device.

Troubleshooting

No Data Received

1. Serial port not recognized -- verify the serial port name matches the system device (check with ls /dev/tty* on Linux or Device Manager on Windows).
2. Baud rate mismatch -- if the baud rate does not match the device, data will be garbled or not received at all. Verify against the device documentation.
3. Communication parameters -- data bits, stop bits, and parity must all match the device settings.
4. Cable issues -- verify the serial cable is connected and, for RS-232, that the correct pins are wired (TX to RX, RX to TX). RS-485 requires correct A/B polarity.
5. Permissions -- on Linux, the Mango process must have read/write access to the serial device file. Add the Mango user to the dialout group or adjust permissions.
6. USB adapter not detected -- USB-to-serial adapters may require drivers. Check that the adapter appears as a serial device in the operating system.

Messages Garbled or Partial

1. Read timeout too short -- if not using a terminator, a timeout that is too short may split a single device message into multiple incomplete messages. Increase the read timeout.
2. Wrong terminator -- if the configured terminator does not match the device's actual message terminator, messages will accumulate in the buffer until the maximum message size is reached, then be discarded.
3. Buffer overflow -- if the maximum message size is reached before a complete message is identified, the buffer is discarded. Increase the maximum message size or fix the terminator/timeout configuration.
4. Hex mode mismatch -- if the device sends binary data but hex mode is not enabled, the data will appear as garbled text and regexes will not match.

Regex Not Matching

1. Test with the test utility -- use the built-in test string feature to verify the regex against an expected message.
2. Escape sequences -- remember that backslashes in regexes may need double escaping depending on the context.
3. Group numbering -- group 0 is the entire match. The first set of parentheses is group 1.
4. Hex vs. text -- in hex mode, the regex operates on the hex string representation (e.g., 01030200), not the raw binary bytes or their ASCII equivalents.

I/O Logging

Enable Log I/O to capture all serial traffic to a log file. This is the most effective debugging tool for serial communication issues. The log shows exactly what bytes are sent and received, helping to identify:

• Whether the device is sending data at all.
• Whether messages are complete or fragmented.
• The exact format and content of messages for crafting regexes.

Review the log file location displayed below the Log I/O checkbox after saving the data source.

Performance Concerns

1. High message rate -- if the device sends messages at a very high rate, regex processing may fall behind. Simplify regexes or increase the maximum message size to batch processing.
2. Many data points -- each incoming message is compared against every data point's identifier. With hundreds of points, this comparison loop can become significant. Ensure point identifiers are as specific as possible.

Related Pages

• Data Sources Overview — General data source and data point concepts
• TCP/IP Data Source — General-purpose TCP/IP socket communication for network-based devices
• Modbus Data Source — Structured serial protocol for industrial device communication
• DNP3 Data Source — DNP3 serial connections for SCADA outstations
• Data Source Performance — Tuning poll intervals for serial communication