Following subchapters present guides for setting up the environment to enable you to use Arduino(C) IDE to develop solutions for ESP8266 and ESP32. Installation methodology varies much as ESP8266 is already integrated with so-called Board Manager in Ardiono(C) iDE, while ESP32 is somehow external to the Boards Manager and requires some steps to be done, to obtain fully integrated environment. Some of the steps vary in details among various operating systems you use (Windows/Mac/Linux), see details, but in any case, there is a common idea, what to do in following steps. Once it is done, programming of both ESP8266 and ESP32 does not differ much from programming, i.e. Arduino Uno, natively supported by Arduino(C) IDE.

We consider here software that is natively installed as a binary package on your operating system, not a WEB version of the IDE. To obtain the latest version of the binary package, visit the website ^[6], as on figure 1 or install it via integrated software management application (Windows App Store, iTunes, Linux Application Store, etc.).

Assuming you've purchased any of the ESP8266 development boards, it is essential to write the first program. In any case, you'll need a way to write, compile and upload your code to the ESP8266 SoC. Here Arduino(C) IDE comes handy, however before you start, you need to let the Arduino(C) IDE knows, how to compile and communicate with your ESP8266 chip. Below there is a short manual, presenting how to install development extension to the Arduino(C) IDE through the Boards Manager. Note, other solutions (i.e. manual installation via Github pull) is also possible, but we do not consider this option here. ESP8266 core for Arduino(C) IDE is maintained by the community, and the latest version is available here (along with up-to-date installation guide) ^[7].

Install ESP8266 Boards via Board Manager

Start Arduino(C) IDE (Figure 2):

Enter application menu File/Preferences:

and then go to the Additional Boards Manager URLs:, enter following URL and accept changes (press OK) (Figure 4):

http://arduino.esp8266.com/stable/package_esp8266com_index.json

Once finished, you need to tell the Board Manager, which definitions and tools to download. Open Tools/Board:/Boards Manager (Figure 5):

and filter all boards entering “ESP8266” in the Search area, as on figure 6, then click Install:

Note – installation downloads number of resources over Internet connection and may take some time.

Configure Project to Compile for ESP8266

Once you're done with Arduino(C) IDE configuration now it is time to start programming. The process above installs a number of board definitions. First, depending on the development kit you own, select the appropriate type of the development board in the Board Manager menu, i.e. WeMos D1 R2 & mini (Figure 7):

Communication Between Development Machine and ESP SoC

Most of the ESP development boards come with integrated programming interface via serial to USB converter (usually CH340, CP210x, FDTI, Prolific, etc.) that you connect to the development machine using the USB cable. Connector standards vary, but nowadays the most popular seems to be Micro USB connector. There is also possible to upload your compilation using wireless transmission (OTA – Over The Air), or dedicated programming device, but we do not consider it here as too complicated to implement (requires special firmware) and also insecure. You need to select correct device interface – it differs, depending on the operating system you use, see details below how to identify it in your computer.




Windows

Look into the Device Manager to identify COM port, your board is represented by, in the Windows OS (Figure 8, here COM4):

Linux

In case of the Linux distributions, run in the terminal:

lsusb

and

ls /dev/ttyUSB*

or

ls /dev/ttyACM*

to identify your board (Figure 9):

Mac OS

The similar way to Linux distros, look for the devices using:

ls /dev/tty.usbmodem*

or

ls /dev/tty.usbserial*

to get a list of connected devices providing serial port feature (Figure 10):

Configure Details for the SoC

Now select appropriate device in the Arduino IDE (Figure 11) and select communication speed (Figure 12). Eventually, change the other parameters. Details on the flash size, its organisation, communication speed and frequencies should be provided by your hardware vendor. If you experience errors during programming or programming hangs, try to reduce programming speed, as your computer may be not quick enough to deliver data stream over USB. Devices usually present their maximum programming (flashing) speed, and it is common they tolerate lower speeds.

Troubleshooting Access Denied Error

In case of the Linux and Mac, depending on the security context you run your Arduino(C) IDE, you may experience “Access Denied” error. There are several workarounds to this problem, starting from running Arduino IDE with sudo credentials (not recommended) through creating udev rules (advanced) to simplest – providing credentials on-demand and ad-hoc. The disadvantage of this method is you must usually run those command every time you reboot OS or reconnect your board, yet is simplest to handle (Figure 13 and 14):

sudo usermod -a -G dialout $USER

sudo chmod a+rw /dev/ttyUSB0

A need to run one or two of the commands above strongly depends on the operating system configuration.

In case of the Windows OS, marking application to “Run as Administrator” may help to remove permission related errors (Figure 15):

ESP32 SoC is a continuation and extension to the ESP8266 SOCs. At the moment of writing this manual, installation of the ESP32 development environment is not supported via integrated Board Manager of the Arduino(C) IDE, as presented above in the ESP8266 section. Uploading your binary to the ESP32 chip via USB to serial converter requires Python as the ESP32 flashing tool is written in the form of the Python script. In case you're aware of what Python programming language is and how to install it on your machine, please refer to the Python website ^[8] and install Python before continuing.

Installing ESP32 Core for Arduino IDE

Depending on the operating system you use, there is necessary to perform some steps to obtain a fully functional ESP32 development environment for Arduino(C) IDE. ESP32 core for Arduino is maintained by the community, and the latest version is available here (along with up-to-date installation guide) ^[9]. Steps tend to have the same meaning, but tools to obtain the result are different for different operating systems.

Linux
A guide for the most popular distros (Ubuntu/Debian) is presented below.

Modify user credentials
This step is optional, see related ESP8266 section. Run following command in the terminal to add a user to the dialout group:

sudo usermod -a -G dialout $USER

Download and install git client
Run following command in the terminal:

sudo apt-get install git

Download and install python tools and packages
Run following commands in the terminal:

wget https://bootstrap.pypa.io/get-pip.py && \
sudo python get-pip.py && \
sudo pip install pyserial

Create destination folders and clone repository
Assuming your Arduino IDE is installed in your home directory, (~/Arduino), run the folowing code in terminal:

mkdir -p ~/Arduino/hardware/espressif && \
cd ~/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32

Pull depending modules and tools
Run following commands in the terminal:

git submodule update --init --recursive && \
cd tools && \
python2 get.py

Then start Arduino IDE.

Windows
Installing ESP32 core for Arduino requires Git client, both GUI and bash as well as command line operations.

Install Git and clone repository
You can download and install Git ^[10]. Once installed, choose “Clone Existing Repository” (Figure 16):

Use ESP32 core for Arduino repository address as source:

https://github.com/espressif/arduino-esp32.git

The destination folder depends on where you've installed Arduino IDE and your Windows user name. The common location is:

C:/Users/[YOUR_USER_NAME]/Documents/Arduino/hardware/espressif/esp32

note, you do not need to create this folder manually. If you install fresh copy of the Arduino IDE, perhaps there will be no hardware subfolder, but Git GUI will create remaining path for you. Once entered Source and Destination, click “Clone” (Figure 17). Cloning may take a while.

Pull depending modules
Use Git Bash command line (not a Windows command line!) to install dependencies (Figure 18). Change directory to the esp32 git local copy then run submodules install:

cd Documents/Arduino/hardware/espressif/esp32/

git submodule update --init --recursive

Download ESP32 tools
Open Windows command line (not a Git Bash command line!), navigate to the tools folder (Figure 19):

cd C:/Users/[YOUR_USER_NAME]/Documents/Arduino/hardware/espressif/esp32/tools

then run:

get.exe

Mac OS
Instruction for the Mac is similar to this for Linux. They require terminal to issue a set of commands to install ESP32 development kit and tools.

Create destination folders and clone source

mkdir -p ~/Documents/Arduino/hardware/espressif && \
cd ~/Documents/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32

Pull depending modules and tools
Run following commands in the terminal:

git submodule update --init --recursive && \
cd tools && \
python get.py

Then start Arduino IDE. Troubleshooting
If you get the following error during installation:

xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), 
missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun

then install command line developer tools using:

xcode-select --install

Configure Project to Compile for ESP32

Once ESP32 platform is installed, start Arduino IDE and you should see new board definitions, similar to those presented on the figure 20:

Refer to your board vendor for information about compatible configurations and setting up upload parameters. Detailed description and information on selecting communication port and upload speed is presented in the ESP8266 section, above.