eGauge Meter Communication

Covers meter communication options, including Modbus TCP/RTU, BACnet, and remote eGauge meters.

XML API

eGauge has a free XML-format API for requesting data

XML API

Interpreting XML data and examples

Contained in this article:

  1. General Information
  2. Example: Energy and power for specific dates

External Links:


General Information

XML data is sent with cumulative register values. In the case for power registers, the cumulative values are in watt-seconds. To convert watt-seconds to kWh, divide the watt-seconds by 3,600,000. Cumulative values can be imagined as meter readings at that point in time, where consumption readings continuously increase over time. To get the kWh usage between two dates, subtract the more recent value from the older value and divide by 3,600,000.

 

At the bottom of the page is the output of a minute granular export showing the past ten minutes of cumulative data (obtained with the URL http://DEVNAME.egaug.es/cgi-bin/egauge-show?m&n=10). time_stamp represents the time of the export (unix timestamp in hex); time_delta indicates the time in seconds between exports; epoch represents the date and time recording started on that device (unix timestamp in hex).  

Each <cname> tag contains data on a column header; in this case, that translates to a physical register on the device. t indicates the register type (P for power, V for Voltage, etc) and the text inside the tag represents the register name as recorded on the device. Virtual registers may also be shows in the appropriate parameter is passed in the initial request.

Each row (<r> tag) contains a series of columns (<c> tag) that show the cumulative value of each register. To determine the average value of a register over a given time, simply find the difference between the two cumulative values and divide by the appropriate time delta. The resulting values are expressed in units based on the register type (see the chart in section 2.2.1 of the XML API document for the unit type).  It should be noted that prior to firmware 3.01 cumulative values do not necessarily count up from zero. On firmware 3.01 and newer passing the option when requesting data returns values relative to device epoch (ie, values start at zero). Using the parameter epoch in a data push has the same effect. This assumes that the date and time recording started option is set correctly on the eGauge.

Some examples (based on the sample output below):

Average Grid usage over the most recent minute 55357226851 - 55357243343 = −16492 / 60 = -274.86 Watts (remember, Power registers are bidirectional)

Average Voltage L2 over ten minutes 4511385868513 - 4511319123106 = 66745407 / 600 = 111242.345 mV / 1000 = 111.24 Volts

 

<group serial="0x4e842294">
<data columns="12" time_stamp="0x564cb0e8" time_delta="60" epoch="0x55973268">
<cname t="P">Grid</cname>
<cname t="S">Grid*</cname>
<cname t="V">VL2</cname>
<cname t="V">VL1</cname>
<cname t="F">Frequency</cname>
<r>
<c>55357226851</c>
<c>7375247726</c>
<c>4511385868513</c>
<c>4528987513211</c>
<c>2217532746128</c>
</r>
<r>
<c>55357243343</c>
<c>7375223338</c>
<c>4511378482617</c>
<c>4528980146863</c>
<c>2217529147760</c>
</r>
<r>
<c>55357259861</c>
<c>7375198952</c>
<c>4511371100578</c>
<c>4528972784417</c>
<c>2217525549473</c>
</r>
<r>
<c>55357276431</c>
<c>7375174516</c>
<c>4511363715094</c>
<c>4528965418400</c>
<c>2217521950920</c>
</r>
<r>
<c>55357293137</c>
<c>7375149735</c>
<c>4511356276347</c>
<c>4528957999802</c>
<c>2217518352640</c>
</r>
<r>
<c>55357309872</c>
<c>7375124940</c>
<c>4511348838707</c>
<c>4528950580365</c>
<c>2217514754150</c>
</r>
<r>
<c>55357326630</c>
<c>7375100152</c>
<c>4511341406162</c>
<c>4528943162279</c>
<c>2217511155334</c>
</r>
<r>
<c>55357343410</c>
<c>7375075359</c>
<c>4511333976595</c>
<c>4528935743683</c>
<c>2217507556120</c>
</r>
<r>
<c>55357360207</c>
<c>7375050569</c>
<c>4511326550844</c>
<c>4528928327670</c>
<c>2217503956798</c>
</r>
<r>
<c>55357377048</c>
<c>7375025739</c>
<c>4511319123106</c>
<c>4528920909766</c>
<c>2217500357151</c>
</r>
</data>
</group>

 


Example: Energy and power for specific dates

You can make CGI calls to http://DEV-URL/cgi-bin/egauge-show where DEV-URL is the URL of your eGauge (for example, http://egaugehq.d.egauge.net/). 

The T parameter lets you request data from specific points in time. It expects a comma separated list of Unix time-stamps.

The E parameter requests the values be relative to the Date and Time when recording started. This needs to be set correctly in Settings -> Date & time when recording started. It effectively makes the reading start at zero when the date and time when recording started is set to, otherwise the raw database value could be arbitrary. This requires firmware v3.02 or greater.

The a parameter requests total and virtual registers, such as "Usage" and "Generation". This is optional.

http://egaugehq.d.egauge.net/cgi-bin/egauge-show?a&E&T=1514764800,1483228800 returns data for January 1 2018 00:00:00 UTC, and January 1 2017 00:00:00 UTC respectively, using epoch-relative values and requesting total and virtual registers. The output below has all the other registers except for Usage and Generation removed for readability.

<group serial="0x3b2d1cb7">
  <data columns="27" time_stamp="0x5a497a00" time_delta="60" epoch="0x52a0f760">
    <cname t="P">use</cname>
    <cname t="P">gen</cname>
    <r>
      <c>241517238757</c>
      <c>0</c>
    </r>
  </data>
  <data time_stamp="0x58684680" time_delta="900">
  <r>
    <c>171138633823</c>
    <c>0</c>
  </r>
  </data>
</group>

Generation is zero because there is none recorded on this device.

 

Usage for timestamp 0x5a497a00 (Jan 1 2018) is 241517238757 joules (241517238757/3600000 =  67088 kWh).

Usage for timestamp 0x58684680 (Jan 1 2017) is 171138633823 joules (171138633823/3600000 = 47538 kWh).


If you want power instead of energy, subtract the values and divide by the amount of time between them:


67088 kWh - 47538 kWh = 19550 kWh were used between 2017 and 2018. 1 year is 8760 hours, so 19550 kWh / 8760 h = 2.23 kW average over the year. This can be done using any two points in time.

 


Another description example:

XML API

XML API

eGauge Systems offers access to a free, unrestricted API for use in developing applications which fetch data from the eGauge meter. This API covers the same functions used by the default eGauge interface. The eGauge push service functionality is also covered in the API.

eGauge technical support can offer assistance interpreting XML data. Code review and similar support is not available.

 

XML API

 

Modbus

eGauge meters can read and output Modbus RTU and TCP

Modbus

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.

 

Modbus

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.

Modbus

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://"

 

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.

 

 

 

 

 

BACnet

eGauge meters can output BACnet information via MS/TP and IP (UDP)

BACnet

BACnet PICS

The BACnet Protocol Implementation Conformance Statement (PICS) for the eGauge is available below.

 

BACNET PICS

 

BACnet

BACnet register map

The eGauge does not have a fixed BACnet register map. Instead, registers are mapped as they are created. Thus, the map for two different eGauges will differ based on the number of registers and the order they were added in. Registers are organized into groups, which are defined below.

Group 5 and Group 6 addresses may change if register configuration is modified. It is recommended to use range 0xb0000 and 0xc0000 as the addresses numbers are tied to the register ID and will always remain in that order. See this article for more information about register IDs.

Address Range Group Description Measured Value See footnote
0x20000 Group 1 - The RMS voltage of the voltage-taps can be read through this group. Voltage [V]

 
0x30000 Group 2 - The RMS current measured by each sensor/CT can be read through this group. Current [A] 1
0x50000 Group 3 - The frequency of the voltage-taps can be read through this group. Line Frequency [Hz]  
0x60000

Group 4 contains only the object ID 0x60000 and it reports the number of seconds since BACnet daemon startup. The daemon starts after enabling BACnet support through the UI or after power-cycling.

Timestamp [s]  
0x70000

Group 5 reports the register value for each register (virtual and physical). The register values are time-weighted values and hence the unit of these object IDs is equal to the unit of the corresponding object ID in Group 6, multiplied by seconds. For example, for a register recording power, the Group 6 unit would be Watts, and therefore the Group 5 unit would be Watt-seconds (i.e., Joules).

DEPRECATED IN v4.0, use range 0xb0000 to 0xbffff in firmware v4.0 and newer.

REGVAL [various]  
0x80000

Group 6 reports, for each virtual and physical register, the change in register value during the most recent one-second interval. For example, for a register recording power, the unit would be Watts, for a register recording voltage, the unit would be Volts.

DEPRECATED IN v4.0, use range 0xc0000 to 0xcffff in firmware v4.0 and newer.

REGCHG [various]  
0x90000 Mean Voltages - mean (DC) voltages for voltage inputs Voltage [V] 2
0xa0000 Mean Sensor Values - mean (DC) values for sensor/CT inputs Current [A] 1, 2
0xb0000 Register values like Group 5, statically indexed by register ID REGVAL [various] 2, 3
0xc0000 Register rate-of-change (instantaneous) values like Group 6, statically indexed by register ID REGCHG [various] 2, 3

Footnotes:

1. Unit will be Amps for current, various for other sensors
2. Introduced in firmware v4.0
3. These addresses are tied to register ID. Group 5 and Group 6 are liable to have addresses change if register configuration is modified.

The BACnet PICS is available in the support knowledge base here.

Additional Tips:

Serial and USB485

General USB485 and serial information

Serial and USB485

Remote device via eGauge USB485 adapter

The EG4xxx has two USB ports which may be utilized for communicating with third-party serial devices via the eGauge RS485-USB converter (USB485). This effectively replaces the BF-430 used with older model eGauges. In addition, a network connection is not required, as data is read from the third-party serial device through the RS485-USB converter (which is physically connected to the eGauge). At the end of this document is a wiring diagram illustrating the required connections between an eGauge and a single third-party serial device using the RS485-USB converter. Specific wiring diagrams for the commonly used IMT SI-RS485TC irradiance sensor are also available.

 

The RS485-USB Converter features include:

- Micro-USB interface

- 3-wire RS485 terminal interface (data+, data-, ground)

- Termination switch

- 2 LEDs, to indicate TX and RX activity

 

The USB ground is tied to the eGauge DC voltage ground terminal. If the DC voltage terminal is wired in reverse, a significant ground potential may form and damage will occur!

 

Topics in this article include:

- RS485 Interface Grounding

- Termination

- eGauge configuration

- Configuring additional serial parameters

- Indicator LEDs

- Standard wiring diagram

 

RS485 interface grounding

A ground between the RS485-USB converter and serial device's power supply may be required. If the ground potential between the sender and receiver are too far off, the communication voltage can run outside of acceptable limits resulting in communication degradation or even damage to connected equipment.

If the serial device is powered via one of the eGauge USB ports, the ground connection is not needed.

 

Termination

The RS485-USB Converter has a termination toggle switch. This should be enabled if the converter is the last device on the chain, or if there is only a single serial device connected. In most cases this termination switch should be in the ON position. Failure to enable the termination switch may result in communication degradation or failure.

 

eGauge Configuration

The configuration for an eGauge to communicate with a remote serial device using the RS485-USB Converter is similar to configuring other remote devices. Navigate to Settings -> Installation and add a new remote device using protocol "RS485". The device address is either USB1 or USB2, depending on the USB input in use. All other remote device configuration is standard, and more information on the device address syntax for custom Modbus definitions can be found in the third party device section of eGauge.net.

 

Example of remote device address for a Modbus IMT irradiance sensor with serial address 1 connected via an RS485-USB converter in USB port 1

 

Configuring additional serial parameters (i.e., baud rate, data bits, parity, stop bits)

If the default serial parameters for a supported device change, or if an unsupported Modbus device with in-line definitions is used, serial parameters may need to be defined in the device address. To specify serial parameters, append to the end of the remote device address (do not include brackets):

 

:[BAUD_RATE]/[DATA_BITS][PARITY][STOP_BITS]

 

For example, modbus://imt_si.1@USB1:19200/8e2 will look for a Modbus IMT sensor with serial address 1 on USB port 1, with 19200 baud, 8 data bits, even parity, and 2 stop bits.

Similarly, modbus://temperature=2,s32,degC.3@USB2:1200/8n1 will read a signed 32-bit (s32) temperature value from register 2 from a Modbus device at serial address 3, connected via an RS485-USB converter in USB port 2, running at 1200 baud, 8 data bits, no parity, and one stop bit.

Parity options are 'e' for even, 'n' for none, and 'o' for odd.

 

Indicator LEDs

The eGauge RS485-USB Converter has 2 indicator LEDs. The left-side green LED flashes to indicate serial data was received (responses from the remote serial device), while the right-side red LED flashes to indicate data was received from the eGauge (requests from the eGauge to the serial device).

If there is only activity on the red LED, and no green LED flashes, it is an indication that the serial device is not responding or is not receiving the requests from the eGauge. This may be due to incorrect wiring or incorrect configuration of the eGauge remote device address, or of the serial device itself.

 

Standard wiring diagram

Below is the standard wiring diagram for an eGauge communicating to a single serial device via the RS485-USB Converter. An external power supply for the serial device is generally needed, but if the serial device can be powered via USB, an unused USB port on the eGauge may be connected for the power, and voltage and ground wires in the diagram ignored. It is recommended to connect the ground connection before the data cables, unless the serial device is powered from one of the USB ports on the eGauge.

 

Serial and USB485

Using the USB485 converter with Windows 10

The eGauge USB485 converter may be used as a standard serial-to-USB converter on a computer to read data from an eGauge or communicate with other third party devices besides the eGauge. The eGauge USB485 uses the FT230X chipset from FTDI. Up to date systems should already have the FTDI drivers available for use. If the FTDI drivers are not installed, drivers and information are available from the FTDI website at http://www.ftdichip.com/FTDrivers.htm. COM port downloads can be found at https://www.ftdichip.com/Drivers/VCP.htm.

This article describes how to verify the USB485 converter is recognized by a Windows 10 machine, and uses QModBus to show data being read from an eGauge via two USB485 converters.

Note that support for third party devices is not guaranteed. 

 

1) Connect the eGauge USB485 via USB to the Windows 10 machine. After a minute or several, a notification indicating the serial converter drivers are ready will be displayed at the bottom right-hand corner. If this does not appear after 5 minutes, verify the USB cable is secure and move to the next step.


 

2) Open the device manager by pressing the Windows Key and R (Win+R) to open the "Run" prompt. Alternatively open the start menu, and type "run" and press enter to open the run prompt. Enter devmgmt.msc in the text box and press "OK":


3) Under "Universal Serial Bus controllers" you should see "USB Serial Converter":


4) You can determine the COM port by expanding "Ports (COM & LPT)". Here, it is COM3:


5) The QModBus program may be installed from http://qmodbus.sourceforge.net. eGauge Systems does not endorse and cannot validate the legitimacy of the QModBus program. When the QModBus program is installed and executed, if no serial converters are found it will warn you:


6) If a serial converter is detected, the QModBus will default to use one that is found (in our case, COM3). Here, we have configured the serial settings to match with an eGauge Modbus slave connected via serial to this Windows computers USB485 converter. In the screenshot below, we read registers 1012 and 1013, as DC voltage is a 32-bit float starting at address 1012. When converting 0x4143 and 0xB07B as a big endian float, we see the DC voltage is about 12.23.

 

HomePlug power-line communication

All about HomePlug power-line communication

HomePlug power-line communication

What do the different LEDs on the HomePlug adapter mean?

EG4xxx and EG30xx meters can function with a wide variety of HomePlug AV compliant powerline communication adapters. Some officially supported adapters and their LED keys are shown below.

TRENDnet HomePlug AV (TPL-406E2K)

LED
Function
Typical Behavior
Other Behavior
POWER Indicates the adapter has power Green light No LED - no communication for too long or not receiving power
ETHERNET Indicates an Ethernet line connection On -  live Ethernet line connected
Blinking - sending/receiving Ethernet data
Off - may indicate an issue with network connectivity or a damaged Ethernet cable
DATA Indicates presence of powerline communication On - Powerline device connected
Blinking - sending/receiving powerline data 
Off - no connection to any HomePlug devices


 

 

 

Actiontec HomePlug AV (PWR500/PWR200)

HomePlug AV Adapter
LED Function Typical Behavior Other Behavior
PWR Indicates the adapter has power Green light No LED - no Ethernet communication for too long or not receiving power
LK Indicates a connection with the eGauge or another HomePlug AV adapter Blinking red light when communicating with the eGauge Blinking orange or green - possible connection with another HomePlug AV device
Off - no connection to any HomePlug AV devices
ETH Indicates an Ethernet line connection Blinking green light when transmitting data Off - may indicate an issue with network connectivity or a damaged Ethernet cable

 

 

HomePlug 1.0 HPE100T

HomePlug 1.0 Adapter
LED Function Typical Behavior  
Power Adapter has power and is connected to the eGauge or another HomePlug 1.0 device Green light when active, blinking green light when transmitting data Off - adapter is not receiving power, or cannot communicate to the eGauge
Link Indicates an Ethernet line connection Green when active, blinking green when transmitting data Off - issue with network connectivity or a damaged Ethernet cable

NOTE: Other HomePlug adapters from different manufacturers may work. However, since they have not been tested by eGauge we cannot guarantee full functionality. Troubleshooting and support may be limited in these situations. HomePlug 1.0 adapters are no longer available directly through eGauge - please see our article on locating replacement HomePlug 1.0 adapters for more information.

HomePlug power-line communication

Can the HomePlug adapter be connected to a power strip?

HomePlug adapters should be connected directly into a wall outlet. If that is not an option, it is possible to plug the HomePlug into a power strip provided the power strip has no integrated surge suppressor. Most power strips designed for computers have integrated surge suppressors, so they are not suitable. Uninterruptible power supplies or power strips connected to uninterruptible power supplies are also not suitable.

Low-cost power strips are available at local hardware stores and generally work fine. Non-surge suppressed power strips may be referred to as "relocatable power taps". "Multi outlet taps" are also generally suitable. Extension cords may be used, but keep in mind that the length of the extension cord must be factored into the distance between the eGauge and HomePlug (40ft of wire run + 25ft of extension cord = 65ft between the eGauge and HomePlug).  Maximum effective communication distance is approximately 100ft.

 

HomePlug power-line communication

HomePlug Security Considerations

Overview

Some eGauge models have integrated powerline communication, commonly known as "HomePlug communication" or just "HomePlug". These eGauge models inject a signal into the conductor connected to the L1 terminal of the eGauge and attempt to communicate with other powerline communication devices that are within range connected to the same power line using the HomePlug standard. This effectively acts as a powerline-Ethernet bridge when used to connect an eGauge to a network with a HomePlug adapter.

eGauge2 model units utilize the "HomePlug 1.0" protocol, while newer model eGauges (EG31xx, EG41xx) utilize the newer "HomePlug AV" protocol. "HomePlug AV" is not backwards compatible with "HomePlug 1.0", and the devices will not see each other or communicate. The HomePlug 1.0 standard is no longer in common use, and HomePlug 1.0 adapters may not be readily available.

The HomePlug signal’s reach is limited to about 100ft of wiring and does not extend beyond transformers or cross phases. Thus, for most single-family homes, the HomePlug signal will be contained to within the home itself. This is in contrast to a WiFi signal, for example, which usually can be picked up easily outside a home.

Security Considerations

All HomePlug devices have a "password" or "encryption key" assigned to them. Any HomePlug devices with the same encryption key can communicate to each-other and form a "HomePlug network". By default, the HomePlug 1.0 encryption key is "HomePlug" (case sensitive, without quotes) while the HomePlug AV default encryption key is "HomePlugAV" (case sensitive, without quotes).

Because the HomePlug devices come with default encryption keys, buildings that share electrical services (e.g., possibly duplexes, apartment buildings) may have the HomePlug signal extended into neighboring units which could then allow an individual to obtain someone else's network access via a HomePlug adapter if both are using the default encryption keys. Therefore, it is important to set a unique encryption key on any HomePlug networks that may share a power line with another unit.

HomePlug AV (models EG31xx, EG41xx) utilize the HomePlug Green PHY specification and are compatible with HomePlug AV using 128-bit AES encryption.

HomePlug 1.0 (model eGauge2) utilize a HomePlug 1.0-compatible link and are encrypted with 56-bit Data Encryption Standard (DES).

It is best practice to utilize a unique and secure HomePlug encryption password, but in many private residences it is unlikely to be an issue because of the limitations of powerline communication (specifically, it is unlikely the HomePlug signal will propagate beyond the building's electrical wiring).

More information can be found on the HomePlug Alliance website at http://www.homeplug.org/.

Related Articles

Pairing an eGauge with a HomePlug adapter

What do the different LEDs on the HomePlug adapter mean?

What are some common causes of HomePlug communication issues?

HomePlug power-line communication

How do I pair the eGauge with a HomePlug adapter?

Overview

By default all HomePlug-compliant PLC devices use the same encryption key - this means that, out of the box, any HomePlug-compliant device should be able to connect to any other HomePlug-compliant device without any adjustments. However, if there are multiple HomePlug adapters in the same location, or if there are security concerns regarding PLC traffic, it may be necessary to pair an eGauge with its HomePlug adapter. This is typically not required for most installations.

This article has instructions for pairing eGauge devices with their respective HomePlug adapters. Also included are instructions to rescue an "orphaned" device (that is, an eGauge or HomePlug with an unknown encryption key). These steps typically cannot be performed remotely, and require physical access to both the eGauge meter and the HomePlug.

In new installations, pairing is optional but not required. The eGauge and HomePlug adapter should communicate out of the box. If they do not communicate, there is likely a distance or installation issue; pairing will not correct these issues.

Contents

HomePlug Basics

    What is HomePlug and how is it used?

    Technical And Environmental Considerations

    How Secure is HomePlug Communication?

Changing the HomePlug Encryption Key (pairing)

     Push Button Method (EG301x meters)

     LCD Method (EG41xx meters)

     HomePlug Adapter Push Button Timing

Push Button Pairing Process

Pairing through the eGauge user interface

Recovering an Orphaned Device

     Via eGauge UI

     Via Vendor Software

HomePlug Basics

 

What is HomePlug and how is it used?

HomePlug is a Power Line Communications (PLC) specification used to transmit networking data over standard power lines. Thus, all HomePlug devices are PLC devices, but not all PLC devices use HomePlug. It is commonly used to create a network bridge  in a location where Wi-Fi can not work or is not convenient. Think of the HomePlug adapter as a "translator" that can convert an Ethernet signal into a form which can be sent over existing power lines, and vice versa. HomePlug adapters may commonly be referred to as "HomePlugs", although this can be confusing.

HomePlug adapters are commonly mistaken for wireless (WiFi) devices. Standard HomePlug adapters have no wireless component. A physical connection to an outlet and a router (via Ethernet) is required.

Typically, one HomePlug adapter is connected to a router with Internet access, and another is placed elsewhere in the building so Ethernet-capable network devices may connect to it. eGauge meters have a built-in HomePlug adapter, so only one HomePlug adapter is required when using an eGauge. Examples of common HomePlug adapters are shown below: