From 9985a32914f16bea727769d73e288f9a3a4621fd Mon Sep 17 00:00:00 2001 From: "Earle F. Philhower, III" Date: Fri, 20 Dec 2019 09:22:10 -0800 Subject: [PATCH] Add documentation for compressed OTA, fix bug (#6924) * Add documentation for compressed OTA, fix bug Fixes #6923 Documents the user steps needed to do a compressed upload, and notes the 2-step process needed for deploying compressed uploads to the field for the first time. Fixes a bug in serial output formatting discovered by @AdrianEddy. Adds additional contributors for uzlib, per @pfalcon. * Update README for esptool.py, too --- README.md | 4 ++-- bootloaders/eboot/eboot.c | 4 ++-- bootloaders/eboot/eboot.elf | Bin 34856 -> 34820 bytes doc/ota_updates/readme.rst | 31 +++++++++++++++++++++++++++++-- 4 files changed, 33 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index da691966d..2b198c63b 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,7 @@ Arduino IDE is developed and maintained by the Arduino team. The IDE is licensed ESP8266 core includes an xtensa gcc toolchain, which is also under GPL. -Esptool written by Christian Klippel is licensed under GPLv2, currently maintained by Ivan Grokhotkov: https://github.com/igrr/esptool-ck. +Esptool.py was initially created by Fredrik Ahlberg (@themadinventor, @kongo), and is currently maintained by Angus Gratton (@projectgus) under GPL 2.0 license. Espressif SDK included in this build is under Espressif MIT License. @@ -124,7 +124,7 @@ ESP8266 core files are licensed under LGPL. [LittleFS](https://github.com/ARMmbed/littlefs) library written by ARM Limited and released under the [BSD 3-clause license](https://github.com/ARMmbed/littlefs/blob/master/LICENSE.md). -[uzlib](https://github.com/pfalcon/uzlib) library written and (c) 2014-2018 Paul Sokolovsky, licensed under the ZLib license (https://www.zlib.net/zlib_license.html). +[uzlib](https://github.com/pfalcon/uzlib) library written and (c) 2014-2018 Paul Sokolovsky, licensed under the ZLib license (https://www.zlib.net/zlib_license.html). uzlib is based on: tinf library by Joergen Ibsen (Deflate decompression); Deflate Static Huffman tree routines by Simon Tatham; LZ77 compressor by Paul Sokolovsky; with library integrated and maintained by Paul Sokolovsky. ### Other useful links ### diff --git a/bootloaders/eboot/eboot.c b/bootloaders/eboot/eboot.c index b9d655778..c7cf285c0 100644 --- a/bootloaders/eboot/eboot.c +++ b/bootloaders/eboot/eboot.c @@ -27,14 +27,14 @@ int print_version(const uint32_t flash_addr) if (SPIRead(flash_addr + APP_START_OFFSET + sizeof(image_header_t) + sizeof(section_header_t), &ver, sizeof(ver))) { return 1; } - char fmt[16]; + char fmt[7]; fmt[0] = 'v'; fmt[1] = '%'; fmt[2] = '0'; fmt[3] = '8'; fmt[4] = 'x'; fmt[5] = '\n'; - fmt[6] = '0'; + fmt[6] = 0; ets_printf((const char*) fmt, ver); return 0; } diff --git a/bootloaders/eboot/eboot.elf b/bootloaders/eboot/eboot.elf index 442ad15f542c9fd9fc810b683e6bed08a260e975..7ef036b4d7e9219dc4b5b617df91807ec0043f85 100755 GIT binary patch delta 7986 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 delta 7915 zcma)B3v^UPny$Lt2?=yU=K+C`^eayiLehEgh#{nrhd==B?qDFDkf>pR5d~BnCCLSW zfQkyI#1RMgM$}n#WLAtvXU>ccc;qa)VFewX@d2XFuz_(D1|JZT^nQQcdpjLx&Yn%q zf4{%}`s%N`e?4wh^|sy0bGwz@<^c_=BewWcgkQ z=e?5Xem)GPAS56u8D_}-2C6fOG(B20dXd2PV9Z*zB2a~QJB0t^@ecY z?CY%O6n7}>4Ta~Ap6~QEhOo2*vhDa5m7##&k1 zKPD#G5p3BFY3xj{Wi{-G3)mtiS z*UVmKU09YUzA3UDy&Cp*57yg!N5rZz?oqD}+7yr`TD-4`N5{%|-C zS=QA9zSZ4-O&3Z$!{5#Ud(BSKo_TF%BU08_JQ7Q+7}ji;vYF=t>90hb$}Hq3M7$%9 z_Y1G1nD>enM_E$uxAvN8$j^ZELtNrnhm%){qmCtfml)%8@-9)~EaWeW7H1mI5cfFq zc(!;7&!Bi4&;8;eaxaTa*MoeLc;1zl)Qt9|!xPoKA5*GFeC}Go4-20=3w5^Qnc987 zd!L0jimaTRIn5JRuDz3S#{h<|vgi7Y`xW$gZVn2+1xqG#oV#GJNgT=8{~$S@2YLB; z9#Hl)kLUi_OWdEe+r`FZh=+1KiKE%rEmjmRpu#2M^_;EzR^iKaq&#*}_kbcwJM!4L zTCpKF7tz?4TZlFt&7Fpr4CWr>Tf~cb6PDlq4|~lyc$$J(Qkk|k=6Kw&Eii5E%<-II zYcg#e%<-yW+hE#Mmis%{s__PnPlP)^i=Pp5@~840qCG#ovK{NuUC5$pRJ6=7*C?Mh zLN|86)@;}cO&e#99C0!~jn{~C`7T~3Mo#qMJ!&Uj!(+wHiJ8fX=+!q2w{bO$<)nz$ zCT6PH(PntgDTHA$s{JSqBj8brd=CY$2}wl0+@Nnjk{TFyGjq%^Y@McU9dpbvY)_cB zN|w72ws+Bj+#r<2SYdNR-%hgEdYbGkK}FadIgp%>$F0 zc&j)!`Eg90`-%(sE#1E^&Q>sk-uK>t88okS6=u*&rD-`+Fh?8+v@;(u{|Mdcnh8rH zEbdZRzJkRwTYObI4s$K0tbkXFlClYyakXW&e2v&wmhWi$-d?j7t;|BdpeGs2+lL_Y zH131GUwl@!98<2cd;+HC((;oT4L{gxx+OixOR{)?mr=nsa3^<)Yb$E`BVu>O_~buF zXnJOGhWK5Dljn<1Dl&PwxPs?BB5jJ3j}TL*xOlRtpYo-B(q(&%22Xr{96Gf4IE%8j^UuX&Zc_?2yl z{ESA}W(4qXjSz#=(k7ioKD{V!QM?#L&ijxRKN{I)hIY{u)7|e*Gqj+b7y9Gx2lw64h>2T^hMvDEWQ@at*he zT^ecR4312ndWPx9Y=y!~B5mL-WMrih~Nrjcs%-H8H?`-;z2M5iyUW71ZN@t%=JiafS?4Tunml`8e(DVcaMak)~u5$ zb@xb8Hb7#S3ZjQpa&2MAi>@OO=^tv(9MCum5}1t$MhH2uo{&u&$?X5i8dgU~%=I8Q zKor)_2&tgL)|=sDl)n~&C~pC5)m4IrA)_#If>~kbD0U%TBg0-uEM6oooUW1nbD7>K z)ATy4Ae^Zo!ZlJ45Iil_P&a@Y5Y?qrzn*`-j1JR8FVrSYkx@vSl?Qaze*;wg zB_kzv!}g@ij+CI|)>3?56*gTXY=EE+f`6B4h~Nd?N^n-UnvJ0Hu`tnF5T;1os}W|a zMh5L_^m4QTmVdOX9rc~8i@>F;(YfD(!C8P{0&*?v4z7`+Q-@vv`R64yNI-O&D?tsK zD#qrbQLU%B*9P6Db*0cgOK6ed9eKdxGu(8LEZ$38aGt_ zdI-8qd|u}ezh7Ldb|L*+okoy>y$co}f-K1J`ic8{$qf*^C)FDXOzzMkLfm7L5F|*K zej5o)u3S%488jllE6H^P{Zd^)V3O-1>xtP28h1mjSW2zX%Y_KyWqm<{B#4FGscNK< zKdftJSM{slI;3rdX?qc0wpSoj!CSyjAe_~m27FoB6`f5qqC^d<46yTL z2|q!-R73Rxs=cNW`tUf@7Br|cO!u>qTp&%6Ih~DW7s;mk2^LE=L=b=s_c#ldS_lnf zZ@NY*k+4uk+y#-oOWOPdLaI#!Pe6vdBkl%C2oRWrq23>I79?kTC3gjZ$u+(v)c+=# z0#58bk{$WxQVnFrl0a}jB$jzGrL!Yr!lWq7D?JbgpLjEP`;mM_n*0P8q`HFOI~9-N z?>0mZ5c!lOHxc~B;083(&gvNi-$gQhTqC^_dHJ&>HxhgdiN&|@PUg`*{vQ2L&M+j0 zeEw6rO)szM%>M+uud5#b$l!B(Yb6Ld&5GO4#B*{SCe7=?q_6X}0uX$ln;UnIE!g5^@JTLt); zu9{VvPN~pa$a+U+N5W4hw)4{DC%6Eioy#38LnHkXWQ0neC~V6#N_`*2FzcYx;aW)4 zGX4mX2X)iSfLC?(FyMr)nq^HQwU3y;g^*52bnF~&VrDtYpz?o$L@iuH+|sD*$VYgn ziZWRRc~Dqc6g4QCmt~4@-R>?StDoQ%9E>ou2wsI?FaGJh8fkx!spwO~ zJ2(p-heQP;56L13HJz|p&nECetZd_!4vn;0J)`ytrkfu+6(Fpax>qA?l6t8|c#G7_ zG{QAfFV_gyNxecN+$i-a8eyB%r)q@Tq+X&C?t!4a1pA~}EzwBXFB4vkP?LJ8MtDH# zWg6kLQZLsCUyyo*M);!COEkjQAyM%-jU=6WqjtA+I9?=8a-o;Q{coUst(PR2AhTBx zI3d`Hs*#0t0Qq5^N??)H03E^OAvTO=?8B#JuV=BINEvFu9@%|u&%_L~w)P?ZxM+Th zX{{iwfnZT5F!;zY$FAum>RsqWZi8dI@mN5vuI>UntgB|(PeJ@aI*)waeu|{pXSY$| z=b@i~h(mQLV%@R??1S85U0teJu&hcw3|A*~cLZNbwUM9~GJNeD;s%KOIfT~K$U9Jp z%MjE_kRZ1NA%axMa9>wJ7`Td!BgnuSx*niU7{CGQfn4JOKB^(V-FKyhmB1QYF+kmtsqHCsXd=-j;LEu~+HN;POgn{& z!bC!c0SXmu^bt!&vI{x|%H-1rXeETcKJ*#T?J8p@v3mXyavHK9QFtEmYZ^Dk-%S|c z`AD17!?crg+5}TC&=!_@fp(zO3$!JqUZ6c1^#bi{=$lPnOS6FzYvGML=D#4+G511f zWv5l!B$^e{B%y91p>86f;c4b?>F#U{DQX@obM*@U+BR@Z|E@CZAUM zY&Ue`v`J>PJw{qKMe%hHJU$-$yW*{Q+K3ZB3Q^}QMkx{3HXo&*U|K49fA{Q`vz+&K z7v8*D!3Eyl))lx*{;o9-x5$|*_wrrc-75neH^(DZy@Z?N->iB9H^+h1e%uHDa`jx? z1pj??J$`$cyJii)+8G!Qc=n3p?Zvpa9)NyAWOg`tiI~wr^{wq#g6HcUOWfvqK>jmv`A+kf7CTB8 zBHb^FR41;$7pcF9MWfGc&%!gIGY|b)foFke#PgWgj^{yfurn{_uMPNNS{&+35npxM zV;+L9PQiC%DJdI7?v7mi%CKlhUd*-k;MY)baYu^SwZqQa#FIPn@N2`-9eIj%yZCy? G*#8ClhwB{x diff --git a/doc/ota_updates/readme.rst b/doc/ota_updates/readme.rst index 4d717df59..aac3e5e5a 100644 --- a/doc/ota_updates/readme.rst +++ b/doc/ota_updates/readme.rst @@ -123,7 +123,7 @@ Compile the sketch normally and, once a `.bin` file is available, sign it using .. code:: bash - /tools/signing.py --mode sign --privatekey --bin --out + /tools/signing.py --mode sign --privatekey --bin --out Old And New Signature Formats ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -134,7 +134,34 @@ To create a legacy signature, call the signing script with --legacy: .. code:: bash - /tools/signing.py --mode sign --privatekey --bin --out --legacy + /tools/signing.py --mode sign --privatekey --bin --out --legacy + + +Compression +----------- + +The eboot bootloader incorporates a GZIP decompressor, built for very low code requirements. For applications, this optional decompression is completely transparent. For uploading compressed filesystems, the application must be built with `ATOMIC_FS_UPDATE` defined because, otherwise, eboot will not be involved in writing the filesystem. + +No changes to the application are required. The `Updater` class and `eboot` bootloader (which performs actual application overwriting on update) automatically search for the `gzip` header in the uploaded binary, and if found, handle it. + +Compress an application `.bin` file or filesystem package using any `gzip` available, at any desired compression level (`gzip -9` is recommended because it provides the maximum compression and uncompresses as fast as any other compressino level). For example: + +.. code:: bash + + gzip -9 sketch.bin # Maximum compression, output sketch.bin.gz + + +If signing is desired, sign the gzip compressed file *after* compression. + +.. code:: bash + + gzip -9 sketch.bin + /tools/signing.py --mode sign --privatekey --bin sketch.bin.gz --out sketch.bin.gz.signed + +Updating apps in the field to support compression +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you have applications deployed in the field and wish to update them to support compressed OTA uploads, you will need to first recompile the application, then _upload the uncompressed `.bin` file once_. Attempting to upload a `gzip` compressed binary to a legacy app will result in the Updater rejecting the upload as it does not understand the `gzip` format. After this initial upload, which will include the new bootloader and `Updater` class with compression support, compressed updates can then be used. Safety