Web Port - Modbus integration

At the moment this article only exists in english.

Purpose and scope

This document provides practical guidance for configuring, validating, and troubleshooting Modbus communication between Web Port and Modbus-enabled devices. It is intended to help identify common integration issues related to network connectivity, Modbus addressing, device settings, tag configuration, and RTU/TCP gateway behavior.

Communication settings

Modbus TCP device settings

For a Modbus TCP device, configure the device IP address and TCP port in Web Port. The standard Modbus TCP port is 502 unless the installation uses a custom port. If the device uses a Modbus slave address other than 1, configure the slave address explicitly.

Picture 1. Example Web Port device settings for Modbus TCP.

Modbus RTU devices through RTU/TCP gateway

When Modbus RTU devices are connected through an RTU/TCP gateway, create a separate Web Port device for each RTU slave. This isolates failures: if one RTU slave has repeated read/write errors, Web Port resets only that device instead of affecting all devices in the RTU loop.

1. For the first RTU device, enter the gateway IP address in (TCP) Host and the gateway listening port in (TCP) Port.
2. Set the correct slave address for the first RTU device.
3. For additional RTU devices, link each device to the first gateway device and configure each unique slave address.

Picture 2. Example Web Port device settings for multiple Modbus RTU devices through an RTU/TCP gateway.

Communication settings using Web Port OpenVPN Management

Device settings

When the connection uses Web Port OpenVPN Management, configure Web Port with the OpenVPN tunnel IP address instead of the physical device IP address. The tunnel IP address is visible in the OpenVPN Management client list. Router port forwarding then routes traffic from the tunnel address to the actual Modbus device address.

Picture 3. OpenVPN Management client view showing the tunnel IP address.

Router Settings (Teltonika router)

OpenVPN connection

Teltonika user interfaces vary between firmware versions and device models, but the general process is to import the OpenVPN configuration generated by Web Port into the router and run the router as an OpenVPN client.

1. Open Services > VPN > OpenVPN.
2. Add a new OpenVPN instance.
3. Set the role to Client.
4. Assign a clear name, such as Web Port.
5. Upload the Web Port OpenVPN configuration file and save the configuration.

Picture 4. Example Teltonika OpenVPN client configuration.

Port forwarding

Port forwarding is required when Web Port connects through the OpenVPN tunnel and the Modbus device is behind the router. Create a port forward rule from the OpenVPN zone to the device IP address and Modbus port. For Modbus TCP, the port is commonly 502.

• Use the port configured in Web Port as the external port on the router.
• Set the internal IP address to the actual LAN IP address of the Modbus device.
• Set the source zone to openvpn so traffic from the tunnel is allowed.
• If Web Port has different port in device settings than device actually uses, set Web Port’s port to external port and device’s port to internal port

Picture 5. Example Teltonika port forward rule for a Modbus device.

Scheduled reboot

Set a scheduled reboot for the router once a week. This may prevent communication issues.

Updating firmware

When updating router firmware, update from file, not server. Update from server has caused issues where OpenVPN or port forwards don’t work even if they appear to be functional.

Multiple Modbus devices in the same OpenVPN tunnel

If multiple Modbus devices are connected to the same router, configure a unique port for each device in Web Port and create matching router forwarding rules. This allows all devices to share the same OpenVPN tunnel IP while still forwarding traffic to different internal device addresses.

Picture 6. Example Web Port settings using separate ports for two devices behind one tunnel.

Picture 7. Example router port forwarding rules for two Modbus devices.

Teltonika router as a Modbus RTU/TCP gateway

Routers with a serial port can be configured as a Modbus TCP over serial gateway. In this topology, the OpenVPN tunnel provides a TCP path to the router, and the router forwards Modbus TCP requests to the serial RTU bus.

1. Configure the OpenVPN tunnel between the router and Web Port.
2. Go to Services > Modbus > Modbus TCP over Serial Gateway and create a new gateway configuration.
3. Enter the correct serial settings, including baud rate, data bits, parity and stop bits.
4. Set Listening IP to 0.0.0.0 so the gateway listens on all relevant router interfaces.
5. Set the same TCP port that is configured in the Web Port device settings.
6. Set Slave ID configuration type to Obtained from TCP so slave IDs are controlled from Web Port.
7. Under “Add new instance”, add openvpn interface and set IP address of the OpenVPN tunnel to Allow IP field (1).
   

Picture 8. Example Modbus TCP over serial gateway configuration.

In Web Port, point the device to the router tunnel IP address and the gateway port.

Picture 9. Example Web Port settings for a Teltonika Modbus gateway.

Tags

Modbus registers are memory locations used to exchange values such as temperatures, pressures, meter readings, setpoints, device states, and control signals. Correct tag configuration depends on the register type, data type, register size, scaling, and vendor-specific address notation.

Tag datatype

The datatype defines how Web Port reads and writes the value. Select the datatype based on whether the value is signed or unsigned and how many 16-bit registers are used by the value.

Datatype depends on things like:

• Is the value unsigned or signed. Signed values can present negative and positive values whereas unsigned values are only positive.
• Is value presented in one or multiple registers (16-bit = one register, 32-bit = two consecutive registers, 64-bit = four consecutive registers)

Datatype in Web Port depends on size of the value that is read:

• Coils and discrete inputs use DIGITAL.
• 16-bit signed values use INT; 16-bit unsigned values use UINT.
• 32-bit signed values use LONG; 32-bit unsigned values use ULONG.
• 64-bit signed values use INT64; 64-bit unsigned values use UINT64.
• 32-bit floating point values use REAL.

Tag address

Modbus manufacturers use different address formats. Web Port supports full register addressing and function-code addressing. Full register addressing is recommended when tag lists are opened or edited in Excel, because function-code formats can be interpreted unexpectedly by spreadsheet software.

There are also many different styles of presenting addresses between different manufacturers. Here are some examples of how holding register 40100 could be presented:

Holding   Register	Zero-Based Offset	One-Based Offset	Hex Offset	Register Type + Address	Function Code + Address
40100	99	100	0x0064	Holding Register 100	FC03, 100

Tag address for Coils

Coils are single bit read/write values used for outputs and control signals. Address range using full register is between 1 - 65536 and with function code 1:1 - 1:65536. Datatype should be DIGITAL.

Picture 10. Example coil address configuration in Web Port.

Tag address for Discrete inputs

Discrete inputs are single bit read-only values. Address range using full register is between 10001 - 165536 and with function code 2:1 - 2:65536. Datatype should be DIGITAL.

Picture 11. Example discrete input address configuration in Web Port.

Tag address for Input registers

Input registers are read-only values meant for measurements and statuses. Address range using full register is between 30001 - 365536 and with function code 4:1 - 4:65536. Datatype can be INT, UINT, LONG, ULONG, INT64, UINT64 or REAL.

Picture 12. Example input register address configuration in Web Port.

Tag address for Holding registers

Holding registers are read/write values meant for measurements, setpoints and statuses. Address range using full register is between 40001 - 465536 and with function code 3:1 - 3:65536. Datatype can be INT, UINT, LONG, ULONG, INT64, UINT64 or REAL.

Picture 13. Example holding register address configuration in Web Port.

Using Boolean expressions in tag address

A Modbus address can include a Boolean comparison that converts a numeric value into 1 or 0 depending on whether the condition is true. Append a comparison operator and a comparison value to the address, for example >, <, >=, <=, <>, or =.

Value can be inverted using =0 in address. The expression 40001=0 returns 1 when register 40001 equals 0 and returns 0 when the register value is 1.

Reading specific bit from value

A specific bit can be read by appending a dot and the bit index to the address. For example, 40001.1 reads the second bit from the right. If the tag value is 2 and the datatype is INT, the binary value is 0000 0000 0000 0010, so the expression returns 1.

Tips & Tricks

Local schedules

If the Modbus device has local schedules, a scheduling script is required in Web Port. Because schedule implementations vary by manufacturer, a universal script is normally not possible. Start from an existing Web Port support example when available and adapt it to your device. Examples can be found here.

Poll delay for slower devices

Some devices restrict amounts of polling. In that case setting a poll delay between polls is necessary to prevent connection issues due to too intense traffic towards device.

Debugging in Web Port

Web Port tools

Web Port includes built-in debug tools for tag read/write operations, IO reads, and IP ping tests. These tools are available under System settings > Debug and are useful for validating both network reachability and register-level communication.

Picture 14. Example Web Port debug tools.

Debug logs

When Debug mode is checked in device settings, there will be more info from device. All the trend and alarm cycle readings and value writings will be printed there. Also writing errors are logged in debug logs.

Device errors

Device is changing state between ok and offline

Web Port resets Modbus devices after 5 consecutive read/write errors. This can cause unstable behavior where device is in OK state for a while and then goes OFFLINE and so on. That can be confusing when some tags can read values successfully and device keeps resetting.

This usually happens if device in Web Port has wrong slave address, there are tags that have invalid address or if multiple RTU devices are connected via single Web Port device and one or more of the devices fail to communicate.

To see which tags are causing the issue, set device on debug mode and monitor debug logs. If there are lot of messages, start logging to file and download debug log to your machine so it’s easier to find tags that don’t receive value. Look for tags that receive empty values, you can search for the with “value: ,”. This is how tags that don’t receive value look in debug logs:

Picture 15. . Example debug log entries showing tag read activity.

Once tags that don’t receive values are found. Check tag status of those tags in tag list to get more info about the issue.

Picture 16. Example tag status showing an illegal data address exception.

Communication error

If device is in Communication error state, first step of debugging would be to try to ping the IP address of the device. NOTE that ping might be disabled in some networks. If OpenVPN Management tool’s connection is used, pinging from Web Port tells if connection to the router is working. Ping the device on router as well.

If ping goes through, it could be that either port is wrong or device isn’t listening to that port. It could be that port forwarding’s aren’t done or are configured wrong. Double check device port in device settings and in router settings, if you have access to it. Otherwise ask IT if ports are open.

Tag errors

Reply-timeout

This error can have several causes. If all tags for the device are reporting a Reply Timeout error, first verify that the Slave Address configured in the device settings is correct.

Some devices respond more slowly than others and may generate this error even though communication is otherwise functioning correctly. In such cases, increase the Timeout [ms] value in the device settings. The default timeout is 1000 ms (1 second). Increasing this value may resolve the issue.

Illegal Data Address Exception

This error indicates that the register address specified in the request is not valid for the device.

Verify that the correct register type and address are being used. For example, the request may be attempting to read Holding Register 40100 when the value is in Input Register 30100.

Also ensure that the requested register address exists and is supported by the device.

Illegal Function Code Exception

This error indicates that the device does not support the requested Modbus function code.

Possible causes include:

• The requested function is not implemented by the device or is only supported by a newer device model.
• The request is using the wrong register type. For example, the driver may be attempting to read a Holding Register when the value is in an Input Register.
• The device is not in a state where it can process the request, such as when it has not been fully configured or initialized.

Verify that the correct register type and address are configured and confirm that the device supports the requested Modbus function.

Incorrect value

An incorrect value can be caused by several factors, including:

• An incorrect register address.
• An incorrect Byte Order setting.
• For floating-point values, the Swapped Floats option may need to be enabled.

If some tags display the correct values while others do not, the issue is most often caused by an incorrect Byte Order setting for the affected tags.

A common symptom is that values stored in a single register are displayed correctly, while values stored across multiple consecutive registers are incorrect. In this case, verify that the Byte Order setting matches the device's data format.

Note: An incorrect value may be caused by multiple configuration issues at the same time. For example, both an incorrect register address (offset) and an incorrect Byte Order setting may be present. As a result, some values may appear correct while others are displayed incorrectly. Always verify all relevant configuration settings when troubleshooting unexpected values.

Scaling is not correct

Scaling is common in Modbus integrations. Compare the Web Port scaling settings with the vendor Modbus register documentation. If scaling does not apply as expected, make sure the Format field is not empty; use formats such as 0 or 0.0 depending on the required decimal precision.

Picture 17. Example scaling configuration and values.

Offsetting the Modbus address

If all values appear incorrect, test for an address offset. If the documentation lists address 40010, test 40009 and 40011 to determine whether the manufacturer uses zero-based or one-based addressing.

Wrong datatype

In the Modbus driver, the Data Type determines how Web Port reads and writes values to and from the device, as described earlier in this guide. Verify that the selected data type matches the format of the data stored in the device. This ensures that Web Port reads the correct number of registers required to retrieve the value.

For example, if a register contains a signed integer but an unsigned data type (such as UINT, ULONG, or UINT64) is selected, any negative values will be interpreted as very large positive numbers.

Picture 18. Example of signed and unsigned datatype behavior.

For values that span multiple registers, using a single-register datatype (INT) can appear correct while the value is small, but it fails once the value exceeds the 16-bit range.

Picture 19. Example where a small value still appears correct with an insufficient datatype.

Picture 20. Example where a larger value requires a multi-register datatype.

Byte order and swapped floats setting

If a value is stored across two or four consecutive registers, select the appropriate data type (LONG, ULONG, INT64, or UINT64) so that Web Port reads all required registers.

Different devices may use different byte orders to store multi-register values. If the configured Byte Order does not match the device, the displayed value will be incorrect.

The screenshots below demonstrate how the Byte Order setting affects values in Web Port. The correct value is 25, but when an incorrect byte order is used, the value is displayed as 1638400.

As shown in the examples, the **Byte Order** setting does not affect values stored in a single register. It only determines how bytes from multiple consecutive registers are combined to form a single value.

Picture 21. Example showing correct value interpretation with byte order configuration.

Picture 22. Example showing incorrect value interpretation when byte order is wrong.

For REAL values, use the Swapped floats setting when the device stores floating-point values in a different word order.

Device is green but tag reading timeout when using TCP/RTU gateway

If a Modbus TCP/RTU gateway device is in OK state, the TCP connection between Web Port and the gateway is working. If tag values still time out, verify the RTU side of the installation, including baud rate, parity, stop bits, permitted slave IDs, and serial wiring.

DrvModbus

More info about Modbus Driver here:
DrvModbus