MODBUS TCP Interface

Note: This article is written for the Ethernet Gateway 4. There are slight differences in the MODBUS TCP Interface of the Ethernet Gateway 3. This should be considered when using the Ethernet Gateway 3.

The Monnit Ethernet Gateway offers a MODBUS TCP Interface by which you can access gateway and sensor information directly via MODBUS TCP poll requests. Modbus TCP is the Modbus RTU protocol with a TCP interface that operates over Ethernet. This interface can be used without the Default Server Interface (Monnit software) active or as a standalone interface. Using the Interface in a standalone configuration enables the gateway to be used on a local private network (without the use of Monnit software) by polling the gateway via MODBUS TCP requests.

Note: The MODBUS TCP Interface is a read-only interface. Therefore there is no manner by which to send data or configure the gateway or sensors through the MODBUS TCP Interface.

!!Important!! There are important considerations when operating an Ethernet Gateway on a private network without the use of Monnit software. The gateway must be unlocked, and there are certain limitations in terms of configuring sensors. Please review the article at the following link for detailed information on using the gateway on a private network with the Default Server Interface disabled. If you are using the MODBUS TCP Interface in conjunction with the iMonnit software (such as iMonnit.com, there is no need to Unlock your gateway. Using the Ethernet Gateway 4 on a private MODBUS TCP or SNMP Network.


Activating the MODBUS TCP Interface

The MODBUS TCP Interface on an Ethernet gateway is inactivate by default. There are two manners by which you can activate the interface. It can be activated through iMonnit Online (or other Monnit software) or locally using the HTTP Interface (local configuration page).

Note: In order to effectively use your gateway with the MODBUS TCP Interface, you will need to be able to poll your gateway at the same IP address. Therefore you will need to configure your gateway to operate with a static IP address. For more information on this, see the relevant article Setting Up a Static IP.

Activating the MODBUS TCP Interface using iMonnit Online

These steps assume that your gateway has been added to your iMonnit account.

  1. Log into your iMonnit Online account.
  2. Select Gateways from the primary menu (left-hand side bar).
  3. Select the gateway for which you wish to activate the MODBUS TCP Interface.
  4. Select the Settings tab (Gear icon) in the upper navigation bar.
  5. Select the Interface sub-tab (in the gray area toward the center of the screen).
  6. Toggle the switch for “Activate MODBUS Interface” to On.
  7. Click the Save button.
  8. Click the Continue button.
    Upon the subsequent gateway check-in, this interface will be enabled and can be polled to retrieve MODBUS data.

With default configuration, the TCP Timeout Minutes is set to 5 minutes, and the Port number is set to 502. If you need to modify these configurations, you can do it under the Modbus sub-tab that now appears in the gateway Settings.

Activating the MODBUS TCP Interface using the HTTP Interface (local configuration page)

Another way of adjusting your Modbus TCP settings is through the gateway’s HTTP Interface (local configuration page) through a browser. The local interface is accessible from a web browser on the same local network. This interface can be enabled from iMonnit Online, or locally. For information on accessing the HTTP Interface through a browser, see the following articles (depending on whether your gateway is communicating with iMonnit Online or not):

Local Configuration Page (HTTP Interface) of the Ethernet Gateway 4 through iMonnit Online
Ethernet Gateway 4 - Accessing local configuration page (HTTP Interface) Locally

  1. Launch a web browser, and navigate to the IP address of your gateway.
  2. Select the Data Interfaces tab.
  3. Select the MODBUS TCP Interface tab.
  4. Select the Active option.
  5. Enter desired configurations.
    Data Expiration – This is the number of minutes that data can be received from a register on the MODBUS TCP Interface. Once the age of the data held in the register has reached this threshold, it is cleared out.
    Socket Timeout – The amount of time in seconds the gateway waits for communication from the server before the connection is refused.
    Listening Port - This is the number for where specifically in the server data from the gateway is received.
  6. Click the Save Changes button.
    The gateway will reinitialize, and when it is up and running, the MODBUS TCP Interface will be active.

Adding Sensors


There are two manners by which you can add sensors to the gateway’s Wireless Sensor Network. This can be done using Monnit software (such as iMonnit Online) by adding the gateway and sensors to a Network in the software. If you are operating your gateway without the use of Monnit software (Default Server Interface disabled), sensors can also be added to gateways using the HTTP Interface (local configuration page). It is recommended that if utilizing Monnit software, you add devices through the software and not using the local interface.

The Sensor List (Wireless Device Network) of a gateway has some important behaviors. You can find detailed information on the Sensor List in the following article: Understanding Gateway Sensor Lists .

It is also important to understand the Reform command and how it effects the gateway’s Sensor List. Information on the Reform command can be found in this article: [Reform Gateway Network]/support/knowledgebase/gateways/reform-gateway-network/ “how to reform the gateway network”)

Adding sensors using iMonnit Online

If you haven’t done so already, you can build your wireless network in the iMonnit portal. This is done simply by adding your gateway and sensors to the same Network. For step by step instructions on setting up your sensor(s) and gateway(s) please visit this article: Getting Started Registering Devices.

Adding sensors using the HTTP Interface (local configuration page)

Alternatively, you can add sensors using the gateway’s HTTP Interface (local configuration page). For information on accessing the gateway’s local configuration page, see the following article: Ethernet Gateway 4 - Accessing local configuration page (HTTP Interface) Locally.

To add sensors using the HTTP Interface (local configuration page):

  • Access the gateway’s HTTP Interface through a web browser.
  • Click the General Options tab.
  • Click the Wireless Sensor Network Configuration tab.
  • Enter the Device ID in the Device ID field.
  • Enter the Security Code in the Security Code field.
  • If you are manually configuring the Slot, enter the value for the desired Slot Index (otherwise leave this field blank).
  • Click the Add Device button.
    After adding the device to the Wireless Sensor Network, your gateway will allow the device to Join and report data in the corresponding registers for that slot.
    Wireless Sensor Network Configuration

MODBUS Registers


MODBUS registers are numerical identifiers referring to 16-bit data stores. The Modbus TCP Interface will store all data values in 16-bit registers. In some cases where a value is greater than 16 bits (such as the device ID which is 32 bits) the value is spread across multiple registers and must be concatenated in order to interpret the data.

With the Ethernet Gateway 4, there are 5 registers which can be polled to provide gateway information (the Ethernet Gateway 3 has 4).
There are 16 registers for each sensor added to the gateway’s Sensor List (8 of which are data registers where the sensor provides data from readings).

Note: Monnit gateways are MODBUS Slaves. The gateway does not offer a configuration for a slave ID.

Gateway Registers

These registers offer basic information on the gateway and it’s current configuration as displayed below. These registers are outlined below:
Field: Gateway ID_High
Description: The first 16 bits of a 32-bit serial ID number.
Holding Register: 40001
Data Address: 0

Field: Gateway ID_Low
Description: The last 16 bits of a 32-bit serial ID number.
Holding Register: 40002
Data Address: 1

Field: Gateway Version - Revision + Major
Description: The gateway firmware Revision and Major version numbers (1 byte each)
Holding Register: 40003
Data Address: 2

Field: Gateway Version - Minor + Release
Description: The gateway firmware Minor and Release version numbers (1 byte each)
Holding Register: 40004
Data Address: 3

Field: Gateway Device Count
Description: The number of devices in its wireless network
Holding Register: 40005
Data Address: 4

Sensor Registers

The gateway stores sensor data in consecutive banks of 16 registers for each sensor corresponding to the slot to which the sensor is assigned. 8 of the registers provide sensor information and 8 registers are reserved for data from sensor readings. Depending on the sensor type, not all 8 registers will be utilized (some sensors such as temperature sensors may only use the first data register while the remaining registers are unused). Any data field not utilized will hold a 0 value.

The registers and their data fields are outlined below:
Field: Sensor ID_High
Description: The first 16 bytes of a 32-byte serial number
Holding Register: 40101
Data Address: 100

Field: Sensor ID_Low
Description: The last 16 bytes of a 32 bytes serial ID number
Holding Register: 40102
Data Address: 101

Field: Device Type
Description: The unique type identifier for the sensor profile
Holding Register: 40103
Data Address: 102

Field: Data Age
Description: The number of seconds that have elapsed since the last data was retrieved
Holding Register: 40104
Data Address: 103

Field: Device Active
Description: 0 indicates no data for this slot, 1 indicates there is data for this slot
Holding Register: 40105
Data Address: 104

Field: Is Aware
Description: Becomes aware when a sensor threshold has been breached
Holding Register: 40106
Data Address: 105

Field: Voltage
Description: Battery voltage in centivolts
Holding Register: 40107
Data Address: 106

Field: RSSI
Description: Signal Strength indicator, RSSI value as percentage signal strength
Note: firmware version 1.0.6.5 and earlier report the percentage as the inverse percentage. A 75% signal reports a 25 value, 66% reports 34, 55 reports 45, etc.
Holding Register: 40108
Data Address: 107

Field: Data 1
Description: Sensor Data Field 1
Holding Register: 40109
Data Address: 108

Field: Data 2
Description: Sensor Data Field 2
Holding Register: 40110
Data Address: 109

Field: Data 3
Description: Sensor Data Field 3
Holding Register: 40111
Data Address: 110

Field: Data 4
Description: Sensor Data Field 4
Holding Register: 40112
Data Address: 111

Field: Data 5
Description: Sensor Data Field 5
Holding Register: 40113
Data Address: 112

Field: Data 6
Description: Sensor Data Field 6
Holding Register: 40114
Data Address: 113

Field: Data 7
Description: Sensor Data Field 7
Holding Register: 40115
Data Address: 114

Field: Data 8
Description: Sensor Data Field 8
Holding Register: 40116
Data Address: 115

The sensor in the next slot will use the following bank of 16 registers. Registers 40117 - 40132 are the next bank of 16 registers for the sensor in position 2, the sensor in position 3 will use registers 40133 – 40148 and so on for the number of sensors registered in the gateway.

Concatenating split registers

For data values that occupy more than a single register (such as the device ID which is 32 bits), the value must be concatenated in order to interpret the full value. See the example below:

In this example, we will look at a sensor with the ID 315234 registered to slot 2.
To get the ID High and ID Low, you would poll registers 40117 and 40118 (the first 2 registers in the bank of 16 for the sensor in slot 2). Polling these registers would give the following values if polled as decimal integers:
Register 40117: 3
Register 40118: 53090

You would then convert the values to Hexidecimal. Doing so gives you the following values:
Register 40117: 3
Register 40118: CF62

You would then concatenate (join together) the two values to get 3CF62.

Converting the hexadecimal value of 3CF62 to decimal gives you 315234 which is the sensor ID in a decimal integer.

Humidity sensor example

We will use a Humidity sensor to demonstrate what values you might expect to see and how to interpret these values. We will be using a Humidity Sensor ID 315234 registered to slot 2 with the following details:
Last checked in: 5 minutes ago
Aware: Not Aware
Signal: 60%
Battery Level: 90%
Signal Level: 80%
Reading: 72.5° F with 42.5% humidity

To see all 16 sensor registers, you would poll registers 40117 - 40132. Doing so would result in the following results when polled as decimal values:
40117: 3 (first part of the 32 bit sensor ID - 3 in decimal = 3 in hexidecimal)
40118: 53090 (second part of the 32 bit sensor ID - 53090 in decimal = CF62 in hexidecimal - concatenate ID high and low to get 3CF62 which equals the sensor ID 53090)
40119: 48 (device type = 48 - according to the following call, type 48 is a Humidity sensor: https://www.imonnit.com/xml/GetApplicationID)
40120: 300 (data age is 300 seconds - the sensor last communicated with the gateway 300 seconds ago)
40121: 1 (sensor is Active since value is 1 and not 0)
40122: 0 (sensor is not in Aware State since value is 0 and not 1)
40123: 316 (battery is full as voltage is reported as 316 = 3.16 Volts)
40124: 60 (signal is 100 as RSSI is -60 RSSI)
40125: 4250 (humidity is reported as 425 = 42.5 percent
40126: 2250 (temperature is reported as 2250 22.5°C)
40127: 0 (this sensor type does not report data on data registers 3-8)
40128: 0 (this sensor type does not report data on data registers 3-8)
40129: 0 (this sensor type does not report data on data registers 3-8)
40130: 0 (this sensor type does not report data on data registers 3-8)
40131: 0 (this sensor type does not report data on data registers 3-8)
40132: 0 (this sensor type does not report data on data registers 3-8)


Testing the MODBUS TCP Interface


If your have activated the MODBUS TCP Interface on your gateway, you can test it with a lightweight tool developed by Schneider Electric. This tool can be downloaded at the following link - Schneider Electric Testing Tool.

Instructions for testing the Interface can be found below.

  • Ping the IP address of the gateway from your PC to confirm you get a successful response.
  • Disable any firewall or security software that might block requests on the used port (TCP port 502 by default).
  • Download and Launch the Tester.exe application.
  • Confirm the Port is set to TCP/IP.
  • Enter the IP Address of the gateway in the TCP/IP Address or URL field.
  • Confirm Sample Mode is set to Manual.
  • Leave Timeout in ms: set to 20000.
  • Leave Sample Rate in ms: set to 1.
  • Leave Data Type: set to Holding Registers (R03/W16).
  • Leave Slave ID at the default setting.
  • Enter 1 for the Starting Register.
  • Enter 5 for the # of Registers.
  • Click the Read button.

You should return values for the registers 1-5. These registers correspond to the gateway information.

To poll data from the sensor in slot 1, you would change the Starting Register to 101, and # of registers to 10 (note: this utility can only display a maximum of 10 registers at a time). If you receive a timeout or similar error, the utility was not successful in communicating with the gateway’s MODBUS TCP Interface.


Updating the Gateway firmware

There are important updates for the MODBUS TCP Interface for the Ethernet Gateway 4. Therefore it is important to make sure your gateway is running current firmware before building your sensor network with your Ethernet Gateway’s MODBUS TCP Interface.

Note: Updating the gateway’s firmware may reset the gateway’s configurations to default settings. If you have your gateway programmed with a static IP address, this may be cleared out and DHCP (re)enabled. You should be prepared to reconfigure the gateway on a network with DHCP enabled if you perform an update on a gateway with a static IP address. However, gateway firmware version 1.0.5.1 and later are able to restore configurations after being updated.

Keeping the gateway’s firmware is an important step to resolving some unexpected issues. In order to update the firmware, the gateway must be checking in with the iMonnit Online portal. You can update your gateway’s firmware by following the steps described below.

  • Log into the iMonnit Online portal with an Administrator login.
  • Click the Gateways link in the left-hand sidebar.
  • Click the Gateway you wish to update.
  • Click the Settings tab (gear icon).
  • Click the Commands sub-tab.
  • If an update is available, you will see a blue button labeled Update, click it.
  • The gateway’s firmware will update to the most recent version on its subsequent check in. Updates generally take less than 10 minutes, and the gateway will check in normally after the update is complete.

Conclusion

The MODBUS TCP Interface offers versatility in the manner which you integrate Monnit devices with your application. While there are many details and configurations to consider when implementing an Ethernet Gateway with the MODBUS TCP Interface, this article should get your started with your integration. For related inquiries, feel free to contact Monnit Support.