sohaib qamar / SWUpdate_RPC

SWUpdate library to be used with RPC.

Fork of SWUpdate by David Smart

SWUpdate.h@14:0e012d53c6df, 2014-06-27 (annotated)

Committer:
WiredHome
Date:
Fri Jun 27 20:57:23 2014 +0000
Revision:
14:0e012d53c6df
Parent:
13:cf76c2bd3dfc
Child:
15:49cc43dcbbf6
bin file must be 8-chars total, so revised the example to have a shorter filename, and sequence number to be 2 digit, not 3.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
WiredHome 12:f1fdf8cabbc4 1 /// @file
WiredHome 12:f1fdf8cabbc4 2 /// Automatic Software Update via the network.
WiredHome 9:73067ef14c30 3 ///
WiredHome 9:73067ef14c30 4 /// This library provides a reasonably simple interface to updating sofware
WiredHome 10:78d727e8d0de 5 /// semi-automatically via the network. It does that by querying a web server
WiredHome 10:78d727e8d0de 6 /// upon which you have placed an updated version of the embedded software
WiredHome 10:78d727e8d0de 7 /// application. Upon finding something there, it will determine if it is
WiredHome 10:78d727e8d0de 8 /// a different version than the one you current have installed and it
WiredHome 10:78d727e8d0de 9 /// will try to download the software. If that succeeds, then it can
WiredHome 10:78d727e8d0de 10 /// optionally reboot to activate the new software.
WiredHome 10:78d727e8d0de 11 ///
WiredHome 10:78d727e8d0de 12 /// While the name shown in the examples here is "myprog", this is unimportant.
WiredHome 10:78d727e8d0de 13 /// Your application will have a name of your choosing, which you will
WiredHome 10:78d727e8d0de 14 /// use in the API.
WiredHome 10:78d727e8d0de 15 ///
WiredHome 14:0e012d53c6df 16 /// @note Your binary file name should not exceed 6 characters. This leaves
WiredHome 14:0e012d53c6df 17 /// room for a 2-digit sequence number. Since this is using the local
WiredHome 14:0e012d53c6df 18 /// file system, it does not support long filenames when accessed from
WiredHome 14:0e012d53c6df 19 /// the mbed. So, SomeLongFile23.bin becomes somefi~1.bin and is then
WiredHome 14:0e012d53c6df 20 /// erased, leaving no file.
WiredHome 14:0e012d53c6df 21 ///
WiredHome 10:78d727e8d0de 22 /// Local File System Files:
WiredHome 10:78d727e8d0de 23 ///
WiredHome 10:78d727e8d0de 24 /// The files of interest on the local file system are as follows:
WiredHome 10:78d727e8d0de 25 ///
WiredHome 14:0e012d53c6df 26 /// @li myprog23.bin - The actual application binary file that is currently
WiredHome 10:78d727e8d0de 27 /// executing. In this case, this is the 23rd version that
WiredHome 10:78d727e8d0de 28 /// has been installed. You can go to 99 after which you might
WiredHome 10:78d727e8d0de 29 /// want to start over.
WiredHome 10:78d727e8d0de 30 /// @li myprog.ver - A text file, maintained by this software update
WiredHome 10:78d727e8d0de 31 /// application, that was downloaded from the server with
WiredHome 10:78d727e8d0de 32 /// application version 23.
WiredHome 10:78d727e8d0de 33 ///
WiredHome 10:78d727e8d0de 34 /// If "myprog.ver" does not exist, it will assume that the server has a
WiredHome 10:78d727e8d0de 35 /// newer application, so it will be downloaded and activated (even if all
WiredHome 14:0e012d53c6df 36 /// it does is to replace the existing myprog23.bin file).
WiredHome 10:78d727e8d0de 37 ///
WiredHome 10:78d727e8d0de 38 /// Web Server Files:
WiredHome 10:78d727e8d0de 39 ///
WiredHome 10:78d727e8d0de 40 /// The files on the web server are as follows.
WiredHome 10:78d727e8d0de 41 ///
WiredHome 10:78d727e8d0de 42 /// @li myprog.bin - The latest version of the application binary file.
WiredHome 10:78d727e8d0de 43 /// Note that this file does not have any version number
WiredHome 10:78d727e8d0de 44 /// embedded into its filename as is the case on the local
WiredHome 10:78d727e8d0de 45 /// file system.
WiredHome 10:78d727e8d0de 46 /// @li myprog.txt - A corresponding text file. The root name must match
WiredHome 10:78d727e8d0de 47 /// that of the binary file.
WiredHome 10:78d727e8d0de 48 ///
WiredHome 10:78d727e8d0de 49 /// The myprog.txt file shall have 3 comma-separated numbers in it.
WiredHome 10:78d727e8d0de 50 /// version,checksum,filesize (e.g. "23,41384,107996").
WiredHome 10:78d727e8d0de 51 ///
WiredHome 10:78d727e8d0de 52 /// @li version is a simple number. If the number is different than
WiredHome 10:78d727e8d0de 53 /// what is stored on the local file system, then the program
WiredHome 10:78d727e8d0de 54 /// will be updated (even if the server number is lower).
WiredHome 10:78d727e8d0de 55 /// This bidirectional "update" can let you downgrade.
WiredHome 10:78d727e8d0de 56 /// @li checksum is the decimal representation of a simple 16-bit checksum.
WiredHome 10:78d727e8d0de 57 /// @li filesize is the decimal representation of the size of the file.
WiredHome 10:78d727e8d0de 58 ///
WiredHome 10:78d727e8d0de 59 /// Variations:
WiredHome 10:78d727e8d0de 60 ///
WiredHome 10:78d727e8d0de 61 /// Within that single web server folder, you could have several apps -
WiredHome 14:0e012d53c6df 62 /// @li Sensor.bin, Sensor.txt
WiredHome 14:0e012d53c6df 63 /// @li SensrB.bin, SensrB.txt
WiredHome 14:0e012d53c6df 64 /// @li SensrD.bin, SensrD.txt
WiredHome 10:78d727e8d0de 65 ///
WiredHome 10:78d727e8d0de 66 /// In this example, perhaps your first version was called SensorNode, but
WiredHome 10:78d727e8d0de 67 /// with a small hardware design change, you have a new "model B" version.
WiredHome 10:78d727e8d0de 68 /// This example also assumes that you have a need to maintain two separate
WiredHome 10:78d727e8d0de 69 /// applications, one for each hardware version.
WiredHome 10:78d727e8d0de 70 ///
WiredHome 13:cf76c2bd3dfc 71 /// Creating the Version and Integrity Check data:
WiredHome 13:cf76c2bd3dfc 72 ///
WiredHome 10:78d727e8d0de 73 /// You can create the server "myprog.txt" file with this perl script (not
WiredHome 10:78d727e8d0de 74 /// every detail is shown, but it should be easy to figure out).
WiredHome 10:78d727e8d0de 75 /// @code
WiredHome 10:78d727e8d0de 76 /// # Read current .txt file
WiredHome 10:78d727e8d0de 77 /// open (FT, "<$txt") || die("Can't read $txt.");
WiredHome 10:78d727e8d0de 78 /// $ver = <FT>; chomp $ver; close FT;
WiredHome 10:78d727e8d0de 79 /// $ver =~ s/(\d+),.*/$1/;
WiredHome 10:78d727e8d0de 80 /// print "Current Version is {$ver}\n";
WiredHome 10:78d727e8d0de 81 ///
WiredHome 10:78d727e8d0de 82 /// # Read the [assumed new] .bin file
WiredHome 10:78d727e8d0de 83 /// open (FB, "<$bin") || die("Can't read $bin.");
WiredHome 10:78d727e8d0de 84 /// binmode FB;
WiredHome 10:78d727e8d0de 85 /// while (sysread(FB, $c, 1))
WiredHome 10:78d727e8d0de 86 /// {
WiredHome 10:78d727e8d0de 87 /// $cksum = ($cksum + ord($c)) & 0xFFFF;
WiredHome 10:78d727e8d0de 88 /// $byteCount++;
WiredHome 10:78d727e8d0de 89 /// }
WiredHome 10:78d727e8d0de 90 /// close FB;
WiredHome 10:78d727e8d0de 91 /// # Advance version number and write the new .txt file
WiredHome 10:78d727e8d0de 92 /// $ver++; print "$ver Checksum is $cksum over $byteCount bytes.\n";
WiredHome 10:78d727e8d0de 93 /// open (FT, ">$txt") || die("Can't write update to $txt.");
WiredHome 10:78d727e8d0de 94 /// printf(FT "%d,%d,%d\n", $ver, $cksum,$byteCount);
WiredHome 10:78d727e8d0de 95 /// close FT;
WiredHome 10:78d727e8d0de 96 /// @endcode
WiredHome 4:1a3656ae80dc 97 ///
WiredHome 0:e221363f7942 98 #include "mbed.h"
WiredHome 0:e221363f7942 99
WiredHome 0:e221363f7942 100 #ifndef SWUPDATE_H
WiredHome 0:e221363f7942 101 #define SWUPDATE_H
WiredHome 0:e221363f7942 102
WiredHome 9:73067ef14c30 103 // This defines the maximum string length for a fully qualified
WiredHome 9:73067ef14c30 104 // filename. Usually, this will be pretty short
WiredHome 14:0e012d53c6df 105 // (e.g. "/local/myprog.bin"), but we want to be generous.
WiredHome 14:0e012d53c6df 106 #define SW_MAX_FQFN 30
WiredHome 9:73067ef14c30 107
WiredHome 9:73067ef14c30 108 // This defines the maximum string length for the url, including
WiredHome 9:73067ef14c30 109 // the base filename of interest.
WiredHome 9:73067ef14c30 110 #define SW_MAX_URL 150
WiredHome 9:73067ef14c30 111
WiredHome 1:208de08b1a19 112 /// After downloading, the user can choose what happens next.
WiredHome 0:e221363f7942 113 typedef enum {
WiredHome 6:6025fddc1af9 114 DEFER_REBOOT, ///< Do not reboot to activate the new firmware.
WiredHome 6:6025fddc1af9 115 AUTO_REBOOT ///< Automatically reboot to activate the new firmware.
WiredHome 0:e221363f7942 116 } Reboot_T;
WiredHome 0:e221363f7942 117
WiredHome 9:73067ef14c30 118 /// Bit-Field return codes from the SoftwareUpdate API.
WiredHome 9:73067ef14c30 119 ///
WiredHome 9:73067ef14c30 120 /// Various things can go wrong in the software update process. The return
WiredHome 9:73067ef14c30 121 /// value is a bit-field that flags the possibilities.
WiredHome 9:73067ef14c30 122 typedef enum {
WiredHome 9:73067ef14c30 123 SWUP_OK = 0x00, ///< Software Update succeeded as planned.
WiredHome 9:73067ef14c30 124 SWUP_SAME_VER = 0x01, ///< Online version is the same as the installed version.
WiredHome 9:73067ef14c30 125 SWUP_BAD_URL = 0x02, ///< Bad URL provided, File missing on server, etc.
WiredHome 9:73067ef14c30 126 SWUP_OLD_STUCK = 0x04, ///< Old file could not be removed,
WiredHome 9:73067ef14c30 127 SWUP_VER_STUCK = 0x08, ///< Old version number could not be updated.
WiredHome 9:73067ef14c30 128 SWUP_VWRITE_FAILED = 0x10, ///< Can't open for write the version tracking file.
WiredHome 9:73067ef14c30 129 SWUP_INTEGRITY_FAILED = 0x20, ///< Integrity check of downloaded file failed.
WiredHome 9:73067ef14c30 130 SWUP_HTTP_ERR = 0x40, ///< HTTP get returned an error
WiredHome 9:73067ef14c30 131 } SWUpdate_T;
WiredHome 9:73067ef14c30 132
WiredHome 10:78d727e8d0de 133
WiredHome 10:78d727e8d0de 134 /// To perform the software update, we simply give this API the web
WiredHome 10:78d727e8d0de 135 /// server URL that is hosting the embedded software. We also give it
WiredHome 10:78d727e8d0de 136 /// the "root" name of the file of interest, which permits you to
WiredHome 10:78d727e8d0de 137 /// have different applications served from the same location.
WiredHome 10:78d727e8d0de 138 /// One optional parameter lets you decide what happens if a new
WiredHome 10:78d727e8d0de 139 /// version is installed - automatically reboot to launch it, or
WiredHome 10:78d727e8d0de 140 /// return to the calling program which may perform a more orderly
WiredHome 10:78d727e8d0de 141 /// reboot.
WiredHome 9:73067ef14c30 142 ///
WiredHome 9:73067ef14c30 143 /// @code
WiredHome 9:73067ef14c30 144 /// ...
WiredHome 9:73067ef14c30 145 /// if (NowIsTheTimeToCheckForSoftwareUpdates()) {
WiredHome 9:73067ef14c30 146 /// if (SWUP_OK == SoftwareUpdate("http://192.168.1.200", "myprog", DEFER_REBOOT)) {
WiredHome 9:73067ef14c30 147 /// printf("Software updated, rebooting now...\r\n");
WiredHome 9:73067ef14c30 148 /// wait_ms(5000);
WiredHome 9:73067ef14c30 149 /// mbed_reset();
WiredHome 9:73067ef14c30 150 /// }
WiredHome 9:73067ef14c30 151 /// }
WiredHome 9:73067ef14c30 152 /// ...
WiredHome 9:73067ef14c30 153 /// @endcode
WiredHome 9:73067ef14c30 154 ///
WiredHome 1:208de08b1a19 155 /// @param url is a pointer to a text string of the url from which to download.
WiredHome 1:208de08b1a19 156 /// @param name is the base filename of the binary file.
WiredHome 9:73067ef14c30 157 /// @param action determines whether to automatically reboot to activate the new bin.
WiredHome 13:cf76c2bd3dfc 158 /// @return SWUpdate_T code indicating if the update succeeded, otherwise it returns a bitmask
WiredHome 13:cf76c2bd3dfc 159 /// of failure flags. Also, note that if it succeeded, and it was set for AUTO_REBOOT
WiredHome 13:cf76c2bd3dfc 160 /// that it will not return from this function.
WiredHome 1:208de08b1a19 161 ///
WiredHome 9:73067ef14c30 162 SWUpdate_T SoftwareUpdate(const char *url, const char * name, Reboot_T action = AUTO_REBOOT);
WiredHome 0:e221363f7942 163
WiredHome 0:e221363f7942 164 #endif // SWUPDATE_H