sohaib qamar
SWUpdate library to be used with RPC.
Fork of
SWUpdate
by 
David Smart
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