# OpenBOS > The OpenBOS app enables integration and synchronization between Eliona and [ABB Ability™ Building Edge](https://new.abb.com/low-voltage/products/building-automation/building-edge) (using the OpenBOS software). ### Overview This guide 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, an integrated tool of Building Edge for configuration, is [here](https://library.abb.com/d/9AKK108467A9325) available. In the following, it is referred to as **Edge Editor Doc** and the content corresponds to revision G of the English version. #### Topology and services The building data is collected by Building Edge, assigned to assets, and sent to the ABB Ability Cloud. From there, the assets are retrieved via the Eliona app and created automatically. ![Building Edge schema example](https://raw.githubusercontent.com/eliona-smart-building-assistant/open-bos-app/refs/heads/develop/user_guide/building_edge_schema.png) #### Initial installation The following configurations must be made during the initial installation: **Local configuration** Once Building Edge is powered on, it can be accessed via a browser through LAN port 1 or 2. Carry out the remaining steps according to the **Edge Editor Doc** (pages 23–32). **Cloud configuration** For the Edge to connect 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, review the general settings and adjust or complete them if necessary according to **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: Carry out 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 from data points, each data point must be configured for API subscriptions: 1. In the **Library/asset template**: 2. Select your asset. 3. Click on the **Edit pencil icon**. 4. Go to **API subscription**. 5. Enable the desired subscription. 6. Don't forget to click **Save** (top right in the bar next to “API subscription”). ![Enable API subscription](https://raw.githubusercontent.com/eliona-smart-building-assistant/open-bos-app/refs/heads/develop/user_guide/api_subscription.png) #### App registration 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 configuration through the Eliona settings interface. The following steps are required to configure the app. #### Configuration of the OpenBOS app Configurations can be created in Eliona under `Settings > Apps > OpenBOS` created, which opens the [Generic Frontend](https://doc.eliona.io/collection/v/eliona-english/manuals/settings/apps) opens the app. Here you can use the `\configs`interface with the POST method. Each configuration requires the following data: | Attribute | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `gwid` | The ID of the gateway device used in API requests. | | `clientID` | The client ID for OAuth 2.0 authentication. | | `clientSecret` | The client secret for OAuth 2.0 authentication. | | `appPublicAPIURL` | URL of this app's public API. Automatically derived from the request. Example: "https\://{your-eliona-instance.io}/apps-public/open-bos". | | `enable` | Flag to enable or disable retrieval from this API. Default: `true`. | | `refreshInterval` | Interval in seconds for retrieving data from the API. Default: `24`. | | `requestTimeout` | Timeout for API requests in seconds. Default: `120`. | | `active` | Is set by the app to `true` 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: ```json { "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 minimal configuration file can look like this: ```json { "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 begins continuous asset creation (CAC). Detected resources are automatically created as assets in Eliona, and the user who configured the app is informed via the Eliona notification system. **Structuring the 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 during 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. Usually there is a “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; the entire ontology will move with them. It is not possible to change GAIs in Eliona for assets. #### Asset filtering If not all assets are to be imported from OpenBOS 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 filters can be found in the [asset filter documentation](https://doc.eliona.io/collection/dokumentation/einstellungen/apps/asset-filter). #### Asset types Asset types are created and synchronized automatically from the OpenBOS asset templates. | Eliona | OpenBOS | | ------------------ | ----------------------------------------------------------- | | 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 remains 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 type "External"** and 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 a **confirmation** it can be acknowledged in Eliona, and this acknowledgment is synchronized with OpenBOS. ### Monitoring the app status Together with asset creation, an asset called “OpenBOS app” is also created. It is used to inform users about the app's status - it indicates whether the app is running (asset status -> active/inactive) and what status it has - the Status attribute. If the app status is not “OK”, this means the app may not be functioning properly. If the error status persists, let us know by submitting a bug report.