enteliBRIDGE

ModbusTCP Protocol Driver

Version 1.1
Application Guide
Edition 1.24
Contents
Tips, Information, Caution, and Warning Labels......................................................................... 5
Introduction ................................................................................................................................6
Protocol Driver Overview............................................................................................................. 6
Assumptions ............................................................................................................................ 7
Modbus Protocol Specifications .................................................................................................. 7
Supported Devices ................................................................................................................... 8
ModbusTCP Protocol Overview ................................................................................................... 8
Modbus Driver Application ...................................................................................................... 9
Licensing.................................................................................................................................10
Other Resources and Documents ..............................................................................................11
Protocol Specification Standard Documents..........................................................................11
Useful Tools ............................................................................................................................11
Modbus Data Types, Registers and Functions ...........................................................................12
Modbus Data Types.................................................................................................................12
Settable Byte Orders ..............................................................................................................12
Scaling ....................................................................................................................................13
Modbus Registers ...................................................................................................................13
Modbus Functions ..................................................................................................................13
Workflow: Five Steps to Connect to Your Modbus Devices .......................................................14
Step I: Consult Documentation for Modbus Devices on Site......................................................14
Step II: Modbus Networking and Wiring.....................................................................................14
Networking Considerations ....................................................................................................14
Wiring Considerations ............................................................................................................15
Step III: Establish Communication with Gateway (GWS and GWD objects) ...............................15
GWS Settings: Set Up Max Sockets ........................................................................................15
GWD Settings: Set Up Device ModbusTCP Address and IP Port ............................................16
GWD Heartbeat Configuration ................................................................................................17
 GWD Configuration Tab ..........................................................................................................18
Step IV: Configure the Modbus Registers (GWF object mappings) ............................................19
GWF Settings: Set Up Modbus Registers ...............................................................................19
Mappings ................................................................................................................................20
Syntax: Remote Reference Field ............................................................................................21
Syntax: Data Type Field ..........................................................................................................23
Trend Log Support ..................................................................................................................24
Device Templates for Field Device .........................................................................................25
Step V: Troubleshooting .............................................................................................................25
Data Explained in Detail ...........................................................................................................26
Data Representation ..................................................................................................................26
Offsets ........................................................................................................................................26
Masks .........................................................................................................................................28
Data Sizing Considerations ........................................................................................................31
Additional Examples ................................................................................................................32
GWD Object Subnet ....................................................................................................................32
Data Types ..................................................................................................................................32
Data Type * Multiplier (Scaling) ..............................................................................................32
MASK Data Type .....................................................................................................................34
CHARS Data Type....................................................................................................................35
Polling with Offsets ....................................................................................................................35
Specify Byte Order ......................................................................................................................36
Mapping a COIL to an Integer Value .......................................................................................37
Using LAV Object to Handle 64-bit Integer Values .....................................................................37
Appendix A: Modbus Basics Tutorial ........................................................................................38
Modbus Data Types ....................................................................................................................38
Review of Numbering Systems ..................................................................................................38
Integers...................................................................................................................................39
Unsigned Integers ..................................................................................................................40
Signed Integers .......................................................................................................................40

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 2 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Introduction
Tips, Information, Caution, and Warning Labels

Encoding of Integers ...............................................................................................................40

Floating Point Numbers .........................................................................................................41
Appendix B: Energy Meter Example .........................................................................................44
Overview .....................................................................................................................................44
Site Application Story..............................................................................................................45
Step I: Consult Documentation for Modbus Devices on Site......................................................46
Documents ..............................................................................................................................46
Three Meters ..........................................................................................................................47
Shark Meter 200 Power Meter ...............................................................................................51
ONICON System-10-MOD BTU Meter.....................................................................................53
Step II: Modbus Networking and Wiring.....................................................................................56
Step III: Establish Communication with Gateway (GWS and GWD objects) ...............................57
A: Create GWS1 Instance ........................................................................................................57
B: Create a GWD for the Power Meter in Each Building ........................................................58
C: Create GWD for BTU Heat Meter........................................................................................62
Step IV: Configure the GWF Point Mappings ..............................................................................62
A: Add GWF Mappings for ACUVIM II Power Meter ................................................................63
B: Add GWF Mappings for Shark 200 Power Meter ................................................................65
C: Add GWF Mappings for ONICON System-10-MOD BTU Heat Meter ..................................66
D: Create and Use BDC/ MIC with a Mapping.........................................................................67
E: Specify a BDC/MIC in a GWF Mapping (1.0.14) ...................................................................69
Step V: Troubleshooting .............................................................................................................70
Appendix C: Troubleshooting: Interpreting System Feedback Messages ................................71
Working with GWD Objects ModbusTCP ....................................................................................71
a: Gateway Not Loaded Yet (GWD) ..........................................................................................71
b: GWF Configuration Error (GWD) .........................................................................................72
c: Query Failed: OS::SEND_FAIL (GWD) .................................................................................72
d: Communication Timeout (GWD) .........................................................................................72
e: Empty ProtoX Address (GWD) .............................................................................................73
f: Description of Halt (GWD) – Failed to Query device. ...........................................................73

Page 3 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
 g: Description of Halt (GWD) – Failed to poll device DEVICE:.................................................73
GWF Template Mappings ModbusTCP .......................................................................................74
Working with GWF Mapping Entries .......................................................................................75
a: Invalid Remote Reference ..................................................................................................76
b: Incorrect Data Type ............................................................................................................76
c: Incorrect Read: Offset Entries Must NOT be Read-Periodically ........................................77
Appendix D: Glossary of Modbus Terms ...................................................................................78
Copyright ..................................................................................................................................84
Document Revision History ........................................................................................................85

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 4 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Introduction
Tips, Information, Caution, and Warning Labels

Tips, Information, Caution, and Warning Labels

This is a tip. Use this for tips and tricks.

This is an information-type box. Use it for any content that would

provide additional information to the user, like related documents or
KB articles.

This is a caution type. Not something that requires immediate action

but nonetheless something users should be aware of.

This is a do-or-die warning type. This indicates a situation that needs

immediate attention or where serious electronic equipment damage
or other consequences may result.

Page 5 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Introduction
This document provides information that is specific to using the ModbusTCP protocol driver with
the enteliBRIDGE® hardware and software. Each protocol driver available with the
enteliBRIDGE Gateway product has its own driver-specific application guide that explains the
specifics of configuring and using a particular protocol driver. The resulting document is the
ModbusTCP Version 1.0 Protocol Driver Application Guide.

In addition to the driver-specific application guides, a user guide is available. The enteliBRIDGE
Gateway User Guide focuses on general information about the web interface that is not specific
to a particular driver. When you click the Help Question mark button in the upper right area of
the web interface, the User Guide PDF file opens in a separate window.

This section describes the specifications and basic data structure and communication models
for the Modbus protocol driver. It is assumed that you have the enteliBRIDGE Gateway User
Guide available and are familiar with its content. The user guide provides general information
that is not specific to a protocol driver and focuses on doing tasks using the web interface.

Protocol Driver Overview

This section explains:

• Modbus driver specification

• Protocol type
• Models for communication, data, messages etc.
• Message types, reference types, data types, data tables

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 6 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Introduction
Modbus Protocol Specifications

Assumptions
You have:

• enteliBRIDGE Gateway product with the Modbus Protocol Driver installed

• Means to connect the enteliBRIDGE Gateway to the ModbusTCP network

Modbus Protocol Specifications

This section presents the specifications of the ModbusTCP Driver.

Component Description
Capacity Up to 30,000 Modbus points total mapped to BACnet virtual devices
*Capacities listed have with: 250 virtual devices max
been tested but actual 1300 points max per virtual device
limits may vary depending Trend up to 5000 mapped points
on site configurations.
Modbus Data Types Coils (0xxxx references),
Read (01), Write Single (05)
Discrete Inputs (1xxxx references),
Read (02)
Input Registers (3xxxx references),
Read (04)
Holding Registers (4xxxx references)
Read (03), Write Single (06), Write Multiple (16)
If the Modbus device doesn’t support the Read/Write Multiple
service then the Read/Write Single service will automatically be
used.
There is no 2xxxx address prefix.
Data Types / Data Model Bit, UINT16, UINT32, UINT64, INT16, INT32, INT64, Float, Chars,
Lenchars, MASK16, MASK32, MASK64
Settable byte orders
Supports scaling, offsetting and bit masking
BACnet Objects Analog Input, Binary Input, Multi-State Input,
Analog Output, Binary Output, Multi-State Output,
Analog Value, Binary Value, Multi-State Value,
Large Analog Value, Integer Value, Positive Integer Value,
Bit String Value, Character Value, Octet String Value
Date Value, Time Value, Date Time Value.

Page 7 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Component Description
Device, Trend Log, Archival EVC (Notification Class)
Auto Mapping / Discovery Driver does NOT support auto mapping function
Polling Frequency 1 register/interval, All registers/interval, Continuous
Retrieve periodically; Retrieve on read, Retrieve once
Write immediately, Write on polling interval
Supports writes based on change of value of the BACnet object
Supported Devices See the Delta Exchange area reserved for GWF objects.
Deltaexchange.deltacontrols.com
Link to Delta Exchange
Communication Gigabit Ethernet ports (2) available each with separate port settings
ModbusTCP Driver <current version><release date><release time>
Version SDK:1.0 DRV:<MMM DD YYYY>.<HH:MM:SS>
SDK:1.1 DRV:<MMM DD YYYY>.<HH:MM:SS>
enteliCORE Hardware Version 1.2 or greater
enteliBRIDGE Software enteliBRIDGE 1.0.14 or greater

Supported Devices
You can save time in setting up a device by using an existing GWF object that was created for
that device. Sometimes an existing GWF provides a reasonable start and you can then modify it
to suit your application if required. The Delta Exchange (http://deltaexchange.deltacontrols.com/)
has a repository of freely available GWF templates that can be searched and downloaded to the
gateway.

ModbusTCP Protocol Overview

The ModbusTCP protocol driver allows the enteliBRIDGE® gateway to communicate with
Modbus devices over a TCP connection as a Modbus Master. The gateway allows the connection
of ModbusTCP slave controllers to a BACnet network. The driver provides interaction with
Modbus devices as virtual BACnet devices in your building automation system.

ModbusTCP products come in two main types: gateways to Modbus controllers, and native
ModbusTCP controllers. The Delta ModbusTCP gateway connects to both types of controllers.
This version of the ModbusTCP protocol driver does not accept serial Modbus RTU or ASCII
communications directly so it would rely on a Modbus gateway to translate between RTU or
ASCII and TCP.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 8 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Introduction
ModbusTCP Protocol Overview

When using the enteliBRIDGE gateway to connect through a ModbusTCP gateway to serial
Modbus controllers, a virtual device is created for each Modbus controller. For native
ModbusTCP controllers, a single virtual device is created for each controller. The enteliBRIDGE
gateway can connect to a mixture of both types.

Modbus is a simple protocol that allows access to collections of binary data (coils or discrete
inputs) and other data (holding registers and input registers). Registers are 2 byte values that
can be combined to provide support for larger values. Common larger values include 4 byte or 8
byte signed and unsigned integer values, 4 byte floating point values, and character strings. All
of these types are supported by the gateway. The gateway also allows for bit fields from within
registers to be accessed.

While the current Modbus specification does provide direction on byte ordering, historically it
did not and many products exist that do not use the standard byte ordering on the wire. The
Delta gateway allows for byte ordering to be specified for each data value.

The enteliBRIDGE system can organize the data into logical devices for effective interactions
between the BACnet and Modbus networks. Modbus device formats provide a simple mapping
template for each device type and you can bring similar devices online by just defining the IP
address and format selection.

The ModbusTCP/IP provides a Client/Server communication between devices connected on an

Ethernet TCP/IP network. This client / server model is based on four types of Modbus
messages: Request, Confirmation, Indication and Response. The Modbus data model uses four
primary tables: Discrete Inputs, Coils, Holding Registers and Input Registers.

The driver has a heartbeat configuration function which provides a way to handle slave devices
that do not support a COIL at address 0. By default, the driver pings the first coil to verify
communications with a slave device if this heartbeat configuration feature is inactive. The
heartbeat provides a way to ping a specific register or coil as defined in the Heartbeat Read
Mapping entry on the Configuration tab of each GWD. See the GWD Heartbeat Configuration
Function topic.

For more information, see Appendix A: Modbus Basics Tutorial.

Modbus Driver Application

The ModbusTCP protocol driver allows the enteliBRIDGE® gateway to connect to your Modbus
devices over a TCP connection. Since the driver supports all the Modbus functions, it can
retrieve data efficiently allowing larger numbers of devices to be connected while reducing

Page 9 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
latency in data retrieval. Latency is an expression of the time delay in getting a data packet from
one designated point to another in a network. The term latency refers to time delays typically
incurred in processing of network data. See Appendix D: Glossary of Modbus Terms.

The Modbus protocol driver provides the ability to interact with Modbus devices as virtual
BACnet® devices in your building automation system. As the system allows for up to 250
Modbus devices and a total of 30,000 mappings, the ability to organize the data into logical
devices is crucial for effective interactions between the BACnet and Modbus networks. Modbus
device formats (GWF object) provide a simple mapping template for each device type and you
can bring similar devices online by just defining the IP address and format selection. Each
defined Modbus device can only reference a single Modbus Device Format (GWF).

Modbus devices regularly use scaling to return integer-based values for non-integer based
data. The ModbusTCP protocol driver allows for scaling to be defined in the mapping of the
register to a BACnet point so that the appropriately scaled data is presented to the user. It also
allows for bits to be extracted to Binary Variables or enumerated lists to Multi-state variables,
thereby providing a much more intuitive environment for the end user to consume the data
being presented.

Licensing
The protocol drivers use a licensing model based on the number of points used. After an initial
trial period, the number of points needed for the working application can be determined and the
license finalized. The Modbus Protocol Driver Catalog Sheet describes licensing and the point
count calculation.

Licensing Point Calculation

• Modbus – Each register mapped to a BACnet object counts as a point. The total number
of mapping points is calculated by adding up the number of mappings in a GWF times the
number of GWDs that are referencing that GWF, for all available GWFs. The Licensing
tab of the Main page of the web interface shows the current point count for an
enteliBRIDGE gateway installation.

See the enteliBRIDGE User Guide for explanation of the Licensing tab
located on the web interface Landing page.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 10 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Introduction
Other Resources and Documents

Other Resources and Documents

• enteliBRIDGE Gateway User Guide
General information about the enteliBRIDGE Gateway without driver specific information
Click on the Help ? icon in the upper right area of the web interface to open the PDF file.
• Main page help included with the enteliBRIDGE Web Interface
• Help for the Web Interface objects (GWS, GWD, GWF plus MIC/ BDC). Some of the fields
have content appended that relates to a specific protocol driver.
• Modbus Protocol Driver Catalog Sheet

Protocol Specification Standard Documents

For detailed information on the Modbus specification, see these documents on the Modbus.org
site:

• Modbus Specification v1.1b

• Modbus/TCP Implementation Guide V1.0a
• Modbus Serial Line Implementation Guide V1.02

See also Appendix D: Glossary of Modbus Terms.

Useful Tools
Several useful free tools:

• Chipkin's Modbus scanner

http://www.chipkin.com/products/software/Modbus-software/
• Wireshark packet sniffer software
http://www.wireshark.org/
• Delta Network Tool (DNAT)
• Programmer calculator to change address formats etc.

Page 11 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Modbus Data Types, Registers and Functions
Modbus Data Types
The possible data types that you may find in a Modbus device are:

Each byte has 8 bits and a single register consists of 2 bytes or 16 bits.
See Appendix A: Modbus Basics Tutorial for more info.

Data Type Description

Bit 2 state (binary) data.
UINT16 2 Byte (single register) positive integer values (0 to 65,535)
UINT32 4 Byte (dual register) positive integer values (0 to 4,294,967,295)
UINT64 64-bit unsigned integer (0 to 18446744073709551615)
INT16 2 Byte (single register) positive or negative integer values
(-32,768 to 32,767)
INT32 4 Byte (dual register) positive or negative integer values
(-2,147,483,648 to 2,147,483,647)
INT64 64-bit signed integer (-9223372036854775807 to 9223372036854775807)
Float 4 Byte (dual register) positive or negative decimal values
(+/- 10E-38 to +/- 10E38)
Chars Character data
LenChars Length defined Character data

MASK16 Used to retrieve bit fields from within 1 or 2 registers.

MASK32
MASK64 64-bit unsigned integer of only the masked bits. Used to retrieve bit fields
from within 4 registers.

Settable Byte Orders

Experience has shown that not all vendors use the same ordering for 2, 4 or 8 byte data. The
mapping allows for the byte order to be manipulated so that the value presented to the user in
BACnet matches reality. If not specified by the user the default byte order is 4321.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 12 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Introduction
Modbus Data Types, Registers and Functions

Scaling
Many Modbus devices represent data as a scaled value in order to constrain the data to a single
register. For example, a temperature of 72.5 would be represented as 725. You need to know
how the device treats data. Most manufacturers provide a register table in their documentation.
The ModbusTCP driver can handle the scaling of registers, reading or writing, so that the value
presented to the user in BACnet matches reality.

Modbus Registers
Register Read/ Write Function
Coils (0xxxx references) Read (01), Write Single (05)
Discrete Inputs (1xxxx references) Read (02)
Input Registers (3xxxx references) Read (04)
Holding Registers (4xxxx references) Read (03), Write Single (06), Write
Multiple (16)
If the Modbus device doesn’t support the Read/Write Multiple service then the Read/Write
Single service will automatically be used.

Read/Write Single and Multiple: supports Decimal (i.e. HREG[xxxx])

Modbus Functions
The ModbusTCP driver supports:

Name Modbus
Function
Read Coils 01
Read Discrete Inputs 02
Read Holding Register 03
Read Input Register 04
Write Single Coil 05
Write Single Register 06
Write Multiple Registers 16

Page 13 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Workflow: Five Steps to Connect to Your Modbus
Devices
The intention is to first give five overall general steps and then provide details in the following
sections:

The general approach:

1. Consult documentation for Modbus devices on site (especially conventions for

referencing registers).
2. Ensure the device functions properly on its network and that you understand the
network arrangements and wiring considerations.
3. Establish Communication with enteliBRIDGE Gateway (GWS and GWD objects).
4. Configure the Modbus registers (GWF objects).
5. Troubleshoot.

The Steps I-V sections include basic information and more complex topics are covered in the
following sections. For Modbus terms, see Appendix D: Glossary of Modbus Terms.

For a longer start-to-finish example with GWF mappings for specific

devices, see Appendix B: Energy Meter Example.

Step I: Consult Documentation for Modbus Devices on Site

It is critical to understand the conventions used for referencing registers etc. in the
documentation for different devices. The conventions may vary!

Step II: Modbus Networking and Wiring

Networking Considerations
ModbusTCP operates on the Ethernet network and since it is TCP/IP based, it can traverse
network segments. Being an Ethernet based protocol; it uses the enteliBRIDGE's LAN1 or LAN2
RJ45 ports to connect to the network over a CAT5e or CAT6 cable.

The ModbusTCP driver automatically reconnects to devices when the network connection is
re-established after the connection is dropped.

The LAN ports on the enteliBRIDGE are rated at 1 gigabit speed; however its actual throughput
is determined by the slowest device connection in the network.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 14 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Workflow: Five Steps to Connect to Your Modbus Devices
Step III: Establish Communication with Gateway (GWS and GWD objects)

Some older Modbus devices have a communication limitation of reading a single data point at a
time (1 data point per message) and also requiring delays between messages.

ModbusTCP port
The network port allocated to Modbus is 502. This is the port which will typically be set by
default in all devices and is likely being used unless the site has set aside a different port for
this traffic. The designated port must be open on the network for all ModbusTCP devices to be
able to communicate.

Wiring Considerations
Often, the Modbus devices reside on an existing network. You need to understand network
wiring, arrangement, and communication. In some cases, changes to the network may be
needed to allow proper communications with the gateway.

Step III: Establish Communication with Gateway (GWS and GWD

objects)
The aim is to get some or all the devices to show on the enteliBRIDGE Gateway. The initial focus
is on getting one register of each device type to communicate properly.

GWS Settings: Set Up Max Sockets

The values available on the GWS Configuration tab are:

Element Description
Max Specifies the size of the socket pool used by the GWS to
Sockets communicate with other devices. This value must be greater than
or equal to the number of different devices/ ports that the GWS
will connect to.
For example, if you have 90 GWDs in the GWS and they connect to
10 different ports on a single IP address, then Max Sockets should
be set to 10 or higher.
Do not set this value too high as the enteliBRIDGE does not
support more than 1024 sockets and files to be open at once. You
must restart the enteliBRIDGE for this value to take effect.

Page 15 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
GWD Settings: Set Up Device ModbusTCP Address and IP Port
In the GWD Configuration tab, the values on the GWD Configuration tab are available.

In the GWD, the ModbusTCP Address property value has the form:

GWD ModbusTCP Address and IP Port

Required parameters:
<IPAddr>

Required and optional parameters:

<IPAddr>:<Port>:u<Unit>

Optional parameter default values:

<Port> = 502
u<Unit> = u1

The Port and Unit parameters are optional. The Port parameter indicates the port in the
ModbusTCP device that the gateway should connect to. Port 502 is the default and is used unless
otherwise specified when setting the Modbus device's address in the GWD. If left unspecified, the
default ModbusTCP port of 502 is used. This would not normally need to be modified unless
changed at the Modbus device for network reasons.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 16 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Workflow: Five Steps to Connect to Your Modbus Devices
Step III: Establish Communication with Gateway (GWS and GWD objects)

The Unit parameter is used to select the Modbus RTU device behind the ModbusTCP device that
this GWD represents. The value represents the Modbus address and if left unspecified defaults
to an address of 1.

GWD ModbusTCP Address Example:

ModbusTCP Address Description
192.168.11.105:503:u250 MODBUS/TCP device of address 192.168.11.105,
on port 503 rather than the default port 502, with
Modbus device addressed 250.
192.168.11.105:u250 If a port is not specified, then the default port 502
is assumed.

For subnet addressing, see the GWD Object Subnet topic in the Advanced
Features section of this document.

GWD Heartbeat Configuration

The heartbeat configuration function provides a way to handle slave devices that do not support
a COIL at address 0. By default, the driver pings the first coil COIL[1] to verify communications
with a slave device if the heartbeat configuration feature is inactive. The heartbeat function
monitors the status of communications for a slave device using a specified location.

Page 17 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
The heartbeat function pings a specified register or coil defined in the Heartbeat Read Mapping
entry on the Configuration tab of each GWD.

The ModbusTCP driver Heartbeat function sends a Read request for an item to the device. If no
response is received or specific Modbus error codes (4, 6, 10, 11) are received, the device is
marked as offline. Error codes 1, 2, 3, 5, and 8 do not affect the status the device.

For Modbus error (exception) code information, see:

http://www.simplymodbus.ca/exceptions.htm

https://en.wikipedia.org/wiki/Modbus#Exception_responses

The type of request is configured in the Device configuration page. The request target can be:

• The first mapping in the GWF

• A single coil: COIL[60]

• A single register: HREG[10]

GWD Failure Text Messages

When a Modbus device does not respond, failure text messages display in its GWD:

Case 1: Modbus device is a gateway (or Modbus Master) to Modbus slave RTU devices:

• Modbus Slave device does not respond: (Slave Offline)

o "MODBUS slave device failure" (Error Code 04)
o "MODBUS/TCP-RTU gateway path unavailable." (Error Code 10)
o "MODBUS slave device failed to respond" (Error Code 11)
• Modbus Master does not respond: (Master Offline)
o "Failed to poll device: COMMUNICATION::INVALID_MESSAGE" (or similar) (Error
Code 06)

Case 2: Modbus device is directly controlling points (i.e. not a master to RTU slaves):

• Modbus master does not respond: (Master Offline)

o "Failed to poll device: COMMUNICATION::INVALID_MESSAGE" (or similar)

GWD Configuration Tab

In the GWD Configuration tab, three parameters are available. The Support Write Multiple Coils
and Support Write Multiple Registers parameters are set by the driver depending on whether

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 18 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Workflow: Five Steps to Connect to Your Modbus Devices
Step IV: Configure the Modbus Registers (GWF object mappings)

the device supports the service. If the value for either parameter is set to 0, then the driver does
not attempt to use the service with the device.

The Support Write Multiple Coils parameter is not supported at this time.
It is set to zero by default and is not changeable.

The Heartbeat Read Mapping entry is configured by the user. The entry accepts a reference to a
single REGISTER or COIL. The syntax only allows reads for a single register. The syntax is the
similar to that for the RemoteRef field in a GWF mapping entry with the notable difference that
only a single register or coil can be read.

Valid Entries Invalid Entries

COIL[60] COIL[1:5]
HREG[1000] HREG[1:10]
IREG[5]
INPUT[2]

Step IV: Configure the Modbus Registers (GWF object mappings)

This step maps the Modbus data to virtual BACnet objects. The ModbusTCP protocol does not
allow auto-mapping, so the GWD and GWF objects are created manually.

GWF Settings: Set Up Modbus Registers

The Protocol property of the GWF must be set to ModbusTCP when you create a new GWF.

Page 19 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Create the GWF in the Templates for ModbusTCP folder to set the correct protocol type.

Mappings
You create the required GWD and GWF objects manually as the ModbusTCP protocol does not
allow auto-mapping of the network. The gateway can also upload an xml configuration file.

For a longer start-to-finish example with GWF mappings for specific

devices, see Appendix B: Energy Meter Example

Add a Mapping
When you add a mapping, follow the ModbusTCP Protocol Driver syntax for the Remote
Reference and Data Types fields. The syntax demands precision but does provide great
flexibility for data manipulation. Refer to the ModbusTCP specific help included after the
standard help content for a field.

See the enteliBRIDGE Gateway User Guide for a general treatment of

mapping. The guide opens when you click on the ? Help icon in the upper
right area of the enteliBRIDGE web interface. The PDF file opens in a

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 20 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Workflow: Five Steps to Connect to Your Modbus Devices
Step IV: Configure the Modbus Registers (GWF object mappings)

separate window.

Syntax: Remote Reference Field

The protocol property of the GWF must be set to ModbusTCP. The Remote Reference field is
formatted as:

Remote Reference Field

Required parameters:
<type>[<addr>] -or-
[+<offset>]

Required and optional parameters:

<type>[<addr>:<count>] -or-
[+<offset>]

Optional parameter default values:

<count> = 1

Parameter values:
<type> = COIL // binary 1 bit data type
= INPUT // read only binary 1 bit data type
= HREG // 2 byte register
= IREG // read only 2 byte register
<addr> = 1 to 65536
<count> = 1 to 255
<offset> = 1 to 255

Where the following Data Types are available:

Data Type Explanation

COIL The data value is a Modbus coil (a read/write bit).
INPUT The data value is a Modbus discrete input (a read-only bit).
HREG The data value is a Modbus holding register (a read/write register).
IREG The data value is a Modbus input register (a read-only register).

Where the following parameters are available:

Parameter Description
addr The number of the data item in the Modbus device. This is the 1-based address
of the data item which is the standard way of documenting Modbus coils, inputs
and registers. In contrast, the address on the wire is 0-based.
For example:
Register 40001 is the first Holding Register (but may also be referred to as
Holding Register 0 or 0000H) and is entered as HREG[1:1]

Page 21 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Parameter Description
count The number of data items to read. For coils and inputs, this is the number of
bits. For registers this is the number of 2 byte registers. If not specified, the
count assumes a value of 1.
offset The offset into a previously specified sequence of items. For example, if the
first entry is HREG[5:10], then the second entry can be [+1] to indicate
HREG[6:9] read by the first entry. Offsets are not cumulative; they always
calculated relative to the original address.
Offsets are always the size of the RemoteRef, where [+1] offsets by 1 register (2
bytes) for registers and [+1] offsets by 1 bit for coils.
For example:
HREG[1:2] could be translated into a UINT16 data type and the next [+1] could
be translated into a second UINT16.
COIL[1:32] could be translated into a UINT16 data type and the next [+16] could
be translated into a second UINT16.

Remote Reference Field Examples:

The following reads and writes coil 60:

COIL[60]

The following polling with offset approach is preferred when requesting contiguous data as it is
more efficient. Less network bandwidth is required and the data collection is more rapid.

// Assuming UINT16 Data Type

HREG[10:3]
[+1]
[+2]

The previous HREG example does the following: (Assuming UINT16 data type)

• HREG[10:3] reads holding registers 10 through 12.

• [+1] offset starts at mapping holding register 11 if it follows the previous example.
• [+2] offset starts mapping at holding register 12 if it follows the two previous examples.
The HREG behavior also depends on the Data Type involved in the operation. See the Polling
with Offsets topic in the Additional Examples section.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 22 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Workflow: Five Steps to Connect to Your Modbus Devices
Step IV: Configure the Modbus Registers (GWF object mappings)

Syntax: Data Type Field

Data Type Field
Parameter values:
<bit-type> = BIT // 1-bit binary bit
<numeric-type> = UINT16 // 16-bit unsigned integer
= UINT32 // 32-bit unsigned integer
= UINT64 // 64-bit unsigned integer
= INT16 // 16-bit signed integer
= INT32 // 32-bit signed integer
= INT64 // 64-bit signed integer
= FLOAT // 32-bit floating point
<conversion> = *f // multiply result by f or <float> value
// (constant numeric values only) example: *0.25
= +f // add f or <float> to result
// (constant numeric values only) example: +100.5
= -f // subtract f or <float> from result
// (constant numeric values only) example: -50.0
= <<i // left-shift result by i or <int> bits
// (constant integer values only) example: <<3
= >>i // right-shift result by i or <int> bits
// (constant integer values only) example: >>1
<string-type> = CHARS // character string
= LENCHARS // character string prefixed by a 2 byte length
<mask-type> = MASK16 // 16-bit unsigned integer of only the masked bits
= MASK32 // 32-bit unsigned integer of only the masked bits
= MASK64 // 64-bit unsigned integer of only the masked bits

<byte-order> = 1234 -or- 2143 -or- 4321 -or- 3412

<length> = 1 to 32
<first-bit> = 0 to 15 for MASK16 -or- 0 to 31 for MASK32 or- 0 to 63 for MASK64
// 0 is LSB
<last-bit> = 0 to 15 for MASK16 -or- 0 to 31 for MASK32 -or- 0 to 63 for MASK64
// 0 is LSB

Element Description
BIT Used with COIL and INPUT types
UINT16, UINT32, Signed and unsigned integral values. 16 bit values take a single register
UINT64, INT16, or 16 coils; 32 bit values take 2 registers or 32 coils. The 64-bit values
INT32, INT64 take 4 registers.
FLOAT 4 byte floating point value. Takes up 2 registers or 32 coils.
MASK16, MASK32, Used to retrieve bit fields from within 1 or 2 registers or 4 registers.
MASK64 Non-masked bits are written to 0, so all bits in the registers should be
masked using offset mappings ''[+0]''.
CHARS Character string value with 2 characters per register. The length
indicates the number of characters.
LENCHARS Character string value with first register being a count (number of
characters) and 2 characters per register.

Page 23 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
The following parameters are available:

Parameter Description
byte-order Indicates the order in which the bytes are on the wire where 1 = least
significant byte and 4 = most significant byte. Defaults to 4321.
length 1..32 the number of characters in a CHARS data item.
first-bit The first bit of the bit field. 0 is the least significant bit. For MASK16, the
valid bit range is 0-15. For MASK32, the valid bit range is 0-31. For
MASK64, the valid bit range is 0-63..

Data Type Examples:

Data Type Explanation
BIT The Data Type of the value referred to by the Remote Reference of a
COIL or INPUT register. e.g. COIL[60]
UINT16(4321) An unsigned value from a single register, Most significant byte first on
the wire.
INT32 A signed 2 register value, the most significant byte is first on the wire.
The absence of the optional byte order parameter means that it
defaults to 4321 which is most significant byte first.
MASK16(5:7) A 3 bit value from a single register.
MASK64(40-47) A 8 bit value from a 4 register value.
CHARS(4)(1234) A string of length 4 saved as "s i m o" displayed in BACnet as "simo"

See the Data Explained in Detail section for more information.

Trend Log Support

With 1.1, the gateway supports Trend Logs within each GWF point mappings. The maximum
number is 5000 Trend Logs with a TL Buffer Size of less than 1000. In most cases, use a TL
Buffer Size that is close to its default value of 100. A typical value might be 200.

See the enteliBRIDGE Gateway User Guide which opens when you click
on the ? Help icon in the upper right area of the enteliBRIDGE web
interface. The PDF file opens in a separate window.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 24 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Workflow: Five Steps to Connect to Your Modbus Devices
Step V: Troubleshooting

Device Templates for Field Device

Device templates allow for ease of engineering. The preferred approach is to use existing GWF
template for a known Modbus device. The Delta Exchange has a repository of freely available
GWF templates that can be searched and downloaded to the gateway.

Step V: Troubleshooting
1. Confirm that the values read and decoded are correct. One approach is to pick a single
point with a known value and confirm that it reads in properly. Known values can be the
60 HZ, 120 or 240 VAC etc. Follow this approach for a single point for each of the
different data types needed for the application.
2. Recognize common problems which may involve:
• Reading the incorrect register or trying to read a register that does not exist.
• A Modbus device setup has an issue that is preventing the Gateway from seeing it.
• Older Modbus devices can communicate rather slowly and be lax in their
conformance to the Modbus standard.

Page 25 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Data Explained in Detail
This section provides further explanation of data representation, offsets, masks and data sizing.

Data Representation
This topic provides a visual explanation of data encoding. The Modbus standard uses a ‘big-
Endian’ representation for addresses and data items. This means that when a numerical
quantity larger than a single byte is transmitted, the most significant byte is sent first.
The following graphic shows the default 4321 byte order.

The following graphic shows the 1234 byte order.

Offsets
The following are some offset examples:

HREG[4]

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 26 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Data Explained in Detail
Offsets

// Assuming UINT16 Data Type is used for each reference

HREG[10:3]
[+1]
[+2]

COIL[22:3]
[+1]
[+2]

Page 27 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Masks
Masks are primarily used to get 1 or more individual bits from a register. They should only be
used on registers and not coils since coils are already given in bits. With the MASK data type, all
non-masked bits are set to 0. When mask data types are written, zeros are written to the
mapped registers to fill up the size of the mask. To stop non-masked bits being set to 0, create
MASK mappings for all of the bits:

Be careful when writing to mask data types because zeros are written to
the mapped registers to fill up the size of the mask. It is recommended
that masked data types are only used for reading and not writing.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 28 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Data Explained in Detail
Masks

In the previous example if you write AV3.Present_Value = 7 then

0x00007000 will be written to HREG[1:2] because the size of the mask is
32 bits but only the masked bits can be set and the rest will always write
zero's.

Page 29 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
ModbusTCP Protocol Driver Version 1.1 Application Guide Page 30 of 85
Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Data Explained in Detail
Data Sizing Considerations

In the previous example if you write to AV20.Present_Value = 3 then

0x30000000 will be written to HREG[7] because the size of the mask is 16
bits but only the masked bits can be set and the rest will always write
zero's. Therefore AV10.Present_Value will now be zero.

Data Sizing Considerations

Generally in a perfect world the selected size of the RemoteRef will be the same size of the
selected Data Type. However we have implemented the ability to have a smaller RemoteRef size
than the size of the Data Type. The following are some examples outlining these edge cases:

When mapping a COIL to an integer value, it is recommended to use 1234

byte ordering. The reason is that you can have a smaller data size COIL
array than the mapped data type. For example: COIL [1:3] can map to
UINT16.

Page 31 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Additional Examples
This section contains content that was not covered in the basic information contained in the five
workflow steps. The five steps in the previous general workflow focus more on the basic
function of the protocol driver.

GWD Object Subnet

You can set GWD.Address to use a subnet.
For example, consider a Gateway with two Ethernet ports as follows:

eCORE LAN1 = 192.168.2.189

eCORE LAN2 = 10.10.10.11
Modbus Device 1 = 192.168.2.55
Modbus Device 2 = 10.10.10.200

The GWD.Address fields would be 192.168.2.55 and 10.10.10.200

Data Types
This section explains some additional data type operations.

Data Type * Multiplier (Scaling)

Scaling helps to handle large numbers and the driver has advanced scaling built in for unit
conversion. A numeric value can also be added or subtracted from the BACnet value before it is
read or written.

The following examples show how to use the INT16*0.1 and INT32*0.1 datatypes:

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 32 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Additional Examples
Data Types

UINT64 and INT64 support scaling operators.

Scaling Example
Consider a register that holds 9876 (decimal) with a mapping of UINT32*0.1. The value in an AV
is 987.6
Scaling applies to the numeric types only.

The following shows the syntax used for scaling of a Data Type:

*<multiplier value>

Multiplies the result read from the Modbus register before storing in the BACnet property; or
divides the BACnet value by this amount (constant numeric value only) when writing to the
Modbus register.

The <Conversion> parameter also supports addition or subtraction of a factor or a float value
from the result before it is saved as a BACnet value.

<<bits to shift

Takes the results of the read and shifts the resultant bits to the left before storing in the
BACnet property. (Integers only)

Page 33 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
>>bits to shift

Takes the results of the read and shifts the resultant bits to the right before storing in the
BACnet property. (Integers only)

The following figure contains some sample mappings showing scaling operations for INT64
values mapped to a LAV. Mappings for a UINT64 are similar.

If a register value is shifted three bits to the right (>>3), then the result is equivalent to dividing
by 8 (2^3).

MASK Data Type

With the MASK data type, all non-masked bits are set to 0. To stop non-masked bits being set to
0, create MASK mappings for all of the bits:

Be careful when writing to mask data types because zeros are written to
the mapped registers to fill up the size of the mask. It is recommended
that masked data types are only used for reading and not writing.

The following diagram shows the bits received, masked, and the result:

The data is: (20125 decimal) 0100 1110 1001 1101 binary

MASK16(0:7) is equivalent to: 0000 0000 1111 1111 binary

A Boolean AND function is done on the data and the mask and the result is: (157 decimal) 0000
0000 1001 1101 binary

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 34 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Additional Examples
Polling with Offsets

The following example shows how to mask out groups of bits:

HREG[1:2], AV1, MASK32(0:7)

MASK64 is also supported.

CHARS Data Type

The following examples show how to use the CHARS datatype.

• RemoteRef: HREG[1:4]
• DataType: CHARS(6)

The length in a CHARS is a number of characters and there are 2 characters per HREG so
HREG[1:4] allows strings up to 8 chars in length. The data is translated as UTF-8.

Polling with Offsets

The following polling with offsets approach is preferred when requesting contiguous data as it is
more efficient. Less network bandwidth is required and the data collection is more rapid.

When polling with offsets:

HREG[1:32]
[+2]
[+4]

The driver polls the register set ([1:32]) once with a single ReadMultipleRegister request and it
then uses that data to fill the variables. The example will request 32 registers starting at
register address 1. Each HREG has 2 bytes.

In ModbusTCP, documentation for various devices can reference

registers in multiple ways. For example, one document may start with
holding register 1 (actual register: 40000) whereas another document
might start with holding register 0 (actual register: 40000). Beware!

The gateway polls the ModbusTCP registers at appropriate time when using offsets. Consider:

// Assuming UINT16 Data Type

HREG[10:3]
[+1]
[+2]

The previous HREG example does the following: (Assuming UINT16 data type)

• HREG[10:3] reads holding registers 10 through 12.

• [+1] offset maps starting at holding register 11 if it follows the previous example.

Page 35 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
 • [+2] offset maps starting at holding register 12 if it follows the two previous examples.

Consider a mapping with mixed data types:

RemoteRef Data Type Comment

HREG[1:32] UINT32 Reads a sequence of holding registers
[+2] UINT16 Maps holding register 3
[+3] UINT32 Maps holding registers 4 and 5
[+5] UINT32 Maps holding registers 6 and 7
[+7] UINT16 Maps holding register 8
[+8] UINT32 Maps holding registers 9 and 10
[+10] UINT32 Maps holding registers 11 and 12
[+14] UINT64 Maps holding registers 15 to 18
(8 bytes)

Specify Byte Order

The Delta gateway allows for byte ordering to be specified for each data value.

4321 is the default byte order.

For numerical data types (i.e. UINTxx, INTxx, FLOAT), we can specify the byte order as for
example UNIT32(4321) or UNIT32(1234) or UINT32 (2143) or UINT32 (3412) indicating which way
the bytes are to be read.

UINT64 and INT64 support all byte orders.

For example, the ordering (4321) is used with 1, 2 and 4 register values. For instance: INT16
(4321) or INT32 (4321) or INT64 (4321). The INT64 (4321) notation actually indicates a byte order
of 87654321 and INT16 (4321) indicates a byte order of 21.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 36 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Additional Examples
Using LAV Object to Handle 64-bit Integer Values

Mapping a COIL to an Integer Value

It is recommended to use 1234 byte ordering rather than the default (4321) when mapping an
array of COILs to an integer value. The reason is that you can have a smaller data size COIL
array than the mapped data type and using a byte ordering of 1234 will map the lower order
bytes. For example: COIL[1:3] can map to UINT16(1234).

Using LAV Object to Handle 64-bit Integer Values

A LAV object stores a large analog value of datatype Double and represents that value externally
according to the LAV object properties. The object value is stored as a double precision number
in the range +/-10E-308 to 10E+308. When the value is outside of this range, then ‘inf’ for infinity
is displayed. Data type Double means ANSI/IEEE-754 double precision floating point.

The driver supports 64-bit LAV types and this provides a good way to handle 64-bit integer
values from energy meters and other devices.

The driver supports UINT64, INT64 and MASK64.

LAV.PresentValue can convert to Modbus FLOAT, LENSCHARS, CHARS and BIT fields. The
present value can display up to 15 significant digits plus the exponent.

Page 37 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Appendix A: Modbus Basics Tutorial
This appendix is based on the Technical Support document titled: Modbus Data Types. (revision:
05 Jul 2010)

Modbus Data Types

In the world of Modbus there are 3 data types that we are concerned with:

• Bit Values
• Integers
• Floating Point Numbers

This document will explain the common ways integers and floats are encoded in a Modbus
device.

Modbus devices contain ranges of memory which can be read from and written to and are called
Registers. Registers can be thought of as being equivalent to BACnet objects like analog
variables and binary variables.

Each Modbus register is 16 bits (2 bytes) long.

Review of Numbering Systems

The decimal system stores information in a base-10 format - each place has a value from 0-9.
When integrating with Modbus it is important to be aware of the binary and hexadecimal
systems as well. Binary is a base-2 format and hexadecimal is base-16:

Decimal Hexadecimal Binary

0 0 0
1 1 1
2 2 10
3 3 11
4 4 100
5 5 101
6 6 110
7 7 111
8 8 1000
9 9 1001

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 38 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix A: Modbus Basics Tutorial
Review of Numbering Systems

Decimal Hexadecimal Binary

10 A 1010
11 B 1011
12 C 1100
13 D 1101
14 E 1110
15 F 1111
16 10 10000
17 11 10001

When looking at information directly inside Modbus device memory, or when looking at
information being transmitted over the RS-485 network, the values are displayed in
hexadecimal format.

Integers
If you have ever addressed a Delta controller through DNA, using the on board DIP switches,
you have already decoded an integer value. Each bit in an integer has a different value. When
converting from binary to decimal you add up the value of all bits set to 1 (same as when you
need to determine what the address of a controller is based on its DNA DIP switch). The value of
the bits is as follows:

Each bit is numbered from right to left, starting at 0. The value of each bit is equal to 2n where n
is the bit position. For the furthest right bit, which is commonly referred to as the Least
Significant Bit (or LSB), the value is 20 which equals 1. For the next bit over, the value is 21

Page 39 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
which equals 2. This continues on as you move from right to left. The bit with the highest value
is commonly referred to as the Most Significant Bit (or MSB).

Unsigned Integers
Integers come in 2 different types - the simpler of the 2 is unsigned. Unsigned integers have a
range of 0 to (2n - 1), where n is the number of bits:

• For an 8 bit (1 byte) unsigned integer the range is from 0 to (28 - 1) which is 0 to 255
• For a 16 bit (2 byte) unsigned integer (1 Modbus register) the range is from 0 to (216 - 1)
which is 0 to 65,535
• For a 32 bit (4 byte) unsigned integer (2 Modbus registers) the range is from 0 to
4,294,967,295
• For a 64 bit (8 byte) unsigned integer ( the range is from 0 to 18446744073709551615

As you can see, unsigned integers are whole numbers (no decimal place) and only positive.

Signed Integers
Signed integers can be positive or negative. Like unsigned integers they do not have a decimal
place. They split their range - half is positive and half is negative:

• For an 8 bit signed integer the range is from -128 to 127

• For a 16 bit signed integer the range is from -32,768 to 32,767
• For a 32 bit signed integer the range is from -2,147,483,648 to 2,147,483,647
• For a 64 bit signed integer the range is from -9223372036854775807 to
9223372036854775807

Encoding of Integers
The decimal value of an unsigned integer is determined by adding up the value of all bits set
to 1. Signed integers require 1 additional step:

• If the leading bit is set to 0: the value of all bits set to 1 are added (the same as an
unsigned integer).
• If the leading bit is set to 1: the value of all bits set to 1 are added (including the
leading bit) and 2n is subtracted from the number.
• For an 8 bit integer (1 byte) you subtract 28 which is 256
♦
• For a 16 bit integer (2 bytes - 1 Modbus register) you subtract 216 which is 65536
♦

Example 1: What is the decimal value of an 8-bit integer stored as 0x97? Solve as both unsigned
and signed integers.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 40 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix A: Modbus Basics Tutorial
Review of Numbering Systems

1. Start by breaking this number into its binary format: 0x97 = 1001 0111
2. Add up the value of all bit set to 1 to determine the value as an unsigned integer:
Unsigned Value = 128 + 16 + 4 + 2 + 1 = 151
3. The first bit is set to 1, so we must subtract 2n from this value to determine the signed
integer value:

Signed Value = 151 - 2n = 151 - 28 = 151 - 256 = -105

Example 2: What is the decimal value of a 16-bit integer stored as 0x4F68? Solve as both
unsigned and signed integers.

1. Start by breaking this number into its binary format:

0x4F68 = 0100 1111 0110 1000
2. Add up the value of all bit set to 1 to determine the value as an unsigned integer:
Unsigned Value = 16384 + 2048 + 1024 + 512 + 256 + 64 + 32 + 8 = 20328
3. The first bit is set to 0 so we do not need to subtract 2n - the signed value is the same as
the unsigned: Signed Value = Unsigned Value = 20328

Floating Point Numbers

Floating point numbers allow very large and very small numbers to be stored in a relatively
small block of memory compared to integers.

While a 32 bit signed integer has a range from -2,147,483,648 to 2,147,483,647 a 32 bit floating
point number has a range of +/- 10E-38 to +/- 10E38.

While there are 64 and 128 bit floats, Modbus will only ever deal with the 32 bit versions - the
increased precision and range is not necessary for Modbus applications.

Page 41 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Encoding of Floats

The 32 bits inside a floating point number are broken into 3 parts:

• Sign: when the sign bit is set to 0, the value is positive. When set to 1, the value is
negative. This follows the convention of signed integers.
• Exponent: these 8 bits are decoded as an unsigned integer. A bias of 127 is subtracted
(see equation below), allowing the exponent to be positive or negative. As a result the
exponent has a range of possible values from -127 to 128.
• Mantissa: the rest of the bits are the 'left overs'. The value of the mantissa is also
decoded as an unsigned integer.

These 3 parameters are fed into the following equation to determine the decimal value of the
float:

𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣 = 1. [𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚] 𝑥𝑥 2[𝑒𝑒𝑒𝑒𝑒𝑒 − 127]

Example 1: What is the decimal value of a floating point number stored as 0x42F0999A?

1. Start by breaking this number into its binary format:

0x42F0999A = 0100 0010 1111 0000 1001 1001 1001 1010
2. Determine the decimal values of the exponent and mantissa:
Exponent = 1000 0101 = 133 Mantissa = 111 0000 1001 1001 1001 1010 = 7,379,354
3. Use the equation to determine the value:

𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣 = 1. [𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚𝑚] 𝑥𝑥 2[𝑒𝑒𝑒𝑒𝑒𝑒 − 127]

6
𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣𝑣 = 1.7379354 𝑥𝑥 2[133 − 127] = 1.7379354 x 2 = 111.2278656

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 42 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix A: Modbus Basics Tutorial
Review of Numbering Systems

Because the leading bit was 0 we know the number is positive.

When you have an understanding of the different types of values used in Modbus, you can use a
free programming calculator application to convert values.

Page 43 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Appendix B: Energy Meter Example
This longer example uses actual meters to show the typical workflow for the simple case of
three different Modbus meters.

The target audience is partner personnel and system engineers who design and implement
systems for ModbusTCP sites.

The purpose is to create a longer example for specific meters and map selected points based on
the register table provided in the documentation for each meter.

This section shows how to configure the driver to communicate with Modbus meters. The
documentation and register table is consulted for three meters. This content is in addition to the
Workflow section. Screens and text show how to configure and map points for selected Modbus
data types for each meter.

Overview
This section presents a longer start-to-finish example for a specific basic application with
detailed explanation and many screens. The content includes many screen captures that show
steps in a visual manner in addition to text explanations. The intention is to provide an extended
example with GWF mappings of selected values for actual Modbus meters. The ModbusTCP
driver with enteliBRIDGE 1.0.14 is used.

Selected values are mapped based on information found in the register map table for each
meter. A sample of values is shown that illustrates how to handle different Modbus data types,
how to combine multiple register entries into a single value, and also how to handle scaling
operations. The section contains only a number of representative mapping entries for three
different meters. A typical project would contain many similar mapping entries. Mapping
examples also show the use of BDC and MIC for BI and MV objects.

It is assumed that you are aware of the contents of the enteliBRIDGE Gateway User Guide PDF
file. The User Guide contains general information about using the web interface to configure
and create mappings of ModbusTCP values to BACnet variables. ModbusTCP driver-specific
information is contained within this ModbusTCP Protocol Driver Version Application Guide. The
web interface also provides online help.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 44 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix B: Energy Meter Example
Overview

To view a PDF of the enteliBRIDGE Gateway User Guide, click on the

icon ( ? Help icon) in the upper right area of the user interface. A new
window displays the guide.
To view help for a field, hover the cursor over the area of the field on a
page. Help content displays at the bottom of the web interface.

While this example strives to be realistic, it has some limitations as it was created using a
simulator rather than real devices. The limitations of the simulator affect the device addressing
on the GWD screens.

Site Application Story

A complex with three buildings has existing power, BTU (heat) and flow (steam and water)
Modbus meters installed. The intention is to use these meters over ModbusTCP with the
enteliBRIDGE gateway to monitor, control and log the overall energy usage in these buildings.

The three buildings are:

1. Main: (Acuvim II Series Power Meter)

2. Production: (Shark 200 Power Meter)
3. Heating Utilities: (ONICON System-10-MOD BTU Meter)
Many values are organized into pairs or groups and these values need to be joined together to
generate the correct data value. Each register is 16 bits composed of two 8 bit words. For
example with a 32 bit variable, two 16 bit register entries representing MSB (Most Significant
Byte) and LSB (Least Significant Byte) are combined to form one value. We need to be aware of
the order used in the register for word, byte and bit elements. In many cases, the most
significant element is first and is followed by a less significant element. The gateway mappings
process includes means to manipulate data based on the way that the information is
transmitted over the wire.

The site consists of three buildings and has a central boiler for heating. A typical energy
management application might:

• Monitor
• Display dynamic energy graphics for usage awareness
• Trend and archive data. Do energy calculations for the whole building complex.

Page 45 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Step I: Consult Documentation for Modbus Devices on Site
The sample system has only 3 different types of devices. We need to know information about the
devices and to get a register table for each device. Also, the network and the specific
configuration options are selected based on this information.

For this tutorial, the site contains the following Modbus energy devices:

1. Acuvim II series multifunction digital power meter

2. Shark 200 power meter
3. ONICON System-10-MOD BTU heat meter

The focus is on these three meter types. We want to show the considerations involved in
mapping some typical Modbus data types for each meter. Of course, we would expect the
system to use water, steam and natural gas flow meters but we do not focus on these
components here.

Meters can provide values in real time and some values are also available as average,
maximum and minimum. The maximum and minimum values may also have associated
timestamps.

A site typically has multiple instances of a particular meter and in some cases the calculation
factors used in internal calculations may differ for one or more meters.

Documents
The documentation for each meter may use different conventions. For example, each of these
manuals uses a different notation for hexadecimal Modbus addresses.

Name Links
Acuvim II Series Power Meter User's Acuvim II Series Power Meter User's Manual
Manual Document #1040E2203 Revision Date: June 2015
https://www.accuenergy.com/files/acuvim-ii/Acuvim-II-Power-
Meter-User-Manual-1040E1303.pdf
Shark 200 & 200T Installation and Shark 200 & 200T Installation & Operation Manual V1.17 October
Operation Manual V.1.17 June 18, 9, 2012
2014 Document E149701
http://www.electroind.com/products/Shark200/pdf/manuals/Shar
k%20200%20Data-
Logging%20Power%20and%20Energy%20Meter%20with%20Expa
ndable%20IO%20User%20Manual%20V.1.17_E149701.pdf
BTU Heat Meter ONICON System- System-10-MOD Network Interface Installation Guide 05/14
10-MOD BTU Meter Installation http://www.onicon.com/pdfs/0653-10-System-10-MOD-Network-
Guide Interface-Installation-Guide-05-14.pdf

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 46 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix B: Energy Meter Example
Step I: Consult Documentation for Modbus Devices on Site

Terms
This topic explains some common terms.

The following parameters are measured and calculated:

• Power: An instantaneous reading of the present flow of watts. (watts)

• Energy: Integration of power consumed over a defined time. (kWh)
• Demand: Average rate of energy use per time interval adjusted to an hourly value.
(Kilowatt-hour/hour but uses just kilowatts)

Energy meters typically include both primary mode and secondary mode values:

• Primary mode: The numeric value in the register of the meter and equals the real
physical value.
• Secondary mode: A defined relationship exists between the register numerical value and
the real physical value. The calculation may rely on a number of parameters for
calculation and scaling of the result. You need to understand the calculations used on
each device.

The ONICON Heat Meters can operate in either of two modes:

• Heating (forward mode)

• Cooling (reverse mode)

Three Meters
The following table lists the meters for each building.

Building Meter Voltage Modbus Meter IP Address

Number VAC Meter Location 169.254.8.50:uXXX
Type Room Subnet
255.255.255.0
Gateway
xxx.yyy.zzz.0

1 52 208 ACUVIM A111 169.254.8.50:u1

Main Power II
2 83 208 Shark C7 169.254.8.50:u2
Production Power 200
3 92 n/a ONICON HUB12 169.254.8.50:u3
Heating BTU System-
Utilities 10-MOD

Page 47 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
With meters, the numerical value may not be the same as the communicated value. The
documentation contains a table that lists parameters and the defined relationships. Some
relationships involve division by a fixed scalar such as 100 and the communicated value needs to
be multiplied by 100 in the mapping to get the actual numerical value. Other parameters have
relationships that are defined by operations involving multiple factors. These factors can be set
and read. A site typically has multiple instances of a particular meter and in some cases the
factors may differ for one or more meters.

The driver now supports the 64-bit BACnet LAV type and this provides
a good way to handle 64-bit integer values from energy meters and
other devices.

The Acuvim II Series Multifunction Digital Power Meter

Building Meter Voltage Modbus Meter IP Address
Number VAC Meter Location 169.254.8.50:uXXX
Type Room Subnet
255.255.255.0
Gateway
xxx.yyy.zzz.0
1 52 208 ACUVIM A111 169.254.8.50:u1
Main II

For the secondary values, we need to be aware of the factors used to make calculations.

Address Parameter Default Range Data Type Property

1005H PT1 (High 16 bit 0 50.0~500000.0 word R/W
1006H PT1 (Low 16 bit) 220.0 50.0~500000.0 word R/W
1007H PT2 220.0 50.0~400.0 word R/W
1008H CT1 5 1~50000 word R/W
1009H CT2 5 1,5 word R/W

A site typically has multiple instances of a particular meter and in some cases the factors may
differ for one or more meters. In a mapping, a Data Type entry of FLOAT(4321)*120 means that
the value is multiplied by a scaling factor of 120.

The following graphic shows a segment from the register table in the documentation for the
Acuvim II meter. Note the use of the H notation to indicate a hex address.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 48 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix B: Energy Meter Example
Step I: Consult Documentation for Modbus Devices on Site

The following table contains a number of values selected from the register tables in the
documentation for the device. We would use this table to add mapping to a GWF.

The offset notation, [+1] or [+8] etc., allows for bulk retrieval of multiple values.
Name

Address HEX
Modbus

Ref Decimal
Remote

Ref
Local

Type
Data

Device Type
Units/

Read

Write
Modifiers
Write
Read/

(secs)
Stale Time
Acuvim II Power Meter
1 PT1 (High 1005 HREG[4101] AV1.PresentValue UINT16 retrieve-
16 bit) periodically
2 PT1 (Low 1006 [+1] AV2.PresentValue UINT16 retrieve- do-not-
16 bit) periodically poll
3 PT2 1007 HREG[4103] AV3.PresentValue UINT16 retrieve-
periodically
4 CT1 1008 [+1] AV4.PresentValue UINT16 retrieve- do-not-
periodically poll
5 CT2 1009 HREG[4105] AV5.PresentValue UINT16 retrieve-
periodically

6 System 402b HREG[16427:30] AV11.PresentValue FLOAT(4321) retrieve- not- 5000

reactive periodically writable
power
Qsum
7 System 4033 [+8] AV12.PresentValue FLOAT(4321) retrieve-on- not- do-not- 5000
apparent read writable poll
power
Qsum
8 System 403b [+16] AV13.PresentValue FLOAT(4321) retrieve-on- not- do-not- 5000
power read writable poll
factor
Qsum
9 Power 4043 [+24] AV14.PresentValue FLOAT(4321) retrieve-on- not- do-not- 5000
demand read writable poll
10 Reactive 4045 [+26] AV15.PresentValue FLOAT(4321) retrieve-on- not- do-not- 5000
power read writable poll
demand
11 Apparent 4047 [+28] AV16.PresentValue FLOAT(4321) retrieve-on- not- do-not- 5000
power read writable poll
demand

12 Energy 4049 HREG[16457:18] AV17.PresentValue INT32(4321)*.1 kWh retrieve- write- 5000

periodically through

Page 49 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
 Name

Address HEX
Modbus

Ref Decimal
Remote

Ref
Local

Type
Data

Device Type
Units/

Read

Write
Modifiers
Write
Read/

(secs)
Stale Time
13 Reactive [+4] AV19.PresentValue INT32(4321)*.1 kWh retrieve-on- write- do-not- 5000
energy read through poll
14 Energy [+8] AV21.PresentValue INT32(4321)*.1 kWh retrieve-on- write- do-not- 5000
TOTAL read through poll
15 Energy [+10] AV22.PresentValue INT32(4321)*.1 kWh retrieve-on- write- do-not- 5000
NET read through poll
16 Reactive [+12] AV23.PresentValue INT32(4321)*.1 kWh retrieve-on- write- do-not- 5000
Energy read through poll
TOTAL
17 Reactive [+14] AV24.PresentValue INT32(4321)*.1 kWh retrieve-on- write- do-not- 5000
Energy read through poll
NET
18 Apparent [+16] AV25.PresentValue INT32(4321)*.1 kVA retrieve-on- write- do-not- 5000
Energy read through poll
TOTAL

19 Max of 4175 HREG[ 16757:51] AV26.PresentValue INT16(4321) retrieve- 5000

System periodically
Power
20 Max of 417c HREG[ 16764) AV27.PresentValue INT16(4321) retrieve-on- write- do-not- 5000
System read through poll
Reactive
Power
21 Max of 4183 HREG[16771) AV28.PresentValue INT16(4321) retrieve- do-not- 5000
System periodically poll
Apparent
Power
22 Max of 4198 HREG[16792) AV29.PresentValue INT16(4321) W retrieve- do-not- 5000
Power periodically poll
Demand
23 Max of 419f HREG[16799) AV30.PresentValue INT16(4321) watt retrieve- do-not- 5000
Reactive hours periodically poll
Power reactive
Demand
24 Max of 41a6 HREG[16806) AV31.PresentValue INT16(4321) retrieve- do-not- 5000
Apparent periodically poll
Power
Demand

25 DI1 4386 HREG[17286:2] AV32.PresentValue UINT16(4321) m2 retrieve- not- 5000

counter periodically writable
high
26 DI1 [+1] AV33.PresentValue UINT16(4321) m2 retrieve-on- write- do-not- 5000
counter read through poll
low

27 DI2 4388 HREG[17288:2] AV34.PresentValue UINT16(4321) m2 retrieve- not- 5000

counter periodically writable
high
28 DI2 [+1] AV35.PresentValue UINT16(4321) m2 retrieve-on- write- do-not- 5000
counter read through poll
low

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 50 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix B: Energy Meter Example
Step I: Consult Documentation for Modbus Devices on Site

Watt Total (Demand)

The Watts Total (Demand) is based on a calculation with the return value multiplied by a couple
of other factors:

P=Rx×(PT1/PT2)×(CT1/CT2)
The Acuvim II registers (1005H to 1009H) are 16bit unsigned integer (UINT16) data types that
contain data for the 4 factors.

Shark Meter 200 Power Meter

Building 2 is Production.

Building Meter Voltage Modbus Meter IP Address

Number VAC Meter Location 192.168.108.xxx
Type Room Subnet
255.255.255.0
Gateway
xxx.yyy.zzz.0
2 83 208 Shark C7 169.254.8.50:u2
Production Power 200

The following graphic shows a segment from the register table in the documentation for the
Shark 200 power meter. Note the use of the 0x notation for a hex address.

See Appendix B: Modbus Map and Retrieving Logs section of the Shark 200/200T Meter
Installation and Operation Manual Version 1.13.

Page 51 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
The following table contains a list of values selected from the register tables in the
documentation for the device. We would use this table to map the selected values in a GWF.
Name

HEX
Modbus Address

Decimal
Remote Ref

Ref
Local

Type
Data

Device Type
Units/

Read

Write

Write Modifiers
Read/

Stale Time (secs)

SHARK 200 Power Meter
1 Amps A 03F4 HREG[1012:12] AV1.Present_Value FLOAT(4321) A retrieve- not- 500
periodically writable 0
2 Amps B [+2] AV2.Present_Value FLOAT(4321) A retrieve-on-read not- do-not- 500
writable poll 0
3 Amps C [+4] AV3.Present_Value FLOAT(4321) A retrieve-on-read not- do-not- 500
writable poll 0
4 Watts 3- [+6] AV4.Present_Value FLOAT(4321)*0.0 kW retrieve-on-read not- do-not- 500
ph total 1 writable poll 0
5 Vars 3- [+8] AV5.Present_Value FLOAT(4321)*0.0 Kvar retrieve-on-read not- do-not- 500
ph total 1 writable poll 0
6 Vas 3-ph [+10] AV6.Present_Value FLOAT(4321)*0.0 Kva retrieve-on-read not- do-not- 500
total 1 writable poll 0

7 W-hours 05DC HREG[1500:18] AV7.Present_Value INT32(4321) kWh retrieve- not- 500

Received periodically writable 0
8 W-hours [+2] AV8.Present_Value INT32(4321) kWh retrieve-on-read not- do-not- 500
Delivered writable poll 0
9 W-hours [+4] AV9.Present_Value INT32(4321) kWh retrieve-on-read not- do-not- 500
Net writable poll 0
1 W-hours [+6] AV10.Present_Valu INT32(4321) kWh retrieve-on-read not- do-not- 500
0 Total e writable poll 0
1 VAR- [+8] AV11.Present_Valu INT32(4321) kvar retrieve-on-read not- do-not- 500
1 Hours e writable poll 0
Positive
1 VAR- [+10] AV12.Present_Valu INT32(4321) kvar retrieve-on-read not- do-not- 500
2 Hours e writable poll 0
Negative
1 VAR- [+12] AV13.Present_Valu INT32(4321) kvar retrieve-on-read not- do-not- 500
3 Hours: e writable poll 0
Net
1 VAR- [+14] AV14.Present_Valu INT32(4321) kvar retrieve-on-read not- do-not- 500
4 Hours: e writable poll 0
Total
1 VA-hours [+16] AV15.Present_Valu INT32(4321) kva retrieve-on-read not- do-not- 500
5 Total e writable poll 0

1 W-hours 062E HREG[1583] AV16.Present_Valu INT32(4321) kwh retrieve- not- 500

6 in the :10] e periodically writable 0
interval
received
1 VAR- [+2] AV17.Present_Valu INT32(4321) kwh retrieve-on-read not- do-not- 500
7 hours in e writable poll 0
the
Interval:
Positive
1 VAR- [+6] AV18.Present_Valu INT32(4321) kwh retrieve-on-read not- do-not- 500

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 52 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix B: Energy Meter Example
Step I: Consult Documentation for Modbus Devices on Site

Name

HEX
Modbus Address

Decimal
Remote Ref

Ref
Local

Type
Data

Device Type
Units/

Read

Write

Write Modifiers
Read/

Stale Time (secs)

8 hours in e writable poll 0
the
Interval:
Negative
1 VA-hours [+6] AV19.Present_Valu INT32(4321) kvar retrieve-on-read not- do-not- 500
9 in the e writable poll 0
Interval:
Total
2 VA hours [+8] AV20.Present_Valu INT32(4321) kVa retrieve-on-read not- do-not- 500
0 in the e writable poll 0
interval:
Total

2 Amps A: 07D0 HREG[2000:22] AV21.Present_Valu FLOAT(4321) A retrieve- not- 500

1 Average e periodically writable 0
2 Amps B: [+2] AV22.Present_Valu FLOAT(4321) A retrieve-on-read not- do-not- 500
2 Average e writable poll 0
2 Amps C: [+4] AV23.Present_Valu FLOAT(4321) A retrieve-on-read not- do-not- 500
3 Average e writable poll 0

CT PT numerator, denominator, multiplier are found at 752F to 7533 (30000-30004). Refer to the
Programmable Settings Section of the mapping table in the documentation.

ONICON System-10-MOD BTU Meter

Building 3 is Heating and Utilities and includes steam heat for the whole complex. A gas-fired
package boiler generates steam that is used for heating and industrial processes.

The BTU meter accepts inputs from multiple sensors and calculates the quantity of heat being
transferred. The meter provides heat flow per unit time outputs and also totalized values.

http://www.onicon.com/pdfs/0653-10-System-10-MOD-Network-Interface-Installation-Guide-
05-14.pdf

Building Meter Modbus Meter IP Address

Number Meter Location 169.254.8.50.xxx
Type Room Subnet
255.255.255.0
Gateway
xxx.yyy.zzz.0
3 92 ONICON HUT12 169.254.8.50:u3
Heating System-
Utilities 10-MOD

Page 53 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
It is recommended by ONICON to use floating point format to transmit data over a network.
Floating point also removes the need to do scaling and other operations to generate totalized
flow and energy. By convention, the initial 4 in a Modbus Hex address means that it refers to a
holding register.

41001 (A029H) defines the Meter Operating Mode as an Integer: 1 = single mode; 2 = dual mode;
3 = bi-directional mode. (Create a 3 state MIC for Mode: Single, Dual, and Bi-Directional)

41002 (A02AH) defines the Mode Status Indicator as an Integer: 1= heating mode or forward
direction; 2= cooling mode or reverse direction. (Create a 2 state BDC for Status: Heating,
Cooling)

The meter uses the following data types:

• unsigned integer registers (0 to 65,535)

• 16 bit signed integer values (-32,768 to +32,767).
• 32 bit single precision floating point values. (preferred format for network
communications)
The following graphic shows a segment from the register table in the documentation for the
ONICON System-10 BTU meter. Note the use of 4xxxx notation with an initial 4 at the start of
each address to indicate a holding register address.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 54 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix B: Energy Meter Example
Step I: Consult Documentation for Modbus Devices on Site

The following table contains a number of values selected from the register tables in the
documentation for the device. We would use this table to list values that we want to map in a
GWF.

Registers 41003 through 41064 provide totalization of energy, volume and mass flow data in 32
bit single precision floating point format. The registers are organized mainly into pairs that
must be concatenated. Some totalizers such as 400026 (Low Order), 40027(Middle Order), 40028
(High Order), use three registers to accumulate a large energy total. The registers can be joined
using Modbus offsets as shown in the following table.
Name

HEX
Address
Modbus

Ref Decimal
Remote

Ref
Local

Type
Data

Device Type
Units/

Read

Write3333
Modifiers
Read/ Write
(secs)
Stale Time
BTU Heat Meter ONICON System-10-MOD BTU Meter
1 Meter Operating Mode A020 1001 MV1. Present_Value UINT16 retrieve- not- 5000
(Create MIC with periodically writable
1=Single, 2=Dual,
3=Bi-Directional)
2 Meter Status (create A02A 1002 BV1. Present_Value BIT retrieve- not- 5000
BDC with 1=Heating, periodically writable
2=Cooling)

3 EnergyRate-BTUpHr A02B HREG[1003:14] AV3.Present_Value FLOAT BTU/Hr retrieve- not- 5000

periodically writable
4 EnergyRate-KW [+2] AV4.Present_Value FLOAT KW retrieve- do- 5000
on-read not-
poll
5 EnergyRate_Tons [+4] AV5.Present_Value FLOAT Tons retrieve- do- 5000
on-read not-
poll
6 VolumeRate-GPM [+6] AV6.Present_Value FLOAT GPM retrieve- do- 5000
on-read not-
poll
7 VolumeRate-GPH [+8] AV7.Present_Value FLOAT GPH retrieve- do- 5000
on-read not-
poll
8 VolumeRate-MPD [+10] AV8.Present_Value FLOAT MGD retrieve- do- 5000
on-read not-
poll
9 VolumeRate-LpS [+12] AV9.Present_Value FLOAT L/S retrieve- do- 5000
on-read not-
poll

10 Supply Temperature- A043 HREG[1027:12] AV10.Present_Valu FLOAT degF retrieve- not- 5000
degF e periodically writable
11 Return Temperature- [+2] AV11.Present_Valu FLOAT degF retrieve- do- 5000
degF e on-read not-
poll
12 Supply Temperature- [+4] AV12.Present_Valu FLOAT degC retrieve- do- 5000
degC e on-read not-
poll
13 Return Temperature- [+6] AV13.Present_Valu FLOAT degC retrieve- do- 5000

Page 55 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
 Name

HEX
Address
Modbus

Ref Decimal
Remote

Ref
Local

Type
Data

Device Type
Units/

Read

Write3333
Modifiers
Read/ Write
(secs)
Stale Time
degC e on-read not-
poll
14 Energy Total Mode2- [+8] AV14.Present_Valu FLOAT BTU retrieve- do- 5000
BTU e on-read not-
poll
15 Energy Total Mode1- [+10] AV15.Present_Valu FLOAT BTU retrieve- do- 5000
BTU e on-read not-
poll

16 Energy Total Mode1- A053 HREG[1043:4] AV16.Present_Valu FLOAT kWHr retrieve- not-
kWHr e periodically writable
17 Energy Total Mode2- [+2] AV17.Present_Valu FLOAT kWHr retrieve- do- 5000
kWHr e on-read not-
poll

Pulse Totalization
The register pair 41063 and 41064 can provide pulse totalization using the optional auxiliary
pulse input board for the System-10 BTU Meter. This option can totalize pulse outputs from
water or gas meters. The maximum count is 9,999,999.

A remote reference entry with an offset would join the pulse registers:

HREG[1063:4]
[+2]

Step II: Modbus Networking and Wiring

Confirm that enteliBRIDGE® gateway has the ModbusTCP protocol driver installed and
communicating on the target network. The enteliBRIDGE gateway comes with a two-page Quick
Start Guide that explains how to connect the unit to a network. The enteliBRIDGE User Guide
also has relevant information.

A newer frontend such as enteliWEB 4+ provides the means to create, view and edit BACnet
objects including newer ones such as LAV which are often useful when mapping points.

A BACnet frontend such as ORCAview provides access to older BACnet objects.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 56 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix B: Energy Meter Example
Step III: Establish Communication with Gateway (GWS and GWD objects)

Step III: Establish Communication with Gateway (GWS and GWD

objects)
Next, we need to add and configure a GWS object for a ModbusTCP protocol driver instance.

A: Create GWS1 Instance

1. From the landing page, click on the Main tab. The page shows the GWS instances for
each protocol driver.
2. Click on Create at the bottom of the grid.
3. Enter a Name.
4. Select the Protocol from the options available in the dropdown list.

5. Click OK. A GWS instance for the ModbusTCP protocol driver appears. Generally, you
would accept the defaults.
The following shows the ModbusTCP GWS1 for Seaside Energy:

Page 57 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
When a GWD and GWF with mappings are created for the Acuvim II power meter, the GWD and
GWS objects are enabled.

The Enable checkbox is found at the top of the page for each object. When you enable or disable
a GWD or GWS, click the save button in the lower right area.

B: Create a GWD for the Power Meter in Each Building

We create at least one GWD object for each device that provides measurements. These device
objects are associated with the ModbusTCP protocol driver instance.

You can create a GWF for each meter and reference it in the Device Template field of the GWD.
Name the GWF objects as follows: Acuvim II Power, Shark 200 Power, and ONICON Sys10 BTU
Meter. The approach is to first establish basic communications with the GWS and GWD objects
and then later in the process to add mapping entries to each GWF.

In Step IV: Configure the GWF Point Mappings of the workflow, mappings are added for the
required data points.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 58 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix B: Energy Meter Example
Step III: Establish Communication with Gateway (GWS and GWD objects)

For this example, we might create one GWD object for each of the following meters:

Building Meter Voltage Modbus Meter IP Address

Number VAC Meter Location 169.254.8.xxx
Type Room Subnet
255.255.255.0
Gateway
xxx.yyy.zzz.0
1 72 208 ACUVIM A111 169.254.8.50:u1
Main II Power
2 84 208 Shark B12 169.254.8.50:u2
Production 200
Power
3 92 n/a ONICON HUT12 169.254.8.50:u3
Heating Sys-10
and Heat
Utilities

The following three GWD objects were created for the meters:

Page 59 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
The following graphic shows the Setup tab for the B1 Main (GWD1) which handles the Acuvim II
Power Meter for Building 1 Main. The Device Template field contains a reference to the GWF
created for this meter.

The following graphic shows the Configuration tab for GWD1 which handles the Power Meter for
Building 1 Main.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 60 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix B: Energy Meter Example
Step III: Establish Communication with Gateway (GWS and GWD objects)

The following shows the Setup tab of the GWD2 which handles the Shark 200 Power Meter for
Building 2 production.

Page 61 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
C: Create GWD for BTU Heat Meter
The following graphic shows the Setup tab for B3 Heat and Utility (GWD3) which handles
ONICON System 10 Heat (BTU) Meter.

Step IV: Configure the GWF Point Mappings

This step shows how to map representative points for each meter.

The general process is to add a row entry into the mapping grid, save it, and then use the
system feedback and error messages to fix all error in an entry. Sometimes, it helps to refresh
the window (F5) during the error fixing process. If you created GWF objects prior to creating the
GWD objects, then add mappings to the existing GWF that is referenced in each GWD object.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 62 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix B: Energy Meter Example
Step IV: Configure the GWF Point Mappings

A: Add GWF Mappings for ACUVIM II Power Meter

Page 63 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
The following graphic shows some possible GWF mappings for an Acuvim II Series Multifunction
Digital Power Meter.

The following graphic shows only the mapping grid.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 64 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix B: Energy Meter Example
Step IV: Configure the GWF Point Mappings

B: Add GWF Mappings for Shark 200 Power Meter

The Shark 200 power meter objects are created in a similar manner as the Acuvim II Power
Meter.

The following graphic shows only the mapping grid.

Page 65 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
C: Add GWF Mappings for ONICON System-10-MOD BTU Heat Meter
The ONICON System-10 heat meter objects are created in a similar manner as the Acuvim II
Power Meter.

The following graphic shows only the mapping grid.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 66 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix B: Energy Meter Example
Step IV: Configure the GWF Point Mappings

D: Create and Use BDC/ MIC with a Mapping

This topic shows an example of how to use BDC / MIC configuration objects with a GWF point
mapping.

The ONICON System-10-MOD BTU Heat Meter has Meter Operating Mode Indicator and Mode
Status Indicator entries in its register table.
Name
Ref HEX
Remote

Decimal
Ref
Remote

Ref
Local

Type
Data
Type
Device
Units/

Read

Write
Modifiers
Write
Read/
(secs)
Stale Time
BTU Heat Meter ONICON System-10-MOD BTU Meter
Meter Operating A020 1001 MV1. UINT16. retrieve- not-
Mode Present_Value periodically writable
41001
(Create MIC with
1=Single, 2=Dual,
3=Bi-Directional)
Meter Status A02A 1002 BV1. Present_Value BIT retrieve- not-
41002 periodically writable
(create BDC with
1=Heating,
2=Cooling)

The following graphic shows a segment from the register table in the documentation for the
ONICON System-10 BTU meter.

Page 67 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Create a BDC Configuration Object
• Create any BDC objects that you need.
A BDC provides text that is associated with the states of a binary value. The Status entries are:
Heating, and Cooling.

Create an MIC Configuration Object

• Create any MIC objects that you need.

An MIC associates text with the states of a multistate value. The StateText entries are: Single,
Dual, and Bi-Directional.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 68 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix B: Energy Meter Example
Step IV: Configure the GWF Point Mappings

E: Specify a BDC/MIC in a GWF Mapping (1.0.14)

For more details, see View/ Edit a GWF Mapping Entry topic in the enteliBRIDGE User Guide for
1.0.14

1. In the left navigation pane, if necessary click on a specific protocol to expand the folder.
2. Double click on the Templates folder for the ModbusTCP protocol. The right pane
provides information about the three types of template objects. Clicking on one of the
three tabs shows a list of existing objects.
3. Click on the Device Templates tab. A list of GWF objects appears. You can edit a GWF by
adding a Mapping that uses a BDC/MIC object to an existing GWF.
4. Specify a BDC/MIC object by entering the instance number in the Units/ Device Type
field. Based on the Local Reference, the application selects either the BDC or MIC
instance.
The following graphic shows that for the first mapping row, the Units/ Device Type field
contains 1 which references MIC1. In the second mapping row, the Units/ Device Type
field contains 3 which references BDC3.

Click Save.

In enteliBRIDGE 1.0.14, you can specify an MIC or BDC by entering the

instance number of the configuration object in the Units/ Device Type field.
For example with a COIL RemoteRef, a BV local reference, and a BIT
Modbus data type, you would enter 2 in the Units Device Type field to
specify BDC2.
In enteliBRIDGE 1.1, any BDC/MIC objects suitable for a particular
mapping are included in the Units /Device Type dropdown list.

For more information, see the procedures in the GWF: Binary Templates (BDC) and Multistate
Templates (MIC) section of the enteliBRIDGE User Guide for 1.0.14.

Page 69 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Step V: Troubleshooting
Consider the following:

1. GWF Mappings: Confirm:

a. Correct entry in the register table is read?
b. Data type is correct?
c. Local Reference BACnet object type agrees with the Modbus data type?
d. Scaling in Data Type in the mapping is correct?
e. Correct parameters for meter calculated quantities? (individuals meters may
differ)
f. Programs read intended values and handle them correctly.
g. Data elements combined correctly?
2. Correct conversion factors in PG or other program? If multiplied by *0.01 then you need
to multiple the Data Type by a scaling factor of 100. Often the associated programming
also uses conversion and scaling factors that need to be correct. .
3. Are you using signed INT when an unsigned UINT would do the job?
4. Confirm the rollover value for accumulators / totalizers. The registers may roll over and
increment the following register at some multiple other than 65536. For example, 10,000
is sometimes used.
5. Do not assume that the same parameters / multipliers are used in all meters that are
the same model. A site typically has multiple instances of a particular meter and in
some cases the factors may differ for one or more meters.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 70 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix C: Troubleshooting: Interpreting System Feedback Messages
Working with GWD Objects ModbusTCP

Appendix C: Troubleshooting: Interpreting System

Feedback Messages
This topic presents content that aims to help a user interpret and act on the feedback provided
by the web interface and the ModbusTCP protocol driver. The web interface also provides
general help and additional driver-specific help displays at the end of the help entry.

The system provides feedback that helps a user to configure a gateway using the ModbusTCP
protocol driver with the GWD and GWF objects. The web interface and object dialogs provide
feedback for field entries and a temporary message displays at the top after most actions.

The Setup tab of the GWD object page includes these fields that provide feedback: Status,
Reliability, Description of Halt, GWS Description of Halt and Last Error.

Additionally, the message system provides feedback for the row entries of the GWF mapping
table grid.

Working with GWD Objects ModbusTCP

a: Gateway Not Loaded Yet (GWD)

Comment Actions Result

The Description of Halt Not a) Fix the ModbusTCP Address. The GWS Status field now
Loaded yet message indicates b) Enable the GWD if necessary. indicates Running instead
a missing or invalid c) Enable the GWS object if of stopped.
ModbusTCP Address on the necessary.
GWD. Click Save and refresh the
web interface.

Page 71 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
b: GWF Configuration Error (GWD)

Comment Actions Result

The GWD indicates a GWF Check the mappings on the GWF The GWD reads in data.
error. associated with the GWD. Fix any
Click Save and refresh the
issues.
web interface.

c: Query Failed: OS::SEND_FAIL (GWD)

Comment Actions Result

The GWD indicates a Check that the physical Modbus The GWD reads in data.
communication failure. device is online and
Click Save and refresh the
communicating.
web interface.

d: Communication Timeout (GWD)

Comment Actions Result

Polling issues a) Check that the physical The GWD reads in data.
Modbus device is online and
Click Save and refresh the
communicating.
web interface.
b) Check the Modbus Address on
the GWD.
c) Check the mappings on the
GWF associated with the GWD.
Fix any issues.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 72 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix C: Troubleshooting: Interpreting System Feedback Messages
Working with GWD Objects ModbusTCP

e: Empty ProtoX Address (GWD)

Comment Actions Result

Missing ModbusTCP Address Enter a valid ModbusTCP Click Save and refresh the
Address on the GWD. web interface.

The GWD reads in data.

The Description of Halt

message does not display
anymore.

f: Description of Halt (GWD) – Failed to Query device.

Comment Actions Result

Device Query issue. a) Check that the physical Click Save and refresh the
Modbus device is online and web interface.
communicating.
b) Check the mappings on the The GWD reads in data.
GWF associated with the GWD. The Description of Halt
Fix any issues.
message does not display
anymore.

g: Description of Halt (GWD) – Failed to poll device DEVICE:

BAD-DESTINATION-ADDRESS

Page 73 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Comment Actions Result

Missing ModbusTCP address. Enter a valid ModbusTCP Click Save and refresh the
Address on the GWD. web interface.
The GWD reads in data.

The Description of Halt

message does not display
anymore.

GWF Template Mappings ModbusTCP

If there is an error in the mappings, then a configuration error message appears above the
templates table. The Error Description message states that there is an invalid configuration
item and also specifies the row where the error is located.

For example, if the Data Type property for the first row is invalid, the Error Description reads:

OBJECT::INVALID_CONFIGURATION Unknown conversion function (Mappings[

1].expectedDataType).

You might have entered INTEGER32 by mistake when BIT is the correct choice. You would
change the Data Type to BIT and click Save. You may also need to do a refresh of the window.
The temporary message at the top would display Mapping OK and the Reliability field would
display no-fault-detected. In 1.1, the Reliability field does not change.

The following graphic shows the GWF Mapping tab from the gateway 1.1 web interface. In 1.0.14,
there was only one tab.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 74 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix C: Troubleshooting: Interpreting System Feedback Messages
GWF Template Mappings ModbusTCP

The following graphic shows the GWF Configuration tab from the enteliBRIDGE Gateway 1.1 web
interface.

Working with GWF Mapping Entries

In GW 1.0, a typical mapping process is to fix the flagged issues one by one until all the errors
are addressed. The displayed error message relates to the first occurrence of an error state. An
error message displays for only one error at a time. When this first error is fixed, if another
error exists, the next error is then indicated by the feedback system. When all the mapping
errors are fixed, the Reliability field of the GWF then shows no-fault-detected. During this
process, press Save after a change. Sometimes, it may help to refresh the web interface. In 1.0,
any configuration error disables the entire GWF and no virtual objects are created for the GWF.

Page 75 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
In GW 1.1, the behavior differs from GW 1.0. Any erroneous mappings are disabled in 1.1. The
Reliability field does not change - it always shows "no-fault-detected". Configuration errors do
not prevent the GWF from functioning. All correct mappings have corresponding virtual objects
created for them. Mappings that are in error are disabled and do not have virtual objects
created.

The following demonstration sequence shows what happens when you start with two correct
entries and then deliberately make a typical error in a column starting with Name and
continuing with RemoteRef etc. The intention is show the system response to a single deliberate
error and then fix this error. If needed, refer to the help available at the bottom of the web
interface.

Typically, after you fix one error, the system provides feedback on the following error. This
process continues until each error is fixed up to the last mapping.

a: Invalid Remote Reference

The Error Description for an invalid RemoteRef with the end bracket missing: HREG[1001

Comment Actions Result

Remote Reference Fix the syntax of the remote Click Save and refresh the
reference. For example, add the web interface.
missing ending bracket and put:
HREG[1001] The Error Description field is
blank and the Reliability
indicates ‘no-fault-detected.

b: Incorrect Data Type

Comment Actions Result

Data Type Fix the data type so that it Click Save and refresh of the

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 76 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix C: Troubleshooting: Interpreting System Feedback Messages
GWF Template Mappings ModbusTCP

agrees with the RemoteRef. web interface

Also check for a typing error. The Error Description field is
For example, you could have blank and the Reliability
entered UINT19 when the indicates ‘no-fault-detected.
correct value is: UINT16

c: Incorrect Read: Offset Entries Must NOT be Read-Periodically

The error message indicates that the Read/Write Modifier must not be do-not-poll for an Offset
(e.g. [+1] entry. The error message indicates that an entry that uses an offset in the RemoteRef
must NOT be set to retrieve-periodically in the Read column.

Comment Actions Result

Read/Write Modifier Change the Read/Write Modifier Click Save and refresh of the
for the mapping entry to ‘do- web interface.
not-poll’.
The Error Description field is
For example, the Offset entry in blank and the Reliability
the second row could contain an indicates ‘no-fault-detected.
offset [+1] in the RemoteRef
column but with the incorrect
retrieve-periodically.

Page 77 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Appendix D: Glossary of Modbus Terms
This section explains terms usage within the context of the ModbusTCP protocol driver.

Term Explanation
Bit 2 state (binary) data.
The Data Type of the value referred to by the Remote Reference of a
COIL or INPUT register. e.g. COIL[60]
Byte order The order in which each byte of data (8 bits) is received or sent to a
Modbus register that assembles it to correctly represent the data.
Client/server The requesting device is called the client (Modbus Master) and the
devices that supply the information are called servers (Modbus
Slaves). Using computer terminology, a master is a client and a slave
is a server.
COIL In Modbus, a coil provides a way to read and write Boolean values.
Coils often represent binary outputs or internal bits which allow both
read and operations.
Data type A data type is a classification identifying one of various types of data,
which determines the possible values for that type. The type
determines the operations that can be done on values of that type; the
meaning of the data; and the way values of that type can be stored. For
this driver, types include: unsigned integer, signed integer or Boolean.
Data Type Specifies the Data Type of the value referred to by the Remote
field Reference. The options available depend on the protocol driver.
Debug Specifies the datatypes of configuration parameters. The specific
Comms protocol driver defines the names, types and semantics of each
(GWS) configuration item.
Values are limited to 255 characters. Binary values are formatted as
HEX strings and must have an even number of ASCII chars (e.g.
002f30). Case is ignored.
When set to 1, the ModbusTCP driver will generate extra debug for
certain communication events to the GWS log.
Debug Specifies the datatypes of configuration parameters. The specific
Errors (GWS) protocol driver defines the names, types and semantics of each
configuration item.
Values are limited to 255 characters. Binary values are formatted as
HEX strings and must have an even number of ASCII chars (e.g.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 78 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix D: Glossary of Modbus Terms
GWF Template Mappings ModbusTCP

Term Explanation
002f30). Case is ignored.
When set to 1, the ModbusTCP driver will generate extra debug for
certain internal errors to the GWS log.
Debug Specifies the datatypes of configuration parameters. The specific
Requests protocol driver defines the names, types and semantics of each
(GWS) configuration item.
Values are limited to 255 characters. Binary values are formatted as
HEX strings and must have an even number of ASCII chars (e.g.
002f30). Case is ignored.
When set to 1, the ModbusTCP driver will generate debug output for all
requests to the GWS log.
Device Specifies the protocol specific address of this device. The address
address must be unique for this GWS (no other GWD associated with this GWS
(GWD) can have the same address value.)
The Address format is:
ipaddr[:port][:unit#]
The Port field indicates the port in the ModbusTCP device that the
gateway should connect to. It defaults to 502 which is the default
ModbusTCP port. The Unit field is used to select the Modbus RTU
device behind the ModbusTCP device that this GWD represents. This
field defaults to 1.
The GWD.Address differs from the BACnet device address.
Discrete A Modbus discrete input (a read-only bit).
Input
Float 4 Byte (dual register) positive or negative decimal values
(+/- 10E-38 to +/- 10E38)
Functions Modbus commands are called functions. A function is a command to
read or write a data table address. Each available function has a
number. Read Single is a function 01 type.
Gateway This object contains settings that apply to a specific protocol.
Settings
object (GWS)
Gateway This object contains settings that apply to a real or virtual device that
Device object communicates the protocol. There can be many devices per GWS (per
(GWD) protocol).
Gateway This object provides a template mapping for protocol devices. The
format protocol driver using mappings in this object to translate from

Page 79 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Term Explanation
object (GWF) protocol-specific datatypes to BACnet datatypes.
HREG Typically used to represent analog outputs or internal numbers which
(Holding are read/write. The registers are read/write 16 bit integers.
Register)
INPUT Typically used to represent analog input values and other integer
Register values which are read only. The registers are read only 16 bit integers.
(IREG)
Integer UINT16: 2 Byte (single register) positive integer values (0 to 65,535)
values UINT32: 4 Byte (dual register) positive integer values (0 to
4,294,967,295)
UINT64: Byte (quad register) positive integer values (0 to
18446744073709551615)
INT16: 2 Byte (single register) positive or negative integer values
(-32,768 to 32,767)
INT32: 4 Byte (dual register) positive or negative integer values
(-2,147,483,648 to 2,147,483,647)
INT64: 4 Byte (quad register) positive or negative integer values
(-9223372036854775807 to 9223372036854775807)
Latency Latency is an expression of the time delay in getting a data packet
from one designated point to another in a network. The term “latency”
refers to time delays typically incurred in the processing of network
data.
Local A local reference specifies the BACnet object that is being mapped to.
Reference For example: PIV1.Present_Value refers to the Present Value of the
BACnet Positive Integer Value 1 variable.
mapping Specifies how a protocol-specific value or point is translated into a
entry BACnet object.
MASK Used to extract one or more bits from a binary value. Use MASK with
Registers but not with COILS.
MASK32 retrieves bit fields from within 2 registers while MASK16 is
within 1 register. MASK64 retrieves bit fields from within 4 registers
Max Sockets This is the size of the socket pool used by the GWS to communicate
(GWS) with other devices.
Modbus Modbus is a client/server or master/slave type protocol. It was
developed as a serial communication protocol.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 80 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix D: Glossary of Modbus Terms
GWF Template Mappings ModbusTCP

Term Explanation
ModbusTCP Internet access to MODBUS is available at the reserved system port
502 on the TCP/IP stack. TCP is Transmission Control Protocol.
Modbus Modbus ASCII is similar to Modbus RTU but encodes the data as ASCII
ASCII instead of binary.
Modbus The requesting device is called the Modbus Master and the devices
Master/Slave that supply the information are called Modbus Slaves. Using computer
terminology, a master is a client and a slave is a server.
The master can initiate transactions (queries) but the slaves can only
supply the requested data, or perform the action requested in a query.
Modbus The message sent on the network by the Client to initiate a
Request transaction.
Modbus The Request message received on the Server side.
Indication
Modbus The Response message sent by the Server.
Response
Modbus The Response Message received on the Client side.
Confirmation
Modbus RTU Controllers communicate on a Modbus network using RTU (Remote
Terminal Unit) mode. Within a message each eight-bit byte contains
two four-bit hexadecimal characters. This mode provides greater
character density than ASCII for the same baud rate. It is used with
RS-232 and RS-485 connections.
Offset Used to specify a relative register or coil number to read. The offset is
relative to the register or coil specified by the previous mapping.
Poll interval Defines the length of one poll interval in milliseconds. The Poll Type
determines how many items are polled in one poll interval.
When using 1-per-Interval polling, set the interval to slightly longer
than the expected time it would take to poll one item from a Modbus
device. This time is dependent on the response time of devices being
used.
When using All-per-Interval, select a time which longer than (#
mappings) * (expected time per mapping).
Poll Type Specifies the polling behavior of the device.
The options are: constant, 1-per-interval, all-per-interval, and custom.
Constant: Poll through the request list at the Poll Interval (e.g. every
1000 msec) and then restarts at the beginning when complete.

Page 81 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Term Explanation
1-per-interval: Requests one piece of data for each interval. Used
where network can only tolerate a limited number of requests.
All-per-interval: Request all data in the specified interval. When all
have been read, the GWS waits until the Poll Interval completes before
it starts requesting again.
Custom: The protocol driver has a custom method for polling. This is
only provided by drivers which need special handling for the polling of
data values.
The ModbusTCP driver does not support COV or CUSTOM.
Register A Modbus data type that consists of two bytes.
Remote Specifies the protocol-specific object being mapped.
Reference
Scaling Many Modbus devices represent data as a scaled value in order to
constrain the data to a single register. For example, a temperature of
72.5 would be represented as 725.
Modbus devices regularly use scaling to return integer based values
for non-integer based data.
The ModbusTCP protocol driver allows for scaling to be defined in the
mapping of the register to a BACnet point so that the appropriately
scaled data is presented to the user.
A typical examples is to use the INT16*0.1 or INT32*0.1 data types in a
mapping entry on a GWF object.
Transaction The basic unit of communication over MODBUS/TCP (or MODBUS) is a
called a transaction. Through a combination of request and response
messages, a client can do an operation. A client might request a server
to do a read or to write data operation.
Virtual The BACnet representation of a non-BACnet device within the BACnet
device network. The enteliBRIDGE gateway handles all requests for data from
the virtual devices it represents.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 82 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Appendix D: Glossary of Modbus Terms
GWF Template Mappings ModbusTCP

Glossary Sources include:

http://www.modbus.org/docs/Modbus_Messaging_Implementation_Guide_V1_0b.pdf

http://www.modbus.org/docs/Modbus_Application_Protocol_V1_1b3.pdf

http://mblogic.sourceforge.net/mbapps/ModbusBasics-en.html

http://www.lammertbies.nl/comm/info/modbus.html

http://en.wikipedia.org/wiki/Modbus

http://www.scorpioncontrols.com/info/modbustcp.htm

Page 83 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
Copyright
Copyright © Delta Controls Inc. All rights reserved.
Document Title: ModbusTCP Protocol Driver Version 1.1 Application Guide SDK:1.1 DRV: Nov 3
2016.18:21:27
Edition: 1.24 Date of edition: November 7, 2016
No part of this document may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language
(natural or computer), in any form or by any means, without the prior written permission of Delta Controls Inc.
Limited permission is granted to reproduce documents released in Adobe® Portable Document Format (PDF) electronic format in
paper format. Documents released in PDF electronic format may be printed by end-users for their own use using a printer such as
an inkjet or laser device. Authorized distributors of Delta Controls Inc. products (Delta Partners) may print PDF documents for their
own internal use or for use by their customers. Authorized Delta Partners may engage a printing or copying company to produce
copies of released PDF documents with the prior written permission of Delta Controls Inc.
Information in this document is subject to change without notice and does not represent a commitment to past versions of this
document on the part of Delta Controls Inc. Delta Controls Inc. may make improvements and/or changes to this document/the
associated software/or associated hardware at any time.
BACspec, BACstat, the Delta logo, ORCAview, ORCAweb, Earthright, enteliBRIDGE, enteliWEB, enteliBUS, enteliMESH,
enteliTOUCH, enteliVIZ, enteliZONE, enteliSTAT, and Virtual Stat are registered trademarks of Delta Controls Inc.
Modbus is a registered trademark of Schneider Electric.
BACnet is a registered trademark of the American Society of Heating, Refrigeration and Air-Conditioning Engineers (ASHRAE).
Microsoft, Windows Server, Windows 7 and Windows 8 are registered trademarks of Microsoft Corporation.
Intel is a registered trademark of Intel Corporation.
All other trademarks are the property of their respective owners.

ModbusTCP Protocol Driver Version 1.1 Application Guide Page 84 of 85

Document Edition 1.24 SDK:1.1 DRV: Nov 3 2016.18:21:27
Copyright
Document Revision History

Document Revision History

Edition Date Published Change Description
1.0 February 20, 2015 Preliminary edition for the 1.0.13 Beta 2 Release.
1.1 April 19, 2015 1.0.14 Release edition.
1.11 June 22, 2015 Fix exponents on page 32 in Appendix A: Modbus
Basics Tutorial so 20 instead of 20 and 21 instead of
21. Also do 10 minor copy/format edits.
1.2 June 5, 2016 Add new Appendix B: that has a longer example for
three Modbus energy meters with a focus on GWF
mappings. Add Appendix C: Troubleshooting:
Interpreting System Feedback Messages. Improve
screen captures. Focus is 1.0.14 but includes some
1.1 information.
1.21 July 6, 2016 Add driver version information. Update two screens
on page 60 plus revise the corresponding Acuvim II
Power Meter mapping table on page 45 in Appendix
B: Energy Meter Example.
1.22 September 23, 2016 Add LAV support and also UINT64, INT64 including
byte ordering and MASK64. Mention Trend Log
support and TL Buffer Size. Revise capacity values
in the Specifications.
1.23 September 30, 2016 Do final edits for release.
1.24 November 7, 2016 Add GWD heartbeat configuration function.

Page 85 of 85 ModbusTCP Protocol Driver Version 1.1 Application Guide

Document Edition 1.24
www.deltacontrols.com