App SDK
App SDK
Apps ermöglichen es, die BuildingPro Suites-Suiten um neue Funktionen individuell zu erweitern und beliebige andere Systeme anzusteuern sowie deren Kennzahlen zu integrieren. Zu diesem Zweck steht bereits eine große Anzahl vorgefertigter Apps zur Verfügung, die je nach Bedarf verwendet werden können. Mit dem BuildingPro Suites App SDK steht ein Werkzeug zur Verfügung, mit dem neue und eigene Apps entwickelt werden können, wodurch der Umfang der verfügbaren Integrationen und Funktionen erweitert wird.
Überblick
Für die Entwicklung von Apps mit dem BuildingPro Suites App SDK müssen bestimmte Anforderungen und Rahmenbedingungen beachtet werden. Einerseits ist es notwendig, definierte Schnittstellen zu verwenden, andererseits definierte Schnittstellen bereitzustellen. Nur so kann eine App in einer BuildingPro Suites-Umgebung reibungslos verwendet werden. Darüber hinaus müssen technische Voraussetzungen erfüllt sein. Diese dienen vor allem dazu, eine einheitliche Konfiguration der App und die Kompatibilität über alle Apps hinweg sicherzustellen.
Die zentrale Anlaufstelle für das BuildingPro Suites App SDK und alle notwendigen Ressourcen für die App-Entwicklung ist auf GitHub zu finden.
Schnittstelle
Der Zugriff auf das Kernsystem von BuildingPro Suites erfolgt ausschließlich über die BuildingPro Suites API. Für benutzerdefinierte Daten, beispielsweise für Konfigurationsdaten, muss eine Datenbank zur dauerhaften Speicherung verwendet werden. Auf diese Daten sowie mögliche Funktionen der App kann extern nur über eine eigene API zugegriffen werden.
REST-API
Damit Apps auf Funktionen und Daten des Kernsystems von BuildingPro Suites zugreifen können, stellt BuildingPro Suites eine umfangreiche REST API und WebSockets bereit. Die Erreichbarkeit dieser API muss über die Umgebungsvariablen API_ENDPOINT und API_TOKEN konfigurierbar sein.
Für den Zugriff auf die REST API und WebSockets können vorgefertigte Bibliotheken verwendet werden, die bereits alle notwendigen Voraussetzungen berücksichtigen.
Für die Entwicklung kann ein Mock verwendet werden, der den Zugriff über die API ohne eine vollständige BuildingPro Suites-Umgebung ermöglicht.
Datenbank
Apps benötigen typischerweise eigene Daten. Dazu gehören beispielsweise:
Konfigurationsdaten (allgemeine Einstellungen, Timeouts, Poll-Intervalle usw.)
Daten für den Zugriff auf externe Systeme (Passwörter, API-Endpunkte usw.)
Zuordnung zwischen BuildingPro Suites-Objekten und externen Einheiten (Assets, Geräte usw.)
Diese Daten müssen von der App dauerhaft in einer Datenbank gespeichert werden. Diese Datenbank muss über die Umgebungsvariable CONNECTION_STRING konfigurierbar sein. Innerhalb der Datenbank müssen diese Daten in einem app-spezifischen Schema gespeichert werden, typischerweise mit dem Namen der App. Um die übergreifende Kompatibilität aller Apps sicherzustellen, muss der Datenbankzugriff reibungslos und vollständig mit einem PostgreSQL-DBMS funktionieren.
Für den Zugriff auf die Datenbank können vorgefertigte Bibliotheken verwendet werden, die bereits alle notwendigen Voraussetzungen berücksichtigen.
Für die Entwicklung kann ein Mock verwendet werden, der den Zugriff auf eine geeignete Datenbank ohne eine vollständige BuildingPro Suites-Umgebung ermöglicht.
App-API
Wenn eine App separate Funktionen oder eigene Daten anbietet oder benötigt, müssen diese extern über eine eigene API aufgerufen bzw. verändert werden können. Dadurch wird es unter anderem möglich, dass BuildingPro Suites eigene Konfigurationsoberflächen für die App bereitstellt.
Die Definition dieser Schnittstelle muss über eine OpenAPI-Beschreibungsdatei mit dem Namen openapi.yaml. Dies soll eine einheitliche und präzise Beschreibung der Schnittstelle sicherstellen. Die Erreichbarkeit der API muss über die Umgebungsvariable API_SERVER_PORT (Standardwert 3000) anpassbar sein.
Die API muss zusammen mit der Funktion der App verfügbar sein. Das bedeutet, dass beim Start einer App die API gleichzeitig mitgestartet werden muss.
App-Lebenszyklus
Eine erstellte App durchläuft innerhalb einer BuildingPro Suites-Umgebung einen Lebenszyklus.
Aktivierung
Installation
Initialisierung
Weiterentwicklung
Deinstallation
Damit eine App für eine BuildingPro Suites-Umgebung verfügbar oder nutzbar ist, muss die App aktiviert werden. Dazu muss der Administrator die App unter ihrem Namen registrieren. Dies umfasst die Möglichkeit, die App innerhalb von BuildingPro Suites zu versionieren und das für den Zugriff auf die BuildingPro Suites API erforderliche Token zu erzeugen und bekannt zu machen.
Die Installation stellt sicher, dass eine lauffähige Version der App verfügbar ist. Dies ist in der Regel ein Docker-Image, das die notwendigen Komponenten der App enthält und startet.
Die Initialisierung der App erfolgt beim ersten Start der App innerhalb einer BuildingPro Suites-Umgebung. Dabei wird der Start der App in BuildingPro Suites registriert, und die App selbst kann bei Bedarf ihr Datenbankschema und notwendige Datenbankobjekte anlegen und mit Anfangswerten befüllen.
Nach dem ersten Start der App können mehrere Weiterentwicklungen die App verändern und eine Migration bestehender Strukturen oder Daten erforderlich machen. Dafür können in einer BuildingPro Suites-Umgebung Patches registriert und die notwendigen Schritte durchgeführt werden.
Wenn eine App nicht mehr benötigt wird, kann sie aus einer BuildingPro Suites-Umgebung entfernt werden. Das bedeutet, dass die App gestoppt und die lauffähige Version entfernt wird.
Installation
Damit eine App installiert werden kann, muss sie als Docker-Image verfügbar sein, um letztlich modular in einer BuildingPro Suites-Umgebung integriert und gestartet werden zu können. Dementsprechend benötigt jede App ein geeignetes Dockerfile, über das ein Image mit einer lauffähigen Version der App erstellt werden kann. Das Image muss anschließend alle notwendigen Komponenten der App starten (Funktionalität, App-API usw.).
Initialisierung
Die Initialisierung der App muss von der App in BuildingPro Suites registriert werden. Dadurch wird die BuildingPro Suites-Umgebung darüber informiert, dass die App eingerichtet und verfügbar ist. Voraussetzung ist, dass die App zuvor in BuildingPro Suites aktiviert wurde. Die folgenden Aufgaben sind bei der Initialisierung typisch:
Registrierung über die BuildingPro Suites API
Erstellung eines Datenbankschemas für die App
Erstellung von Datenbankobjekten
Erstellung von Standarddaten
Für die Initialisierung können vorgefertigte Bibliotheken verwendet werden, die bereits alle notwendigen Voraussetzungen berücksichtigen.
Weiterentwicklung und Migration
Für neuere Versionen einer App müssen diese in BuildingPro Suites registriert werden. Dies dient auch dazu, zu erkennen, welche Version bisher installiert wurde und somit ob und welche Migrationsschritte ggf. durchgeführt werden müssen.
Für die Migration können vorgefertigte Bibliotheken verwendet werden, die bereits alle notwendigen Voraussetzungen berücksichtigen.
Best Practices für Apps
Continuous Asset Creation (CAC)
Continuous Asset Creation (CAC) ermöglicht es Apps, neue Geräte und Sensoren automatisch zu erkennen und in BuildingPro Suites Assets anzulegen, einschließlich der Zuordnung zwischen ihnen. Hierarchische Beziehungen und vorhandene Bezeichnungen können berücksichtigt werden, während der Benutzer entscheidet, wie die automatisch erstellten Assets in BuildingPro Suites verwendet werden. CAC unterstützt außerdem das Löschen von Assets und ermöglicht die Erstellung von Vorlagen für Dashboards, die die automatisch erzeugten Assets passend darstellen.
Zusammenfassung der Anforderungen an das App SDK
Die technischen und systemischen Anforderungen an eine App mit dem BuildingPro Suites App SDK lassen sich wie folgt zusammenfassen:
Die Entwicklung von Apps erfolgt in Go
Verwendung der Git-Versionskontrolle
App muss registriert sein und ein Zugriffstoken muss erstellt werden
Für den Zugriff die BuildingPro Suites API über Zugriffstoken verwenden
Für die Persistenz ein eigenes Datenbankschema verwenden
Datenbankobjekte und Zugriff müssen mit PostgreSQL kompatibel sein
Datenzugriff und Funktionen aus externen Quellen nur über eine eigene API
Die App muss mindestens die folgenden Umgebungsvariablen unterstützen:
API_ENDPOINT: Endpunkt der BuildingPro Suites APIAPI_TOKEN: Zugriffstoken für die BuildingPro Suites APICONNECTION_STRING: Datenbank zur Speicherung benutzerdefinierter Daten (PostgreSQL)API_SERVER_PORT: Erreichbarkeit der eigenen API der App
Die folgenden Dateien werden erwartet:
Dockerfile: Erstellt ein lauffähiges Imageopenapi.yaml: Definition und Dokumentation der eigenen API der App
Übersicht über Ressourcen des App SDK
Für die Entwicklung von BuildingPro Suites-Apps stehen mehrere Ressourcen und Bibliotheken zur Verfügung. Diese befinden sich im BuildingPro Suites-Profil auf GitHub.
BuildingPro Suites auf GitHub: https://github.com/eliona-smart-building-assistant
Folgende Ressourcen sind im Besonderen zu nennen:
BuildingPro Suites-API: https://github.com/eliona-smart-building-assistant/eliona-api
BuildingPro Suites-API-Dokumentation: https://api.eliona.io
BuildingPro Suites Mock: https://github.com/eliona-smart-building-assistant/eliona-mock
Vorlage für neue Apps: https://github.com/eliona-smart-building-assistant/app-template
Go-Client für BuildingPro Suites: https://github.com/eliona-smart-building-assistant/go-eliona
Go-Client für API: https://github.com/eliona-smart-building-assistant/go-eliona-api-client
Hilfsprogramme für Go: https://github.com/eliona-smart-building-assistant/go-utils
Zuletzt aktualisiert
War das hilfreich?