sohaib qamar
SWUpdate library to be used with RPC.
Fork of
SWUpdate
by 
David Smart
Diff: SWUpdate.h
- Revision:
- 10:78d727e8d0de
- Parent:
- 9:73067ef14c30
- Child:
- 11:4ef0309135e6
--- a/SWUpdate.h Sat Jun 21 19:13:30 2014 +0000
+++ b/SWUpdate.h Sat Jun 21 19:29:43 2014 +0000
@@ -1,13 +1,93 @@
/// Automatic Software Update via the network.
///
/// This library provides a reasonably simple interface to updating sofware
-/// semi-automatically via the network.
+/// 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.
+///
+/// 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 myprog_23.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 99 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 myprog_23.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.
+///
+/// Variations:
+///
+/// Within that single web server folder, you could have several apps -
+/// @li SensorNode.bin, SensorNode.txt
+/// @li SensorNode_B.bin, SensorNode_B.txt
+/// @li SensorDisplay.bin, SensorDisplay.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.
+///
+/// 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
///
#include "mbed.h"
-/** \file
-Software Update header file
-*/
#ifndef SWUPDATE_H
#define SWUPDATE_H
@@ -41,84 +121,15 @@
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.
+
+/// 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.
+/// 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.
///
/// @code
/// ...