Preconditions

• SGC500 software version: 3.03.00 or higher
• Connect Modbus TCP device to LAN network. Make sure port 502 is accessible.
• The field device health data must be integrated in Netilion.

Configuration for Analytics service

Modbus TCP protocol does not provide field device information by default. An asset can not be created fully automatically. Device information must be added manually as described here:

• On page Edge Device Details create a new Field Gateway / Device.
• Select type "Modbus TCP Device".
• Add a name (displayed on field gateway / device pages only).
• Add IP address of the Modbus TCP device.
• Add serial number of the Modbus TCP device.
• Add tag of the Modbus TCP device.
• Press button Save.

Within next 20 minutes the edge device will read the new field gateway / device configuration.

An asset will be created based on configured serial number. Manufacturer and product code are set to unknown.

A tag will be created based on configured tag information and linked to asset.

To get more asset insights finish asset commissioning:

• Open the asset page and select edit.
• Select e.g. Endress+Hauser as manufacturer.
• Select product code of field device.
• Press button Save.

Assign connected sub devices

It is possible to create assets for the connected sub devices in case the Modbus device is a gateway. For this enter the serial numbers of the assets in the channel number items. For the sub devices an asset will be created.

For example, use a Modbus TCP/RTU adapter to connect Modbus RTU devices to SGC500. Add an TCP/RTU adapter as Field Gateway and add the connected RTU devices with serial number and sub address in Modbus configuration.

Configuration for Value and Health service

With Modbus devices, measured values are stored in specific registers. The following Modbus information from the field device must be available for configuration and varies for each device type:

• Modbus command
• register number
• data type
• byte order
• Netilion unit code (Value service only)
• Unit Identifier / Sub address (0 if not defined)

Modbus configurations are imported as a file on field gateway / device page created above. The format is json and requires the file extension mbconf.

{
  "config_version": 1,
  "config_type": "specifications",
  "configuration": {
    <see chapter value service related below>,
    <see chapter health service related below>
    }
  },
  "byte_order": 0, 
  "unit_identifier": 0
}

file name e.g.: example.mbconf

byte order	8 / 16 bit types	32 Bit types	64 bit types
0	1-0	1-0-3-2	1-0-3-2-5-4-7-6
1	0-1	0-1-2-3	0-1-2-3-4-5-6-7
2	0-1	2-3-0-1	6-7-4-5-2-3-0-1
3	1-0	3-2-1-0	7-6-5-4-3-2-1-0

 

unit_identifier (optional) [global unit identifier, 0 if not defined]

0 to 255

Within next 20 minutes the edge device will read the Modbus configuration and collect data. With configuration changes we have the same behavior.

An asset will be created based on configured serial number. Manufacturer and product code are set to unknown.

With configuration changes we have the same behavior.

 

Value service related

The following example shows the configuration of a measured value, mapped to the field gateway asset:

• Modbus command: Input (3)
• register number: 210
• data type: Float (10)
• Netilion unit code: degree Celsius
• byte order: 1-0-3-2 (0)

{
  "config_version": 1,
  "config_type": "specifications",
  "configuration": {
    "config.modbus_3_210": {
    "value": "0;Temperature;degree_celsius;1;10"
    }
  },
  "byte_order": 0
}

 

The following example shows the configuration of two RTU devices behind a TCP/RTU Gateway. Values read from different sub addresses and added to different assets.

• Modbus command: Input (3)
• register number: 210
• data type: Float (10)
• Netilion unit code: degree Celsius
  
• byte order: 1-0-3-2 (0)
  
• sub address 73 and 74
  
• unit identifier 75
  

{
  "config_version": 1,
  "config_type": "specifications",
  "configuration": {
    "config.modbus_3_210_73": {
    "value": "123456789;Temperature;degree_celsius;1;10"
    }
  },

    "config.modbus_3_210_74": {
    "value": "987654321;Temperature;degree_celsius;1;10"
    }
  },
  "byte_order": 0, 
  "unit_identifier": 75
} 

The following example shows the configuration of an IO Link device FTI26 behind a Turck IO Link Master. Values read from Modbus register of the IO Link Master.

• Modbus command: Input (3)
• register number: 2
• data type: Unit with 14 bits (bits 0 to 13)
• Netilion unit code: percentage
• byte order: 1-0-3-2 (0)

 

• Modbus command: Input (3)
• register number: 2
• data type: bit (bit 14)
• Netilion unit code: -
• byte order: 1-0-3-2 (0)

{
  "config_version": 1,
  "config_type": "specifications",
  "configuration": {
    "config.modbus_3_2.0-13": {
    "value": "FTI26_serial;Coverage;percent;1;5"
    },
    "config.modbus_3_2.14": {
    "value": "FTI26_serial;OU1;other;1;1"
    }
  },
  "configuration_status": {
  },
  "byte_order": "0",
  "unit_identifier": "0"
}

The configuration key is defined as: config.modbus_<modbus command number>_<register number[.<bit offset> | .<start bit>-<end bit>]>[_<sub address>]

from our example: config.modbus_3_210_73

Modbus command number
3	Read Holding Register
4	Read Input Register

 

Register number
0 to 65535	.<bit offset> (optional) for single bits (only for data type Boolean) 0 to 15 Example < register number >.5
	.<start bit>-<end bit> (optional) for bit ranges Start bit End bit Related data type  0 to 14  1 to 15   signed / unsigned 16  0 to 30  1 to 31  signed / unsigned 32  0 to 62  1 to 63  signed / unsigned 64 Example < register number >.3-8 Start bit must be less the end bit

 

sub address (optional) [if not defined, the global unit identifier is used]

0 to 255

The configuration value is defined as:

<channel number>;<value name>;<netilion unit code>;<endpoint>;<datatype>

from our example: 0;Temperature;degree_celsius;1;10

Item	Value		Description
<channel number>	0 or [a-z][A-Z][0-9]		0 : assign the read value to the Modbus device itself [a-z][A-Z][0-9] : Serial number of the sub device. (Create asset and assign the value to it)
<value name>	[a-z][A-Z][0-9][_.-]		displayed value name in Netilion
<Netilion unit code>	[a-z][0-9][_]		Code defined on Netilion API endpoint Unit, see appendix Netilion_API_Units.csv
<endpoint>	1		used for Netilion Value
<datatype>	1	Boolean
	2	Signed 8
	3	Unsigned 8
	4	Signed 16
	5	Unsigned 16 or bit range 16
	6	Signed 32
	7	Unsigned 32 or bit range 32
	8	Signed 64
	9	Unsigned 64 or bit range 64
	10	Float (32 bit Float)
	11	Double (64 bit Float)
	13	DateTime*

*The DateTime format is based on Liquiline platform. In case the device uses another formatting for date and time SGC500 does not support this.

Note: In case the value does not start on the first bit of the register, it is possible to set a bit offset in the register. E. g. register 2 has an uint12 starting on bit 5 to bit 16: 2.4-15

Health service related

To use Netilion Health service the field device must provide diagnostic code information in a Modbus register. Related health information must be available for device type in Netilion.

The following example shows a configuration:

• Modbus command: Holding
• register number: 501
• data type: Unsigned 16
• byte order: 3-2-1-0
• sub address 75

{
  "config_version": 1,
  "config_type": "specifications",
  "configuration": {
    "config.modbus_4_501": {
    "value": "0;;;2;5"
    }
  },
  "byte_order": 3, 
  "unit_identifier": 75
}

 

The configuration key is defined as: 

config.modbus_<modbus command number>_<register number>[_<sub address>]

from example: config.modbus_4_501_75

Modbus command number
3	Read Holding Register
4	Read Input Register

 

Register number

0 to 65535

 

sub address  (optional) [if not defined, the global unit identifier is used]

0 to 255

 

The configuration value id defined as:

<channel number>;<value name>;<netilion unit code>;<endpoint>;<datatype>

from example: 0;;;2;5

Item	Value		Description
<channel number>	0 or [a-z][A-Z][0-9]		0 : assign the read value to the Modbus device itself [a-z][A-Z][0-9] : Serial number of the sub device max 255 characters. (Create asset and assign the value to it)
<value name>	<empty>		displayed value name in Netilion
<Netilion unit code>	<empty>		Code defined on Netilion API endpoint Unit, see appendix Netilion_API_Units.csv
<endpoint>	2		used for Netilion Health
<datatype>	2	Signed 8
	3	Unsigned 8
	4	Signed 16
	5	Unsigned 16
	6	Signed 32
	7	Unsigned 32
	8	Signed 64
	9	Unsigned 64
	10	Float (32 bit Float)
	11	Double (64 bit Float)

Note: Just one health register configuration is allowed.

 

Status information

Each Modbus configuration will be checked from the edge and a status provided. The status information is stored in the same file in which the configurations are made. They are available via export functionality on field gateway / device page.

The list below shows possible status information:

status	description
OK	Configuration is OK and value can be read from edge device.
UNDEFINED	The related configuration is new or has changed and the edge did not process the configuration yet.
error.invalid_serial_number_or_channel	Channel number is out of range or serial number contains invalid characters/size. Process value and health information cannot be assigned to an asset.
error.invalid_pv_name_specified	Process variable name contains invalid characters. Process value cannot be written to Netilion.
error.invalid_pv_name_size	PV name to long.
error.pv_name_not_unique_in_channel_scope	Process Variable name is not unique in the channel scope. In Netillion the process variable contains data from all inputs with same name.
error.invalid_modbus_command_number	Not a valid Modbus command number used.
error.invalid_modbus_register_number	Modbus register number is not in the allowed range and cannot be processed.
error.invalid_modbus_sub_address	Configured Modbus address is not in the range 0-255 or not a number.
error.invalid_netilion_unit_code	Not a valid Netilion unit code is used.
error.invalid_netilion_unit_code_size	Unit code to long.
error.invalid_endpoint	Not a valid endpoint is used.
error.invalid_datatype	Not a valid datatype is used.
error.invalid_modbus_config	Unknown configuration key prefix used.
error.invalid_modbus_config_key_size	Modbus key size has not the correct number of items.
error.invalid_modbus_config_value_size	Modbus value size has not the correct number of items.
error.config_not_supported	Configuration not valid for generic Modbus device.
error.generic_config_not_supported	Unknown generic Modbus parameter.
error.generic_config_serial_number_issue	Invalid serial number size.
error.generic_config_tag_issue	Invalid tag size.
error.generic_config_byte_order_issue	Invalid byte order configured.
error.generic_config_endpoint_not_unique	Endpoint is configured more than once.
generic_config_unit_identifier_issue	Defined value is out of rang (0-255) or not a number.
error.invalid_bit_confguration	Bit configuration invalid characters. Check limitations.
error.bit_confguration_not_supported	Bit configuration supports 16 bit data types only.
error.invalid_bit_position_confgured	Bit position must be less 16.
error.invalid_bitfield_confguration	Bit range out of range. Check limitations.
error.bitfield_confguration_not_supported	Not supported data type selected.

Note: The listed checks are only related to configurations issues. Problems that may occur during the register query are not listed. The status would still be OK.

Example export from a configuration which includes two configurations for Health service:

{
  "config_version": 1,
  "config_type": "specifications",
  "configuration": {
    "config.modbus_4_501_73": {
      "value": "123456789;;;2;5"
    },
    "config.modbus_4_601_74": {
      "value": "987654321;;;2;5"
    }
  },
  "configuration_status": {
    "config.status.byte_order": {
      "value": "OK"
    },
    "config.status.serial_number": {
      "value": "OK"
    },
    "config.status.tag": {
      "value": "OK"
      },
    "config.status.modbus_4_501": {
      "value": "error.generic_config_endpoint_not_unique"
    },
    "config.status.modbus_4_601": {
      "value": "error.generic_config_endpoint_not_unique"
    }
  },
  "byte_order": "3"
}

To see the correct unit symbols open excel and import the csv file.