11.7. Application Management

GEISA Application & Device Management

Application management is the process of deploying, activating, deactivating, and decommissioning applications on a GEISA ADM conformant platform, for execution within an execution environment.

The LwM2M /9/x Software Management object SHALL be used to manage the software package lifecycle of containerized edge applications running in the GEISA EE. In contrast to the Firmware Update object, each instance of the multi-instance Software Management object represents a distinct edge application Package installed in the EE.

11.7.1. Application Package Format

To enable interoperable of loading of application packages into the Edge Management System, GEISA defines a simple application package format. This format is used for all execution environments GEISA Execution Environment.

The format is a gzipped tar file, following the POSIX.1-2001/pax tape archive format. This is the default archive format used by GNU tar, see [GNUTAR], Appendix E for details, but common tar implementations should support this format by default, and it is well supported by LibArchive.

The file SHALL contain a GEISA application manifest in the root of the archive named manifest.json. For publisher provided manifests, it SHALL be the vendor manifest. For manifests provided by an EMS to a platform, it SHALL be the deployment manifest.

Each artifact listed in manifest.json shall be provided in the root of the compressed archive.

The format of artifacts themselves will be determined by the toolchain in use; however, LEE application images SHALL follow the file layout described in Base Filesystem GEISA Linux Execution Environment.

To minimize edge application image sizes, applications are encouraged to dynamically link against the libraries provided by the base GEISA environment rather than providing their own. Consideration for the management of the base libraries and/or package dependencies will be deferred to a future release; at this time, no consideration is made for the use of LwM2M object 14 Software Component.

11.7.2. Application Installation and Activation

Similar to Firmware Update, the LwM2M spec permits edge app packages can be transferred to the EE via either of the following methods:

  • PUSH via Write of the opaque package to /9/x/2 Package

  • PULL via Write to resource /9/x/3 Package URI for the GEISA platform

    to download as soon as practical

PULL downloads will attempt to use the protocol specified in the URI. GEISA ADM conformant EMS and GEISA ADM conformant platform implementations must support CoAP transfers. GEISA ADM conformant EMS must include the ability to host firmware and application images for download via CoAP. GEISA conformant EMS MAY support alternate protocols (like HTTP) or specifying external URIs.

In contrast to Firmware Update, the Software Management object 9 does not support the concept of automatic Installation or Activation. Both operations of Installation and Activation are manually executed by the EMS, following successful package download/verification and successful package install, respectively.

The Software Management Object /9 instance number is independent of resource 4050 AppID. Resource 4051 Software Instance links a GEISA application Object Instance to the corresponding /9 instance.

The following example demonstrates GEISA conformant edge app installation and

activation:

  1. PULL download of the edge app package from the URL set by the EMS into /9/x/3 Package URI, shown in Figure 11.9.

  2. The EMS performing a manual Execute /9/x/4 to trigger edge app Installation following successful app download and verification, shown in Figure 11.10.

  3. The EMS performing a manual Execute /9/x/10 to trigger edge app Activation following successful app installation, shown in Figure 11.10.

  4. The EMS performing a manual Execute /9/x/6 to trigger Uninstall of the edge app (not shown).

../_images/software-update-trigger.svg

Figure 11.9 Edge App Image Pull

../_images/software-update-install.svg

Figure 11.10 Edge App Install and Activate

11.7.3. Application Update

ADM conformant platforms and EMS MUST support application updates using the existing /9/x Software Management Object Instance and /9/x/6 Uninstall with argument 1 (ForUpdate).

When updating an installed edge application, the EMS SHALL use ForUpdate. The platform SHALL set /9/x/7 Update State to INITIAL and /9/x/9 Update Result to 0, and prepare to receive the replacement package as defined by the Software Management Object.

Application updates MUST preserve persistent files in /home/geisa. Non-persistent files are not retained when the application filesystem is reconstructed as part of the update.

If the operator does not wish to retain persistent application data when moving to a newer version, they may instead use /9/x/22 Purge Data via the EMS together with a normal /9/x/6 Uninstall and then perform a new application installation. Purge Data remains an independent operation and MAY also be used outside of an application replacement workflow. Note that Purge Data MUST be supported as part of GEISA conformance.

Executing /9/x/6 with no argument or argument 0 performs a normal uninstall rather than an application update.

After ForUpdate, the replacement package SHALL be transferred using /9/x/2 Package or /9/x/3 Package URI and follow the normal download, verification, and /9/x/4 Install sequence. After successful installation, the EMS MAY execute /9/x/10 Activate and, when application execution is desired, /9/x/19 Start.

The Software Management object Activation state machine defines the ability to use an app but does not address app execution state semantics:

  • When the current state is set to ACTIVE, the installed software can be used by the LwM2M Client.

  • When the current state is set to INACTIVE, the LwM2M Client MUST NOT use the installed software.

11.7.4. Application Execution State

Version 1.1 of the Software Management object adds resources for an EMS to control the Execution State of an edge application:

Resource ID

Operation

Data Type

Description

19

Execute

Start Application. Only available when Activation State = Enabled.

20

Execute

Stop Application. Only available when Activation State = Enabled.

21

Read

Integer

Execution Status. 0 = Stopped. 1 = Running.

11.7.5. Application Purge

Version 1.1 of the Software Management object adds an executable resource for an EMS to remotely purge local data from an instance of an edge application installation. Purge is independent of application update and uninstall operations and MAY also be used when an operator requires a clean application replacement without retaining persistent data:

Resource ID

Operation

Data Type

Description

22

Execute

Purge Data. Deletes existing local application data without modifying the app installation/activation states.

GEISA Pyramid