sohaib qamar / SWUpdate_RPC

SWUpdate library to be used with RPC.

Fork of SWUpdate by David Smart

SWUpdate.h@13:cf76c2bd3dfc, 2014-06-21 (annotated)

Committer:
WiredHome
Date:
Sat Jun 21 19:39:27 2014 +0000
Revision:
13:cf76c2bd3dfc
Parent:
12:f1fdf8cabbc4
Child:
14:0e012d53c6df
Documentation is now up to date and believed accurate.

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