Diff: SWUpdate.h

Revision:

9:73067ef14c30

Parent:

6:6025fddc1af9

Child:

10:78d727e8d0de

--- a/SWUpdate.h	Sun Jun 15 20:01:58 2014 +0000
+++ b/SWUpdate.h	Sat Jun 21 19:13:30 2014 +0000
@@ -1,4 +1,7 @@
-/// Firmware Over The Air (FOTA) Update.
+/// Automatic Software Update via the network.
+///
+/// This library provides a reasonably simple interface to updating sofware
+/// semi-automatically via the network.
 ///
 #include "mbed.h"
 
@@ -8,29 +11,82 @@
 #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;
 
-/// This API performs some processing to see if a web server
-/// has an updated version of software. If it does, then it
-/// will try to download it. If that succeeds, then it can
+/// 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.
 ///
-/// The files on the web server are as follows:
-///   @li myprog.bin - The actual binary file. The name is unimportant, but
-///             this is the binary file that was generated from the sources.
+/// 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 (ex: "21,41384,107996")
+///   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.
 ///
@@ -43,7 +99,7 @@
 /// $ver =~ s/(\d+),.*/$1/;
 /// print "Current Version is {$ver}\n";
 /// 
-/// # Read new .bin file
+/// # Read the [assumed new] .bin file
 /// open (FB, "<$bin") || die("Can't read $bin.");
 /// binmode FB;
 /// while (sysread(FB, $c, 1))
@@ -59,11 +115,28 @@
 /// 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 reboot determines whether to automatically reboot to activate the new bin.
+/// @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).
 ///
-bool SoftwareUpdate(const char *url, const char * name, Reboot_T reboot = DEFER_REBOOT);
+SWUpdate_T SoftwareUpdate(const char *url, const char * name, Reboot_T action = AUTO_REBOOT);
 
 #endif // SWUPDATE_H