Intro

The user can find below the details of the new BTL Certified BACnet Operator Workstation (OWS) and BACnet Server (not certified). It includes new functionalities, supported objects and properties. As well as some differences compared to the old configurations.

The documentation for the BACnet connector can be found in BACnet Connector and BACnet Server can be found in BACnet Server.

Objects

Supported objects are as shown in this spreadsheet.

Properties

Supported properties are as shown in this spreadsheet.

Differences

Below are some differences covering both the BACnet Connector Client and BACnet Server.

BACnet Connector Client

1. The bacnetLocalAddress tag is now replaced with bacnetRoute string tag if connecting through VPN and if network number is 0. The bacnetRoute tag will need to be added to the BACnet connector in order for it to communicate and for the connector to know where the device lives. The reason is because VPN doesn’t support broadcast messages such as ‘who-is’ and ‘i-am’. The bacnetRoute tag is a string type and it’s value is the router IP address.

2. The bacnetLocalAddress tag is deprecated.

3. The actorTimeout (“APDU Timeout”) and bacnetRetryCount (“Retry Count”) are now set up in the BACnet Global Config tool, not in the tuning policy record(s). Both will apply to all BACnet connectors.
   Query to batch remove these tags from tuning policies if applicable:
   readAll(connTuning).map x => diff(x, {-actorTimeout, -bacnetRetryCount}).commit

4. After the updating to 5.1, this process identifier number from the BACnet device will be the same for all connectors because the instance number of the device (added in the NC object recipient list) is changed.
   User needs to manually change the process identifier number in the BACnet device or the value of the bacnetAlarmPid tag in order to have specific alarms added in the Alarms app. User should not have to do anything when migrating as the connector will re-subscribe to those NCs using the new pid and the new instance number.

   If there was a bacnetAlarmPid set and for some reason there is a requirement to keep all settings the same, the user would just have to make sure the the bacnetInstance is the same as on the older setup and set it in the BACnet Global Config tool.

5. The ACC object is configured with the kind type as number after the update. The user must manually change it to string type if used.

6. Some point types have changed. Here is a list of those point types.

7. If using a FIN zip on a Windows environment, the user needs initialize the BT BACnet Stack (BBS) configuration manually. Look at the “Setting BBS Manually” section in the BACnet Connector doc on how to do this.

8. New connector is not supported on MAC.

9. New connector supports communication with multiple IP’s (network cards) when local bind address is set to 0.0.0.0 and standard port of 47808. If local bind address is configured to some specific IP and port other than 47808, then it can only communicate on that IP network card and port.

10. All projects on the same instance will share the same local bind address IP and Port.

11. Read Property Multiple (RPM) supports all/optional/required properties also.

12. Write Property Multiple (WPM) with specific Index of Array support added.

13. Proprietary Data types will be displayed as Raw data in FIN.

14. For intrinsic alarms, add the corresponding Event Enrollment (EE) object under the Equip Tree in the database. The EE would be mapped as a point under an equip just like all the other BACnet objects, which then allows the connector to subscribe to those notification events.

15. For IP devices the default value of APDU Timeout is 6sec and Retry Count is 3 (recommended and default in the BACnet Global Config tool).

16. Support for Foreign Device registration.

17. Recommend Java 11 for new FIN.

BACnet Server

1. An object's PRESENT_VALUE is dependent on PriorityArray and RelinquishDefault properties.

2. All the project devices will be on same local network number and local bind address.

3. The bacnetServerLocalAddress and bacnetServerNetwork tags no longer needed on the bacnetServer extension.

4. All the project devices should have a unique device instance number and MAC address.

5. Added new properties:
   a) RelinquishDefault on all Value Objects (AV/BV/MSV)
   b) PropertyList on all supported objects
   c) Polarity for BI

6. Points with Str type and missing the enum tag, won't be added to Server Device (strings don’t exist in BACnet protocol).

7. Writing a value of 0 to any specific index of MSV will clear that index (Null).

8. When the Server is enabled, BBMD and FD are not supported and will not process local broadcast messages.

9. BACnet Client and Server cannot communicate with each other on the same PC.

10. The bacnetServerConfigureIp() function has been deprecated.

11. BACnet Client and Server must have different instance number if in the same instance of FIN.

BACnet Protocol Revision 1.18 Update

Below are new updates with BACnet protocol revision 1.18.

Configuration settings:

• Engineering units

  • standard-cubic-feet-per-day (47808)

  • million-standard-cubic-feet-per-day (47809)

  • thousand-cubic-feet-per-day (47810)

  • thousand-standard-cubic-feet-per-day (47811)

  • pounds-mass-per-day (47812)

  • millirems (47814)

  • millirems-per-hour (47815)

• BACnetWeekNDay

  • Allow selection of the Nth last day of the month in a BACnetWeekNDay : 7, 8, and 9

• UTC_Offset

Support for new object types:

• Timer

  • Properties required for Timer object:

    • Present_Value

    • Timer_State

    • Timer_Running

    • Default_Timeout

    • State_Change_Values

• Network Port

• Elevator Group

• Lift

• Escalator

Support new event types:

• Change_of_timer

Support new properties:

• SubscribeCOV Property Multiple Service

• COV Property Multiple Service

• unConfCOV Property Multiple Service

Network Port

The Network Port object primarily encompasses properties related to networking. Functions such as BBMD support and FD registration now utilize these Network Port properties. Registration of BBMD and FD remains consistent, employing the Folio query method. Additionally, other queries are available for individually managing Network Port properties. Below is a list of these queries along with their descriptions.

Why Network Port Object is Added

The new protocol version update allows FIN to incorporate support for the Network Port Object. Adopting the object property approach simplifies FIN configuration for BBMD and FD, eliminating the need for direct access to FIN. Changes can be made by simply adjusting the property values.

What is the Network Port Object Instance

The instance is Network Port 1 and can be used as NP1 or 56:1.

Properties supported in Network Port Object

All the above properties are readable using bacnetReadPropertyFromDB query in Folio → Launch (refer to Read Network Port Properties section).

Functions that changed

New functions

Register FIN as BBMD

Following the protocol revision 1.18 updates, BBMD no longer supports the BDT table. Instead, all BBMD entries are now added to the BBMD_Broadcast_Distribution_Table property of the Network Port object. Users do not need to manually manage these properties; they only need to register FIN as BBMD using the provided queries. FIN will handle the addition of values to their respective properties internally. Refer to the examples below for guidance.

Example: bacnetRegisterBBMDwithNetworkPort(BBMD-entries, Accept-FD-Registration, Max-Fdt-Entries, Two-Hops)

Use the below queries to register FIN as BBMD.

1. bacnetRegisterBBMDwithNetworkPort()
   This query registers FIN as BBMD using the Network Port object. By default, it automatically adds FIN's self-entry to the BBMD_Broadcast_Distribution_Table property within the Network Port object. Explicitly providing the self-entry is not necessary.

2. bacnetRegisterBBMDwithNetworkPort([["192.168.253.1",47808,"255.255.255.0"]])
   This query adds the specified BBMD entry along with FIN's self-entry to the BBMD_Broadcast_Distribution_Table property of the Network Port object.

3. bacnetRegisterBBMDwithNetworkPort([["192.168.253.1",47808,"255.255.255.0"],["192.168.253.111",47808,"255.255.255.0"]], true, 25, false)
   This query adds all specified BBMD entries, including FIN's self-entry, to the BBMD_Broadcast_Distribution_Table property of the Network Port object.

Upon the successful execution of this query, a success status will be displayed on the folio UI, and the stack will restart to apply the changes. You can then read all the BBMD entries by using a read-property query on the Network Port object (instance 1- NP:1 or 56:1) and the BBMD_Broadcast_Distribution_Table property (414) from any other tool like VTS or YABE. Send the read-property query to FIN with the specified Object and property. Alternatively, you can read the property values using bacnetReadPropertyFromDB (refer to Read Network Port Properties section).

Unregister FIN as BBMD

To unregister FIN as a BBMD and revert it to Normal mode, you can use the bacnetUnregisterBBMDwithNetworkPort query. Executing this query will restart FIN.

Example: bacnetUnregisterBBMDwithNetworkPort()

1. bacnetUnregisterBBMDwithNetworkPort()
   Unregister FIN as a BBMD and restart the stack. The default parameter is TRUE.

2. bacnetUnregisterBBMDwithNetworkPort(false)
   To unregister FIN as a BBMD without restarting FIN, set the parameter to FALSE in the query. You can then run the bacnetApplyNetworkPortPendingChanges() Folio query to apply the changes. However, since the stack must be restarted for the changes to take effect, it is recommended to run bacnetUnregisterBBMDwithNetworkPort() without the FALSE parameter.

Register FIN as FD

Following the protocol revision 1.18 updates, configuring FIN as a Foreign Device is done using the properties of the Network Port object. Parameters such as time-to-live and BBMD IP are now managed through these properties. However, users do not need to worry about these properties as they only need to register FIN as a Foreign Device using the queries provided below. FIN handles the assignment of values to the respective properties internally. Refer to the examples below for guidance.

Example: bacnetRegisterForeignDeviceWithNetworkPort("IP:UDP", timeToLive (in seconds), FD-Registration-Timeout, FD-Registration-Retries)

Specify the IP and UDP address of the BBMD with which you want FIN to register as a Foreign Device. Provide the time-to-live parameter and registration-timeout parameter in the query. The FD-registration-retries parameter is optional (default is 3).

This query internally populates the FD-Subscription-Lifetime & FD-BBMD-Address properties. You can read these values using the bacnetReadPropertyFromDB Folio query (refer to Read Network Port Properties section).

Use the below queries to register FIN as BBMD.

1. bacnetRegisterForeignDeviceWithNetworkPort("192.168.253.136:47808", 1800, 1200, 4)

2. bacnetRegisterForeignDeviceWithNetworkPort("192.168.1.1:47808", 2000, 200)

Unregister FIN as FD

To unregister FIN as a Foreign Device and revert it to Normal mode, use the bacnetUnregisterForeignDeviceWithNetworkPort query. This query will also restart FIN.

Example: bacnetUnregisterForeignDeviceWithNetworkPort()

1. bacnetUnregisterForeignDeviceWithNetworkPort()
   Unregister FIN as a FD and restart the stack. The default parameter is TRUE.

2. bacnetUnregisterForeignDeviceWithNetworkPort(false)
   To unregister FIN as a FD without restarting FIN, set the parameter to FALSE in the query. You can then run the bacnetApplyNetworkPortPendingChanges() Folio query to apply the changes. However, since the stack must be restarted for the changes to take effect, it is recommended to run bacnetUnregisterForeignDeviceWithNetworkPort() without the FALSE parameter.

Read Network Port Properties

As the Network Port object is supported by FIN, similar to the default device object, you can now read the values of Network Port properties directly from the Folio. This functionality allows you to verify the values after setting them using the bacnetWriteNetworkPortProperty() query. Reading the values of the Network Port object's properties is crucial to ensure that the values are correctly set, as listed in the "properties supported" section.

Example: bacnetReadPropertyFromDB (ObjectId, property, index)

Specify the object identifier as the first parameter, followed by the property. The index parameter is optional and is required only if the property is of type array and you want to retrieve it based on an index. By default, the index parameter is null.

Below are some examples:

1. bacnetReadPropertyFromDB("NP1", 75)
   To read the Object-ID of the Network Port object (NP1). In this query, 75 corresponds to the Object-Identifier property.

2. bacnetReadPropertyFromDB("NP1", "BACnet-IP-Mode")
   To determine if FIN is operating as a BBMD, FD, or in Normal mode.

3. bacnetReadPropertyFromDB("NP1", "BBMD_Broadcast_Distribution_Table")
   To read which BBMD entries are present in the BDT.

4. bacnetReadPropertyFromDB(8:1, "object_list")
   To read the Object-List of the Network Port Object.

Write Network Port Properties

Since the latest version of FIN supports functionalities like BBMD and FD using the network port, it is essential to write these properties with correct values. Currently, there is no dedicated UI provided for manipulating Network Port properties, so the only way to do this is through Folio queries.

After changing a property value using bacnetWriteNetworkPortProperty, FIN must be restarted for the changes to take effect. For example, if you change the network-number property value, you must restart FIN for it to start with the new network number. The provision for restarting FIN is flag-based, with the default value being false (i.e., don’t restart FIN), provided in the query. However, it is recommended to restart FIN using the bacnetApplyNetworkPortPendingChanges query.

When you change a property value, the Changes-Pending property is set to TRUE, indicating that some changes have been made and need to be applied. Therefore, once you have made the necessary changes to various network port properties, you can apply those changes by running the bacnetApplyNetworkPortPendingChanges query.

The writable properties are listed below. Only network port properties can be written using this query.

Properties that can be modified in the Network Port object using the bacnetWriteNetworkPortProperty folio query

Example: bacnetWriteNetworkPortProperty (property, value, reStartFIN, index)

The "reStartFIN" parameter defaults to FALSE, meaning that changes are applied without restarting FIN. Setting it to TRUE will restart FIN and apply the changes. The "Index" parameter defaults to null.

1. bacnetWriteNetworkPortProperty(400, "192.168.245.1", true,  null)
   This will set the IP-Address property (Property Identifier - 400) of FIN.

2. bacnetWriteNetworkPortProperty("bacnet_ip_udp_port", 47808)
   This will set the IP-UDP port property of the Network Port Object. However, the changes will be applied only when the stack restarts. After setting this property, if you check the "Changes-Pending" property, it will show TRUE until the changes are applied.

3. bacnetWriteNetworkPortProperty("network-number", 65530)
   This will set the Network-Number property. However, the changes will be applied only when the stack restarts. After setting this property, if you check the "Changes-Pending" property, it will show TRUE until the changes are applied.

The Fallback mechanism

Attempting to change a property value to an inappropriate or unavailable value will result in an error, and FIN will revert to the old configuration. For example, if you try to change the UDP port value to 47809, but that port is already occupied, FIN will revert to the old UDP port, and an appropriate message will be displayed on the UI. This mechanism applies to BBMD and FD queries as well.

Write Network Port properties using any BACnet client

The Network Port object contains various properties that can also be modified using the traditional "Write-property()" request from BACnet tools like Yabe or VTS. However, it's important to note that currently, only 4 properties can be changed using the write-property request. These properties are listed in the table below:

To modify these properties using the write-property service, you'll need to select the object as (Network Port, 1) and choose one of the above mentioned properties. It's important to note that BBMD-Accept-FD-Registrations and BBMD-Broadcast-Distribution-Table are writable only when FIN is configured as a BBMD (refer to the "Register FIN as BBMD" section), while FD-Subscription-Lifetime and FD-BBMD-Address are writable only when FIN is configured as an FD (refer to the "Register FIN as FD" section).

After making these changes using the write-property service, you need to apply the changes in FIN by restarting it. However, manually restarting FIN from a remote location is challenging. To address this, FIN now supports the ReinitializeDevice service request. It is crucial to send the ReinitializeDevice service request to FIN after making changes to property values remotely. Without sending this request, the changes will not apply in FIN.

Below are the parameters to send ReinitializeDevice service request.

State: Warm-Start or Activate-Changes

Password: <As password support is not provided in this release, leave the password field blank>

Apply Changes-Pending

Use the following query to apply pending changes to the stack and restart FIN. It is crucial to run this query after using bacnetWriteNetworkPortProperty to ensure the changes take effect.

Example: bacnetApplyNetworkPortPendingChanges()

Client Restart Query

Another query you can use to restart FIN is the client restart query. This query provides an additional feature: if you explicitly pass TRUE in the query, it restarts FIN with the old configuration, i.e., the configuration from the last successful restart of FIN. This can be used instead of the bacnetApplyNetworkPortPendingChanges() query.

Example: bacnetClientRestart()

1. bacnetClientRestart()
   Restart the client with the current configuration, which may include changes that have not yet been applied to FIN, i.e., changes that are pending.

2. bacnetClientRestart(true)
   Restart the client from the last successful configuration, which will exclude any current changes that have not yet been applied to FIN.