Page tree
Skip to end of metadata
Go to start of metadata

You can create and modify device interface (XIF) definitions for Modbus TCP and Modbus RTU devices.  A Modbus XIF definition specifies the name, program ID, manufacturer, and Modbus registers in a device.

This topic includes the following sections:

Creating a Modbus XIF File

To create a Modbus XIF definition, you create a CSV file with a .mod extension that defines the device interface for a Modbus device interface (XIF).  The name of the Modbus XIF file, without the .mod extension, is the name of the Modbus XIF. The extension must be .MOD or .mod.  You cannot use a compound extension name such as .mod.csv.  To create the file, you will need the manufacturer's documentation for the Modbus device register addresses and contents implemented by the device

A Modbus XIF file has the following three sections.

  • A file type specification that identifies the file as a Modbus XIF file.
  • A product details section that specifies the program ID, version, product name, manufacturer, and description for the Modbus device.
  • A datapoint list that specifies the datapoints on the device to be available to the SmartServer. The first line of the datapoint list is a header with column headings for a datapoint list. 

The following figure illustrates the top portion of a Modus XIF file.

#filetype,Modbus_xif
#program_ID,9F0096052804DB01
#version,v2.10.020
#product_name,Adam 4150
#manufacturer,Advantech
#description,Adam 4150 DIO module
Block Name,Block Index,Datapoint Name,Address,Native Type,IAP Type,Write Enable,Function Code,Marker Value

File Type Specification

The file type specification for a Modbus XIF file is the following:

#filetype,Modbus_xif

If you open a CSV file with this line in Excel, it is displayed as two cells, one with #filetype and one with Modbus_xif.

Product Details

The product details identify the product specified by the Modbus XIF file.  The product details specification has the following contents:

#program_ID,<Program ID>
#version,<Version>
#product_name,<Product Name>
#manufacturer,<Manufacturer>
#description,<Description>

If you open a CSV file with these lines in Excel, each line is displayed as two cells.

Specify the details as follows:

  • <Program ID> – (required) a 64-bit hexadecimal number used for identifying resource definitions. An example Modbus RTU program ID is 9F0096052804DB0. The program ID can optionally have colon and hyphen separators.  See Device Type Definition for instructions on how to create a Modbus XIF program ID.

  • <Version> – (optional) version of the device.
  • <Product Name> – (optional) manufacturer's name for the device.
  • <Manufacturer> – (optional) manufacturer of the device.
  • <Description> – (optional) comment description of the device.

Following is an example product details specification for an Advantech ADAM 4150 DIO module:

#program_ID,9F0096052804DB01
#version,v2.21.019
#product_name,Adam 4150
#manufacturer,Advantech
#description,Adam 4150 DIO module

Datapoint List

The datapoint list that specifies the datapoints on the device to be available to the SmartServer. The first line of the datapoint list is a header with column headings for a datapoint list.  Following is an example datapoint list with a single datapoint defined:

Block Name,Block Index,Datapoint Name,Address,Native Type,IAP Type,Write Enable,Function Code,Marker Value
DI,0,DI_0,0,BIT,SNVT_count,-,FC01,

The following table describes the column contents for the datapoint list (for SmartServer releases prior to SmartServer 3.2.  You can arrange the columns in any order, the SmartServer uses the name in the heading row entry to identify the contents of the column.  See (Optional) Creating a Modbus Device Interface (XIF) Definition (Release 3.1) in the Documents Archive area)

Parameter

Required/
Optional

Description

Block NameOptionalBlock XIF name for the datapoint. 
Block IndexOptional

Specifies a numeric block index.  The block index can be any positive (>=0) integer value and is not required to be sequential.  If not specified, the block index will be zero.

For example: for a device with 8 digital outputs, you can define 8 blocks, each named DO, using indexes 0 through 7 (the index names are not required to be sequential, but they are in this example). 

this parameter is available with smartserver 2.8 and higher .

Datapoint Name

Required

The datapoint XIF name.  This is a descriptive name to identify the datapoint.  The name must be unique for all the datapoints in a block containing (see Block Name). 

Prior to SmartServer 3.2, this parameter was called POINT NAME.
Address

Required

The Modbus register address in the device. Specify Modbus 0-based addressing without a memory block number. Some devices specify their addresses using Modicon addressing with 5 or 6 digits, where the first digit of Modicon addressing represents the memory block, and the remaining digits representing the register address offset by 1. The memory blocks are 0 for coils, 1 for discrete inputs, 3 for input registers, and 4 for holding registers. Do not include the memory block in the address specification, and subtract the offset. For example: if the Modicon register address is 400001, do not include the 4, and subtract 1 from the address of 1. The resulting address is 0.

Native Type

Required

Specifies how the data is encoded in the Modbus registers.  Select a value based on the Modbus register type and encoding as follows:

  • For Modbus coil outputs and discrete inputs, specify BIT
  • For Modbus input registers and holding output registers, select UINT8, UINT16, SINT16, UINT32, SINT32, FLOAT, MOD10_2, MOD10_3, or MOD10_4

If a native type value is not defined, the default native type is UINT16.

Prior to SmartServer 3.2, this parameter was called datatype.
Word OrderOptional

Specifies the 16-bit word ordering within multi-word native values.  Values can be blankbig, or littlebig or blank specify big-endian word ordering.  little specifies little-endian, 16-bit word ordering. 

Byte OrderOptional

Specifies the 8-bit byte ordering within multi-byte native values. Values can be blank, big, or little. big or blank specifies big-endian ordering. little specifies little-endian ordering. Byte ordering specification controls the ordering of bytes within the entire value if the Word Order value is blank, and controls byte ordering within each 16-bit word if the Word Order value is specified as big or little.  

Bit OrderOptional

Specifies the bit ordering within each native value byte.  Values can be blankbig, or littlebig specifies big-endian bit ordering. little or blank specifies little-endian. 

IAP TypeRequired

IAP type that identifies how the data appears in IAP. 

Prior to SmartServer 3.2, this parameter was called presentation type for some of the drivers. for backward compatibility, presentation type is supported. If both presentation type and IAP type are specified, the iap type is used and warning will be generated indicating that the presentation type was ignored due to a specified iap type.
Write EnableRequired

Specifies if a datapoint is read-only (-) or read-write (+).  Modbus datapoints with FC02 and FC04 function codes  are required read-only registers and must specify - in this column. Modbus datapoints with FC01 and FC03 function codes may specify - to disable writing and + to enable writing

Prior to SmartServer 3.2, this parameter was called direction with values of R and RW for MODBUS XIF files.
PrecisionOptionalSpecifies the number of digits of precision. The precision must be a positive or negative integer, or zero. If the precision is positive, the value is rounded to the specified number of decimal places after the decimal point. If the precision is zero, the value is rounded to the nearest integer. If the precision is negative, the number is rounded to the left of the decimal point. 
DescriptionOptionalProvides a human-readable freeform description of the datapoint or datapoint field.
Function CodeRequired

Specifies the read function code of the datapoint. 

Enter one of the following values:

Do not specify the FC05, FC06, FC15, and FC16 write function codes. The SmartServer automatically determines the write function code based on the read function code.

Marker ValueRequired for Modbus device discovery, otherwise this parameter is optional

Supports Modbus device discovery.

The Modbus protocol does not support automatic discovery of devices. The SmartServer discovers Modbus devices by probing each Modbus address for marker values that you specify. A marker is a fixed datapoint value that the SmartServer identify the device type for a device. 

For example, if a device type includes a datapoint with a model name or model number, the datapoint can be used as a marker for the device type. If a Modbus device manufacturer sells a line of devices, Model number 23854, and embeds that number in a datapoint at the same register address in each device, but then also has a datapoint with the number of phases supported by the particular meter, the marker for each meter type can consist of two datapoints, one with the model name and one with the number of phases. Both values must match the marker values in the device interface definition. 

This parameter was added in SmartServer 2.8.
Native Value 1Optional

Specifies the first of two native values for the datapoint. To specify scaling for a datapoint, specify two scaled values for the datapoint. The SmartServer uses the two sets of values to determine the scaling factors for converting a native value to an IAP value, as well as to convert an IAP value to a native value. 

If a Native Value 1 value is specified, the Native Value 2, Scaled Value 1, and Scaled Value 2 values are required.

Prior to SmartServer 3.2, Modbus scaling was done with A', B', and C' or Multiplier and Offset columns. These parameters arel still supported for backward compatibility. 
Native Value 2Optional

Specifies the second of two native values for the datapoint.  If a Native Value 2 value is specified, the Native Value 2, Scaled Value 1, and Scaled Value 2 values are required.  See the Native Value 1 parameter for usage and value requirements. Specifies the second of two native values for the datapoint.  

Scaled Value 1Optional

Specifies the first of two scaled values for the datapoint.  If a Scaled Value 1 value is specified, the Native Value 1, Native Value 2, and Scaled Value 2 values are required.  See the Native Value 1  parameter for usage, value requirements, and backward compatibility requirements. 

Scaled Value 2Optional

Specifies the second of two scaled values for the datapoint.  If a Scaled Value 2 value is specified, the Native Value 1, Native Value 2, and Scaled Value 1 values are required.  See the Native Value 1 parameter for usage, value requirements, and backward compatibility requirements. 

Range MinOptional

Specifies the minimum scaled value for the datapoint. If specified, the minimum range has the same behavior as the minimum value defined in the IAP type definition, and the specified minimum overrides the minimum defined in the IAP type definition. If a minimum value is not defined in the IAP type, the default minimum is undefined, disabling any minimum value range checking. The minimum value is specified as an IAP type, with any type mapping completed including value scaling. A minimum value can only be specified if the the IAP value is a scalar type. 

Range MaxOptional

Specifies the maximum scaled value for the datapoint. If specified, the maximum range has the same behavior as the maximum value defined in the IAP type definition, and the specified maximum overrides the maximum defined in the IAP type definition. If a maximum value is not defined in the IAP type, the default maximum is undefined, disabling any maximum value range checking. The maximum value is specified as an IAP type, with any type mapping completed including value scaling.  A maximum value can only be specified if the the IAP value is a scalar type.

IAP Type Mapping

IDL-based drivers map native datapoints to and from IAP datapoints and datapoint fields. Type mapping is bidirectional so that the driver or server will map received native values to IAP values, and received IAP value will be mapped to native values. 

The IAP type mapping is performed as described in the following table.

Native TypeIAP TypeNative → IAP MappingIAP → Native Mapping
Any scalar typeAny scalar typeScaled native value

Scaled IAP value

Any scalar typeEnumerationAny native scalar type is mapped to an IAP enumeration type by setting the enumeration value to the scalar value, and the IAP value to the corresponding member name for the enumeration value.The reverse of the native to IAP mapping.

Modifying a Modbus XIF File

You can modify a Modbus XIF definition prior to or after you have used the XIF definition to create, provision, and configure any Modbus devices using the XIF defnition.  For example, after provisioning a Modbus device and specifying the monitoring, logging, alarming, mapping, connections, and sequencing for it, you may find an error in one of the datapoint definitions for the device's XIF definition.  To modify a Modbus XIF definition, modify your Modbus XIF file and re-import it with the modified content.  This capability was added with SmartServer 3.2.

Modbus XIF File Examples

Example 1 – Advantech ADAM 4150 DIO Module 

Following is an example Modbus XIF for an Advantech ADAM 4150 device.

#filetype,Modbus_xif
#program_ID,9F0096052804DB01
#manufacturer,Advantech
#description,Adam 4150 DIO module
Block Name,Block Index,Datapoint Name,Address,Native Type,IAP Type,Write Enable,Function Code,Marker Value
DI,0,DI_0,0,BIT,SNVT_count,-,FC01,
DI,0,DI_1,1,BIT,SNVT_count,-,FC01,
DI,0,DI_2,2,BIT,SNVT_count,-,FC01,
DI,0,DI_3,3,BIT,SNVT_count,-,FC01,
DI,0,DI_4,4,BIT,SNVT_count,-,FC01,
DI,0,DI_5,5,BIT,SNVT_count,-,FC01,
DI,0,DI_6,6,BIT,SNVT_count,-,FC01,
DO,0,DO_0,16,BIT,SNVT_count,+,FC01,
DO,0,DO_1,17,BIT,SNVT_count,+,FC01,
DO,0,DO_2,18,BIT,SNVT_count,+,FC01,
DO,0,DO_3,19,BIT,SNVT_count,+,FC01,
DO,0,DO_4,20,BIT,SNVT_count,+,FC01,
DO,0,DO_5,21,BIT,SNVT_count,+,FC01,
DO,0,DO_6,22,BIT,SNVT_count,+,FC01,
DO,0,DO_7,23,BIT,SNVT_count,+,FC01,
Sys,0,ModuleName-1,210,UINT16,SNVT_count,-,FC04,16720

Example 2 – EasyIO FC-20 BMS Controller

Following are examples of the manufacturer's documentation for the Modbus registers in an EasyIO FC-20. This example specifies two datapoints per memory block and three for the holding register.

Discrete Input

Coil Output

Input Register

Holding Register

  • Datapoint Name – Register Name

  • IAP Type – Select best the IAP type from IzoT Resource Editor standard list that represents the Modbus datatype.

  • Modbus Datatype – Type field in Input Register and Holding Register. Coil Output or Discrete Input is always BIT.

  • Function Code – Register is clearly labeled for each datapoint in the Easy IO registry map.


  • Address – Easy IO documentation specifies it is 1-base addressing, with 5 digits.

    If the first digit is:

0 – use FC01
1 – use FC02
3 – use FC04
4 – use FC03

For the next 4 digits, subtract 1 to get register address as shown in the following examples:

40001 in Easy IO – FC03 0000 in MOD file
30001 in Easy IO – FC04 0000 in MOD file

  • Write Enable – Depends on whether registry allows for read/write options, based on the function code for the datapoint, you can use the following direction:

    Valid values


    Read only (-)
    Read-write (+)

    Function CodeWrite Enable
    FC01+ or -
    FC02-
    FC03+ or -
    FC04-
  • Native Value 1/2Scaled Value 1/2 – Refer to the scaling example provided above, and to be used if the way the data is presented needs to be a different resolution.

  • Range Min/Max – (Optional) Enter a scaled value that is out-of-range for the datapoint. 

  • Description – Description field in Easy IO register map.

Example 3 – Schneider PM5563 Power Meter

Following is an example of the manufacturer's documentation for the Modbus registers in a Schneider PM5563.

  • Datapoint Name – Description field

  • IAP Type – Select best the IAP type from IzoT Resource Editor standard list that represents the Modbus datatype.

  • Modbus Datatype – Data-Type field; Input Register and Holding Register. Coil Output or Discrete Input is always BIT.

  • Function Code – Use the function code based on the memory block where the data is located.

  • Address – The PM55XX series register index is a spreadsheet with tabs for registers and coils.

    The datapoints in the Register List tab will have a function code of FC03 or FC04 depending on the memory block where the data is stored. The datapoints in the Coils tab will have a function code of FC01 or FC02 depending on the coil where the data is stored.

    Since the Register column values represent the raw address value, both raw address and raw address minus 1 were tried. It was determined that the raw value minus 1 returned the correct data.
    • Minute – 1841 – Subtract 1 from the address to convert it to 0-base addressing
    • VT_Primary – 2026 – Subtract 1 from the address to convert it to 0-base addressing

  • Write Enable – Access Field. Depending on whether the registry allows for read/write options, based on the function code for the datapoint, use the following direction:

    Valid values


    Read only (-)
    Read-write (+)

    Function CodeWrite Enable
    FC01+ or -
    FC02-
    FC03+ or -
    FC04-
  • Native Value 1/2Scaled Value 1/2 – Refer to the scaling example provided above, and to be used if the way the data is presented needs to be a different resolution.

  • Range Min/Max – (Optional) Enter a scaled value that is out-of-range for the datapoint. 

  • Description – Description field in register map.
  • No labels