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

You can create and modify device interface (XIF) definitions for BACnet/IP or BACnet MS/TP devices.  A BACnet XIF definition specifies the name, program ID, manufacturer, and BACnet objects in a device.

This topic includes the following sections:

Creating a BACnet XIF File

To create a BACnet XIF definition, you create a CSV file with a .bac extension that defines the device interface for a BACnet device interface (XIF).  The name of the BACnet XIF file, without the .bac extension, is the name of the BACnet XIF. The extension must be .BAC or .bac.  You cannot use a compound extension name such as .bac.csv.  To create the file, you will need the manufacturer's BACnet Protocol Implementation Conformance Statement (PICS) for the device, or the BACnet object type and object instance numbers reported by a BACnet workstation. You can download a free BACnet workstation for this purpose here

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 
#program_ID,9B008C011E00FC04
#version,v3.20.001
#product_name,VT7200C5x00B
#manufacturer,Viconics Electronics Inc
#description,Viconics VT7200 zone controller
Block Name,Block Index,Datapoint Name,Address,IAP Type,Write Enable,BACnet Priority Support,Writable Normal Value

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>
#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 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 
#version,v3.20.001
#product_name,VT7200C5x00B
#manufacturer,Viconics Electronics Inc
#description,Viconics VT7200 zone controller

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
AV,7,Room Temperature,AV:7,+,float,false

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/
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 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 (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 AIAOAVBIBO, BV, LAV, IV, MSI, MSO, MSV, and PIV BACnet outputs (AOBOMSO) are the equivalents of LON and Modbus inputs.  BACnet inputs (AIBIMSI) are the equivalent of LON and Modbus outputsThe 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 the Documents Archive area for details.
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 (+).   BACnet AO and BO objects must specify +. BACnet AI and BI objects must specify -

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

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. 

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

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 TypeIAP TypeNative → IAP MappingIAP → Native Mapping
Any scalar typeAny scalar typeScaled native value

Scaled IAP value

MultistateEnumeration

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.  

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

BACnet XIF File Example

The following is an example a BACnet XIF file a Viconics VT7200F5031B Thermostat.

#filetype,BACnet_xif
#program_ID,9B008C011E00FC04
#version,v3.20.001
#product_name,VT7200C5x00B
#manufacturer,Viconics Electronics Inc
Block Name,Block Index,Datapoint Name,Address,IAP Type,Write Enable,BACnet Priority Support,Writable Normal Value
AV,7,Room Temperature,AV:7,float,+,false,false
BI,29,BI 1 Status,BI:29,boolean,-,false,false
BV,8,Room Temp Override,BV:8,boolean,+,false,false
AV,39,Occupied Heat Setpoint,AV:39,float,+,false,false
BV,51,Temperature Scale,BV:51,scalar,+,false,false
  • No labels