3.14. Modbus


3.14. Modbus
Prev	Chapter 3. Properties Window	Next

The Modbus option provides Modbus master support for Modbus/TCP. Using this with the OPC DA option enables the DataHub program to function as a Modbus OPC server.

The Add Slave, Edit Slave, and Remove Slave buttons allow you to add, edit, or remove a slave connection, as described below. The Load Modbus Configuration button allows you to load an XML file to configure the DataHub program. For an example of the XML code, you can refer to the plugin_Modbus.cfg file located with the configuration files.

Clicking Add Slave or Edit Slave will open the Connect to Modbus Slave dialog with the following options:

Connection

Name

A unique name for this connection. The system auto-generates the name MBnnn where nnn is an incrementing number starting at 000.

Host / IP Address

The name or IP address of the Modbus slave.

Port

The port number used to connect to the Modbus slave. The default port is 502.

Retry Rate (ms)

A value in milliseconds of how often the DataHub instance should attempt to retry the connection to the Modbus slave, in case of failure to connect.

Share existing socket

When more than one connection is made to the same IP address and port number there is an opportunity for the DataHub Modbus driver to share the same socket for all such slave connections. If you select this option, the Modbus driver will find any other slave connections to the same IP address and port, and combine them into a single socket connection. If you do not select this option then the connection to the slave will occur on a distinct socket from other slaves on the same IP address and port. This selection is on a per-slave basis. There can be at most one shared socket to any IP address and port, and any number of non-shared sockets.

Serialize messages on a socket

If a socket is being shared, setting this option tells the DataHub Modbus driver to serialize the communication with the devices. That is, not send a message until the previous message has produced a response. This is necessary for some devices that expect the Modbus master to transmit a single message and then wait for either a response or a timeout. For this type of device, if the master transmits more than one message at a time, only the first message is processed and the others are lost.

If none of the connected devices require serialized messages, you should not set this option. It is more efficient to transmit requests to all of the slave devices at once, and then to wait asynchronously for the responses to come back. That way, if a particular slave is off-line or is very slow, it will not affect the timing of the communication with the other slave devices, since the results of the query can arrive in any order and independently of one another. You can think of this kind of communication as parallel multiplexing of the shared socket, instead of serialized messages.


	Serializing messages will, in general, produce longer latencies when communicating with more than one slave device, and will introduce significant delays for all slaves when any slave is slow to respond. Effectively, this will couple the slave device polling timing. Thus, you should not set this option unless your target slave device requires it.


	If you have configured more than one slave connection to share a socket, then setting this option on any of those slave connections will cause all slave connections sharing the same socket to also be serialized.

Modbus Options

The DataHub program supports nine of the most commonly used Modbus read and write functions, as illustrated in the following two tables:

Table 3.1. Supported Modbus Read Functions

Code	Function Type	Function Name
1	Internal Bits or Physical Coils	Read Coils
2	Physical Discrete Inputs	Read Discrete Inputs
3	Int/Physical Output Registers	Read Holding Registers
4	Physical Input Registers	Read Input Registers

Table 3.2. Supported Modbus Write Functions - Optional

Code	Function Type	Function Name
5	Internal Bits or Physical Coils	Write Single Coil
6	Int/Physical Output Registers	Write Single Register
15	Internal Bits or Physical Coils	Write Multiple Coils
16	Int/Physical Output Registers	Write Multiple Registers
22	Int/Physical Output Registers	Mask Write Register

The Modbus driver can write all of the value types that it can read. You may select which Modbus functions will be available for writing during configuration of the slave connection. If no function is enabled that would allow the driver to write a particular value then that value will not be written to the Modbus slave. The slave device must support Masked Write Register (function 22) in order to write to a bit field within a register.

Polling Rate (ms): A value in milliseconds of how often the DataHub instance should poll the connection to the Modbus slave for data updates.
Max message length (bytes): The maximum message length that the slave device can support. The Modbus specifications set this length to 256, but some devices may vary from that. Check your device documentation, and set this value accordingly.
Slave ID: A value in the range of 0 - 256. This setting is useful for TCP Modbus when the connection goes via a serial gateway to multiple slave devices, and the target slave device needs to be identified. Setting this value to 0 means a non-specific broadcast to all devices.
Timeout (ms): A value in milliseconds for the response timeout.

Addressing

These options are provided to facilitate configuration, allowing the selected addresses to match the documentation of the slave device.

Bits within registers start at 1 instead of 0

If you are accessing bit fields within a register, this option lets you choose which bit to start with.

Bit 0 in register is most significant bit

If you are accessing bit fields within a register, this option tells the driver whether to treat the lowest order or highest order bit as the first bit.

When packing digital values into an integer (see below), the order of the digital bits will be determined by this setting. If checked the highest address in the field will be packed into integer bit 0. If not, the digital bit in the lowest address in the field will be packed into integer bit 0.

Addresses start at 1 instead of 0

A convenience option allowing you to start your address numbering at 1 instead of 0.

Data Points

Here you configure the points in the DataHub instance that correspond to register addresses in the Modbus slave. Detailed information about the configured points for this slave gets displayed in the list.

Choose Add Point to add a single point, or Add Range to add a range of points.


	If you select an existing, configured point from this list, when you click the Add Point button the system will make a copy of that point, incrementing the address and highlighting the DataHub point name.

Data Domain: The data domain in the DataHub instance for all of the data points for this slave connection.

Address and Type

The Add Point, Add Range and Edit buttons in the Connect to a Modbus Slave window (above) all open the Configure Data Point Address dialog:

I/O Type

A pick list of the four supported I/O types:

0: Digital Output (coil)

1: Digital Input (discreet)

3: Analog Input (input register)

4: Analog Output (holding register)

When one of these is chosen, the following selections are given default values.

Number Type

Available for analog inputs and outputs only, the options are Integer, Float, and String.

Encoding

Encoding for integers can be 16, 32, or 64 bit; for floats 32 or 64 bit.

Strings are stored as groups of contiguous registers. The bytes of each register in the string are ordered according to the byte order selection (see Swap, below) and then converted to a character string using one of the following encoding methods:

ASCII Each byte is interpreted as an 8-bit ASCII character. Two characters are stored in each register. If the configured number of registers is insufficient to store the entire string then the string will be truncated.
UTF-8 Each byte in a register is interpreted as a single byte in the UTF-8 stream. If the string contains only 7-bit ASCII characters then UTF-8 is equivalent to ASCII. A single UTF-8 character can require up to 5 bytes (2.5 registers) to store. The number of characters that can be stored in a sequence of registers is therefore variable. If the configured number of registers is insufficient to hold the entire UTF-8 sequence then all bytes beyond the register length will be truncated to the nearest character. This option is displayed in Flags in the Connect to Modbus Slave window as "u".
UTF-16 Each character is normally stored in a single register. For some characters, a second register may be necessary to store the entire character. If the configured number of registers is insufficient to hold the entire UTF-16 sequence then the sequence will be truncated to the nearest character.

Swap

These options allow you to specify the byte order of the data stored in the Modbus slave device. The natural byte order in Modbus is big-endian, meaning that the most significant byte is stored first. The DataHub Modbus driver assumes that the data in the slave device is big-endian unless you specify otherwise. If you know that your slave device stores its data in a different order, you can use the swap options to specify which bytes, words or dwords are swapped in the slave device relative to the standard big-endian representation.

All possible byte order combinations can be produced by selecting zero or more of the following:

Bytes: each pair of bytes gets swapped. For example, AB would become BA; ABCD would become BADC.
Words: each pair of words gets swapped. This is only applicable when the length of the value is at least 4 bytes. For example, ABCD would become CDAB; ABCDEFGH would become CDABGHEF.
DWords: two dwords get swapped. This is only applicable when the length of the value is 8 bytes. For example, ABCDEFGH would become EFGHABCD.

These options are displayed in Flags in the Connect to Modbus Slave window as "b" for Bytes, "w" for Words, and "d" for DWords.

Other examples:

Swapping both bytes and words: ABCD - DCBA
Swapping both bytes and dwords: ABCDEFGH - FEHGBADC
Swapping both words and dwords: ABCDEFGH - GHEFCDAB
Swapping bytes, words, and dwords: ABCDEFGH - HGFEDCBA

Sign

The sign indicates whether a particular integer should be interpreted as signed or unsigned. There is no distinction in the Modbus slave register, so the sign is applied by the Modbus master driver. The Signed option is displayed in Flags in the Connect to Modbus Slave window as "-".

Deadband

An optional means to filter out insignificant value changes.

When the DataHub Modbus driver writes a value from the Modbus slave device to the DataHub instance, it notes that value as significant. Each subsequent incoming value gets compared to that last significant value, and is only written to the DataHub instance when the difference is greater than the amount specified by the deadband. Any new value that gets written then becomes the latest significant value to be used for future deadband comparisons.

An entry of 0 means that no deadband applies, and all value changes will be considered significant.


	No deadband is applied when writing values from the DataHub instance to the Modbus slave device. All value changes will be written to the device.

Address

The Modbus register address(es) to link to DataHub point(s).


	The information in the table below also pops up when you hover your mouse over this entry field.

Addresses can be specified as individual values, ranges of values, bit fields within a register, and ranges of bits within a register. Here is a guide of the address formats.

	Address Format	Description	Example	Refers to
Digital Points	`address`	A single value.	`12`	The digital value in address 12.
	`address-address`	A "packed" integer composed of up to 64 consecutive digital bits.	`12-17`	A 6-bit integer created by packing digital values `12-17` into integer bits `0-5`.
	`address[N]`	An array of `N` consecutive values starting from `address`.	`13[5]`	An array of 5 digital values starting at address 13.
Analog Points	`address`	A single value.	`4`	The 16, 32 or 64 bit integer starting at register 4.
	`address.bit`	A single bit within an integer.	`4.3`	The third bit of the integer starting at register 4.
	`address.bit-bitend`	A range of bits within an integer.	`4.3-27`	Bits 3 through 27 (inclusive) within the integer starting at register 4.
	`address[N]`	An array of `N` consecutive values starting from `address`.	`10[5]`	An array of 5 analog values (16, 32 or 64 bit) starting at address 10.
Strings	`address[N]`	A string consuming at most `N` 16-bit registers.	`10[20]`	A string of up to 20 registers, starting at address `10`. This could hold 40 ASCII characters, between 8 and 40 UTF-8 characters, or between 10 and 20 UTF-16 characters.

For Digital and Analog Points

address is the Modbus register address corresponding to the data point, starting from 0 (or optionally from 1), within the I/O block for that register type. I/O blocks can be one of Analog Input, Analog Output, Digital Input and Digital Output. All values of any bit length other than digital values are considered to be analog. All bit fields within a register are also considered to be analog.
bit is the bit number, starting from zero (or optionally from 1) within an integer data type. The bit number cannot be larger than the number of bits in the selected data type. For example, if the data type is a 32-bit integer then bit can be from 0 to 31 (or 1 to 32).
endbit is the last bit in a multi-bit bit field. This can be any number from bit + 1 to the highest bit number in the selected data type. If endbit is equal to bit, it will be treated the same as if endbit was not specified. The resulting bit field will be converted to signed or unsigned integer of the same size as the selected integer type.

Packing Digital Values

When packing digital values into an integer, the order of the digital bits will be determined by the setting Bit 0 in register is most significant bit (see above). If this is not checked then the digital bit in the lowest address in the field will be packed into integer bit 0. If this option is checked then the highest address in the field will be packed into integer bit 0.
Packed digital values can be up to 64 bits in length. You can use the Convert to type option in the Transform section to determine the data point type of the result. You may specify any signed or unsigned integer type, though you should specify a type that is large enough to hold the selected number of bits.

For Strings

N is the number of 16-bit registers to use for storing the string. This is the maximum number of registers in the string, not the maximum number of characters. The maximum number of characters will depend on the character encoding selected, and the string to be stored. For example, UTF-8 strings can require up to 5 bytes per character.
The bytes in a string are packed into the registers such that 8-bit types (ASCII and UTF-8) store 2 characters per register and UTF-16 stores one character per register. The Swap option (see above) determines which of the two bytes is treated as the first character.

Point name

Any valid DataHub point name, without a domain name. (The domain is specified in the Connect to Modbus Slave dialog). A dot ( . ) in the point name will create an assembly or sub-assembly in the domain hierarchy.

Ranges

A range is a labour-saving method for specifying many similar data points at one time. By choosing Add Range instead of Add Point for adding points, you can specify a point once, and then enter a value in the Item Count to repeat that specification for that number of points. The range will automatically create new points with consecutive addresses based on the selected data type.

Point names are numbered consecutively, starting from the Start Number that you specify, incrementing by one for each point name in the range. The point name in a range must contain a .NET format specifier that tells the driver how to construct the point name and where to insert this number. The specifier is one of these forms:

`{0}`	The current sequence number, with no additional leading zeros.
`{0:Dn}`	The current sequence number, prefixed with additional zero characters to pad the number to `n` characters.

The format specifier does not need to be at the end of the point name. For example, the Point name entry:

mb.tank{0:D2}_level

with an Item Count of 3 and a Start Number of 5 would produce point names like this:

mb.tank05_level
mb.tank06_level
mb.tank07_level

If you specify a range of bit masks within registers, then these rules apply:

If the bit field contains exactly one bit then the range will be all consecutive bits within the same register (or 32- or 64-bit integer as specified in the data type).
If the bit field contains more than one bit then the range will consist of the same bits taken from consecutive registers (or 32- or 64-bit integers as specified in the data type).

Allow writes to Modbus device

Enables or disables writes to the Modbus slave for this point or range.

Transform

Specify the type of transformation by clicking Direct copy, Linear Transformation, or Linear Range Mapping.

Direct copy does not apply a transform. It copies the value from the Modbus slave directly to the DataHub point.
Linear Transformation lets you multiply by one value and add another value, such as in the equation y = mx + b where the DataHub point is y, the Modbus value is x, the multiply by value is m, and the then add value is b. For example to transform a Celsius value in the Modbus slave to a Fahrenheit value in the DataHub instance, you would multiply by 1.8 and add 32, or
```
Fahrenheit = (1.8 X Celsius) + 32
```
Linear Range Mapping lets you enter a range for the Modbus slave and DataHub Data Points, and the DataHub instance automatically calculates the corresponding linear transformation.

For example, the multiply by and then add entries to convert a Fahrenheit value in the Modbus slave to a Celsius value in the DataHub instance would not be simple round numbers. But you can let the system do the math by using the entries of 32 and 212 for the Min and Max of the Modbus value, and 0 and 100 for the Min and Max of the Data Point. As soon as you make these entries, the correct values get entered automatically in the Linear Transformation.
Entries for Clamp are applied to all values read into or written out of the DataHub instance for this point. So, the value read from the Modbus slave will never exceed the clamped range. Or, when a value is written to the DataHub point from another source, the clamp is applied before writing the transformed value to the Modbus slave. It is possible for the value in the Modbus slave to be different from the value in the DataHub instance if a value beyond the clamped range is written to the Modbus slave by an external program. In that case, the DataHub point will report the clamp value, even though the value in the Modbus slave is out of range.

Convert to lets you convert an input value from the Modbus slave into a signed or unsigned integer, float, or double for the DataHub point value.


	When applying a transformation to a value, the result is frequently a non-integer. Thus, it is a good idea to convert the value to a floating point (float or double) number when using a transform.


	You can use this option to determine the data point type of a packed digital value (see above). You may specify any signed or unsigned integer type, though you should specify a type that is large enough to hold the selected number of bits.

Prev	Up	Next
3.13. MQTT Broker	Home	3.15. Event Streams