David Smart / SWUpdate Featured

Software Update via Ethernet - the mbed application can pull down an updated application binary from a web server and activate that binary. This library works only with the LPC1768, as it relies on the magic-chip boot-loader mechanism.

Dependents:   WattEye X10Svr PUB_SWUpdate

Success!! With this library, a network connection, and a web server hosting a new binary image, you can update the mbed firmware over the air (FOTA) - well, at least via Ethernet so far.

As of March 2015, it has been tested with the following mbed official libraries:

And a custom derivation:

  • HTTPClient v33, v32, which includes a custom HTTPFile.

Part of the update process involves checking the integrity of the downloaded binary file, for both a checksum and the program (file) size. To create this additional information, a small perl script is used (the important part is only 20 lines of code). See the documentation in the header file.

After the new binary is successfully downloaded, the checksum and the size are evaluated and if correct, then the old binary file is removed (this is the only way to cause the new binary to activate).

The mbed can then be automatically reset to activate the new image, or this may be deferred in case there is some other process necessary for an orderly restart.

Details are in the SWUpdate header file, and PUB_SWUpdate is a publicly accessible demonstration program for this library.

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