Niagara - BACnet/SC - Hub configuration

This article outlines how to properly configure a BACnet/SC hub in Niagara.

NOTE: This BACnet/SC function is available from Niagara 4.11, therefore, it is required to make sure that the 4.11 or higher version has been installed.

Hub configuration in a station

NOTE: Before proceeding with the following instructions, make sure that that station has a digitally signed server certificate active, which is described in the following article: Niagara - Certificates - Creating and signing certificates of devices . Also make sure to set the signed server certificate in the "WebService" as the one to be used.

NOTE: It is required to click the "Save" button in specified places, as the order of configuration affects whether the integration can be carried out correctly.

In the first step, it is required to carry out a basic BACnet configuration, which is described in the article: Niagara - BACnet - Basic configuration steps.
Then, add the ScHubPort port from the bacnet palette to the Config->Drivers->BacnetNetwork->BacnetComm->Network, and set its NetworkNumber slot.
Fig. 1. Adding the ScHubPort port to the BacnetNetwork, and setting its Network Number slot.
Next, expand the Link->Credentials components and in the Operational Certificate slot select the digitally signed server certificate from the list, while in the Issuer Certificate slot indicate the link to the PEM file containing only the public key of the custon CA's certificate with which the said server certificate was signed, and save the changes.

Fig. 2. Selecting the server certificate with which the hub will present itself and adding the public key of the CA certificate.

In the next step, configure the Node Switch to determine the node's behavior for direct in and out connections; to do this, set the Accept Enabled and Initiate Enabled slots to true and save the changes. An error will pop up here, which should be ignored, as it will be fixed at a later stage.
Fig. 3. Setting the Node Switch behavior for direct connections
Expand the Hub Function folder, set the Enabled to true and save changes.
Next, right-click the Hub Function, expand actions and invoke the Add Sc User action. It will result in adding a new user for the BACnet/SC communication.
Set the Enabled slot of the ScHubPort component to true and save changes.
To check the connection between the host and the hub started on the same host, go to the ScHubPort->Link->HubConnector->PrimaryConnection folder and verify the status of connection.

Fig. 4. Checking the BACnet/SC connection status with the hub on the same host

In this step, there may be an error with the TLS certificate, this means that in "WebService" the certificate was not changed to a digitally signed server certificate. If this is the case, correct it, then go back to ScHubPort, set the Enabled slot to false, save the changes and set true again with the changes saved.

NOTE: The MAC36NL driver has innate problems opening communication ports below the number 1024, so while setting the BACnet/SC hub on the MAC36NL, change the HTTPS port in the WebService to any number above 1024, e.g., 8443. With the default port set to 443, it will not be possible to set the BACnet/SC hub on the MAC36NL correctly. This problem does not apply to the JACE8000 driver.

NOTE: The default name of the hub is "hub"; to change it, go to the ScHubPort->Link->HubFunction->WebSocketAcceptor location and edit the Servlet Name slot. This change involves writing the same name to the Hub Uri Path slot in the ScHubPort->Link->HubConnector->PrimaryConnection location both in the hub and in the configuration of clients that connect to it.

NOTE: In order to guarantee greater reliability of the BACnet/SC network, a second (backup) hub can be prepared on another device and a connection to it can be configured in the Failover Connection. If there is a certificate signed by another Certificate Authority (CA) on the standby device, add the public key of the second CA certificate in the Issuer Certificate2 component. The name of the backup hub (Servlet Name) must be different from the primary one.

NOTE: Make sure to set up roles for BACnet and BACnetSC_ScHubPort users. Roles must have appropriate access to components that are to be overridden in the future from another device connecting via the BACnet/SC protocol.

Configuration of the hub’s device to work with devices with certificates signed by different CAs

Normally, this should be done by specifying different CA public certificate keys in the Issuer Certificate slots, and alternative server certificates in the webService, but the driver has a bug that needs to be circumvented as described below. In short, the workaround is to create 2 (or more) ScHubPort on one station and start routing between them.

The first step is to create (in platform->certificateManagement) 2 server certificates and generate CSR files from them. Then both of them should be signed by different CAs, and the signed file must be in the PEM file standard. After receiving both files, import them to platform->certificateManagement.

One of the server certificates along with the CA certificate's public key should be used exactly as described in the previous section.

For the other server certificate and the CA certificate's public key, add a new webService from the web palette in the Config->Services location.

Fig. 6. Two webServices added to one station

Next, in the WebService1 component, the second server certificate should be indicated, the communication ports should be changed to other than the WebService component, and the component should be turned on.

Fig. 7. Configuration of the second WebService component

Then, from the bacnet palette, add a second ScHubPort component in the "Config->Drivers->BacnetNetwork->BacnetComm->Network" location and configure it the same way as in the previous section, only using the second server certificate and the second CA certificate public key. Then perform the following steps in addition:

In the NetworkNumber slot of the new ScHubPort2 component, assign a unique network number.
In the "ScHubPort2->Link->HubFunction->WebSocketAcceptor" location, change the Hub's name to a unique one in the ServletName slot, and indicate the component of the second WebService in the WebServiceOrd slot.

Fig. 8. Setting a unique name for a second hub and indicating a proper WebService inside the HubFunction.

In the ScHubPort2->Link->NodeSwitch->WebSocketAcceptor location, change the name of the node switch to a unique one in the ServletName slot and indicate the component of the second WebService in the WebServiceOrd slot.

Fig. 9. Giving a unique name to the second Node Switch and pointing to the corresponding WebService inside the NodeSwitch

On the other hand, the HubConnector in PrimaryConnection, in all devices attempting to connect to the hub, in the HubUriAddress slot must contain (in addition to the address) an indication of the port configured in the WebService1 component. A new unique hub name must be entered in the HubUriPath slot.

Rys. 10. Proper configuration of the client connecting to a second ScHubPort

Next, in the WebServiceOrd slots in the first port, named ScHubPort, point to the first WebService component (in the one with the first server certificate, signed by the first CA certificate) in the ScHubPort->Link->HubFunction->WebSocketAcceptor and ScHubPort->Link->NodeSwitch->WebSocketAcceptor locations.
Finally, enable routing between BACnet ports at the station where the hubs were configured.

Fig. 11.Enabling BACnet routing between configured ports

Having completed the above steps, it will be possible to connect devices with certificates signed by two different CA certificates in a single station, except that it should be borne in mind that these will be separate networks between which BACnet routing has been configured.

Solving problems

In case of configuration problems, the ScHubPort component has many subcomponents, which are slots describing the details of errors. At least some of them are listed below, as well as possible causes and their solutions.

Message	Possible cause and solution
javax.baja.sys.LocalizableException: No link layer operational certificate selected	No server certificate for the BACnet S/C hub has been specified in the ScHubPort->Link->Credentials->OperationalCertificate.
No trust anchors specified for BACnet SC	No CA public certificate has been selected in the ScHubPort->Link->Credentials->IssuerCertificate, to sign clients certificates.
Web socket failed: TlsFatalAlert: certificate_unknown(46)	The server certificate signed by the CA certificate indicated in ScHubPort was not selected in the WebService.
No BACnet/SC user associated with this link layer	A BACnetS/C user has not yet been added via the action invoked on ScHubPort->Link->HubFunction.
Web socket failed: UpgradeException (HTTP status code: 200 OK): Failed to upgrade to websocket: Unexpected HTTP Response Status Code: 200 OK	One of the following: In ScHubPort->Link->Credentials->OperationalCertificate selected a certificate not signed digitally In ScHubPort->Link->HubConnection->PrimaryConnection->HubUriPath a different name than in ScHubPort->Link->HubFunction->WebSocketAcceptor->ServletName was set
Web socket failed: UpgradeException (HTTP status code: 401 Unauthorized): 401 Unauthorized	In ScHubPort->Link->NodeSwitch the AcceptEnabled and InitiateEnabled were not set to true.
Web socket failed: ConnectException: Connection refused	One of the following: in JACE8000 it helped to change the name of the hub (and, of course, to change the name of the hub to which the driver connects) in the case of the MAC36NL controller, the cause is most often the default value of 443 of the HTTPS port in the WebService - it is necessary to switch it to a value above 1024, e.g., 8443.