Espressif ESP32 Tutorial - Programming (Eclipse)

Eclipse (Photon)

The Eclipse IDE is one of the most popular desktop development environments. Being free and open source helps! It also supports most of the common programming languages through Language Server-based plugins. The current release is called Photon.

The C/C++ Development Toolkit (CDT) is a collection of Eclipse-based features that provides the capability to create, edit, navigate, build, and debug projects that use C and/or C++ as a programming language.

The CDT does not include the necessary compilers and debuggers to convert C/C++ code into executable programs and to debug those programs, but it does provide the frameworks that allow such tools to be integrated in a consistent fashion. We will be using the CDT version of Eclipse to program the ESP-32.

Installing the Eclipse IDE

The Eclipse IDE gives you a graphical integrated development environment (IDE) for writing, compiling and debugging ESP-IDF projects. It is quite a bit easier to use than the command line ESP-IDF provided by Espressif. It is also more sophisticated and better suited to larger projects than the Arduino IDE.

As Eclipse doesn't provide an ESP-32 compiler or the ability to flash the DevKit, you will need to have already installed the ESP-IDF tool chain for your operating system. If you haven't done this, refer to our earlier tutorial on the ESP-IDF.

Using ESP-IDF with Eclipse on Windows requires different configuration steps. See the Eclipse IDE on Windows guide if you are using Windows. The following is an overview of the steps for those using a Mac. This content is based on the material from the Espressif ESP-IDF Programming Guide but I have noted any areas where I had difficulty and included screenshots to make some of the explanations clearer.

1. Download the Eclipse Installer for your platform from eclipse.org.

2. Create a working directory, uncompress the download and run the installer app.

mkdir -p ~/eclipse
cd ~/eclipse
tar -xzf ~/Downloads/eclipse-inst-mac64.tar.gz 

open -a 'Eclipse Installer.app'

3. When running the Eclipse Installer, choose “Eclipse for C/C++ Development” (in the documentation you’ll see this referred to as CDT.)

4. When running the installer, you may get the following error.

Note that this is NOT referring to the Java Runtime Environment which you would update via System Preferences.

If you get the JVM error, you need to update the Java Development Kit. 

After that you should be rewarded with the following installation screen when you run the provided install app.

Setting up Eclipse

After the new Eclipse installation launches, follow these steps:

1. Import a New Project

Eclipse uses the Makefile capability in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the skeleton project from github or one of the example projects in the esp-idf examples subdirectory. We will use our old mate Blink again. Refer to our previous tutorial on the ESP-IDF if you don't know how to copy an example project.

Once Eclipse is running, choose File -> Import...

In the dialog that pops up, choose “C/C++” -> “Existing Code as Makefile Project” and click Next.

On the next page, in the “Existing Code Location” field, use the directory of your IDF project. Don’t specify the path to the ESP-IDF directory itself (we will do that in Project Properties). The directory you specify should contain a file named “Makefile” (the project Makefile).

On the same page, under “Toolchain for Indexer Settings” choose “Cross GCC”. Then click Finish.

2. Project Properties

The new project will appear in the left hand Project Explorer column. Right-click the project and choose Properties from the context menu.

Click on the “Environment” properties page under “C/C++ Build”. Click “Add…” and enter name BATCH_BUILD and value 1.

Click “Add…” again, and enter name IDF_PATH. The value should be the full path where ESP-IDF is installed. If you completed our previous ESP-IDF tutorial, you shouldn't have to do this step as the path will already be updated from the .profile preferences file.

Edit the PATH environment variable. Keep the current value, and append the path to the Xtensa toolchain installed as part of IDF setup, if this is not already listed on the PATH. 

A typical path to the toolchain looks like /home/user-name/esp/xtensa-esp32-elf/bin. Note that you need to add a colon : before the appended path.

On macOS, add a PYTHONPATH environment variable and set it to:

/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages. 

This is so that the system Python, which has pyserial installed as part of the setup steps, overrides any built-in Eclipse Python. I didn't need to do this on my Mac.

Navigate to “C/C++ General” -> “Preprocessor Include Paths” property page:

Click the “Providers” tab

In the list of providers, click “CDT Cross GCC Built-in Compiler Settings”. Under “Command to get compiler specs”, replace the text ${COMMAND} at the beginning of the line with xtensa-esp32-elf-gcc. This means the full “Command to get compiler specs” should be xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}".

In the list of providers, click “CDT GCC Build Output Parser” and type xtensa-esp32-elf- at the beginning of the Compiler command pattern. This means the full Compiler command pattern should be xtensa-esp32-elf-(g?cc)|([gc]\+\+)|(clang)

Navigate to “C/C++ General” -> “Indexer” property page:

Uncheck “Allow heuristic resolution of includes”. When this option is enabled Eclipse sometimes fails to find correct header directories.

3. Building in Eclipse

Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the esp-idf build process. These errors and warnings will go away after you build the project.

Click OK to close the Properties dialog in Eclipse.

Outside Eclipse, open a command line prompt. Navigate to your project directory, and run make menuconfig to configure your project’s esp-idf settings. This step currently has to be run outside Eclipse.

If you try to build without running a configuration step first, esp-idf will prompt for configuration on the command line - but Eclipse is not able to deal with this, so the build will hang or fail.

Back in Eclipse, choose Project -> Build All to build your project.

TIP: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before choosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths.

4. Flash from Eclipse

You can integrate the “make flash” target into your Eclipse project to flash using esptool.py from the Eclipse UI:

Right-click your project in Project Explorer (important to make sure you select the project, not a directory in the project, or Eclipse may find the wrong Makefile.)

Select Build Targets -> Create… from the context menu.
Type “flash” as the target name. Leave the other options as their defaults.

Make sure that the ESP-32 is connected and the correct serial port  has been selected using menuconfig then use Project -> Build Target -> Build (Shift+F9) to build the custom flash target, which will compile and flash the project.

Your program will be compiled and flashed to the ESP-32 and the results shown in the CDT build console.

Note that you will need to use “make menuconfig” to set the serial port and other config options for flashing. “make menuconfig” still requires the command line terminal (see the instructions for your platform on the Espressif site or refer to our ESP-IDF tutorial.)

Follow the same steps to add bootloader and partition_table targets, if necessary.