App SDK
App SDK
Apps enable Eliona to be individually extended with new functions and to control any other systems and integrate their key figures. A large number of pre-fabricated apps are already available for this purpose and can be used as needed. With the Eliona App SDK, a tool exists with which new and custom apps can be developed, thereby expanding the range of available integrations and functions.
Overview
For the development of apps with the Eliona App SDK, certain requirements and framework conditions must be observed. On the one hand, it is necessary to use defined interfaces, and on the other hand, to provide defined interfaces. This is the only way an app can be used smoothly in an Eliona environment. In addition, technical prerequisites must be met. These primarily serve to ensure a uniform configuration of the app and compatibility across all apps.
The central point of contact for the Eliona App SDK and all necessary resources for app development can be found on GitHub.
Interface
Access to the Eliona core system is exclusively via the Eliona API. For custom data, for example, for configuration, a database must be used for permanent persistence. This data, as well as possible functions of the app, can only be accessed externally via a custom API.
REST API
To enable apps to access functions and data of the Eliona core system, Eliona provides an extensive REST API and WebSockets. The accessibility of this API must be configurable via the environment variables API_ENDPOINT and API_TOKEN.
Pre-fabricated libraries can be used to access the REST API and WebSockets, which already take all the necessary prerequisites into account.
For development, a mock can be used that allows access via the API without using a full Eliona environment.
Database
Apps typically require their own data. This includes, for example:
Configuration data (general settings, timeouts, poll intervals, etc.)
Data for accessing external systems (passwords, API endpoints, etc.)
Mapping between Eliona objects and external units (assets, devices, etc.)
This data must be permanently persisted by the app in a database. This database must be configurable via the environment variable CONNECTION_STRING. Within the database, this data must be stored in an app-specific schema, typically with the name of the app. To ensure overarching compatibility of all apps, database access must work smoothly and completely with a PostgreSQL DMBS.
Pre-fabricated libraries can be used to access the database, which already take all the necessary prerequisites into account.
For development, a mock can be used that allows access to a suitable database without using a full Eliona environment.
App API
If an app offers or requires separate functions or its own data, these must be able to be called or modified externally via a custom API. This makes it possible, among other things, for Eliona to provide its own configuration interfaces for the app.
The definition of this interface must be defined via an OpenAPI description file with the name openapi.yaml. This is intended to ensure a uniform and precise description of the interface. The accessibility of the API must be adjustable via the environment variable API_SERVER_PORT (default value 3000).
The API must be available together with the app's function. This means that when an app is started, the API must also be started at the same time.
App Lifecycle
A created app goes through a lifecycle within an Eliona environment.
Activation
Installation
Initialization
Further development
Uninstallation
For an app to be available or usable for an Eliona environment, the app must be activated. To do this, the administrator must register the app under its name. This includes the ability to version the app within Eliona and to generate and announce the token necessary for access to the Eliona API.
Installation ensures that a runnable version of the app is available. This is usually a Docker image that contains and starts the necessary components of the app.
The initialization of the app takes place during the app's first start within an Eliona environment. During this process, the app's start is registered in Eliona, and the app itself can, if required, create its database schema and necessary database objects and fill them with initial values.
After the app's first start, several further developments can modify the app and require a migration of existing structures or data. For this, patches can be registered in an Eliona environment and the necessary steps can be carried out.
If an app is no longer needed, it can be removed from an Eliona environment. This means that the app is stopped and the runnable version is removed.
Installation
For an app to be installed, it must be available as a Docker image to be able to be ultimately integrated and started modularly in an Eliona environment. Accordingly, every app needs a suitable Dockerfile through which an image with a runnable version of the app can be created. The image must then start all the necessary components of the app (functional, App-API, etc.).
Initialization
The app's initialization must be registered by the app in Eliona. This informs the Eliona environment that the app is set up and available. A prerequisite is that the app has been activated in Eliona beforehand. The following tasks are typical during initialization:
Registration via Eliona API
Creation of a database schema for the app
Creation of database objects
Creation of standard data
Pre-fabricated libraries can be used for initialization, which already take all the necessary prerequisites into account.
Further Development and Migration
For newer versions of an app, these must be registered in Eliona. This also serves to detect which version has been installed so far and thus whether and which migration steps may need to be performed.
Pre-fabricated libraries can be used for migration, which already take all the necessary prerequisites into account.
App Best Practices
Continuous Asset Creation (CAC)
Continuous Asset Creation (CAC) enables apps to automatically detect new devices and sensors and create assets in Eliona, including the mapping between them. Hierarchical relationships and existing designations can be taken into account, while the user decides how to use the automatically created assets in Eliona. CAC also supports the deletion of assets and enables the creation of templates for dashboards that appropriately display the automatically generated assets.
App SDK Summary of Requirements
The technical and systemic requirements for an app with the Eliona App SDK can be summarized as follows:
The development of apps takes place in Go
Use of Git version control
App must be registered and an access token must be created
For access, use the Eliona API via access token
For persistence, use a custom database schema
Database objects and access must be compatible with PostgreSQL
Data access and functions from external sources only via a custom API
The app must support at least the following environment variables:
API_ENDPOINT: Endpoint of the Eliona APIAPI_TOKEN: Access token to the Eliona APICONNECTION_STRING: Database for storing custom data (PostgreSQL)API_SERVER_PORT: Accessibility of the app's custom API
The following files are expected:
Dockerfile: Creates a runnable imageopenapi.yaml: Definition and documentation of the app's custom API
App SDK Resource Overview
Several resources and libraries are available for the development of Eliona apps. These are located in the Eliona profile on GitHub.
Eliona on GitHub: https://github.com/eliona-smart-building-assistant
The following resources are to be mentioned in particular:
Eliona-API Documentation: https://api.eliona.io
Template for new apps: https://github.com/eliona-smart-building-assistant/app-template
Go-Client for Eliona: https://github.com/eliona-smart-building-assistant/go-eliona
Go-Client for API: https://github.com/eliona-smart-building-assistant/go-eliona-api-client
Utilities for Go: https://github.com/eliona-smart-building-assistant/go-utils
Last updated