ESP8266 Arduino Core Documentation

79 Pages·2017·3.26 MB·English

ESP8266 Arduino Core Documentation
Release 2.4.0
Ivan Grokhotkov
May 14, 2017

Contents:
1 Installing 1
1.1 BoardsManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Usinggitversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2 Reference 5
2.1 DigitalIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Analoginput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.3 Analogoutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4 Timinganddelays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.5 Serial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.6 Progmem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3 Libraries 9
3.1 WiFi(ESP8266WiFilibrary) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2 Ticker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3 EEPROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.4 I2C(Wirelibrary) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.5 SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.6 SoftwareSerial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.7 ESP-specificAPIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.8 mDNSandDNS-SDresponder(ESP8266mDNSlibrary). . . . . . . . . . . . . . . . . . . . . . . . 11
3.9 SSDPresponder(ESP8266SSDP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.10 DNSserver(DNSServerlibrary). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.11 Servo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.12 Otherlibraries(notincludedwiththeIDE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4 Filesystem 15
4.1 Flashlayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.2 Filesystemlimitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.3 Uploadingfilestofilesystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.4 Filesystemobject(SPIFFS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.5 Filesysteminformationstructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.6 Directoryobject(Dir) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.7 Fileobject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5 ESP8266WiFilibrary 21
5.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
i
5.2 ClassDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.3 Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.4 What’sInside? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
6 OTAUpdates 33
6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.2 ArduinoIDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.3 WebBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
6.4 HTTPServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
6.5 StreamInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.6 Updaterclass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
7 Boards 49
7.1 AdafruitHUZZAHESP8266(ESP-12) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.2 ESPressoLite1.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.3 ESPressoLite2.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.4 Phoenix1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.5 Phoenix2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.6 NodeMCU0.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.7 NodeMCU1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.8 OlimexMOD-WIFI-ESP8266-DEV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.9 OlimexMOD-WIFI-ESP8266 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.10 OlimexESP8266-EVB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.11 SparkFunESP8266Thing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.12 SweetPeaESP-210 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.13 ESPino . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.14 WifInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
7.15 GenericESP8266modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
7.16 SerialAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
7.17 MinimalHardwareSetupforBootloadingandUsage . . . . . . . . . . . . . . . . . . . . . . . . . . 53
7.18 ESPtoSerial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
7.19 Minimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
7.20 ImprovedStability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
7.21 BootMessagesandModes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
7.22 GenericESP8285modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
7.23 WeMosD1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
7.24 WeMosD1mini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
7.25 ESPino(WROOM-02Module)byThaiEasyElec . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
7.26 gen4-IoDRangeby4DSystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
8 FAQ 59
8.1 Iamgetting“espcomm_syncfailed”errorwhentryingtouploadmyESP.Howtoresolvethisissue? 59
8.2 Whyesptoolisnotlistedin“Programmer”menu? HowdoIuploadESPwithoutit? . . . . . . . . . 59
8.3 MyESPcrashesrunningsomecode. Howtotroubleshootit? . . . . . . . . . . . . . . . . . . . . . 59
8.4 ThisArduinolibrarydoesn’tworkonESP.HowdoImakeitworking? . . . . . . . . . . . . . . . . 60
8.5 IntheIDE,forESP-12Ethathas4Mflash,Icanchoose4M(1MSPIFFS)or4M(3MSPIFFS).No
matterwhatIselect,theIDEtellsmethemaximumcodespaceisabout1M.Wheredoesmyflashgo? 60
8.6 IhaveobservedacasewhenESP.restart()doesn’twork. Whatisthereasonforthat? . . . . . . . . . 60
8.7 Howtoresolve“Boardgeneric(platformesp8266,packageesp8266)isunknown”error?. . . . . . . 60
9 ExceptionCauses(EXCCAUSE) 61
10 Debugging 63
10.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
10.2 Informations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
ii
11 StackDumps 67
11.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
12 UsingEclipsewithArduinoESP8266 69
12.1 WhattoDownload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
12.2 SetupArduino . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
12.3 SetupEclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
12.4 Eclipsewontbuild . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
13 Changelog 71
13.1 2.3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
13.2 2.2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
13.3 2.0.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
13.4 1.6.4-673-g8cd3697 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
13.5 1.6.4-628-g545ffde . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
iii
iv
1
CHAPTER
Installing
Boards Manager
Thisisthesuggestedinstallationmethodforendusers.
Prerequisites
• Arduino1.6.8,getitfromArduinowebsite.
• Internetconnection
Instructions
• StartArduinoandopenPreferenceswindow.
• Enterhttp://arduino.esp8266.com/stable/package_esp8266com_index.jsonintoAddi-
tionalBoardManagerURLsfield. YoucanaddmultipleURLs,separatingthemwithcommas.
• OpenBoardsManagerfromTools>Boardmenuandfindesp8266platform.
• Selecttheversionyouneedfromadrop-downbox.
• Clickinstallbutton.
• Don’tforgettoselectyourESP8266boardfromTools>Boardmenuafterinstallation.
You may optionally use staging boards manager package link: http://arduino.esp8266.com/staging/
package_esp8266com_index.json. Thismaycontainsomenewfeatures,butatthesametime,somethings
mightbebroken.
1
ESP8266ArduinoCoreDocumentation,Release2.4.0
Using git version
Thisisthesuggestedinstallationmethodforcontributorsandlibrarydevelopers.
Prerequisites
• Arduino1.6.8(ornewer,ifyouknowwhatyouaredoing)
• git
• python2.7
• terminal,console,orcommandprompt(dependingonyouOS)
• Internetconnection
Instructions
• Open the console and go to Arduino directory. This can be either your sketchbook directory (usually
<Documents>/Arduino),orthedirectoryofArduinoapplicationitself,thechoiceisuptoyou.
• Clonethisrepositoryintohardware/esp8266com/esp8266directory. Alternatively,cloneitelsewhereandcreate
asymlink,ifyourOSsupportsthem.
cd hardware
mkdir esp8266com
cd esp8266com
git clone https://github.com/esp8266/Arduino.git esp8266
Youshouldendupwiththefollowingdirectorystructure:
Arduino
|
--- hardware
|
--- esp8266com
|
--- esp8266
|
--- bootloaders
--- cores
--- doc
--- libraries
--- package
--- tests
--- tools
--- variants
--- platform.txt
--- programmers.txt
--- README.md
--- boards.txt
--- LICENSE
• Downloadbinarytools
cd esp8266/tools
python get.py
2 Chapter1. Installing
ESP8266ArduinoCoreDocumentation,Release2.4.0
• RestartArduino
1.2. Usinggitversion 3
ESP8266ArduinoCoreDocumentation,Release2.4.0
4 Chapter1. Installing