Update Configurations

The update process is shown in the following figure:

To update an app you need only to install the app container which contains the new app version (without uninstalling the old app version). The update is detected automatically when:

An app is being installed, even though an app with the same app identifier is already installed on the controller at the install time point.
the app description file of the app container to be installed has an updateconfigs object with enabled "Auto Update" (see following section).
The version of the app being installed is greater than the installed app on the controller with the same app identifier.

The following applies on app update:

Supported configuration on app update:
- Keep/Delete temporary/persistent data folder of the app. The temporary/persistent data folders will exist only if the app is running. (See File-/Data-Storage).
Run a user specific linux shell script immediately after the update and before starting the app (if it the app was running on update).
If a post-update shell script is provided (see Necessary additions in the app description file), it will only be executed if the automatic update mode is present and the app was started (RUN-Mode) at the update time point.

Necessary additions in the app description file

If the optional JSON object "updateconfigs" is present in the app description file, the AppManager knows that configurations for updating the app are located in the app.

The "updateconfigs" entry is structured as follows:

"updateconfigs":{     
     "autoupdate_enabled": <true/false>,
     "keep_persistentdata": <true/false>,
     "keep_temporarydata" : <true/false>,
     "post_updatescript": "/sbin/post_script.sh"
 }

"autoupdate_enabled":

Allows the automatic update if its value is true, otherwise the update via installing the new version of app container can not take place (mandatory entry).

"keep_persistentdata":

Keep/Delete the persistent data storage folder of the app (optional entry. Default value is 'false').

"keep_temporarydata":

Keep/Delete the temporary data storage app folder of the app. (optional entry. Default value is 'false').

"post_updatescript":

Path to the post-update script in the app container, which will be executed immediately after the update (optional entry. Default string value is 'n/a'). When the update script is called, the following parameters are passed as command line arguments (with the sequence being maintained):

No.	Description
1	App identifier
2	Absolute path to the mounted app directory
3	Absolute path to the persistent data folder of the app
4	Absolute path to the temporary data folder of the app

Steps to create and integrate Update Configurations

Create the new version of your Update Configurations:

Update the app files in your app container.
If needed, integrate new app parts to the app and modify/extend the app description file.
Create a post-update script if needed (e.g. to convert persistent app data to a new data format)

Integrate Update Configurations to your app:

Add the optional app part "updateconfigs" with the needed configurations in your app description file. The auto update mode must be enabled.

Specifications and restrictions

On "normal" app install/uninstall the Update Configurations in the updateconfigs object entry will not be considered.
If an app is running on its update and this app requires a system reboot, the controller will automatically be rebooted after the app process is completed.

Demo App Updating

The Sample Linux Daemon App from section Demo Linux Daemon App will be updated from version 123.11.6.0 to version 123.11.6.9. The app description for the new Sample Linux App version is as follows:

{
        "plcnextapp": {
            "name": "Sample Linux Daemon App",
            "identifier": "60023450000002",
            "version": "123.11.6.9",
            "target": "AXC F 2152",
            "minfirmware_version": "19.9.0",
            "manufacturer": "PhoenixContact"    },
        "datastorage": {
            "persistentdata": true,
            "temporarydata" : false    },
        "linuxdaemons" :
        [
            {
              "path" : "/bin/SampleLinuxDaemon",
              "cmdargs" : "",
              "starttime": "99"        }
        ],
        "updateconfigs": {
            "autoupdate_enabled": true,
            "keep_persistentdata": true,
            "keep_temporarydata": false,
            "post_updatescript" : "/sbin/postupdate.sh"    }
}

The updateconfigs object contains following Update Configurations:

Auto update is enabled.
Persistent data folder will not be deleted on update.
Temporary data folder will be deleted on update (if it exists).
Following example post update script will be executed immediately after update (the app must run on update):

#!/bin/sh
    # Get script arguments
    APPIDENTIFIER="$1" 
    APPDIRECTORY="$2"APPDATADIRECTORY="$3"APPTEMPDIRECTORY="$4" 
    echo "App Identifier = $APPIDENTIFIER"echo "Persistent App data dir = $APPDATADIRECTORY"
    echo "Temporary App data dir  = $APPTEMPDIRECTORY"
    echo "App Directory = $APPDIRECTORY" 
    # Get current time stamp
    DATETIME=`date "+%Y%m%d-%H%M%S"`
    # Check if linux daemon output file exists
    LINUXDAEMON_OUTPUT="$APPDATADIRECTORY/linuxDaemonOut.log"
    echo "Linux Daemon output file path = $LINUXDAEMON_OUTPUT" if [ -e $LINUXDAEMON_OUTPUT ]
    then
       LOGFILECOPYPATH="$APPDATADIRECTORY/$DATETIME.copy.log"   
       echo "Log file copy path = $LOGFILECOPYPATH"   cp $LINUXDAEMON_OUTPUT $LOGFILECOPYPATH
    else   echo "Output log file not found!"fi

This sample update script copies on Update the log file linuxDaemonOut.log, which was generated by the previous Sample Linux Daemon App with version 123.11.6.0 and which was stored in the app persistent data folder, and names the archived log file with <Date Time Stamp>.copy.log.

Following steps are needed to test the update app e.g. via WBM - PLCnext Apps:

Install and start the Sample Linux Daemon App with the older version 123.11.6.0
Check the content of the app persistent data dir
Install the Sample Linux Daemon App with the new version 123.11.6.9
After updating the app:
- The Linux Daemon must run
- The daemon log file is copied in the app persistent data folder
- The daemon log file contains log data from new and old app versions

In the following sources for the demo Sample Linux Daemon Update App are available on GitHub HERE:

Update app container folder (Container_Update):
- App description file: app_info.json
- Demo linux daemon binary file (bin/SampleLinuxDaemon)
- Post update script (sbin/postupdate.sh)
Sources folder:
- Source file of the Linux Daemon: SampleLinuxDaemon.cpp
- Linux start script for the daemon created automatically using the template init script: SampleLinuxDaemon-60023450000002
Demo App container file: SampleLinuxDaemon.app

Support in the firmware

The Update Configurations app part type is supported in the firmware from version 20.0.0.