BACNet Driver

The BACNet Driver provided by ESF is a implementation of the BACNet protocol for Wires and Asset model. It is based on the Bacnet4j library and allows to connect, read from and write to BACNet remote devices.

🚧
This documentation is for the ESF BACNet Driver version 1.0 and 2.0.
For newer versions please refer to this page.

Download and Installation

The ESF BACNet driver is available in the Official ESF Downloads page and in the Eclipse Kura Marketplace.

The driver can be installed as a .dp package or directly from the Kura Marketplace as described here.

Features

The ESF BACNet Driver supports both IP and MS/TP protocols, that can be configured using the web interface.

All the standard objects presented in the ANSI/ASHRAE Standard 135-2016 are supported. The various properties can be read and written by the Driver in a seamless way. In section are listed the supported data types.

The primitive types can be converted in all the standard Java types, while the enumerated type is converted only to Strings. The constructed (complex) types are converted to a Json string.

Callbacks and listeners are supported as well.

ESF BACNet Driver configuration

The Driver configuration tab shows the following options:

Protocol type: the data link protocol to be used for communication. The available options are IP and MS/TP.
BACnet/IP Subnet address: the subnet address in CIDR notation when the BACnet/IP protocol is chosen.
BACnet/IP Port: the port to be used for the BACnet/IP connection.
BACnet/MSTP Serial port: the RS 485 serial port when BACnet/MSTP option is chosen.
BACnet/MSTP Serial baudrate: the RS 485 serial baudrate for BACnet/MSTP.
BACnet/MSTP Serial data-bits: the RS 485 serial data bits for BACnet/MSTP.
BACnet/MSTP Serial parity: the RS 485 serial parity for BACnet/MSTP.
BACnet/MSTP Serial stop-bits: the RS 485 seria stop bits for BACnet/MSTP.
Local device instance number: the instance number of the local device used to connect to BACNet remote devices.
Discovery Timeout: the timeout in seconds for discovering new devices.
Change-Of-Value subscription lifetime: the lifetime of COV subscriptions. After the lifetime timeout, the driver will automatically refresh the subscriptions.

🚧
Since the BACNet protocol uses the udp port 47808, the user has to open it in the firewall.

ESF BACNet Driver usage

As presented in the Introduction to Drivers and Assets, an Asset is a logical representation of a field device. The asset is described as a set of channels that represent the data to be retrieved by the remote device. The channels in the ESF BACNet Driver are configured by the following options:

enabled: enable/disable the channel.
name: a friendly name for the channel.
type: type of operation to be performed. READ, WRITE and READ-WRITE are the available options.
value.type: the Java types a data have to be converted. Some BACNet types cannot be converted to all Java types. Please see this section.
listen: enable a listener for this channel.
remote.device: the instance number of the remote device.
object.type: the type of the object on the remote device.
object.instance: the instance number of the remote object.
property: the name of the property on the remote object.
cov.increment: set the minimum change-of-value that triggers a listener.

Supported data types

The ESF BACNet Driver supports the following data types.

Primitive

All primitive data types are supported (BitString, Boolean, CharacterString, Date, Double, Enumerated, Null, ObjectIdentifier, OctetString, Real, SignedInteger, Time, UnsignedInteger, Unsigned8, Unsigned16 and Unsigned32). They can be converted to almost all Java types.

Enumerated

All enumerated are supported. They can be converted only to Java strings.

Constructed

The constructed types are converted to JSON Strings. All types are supported, except the following types: ActionCommand (partial support), ActionCommandList, AssignedAccessRights, BDTEntry, ChannelValue (partial support), CovSubscriptions, CovMultipleSubscriptions, CredentialAuthenticationFactor, DeviceObjectPropertyValue, EventLogRecord, EventNotificationSubscription, GroupChannelValue, HostAddress, KeyIdentifier, LogData, LogMultipleRecord, LogRecord, LogStatus, NameValue, ObjectPropertyValue, PropertyAccessResult, PropertyStates, PropertyValue, ReadAccessResults, ReadAccessSpecification, SecurityKeySet, WriteAccessSpecification.

Examples of JSON strings for constructed types

ValueSources:

{
   "ValueSource":{
      "Address":{
         "NetworkNumber":2,
         "MacAddress":"[11,22,33,44,55,66]"
      }
   }
}

{
   "ValueSource":{
      "DeviceObjectReference":{
         "ObjectId":{
            "ObjectIdentifier":{
               "ObjectType":"device",
               "InstanceNumber":9
            }
         },
         "DeviceId":{
            "ObjectIdentifier":{
               "ObjectType":"analog-input",
               "InstanceNumber":9
            }
         }
      }
   }
}

Arrays of primitives:

{
   "Unsigned32Array":[
      100,
      33
   ]
}

Client COV:

{
   "ClientCov":{
      "Real":1.0
   }
}

Process ID Selection:

{
   "ProcessIdSelection":{
      "Unsigned32":32
   }
}

Recipient list:

[
   {
      "Destination":{
         "ValidDays":"[false, true, true, true, true, true, true]",
         "FromTime":{
            "Time":{
               "Hour":1,
               "Minute":0,
               "Second":0,
               "Hundredth":0
            }
         },
         "ToTime":{
            "Time":{
               "Hour":23,
               "Minute":59,
               "Second":59,
               "Hundredth":99
            }
         },
         "Recipient":{
            "Recipient":{
               "ObjectIdentifier":{
                  "ObjectType":"analog-input",
                  "InstanceNumber":0
               }
            }
         },
         "ProcessIdentifier":0,
         "IssueConfirmedNotifications":false,
         "Transitions":"[false, false, false]"
      }
   },
   {
      "Destination":{
         "ValidDays":"[true, true, true, true, true, true, true]",
         "FromTime":{
            "Time":{
               "Hour":0,
               "Minute":0,
               "Second":0,
               "Hundredth":0
            }
         },
         "ToTime":{
            "Time":{
               "Hour":23,
               "Minute":59,
               "Second":59,
               "Hundredth":99
            }
         },
         "Recipient":{
            "Recipient":{
               "ObjectIdentifier":{
                  "ObjectType":"analog-input",
                  "InstanceNumber":0
               }
            }
         },
         "ProcessIdentifier":0,
         "IssueConfirmedNotifications":false,
         "Transitions":"[false, false, false]"
      }
   }
]

Driver configuration examples

The following images show a typical configuration for the ESF BACNet Driver and asset.