(Optional) Creating a Modbus Device Interface (XIF) Definition

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

This page includes the following sections:

Creating a Modbus XIF File

For a Modbus XIF definition, 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 NameOptionalSpecified the Block 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

Specified 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.
ModiconOptional

Specifies whether the Modbus register address (see Address parameter below) is a Modicon address.

Valid values are blank, Y for yes, and N for no.

This parameter is available with SmartServer 4.2 and higher.
Address

Required

Specifies the Modbus register address in the device. Addresses are specified using Modicon addressing with 5 or 6 digits, where:

  • The first digit represents the memory block as follows:
    • 0 for coils
    • 1 for discrete inputs
    • 3 for input registers
    • 4 for holding registers
  • The remaining digits represent the register address offset by 1.

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.

With SmartServer 3.5 and higher, you can specify Modbus addressing using the Modicon addressing approach. When using Modicon addressing, the SmartServer will automatically remove the memory block in the address and subtract the appropriate offset. For example, you can enter the Modicon register address as 40001 and the SmartServer will read/write to register 0 as expected. 

When using Modicon addressing, it is not a requirement that you specify a value in the Function Code parameter; you can leave this parameter empty. The SmartServer will automatically determine the correct Function Code. See the section on the Function Code parameter for more information.

For SmartServer 3.4 and prior, always specify Modbus 0-based addressing without using a memory block number.

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:

  • BIT
  • CHAR8 for UTF-8 characters, where each UTF-8 character is stored in an independent Modbus register. Available with SmartServer 3.4 and higher.
  • CHAR8_2 for UTF-8 characters, however, two characters are stored sequentially in each 16-bit Modbus register. Available with SmartServer 3.4 and higher.
  • CHAR16 for UTF-16 characters stored in independent Modbus registers. Available with SmartServer 3.4 and higher.
  • FLOAT for 32-bit floats; same as FLOAT32
  • FLOAT32 for 32-bit floats; same as FLOAT. Available with SmartServer 4.4 Update 1 and higher.
  • FLOAT64 for 64-bit floats. Available with SmartServer 4.4 Update 1 and higher.
  • MOD10
  • MOD10_2
  • MOD10_3
  • MOD10_4
  • SINT16
  • SINT32
  • SINT64
  • UINT8
  • UINT16
  • UINT32

If you specify the CHAR8CHAR8_2, or CHAR16 type, then you must also define the ASCII Length parameter (see below) in the Modbus XIF file specifying the string length.

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

Native type values are case-sensitive and must use upper-case letters.

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

Specifies the data encoding for a datapoint, the datapoint value appearance in IAP/MQ, and identifies the datapoint type to be reported in IAP/MQ when a datapoint update is published to IAP/MQ. 

An IAP type may also specify the semantic meaning of a datapoint. Each driver may support a different subset of IAP types for the native types.

The following IAP types are defined:

  • Base types – bit (e.g., Modbus coil outputs and discrete inputs), boolean, multistate, sint8uint8, uint16, sint16, uint32, sint32, uint64, sint64, floatfloat32, float64, mod10_32, mod10_48, mod10_64.

    Base type values are case-sensitive and must use lower-case letters.

  • Standard types – the types listed in the SNVT, SCPT, and ENUM sections of Online Resource Files - LonMark. As of SmartServer 3.2, the IAP standard resource file set is based on the version 16.00 LonMark standard resource file set and the version 2.01 IoT resource file set. These types are made available to IAP applications by the Resource Publisher. 

    You can specify an IAP type that provides some context for the data point. You can also specify some common, generic IAP types for certain Native Types. For example:

    Native Type

    IAP Type

    UINT8

    SNVT_count

    UINT16

    SNVT_count

    SINT16

    SNVT_count_inc

    UINT32

    SNVT_count_32

    FLOAT

    SNVT_count_inc_f

    FLOAT

    SNVT_count_f (positive values only)


  • Custom types – types defined by a custom IAP resource file set.  Custom types are defined by an XML format export from the IzoT Resource Editor. Custom IAP resource file sets include a program ID and a scope identifier that specifies a mask for the program ID.  The scope ID may be 3, 4, 5, or 6 corresponding to program ID masks of 0xFFFFFF0000000000 for 3, 0xFFFFFFFFFF000000 for 4, 0xFFFFFFFFFFFFFF00 for 5, and 0xFFFFFFFFFFFFFFFF for 6.  Custom types are specified as <program ID>-<scope>/<type name> where the <program ID>-<scope> specification is the set identifier.  

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.
IAP FieldOptional

Specifies the name of a field within the IAP type. The field is specified as a path in a nested structure. For example: the CIE luminance field in a SNVT_color_2 datapoint is named color_value/CIE1931_lumen/y. If this field is not specified, then the entire type is used.  

Prior to SmartServer 3.2, this parameter was called SNVT FIELD with a required field name or a value of "VALUE" in the BACNET TYPE MAP file. Specifying "VALUE" for the entire field is not required starting with SmartServer 3.2.
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

By default, the SmartServer uses the FC06 (single-write) command when writing to datapoints that do not span more than one Modbus register.

For SmartServer release 4.0 and higher, you can specify ++ in the Write Enable field to instruct the SmartServer to only use the FC16 (multi-write) command, even when writing to a datapoint that does not span more than one Modbus register. This designation supports Modbus devices that do not implement the FC06 (single-write) command.

For SmartServer releases prior to 4.0, Modbus devices that implement datapoints contained within a single register must support the FC06 single-write command.

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.

With SmartServer 3.5 and higher, you can leave the Function Code parameter blank if you use Modicon addressing. In these cases, the SmartServer will automatically determine the correct Function Code based on the Modicon address.

If you are using Modicon addressing and do specify the Function Code, then the Function Code must be appropriate based on the Modicon address register type. If it is not, then the SmartServer will throw an error.

For example, if you are indicating a holding register based on using address 40001 and choose to specify the Function Code, then it must specify FC03.

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.

Example: a native value can be scaled to an IAP value with the following:

Scaled Value = ((Native Value - Native Value 1) * ((Scaled Value 2- Scaled Value 1) / (Native Value 2- Native Value 1))) + Scaled Value 1

Example: an IAP value can be scaled to a native value with the following:

Native Value = ((Scaled Value - Scaled Value 1) *  ((Native Value 2 - Native Value 1) / (Scaled Value 2 - Scaled Value 1))) + Native Value 1

* If a Native Value 1 value is specified, then 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 are 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.

ASCII LengthRequired when defining a Native Type of CHAR8, CHAR8_2, or CHAR16, otherwise this parameter is optional.

Specifies the length of the string for the register definition.

For example, to specify a holding register that contains a 4-byte long string contained within two sequential Modbus registers, use the Native Type CHAR8_2 and set ASCII Length to 4.

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 

Below 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

Below 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

Below 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.