Skip to content

Create a Workflow Script

OTA Update Workflow is the core logic behind the OTA update.

You need to first define the software (OTA) update workflow logic in the form of a Workflow Definition Script. The script can be written as a Linux shell script or Python/Perl script or any scripting language of your choice.

The workflow script defines the various steps involved in the software update process and the order in which the steps need to be executed. The workflow script will also have a rollback on failure logic to rollback the device software to the original state (the previous working state), if the update fails.

Workflow Script Blueprint

An OTA update workflow script should have the following logic:

  1. Stop the app or service running in the device ( On failure, do what? - Undo the current action.)
  2. Back up the existing working app/version and working config files (On failure, do what? - Undo the previous actions)
  3. Download and install the new app binary to the app directory (On failure, do what? - Restore from the backup)
  4. Update the app configuration and settings, or download a new config file with the required settings. (On failure, do what? - Restore from the backup)
  5. Start the app or service (On failure, do what? - Restore from the backup)
  6. Verify if the app is up and running (On failure, do what? - Restore from the backup)
  7. Clean up the back up.
  8. Done. Exit.

Here is a very simple Workflow Script file written in Linux Shell script, using the above blueprint. Please feel free to modify the below shell script to adapt it for your application's OTA update workflow requirements.

$ cat update.sh

#!/bin/bash

#================================================
# MyApp Update Workflow Script - Example #1
#================================================

# stop the app running as systemd service
systemctl stop myapp

# backup the existing app
mv /usr/bin/myapp /usr/bin/myapp.bkup

# update the new binary
mv myapp /usr/bin/myapp

systemctl start myapp

# verify the app is working fine
service_name="myapp"
if systemctl --quiet is-active "$service_name"; then
  echo "$service_name is running."
  # update success
  # clean up the backup and exit
  rm -f /usr/bin/myapp.bkup
else
  echo "$service_name is not running."
  # update failed
  # restore from the backup
  mv /usr/bin/myapp.bkup /usr/bin/myapp
  # start the previous working version
  systemctl start myapp
fi
You should package the above workflow script (udpate.sh) along with your myapp binary and create a tar.gz file. You should then upload this tar.gz file as an artifact to the SocketXP Artifact Registry and deploy OTA updates to a fleet of remote devices using the artifact.

Here is a more sophisticated version of the workflow script above.

The script assumes that the artifact is uploaded to a third-party artifact registry such as AWS S3, GitHub Packages Registry or Docker Hub or any cloud based artifact storage.

$ cat update.sh

#!/bin/sh

#================================================
# MyApp Update Workflow Script - Example #2
#================================================

# On-failure (before the backup) just restore the service
invoke_restore() {
    systemctl start myapp
    systemctl status myapp
    exit 1
}
# On-failure clean up and restore from backup.
invoke_restore_backup() {
    systemctl stop myapp
    cp /usr/local/bin/myapp.bkup /usr/local/bin/myapp
    cp -R /var/lib/myapp.bkup /var/lib/myapp
    rm -rf /var/lib/myapp.bkup
    cp /etc/myapp/config.json.bkup /etc/myapp/config.json   
    systemctl start myapp
    systemctl status myapp
    exit 1
}

debug_error() {
    echo "$(date +"%Y-%m-%d %H:%M:%S.%N"): Error: $1"
}

debug_log() {
    echo "$(date +"%Y-%m-%d %H:%M:%S.%N"): $1"
}

# Workflow Begins.

# stop the service first
systemctl stop myapp

# backup the current working app 
cp /usr/local/bin/myapp /usr/local/bin/myapp.bkup
if [ $? -eq 0 ]; then
    debug_log "Binary copied."
else 
    debug_error "Binary backup failed."
    invoke_restore
fi

# backup the current config file
cp /etc/myapp/config.json /etc/myapp/config.json.bkup
if [ $? -eq 0 ]; then
    debug_log "Config copied."
else 
    debug_error "Config backup failed."
    invoke_restore
fi

# Download the new myapp file from your online storage such as AWS S3 Bucket
curl -O https://abcdefghxyz.amazonaws.com/v41/bin/myapp && chmod +wx myapp && sudo mv myapp /usr/local/bin
if [ $? -eq 0 ]; then
    debug_log "New binary downloaded."
else 
    debug_error "New binary download failed."
    invoke_restore_backup
fi

# Download a new myapp config.json file from your online storage such as AWS S3 Bucket
curl -O https://abcdefghxyz.amazonaws.com/v41/cfg/config.json && sudo mv config.json /etc/myapp/config.json
if [ $? -eq 0 ]; then
    debug_log "New config file downloaded."
else 
    debug_error "New config file download failed."
    invoke_restore_backup
fi

# Start the service again
systemctl start myapp

# Check the status of the service
STATUS="$(systemctl status myapp | grep 'Active: active (running)')"
if [ -z $STATUS ]; then
    debug_error "myapp service failed to run."
    invoke_restore_backup
else 
    debug_log "myapp service is running."
fi

# Clean up files
rm -f /usr/local/bin/myapp.bkup
rm -f /etc/myapp/config.json.bkup

Again, the above workflow script assumes that the artifact (your app binary, app package(RPM, DEB), or docker container) is stored in a third-party online registry such as AWS S3, GitHub Packages Registry or Docker Hub or any cloud based online registry.

Note:

If you are packaging the above workflow script along with your app binary, config file and creating a tar.gz file to upload it to the SocketXP Artifact Registry, you can skip the steps(shown below) that involve "curl download of the myapp binary file and the config.json file from the AWS S3 bucket" in the above workflow script.

You'll find your myapp binary and the config.json files(untarred and unzipped) in the same local directory as your workflow script.

However, make sure that you move the app binary and config files from the current directory to the appropriate destination folder in your device. For example: /usr/local/bin and /etc/myapp/ respectively.

# Download the new myapp file from your online storage such as AWS S3 Bucket
curl -O https://abcdefghxyz.amazonaws.com/v41/bin/myapp && chmod +wx myapp && sudo mv myapp /usr/local/bin
if [ $? -eq 0 ]; then
    debug_log "New binary downloaded."
else 
    debug_error "New binary download failed."
    invoke_restore_backup
fi

# Download a new myapp config.json file from your online storage such as AWS S3 Bucket
curl -O https://abcdefghxyz.amazonaws.com/v41/cfg/config.json && sudo mv config.json /etc/myapp/config.json
if [ $? -eq 0 ]; then
    debug_log "New config file downloaded."
else 
    debug_error "New config file download failed."
    invoke_restore_backup
fi

Please ensure the IoT devices are able to access the artifact via a public web URL, so that it can be downloaded by the workflow script when executed in the device during OTA update.

Cloud based online storages or registries usually provide a secure and unique random public URL to the artifact storage for this purpose.