Modbus Data Source

The Modbus data source allows Mango to communicate with industrial devices using the Modbus protocol. Mango supports both Modbus IP (TCP, TCP with keep-alive, UDP, and Encapsulated RTU-over-IP) and Modbus Serial (RTU and ASCII over RS232 or RS485). This is a polling data source -- Mango actively requests register values from slave devices at a configurable interval.

Modbus is one of the most widely used industrial protocols, found in PLCs, VFDs, power meters, temperature controllers, and thousands of other devices. Because Modbus devices vary widely in their register maps and capabilities, proper configuration requires the device documentation.

Overview

Property	Value
Module	mangoAutomation-Modbus
Protocol	Modbus TCP/IP and Serial RTU/ASCII
Direction	Bidirectional
Typical Use	Reading/writing registers on PLCs, RTUs, and industrial devices

Prerequisites

• Network access to the Modbus device (for Modbus IP) or a serial connection via RS232 or RS485 adapter (for Modbus Serial).
• The device's register map documentation, which specifies register addresses, data types, and read/write permissions.
• Knowledge of the device's slave ID (a number between 1 and 240).
• For Modbus IP: the device's IP address and port number (default is 502).
• For Modbus Serial: the serial port name, baud rate, and communication parameters (data bits, stop bits, parity).

Configuration

Data Source Settings (Modbus IP)

Every data source requires a Name, which can be any description.

Setting	Description
Update period	How often Mango polls the device for data.
Quantize	When checked, aligns poll times to even intervals (e.g., every 10 seconds on the :00, :10, :20 marks).
Timeout	Milliseconds to wait for a response before considering the request failed.
Retries	Number of times to retry a failed request before giving up.
Host	IP address or hostname of the Modbus device.
Port	TCP/UDP port number (default: 502).
Transport type	The network transport to use (see below).

Transport Types

Transport	Description	When to Use
TCP	Opens a new TCP connection for each poll cycle.	Infrequent polling or unreliable connections.
TCP with keep-alive	Opens one TCP connection and reuses it across polls. Reconnects automatically if the connection drops.	Recommended for most users. Efficient and robust.
UDP	Uses UDP datagrams for communication. More network-efficient but requires both Mango and the device to be directly visible on the network.	High-performance scenarios where Mango is on the same subnet.
Encapsulated	Modbus RTU frames sent over TCP/IP.	When communicating through an Ethernet-to-serial converter that does not translate Modbus TCP to RTU.

The Linger setting controls TCP socket close behavior. A negative value disables the linger feature. A value of zero forces an immediate close with a TCP RST. A positive value (in seconds) causes close to block while pending data is transmitted.

Additional Settings

Setting	Description
Contiguous batches only	When checked, Mango only combines register requests that form a contiguous address range. Uncheck this to allow Mango to optimize by combining non-contiguous registers into fewer requests.
Use multiple write commands only	Forces Mango to always use the "write multiple" Modbus function codes, even for single-register writes. Enable this if your device does not support single write commands.
Create device monitor points	Automatically creates binary data points that track whether each polled device is online. Useful for alerting on device failures.
Max read bit count	Maximum number of coils or discrete inputs to request in a single read operation.
Max read register count	Maximum number of holding or input registers to request in a single read operation.
Max write register count	Maximum number of registers to write in a single write operation.
Log IO	Enables I/O logging to a file named modbusIO-<dataSourceId>.log in the Mango logs directory.
Discard data delay (ms)	How long data remains in the receive buffer before being discarded as stale. A value of 0 means never discard.

Example: Modbus IP Data Source Configuration

{
  "name": "Building-1 Power Meters",
  "updatePeriod": { "periods": 5, "type": "SECONDS" },
  "quantize": true,
  "timeout": 1500,
  "retries": 2,
  "host": "192.168.1.100",
  "port": 502,
  "transportType": "TCP_KEEP_ALIVE",
  "contiguousBatchesOnly": false,
  "maxReadRegisterCount": 125,
  "maxReadBitCount": 2000,
  "logIO": false
}

Back-Off Strategy

When a connection fails, rather than retrying every poll period (which can stress the network), Mango uses an exponential back-off strategy:

• Scale Factor: Determines how fast the wait time between retries increases. Must be greater than 1 (e.g., 1.5, 2.0). Higher values cause the back-off to grow faster.
• Max back-off period: The maximum time Mango will wait between retry attempts. Once this ceiling is reached, retries occur at this fixed interval.

Data Source Settings (Modbus Serial)

Serial Modbus uses the same polling, timeout, retry, batching, and I/O logging settings as Modbus IP. The transport-specific settings are:

Setting	Description
Baud rate	Communication speed (e.g., 9600, 19200, 38400, 115200). Must match the device.
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.
Flow control in / out	Hardware or software flow control settings.
Echo	Enable for RS485 networks that echo transmitted data.
Encoding	RTU (binary, most common) or ASCII. See your device documentation.

When sharing a serial port between data sources, I/O logging will capture data for all data sources on that port, but only if a data source with Log IO enabled was started first. You cannot add I/O logging to a serial master that is already running.

Data Point Configuration

Both serial and IP Modbus data points use the same point locator settings:

Setting	Description
Device ID	The Modbus slave address (1 to 240).
Register range	Which of the four Modbus register ranges to read from (see table below).
Offset	The 0-indexed register address within the chosen range.
Modbus data type	How to interpret the raw register bytes (see data types table).
Bit	For binary values encoded as individual bits within a register.
Settable	Whether Mango can write values to this register.
Multiplier	Scale factor applied to read values: displayed = (raw * multiplier) + additive. The reverse is applied on writes.
Additive	Offset applied after the multiplier.

Register Ranges

Range	Hex Address	Size	Access	Mango Data Types
Coil Status	0x00000 - 0x0FFFF	1 bit	Read/Write	Binary
Input Status	0x10000 - 0x1FFFF	1 bit	Read Only	Binary
Input Register	0x30000 - 0x3FFFF	16 bits (1 word)	Read Only	Binary, Numeric
Holding Register	0x40000 - 0x4FFFF	16 bits (1 word)	Read/Write	Binary, Numeric

Example: Power Meter Register Map

A typical power meter (e.g., Acuvim II, Shark 200) maps readings to holding registers like this:

Register   Offset   Data Type                  Description
--------   ------   -------------------------  --------------------------
40001      0        FOUR_BYTE_FLOAT            Voltage L1-L2 (V)
40003      2        FOUR_BYTE_FLOAT            Voltage L2-L3 (V)
40005      4        FOUR_BYTE_FLOAT            Voltage L3-L1 (V)
40007      6        FOUR_BYTE_FLOAT            Current L1 (A)
40009      8        FOUR_BYTE_FLOAT            Current L2 (A)
40011      10       FOUR_BYTE_FLOAT            Current L3 (A)
40013      12       FOUR_BYTE_FLOAT            Active Power Total (kW)
40021      20       FOUR_BYTE_FLOAT            Power Factor

The corresponding Mango data point configuration for the first register:

{
  "name": "Voltage L1-L2",
  "deviceId": 1,
  "registerRange": "HOLDING_REGISTER",
  "offset": 0,
  "modbusDataType": "FOUR_BYTE_FLOAT",
  "settable": false,
  "multiplier": 1.0,
  "additive": 0.0
}

Note the offset is 0, not 40001 -- Mango uses 0-based indexing within the selected register range.

Important note on indexing: Mango uses 0-based indexing for register offsets. Many Modbus device manuals use 1-based indexing. If your device documentation lists register 40001, the Mango offset is 0 in the Holding Register range. When register addresses include their range prefix (e.g., 0x30001), 1-based indexing is typically implied.

Modbus Data Types

Modbus does not define a standard byte order, so devices may use different endian conventions. Use this reference table to determine which data type matches your device. If you are unsure, try reading a known value with different data type settings until the displayed value matches the expected value.

Data Type	Registers	Byte Order
TWO_BYTE_INT_UNSIGNED	1	Big-endian (b1 b0)
TWO_BYTE_INT_SIGNED	1	Big-endian (b1 b0)
TWO_BYTE_INT_UNSIGNED_SWAPPED	1	Little-endian (b0 b1)
TWO_BYTE_INT_SIGNED_SWAPPED	1	Little-endian (b0 b1)
FOUR_BYTE_INT_UNSIGNED	2	Big-endian (b3 b2 b1 b0)
FOUR_BYTE_INT_SIGNED	2	Big-endian (b3 b2 b1 b0)
FOUR_BYTE_INT_UNSIGNED_SWAPPED	2	Word-swapped (b1 b0 b3 b2)
FOUR_BYTE_INT_SIGNED_SWAPPED	2	Word-swapped (b1 b0 b3 b2)
FOUR_BYTE_FLOAT	2	Big-endian IEEE 754
FOUR_BYTE_FLOAT_SWAPPED	2	Word-swapped IEEE 754
EIGHT_BYTE_INT_UNSIGNED	4	Big-endian
EIGHT_BYTE_INT_SIGNED	4	Big-endian
EIGHT_BYTE_FLOAT	4	Big-endian IEEE 754
EIGHT_BYTE_FLOAT_SWAPPED	4	Word-swapped IEEE 754

Additional types include BCD (binary-coded decimal) and MOD10K variants. The _SWAPPED suffix always indicates word-level byte swapping, and _SWAPPED_SWAPPED indicates full byte reversal. If your device documentation refers to "Mod10" or "Mod10K" data types, use the corresponding MOD_10K types.

The Multistate numeric checkbox allows numeric Modbus values to be stored as multistate points in Mango, which is useful for register values that represent discrete states (such as operating modes).

Node Scanning

Mango can scan a Modbus network to discover available device nodes. The scan utility iterates through device IDs 1 to 240, sending a ReadExceptionStatus request (function code 7) to each. Devices that respond within the configured timeout are listed as available. Note that not all devices support function code 7, so some devices may not appear in the scan even though they are present on the network.

Common Patterns

Power Meter with Mixed Data Types

A typical power meter might expose voltage as a 4-byte float in holding registers 0-1, current in registers 2-3, and power factor as a 2-byte unsigned integer in register 4. Create three data points with different Modbus data types, all on the same device ID. Mango will batch these into a single request if contiguous batches only is unchecked.

Multiple Devices on One Network

When polling multiple Modbus devices, use a single Modbus IP data source with different device IDs for each device. This is more efficient than creating separate data sources because it shares the TCP connection and poll cycle. However, if the devices have very different polling requirements (some fast, some slow), consider splitting them into separate data sources.

[
  { "name": "Power Meter Floor 1", "deviceId": 1, "registerRange": "HOLDING_REGISTER", "offset": 0, "modbusDataType": "FOUR_BYTE_FLOAT" },
  { "name": "Power Meter Floor 2", "deviceId": 2, "registerRange": "HOLDING_REGISTER", "offset": 0, "modbusDataType": "FOUR_BYTE_FLOAT" },
  { "name": "VFD Pump 1 Speed",   "deviceId": 10, "registerRange": "HOLDING_REGISTER", "offset": 100, "modbusDataType": "TWO_BYTE_INT_UNSIGNED", "multiplier": 0.1 }
]

Writing to Coils and Registers

To write values from Mango to a Modbus device, ensure the data point is marked as Settable and that it is in a writable register range (Coil Status or Holding Register). You can then set values through the Mango UI, REST API, or scripting. When writing numeric values, the multiplier and additive are applied in reverse.

Troubleshooting

Polls Being Aborted

If the runtime status shows aborted polls, the poll duration exceeds the poll period. Enable I/O logging and check the modbusIO-<dataSourceId>.log file. Look for:

• Constant stream of requests with no gaps between poll cycles -- this indicates poor batching. Uncheck "Contiguous batches only" and increase the max read register count.
• Long delays between request and response -- the device is slow to respond. Check device load, network latency, or consider reducing the number of points.

When polls are aborted, the next poll starts on the original schedule (based on when the data source was started), not on the completion time of the overrun poll.

Timeout Errors

If you see timeout events, verify:

1. The device IP address and port are correct.
2. The device ID (slave address) matches the device configuration.
3. There are no firewall rules blocking port 502.
4. The device is not overloaded with requests from other masters.

Wrong Values

If values appear incorrect (e.g., very large numbers, negative when they should be positive, or decimal places in the wrong position):

1. Check the data type -- try swapped variants. Many devices use word-swapped byte order.
2. Check the offset -- remember Mango uses 0-based indexing.
3. Check the multiplier/additive -- these may be misconfigured.
4. Consult the device register map -- verify the documented register address, data type, and scaling factor.

I/O Log Analysis

The I/O log shows outgoing (O) and incoming (I) messages with timestamps:

2026-02-17 14:30:00.001 O: 00 01 00 00 00 06 01 03 00 00 00 0A
2026-02-17 14:30:00.023 I: 00 01 00 00 00 17 01 03 14 43 6B 00 00 43 6C 00 ...
2026-02-17 14:30:05.001 O: 00 02 00 00 00 06 01 03 00 00 00 0A
2026-02-17 14:30:05.019 I: 00 02 00 00 00 17 01 03 14 43 6B 40 00 43 6C 40 ...

In this log, O lines are requests from Mango and I lines are device responses. The 5-second gap between groups matches the configured poll period, indicating healthy operation. The 22ms response time (14:30:00.001 to 14:30:00.023) shows a responsive device.

Look for:

• Tightly grouped timestamp entries separated by the poll interval = healthy operation.
• Continuous requests with no visible period grouping = poll duration exceeds poll period.
• Requests with no matching response = device not responding (timeout will follow).

Related Pages

• Data Sources Overview — General data source and data point concepts
• Data Source Performance — Tuning poll periods, batching, and timeout calculations
• SNMP Data Source — Another polling protocol commonly used alongside Modbus for network devices
• Modbus Troubleshooting — Systematic diagnosis of Modbus communication failures
• Modbus Point List Requirements — Reference for the information needed to configure Modbus points