Diff: SWUpdate.h

Revision:

3:c69fff55fc60

Parent:

2:ef2ac9627546

Child:

4:1a3656ae80dc

--- a/SWUpdate.h	Sat Jun 14 16:15:30 2014 +0000
+++ b/SWUpdate.h	Sat Jun 14 18:18:28 2014 +0000
@@ -15,10 +15,46 @@
 /// will try to download it. If that succeeds, then it can
 /// optionally reboot to activate the new software.
 ///
-/// @todo check the freshly downloaded sw integrity. Since we have
-///     to remove the old .bin file before the new one will execute,
-///     it is in the device' best interest to ensure that new one
-///     is a good one.
+/// 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.
+///   @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")
+///
+///   @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).
+///   @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).
+///
+/// # Read current .txt file
+/// <<code>>
+/// 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 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
+/// $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;
+/// <</code>>
 ///
 /// @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.