# Edge Apps

# Summary

An Edge app is a LUA (opens new window) application that can be pushed to the users' gateway together with some configuration options for that app. Apps can have a multitude of properties, and some values from Lynx are automatically injected into the LUA environment. Apps are managed using the Edge-App portal or API:s.

# Architecture (API:s)

Several API-endpoints are used to manage and configure the available apps. A published app should be seen as a complete program that can be downloaded and run on any gateway.

# Lifecycle

When a new app is created some basic information such as description and other data is needed. This data is mainly used for the index and displaying apps in a friendly way.

The newly created app does not need to have any code or configuration yet. It is only the listing that is created. This listing can never be removed, although an app can be hidden using the public flag. An app that is not public is only visible in the same organization as the app was created in. Apps can not be removed because the app might be running as an instance on an installation not visible to the publisher. If the app were removed and the users' gateway restarted the app would fail to download and the user might encounter unexpected behaviour.

When the index has been created a new version of the app can be created. Each version is represented with a hash. And it is possible to name the hash as a release. Each version of an app needs two things, the LUA-code and the config.json file.

# Configuration

A published app can be configured to run one or several times on a gateway as instances. This is, the app is run with the same executable code using different configurations. The configuration sent to the API includes the installation ID, app ID, app version and user config. The app version can be either the hash or the named of a release. The hash is useful for testing a new release of the app, running new code as this is normally not visible for users (special flag to view in API-request).

User configuration is normally determined by the options provided in the config.json file. This file specifies the parameters that the app expects to be able to run.

# Architecture (gateway)

All programs on the Gateway is run inside the IoT Open Runtime (iotopen-rt). The runtime handles authentication of the gateway to API:s and on MQTT. The program managing the Edge-apps is called edged.

The edged program consists of several layers. The daemon itself handles fetching of configurations, updating the apps version and doing callbacks into the running environment of the app. Each app is started inside an abstraction layer with a socket connection to the daemon. The socket is used for RPC communication from the daemon. The edged software also downloads the executable code and injects the user configuration into the environment.


# Callbacks

The following methods will be called inside the app-runtime if defined.

Method Description When
onFunctionsUpdated Normally used to register new functions for inclusion in app or remove functions that are no longer relevant. If a function is changed/added/removed.
onStart Set up application with initial parameters and state At every start of app.
onCreate App needs to change something when created, fetch more info or write files to the system. First run of app (before onStart).
onDestroy Handle cleanup and unregister all resources. App is removed.
onExit Can be used to save the state. When asked to exit.

# Available packages

Most of the standard Lua packages are built into iotopen-rt. The following packages have been added to provide more functionality.

Package name Description Link
lynx Wrapper functions for API calls. More
timer Provide time based operations More
json JSON handling More
mq MQTT Connectivity More
log Logging helpers More
edge Helper functions for Edge compute More
cfg All parameters set by the user in when configuring the app
functions An updated list of all available functions on this installation
app Information of the current app