OpenBOS
The OpenBOS App enables the integration and synchronization between Eliona 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 Eliona 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 Eliona 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 Eliona 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 Eliona 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 Eliona: https://{your-eliona-domain.io}/apps-public/open-bos.
Eliona requires the Gateway ID, Client ID, and Client Secret for authentication.
Installation
Install the OpenBOS App via the Eliona App Store.
Configuration
The OpenBOS App requires a configuration via the Eliona settings interface. The following steps are required to configure the app.
Configuring the OpenBOS App
Configurations can be created in Eliona under Settings > Apps > OpenBOS, which opens the app's Generic Frontend. Here you can use the \configs endpoint with the POST method. Each configuration requires the following data:
gwid
The ID of the gateway device used in the API requests.
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. Is automatically derived from the request. Example: "https://{your-eliona-instance.io}/apps-public/open-bos".
enable
Flag to activate or deactivate the retrieval from this API. Default: true.
refreshInterval
Interval in seconds 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.
projectIDs
List of Eliona project IDs for data collection. For each project ID, all smart devices are automatically created as assets in Eliona, with the mappings stored in the OpenBOS app. Example: ["42", "99"].
Example of a complete configuration file in JSON format:
{
"gwid": "1234acbd-3faa-ab32-ab32-21c3876ba",
"clientID": "4321dcba-3faa-ab32-ab32-21c3876ba",
"clientSecret": "your-client-secret",
"appPublicAPIURL": "https://{your-eliona-instance.io}/apps-public/open-bos",
"enable": true,
"refreshInterval": 24,
"requestTimeout": 120,
"projectIDs": [
"42",
"99"
]
}Some fields have default values, so a minimalist configuration file can look like this:
{
"gwid": "1234acbd-3faa-ab32-ab32-21c3876ba",
"clientID": "4321dcba-3faa-ab32-ab32-21c3876ba",
"clientSecret": "your-client-secret",
"projectIDs": [
"42"
]
}Continuous Asset Creation
After configuration, the app starts Continuous Asset Creation (CAC). Recognized resources are automatically created as assets in Eliona, and the user who configured the app is informed via the Eliona notification system.
Structuring Assets
After creation, the assets in Eliona are organized in the same structure as in OpenBOS. This structure remains synchronized, and changes in Eliona (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 Eliona for assets.
Asset Filtering
If not all assets from OpenBOS are to be imported into Eliona, an asset filter can be defined to include only certain assets. The app can filter assets by ID, name, and templateID (for assets and rooms). The instructions for creating a filter can be found in the Asset Filter documentation.
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 Eliona.
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. Eliona adopts this behavior and assigns such data points to the "OpenBOS unassigned" asset.
Alarms
Alarms triggered in OpenBOS are synchronized with Eliona. They are created in Eliona 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 Eliona and is removed accordingly when it ends in OpenBOS.
External Alarms are alarms that are not managed by Eliona. Alarm rules are displayed so that users can tag and categorize them, but Eliona 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 Eliona, 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