sohaib qamar / SWUpdate_RPC

SWUpdate library to be used with RPC.

Fork of SWUpdate by David Smart

SWUpdate.h@18:5f7667d63a27, 2014-10-11 (annotated)

Committer:
WiredHome
Date:
Sat Oct 11 17:27:46 2014 +0000
Revision:
18:5f7667d63a27
Parent:
17:1d318666246c
Child:
19:169aab9047bd
Documentation updates only.

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