(Optional) Creating a Modbus Device Interface (XIF) Definition
- Nina Cardillo
For SmartServer 3.1, see (Optional) Creating a Modbus Device Interface (XIF) Definition (Release 3.1).
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 |
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> |
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 |
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 |
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/ | Description |
|---|---|---|
| Block Name | Optional | Specified the Block XIF name for the datapoint. |
| Block Index | Optional | 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. |
| Modicon | Optional | 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:
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:
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 Order | Optional | Specifies the 16-bit word ordering within multi-word native values. Values can be blank, big, or little. big or blank specify big-endian word ordering. little specifies little-endian, 16-bit word ordering. |
| Byte Order | Optional | 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 Order | Optional | Specifies the bit ordering within each native value byte. Values can be blank, big, or little. big specifies big-endian bit ordering. little or blank specifies little-endian. |
| IAP Type | Required | 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:
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 Field | Optional | 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 Enable | Required | 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. |
| Precision | Optional | Specifies 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. |
| Description | Optional | Provides a human-readable freeform description of the datapoint or datapoint field. |
| Function Code | Required | 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 Value | Required 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 1 | Optional | 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 2 | Optional | 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 1 | Optional | 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 2 | Optional | 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 Min | Optional | 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 Max | Optional | 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 Length | Required 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 Type | IAP Type | Native → IAP Mapping | IAP → Native Mapping |
|---|---|---|---|
| Any scalar type | Any scalar type | Scaled native value | Scaled IAP value |
| Any scalar type | Enumeration | Any 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 |
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 Code Write Enable FC01 + or - FC02 - FC03 + or - FC04 - - Native Value 1/2, Scaled 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 Code Write Enable FC01 + or - FC02 - FC03 + or - FC04 - - Native Value 1/2, Scaled 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.