Updater

Description

Updater is a piece of software that connects to a device management and provisioning server and downloads new FW version (and optionally upgrade instructions) from a predefined or given URL.

Then it applies sysupgrade with preserving the needed system state (user installed packages, modified files, etc) - as explained here: http://wiki.openwrt.org/doc/howto/generic.sysupgrade

To be more flexible this whole procedure is divided in two parts:

• Updater downloads update recipe from a distant server
• Updater checks MD5 integrity of this recipe
• Updater starts update recipe which finishes the update procedure

Update recipe is a script that does all the custom update. Benefits of having most of the update process in separate remote script is that this script can evolve and be changed and customized (as opposed to a lightweight Updater that is on the board somewhere deployed in the field).

Method of operation

1. Main user program receives a RPC (either over MQTT or WS) to initiate FW update

2. In a handler for this RPC, main user program calls Updater (from a provided on-board client library, in this case weioLib)

3. Updater checks config.weio for 2 things:

• Current version number
• URL of the update JSON metadata, which is similar to this:

[
   {
       "assets": [
           {
               "browser_download_url": "http://we-io.net/downloads/v1.1/weio.tar.gz", 
               "name": "weio.tar.gz", 
               "size": 3762
           }, 
           {
               "browser_download_url": "http://we-io.net/downloads/v1.1/weio_recovery.bin", 
               "name": "weio_recovery.bin", 
               "size": 13434884
           }
       ], 
       "body": ": WeIO is much more stable and a lot of new drivers has been added", 
       "name": "Attention. After downloading new version and starting install procedure please wait until 2 green LEDs stop to blink", 
       "tag_name": "v1.1" 
   }
]

4. Updater downloads update.json metadata:

• it reads from it LATEST release number and
• if this number is bigger than current release, Updater looks in the update.json metadata to see URL of the update recipe to use and downloads it

6. Updater starts recipe as a separate process (subprocess) and this recipe script finishes the update procedure:

• downloads sysupgrade image from internally hard-coded location (in the recipe)
• checks MD5 integrity
• creates backups if needed
• starts sysupgrade with correct parameters

Custom updater recipe in details

In most cases system upgrade is done in the following steps:

1. Download new FW (sysupgrade image) from some URL to RAM (i.e. /tmp)

2. Check the integrity of downloaded image by applying MD5 SUM

3. Preserve system files as explained here: http://wiki.openwrt.org/doc/howto/generic.sysupgrade or here: http://wiki.openwrt.org/doc/techref/sysupgrade, which would often consider:

   • running backup scripts
   • editing /etc/sysupgrade.conf
   • editing /lib/upgrade/keep.d (https://forum.openwrt.org/viewtopic.php?id=31050)
   • compressing to tar.gz to be used with sysupgrade -f
   • using of SAVE_OVERLAY env variable

4. Execute sysupgrade

Because this is a usual procedure, we can make this procedure default.

However, it might turn out that at some point we have to change update procedure even when having a number of boards already deployed in the filed.

This is where "custom update recipe" comes into play - i.e. we will trigger custom update procedure instead of default one.

This "custom updater procedure (or recipe)" is basically an executable, and can be any executable type - Bash script, Python script, C program, etc...

In order to execute this custom operation, Updater must download it first, and we must provide it URL where to download it from (for WeIO this URL is contained in update.json metadata).

So, since this is a piece of binary code, Updater treats it like any other binary image:

• Goes to URL and fetches custom_update_recipe binary
• Verifies integrity with MD5 SUM
• Executes custom_update_recipe binary (for example by forking it in a separate shel process)

URL of the sysimage

We can say that there is one default location of sysupgrade image - URL on soe pre-defined server which will hold the LATEST version of sysimage.

However, since sysimage location can change - for example if:

• We change the server
• Version numbering format change - so LATEST or vX.Y does not mean what it meant before
• We decide explicitly for this upgrade not to download LATEST, but some other version (for example - we want to downgrade)

By default Updater will look for image in a pre-defined URL.

If custom URL is demanded, Updater will fetch the sysimage from this URL, and continue standard procedure (MD5, system files preservation, sysupgrade) never returning to Updater (moreover, it might decide to kill WeIO app in the beginning in order to liberate some RAM).