sohaib qamar / SWUpdate_RPC

SWUpdate library to be used with RPC.

Fork of SWUpdate by David Smart

SWUpdate.h@9:73067ef14c30, 2014-06-21 (annotated)

Committer:
WiredHome
Date:
Sat Jun 21 19:13:30 2014 +0000
Revision:
9:73067ef14c30
Parent:
6:6025fddc1af9
Child:
10:78d727e8d0de
Several updates to make it more robust and reliable, including removal of all other .bin files.

Who changed what in which revision?

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