# 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 |