11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino
Thisrepository Search

Pullrequests

Issues

Gist

esp8266 / Arduino
Code

Issues 319

Watch

Pullrequests 8

Wiki

Pulse

381

Unstar

Fork

802

Graphs

Arduino/doc/ota_updates/ota_updates.md

Branch:master

2,024

Findfile

Copypath

7daysago

rhergetfixdemoOTAphpscript
4contributors

 

Raw

Blame

History

title
OTAUpdate

TableofContents
Introduction
Security
Safety
BasicRequirements
ArduinoIDE
Requirements
ApplicationExample
ClassicOTA
ArduinoOTA
PasswordProtection
Troubleshooting
WebBrowser
Requirements
ImplementationOverview
ApplicationExample
HTTPServer
Requirements
Arduinocode
Simpleupdater
Advancedupdater
Serverrequesthandling
Simpleupdater
Advancedupdater
StreamInterface
Updaterclass

Introduction
OTA(OvertheAir)updateistheprocessofloadingthefirmwaretoESPmoduleusingWiFiconnectionratherthataserial
port.Suchfunctionalitybecameextremelyusefulincaseoflimitedornophysicalaccesstothemodule.

https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

1/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

OTAmaybedoneusing:
ArduinoIDE
WebBrowser
HTTPServer
ArduinoIDEoptionisintendedprimarilyforsoftwaredevelopmentphase.Thetwootheroptionswouldbemoreusefulafter
deployment,toprovidemodulewithapplicationupdatesmanuallywithawebbrowserorautomaticallyusingahttpserver.
Inanycasefirstfirmwareuploadhavetobedoneoveraserialport.IfOTAroutinesarecorrectlyimplementedinasketch,
thenallsubsequentuploadsmaybedoneovertheair.
ThereisnoimposedsecurityonOTAprocessfrombeinghacked.Itisuptodevelopertoensurethatupdatesareallowed
onlyfromlegitimate/trustedsource.Onceupdateiscomplete,modulerestartsandnewcodeisexecuted.Developershould
ensurethatapplicationrunningonmoduleisshutdownandrestartedinasafemanner.Chaptersbelowprovideadditional
informationregardingsecurityandsafetyofOTAprocess.

Security
Modulehastobeexposedwirelesslytogetitupdatedwithanewsketch.Thatposeschancesofmodulebeingviolently
hackedandloadedwithsomeothercode.Toreducelikelihoodofbeinghackedconsiderprotectingyouruploadswitha
password,selectingcertainOTAport,etc.
CheckfunctionalityprovidedwithArduinoOTAlibrarythatmayimprovesecurity:




Certainprotectionfunctionalityisalreadybuiltinanddonotrequireanyadditionalcodingbydeveloper.ArduinoOTAand
espota.pyuseDigestMD5toauthenticateupload.IntegrityoftransferreddataisverifiedonESPsideusingMD5checksum.
Makeyourownriskanalysisanddependingonapplicationdecidewhatlibraryfunctionstoimplement.Ifrequiredconsider
implementationofothermeansofprotectionfrombeinghacked,e.g.exposingmoduleforuploadsonlyaccordingtospecific
schedule,triggerOTAonlybeuserpressingdedicatedUpdatebutton,etc.

Safety
OTAprocesstakesESPsresourcesandbandwidthduringupload.Thenmoduleisrestartedandanewsketchexecuted.
Analyseandtesthowitaffectsfunctionalityofyourexistingandnewsketch.
IfESPisplacedinremotelocationandcontrollingsomeequipment,youshouldputadditionalattentionwhathappensif
operationofthisequipmentissuddenlyinterruptedbyupdateprocess.Thereforedecidehowtoputthisequipmentintosafe
statebeforestartingtheupdate.Forinstanceyourmodulemaybecontrollingagardenwateringsysteminasequence.Ifthis
sequenceisnotproperlyshutdownandawatervalveleftopen,yourgardenmaybefloodedifthisvalveisnotclosedafter
OTAisfinishedandmodulerestarts.
ThefollowingfunctionsareprovidedwithArduinoOTAlibraryandintendedtohandlefunctionalityofyourapplicationduring
specificstagesofOTAoronanOTAerror:






https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

2/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

BasicRequirements
Flashchipsizeneedsasizethatisabletoholdtheoldsketch(currentlyrunning)andthenewsketch(OTA)atthesame
time.KeepinmindthattheFilesystemandEEPROMforexampleneedsspacetoo(onetime)seeflashlayout.
 

canbeusedforcheckingthefreespaceforthenewsketch.
Foroverviewofmemorylayout,wherenewsketchisstoredandhowitiscopiedduringOTAprocessseeUpdateprocess
memoryview.
ThefollowingchaptersprovidemoredetailsandspecificmethodsofdoingOTA.

ArduinoIDE
UploadingmoduleswirelesslyfromArduinoIDEisintendedforthefollowingtypicalscenarios:
duringfirmwaredevelopmentasaquickeralternativetoloadingoveraserial
forupdatingsmallquantityofmodules
onlyifmodulesareavailableonthesamenetworkasthecomputerwithArduinoIDE

Requirements
TheESPandthecomputermustbeconnectedtothesamenetwork.

ApplicationExample
CurrentlytherearetwosoftwareconfigurationsthatsupportOTAupdates.
ClassicOTA:ArduinoIDE1.6.5and1.6.5947g39819f0(ofJuly23,2015)versionofESP8266boardsupportplatform
packagethatprovidesfirstOTAimplementation,yetwithoutsupportforArduinoOTAlibrary.Thisparticularconfiguration
soonwillbedepreciatedinfavorofnewimplementationdescribedbelow.
ArduinoOTA:ArduinoIDE1.6.7and2.0.0versionofplatformpackage.ArduinoIDE1.6.7isthefirstreleasethat
providessupportforArduinoOTAlibrary.
ForinformationhowtoinstallESP8266boardsupportinArduinoIDEpleasereferto
https://github.com/esp8266/Arduino#installingwithboardsmanager.Onceinstalled,itispossibletoswitchbetweenavailable
versionsofplatformpackageusingBoardsManager:

https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

3/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

InstructionsbelowdemonstratehowtoconfigurebothClassicOTAandArduinoOTAusingNodeMCU1.0(ESP12EModule)
board.Youcanuseotherboardsassumingthattheymeetrequirementsdescribedabove.

ClassicOTA
1.Beforeyoubegin,pleasemakesurethatyouhavethefollowinginstalled:
ArduinoIDE1.6.5and1.6.5947g39819f0versionofplatformpackage,
Python2.7(donotinstallPython3.5thatisnotsupported).
2.Nowpreparethesketchandconfigurationfortheuploadoveraserialport.
StartArduinoIDEandloadsketchDNS_SD_Arduino_OTA.inoavailableunderFile>Examples>ESP8266mDNS

Note:Thissketchisavailableonlyfor1.6.5947g39819f0(ofJuly23,2015)platformpackage.Itwasremovedin
#980fromGitHubrepository.
UpdateSSIDandpasswordinthesketchsothemodulecanjoinyourWiFinetwork

Configureuploadparametersasbelow(youmayneedtoadjustconfigurationifyouareusingadifferentmodule):

https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

4/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

3.Uploadthesketch(Ctrl+U).Oncedone,openSerialMonitor(Ctrl+Shift+M)andcheckifmodulehasjoinedyourWiFi
network.

4.Onlyifmoduleisconnectedtonetwork,afteracoupleofseconds,theesp8266otaportwillshowupinArduinoIDE:

5.NowgetreadyforyourfirstOTAuploadbychangingconfigurationsettingsasfollows:

https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

5/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

Note:IfyoudonotseeUploadUsing:OTAoptionavailableforNodeMCU1.0(ESP12EModule)board,please
uploadthelatestboards.txtfilefromGitHubrepository,replaceexistingfileandrestartArduinoIDE.
6.Ifyouhavesuccessfullycompletedalltheabovesteps,youcanupload(Ctrl+U)thesame(oranyother)sketchover
OTA:

Note:TobeabletouploadyoursketchoverandoveragainusingOTA,youneedtoembedOTAroutinesinside.Pleaseuse
DNS_SD_Arduino_OTA.inoasanexample.
IncaseofissuespleaserefertoinformationprovidedinsectionTroubleshooting.SuccessfulOTAprocesslookslikebelow
onserialterminal:







 











Note:SketchandfreememorysizesaswellasIPaddressesdependonyourparticulars/wandh/wconfiguration.

ArduinoOTA
1.Beforeyoubegin,pleasemakesurethatyouhavethefollowinginstalled:
ArduinoIDE1.6.7and2.0.0versionofplatformpackagefollowingtheprocessdescribedunder
https://github.com/esp8266/Arduino#installingwithboardsmanager
Python2.7(donotinstallPython3.5thatisnotsupported):
https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

6/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

Note:WindowsusersshouldselectAddpython.exetoPath(seebelowthisoptionisnotselectedbydefault).

2.Nowpreparethesketchandconfigurationfortheuploadoveraserialport.
StartArduinoIDEandloadsketchBasicOTA.inoavailableunderFile>Examples>ArduinoOTA

UpdateSSIDandpasswordinthesketchsothemodulecanjoinyourWiFinetwork

Configureuploadparametersasbelow(youmayneedtoadjustconfigurationifyouareusingadifferentmodule):

3.Uploadthesketch(Ctrl+U).Oncedone,openSerialMonitor(Ctrl+Shift+M)andcheckifmodulehasjoinedyourWiFi
network:
https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

7/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

4.Onlyifmoduleisconnectedtonetwork,afteracoupleofseconds,theesp8266otaportwillshowupinArduinoIDE:

Note:IfOTAportdoesnotshowup,trytoexitArduinoIDE,openitagainandcheckifportisthere.
5.NowgetreadyforyourfirstOTAuploadbyselectingtheOTAport:

Thereisnoneedtochangeor.
6.Ifyouhavesuccessfullycompletedalltheabovesteps,youcanupload(Ctrl+U)thesame(oranyother)sketchover
OTA:

https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

8/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

Note:TobeabletouploadyoursketchoverandoveragainusingOTA,youneedtoembedOTAroutinesinside.Pleaseuse
BasicOTA.inoasanexample.

PasswordProtection
ProtectingyourOTAuploadswithpasswordisreallystraightforward.Allyouneedtodo,istoincludethefollowingstatement
inyourcode:


Whereisasamplepasswordthatyoushouldreplacewithyourown.
Beforeimplementingitinyoursketch,itisagoodideatocheckhowitworksusingBasicOTA.inosketchavailableunderFile
>Examples>ArduinoOTA.Goahead,openBasicOTA.ino,uncommenttheabovestatementthatisalreadythere,and
uploadthesketch.Tomaketroubleshootingeasier,donotmodifyexamplesketchbesideswhatisabsolutelyrequired.Thisis
includingoriginalsimpleOTApassword.Thenattempttouploadsketchagain(usingOTA).Aftercompilationis
complete,onceuploadisabouttobegin,youshouldseepromptforpasswordasfollows:

Enterthepasswordanduploadshouldbeinitiatedasusualwiththeonlydifferencebeingmessage
visibleinuploadlog.
https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

9/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

Youwillnotbepromptedforareenteringthesamepasswordnexttime.ArduinoIDEwillrememberitforyou.Youwillsee
promptforpasswordonlyafterreopeningIDE,orifyouchangeitinyoursketch,uploadthesketchandthentrytouploadit
again.
Pleasenote,itispossibletorevealpasswordenteredpreviouslyinArduinoIDE,ifIDEhasnotbeenclosedsincelastupload.
ThiscanbedonebyenablingShowverboseoutputduring:uploadinFile>Preferencesandattemptingtouploadthe
module.

Thepictureaboveshowsthatthepasswordisvisibleinlogasitispassedtoespota.pyuploadscript.
Anotherexamplebelowshowssituationwhenpasswordischangedbetweenuploads.

Whenuploading,ArduinoIDEusedpreviouslyenteredpassword,sotheuploadfailedandthathasbeenclearlyreportedby
IDE.OnlythenIDEpromptedforanewpassword.Thatwasenteredcorrectlyandsecondattempttouploadhasbeen
https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

10/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

successful.

Troubleshooting
IfOTAupdatefails,firststepistocheckforerrormessagesthatmaybeshowninuploadwindowofArduinoIDE.Ifthisisnot
providinganyusefulhintstrytouploadagainwhilecheckingwhatisshownbyESPonserialport.SerialMonitorfromIDEwill
notbeusefulinthatcase.Whenattemptingtoopenit,youwilllikelyseethefollowing:

ThiswindowisforArduinoYnandnotyetimplementedforesp8266/Arduino.ItshowsupbecauseIDEisattemptingtoopen
SerialMonitorusingnetworkportyouhaveselectedforOTAupload.
Insteadyouneedanexternalserialmonitor.IfyouareaWindowsusercheckoutTermite.Thisishandy,slickandsimple
RS232terminalthatdoesnotimposeRTSorDTRflowcontrol.Suchflowcontrolmaycauseissuesifyouareusing
respectivelinestotoggleGPIO0andRESETpinsonESPforupload.
SelectCOMportandbaudrateonexternalterminalprogramasifyouwereusingArduinoSerialMonitor.Pleaseseetypical
settingsforTermitebelow:

ThenrunOTAfromIDEandlookwhatisdisplayedonterminal.SuccessfulArduinoOTAprocessusingBasicOTA.inosketch
lookslikebelow(IPaddressdependsonyournetworkconfiguration):

https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

11/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

Ifuploadfailsyouwilllikelyseeerrorscaughtbytheuploader,exceptionandthestackdump,orboth.
ThemostcommoncausesofOTAfailureareasfollows:
notenoughphysicalmemoryonthechip(e.g.ESP01with512KflashmemoryisnotenoughforOTA),
toomuchmemorydeclaredforSPIFFSsonewsketchwillnotfitbetweenexistingsketchandSPIFFSseeUpdate
processmemoryview,
toolittlememorydeclaredinArduinoIDEforyourselectedboard(i.e.lessthanphysicalsize).
FormoredetailsregardingflashmemorylayoutpleasecheckFilesystem.Foroverviewwherenewsketchisstored,howitis
copiedandhowmemoryisorganizedforthepurposeofOTAseeUpdateprocessmemoryview.

WebBrowser
Updatesdescribedinthischapteraredonewithawebbrowserthatcanbeusefulinthefollowingtypicalscenarios:
afterapplicationdeploymentifloadingdirectlyfromArduinoIDEisinconvenientornotpossible
afterdeploymentifuserisunabletoexposemoduleforOTAfromexternalupdateserver
toprovideupdatesafterdeploymenttosmallquantityofmoduleswhensettinganupdateserverisnotpracticable

Requirements
TheESPandthecomputermustbeconnectedtothesamenetwork.

ImplementationOverview
Updateswithawebbrowserareimplementedusingclasstogetherwithand
classes.Thefollowingcodeisrequiredtogetitwork:

setup()





https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

12/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

loop()


ApplicationExample
Thesampleimplementationprovidedbelowhasbeendoneusing:
examplesketchWebUpdater.inoavailableinlibrary
NodeMCU1.0(ESP12EModule)
Youcanuseanothermoduleifitmeetspreviouslydesribedrequirements.
1.Beforeyoubegin,pleasemakesurethatyouhavethefollowingsoftwareinstalled:
ArduinoIDEand2.0.0rc1(ofNov17,2015)versionofplatformpackageasdescribedunder
https://github.com/esp8266/Arduino#installingwithboardsmanager
HostsoftwaredependingonO/Syouuse:
a.Avahihttp://avahi.org/forLinux
b.Bonjourhttp://www.apple.com/support/bonjour/forWindows
c.MacOSXandiOSsupportisalreadybuiltin/noanyextras/wisrequired
2.Preparethesketchandconfigurationforinitialuploadwithaserialport.
StartArduinoIDEandloadsketchWebUpdater.inoavailableunderFile>Examples>ESP8266HTTPUpdateServer.
UpdateSSIDandpasswordinthesketchsothemodulecanjoinyourWiFinetwork.
OpenFile>Preferences,lookforShowverboseoutputduring:andcheckoutcompilationoption.

Note:Thissettingwillberequiredinstep5below.Youcanuncheckthissettingafterwards.
3.Uploadsketch(Ctrl+U).OncedoneopenSerialMonitor(Ctrl+Shift+M)andcheckifyouseethefollowingmessage
displayed,thatcontainsurlforOTAupdate.

Note:SuchmessagewillbeshownonlyaftermodulesuccessfullyjoinsnetworkandisreadyforanOTAupload.
4.NowopenwebbrowserandentertheurlprovidedonSerialMonitor,i.e.http://esp8266webupdate.local/update.Once
entered,browsershoulddisplayaformlikebelowthathasbeenservedbyyourmodule.Theforminvitesyoutochoose
afileforupdate.

https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

13/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

Note:Ifenteringdoesnotwork,tryreplacingwithmodules
IPaddress.Forexample,ifyourmoduleIPisthenurlshouldbe.This
workaroundisusefulincasethehostsoftwareinstalledinstep2doesnotwork.Ifstillnothingworksandthereareno
cluesonSerialMonitor,trytodiagnoseissuebyopeningprovidedurlinGoogleChrome,pressingF12andchecking
contentsofConsoleandNetworktabs.Chromeprovidessomeadvancedloggingonthesetabs.
5.ToobtainthefilenavigatetodirectoryusedbyArduinoIDEtostoreresultsofcompilation.Youcancheckthepathtothis
fileincompilationlogshowninIDEdebugwindowasmarkedbelow.

6.NowpressChooseFileinwebbrowser,gotodirectoryidentifiedinstep5above,findthefileWebUpdater.cpp.bin
anduploadit.IfuploadissuccessfulyouwillseeOKonwebbrowserlikebelow.

ModulewillrebootthatshouldbevisibleonSerialMonitor:

https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

14/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

Justafterrebootyoushouldseeexactlythesamemessage
likeinstep3.Thisisbecausemodulehasbeenloadedagainwiththesame

codefirstusingserialport,andthenusingOTA.
OnceyouarecomfortablewiththisproceduregoaheadandmodifyWebUpdater.inosketchtoprintsomeadditional
messages,compileit,locatenewbinaryfileanduploaditusingwebbrowsertoseeenteredchangesonaSerialMonitor.
YoucanalsoaddOTAroutinestoyourownsketchfollowingguidelinesinImplementationOverviewabove.Ifthisisdone
correctlyyoushouldbealwaysabletouploadnewsketchoverthepreviousoneusingawebbrowser.
IncaseOTAupdatefailsdeadafterenteringmodificationsinyoursketch,youcanalwaysrecovermodulebyloadingitovera
serialport.ThendiagnosetheissuewithsketchusingSerialMonitor.OncetheissueisfixedtryOTAagain.

HTTPServer
classcancheckforupdatesanddownloadabinaryfilefromHTTPwebserver.Itispossibletodownload

updatesfromeveryIPordomainaddressonthenetworkorInternet.

Requirements
webserver

Arduinocode
Simpleupdater
Simpleupdaterdownloadsthefileeverytimethefunctioniscalled.


Advancedupdater
Itspossibletopointupdatefunctiontoascriptattheserver.Ifversionstringargumentisgiven,itwillbesenttotheserver.
Serversidescriptcanusethistocheckifupdateshouldbeperformed.
Serversidescriptcanrespondasfollows:
responsecode200,andsendthefirmwareimage,
orresponsecode304tonotifyESPthatnoupdateisrequired.


 









Serverrequesthandling
Simpleupdater
https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

15/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

Forthesimpleupdatertheserveronlyneedstodeliverthebinaryfileforupdate.
Advancedupdater
Foradvancedupdatemanagementascriptneedstorunattheserverside,forexampleaPHPscript.Ateveryupdate
requesttheESPsendssomeinformationinHTTPheaderstotheserver.
Exampleheaderdata:


 
 
 





Withthisinformationthescriptnowcancheckifanupdateisneeded.Itisalsopossibletodeliverdifferentbinariesbasedon
theMACaddressforexample.
Scriptexample:











 









 






 





 


https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

16/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino



 
 



 







StreamInterface
TODOdescribeStreamInterface
TheStreamInterfaceisthebaseforallotherupdatemodeslikeOTA,httpServer/client.

Updaterclass
UpdaterisintheCoreanddealswithwritingthefirmwaretotheflash,checkingitsintegrityandtellingthebootloadertoload
thenewfirmwareonthenextboot.

Updateprocessmemoryview
Thenewsketchwillbestoredinthespacebetweentheoldsketchandthespiff.
onthenextrebootthe"eboot"bootloadercheckforcommands.
thenewsketchisnowcopied"over"theoldone.
thenewsketchisstarted.

https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

17/18

11/2/2016

Arduino/ota_updates.mdatmasteresp8266/Arduino

2016GitHub,Inc. Terms Privacy Security Contact Help

https://github.com/esp8266/Arduino/blob/master/doc/ota_updates/ota_updates.md

Status API Training Shop Blog About Pricing

18/18