(Optional) Creating a BACnet Device Interface (XIF) Definition
- Nina Cardillo
For SmartServer 3.1, see (Optional) Creating a BACnet Device Interface (XIF) Definition (Release 3.1).
You can download, discover, create, and modify a device interface (XIF) definition for a BACnet IP, BACnet MS/TP, or BACnet FT device. A BACnet XIF definition specifies the name, program ID, manufacturer, and BACnet objects in a device.
This page includes the following sections:
Downloading a BACnet XIF Definition
You can download BACnet device type package (.dtp) files from the SmartServer GitHub Repository. The device type package files are ZIP archives that can contain multiple definition files, include XIF files. You can optionally modify the EnOcean XIF files to hide selected datapoints. Import the downloaded files into the SmartServer as described in Importing a BACnet XIF File on this page.
Discovering a BACnet XIF Definition
The SmartServer automatically creates a BACnet XIF definition when it discovers a BACnet device without a matching XIF definition. When the SmartServer discovers a BACnet device, it searches for a matching BACnet XIF definition based on the manufacturer ID, product name, and datapoints. If the SmartServer discovers a matching XIF definition, it uses the matching XIF definition independent of the datapoints that are actually used in the device.
When the SmartServer creates and exports a BACnet XIF definition, it names the exported XIF file with the following format: <Vendor ID>_<Product Name><Datapoints Hash>.bac. For example, if the SmartServer discovers a Viconics (BACnet vendor ID 140) VT7200-V20 device with a discovered product name of VT7200C5x00B and does not have a matching XIF file, it creates and exports a BACnet XIF file with the following name: 140_VT7200C5x00B3493413e084.bac, where 3493413e084 is the datapoints hash.
The SmartServer calculates the datapoints hash based on the datapoints reported by the device. If the SmartServer discovers multiple BACnet devices with the same vendor ID, product name, and datapoints, it will use the same XIF definition for all the devices. In some cases, multiple BACnet devices with the same vendor ID and product name will have a unique datapoint for each device. In that case, each device will have a unique datapoints hash and as a result will have a unique discovered BACnet XIF definition.
Modifying a Discovered BACnet XIF Definition
You can modify a BACnet XIF definition that was created by a SmartServer. Use a lab SmartServer to discover the BACnet XIF definition to prevent conflicts between the discovered XIF definition and your modified XIF file. To modify a discovered XIF definition, following these steps:
- Discover the device using a lab SmartServer that does not already have a BACnet XIF definition for the device. The SmartServer creates a new XIF definition for the device.
- Export the discovered XIF file.
- To reuse your modified XIF file with all devices from the same vendor and with the same product name, remove the datapoints hash from the XIF filename. For example, if the SmartServer discovers a Viconics (BACnet vendor ID 140) VT7200-V20 device with a discovered product name of VT7200C5x00B, it assigns 140_VT7200C5x00B3493413e084.bac as the XIF definition name. To resuse the discovered XIF definition with all VT7200C5x00B devices, rename the XIF file to 140_VT7200C5x00B.bac.
- Optionally remove any datapoints from the file that you do not require.
- Import the modified XIF file into the SmartServer as described in Importing a BACnet XIF File on this page.
Creating a BACnet XIF File
To create a BACnet XIF definition, follow these steps:
- Create a CSV file with a .bac extension. Name the file using the following format: <Vendor ID>_<Product Name>.bac. For example, 140_VT7200C5x00B.bac is the BACnet XIF file name for a Viconics (BACnet vendor ID 140) VT7200-V20 device with a discovered product name of VT7200C5x00B.
- Create the contents of the file you created in step 1 as described in this section. To create the contents, you can use the manufacturer's BACnet Protocol Implementation Conformance Statement (PICS) for the device, or you can use the BACnet object type and object instance numbers reported by a BACnet workstation. You can download a free BACnet workstation for this purpose.
- Import the XIF file into the SmartServer as described in Importing a BACnet XIF File on this page.
A BACnet XIF file has the following three sections.
- A file type specification that identifies the file as a BACnet XIF file.
- A product details section that specifies the program ID, version, product name, manufacturer, and description for the BACnet 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 example shows the top portion of a BACnet XIF file.
#filetype,BACnet_xif |
File Type Specification
The file type specification for a BACnet XIF file is the following:
#filetype,BACnet_xif |
If you open a CSV file with this line in Excel, it is displayed as two cells, one with #filetype and one with BACnet_xif.
Product Details
The product details identify the product specified by the BACnet 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 BACnet/IP program ID is 9B008C011E00FC04. The program ID can optionally have colon and hyphen separators. See Device Type Definition for instructions on how to create a BACnet 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) description of the device.
The following is an example product details specification for a Viconics VT7200F5031B Thermostat.
#program_ID,9B008C011E00FC04 |
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 on the second line:
Block Name,Block Index,Datapoint Name,Address,Write Enable,IAP Type,Priority Array |
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 BACnet Device Interface (XIF) Definition (Release 3.1) in the Documents Archive area):
Parameter | Required/ | Description |
|---|---|---|
| Block Name | Optional | 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 is 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). |
Datapoint Name | Optional | 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 this datapoint (see Block Name). Prior to SmartServer 3.2, this parameter was called POINT NAME. |
| Address | Required | The BACnet address, specified as <BACnet object type>:<BACnet object instance number>. The supported BACnet object types are AI, AO, AV, BI, BO, BV, LAV, IV, MSI, MSO, MSV, and PIV. BACnet outputs (AO, BO, MSO) are the equivalents of LON and Modbus inputs. BACnet inputs (AI, BI, MSI) are the equivalent of LON and Modbus outputs. The BACnet object instance number is the object instance number defined by the BACnet protocol. Do not include leading zeros. For example: you can specify AI:941001 for the BASremote Reset Status datapoint, but you cannot specify AI:00941001. Prior to SmartServer 3.2, this parameter was defined by two separate parameters called bacnet_type and instance. See (OPTIONAL) CREATING A BACNET DEVICE INTERFACE (XIF) DEFINITION (RELEASE 3.1) in DOCUMENTS ARCHIVE for details. |
| IAP Type | Required | IAP type that identifies how the data appears in IAP/MQ and identifies the datapoint type to be reported in IAP/MQ. An IAP type 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 | 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 (+). BACnet AO and BO objects must specify +. BACnet AI and BI objects must specify -. |
| 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. |
| BACnet Priority Support | Required for datapoints that do not implement a priority array, otherwise this parameter is optional | Specifies whether the BACnet device application implements a priority array for the specified datapoint. true means this datapoint supports a priority array. false means this datapoint does not support a priority array. If a BACnet device does not support priority arrays, add the BACnet Priority Support column and set it to false for all the datapoints on the device. If not specified, the BACnet Priority Support parameter setting defaults to true. Prior to SmartServer 3.2, this parameter was called priority Array. This parameter was added in SmartServer 3.0. |
| Writable Normal Value | Optional | Specifies whether the device supports external writes to the normal value in the device. When the Writable Normal Value parameter is not specified, the default is false. |
| 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, the Native Value 2, Scaled Value 1, and Scaled Value 2 values are required. For Celsius to Fahrenheit conversion: 0 deg C = 32 deg F, and 100 deg C = 212 deg F |
| 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. |
| 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. |
IAP Type Mapping
The BACnet driver maps BACnet datapoints to and from IAP datapoints. Type mapping is bidirectional so that the BACnet driver 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 |
| Multistate | Enumeration | Native BACnet-compatible multistate values are mapped to IAP enumerations based on the multistate value corresponding to the multistate string as follows: starting with a native value of 1 for the first enumeration value, incrementing the native value by one for each subsequent enumeration value followed by the zero value followed by the -1 value which will be Invalid unless otherwise specified by the enumeration, followed by each negative value starting with -2. For example, if an IAP enumeration defines values of -4, -2, 0, 1, 5, and 8, these will be mapped to native values as follows: 1 → 1, 5 → 2, 8 → 3, 0 → 4, -1 → 5, -2 → 6, and -4 → 7. The IAP values will be the enumeration strings associated with the mapped value. | The reverse of the native to IAP mapping. For the example the mapping from IAP value to native values will be based on the enumeration value corresponding to the IAP value string as follows: 1 → 1, 2 → 5, 3 → 8, 4 → 0, -5 → -1, 6 → -2, and 7 → -4. The mapped value string will be the enumeration string for the IAP value. |
| Multistate | Any scalar type | Native BACnet-compatible multistate values are mapped to IAP scalars with the same value, with the multistate value corresponding to the multistate string. | The reverse of the native to IAP mapping. |
| 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 BACnet XIF File
You can modify a BACnet XIF definition prior to or after you have used the XIF definition to create, provision, and configure any BACnet devices using the XIF definition. For example, after provisioning a BACnet 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 BACnet XIF definition, modify your BACnet XIF file and re-import it with the modified content. This capability was added with SmartServer 3.2.
Importing a BACnet XIF File
You can import a BACnet XIF file that you downloaded, discovered, or created as described in the previous sections. The XIF file may be standalone, or it may be embedded in a device type package (.dtp) file. A device type package file is a Zip archive containing multiple definition files. To import a BACnet XIF or device type package file, follow these steps:
- Open the SmartServer CMS.
- Click the Import / Export button (
) on the CMS dashboard.
The Import / Export dialog appears.
- Drag your XIF or device type package file to the Drop Files to Import box, or click Browse to browse for your file.
BACnet XIF File Example
The following is an example a BACnet XIF file a Viconics VT7200F5031B Thermostat.
#filetype,BACnet_xif |