Eliona App for Zevvy

This app sends measurement data to Zevvy using the Zevvy-API.

Configuration

The app needs environment variables and database tables for configuration. To edit the database tables the app provides an own API access.

Registration in Eliona

To start and initialize an app in an Eliona environment, the app has to be registered in Eliona. For this, entries in database tables public.eliona_app and public.eliona_store are necessary.

This initialization can be handled by the reset.sql script.

Environment variables

• CONNECTION_STRING: configures the Eliona database. Otherwise, the app can't be initialized and started (e.g. postgres://user:pass@localhost:5432/iot).

• INIT_CONNECTION_STRING: configures the Eliona database for app initialization like creating schema and tables (e.g. postgres://user:pass@localhost:5432/iot). Default is content of CONNECTION_STRING.

• API_ENDPOINT: configures the endpoint to access the Eliona API v2. Otherwise, the app can't be initialized and started. (e.g. http://api-v2:3000/v2)

• API_TOKEN: defines the secret to authenticate the app and access the Eliona API.

• API_SERVER_PORT(optional): define the port the API server listens. The default value is Port 3000.

• LOG_LEVEL(optional): defines the minimum level that should be logged. The default level is info.

Database tables

The app requires configuration data that remains in the database. To do this, the app creates its own database schema zevvy during initialization. To modify and handle the configuration data the app provides an API access. Have a look at the API specification how the configuration tables should be used.

• zevvy.configuration: Contains configuration of the app and the access to Zevvy API.

• zevvy.asset-attributes: Defines asset attributes whose data is sent to Zevvy as measurements.

Generation: to generate access method to database see Generation section below.

References

App API

The app provides its own API to access configuration data and other functions. The full description of the API is defined in the openapi.yaml OpenAPI definition file.

• API Reference shows details of the API

Generation: to generate api server stub see Generation section below.

Configuring the app

To use the app it is necessary to create at least one configuration. A configuration points to one Zevvy Login.

A minimum configuration that can used by the app's API endpoint POST /configs is:

{
  "authRootUrl": "https://iam.zevvy.org/realms/zevvy-prod",
  "apiRootUrl": "https://api.zevvy.org",
  "clientId": "client",
  "clientSecret": "secret",
  "enable": true
}

The configuration may include an optional refreshToken property provided by the user. In its absence, the application initiates the authorization sequence by generating a new login URL. This URL is communicated to the requester through a user notification and can also be accessed by making a GET /configs request.

Following user login and API access verification, the application finalizes the configuration in the background. Upon successful acquisition of both an access and a refresh token, the user receives a notification via the Eliona frontend.

It's important to note that both the clientSecret and refreshToken properties are write-only for enhanced security. Thus, they cannot be fully retrieved through GET requests.

Define assets attributes

To ensure data is successfully reported to Zevvy, the necessary asset attributes must be correctly configured via PUT /asset-attributes request.

{
  "configId": 1,
  "assetId": 4711,
  "subtype": "input",
  "attributeName": "power"
}

For each attribute all the data stored in Eliona will be sent to Zevvy with the corresponding timestamp.

The asset's GAI is used as device reference and the name off the attribute as register reference. The values can be overwritten by the optional deviceReference and registerReference properties.

Tools

Generate API server stub

For the API server the OpenAPI Generator for go-server is used to generate a server stub. The easiest way to generate the server files is to use one of the predefined generation script which use the OpenAPI Generator Docker image.

.\generate-api-server.cmd # Windows
./generate-api-server.sh # Linux

Generate Database access

For the database access SQLBoiler is used. The easiest way to generate the database files is to use one of the predefined generation script which use the SQLBoiler implementation.

.\generate-db.cmd # Windows
./generate-db.sh # Linux

Generate asset type descriptions

For generating asset type descriptions from field-tag-annotated structs, asse-from-struct tool can be used.