Modbus in Struxureware

[Don Halvorson]

These rules might not apply to every site in every situation, but they should provide a good jumping off point when attempting to work with Modbus in SBO

Modbus Notes:

 

1. Go to the properties of the device. Disable non-contiguous reads and device identification. The poll register is likely a holding register (Read Code of 03) and the register number is shown in R2 under the Device Status > Config section of the device properties. This error shows as controllers being offline.

 

2. You need to determine whether the registers are holding register (read code 03) or input registers (read code 04). Here, they were all set to 03 when they needed to be 04. (The practical application of this is to offset the registers by either 30000 or 40000 in accordance to the Modbus standard). This error shows as all values with a red X in the watch window.

 

3. Use Modbus Register groups. They allow a group read code (same as above) and a group poll interval (default to 1000ms if you don't have one). Also, make all of the values that were shown in R2 even if they weren't used in R2. It helps with the reading. This error shows as values starting fine in the watch window then getting a red X after a short amount of time; a.k.a. the values go stale.

 

4. Each of the Modbus registers needs to be offset by 1; i.e. 1 becomes 2. The register status itself is at the value given through R2, so Reg 1 on the group is the register + 1. This is in addition to the offset for the read code. This effects both inputs and outputs. This error shows up as one value with a red X (probably the first value). 

 

5. For the AOs, I used Read Code 03 and Write Code 06. I couldn't find the setting in R2 where this would be different, so I would default to these values. This error shows up as output values with a red X next to the AO value in the watch window.

[Tyler Smith]

Modbus Network Setup

Serial Modbus 

Modbus is a serial protocol than runs on an 2 or 4 wire network. Only one master is allowed on the trunk.

Network Setup

To setup a network in EBO, determine if the AS will be the master device or not.

If the AS is the master, the AS will be facilitating communications between other controllers and polling controllers when needed.

Create a Modbus Master Network. This will allow you to create controller objects underneath to represent the controllers on the trunk.

• This is the most typical setup with serial communication (com port A/B). Unless the device is connected via IP/Ethernet, use this to set up your network.
  

If the AS is NOT the master, another device will be in control when writing or reading data to or from the AS.

Create a Modbus Interface.  This represents the memory that other devices on the network will write to, and makes the AS act as though it were a modbus device. Change the device address here.

Create a Modbus Slave Network. This will start communications on the network using the AS as a slave device. Change the communication port here.

• You cannot have a Modbus Slave Network and a Modbus Master Network in the same AS. Only one device can be a master on the same trunk.
  
• You cannot have more than 1 Modbus Slave Network on the same AS. EBO is limited to 1 Modbus trunk per AS-P.
  

Modbus/TCP

Modbus over TCP is a protocol that runs over IP using ethernet cables. There is no concept of a master/slave here.

Network Setup

If the AS does not need to act as a modbus device, 

Create a Modbus TCP Network. This will allow you to create controller objects underneath to represent the controllers on the network.

• This is the most typical setup with IP communication (Ethernet). Unless the device is connected via RS-485, use this to set up your network.
  

If the AS needs to be written to by other controllers,

Create a Modbus Interface. This represents the memory that other devices on the network will write to, and makes the AS act as though it were a modbus device. Change the device address here.

Create a Modbus TCP Server. This brings the controller online as a device that can be read from.

• You can have both a Modbus TCP Server and a Modbus TCP Network on the same AS. Controllers can write to the AS, and the AS can write to controllers.
  
• You cannot have both a Modbus TCP Server and a Modbus Slave Network. The device cannot act as both a serial modbus device and a modbus/TCP modbus device at the same time.
  
• You can have a TCP and a serial modbus network on the same AS, as long as they are not both acting as a modbus device. (previous rule)
  

Modbus Serial Over TCP

In special cases, you may have an IP device that is routing modbus TCP packets to a serial network detached from your AS.

Network Setup

Create a Modbus TCP Gateway. This will be used in place of a Modbus Slave Network or Modbus Master Network, since the modbus gateway will be acting as the master device on the serial side.

Addresses vs Registers

When referring to documentation for Modbus devices, the documentation may use either Register or Address when referring to the data address. Address 0 should always correspond to register 1, address 1 to register 2, and so on. This is where the discrepancy of data addresses might differ by ±1.

• Address 0 should always correspond to register 1
  
• EBO will always refer to points as registers.
  
• R2 will refer to points as either registers OR addresses.
  

Modbus In R2

Modbus in R2 is handled in Register Groups. This performs a sequential read, which is generally more efficient than reaching each point individually, even if parts of the sequential read aren't used.

To the left is the properties of ModbusGenericAI_2. 

the DataAddress field of the modbus group is 00115. Since Registers are Addresses + 1, in this example:

Base Address + Offset	Actual Register	Reg#	AI Name
00115 + 1	00116	Reg1	PF_Total
00115 + 5	00120	Reg5	kW_Total
00115 + 6	00121	Reg6	kVAR
00115 + 7	00122	Reg7	kVA
00115 + 8	00123	Reg8	KW_A

The dataType is also important to set, and will need to be checked for each point, though typically controllers will stick to one type per analog, and one type per digital 

In the example above, the dataType is Integer, which corresponds to 16-Bit Unsigned.

R2 Data Type	EBO Equivalent
Integer	16-Bit Unsigned
Long	32-Bit Unsigned
Float	32-Bit Real
SignedInteger	16-Bit Signed
Coil	Digital coil
Input	Digital Input

The last thing to watch out for is the scale. Modbus points don't have any concept of decimal points. If decimal points are needed, the number is divided by a number (a power of 10 usually). In the example above, the first register has 2 decimal points, so it is multiplied by a factor of 0.01. Scale and Offset ( * 1.0 + 0)  in R2 will correspond to GAIN and OFFSET in EBO, and can be set for each individual value.

If a digital point that is read-only in R2 is set up as an Digital Input, you may have to change the read function code in EBO to read as a Coil Status (1)

Advanced

Modbus Communication overview

Modbus Packets are extemely simple, which is why they can be difficult to setup. Other than no response from a controller, there is no error checking to say you are reading the correct point.

Packets are configured like this:

(Controller Address) + (Function Code) + (Register) + (Data)

The first part is the controller address to write to.

The second part is the function code, which tells the controller what to do with the data

The third part is the register to write the data to

and the last part is the data itself.

Types of Function (Read/Write) Codes in EBO

Function Code	Effect	Typical* Effective Range
1	Read Coil Status	00001-09999
2	Read Input Status	10001-19999
3	Read Holding Register	40001-49999
4	Read Input Register	30001-39999
5	Write Single Coil Status	00001-09999
6	Write Single Register	40001-49999
15	Multiple Write Coil**	00001-09999
16	Multiple Write Register**	40001-49999

*Though the modbus standard is to group your point data in these ranges, it was not enforced strictly.

**Many controllers do not support multiple read/write

There are other function codes available, but none of them are within the scope of passing values between the controllers.

Types of Modbus points

Type	Description	Data	Value Range	Address Range	Read codes	Write codes
Coil Status	Binary Read only	1 bit	0-1	00001-09999	1
Input Status	Binary Read/Write	1 bit	0-1	10001-19999	2	5, 15*
Input Register	Analog Read Only	16 bits	0-65535	30001-39999	4
Holding Register	Analog Read/Write	16 bits	0-65535	40001-49999	3	6, 16*

*Many controllers do not support multiple read/write

The read codes are swapped for the analog points (read code 3 corresponds to address range 40001-49999)

Data Types

Modbus registers can only hold 16 bits of information each. to use a 32 or 64 bit number (most analog bacnet points use 32 bit), you will need to specify that this point is taking up two or more registers.

Here is some of the terminology defined while setting up modbus points.

Type	description
Analog / Multistate	--
16 bit	Default. 1 register per value. 2^16 values possible. Also known as a Word ( or 2 bytes)
32 bit	2 registers per value. 2^32 values possible. Also known as a Double Word.
48 bit	3 registers per value. 2^48 values possible
64 bit	4 registers per value. 2^64 values possible. Also known as a Quad word.
unsigned Integer	This value is only capable of positive numbers. A 16 bit unsigned integer can hold whole numbers between 0-65535
signed Integer	This value is capable of negative numbers, at the cost of the first bit of precision. A 16 bit signed integer can hold whole numbers between -32767 -> +32767
real/integer	Real (aka floating point) analog values are stored in scientific notation (e.g. 3.24 * 10^4). This allows a greater range of values that can store extremely big numbers, or extremely small numbers, but not both at the same time. The values might not always be represented accurately either, but most software can compensate for these shortcomings. If real or float is not specified, assume that the value is an integer (or int), and that no decimals are represented unless there is a gain less than 1.
mod10k	'Modulo 10,000' requires multiple registers. Each register holds an integer value from 0-9999 and when used in a program are concatenated for use. For example, reg1:(4022) + reg2:(5333) = value:40225333
swapped	Reverses the order of the bits, which is necessary for some controllers.
Gain	Multiplies the read value by this number before using. This can be used to represent decimal points when multiplying by a decimal number less than 1. A gain of 0.01 (10^-2) will show 2 decimal points.
Offset	Offsets the value by this number by adding it to the value. For example, this feature could be used to calibrate a sensor if the controller has no way to internally calibrate. This would not effect the value inside the controller.
Digital	--
Digital Coil	0/False or 1/True, for use with writing to input statuses.
16 bit unsigned	0/False or 1/True, used with the bit masks for writing to holding registers.
Multibit	--
(default)	Commonly with writing or reading from modbus points, they will use a holding register to hold a block of 16 digital points instead of read/writing them individually. This can usually be used even if the controller does not support multiple read/write functions. Multibits can only be found when using the AS as a modbus device (the Modbus Interface)

If there is a series of 32 bit modbus points to read, since each point takes up 2 registers, you will be incrementing the register by 2 for each point. 

Similarly, a 64 bit modbus point would use 4 registers each, so a point would have an address at every 4th register.

1/2's Compliment

1/2's compliment are methods for storing bits that allow a higher range of numbers without using any more storage. There is currently no easy way to represent 2's compliment numbers in EBO, a script implementation will need to be used if this is required.