Creating Custom Modbus Maps
How To: Create a Custom Modbus Map
Overview
Current firmware allows the eGauge meter to record data from remote devices using Modbus RTU (using the USB485 USB-to-serial converter) and Modbus TCP (Ethernet). The Modbus Map Editor is used to define Modbus addresses on the eGauge to read from third-party hardware.
Prerequisites
- The Modbus map editor was introduced in firmware v.4.1. Please see this article for more information regarding checking and updating firmware versions if needed.
- Valid login credentials are needed to make changes to settings.
- A valid Modbus map for the third-party hardware you want to read from is required to define the registers on the eGauge.
- If the remote device supports SunSpec over Modbus, there is not a need to create a Modbus Map. Instead, configure the remote device as a SunSpec device as described in this article.
Instructions
Step 1: Access the Modbus Map Editor from the Installation Settings page. From the Main Menu navigate to Setup → Other Settings, then choose Installation to the Left. Then click the Modbus Maps button in the Remote Devices section.
A list of existing Modbus maps will load.
- If using the classic eGauge interface, click Settings, then Installation from the home screen to access the installation settings page. Continue with additional steps below.
Step 2: To create a new map, click the icon at the top right corner of the page:
This opens a new page.
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.
Step 3: 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.
Click OK to save the register to your custom Modbus map.
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:
Step 4: Repeat Step 3 to add additional registers as needed.
Step 5: When you're finished adding registers to your map, click Save at the bottom right corner of the page to save changes to the map.
The Sections below offer additional clarification on each register setting. Note that some settings may not be applicable to all data types.
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.
Byte Order
Needs Firmware version 4.7
This option is only available for certain data types. If it's not displayed, then it is not applicable to the chosen data type. The default data type is big-endian. Data types that end with a lowercase L have little-endian byte order by default and cannot be changed.
When using custom or non-standard byte orders you may need to confirm the correct byte order with the hardware manufacturer.
16 bit value options: (AB) (BA)
32 bit value options: (AB CD) (CD AB) (BA DC) (DC BA) or a custom option where the order can be specified.
64 bit value options: (AB CD EF GH) (GH EF CD AB) (BA DC FE HG) (HG FE DC BA) or a custom option where the order is specified.
Kind
The kind of register. There are three options:
- Analog - A simple numerical value. Most applications will use analog values.
- Bitset - A numerical value representing a binary string. Typically, each 1 or 0 in this string would represent a state on the remote device. This selection is never averaged or allowed to accumulate excess, because it would change the fundamental value.
- Enum - A numerical value representing a state on the remote device. This selection is never averaged or allowed to accumulate excess, because it would change the fundamental value.
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.
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
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
Only applies to Modbus RTU devices. The process for changing serial parameters depends on the hardware - reach out to the hardware manufacturer for additional information or instructions.
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.
Default TCP Port
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
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 Custom Modbus maps
How To: Share Custom Modbus Maps
Overview
If a custom Modbus map has been created using the Modbus map editor it can be downloaded and uploaded to another eGauge meter.
Prerequisites
- This is an advanced configuration topic.
Instructions
Step 1: Access the Modbus Map Editor from the Installation Settings page. From the Main Menu navigate to Setup → Other Settings, then choose Installation to the Left. Then click the Modbus Maps button in the Remote Devices section.
A list of existing Modbus maps will load.
Step 2: Locate the custom map to download in the list and click it to open it. Click the Download map icon, click ok to download the map to your computer. Take note of the save location and filename so you can find it later.
Step 3: Upload the map to a different meter by accessing the Modbus map editor as described in step 1 from the new meter's interface. Click the Upload map from CSV file icon and click the Filename field to choose the file you downloaded to your computer in step 2.
Click OK to upload the map to the new eGauge meter.
Additional Resources
How to: Create a Custom Modbus Map