OpenBOS
The OpenBOS App enables the integration and synchronization between BuildingPro Suites and ABB Ability™ Building Edge (using the OpenBOS software).
Overview
This manual provides instructions for configuring, installing, and using the OpenBOS App to manage resources and synchronize data between BuildingPro Suites and OpenBOS Edge.
Required Steps in OpenBOS Building Edge
The complete documentation for using the Edge Editor, a tool integrated into the Building Edge for configuration, is available here. Below, it will be referred to as the Edge Editor Doc, and the content corresponds to Revision G of the English version.
Topology and Services
Building data is captured by the Building Edge, assigned to assets, and sent to the ABB Ability Cloud. From there, the assets are retrieved via the BuildingPro Suites app and automatically created.
Initial Installation
The following configurations must be made during the initial installation:
Local Configuration
As soon as the Building Edge is switched on, it can be accessed via a browser via LAN port 1 or 2.
Follow the further steps according to the Edge Editor Doc (pages 23–32).
Cloud Configuration
For the Edge to be connected to the cloud, it must be in a network with internet access. Adjust the IP address accordingly (see Edge Editor Doc, page 43).
To access the ABB Cloud, a personalized login must be created. Then follow the steps in the Edge Editor Doc (pages 33–40).
General Setup
Next, check the general settings and adjust or complete them if necessary according to the Edge Editor Doc, pages 42–81.
Integration of Field Data
To retrieve data points from a bus system, a new network for the corresponding protocol must be created under "Field Network."
The Ability Cloud is accessible at: https://buildings.ability.abb
Follow the steps according to the Edge Editor Doc (pages 112–123).
Adding Devices and Data Points
To add devices and data points, the CSV import can be used. It is recommended to first export an (empty) CSV file and fill it with data.
Allow Access via API
For BuildingPro Suites to receive updates of data points, each data point must be configured for API subscriptions:
In the Library/Asset Template:
Select your asset.
Click on the Edit pencil icon.
Go to API Subscription.
Activate the desired subscription.
Don't forget to click on Save (top right in the bar next to "API Subscription").
Registering the App in OpenBOS
To connect BuildingPro Suites with your OpenBOS Edge, the Edge must be configured to allow API connections. Contact ABB support for more information. You must provide the public API URL of BuildingPro Suites: https://{your-bprosuites-domain.io}/apps-public/open-bos.
BuildingPro Suites requires the Gateway ID, Client ID, and Client Secret for authentication.
Installation
Install the OpenBOS App via the BuildingPro Suites App Store.
Configuration
The OpenBOS App requires a configuration via the BuildingPro Suites settings interface. The following steps are required to configure the app.
Configuring the OpenBOS App
Configurations can be created in BuildingPro Suites under Settings > Apps > OpenBOS, which opens the app's Generic Frontend. The whole configuration process consists of a few steps:
First is the creation of Configuration entity with POST \configs endpoint which requires the following data:
id
Internal identifier for the configuration (created automatically).
baseUrl
The URL of the BuildingsPortal proxy service through which a connection to Edge device is made.
tokenUrl
The URL of authorization endpoint of Oauth 2.0 service provider.
tokenScope
Oauth 2.0 scope for which authorization should be requested.
clientID
The client ID for OAuth 2.0 authentication.
clientSecret
The client secret for OAuth 2.0 authentication.
appPublicApiUrl
URL of the public API of this app. Example: "https://{your-bprosuites-instance.io}/apps-public/open-bos".
enable
Flag to activate or deactivate the retrieval from this API. Default: true.
refreshInterval
Interval in hours for retrieving data from the API. Default: 24.
requestTimeout
Timeout for API queries in seconds. Default: 120.
active
Is set to true by the app when it is running and to false when it is stopped. Read-only.
userId
Id of the user who should be notified about CAC.
Example of a complete configuration entity in JSON format:
Some fields have default values, so a minimalist configuration file can look like this:
The second step is creation of Gateway entity with POST \gateway\{config-id} where config-id is the id of Configuration created in the previous step. The request requires the following payload data:
id
The UUID of the gateway device (Edge).
siteId
The ID of site in which OpenBos ontology should appear.
configId
The id of Configuration entity to which this Gateway is related Read-only.
ontologyVersion
The latest synchronized version of the ontology in OpenBOS.
createdAt
Timestamp of the creation of this Gateway entity.
changedAt
Timestamp of the last changes made to this entity.
Example of a complete configuration entity in JSON format:
To confirm if Configuration and Gateway were created correctly, a tree for siteId can be requested with the \tree\{site-id} endpoint of Generic Frontend
Continuous Asset Creation
After addition of Configuration and Gateway, the app starts Continuous Asset Creation (CAC).
For CAC to properly pick up desired objects from ontology and create assets for them, a tree filter needs to be defined. The filter supports 4 different Tree types: "functional", "geographical", "network" and "hierarchy" and at least 1 of them has to be defined with some values for assets to start showing.
Example of a complete tree-selection entity in JSON format:
It is enough to put a tree selection with one treeType:
◈ The value null inside of selectedIds list is important, because it makes the filter allow all objects from ontology.
Recognized resources are automatically created as assets in BuildingPro Suites, and the user who configured the app is informed via the BuildingPro Suites notification system.
Structuring Assets
After creation, the assets in BuildingPro Suites are organized in the same structure as in OpenBOS. This structure remains synchronized, and changes in BuildingPro Suites (e.g., renaming an asset or moving a room to another building) are overwritten with the next ontology update.
The only exception are the root assets. These are created in the top-level directory and correspond to the top level of the OpenBOS location structure. As a rule, there is one "Site" in this role. Another root asset is the "OpenBOS unassigned", which contains unassigned assets and data points.
You can rename or move the root assets as you wish, whereby the entire ontology is also moved.
It is not possible to change GAIs in BuildingPro Suites for assets.
Asset Types
Asset types are automatically created and synchronized from the OpenBOS asset templates.
Asset type
Asset template
Attribute - Input
Data point with direction "Feedback"
Attribute - Output
Data point with direction "Command" or "CommandAndFeedback"
Attribute - Info
Property
Limits
Min/Max
Unit
Unit
Value mapping
Enums
Complex data types from OpenBOS are split into separate attributes in BuildingPro Suites.
Orphaned Data Points
If an asset is deleted in OpenBOS but an alarm is still linked to this data point, this data point is retained in the ontology. BuildingPro Suites adopts this behavior and assigns such data points to the "OpenBOS unassigned" asset.
Alarms
Alarms triggered in OpenBOS are synchronized with BuildingPro Suites. They are created in BuildingPro Suites as alarm rules of the type "External" and are controlled by updates from OpenBOS. When an alarm is triggered in OpenBOS, it also appears in BuildingPro Suites and is removed accordingly when it ends in OpenBOS.
External Alarms are alarms that are not managed by BuildingPro Suites. Alarm rules are displayed so that users can tag and categorize them, but BuildingPro Suites is not responsible for checking whether an alarm should be triggered. An external system (in this case, OpenBOS) is responsible for alarm control.
If an alarm requires an acknowledgment, it can be acknowledged in BuildingPro Suites, and this acknowledgment is synchronized with OpenBOS.
Monitoring the App Status
Along with asset creation, an asset named OpenBOS app is also created. It serves to inform users about the status of the app - it signals whether the app is running (asset status -> Active/Inactive) and what its status is - the status attribute. If the app status is not "OK", this means that the app may not be functioning correctly. If the error status persists, please let us know by submitting an error report.
Last updated