File content as of revision 9:73067ef14c30:

/// Automatic Software Update via the network.
///
/// This library provides a reasonably simple interface to updating sofware
/// semi-automatically via the network.
///
#include "mbed.h"

/** \file
Software Update header file
*/
#ifndef SWUPDATE_H
#define SWUPDATE_H

// This defines the maximum string length for a fully qualified
// filename. Usually, this will be pretty short 
// (e.g. "/local/myprogramname.bin"), but we want to be generous.
#define SW_MAX_FQFN 80

// This defines the maximum string length for the url, including
// the base filename of interest.
#define SW_MAX_URL 150

/// After downloading, the user can choose what happens next.
typedef enum {
    DEFER_REBOOT,   ///< Do not reboot to activate the new firmware.
    AUTO_REBOOT     ///< Automatically reboot to activate the new firmware.
} Reboot_T;

/// Bit-Field return codes from the SoftwareUpdate API.
///
/// Various things can go wrong in the software update process. The return
/// value is a bit-field that flags the possibilities.
typedef enum {
    SWUP_OK               = 0x00,   ///< Software Update succeeded as planned.
    SWUP_SAME_VER         = 0x01,   ///< Online version is the same as the installed version.
    SWUP_BAD_URL          = 0x02,   ///< Bad URL provided, File missing on server, etc.
    SWUP_OLD_STUCK        = 0x04,   ///< Old file could not be removed,
    SWUP_VER_STUCK        = 0x08,   ///< Old version number could not be updated.
    SWUP_VWRITE_FAILED    = 0x10,   ///< Can't open for write the version tracking file.
    SWUP_INTEGRITY_FAILED = 0x20,   ///< Integrity check of downloaded file failed.
    SWUP_HTTP_ERR         = 0x40,   ///< HTTP get returned an error
} SWUpdate_T;

/// This library provides a reasonably simple interface to updating sofware
/// semi-automatically via a network connection.
/// 
/// This API performs some processing to see if a web server has an updated 
/// version of the embedded software application. If it does, then it
/// will try to download the updated software. If that succeeds, then it can
/// optionally reboot to activate the new software.
///
/// 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.
///
/// Local File System Files:
///
/// The files of interest on the local file system are as follows:
///
///   @li myprog023.bin - The actual application binary file that is currently
///             executing. In this case, this is the 23rd version that
///             has been installed. You can go to 999 after which you might
///             want to start over.
///   @li myprog.ver - A text file, maintained by this software update
///             application, that was downloaded from the server with
///             application version 23. 
///
/// 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 myprog023.bin file).
///
/// Web Server Files:
///
/// The files on the web server are as follows. 
///
///   @li 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.
///   @li 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. "23,41384,107996").
///
///   @li 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.
///   @li checksum is the decimal representation of a simple 16-bit checksum.
///   @li filesize is the decimal representation of the size of the file.
///
/// 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).
/// @code
/// # 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;
/// @endcode
///
/// Now, for this actual API, we simply give it the web server URL that
/// is hosting the embedded software. We also give it the "root" name
/// of the file of interest. The additional optional parameter lets
/// you decide what happens if a new version is installed.
///
/// @code
///     ...
///     if (NowIsTheTimeToCheckForSoftwareUpdates()) {
///         if (SWUP_OK == SoftwareUpdate("http://192.168.1.200", "myprog", DEFER_REBOOT)) {
///             printf("Software updated, rebooting now...\r\n");
///             wait_ms(5000);
///             mbed_reset();
///         }
///     }
///     ...
/// @endcode
///
/// @param url is a pointer to a text string of the url from which to download.
/// @param name is the base filename of the binary file.
/// @param action determines whether to automatically reboot to activate the new bin.
/// @return true if the update succeeded (and the reboot was set to DEFER_REBOOT).
///
SWUpdate_T SoftwareUpdate(const char *url, const char * name, Reboot_T action = AUTO_REBOOT);

#endif // SWUPDATE_H