Software Update via Ethernet - the mbed application can pull down an updated application binary from a web server and activate that binary. This library works only with the LPC1768, as it relies on the magic-chip boot-loader mechanism.

Dependents:   WattEye X10Svr PUB_SWUpdate

Embed: (wiki syntax)

« Back to documentation index

SWUpdate.h File Reference

SWUpdate.h File Reference

Automatic Software Update via the network. More...

Go to the source code of this file.

Enumerations

enum  Reboot_T { DEFER_REBOOT, AUTO_REBOOT }
 

After downloading, the user can choose what happens next.

More...
enum  SWUpdate_T {
  SWUP_OK = 0x00, SWUP_SAME_VER = 0x01, SWUP_HTTP_BIN = 0x02, SWUP_OLD_STUCK = 0x03,
  SWUP_VER_STUCK = 0x04, SWUP_VWRITE_FAILED = 0x05, SWUP_INTEGRITY_FAILED = 0x06, SWUP_HTTP_VER = 0x07,
  SWUP_NO_SPACE = 0x08, SWUP_NO_FILE = 0x09
}
 

Value return code from the SoftwareUpdate API.

More...

Functions

SWUpdate_T SoftwareUpdate (const char *url, const char *name, Reboot_T action=AUTO_REBOOT)
 To perform the software update, we simply give this API the web server URL that is hosting the embedded software.
HTTPResult SoftwareUpdateGetHTTPErrorCode (void)
 Get the HTTP transaction return code.
const char * SoftwareUpdateGetHTTPErrorMsg (SWUpdate_T r)
 Get the error message from a return code.
int GetSoftwareVersionNumber (const char *name)
 Get the installed software version number.

Detailed Description

Automatic Software Update via the network.

Supported Platforms: mbed LPC1768.

This library provides a reasonably simple interface to updating sofware semi-automatically via the network. It does that by querying a web server upon which you have placed an updated version of the embedded software application. Upon finding something there, it will determine if it is a different version than the one you current have installed and it will try to download the software. If that succeeds, then it can optionally reboot to activate the new software.

 +-----------+
 | Compiler  |
 +-----------+
      V                           +------------------+
 +-----------+                    |Web Server        |
 |myprog.bin |------------------->| /mbed/myprog.bin |
 +-----------+        +-----------|                  |
                      V           |                  |
                +-----------+     |                  |
                |perl script|---->| /mbed/myprog.txt |
                +-----------+     +------------------+
                                           A
 +---------------+                         #
 |mbed appliance |<====== network =========#======...
 +---------------+

     mbed                       server    
      |                           |
      +-- http Get(myprog.txt) -->|
      |<-- file(myprog.txt) ------+
      |                           |
      |---+                       |
      |  v58 newer than v57       |
      |<--+                       |
      |                           |
      +-- http Get(myprog.bin) -->|
      |<-- file(myprog.bin) ------+
      |<-- file(myprog.bin) ------+
      |<-- file(myprog.bin) ------+
      | (save as myprog58.bin)    |
      |                           |
      |---+                       |
      | integrity ck ok?          |
      |<--+                       |
      |                           |
      |---+                       |
      | unlink other .bin files   |
      | and reboot                |
      |<--+                       |
      |                           |

While the name shown in the examples here is "myprog", this is unimportant. Your application will have a name of your choosing, which you will use in the API.

Note:
Your binary file name should not exceed 6 characters. This leaves room for a 2-digit sequence number. Since this is using the local file system, it does not support long filenames when accessed from the mbed. So, SomeLongFile23.bin becomes somefi~1.bin and is then erased, leaving no file.
This was tested with firmware version 16457. Others may/not work. To check your version, open the mbed.htm file in a text editor, and look for "&firmware=16457&"

Local File System Files:

The files of interest on the local file system are as follows:

  • myprog58.bin - The actual application binary file that is currently executing. In this case, this is the 58th version that has been installed. You can go to 99 after which you might want to start over.
  • myprog.ver - A text file, maintained by this software update application, that was downloaded from the server with application version 58.

If "myprog.ver" does not exist, it will assume that the server has a newer application, so it will be downloaded and activated (even if all it does is to replace the existing myprog58.bin file).

Web Server Files:

The files on the web server are as follows.

  • myprog.bin - The latest version of the application binary file. Note that this file does not have any version number embedded into its filename as is the case on the local file system.
  • myprog.txt - A corresponding text file. The root name must match that of the binary file.

The myprog.txt file shall have 3 comma-separated numbers in it. version,checksum,filesize (e.g. "58,41384,107996").

  • version is a simple number. If the number is different than what is stored on the local file system, then the program will be updated (even if the server number is lower). This bidirectional "update" can let you downgrade.
  • checksum is the decimal representation of a simple 16-bit checksum.
  • filesize is the decimal representation of the size of the file.

Variations:

Within that single web server folder, you could have several apps -

  • Sensor.bin, Sensor.txt
  • SensrB.bin, SensrB.txt
  • SensrD.bin, SensrD.txt

In this example, perhaps your first version was called SensorNode, but with a small hardware design change, you have a new "model B" version. This example also assumes that you have a need to maintain two separate applications, one for each hardware version.

Creating the Version and Integrity Check data:

You can create the server "myprog.txt" file with this perl script (not every detail is shown, but it should be easy to figure out).

 # Read current .txt file
 open (FT, "<$txt") || die("Can't read $txt.");
 $ver = <FT>; chomp $ver; close FT;
 $ver =~ s/(\d+),.*/$1/;
 print "Current Version is {$ver}\n";
 
 # Read the [assumed new] .bin file
 open (FB, "<$bin") || die("Can't read $bin.");
 binmode FB;
 while (sysread(FB, $c, 1))
     {
     $cksum = ($cksum + ord($c)) & 0xFFFF;
     $byteCount++;
     }
 close FB;
 # Advance version number and write the new .txt file
 $ver++; print "$ver Checksum is $cksum over $byteCount bytes.\n";
 open (FT, ">$txt") || die("Can't write update to $txt.");
 printf(FT "%d,%d,%d\n", $ver, $cksum,$byteCount);
 close FT;

Definition in file SWUpdate.h.


Enumeration Type Documentation

enum Reboot_T

After downloading, the user can choose what happens next.

Enumerator:
DEFER_REBOOT 

Do not reboot to activate the new firmware.

AUTO_REBOOT 

Automatically reboot to activate the new firmware.

Definition at line 164 of file SWUpdate.h.

enum SWUpdate_T

Value return code from the SoftwareUpdate API.

Various things can go wrong in the software update process. The return value indicates the error.

Enumerator:
SWUP_OK 

Software Update succeeded as planned.

SWUP_SAME_VER 

Online version is the same as the installed version.

SWUP_HTTP_BIN 

HTTP get returned an error while trying to fetch the bin file.

SWUP_OLD_STUCK 

Old file could not be removed.

SWUP_VER_STUCK 

Old version number could not be updated.

SWUP_VWRITE_FAILED 

Can't open for write the version tracking file.

SWUP_INTEGRITY_FAILED 

Integrity check of downloaded file failed.

SWUP_HTTP_VER 

HTTP get returned an error while trying to fetch the version file.

SWUP_NO_SPACE 

No space on file system for new version.

SWUP_NO_FILE 

Specified file on the server does not exist.

Definition at line 174 of file SWUpdate.h.


Function Documentation

int GetSoftwareVersionNumber ( const char *  name )

Get the installed software version number.

If the installed version has a version number, retrieve that number and return it.

Parameters:
nameis the base filename of the binary file.
Returns:
the installed version number, or -1 if it cannot be identified.

Definition at line 171 of file SWUpdate.cpp.

SWUpdate_T SoftwareUpdate ( const char *  url,
const char *  name,
Reboot_T  action = AUTO_REBOOT 
)

To perform the software update, we simply give this API the web server URL that is hosting the embedded software.

We also give it the "root" name of the file of interest, which permits you to have different applications served from the same location.

Note that the root name can be a long filename, as is typically produced from the cloud-based build process. This name will be truncated to the first 6 characters when installed on the mbed local file system, in order to retain space for a 2-digit version number.

One optional parameter lets you decide what happens if a new version is installed - automatically reboot to launch it, or return to the calling program which may perform a more orderly reboot.

     ...
     if (NowIsTheTimeToCheckForSoftwareUpdates()) {
         if (SWUP_OK == SoftwareUpdate("http://192.168.1.200/path/to/file", "myprog_LPC1768", DEFER_REBOOT)) {
             printf("Software updated, rebooting now...\r\n");
             wait_ms(5000);
             mbed_reset();
         }
     }
     ...
Parameters:
[in]urlis a pointer to a text string of the url from which to download.
[in]nameis the base filename of the binary file.
[in]actiondetermines whether to automatically reboot to activate the new bin.
Returns:
SWUpdate_T code indicating if the update succeeded, otherwise it returns a bitmask of failure flags. Also, note that if it succeeded, and it was set for AUTO_REBOOT that it will not return from this function.

Definition at line 218 of file SWUpdate.cpp.

HTTPResult SoftwareUpdateGetHTTPErrorCode ( void   )

Get the HTTP transaction return code.

If something goes wrong with the communications with the server, SoftwareUpdate will respond with an SWUP_HTTP_VER or SWUP_HTTP_BIN return value. To learn more about what went wrong, this API will provide the actual return code from the HTTP transaction.

Returns:
HTTPResult code from the server transaction.

Definition at line 56 of file SWUpdate.cpp.

const char* SoftwareUpdateGetHTTPErrorMsg ( SWUpdate_T  r )

Get the error message from a return code.

Parameters:
[in]ris the result code to translate into a message
Returns:
a pointer to a text string of the message

Definition at line 48 of file SWUpdate.cpp.