sohaib qamar / SWUpdate_RPC

SWUpdate library to be used with RPC.

Fork of SWUpdate by David Smart

SWUpdate.h@20:cf73b0d75bb7, 2015-01-19 (annotated)

Committer:
WiredHome
Date:
Mon Jan 19 14:23:39 2015 +0000
Revision:
20:cf73b0d75bb7
Parent:
19:169aab9047bd
Child:
24:e400edb8d2ee
Documentation changes only to detail supported platform, and operating behavior.

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 20:cf73b0d75bb7 4 /// Supported Platforms: mbed LPC1768.
WiredHome 20:cf73b0d75bb7 5 ///
WiredHome 9:73067ef14c30 6 /// This library provides a reasonably simple interface to updating sofware
WiredHome 10:78d727e8d0de 7 /// semi-automatically via the network. It does that by querying a web server
WiredHome 10:78d727e8d0de 8 /// upon which you have placed an updated version of the embedded software
WiredHome 10:78d727e8d0de 9 /// application. Upon finding something there, it will determine if it is
WiredHome 10:78d727e8d0de 10 /// a different version than the one you current have installed and it
WiredHome 10:78d727e8d0de 11 /// will try to download the software. If that succeeds, then it can
WiredHome 10:78d727e8d0de 12 /// optionally reboot to activate the new software.
WiredHome 10:78d727e8d0de 13 ///
WiredHome 20:cf73b0d75bb7 14 /// @code
WiredHome 20:cf73b0d75bb7 15 /// +-----------+
WiredHome 20:cf73b0d75bb7 16 /// | Compiler |
WiredHome 20:cf73b0d75bb7 17 /// +-----------+
WiredHome 20:cf73b0d75bb7 18 /// V +------------------+
WiredHome 20:cf73b0d75bb7 19 /// +-----------+ |Web Server |
WiredHome 20:cf73b0d75bb7 20 /// |myprog.bin |------------------->| /mbed/myprog.bin |
WiredHome 20:cf73b0d75bb7 21 /// +-----------+ +-----------| |
WiredHome 20:cf73b0d75bb7 22 /// V | |
WiredHome 20:cf73b0d75bb7 23 /// +-----------+ | |
WiredHome 20:cf73b0d75bb7 24 /// |perl script|---->| /mbed/myprog.txt |
WiredHome 20:cf73b0d75bb7 25 /// +-----------+ +------------------+
WiredHome 20:cf73b0d75bb7 26 /// A
WiredHome 20:cf73b0d75bb7 27 /// +---------------+ #
WiredHome 20:cf73b0d75bb7 28 /// |mbed appliance |<====== network =========#======...
WiredHome 20:cf73b0d75bb7 29 /// +---------------+
WiredHome 20:cf73b0d75bb7 30 ///
WiredHome 20:cf73b0d75bb7 31 /// mbed server
WiredHome 20:cf73b0d75bb7 32 /// | |
WiredHome 20:cf73b0d75bb7 33 /// +-- http Get(myprog.txt) -->|
WiredHome 20:cf73b0d75bb7 34 /// |<-- file(myprog.txt) ------+
WiredHome 20:cf73b0d75bb7 35 /// | |
WiredHome 20:cf73b0d75bb7 36 /// |---+ |
WiredHome 20:cf73b0d75bb7 37 /// | v58 newer than v57 |
WiredHome 20:cf73b0d75bb7 38 /// |<--+ |
WiredHome 20:cf73b0d75bb7 39 /// | |
WiredHome 20:cf73b0d75bb7 40 /// +-- http Get(myprog.bin) -->|
WiredHome 20:cf73b0d75bb7 41 /// |<-- file(myprog.bin) ------+
WiredHome 20:cf73b0d75bb7 42 /// |<-- file(myprog.bin) ------+
WiredHome 20:cf73b0d75bb7 43 /// |<-- file(myprog.bin) ------+
WiredHome 20:cf73b0d75bb7 44 /// | (save as myprog58.bin) |
WiredHome 20:cf73b0d75bb7 45 /// | |
WiredHome 20:cf73b0d75bb7 46 /// |---+ |
WiredHome 20:cf73b0d75bb7 47 /// | integrity ck ok? |
WiredHome 20:cf73b0d75bb7 48 /// |<--+ |
WiredHome 20:cf73b0d75bb7 49 /// | |
WiredHome 20:cf73b0d75bb7 50 /// |---+ |
WiredHome 20:cf73b0d75bb7 51 /// | unlink other .bin files |
WiredHome 20:cf73b0d75bb7 52 /// | and reboot |
WiredHome 20:cf73b0d75bb7 53 /// |<--+ |
WiredHome 20:cf73b0d75bb7 54 /// | |
WiredHome 20:cf73b0d75bb7 55 /// @endcode
WiredHome 20:cf73b0d75bb7 56 ///
WiredHome 10:78d727e8d0de 57 /// While the name shown in the examples here is "myprog", this is unimportant.
WiredHome 10:78d727e8d0de 58 /// Your application will have a name of your choosing, which you will
WiredHome 10:78d727e8d0de 59 /// use in the API.
WiredHome 10:78d727e8d0de 60 ///
WiredHome 14:0e012d53c6df 61 /// @note Your binary file name should not exceed 6 characters. This leaves
WiredHome 14:0e012d53c6df 62 /// room for a 2-digit sequence number. Since this is using the local
WiredHome 14:0e012d53c6df 63 /// file system, it does not support long filenames when accessed from
WiredHome 14:0e012d53c6df 64 /// the mbed. So, SomeLongFile23.bin becomes somefi~1.bin and is then
WiredHome 14:0e012d53c6df 65 /// erased, leaving no file.
WiredHome 14:0e012d53c6df 66 ///
WiredHome 15:49cc43dcbbf6 67 /// @note This was tested with firmware version 16457. Others may/not work.
WiredHome 15:49cc43dcbbf6 68 /// To check your version, open the mbed.htm file in a text editor,
WiredHome 15:49cc43dcbbf6 69 /// and look for "&firmware=16457&"
WiredHome 15:49cc43dcbbf6 70 ///
WiredHome 10:78d727e8d0de 71 /// Local File System Files:
WiredHome 10:78d727e8d0de 72 ///
WiredHome 10:78d727e8d0de 73 /// The files of interest on the local file system are as follows:
WiredHome 10:78d727e8d0de 74 ///
WiredHome 20:cf73b0d75bb7 75 /// @li myprog58.bin - The actual application binary file that is currently
WiredHome 20:cf73b0d75bb7 76 /// executing. In this case, this is the 58th version that
WiredHome 10:78d727e8d0de 77 /// has been installed. You can go to 99 after which you might
WiredHome 10:78d727e8d0de 78 /// want to start over.
WiredHome 10:78d727e8d0de 79 /// @li myprog.ver - A text file, maintained by this software update
WiredHome 10:78d727e8d0de 80 /// application, that was downloaded from the server with
WiredHome 20:cf73b0d75bb7 81 /// application version 58.
WiredHome 10:78d727e8d0de 82 ///
WiredHome 10:78d727e8d0de 83 /// If "myprog.ver" does not exist, it will assume that the server has a
WiredHome 10:78d727e8d0de 84 /// newer application, so it will be downloaded and activated (even if all
WiredHome 20:cf73b0d75bb7 85 /// it does is to replace the existing myprog58.bin file).
WiredHome 10:78d727e8d0de 86 ///
WiredHome 10:78d727e8d0de 87 /// Web Server Files:
WiredHome 10:78d727e8d0de 88 ///
WiredHome 10:78d727e8d0de 89 /// The files on the web server are as follows.
WiredHome 10:78d727e8d0de 90 ///
WiredHome 10:78d727e8d0de 91 /// @li myprog.bin - The latest version of the application binary file.
WiredHome 10:78d727e8d0de 92 /// Note that this file does not have any version number
WiredHome 10:78d727e8d0de 93 /// embedded into its filename as is the case on the local
WiredHome 10:78d727e8d0de 94 /// file system.
WiredHome 10:78d727e8d0de 95 /// @li myprog.txt - A corresponding text file. The root name must match
WiredHome 10:78d727e8d0de 96 /// that of the binary file.
WiredHome 10:78d727e8d0de 97 ///
WiredHome 10:78d727e8d0de 98 /// The myprog.txt file shall have 3 comma-separated numbers in it.
WiredHome 20:cf73b0d75bb7 99 /// version,checksum,filesize (e.g. "58,41384,107996").
WiredHome 10:78d727e8d0de 100 ///
WiredHome 10:78d727e8d0de 101 /// @li version is a simple number. If the number is different than
WiredHome 10:78d727e8d0de 102 /// what is stored on the local file system, then the program
WiredHome 10:78d727e8d0de 103 /// will be updated (even if the server number is lower).
WiredHome 10:78d727e8d0de 104 /// This bidirectional "update" can let you downgrade.
WiredHome 10:78d727e8d0de 105 /// @li checksum is the decimal representation of a simple 16-bit checksum.
WiredHome 10:78d727e8d0de 106 /// @li filesize is the decimal representation of the size of the file.
WiredHome 10:78d727e8d0de 107 ///
WiredHome 10:78d727e8d0de 108 /// Variations:
WiredHome 10:78d727e8d0de 109 ///
WiredHome 10:78d727e8d0de 110 /// Within that single web server folder, you could have several apps -
WiredHome 14:0e012d53c6df 111 /// @li Sensor.bin, Sensor.txt
WiredHome 14:0e012d53c6df 112 /// @li SensrB.bin, SensrB.txt
WiredHome 14:0e012d53c6df 113 /// @li SensrD.bin, SensrD.txt
WiredHome 10:78d727e8d0de 114 ///
WiredHome 10:78d727e8d0de 115 /// In this example, perhaps your first version was called SensorNode, but
WiredHome 10:78d727e8d0de 116 /// with a small hardware design change, you have a new "model B" version.
WiredHome 10:78d727e8d0de 117 /// This example also assumes that you have a need to maintain two separate
WiredHome 10:78d727e8d0de 118 /// applications, one for each hardware version.
WiredHome 10:78d727e8d0de 119 ///
WiredHome 13:cf76c2bd3dfc 120 /// Creating the Version and Integrity Check data:
WiredHome 13:cf76c2bd3dfc 121 ///
WiredHome 10:78d727e8d0de 122 /// You can create the server "myprog.txt" file with this perl script (not
WiredHome 10:78d727e8d0de 123 /// every detail is shown, but it should be easy to figure out).
WiredHome 10:78d727e8d0de 124 /// @code
WiredHome 10:78d727e8d0de 125 /// # Read current .txt file
WiredHome 10:78d727e8d0de 126 /// open (FT, "<$txt") || die("Can't read $txt.");
WiredHome 10:78d727e8d0de 127 /// $ver = <FT>; chomp $ver; close FT;
WiredHome 10:78d727e8d0de 128 /// $ver =~ s/(\d+),.*/$1/;
WiredHome 10:78d727e8d0de 129 /// print "Current Version is {$ver}\n";
WiredHome 10:78d727e8d0de 130 ///
WiredHome 10:78d727e8d0de 131 /// # Read the [assumed new] .bin file
WiredHome 10:78d727e8d0de 132 /// open (FB, "<$bin") || die("Can't read $bin.");
WiredHome 10:78d727e8d0de 133 /// binmode FB;
WiredHome 10:78d727e8d0de 134 /// while (sysread(FB, $c, 1))
WiredHome 10:78d727e8d0de 135 /// {
WiredHome 10:78d727e8d0de 136 /// $cksum = ($cksum + ord($c)) & 0xFFFF;
WiredHome 10:78d727e8d0de 137 /// $byteCount++;
WiredHome 10:78d727e8d0de 138 /// }
WiredHome 10:78d727e8d0de 139 /// close FB;
WiredHome 10:78d727e8d0de 140 /// # Advance version number and write the new .txt file
WiredHome 10:78d727e8d0de 141 /// $ver++; print "$ver Checksum is $cksum over $byteCount bytes.\n";
WiredHome 10:78d727e8d0de 142 /// open (FT, ">$txt") || die("Can't write update to $txt.");
WiredHome 10:78d727e8d0de 143 /// printf(FT "%d,%d,%d\n", $ver, $cksum,$byteCount);
WiredHome 10:78d727e8d0de 144 /// close FT;
WiredHome 10:78d727e8d0de 145 /// @endcode
WiredHome 4:1a3656ae80dc 146 ///
WiredHome 0:e221363f7942 147
WiredHome 0:e221363f7942 148 #ifndef SWUPDATE_H
WiredHome 0:e221363f7942 149 #define SWUPDATE_H
WiredHome 0:e221363f7942 150
WiredHome 17:1d318666246c 151 #include "mbed.h"
WiredHome 17:1d318666246c 152 #include "HTTPClient.h"
WiredHome 17:1d318666246c 153
WiredHome 9:73067ef14c30 154 // This defines the maximum string length for a fully qualified
WiredHome 9:73067ef14c30 155 // filename. Usually, this will be pretty short
WiredHome 16:de99e872fc9d 156 // (e.g. "/local/myprog.bin"), which should be 19 max with 8.3 filename.
WiredHome 16:de99e872fc9d 157 #define SW_MAX_FQFN 20
WiredHome 9:73067ef14c30 158
WiredHome 9:73067ef14c30 159 // This defines the maximum string length for the url, including
WiredHome 9:73067ef14c30 160 // the base filename of interest.
WiredHome 9:73067ef14c30 161 #define SW_MAX_URL 150
WiredHome 9:73067ef14c30 162
WiredHome 1:208de08b1a19 163 /// After downloading, the user can choose what happens next.
WiredHome 0:e221363f7942 164 typedef enum {
WiredHome 6:6025fddc1af9 165 DEFER_REBOOT, ///< Do not reboot to activate the new firmware.
WiredHome 6:6025fddc1af9 166 AUTO_REBOOT ///< Automatically reboot to activate the new firmware.
WiredHome 0:e221363f7942 167 } Reboot_T;
WiredHome 0:e221363f7942 168
WiredHome 9:73067ef14c30 169 /// Bit-Field return codes from the SoftwareUpdate API.
WiredHome 9:73067ef14c30 170 ///
WiredHome 9:73067ef14c30 171 /// Various things can go wrong in the software update process. The return
WiredHome 17:1d318666246c 172 /// value is a bit-field that flags the possibilities, although usually there
WiredHome 17:1d318666246c 173 /// will only be a single bit set.
WiredHome 17:1d318666246c 174 ///
WiredHome 9:73067ef14c30 175 typedef enum {
WiredHome 9:73067ef14c30 176 SWUP_OK = 0x00, ///< Software Update succeeded as planned.
WiredHome 9:73067ef14c30 177 SWUP_SAME_VER = 0x01, ///< Online version is the same as the installed version.
WiredHome 17:1d318666246c 178 SWUP_HTTP_BIN = 0x02, ///< HTTP get returned an error while trying to fetch the bin file.
WiredHome 17:1d318666246c 179 SWUP_OLD_STUCK = 0x04, ///< Old file could not be removed.
WiredHome 9:73067ef14c30 180 SWUP_VER_STUCK = 0x08, ///< Old version number could not be updated.
WiredHome 9:73067ef14c30 181 SWUP_VWRITE_FAILED = 0x10, ///< Can't open for write the version tracking file.
WiredHome 9:73067ef14c30 182 SWUP_INTEGRITY_FAILED = 0x20, ///< Integrity check of downloaded file failed.
WiredHome 17:1d318666246c 183 SWUP_HTTP_VER = 0x40, ///< HTTP get returned an error while trying to fetch the version file.
WiredHome 19:169aab9047bd 184 SWUP_NO_SPACE = 0x80, ///< No space on file system for new version.
WiredHome 9:73067ef14c30 185 } SWUpdate_T;
WiredHome 9:73067ef14c30 186
WiredHome 10:78d727e8d0de 187
WiredHome 10:78d727e8d0de 188 /// To perform the software update, we simply give this API the web
WiredHome 10:78d727e8d0de 189 /// server URL that is hosting the embedded software. We also give it
WiredHome 10:78d727e8d0de 190 /// the "root" name of the file of interest, which permits you to
WiredHome 10:78d727e8d0de 191 /// have different applications served from the same location.
WiredHome 16:de99e872fc9d 192 ///
WiredHome 16:de99e872fc9d 193 /// Note that the root name can be a long filename, as is typically
WiredHome 16:de99e872fc9d 194 /// produced from the cloud-based build process. This name will
WiredHome 16:de99e872fc9d 195 /// be truncated to the first 6 characters when installed on the
WiredHome 16:de99e872fc9d 196 /// mbed local file system, in order to retain space for a 2-digit
WiredHome 16:de99e872fc9d 197 /// version number.
WiredHome 16:de99e872fc9d 198 ///
WiredHome 10:78d727e8d0de 199 /// One optional parameter lets you decide what happens if a new
WiredHome 10:78d727e8d0de 200 /// version is installed - automatically reboot to launch it, or
WiredHome 10:78d727e8d0de 201 /// return to the calling program which may perform a more orderly
WiredHome 10:78d727e8d0de 202 /// reboot.
WiredHome 9:73067ef14c30 203 ///
WiredHome 9:73067ef14c30 204 /// @code
WiredHome 9:73067ef14c30 205 /// ...
WiredHome 9:73067ef14c30 206 /// if (NowIsTheTimeToCheckForSoftwareUpdates()) {
WiredHome 16:de99e872fc9d 207 /// if (SWUP_OK == SoftwareUpdate("http://192.168.1.200/path/to/file", "myprog_LPC1768", DEFER_REBOOT)) {
WiredHome 9:73067ef14c30 208 /// printf("Software updated, rebooting now...\r\n");
WiredHome 9:73067ef14c30 209 /// wait_ms(5000);
WiredHome 9:73067ef14c30 210 /// mbed_reset();
WiredHome 9:73067ef14c30 211 /// }
WiredHome 9:73067ef14c30 212 /// }
WiredHome 9:73067ef14c30 213 /// ...
WiredHome 9:73067ef14c30 214 /// @endcode
WiredHome 9:73067ef14c30 215 ///
WiredHome 18:5f7667d63a27 216 /// @param[in] url is a pointer to a text string of the url from which to download.
WiredHome 18:5f7667d63a27 217 /// @param[in] name is the base filename of the binary file.
WiredHome 18:5f7667d63a27 218 /// @param[in] action determines whether to automatically reboot to activate the new bin.
WiredHome 13:cf76c2bd3dfc 219 /// @return SWUpdate_T code indicating if the update succeeded, otherwise it returns a bitmask
WiredHome 13:cf76c2bd3dfc 220 /// of failure flags. Also, note that if it succeeded, and it was set for AUTO_REBOOT
WiredHome 13:cf76c2bd3dfc 221 /// that it will not return from this function.
WiredHome 1:208de08b1a19 222 ///
WiredHome 9:73067ef14c30 223 SWUpdate_T SoftwareUpdate(const char *url, const char * name, Reboot_T action = AUTO_REBOOT);
WiredHome 0:e221363f7942 224
WiredHome 17:1d318666246c 225 /// Get the HTTP transaction return code.
WiredHome 17:1d318666246c 226 ///
WiredHome 17:1d318666246c 227 /// If something goes wrong with the communications with the server, SoftwareUpdate will
WiredHome 17:1d318666246c 228 /// respond with an SWUP_HTTP_VER or SWUP_HTTP_BIN return value. To learn more about
WiredHome 17:1d318666246c 229 /// what went wrong, this API will provide the actual return code from the HTTP transaction.
WiredHome 17:1d318666246c 230 ///
WiredHome 17:1d318666246c 231 /// @returns @ref HTTPResult code from the server transaction.
WiredHome 17:1d318666246c 232 ///
WiredHome 17:1d318666246c 233 HTTPResult SoftwareUpdateGetHTTPErrorCode(void);
WiredHome 17:1d318666246c 234
WiredHome 17:1d318666246c 235
WiredHome 0:e221363f7942 236 #endif // SWUPDATE_H