Modbus

eGauge meters can read and output Modbus RTU and TCP

Modbus Output Communication

All eGauge models with firmware v3.2 or higher have Modbus TCP output capability. eGauge models with USB ports also have capability for Modbus RTU (serial via RS485) output capability, with use of the eGauge USB485 converter. The Modbus server can be enabled in Settings -> Modbus Server. If the Modbus Server option is not available, upgrade your firmware in Tools -> Firmware Upgrade.

NOTICE: Prior to firmware v4.0, the Modbus map addresses are liable to change if the register name or contents is modified. Firmware v4.0 adds additional ranges that are tied to the register ID. The addresses used prior to v4.0 are still usable to provide backwards-compatibility, but are marked as deprecated and are not recommended to use as installation settings reconfiguration may change them. Virtual registers are in the order they appear on the settings page, meaning addresses can change if virtual registers are added or deleted.

 


Enabling the Modbus server

In the eGauge interface, navigate to Settings -> Modbus Server. The following options are available:

 

Check the box for "Enable Modbus" for the appropriate service (Modbus TCP uses Ethernet, Modbus RTU uses the eGauge USB485 serial converter).

For Modbus TCP, choose the port to listen on (default: 502).

For Modbus RTU, click inside the serial device box and detected adapters will be listed to choose from as shown below. Choose the appropriate baud rate, parity and stop bits to match the Modbus master.


Modbus Register Map

The exact Modbus map depends on the eGauge device configuration and is available on the Modbus settings screen. The map is available for viewing in the web browser or for download as a comma-separated value (CSV) file which can then be imported into any spreadsheet program.

Address range

Description

Timestamps

30000 -- 30003

local timestamp (for use when reading from addresses <45000)

30004 -- 30007

THD timestamp indicates when data was acquired that is used by FFTarg(), FFTarg2(), FFTmag(), and THD() functions

30008 -- 30009

register timestamp (for use when reading from addresses ≥45000)

Local data (channel checker)

30500 -- 30999

Line voltages (RMS)

31000 -- 31499

Line voltages (DC/mean)

31500 -- 31999

Line frequencies

32000 -- 32499

Sensor values (normal/RMS)

32500 -- 32999

Sensor values (mean/DC)

33000 -- 33949

Sensor frequencies

Register Data [v4.0 and greater]

34000 -- 34999

Reduced precision cumulative physical register values (float)
35000 -- 35999

 

Cumulative virtual register values (signed 64-bit integers)
36000 -- 36999

Change of virtual register value (float)

37000 -- 37999 Reduced precision cumulative virtual register values (float)
38000 -- 38999 Cumulative physical register values (signed 64-bit integers)
39000 -- 39999 Change of physical register value (float)

 

 

Register Data [PRIOR to firmware v4.0, now deprecated]

35000 -- 35999

Cumulative register values (signed 64-bit integers) [DEPRECATED]

36000 -- 36999

Change of register value (float) [DEPRECATED]

37000 -- 37999

Reduced precision cumulative register values (float) [DEPRECATED]

In v4.0 or greater, the Modbus addresses are tied to the eGauge register IDs. They can be calculated as:

Physical float cumulative value = 34000+(ID*2)

Physical s64   cumulative value = 38000+(ID*4)

Physical float instant value    = 39000+(ID*2)

 

Virtual registers are in the order they appear on the installation settings page, and are therefore liable to shift during deletions or additions.

 

The register ID can be found by hovering over the register delete button in the Installation Settings page:

 

An example Modbus map, which can be found in Settings -> Modbus Server, is displayed below:


 

Example Modbus Transmissions:

 

Example Modbus TCP request and response for L1 RMS voltage:

 

Request: [00 01] [00 00] [00 06] [01] [04] [01 f4] [00 02]

 

[00 01] = Transaction identifier

[00 00] = Protocol identifier (always 00 00)

[00 06] = Bytes following (0x0006 = 6 bytes)

[01] = Unit ID

[04] = Function code (0x04 is read input registers)

[01 f4] = Starting register address (500)

[00 02] = Number of words to return (2 words for float value)

 

Response: [00 01] [00 00] [00 07] [01] [04] [04] [42 f6 2a 06]

 

[00 01] = Transaction identifier

[00 00] = Protocol identifier (always 00 00)

[00 07] = Bytes following (0x0007 = 7 bytes)

[01] = Unit ID

[04] = Function code (0x04 is read input registers)

[42 f6 2a 06] = Contents of register 500 and 501 respectively

 

0x42f62a06 decoded as big-endian (ABCD) float is roughly 123.08, so L1 voltage is 123.08Vrms

 

Example Modbus RTU request and response for L1 RMS voltage:

 

Request: [01] [04] [01 f4] [00 02] [31 c5]

 

[01] = Unit ID

[04] = Function code (0x04 is read input registers)

[01 f4] = Starting register address (500)

[31 c5] = CRC error check

 

Response: [01] [04] [04] [42 f6 2a 06] [90 ac]

[01] = Unit ID

[04] = Function code (0x04 is read input registers)

[04] = Data bytes to follow (not including CRC)

[42 f6 2a 06] = Contents of register 500 and 501 respectively

 

0x42f62a06 decoded as big-endian (ABCD) float is roughly 123.08, so L1 voltage is 123.08Vrms

 


Additional technical information

Additional help is available by clicking the [?] buttons on the Modbus Server settings page.

All data is provided as Modbus input registers and therefore their Modbus addresses start at 30000. The raw frame sent does not include the prefixed '30', this indicates the function code used.

For each register recorded by eGauge, the register's current cumulative value and the amount by which it changed since the previous one-second interval can be read. The cumulative value is available with full resolution as a signed 64-bit value. For convenience, the same value is also available, at reduced resolution, as a 32-bit floating point number. The change-in-value is available only as a 32-bit floating point number. In addition to the register data, it is also possible to read locally measured data such as line-voltages, frequencies, and the value measured by each sensor-port.

The Modbus server guarantees that any data read with a single request is consistent. Timestamps are provided as a means to ensure consistency when data is read with multiple requests (e.g., to read multiple, discontiguous registers). This is accomplished by (i) reading the timestamp, (ii) performing the desired read requests, and (iii) reading the timestamp again. If the two timestamp values are the same, then reader can be certain that the data is consistent.

 

Sunspec Support

Sunspec is a communication standard used by many types of devices (including inverters). It is intended to ease configuration when working with hardware from different manufacturers by providing common addressing block for different device types and allowing devices to query for applicable address blocks. Essentially, Sunspec allows a Modbus master (such as the eGauge) the ability to read the list of available registers from a device, eliminating the need to create inline definitions manually.

 

It's fairly easy to configure a Sunspec remote device:

1. Create a new remote device entry.

2. Name the entry (names are arbitrary but should make sense to the user).

3. Select the appropriate protocol. "Serial" for Modbus RTU, and "Modbus TCP" for Modbus TCP.

4. Enter the device address. This is in the form "modbus://sunspec.<id>@<addr>" where <id> is replaced with the Modbus slave address of the remote device and <addr> is replaced with the address of the remote device.

4a. With Modbus RTU, the address will be a USB port (USB1 or USB2) along with serial settings in the form ": baud / databits parity stopbits". For example, @USB1:9600/8n1 would indicate USB port 1, 9600 baud, 8 data bits, no parity, 1 stop bit. 

4b. With Modbus TCP, the address will simply be the IP address of the Sunspec device on the local network. For example, @192.168.1.25 would indicate the remote device is located at 192.168.1.25.

5. Click the grey "?" to the left of the device address. This will cause the eGauge to query the remote device for a full list of registers, and a green checkmark will appear if the query was successful. A red "X" will appear if the address is invalid or incorrectly entered. Click the blue info button to see detailed information on the state of the query (shown below).

image-1584650126312.png

6. Once the register list has been retrieved, the eGauge needs to be configured to store registers of interest. To do this, create a new physical register, set the register type to the remote device name used in step 2, and then use the dropdown menu to select the remote register to record. The eGauge will only record the registers configured in this step, regardless of how many registers exist on the remote device.

image-1584650909999.png

7. Click the "Save" button at the bottom of the page to save these changes. The eGauge must be rebooted after adding new registers (this process typically takes about 30 seconds).

 

To add additional registers from a remote device, repeat steps 5 and 6.

Custom Modbus definitions (read from any Modbus device)

In firmware v4.0 and greater, a graphical interface to edit Modbus maps is available. This is recommended to be used over in-line definitions. See this article for information on using the Modbus map editor.

The following table describes the full Modbus address format and syntax. In-line definitions may be used to allow the eGauge to read from arbitrary or unsupported Modbus devices. Examples are provided at the end of this document.

Some options have been added in newer firmware releases, if the behavior is not as expected please check the firmware revision notes at egauge.net/revs/ and upgrade the device firmware in Tools -> Firmware Upgrade.

Remote devices are configured in Settings -> Installation -> Remote Devices. The protocol for Modbus RTU is "RS485" The protocol for Modbus TCP is "Modbus TCP".

USB485 connected (EG4xxx with USB485 only) serial devices have a remote device address in the format of:

modbus://DEVTYPE.SLAVE_ADDR@USB_PORT[:SERIAL_SETTINGS]

Note: Modbus RTU requires prefixing the address with modbus://

 

BF-430 connected (older and all models) serial devices have a remote device address in the format of:

modbus://DEVTYPE.SLAVE_ADDRESS@CONV_ADDRESS[:PORT]

Note: Modbus RTU requires prefixing the address with modbus://

 

Modbus TCP connected devices have a remote device address in the format of:

DEVTYPE.SLAVE_ADDRESS@IP_ADDRESS[:PORT]

Note: Modbus TCP does not start with "modbus://". Instead, the protocol drop-down is set to "Modbus TCP"

 

Variable Definition
DEVTYPE Remote device type or inline Modbus register definitions using the following syntax to define the following elements:
name=addr,[!]type[+offset][*scale][,unit];
name Name for data being read into this register
addr Modbus register address
! Indicates a read-only (function code 0x04 read input) register type
type Modbus register type (see following tables)*
offset Additive offset for register value
scale Multiplicative scale value for register value
unit Physical Unit (see following tables)**
SLAVE_ADDR The Modbus address (0-255) of the device
USB_PORT Modbus RTU, USB485 (EG4xxx) use only. The USB port number with the USB485 converter
SERIAL_SETTINGS Modbus RTU, USB485 (EG4xxx) use only. Serial settings for the USB485 converter to use in the format of 9600/8n1 (baud rate, data bits, parity, stop bits). Required for custom definitions
CONV_ADDRESS Modbus RTU, BF-430 use only. MAC address or IP address of BF-430
IP_ADDRESS Modbus TCP use only. The IP address of the Modbus slave
PORT Port number for BF-430 Modbus RTU (default: 50,000), or Modbus TCP slave (default: 502)

 

Register Type * Description    
bit 1-bit value (coil or discrete input if read-only)
s16 Signed 16-bit integer
u16 Unsigned 16-bit integer
float16 IEEE-754 half-precision binary 16-bit float value
float16l Little-endian IEEE-754 half-precision binary 16-bit float value
s32 Signed 32-bit integer
s32l Little-endian signed 32-bit integer
u32 Unsigned 32-bit integer
u32l Little-endian unsigned 32-bit integer
s64 Signed 64-bit integer
u64 Unsigned 64-bit integer
float IEEE-754 32-bit float value
floatl Little-endian IEEE-754 32-bit float value
double Double value

 

Unit Code ** Physical Quantity Unit Code ** Physical Quantity
Ohm Resistance (Ω) mA Current (milliampere)
W Power (watt) As Charge (ampere-second)
kWh Energy (kWh) Ah Charge (ampere-hour)
degC Temperature (degrees Celsius) mAh Charge (milliampere-hour)
m/s Speed (meters per second) Hz Frequency (hertz)
mm Length (millimeter) % Percentage (%)
W/m^2 Irradiance (watts per square meter) m3/s Volumetric flow (cubic meters per second)
ms Time (millisecond) m3 Volume (cubic meters)
s Time (seconds) Pa Pressure (pascal)
h Time (hours) kPa Pressure (kilopascal)
V Voltage (volt) deg Angle (degree)
mV Voltage (millivolt) RH Relative humidity (%)
A Current (ampere) #3 Number with 3 decimals
var Reactive power (VAr) enum enumeration digital value (e.g., fault code)
bitset Bitfield value    

 


Examples:

Modbus RTU:

modbus://ae75_100tx.2@USB1

Modbus RTU supported device "ae75_100tx", slave address 2 using USB485 on USB port 1

 

modbus://ae75_100tx.2@000ee35b0012

Modbus RTU supported device "ae75_100tx", slave address 2 using a BF-430 connecting via MAC address

 

modbus://ae75_100tx.2@000ee35b0012:500

Same as above, but specifying to use port 500 instead of 50,000

 

modbus://power=1,s16,W.5@USB2:19200/8n1

Modbus RTU unsupported device measuring "power" at address 1, signed 16-bit integer, recording Watts, slave address 5, connecting via USB485 on USB port 2. Using 19200 baud, 8 data bits, no parity and one stop bit

 

modbus://power=1,s16,W;voltage=2,s16,V;current=3,s16,A.5@USB2:19200/8n1

Same as above, but also recording voltage and current at addresses 2 and 3 respectively

 

modbus://power=1,!s32*.1,W.5@USB2:19200/8n1

Here, the "power" value is being scaled by 10 (multiply by .1), and is using function code 0x04 (read input registers) as depicted by the exclamation mark

 

Note: "Protocol" is RS485 for Modbus RTU, and the device address starts with "modbus://"

 


Modbus TCP:

ae75_100tx.1@192.168.1.121

Supported Modbus TCP device "ae75_100tx" at slave address 1 at IP address 192.168.1.121

 

ae75_100tx.1@192.168.1.121:503

Supported Modbus TCP device "ae75_100tx" at slave address 1 at IP address 192.168.1.121, using port 503 instead of 502

 

impedance=598,floatl,Ohm;phase=600,floatl,deg.2@10.1.254.3

Unsupported Modbus TCP device recording impedance from register 598 and phase angle from register 600. Both are reading as little-endian float.

 

Note: "Protocol" is "Modbus TCP", and the device address does not start with "Modbus://"

 

Creating, Sharing, and Using Modbus Maps

Overview

From firmware 4.1 and up, the eGauge supports the creation and sharing of Modbus maps through the Modbus map editor. Modbus maps are essentially a set of instructions for the eGauge meter describing how to read data from third party Modbus devices (hardware not manufactured or supported by eGauge Systems).

Traditionally, configuring the eGauge to read correctly from a Modbus device required the creation of inline definitions. This approach is still supported, but it is difficult to apply to multiple meters. It also requires that each user of a specific device create their own inline definitions. With the addition of Modbus maps, definitions for a given remote device can be freely shared and improved upon. These maps can also be applied directly to a meter without risk of error due to copy/pasting issues or typing mistakes.

Firmware 4.1 or later is required.

 

Contents

Accessing the Modbus Map Editor

Creating a New Map

    Adding Registers

    Adding Default Options

Sharing Modbus Maps

    Downloading Maps

    Uploading Maps

Using a Modbus Map

    Modbus RTU

    Modbus TCP

    Creating a Local Register

 


 

Accessing the Modbus Map Editor

The Modbus Map Editor can be accessed through the Installation Settings screen by clicking the "Modbus Maps" button under the "Remote Devices" section:

image-1610986388549.png

image-1610987608742.png

image-1610986408764.png

A list of available Modbus maps will load. From here, maps can be created, edited, shared, or applied to the meter.

 


 

Creating a New Map

To create a new map, click or tap the icon in the top right corner of the page.

image-1608230956044.png

This will open a new page.

image-1608231008968.png

First, enter an appropriate map name. Typically, this should identify the hardware. Hardware model numbers are recommended. Click the "Save" button in the bottom right corner of the page to create an empty map with this name. The meter will load the list of available maps again, with the new (empty) map at the top. Click on this again to return to the empty map.

 

Adding Registers

To add registers, click the "Add Register" button. Enter the appropriate information for your register. "Scale" and "Offset" are optional values; all other fields must be filled. This information will be available in the documentation for the third party hardware - if it is not, it will be necessary to contact that hardware manufacturer directly. eGauge Systems cannot provide Modbus register maps for third party hardware.

As an example, the manufacturer's Modbus register map used to create the register below is available here: XY-MD02 manual. Note that Modbus register maps are not standardized, and it may require some effort to find the values required for eGauge configuration in a given map.

Below is an example register:

image-1608231957161.png

Address

Modbus register address, in decimal form. Note that Modbus documentation is not consistent, and it may be necessary to modify the address. For example, many addresses are listed with a preceding 3 or 4, but this number is usually dropped along with any preceding 0s. Thus, 30001 becomes 1, 40258 becomes 258, and so on. Some addresses may have a +/- 1 offset, so 301 might actually need to be entered as 300. Finally convert hex values (which usually start with 0x) to decimal values using a hexidecimal to decimal converter.

Register Name

The register name is an arbitrary value, but should reflect the item being measured for the sake of clarity. For example, "Temperature" implies a temperature measurement. "Ambient Temperature" might be a better fit for a device which records multiple temperature measurements.

Type

The data type of the register. If this setting is not correct the register data will not be read correctly, although it will usually read something. 32 and 64 bit data types read more than one Modbus register (a single Modbus register is 16 bits). In the absence of a defined data type, a register described by an address range (eg, 10-11, or 1000-1003) is likely a 32 or 64 bit register.

Scale

Applies a scale factor to the raw value read from the Modbus device. This may be used to scale incoming values to better fit a certain data type. In the example above, the Temperature register at address 1 records temperature in .1 C increments, but the eGauge uses C as a unit. A raw value of 334 would therefore be displayed and recorded as 33.4 degrees Celsius with a .1 scale factor. If left blank, this is set to "1".

Offset

Applies a numerical offset to a raw value. This may be used for calibration purposes (eg, if a sensor is known to read 2 units too low, an offset of 2 would display the reading from that sensor as "raw_value + 2"). If left blank, this is set to "0".

Recorded Unit

Associates a supported unit with the value recorded from that register. This assigns a unit to the register in the eGauge user interface. For unsupported units, "record as integer" will record whole numbers and "record with 3 digits" will record fractional numbers to three digits (note that the incoming data may not actually be precise to three digits). 

Read-only Input Register

The eGauge supports reading values from remote devices using either function code 3 (read holding registers) or function code 4 (read input registers). By default, function code 3 is used. However, some devices may only support function code 4 - in this case, selecting "read-only input register" will force the eGauge to use function code 4 for that register. Note that it is possible to use a mix of function codes on a single device.

 

Once a register has been added, click "OK" to save that register into the map. The register will be added to the map, and additional registers can be added by clicking the add icon in the top right corner of the page.

This example device has two registers, shown configured below:

image-1608239783702.png

Make sure to click "Save" in the bottom right corner of the page once all registers are added. Navigating away from the page before clicking save will revert all changes (including newly added registers).

 

Adding Default Options

This section allows the user to specify various communication options on a per-device level. There are four options which can be set. Note that some of these options are mutually exclusive or not required depending on the device type. For example, a serial device (Modbus RTU) will not have a default TCP port.

Default Unit Number

image-1608240018661.png

The default unit number is also referred to as "Modbus ID", "Modbus slave address", "Slave address", and so on. Each device on a single serial chain must have a unique unit number. Typically, hardware will ship with a default unit number, so if multiple devices from the same manufacturer are preset the unit number must be set to a unique value on each device.

The process for changing a device's unit number depends on the hardware - reach out to the hardware manufacturer for additional information or instructions.

 
Default Serial Port Parameters

image-1608240213744.png

Only applies to Modbus RTU devices

Most Modbus RTU devices ship with a predefined set of serial parameters. These include baud rate, data bits, parity, and stop bits. These parameters must be identical across all devices on a single serial chain. If using multiple identical devices they should all be set to use the same values, but devices from different manufacturers may need to be set so they all use the same serial parameters.

The process for changing serial parameters depends on the hardware - reach out to the hardware manufacturer for additional information or instructions.

 
Default TCP Port

image-1608240511366.png

Only applies to Modbus TCP devices

Most Modbus TCP devices ship with a default TCP port of 502. However, in some cases this may not be true, or it may be desirable to use a different TCP port. TCP ports do not need to match across multiple Modbus TCP devices, even on the same network (each Modbus TCP device should have a unique IP address, so the port used is immaterial). 

 

Base Address

image-1610735704509.png

The base address field can be used to apply a starting address for registers. This can be useful if a manufacturer's Modbus map has a +/-1 offset, or if the addresses all require a specific prefix (eg, 30000, 40000, 1000). The address queried by the eGauge will be (base address) + (configured address).

If in doubt, this setting can generally be ignored.

 


 

Sharing Modbus Maps

Modbus maps can be downloaded and shared as CSV files. There is no charge for this service. This can be used to copy a single map to multiple meters, or to share a map with other users. For best results, ensure that the source and destination meters are both on the same firmware version.

Always verify that maps downloaded from unknown sources are valid and complete. A misconfigured map can't cause damage to the eGauge, but it might not work correctly or may report incorrect values.

 

Downloading a Map

image-1610735149230.png

To download a Modbus map, select the desired map from the map list and click the "Download" button. A confirmation window will appear:

image-1610735221894.png

After clicking "OK", the map will be downloaded as a CSV file.

Although it is possible to edit the CSV file directly, this is not supported or recommended. 

 

Uploading a Map

image-1610735390127.png

To upload a Modbus map, click the "Upload" button in the top right corner of the map list. A confirmation window will appear:

image-1610735499646.png

Click the "Filename" field to select the location of the saved map on your computer or device. Optionally, enter the desired map name. Click "OK" to upload the map. 

An error message will appear at the bottom of the page if the map is invalid, corrupted, or incomplete.

Modbus maps can be shared freely as desired. eGauge Systems makes no guarantees as to the correctness or validity of these maps. When uploading a map, always verify that map configuration is correct and complete.

 


 

Using a Modbus Map

Once a Modbus map has been fully configured and saved, it can used in remote device addresses (under Settings -> Installation). Note that a map doesn't do anything until it's added as a remote device and at least one local register is created to store data based on that map.

The process for this varies based on whether the map applies to a Modbus RTU or Modbus TCP device. Make a note of the map name - it will be required to configure the eGauge.

 

Modbus RTU

Modbus RTU device addresses are prefixed with modbus:// and end with the address of either a USB port when using the USB-RS485 adapter (USB1 or USB2) or the MAC address of a Serial to Ethernet converter

The protocol type "Serial" should be selected for all Modbus RTU devices.

In the example below, the map XY-MD02 is associated with a serial to USB adapter in USB port 1

image-1610737163696.png

Serial settings can also be added if default serial settings weren't specified in the map or if different serial settings need to be used. For example:

image-1610737267541.png

In the above example, the serial settings are:

Baud Data Bits Parity Stop Bits
9600 8 n (none) 1

Finally, it's also possible to specify a different Modbus address/slave address/unit number. This will be necessary if a default value isn't specified or if multiple devices are on the same serial chain. To do this, add the address in the form .X after the map name, where X is the address. For example:

image-1610737510383.png

In the above example, an address of 55 is used instead of the default.

 

Modbus TCP

Modbus TCP devices have no prefix, and end with the IP address or MAC address of the Modbus device on the local network. Note that Modbus TCP devices must be on the same local network as the eGauge.

The Protocol type "Modbus TCP" should be selected for all Modbus TCP devices.

In the example below, the map XY-MD02 is associated with the address 192.168.1.25 (presumably the same network the eGauge is connected to):

image-1610737843298.png

A different Modbus address/slave address/unit number may also need to be specified. To do this, add the address in the form .X after the map name, where X is the address. For example:

image-1610737930469.png

In the above example, an address of 55 is used instead of the default.

 

Creating a Local Register

To create a local register and record data from a remote device, you must first validate the Modbus address. To do this, click the grey "?" to the left of the remote device address. A green check mark should appear. If a red "X" appears, it means the remote device is unreachable or the address or map is configured incorrectly.

Once the green check mark appears, registers can be added to the eGauge configuration to store data fetched from the Modbus device. In the example below, the eGauge is importing two registers ("Humidity" and "Temperature") from the remote device "Sensor":

image-1610738509965.png

After adding registers, make sure to save changes by clicking "Save" at the bottom of the page. 

For an introduction to making configuration changes to the eGauge, see this article.