App SDK

Apps ermöglichen es Eliona individuell, um neue Funktionen zu erweitern und beliebige weitere Systeme zu steuern und deren Kennzahlen einzubinden. Dazu gibt es bereits eine Vielzahl vorgefertigter Apps, die bei Bedarf genutzt werden können. Mit dem Eliona App SDK existiert ein Werkzeug, mit dem neue und eigene Apps entwickelt werden können und so die Palette verfügbarer Integrationen und Funktionen ausgebaut wird.

Überblick

Für die Entwicklung von Apps mit dem Eliona App SDK sind gewisse Anforderungen und Rahmenbedingungen zu beachten. Zum einen gilt es definierte Schnittstellen zu nutzen und zum anderen definierten Schnittstellen anzubieten. Nur so kann eine App reibungslos in einer Eliona-Umgebung eingesetzt werden. Ausserdem sind technische Voraussetzungen zu erfüllen. Diese dienen primär einer einheitlichen Konfiguration der App sowie der Kompatibilität über alle Apps hinweg.

Zentrale Anlaufstelle für das Eliona App SDK und alle notwendigen Ressourcen für die Entwicklung von Apps sind bei GitHub zu finden.

Schnittstelle

Zugriffe auf das Eliona-Kernsystem erfolgen ausschliesslich über die Eliona-API. Für eigene Daten, beispielsweise zur Konfiguration, ist eine Datenbank zur dauerhaften Persistierung zu verwenden. Auf diese Daten sowie auf mögliche Funktionen der App kann von extern nur über eine eigene API zugegriffen werden.

REST API

Damit Apps auf Funktionen und Daten des Eliona-Kernsystems zugreifen können, stellt Eliona eine umfangreiche REST-API sowie WebSockets zur Verfügung. Die Erreichbarkeit dieser API muss über die Umgebungsvariablen API_ENDPOINT und API_TOKEN konfiguriert werden können.

Für den Zugriff auf die REST API und die 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 ermöglicht, ohne eine vollständige Eliona-Umgebung zu nutzen.

Datenbank

Apps benötigen in der Regel eigene Daten. Das sind beispielsweise:

Konfigurationsdaten (allg. Einstellungen, Timeouts, Poll-Intervalle usw.)
Daten für den Zugriff auf externe Systeme (Passwörter, API-Endpunkte usw.)
Mapping zwischen Eliona-Objekten und externen Einheiten (Assets, Devices usw.)

Diese Daten sind durch die App dauerhaft in einer Datenbank zu persistieren. Diese Datenbank muss über die Umgebungsvariable CONNECTION_STRING konfiguriert werden können. Innerhalb der Datenbank sind diese Daten in einem App-eigenen Schema, typischerweise mit dem Namen der App, abzulegen. Zur Sicherstellung einer übergreifenden Kompatibilität aller Apps müssen die Datenbankzugriffe reibungslos und vollständig mit einem PostgreSQL DMBS funktionieren.

Für den Zugriff auf die Datenbank können vorgefertigte Bibliotheken verwendet werden, die bereits alle notwendigen Voraussetzungen berücksichtigen.

GitHub - eliona-smart-building-assistant/go-utils: Go utils library for Eliona App SDKGitHub

Für die Entwicklung kann ein Mock verwendet werden, der den Zugriff auf eine geeignete Datenbank ermöglicht, ohne eine vollständige Eliona-Umgebung zu nutzen.

App API

Sofern eine App separate Funktionen oder eigene Daten anbietet bzw. benötigt, müssen diese extern durch eine eigene API aufgerufen oder modifiziert werden können. Somit ist es unter anderem möglich, dass die Eliona für die App eigene Konfigurationsoberflächen anbietet.

Die Definition dieser Schnittstelle ist über eine OpenAPI-Beschreibungsdatei mit dem Namen openapi.yaml zu definieren. Dadurch soll eine einheitliche und exakte Beschreibung der Schnittstelle sichergestellt werden. Die Erreichbarkeit der API muss über die Umgebungsvariable API_SERVER_PORT (Standardwert 3000) einstellbar sein.

Die API muss zusammen mit der Funktion der App verfügbar sein. Das bedeutet, dass beim Start einer App auch immer gleichzeitig die API gestartet sein muss.

App Lebenszyklus

Eine erstellte App durchläuft einen Lebenszyklus innerhalb einer Eliona-Umgebung.

Freischaltung
Installation
Initialisierung
Weiterentwicklung
Deinstallation

Damit eine App für einer Eliona-Umgebung zur Verfügung steht bzw. genutzt werden kann, muss die App freigeschaltet werden. Dazu muss der Administrator die App unter ihrem Namen registrieren. Dazu gehört, dass die App innerhalb Eliona versioniert werden kann und dass der für den Zugriff notwendige Token für die Eliona-API generiert und bekannt gegeben wird.

Die Installation stellt sicher, dass eine lauffähige Version der App zur Verfügung steht. In der Regel ist dies ein Docker-Image, das notwendigen Komponenten der App enthält und startet.

Die Initialisierung der App erfolgt im Rahmen des ersten Starts der App innerhalb einer Eliona-Umgebung. Dabei wird dieser Start der App in Eliona registriert und die App selbst kann, sofern erforderlich, ihr Datenbankschema sowie notwendige Datenbankobjekte anlegen und mit Initialwerten befüllen.

Nach dem ersten Start der App können mehrere Weiterentwicklungen die App modifizieren und eine Migration bestehende Strukturen oder Daten erfordern. Dazu können Patches in einer Eliona-Umgebung registriert und die notwendigen Schritte durchgeführt werden.

Wird eine App nicht weiter benötigt, kann sie wieder aus einer Eliona-Umgebung entfernt werden. Das bedeutet, dass die App gestoppt und die lauffähige Version entfernt wird.

Installation

Für die Installation einer App muss auch als Docker Image zur Verfügung stehen, um letztendlich modular in einer Eliona-Umgebung integriert und gestartet werden zu können. Demnach benötigt jede App ein passendes Dockerfile, über das ein Image mit einer lauffähigen Version der App erstellt werden kann. Das Image muss dann alle notwendigen Komponenten der App (funktional, App-API usw.) starten.

Initialisierung

Die Initialisierung der App muss von dieser in Eliona registriert werden. Damit wird der Eliona-Umgebung mitgeteilt, dass die App eingerichtet und verfügbar ist. Voraussetzung ist, dass die App vorher in Eliona freigeschaltet wurde. Folgende Aufgaben sind typisch im Rahmen einer Initialisierung:

Registrierung über Eliona-API
Anlage Datenbankschema für App
Erstellung Datenbankobjekte
Anlage Standarddaten

Für die Initialisierung können vorgefertigte Bibliotheken verwendet werden, die bereits alle notwendigen Voraussetzungen berücksichtigen.

Weiterentwicklung und Migration

Für neuere Version einer App müssen diese jeweils in Eliona registriert werden. Dies dient gleichzeitig der Erkennung, welche Version bisher installiert ist und somit ob und welche Migrationsschritte eventuell zu erledigen sind.

Für die Migration können vorgefertigte Bibliotheken verwendet werden, die bereits alle notwendigen Voraussetzungen berücksichtigen.

App Best Practices

Continuous Asset Creation (CAC)

Das Continuous Asset Creation (CAC) ermöglicht es Apps, automatisch neue Geräte und Sensoren zu erkennen und Assets in Eliona anzulegen, einschliesslich des Mappings zwischen ihnen. Hierarchische Beziehungen und vorhandene Bezeichnungen können berücksichtigt werden, während der Benutzer entscheidet, wie er die automatisch erstellten Assets in Eliona verwendet. Das CAC unterstützt auch das Löschen von Assets und ermöglicht die Erstellung von Vorlagen für Dashboards, die die automatisch generierten Assets angemessen darstellen.