Installing - ESP8266 Arduino Core Documentation

ESP8266 Arduino Core

• Installing
  • Boards Manager
    • Prerequisites
    • Instructions
  • Using git version
    • Prerequisites
    • Instructions - Windows 10
    • Instructions - Other OS
    • Maintaining
    • Pull requests
  • Using PlatformIO
• Arduino IDE options
• Reference
• Libraries
• File system
• ESP8266WiFi
• OTA Updates
• PROGMEM
• Using GDB to debug
• MMU
• Boards

Troubleshooting

• FAQ
• Exception causes
• Debugging
• Stack Dump
• Using with Eclipse

FAQ

• Why I am getting errors when trying to upload to my ESP?
• My ESP crashes running some code. How to troubleshoot it?
• This Arduino library doesn’t work on ESP. How do I make it working?
• How to resolve “Board generic (platform esp8266, package esp8266) is unknown” error?
• Board generator
• How to specify global build defines and options
• Separate production and debug build options
• Aggressively cache compiled core
• Custom build environments
• Other build confusion

ESP8266 Arduino Core

• Installing
• View page source

Installing

Boards Manager

This is the suggested installation method for end users.

Prerequisites

• Internet connection

• Arduino IDE 1.x or 2.x (https://www.arduino.cc/en/software)

• (macOS/Linux only) Python ≥3.7 (https://python.org)

Instructions

• Start Arduino and open Preferences window.

• Enter https://arduino.esp8266.com/stable/package_esp8266com_index.json into Additional Board Manager URLs field. You can add multiple URLs, separating them with commas.

• Open Boards Manager from Tools > Board menu and find esp8266 platform.

• Select the version you need from a drop-down box.

• Click install button.

• Don’t forget to select your ESP8266 board from Tools > Board menu after installation.

For more information on the Arduino Board Manager, see:

• https://www.arduino.cc/en/guide/cores

Using git version

This is the suggested installation method for contributors and library developers.

Prerequisites

• Internet connection

• Arduino IDE 1.x or 2.x (https://www.arduino.cc/en/software)

• git (https://git-scm.com)

• Python ≥3.7 (https://python.org)

• terminal, console, or command prompt (depending on your OS)

• Uninstalling any core version installed via Board Manager

Instructions - Windows 10

• First, make sure you don’t already have an ESP8266 core version installed using the Board Manager (see above). If you do, uninstall it from the Board Manager before proceeding. It is also advisable to erase the Arduino15 contents.

• Install git for Windows (if not already; see https://git-scm.com/download/win)

• Open a command prompt (cmd) and go to Arduino default directory. This is typically the sketchbook directory (usually C:\Users\{username}\Documents\Arduino where the environment variable %USERPROFILE% usually contains C:\Users\{username})

• Clone this repository into hardware/esp8266com/esp8266 directory.

  cd%USERPROFILE%\Documents\Arduino\ ifnotexisthardwaremkdirhardware cdhardware ifnotexistesp8266commkdiresp8266com cdesp8266com gitclonehttps://github.com/esp8266/Arduino.gitesp8266

  You should end up with the following directory structure in

  C:\Users\{your username}\Documents\

  Arduino | ---libraries ---hardware | ---esp8266com | ---esp8266 | ---bootloaders ---cores ---doc ---libraries ---package ---tests ---tools ---variants ---platform.txt ---programmers.txt ---README.md ---boards.txt ---LICENSE

• Initialize submodules to fetch external libraries

  cd%USERPROFILE%\Documents\Arduino\hardware\esp8266com\esp8266 gitsubmoduleupdate--init

Not doing this step would cause build failure when attempting to include SoftwareSerial.h, Ethernet.h, etc. See our .gitmodules file for the full list.

• Download binary tools

  cdtools python3get.py

• Restart Arduino

• If using the Arduino IDE for Visual Studio (https://www.visualmicro.com/), be sure to click Tools - Visual Micro - Rescan Toolchains and Libraries

• When later updating your local library, goto the esp8266 directory and do a git pull

  cd%USERPROFILE%\Documents\Arduino\hardware\esp8266com\esp8266 gitstatus gitpull

Note that you could, in theory install in C:\Program Files (x86)\Arduino\hardware however this has security implications, not to mention the directory often gets blown away when re-installing Arduino IDE. It does have the benefit (or drawback, depending on your perspective) - of being available to all users on your PC that use Arduino.

Instructions - Other OS

• First, make sure you don’t already have an ESP8266 core version installed using the Board Manager (see above). If you do, uninstall it from the Board Manager before proceeding. It is also advisable to erase the .arduino15 (Linux) or Arduino15 (MacOS) contents.

• Open the console and go to Arduino directory. This can be either your sketchbook directory (usually <Documents>/Arduino), or the directory of Arduino application itself, the choice is up to you.

• Clone this repository into hardware/esp8266com/esp8266 directory. Alternatively, clone it elsewhere and create a symlink, if your OS supports them.

  cdhardware mkdiresp8266com cdesp8266com gitclonehttps://github.com/esp8266/Arduino.gitesp8266

  You should end up with the following directory structure:

  Arduino | ---hardware | ---esp8266com | ---esp8266 | ---bootloaders ---cores ---doc ---libraries ---package ---tests ---tools ---variants ---platform.txt ---programmers.txt ---README.md ---boards.txt ---LICENSE

• Initialize submodules to fetch external libraries

  cdesp8266 gitsubmoduleupdate--init

Not doing this step would cause build failure when attempting to include SoftwareSerial.h, Ethernet.h, etc. See our .gitmodules file for the full list.

• Download binary tools

  cdtools python3get.py

If you get an error message stating that python3 is not found, you will need to install it (most modern UNIX-like OSes provide Python 3 as part of the default install). To install you will need to use sudo yum install python3, sudo apt install python3, or brew install python3 as appropriate. On the Mac you may get an error message like:

python3get.py Platform:x86_64-apple-darwin Downloadingpython3-macosx-placeholder.tar.gz Traceback(mostrecentcalllast): File"/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/urllib/request.py",line1317,indo_open encode_chunked=req.has_header('Transfer-encoding')) ... File"/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/ssl.py",line1117,indo_handshake self._sslobj.do_handshake() ssl.SSLCertVerificationError:[SSL:CERTIFICATE_VERIFY_FAILED]certificateverifyfailed:unabletogetlocalissuercertificate(_ssl.c:1056)

This is because Homebrew on the Mac does not always install the required SSL certificates by default. Install them manually (adjust the Python 3.7 as needed) with:

cd"/Applications/Python 3.7/"&&sudo"./Install Certificates.command"

• Restart Arduino

• When later updating your local library, goto the esp8266 directory and do a git pull

  cdhardware\esp8266com\esp8266 gitstatus gitpull

Maintaining

To keep up with the development branch

gitswitch--recurse-submodules--discard-changesmaster gitpull--recurse-submodules cdtools python3get.py

Pull requests

To test not yet merged Pull Request, first you have to find its ID number. This is the sequence of digits right after the pull request title.

Open terminal and cd into the directory where the repository was previously cloned. For example, 12345 is the Pull Request ID

gitfetchoriginpull/12345/head gitswitch--detach--recurse-submodules--discard-changesFETCH_HEAD

When Pull Request updates packaged tools, make sure to also fetch their latest versions.

cdtools python3get.py

To go back to using the development branch

gitswitch--recurse-submodules--discard-changesmaster gitpull--recurse-submodules

Using PlatformIO

PlatformIO is an open source ecosystem for IoT development with a cross-platform build system, a library manager, and full support for Espressif (ESP8266) development. It works on the following popular host operating systems: macOS, Windows, Linux 32/64, and Linux ARM (like Raspberry Pi, BeagleBone, CubieBoard).

• What is PlatformIO?

• PlatformIO IDE

• PlatformIO Core (command line tool)

• Advanced usage - custom settings, uploading to LittleFS, Over-the-Air (OTA), staging version

• Using Arduino Framework Staging Version - install development version of the Core

• Integration with Cloud and Standalone IDEs - Cloud9, Codeanywhere, Eclipse Che (Codenvy), Atom, CLion, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, VIM, Visual Studio, and VSCode

• Project Examples