Arduino IDE¶

The preferred way to build ESPEasy is using PlatformIO. However, there are still lots of people happily using Arduino IDE. Therefore we try to keep the project source compatible with Arduino IDE.

Since development is not done in Arduino IDE, it may happen that some commit breaks Arduino IDE compatibility. Usually it is something as simple as an include not being relative compared to the file which is being compiled. This is a bug, which PlatformIO does not complain about and thus can be missed easily during development.

If something like this happens, please open an issue (or pull request) for it on GitHub. Also, if someone knows a build flag for PlatformIO to signal those errors, please let us know.

Prepare Arduino IDE¶

When installing Arduino IDE, its default installation folder structure is to share libraries and sketches among all installations of Arduino IDE. If you only build one project, this is just fine. However, if you try to build several projects or versions of projects, then you will run into library dependency issues.

See: how to create portable version of Arduino IDE

For building ESPEasy it is adviced to use a “portable installation” of Arduino IDE.

Arduino IDE Prerequisites¶

For building ESPEasy in Arduino IDE, you need to install the board manager and ESP8266/ESP32 library.

See these excellent tutorials:

Download ESPEasy Sources¶

The sources can be downloaded from GitHub as ZIP file.

In this document, the given file system paths refer to a portable installation of Arduino IDE in D:\temp\Arduino-EspEasy\

The structure in the ZIP file are made for use in PlatformIO. To use the source in Arduino IDE, you have to split the sources into 2 parts:

The used libraries: D:\temp\Arduino-EspEasy\portable\sketchbook\libraries
The source code: D:\temp\Arduino-EspEasy\portable\sketchbook\ESPEasy

Some used libraries differ from the original ones to make them work with ESPEasy. So make sure to use the ones supplied in the ZIP file in the lib folder. If some libraries are missing from the lib folder, you can install them via the Arduino IDE library manager.

The source code files to be placed in the ESPEasy directory must be taken from the (first) src directory in the ZIP file. Meaning the file ESPEasy.ino must be in the ESPEasy folder. (including all files in sub folders)

Building using Custom.h¶

There is a Custom-sample.h file supplied, which has lots of defines that can be set or uncommented to make a specific build including just the plugins and controllers needed and maybe even some proper default settings.

To use this file, it must be renamed to Custom.h.

There are two options to define USE_CUSTOM_H for an Arduino IDE build:

In ESPEasy_common.h: uncomment //#define USE_CUSTOM_H
Create a personal platform.local.txt file

Define USE_CUSTOM_H in ESPEasy_common.h¶

PlatformIO does recognize the presence of this file when building a Custom build environment. But for Arduino IDE, a single line must be uncommented in ESPEasy_common.h

Make sure to uncomment this line at the start of ESPEasy_common.h: //#define USE_CUSTOM_H This define makes sure the Custom.h file is actually included during build.

Build definition via platform.local.txt¶

Locate the file platform.txt in the esp8266 platform directory of ArduinoIDE.

The exact location depends on the installation, usually in a directory below the main application called hardware/esp8266.com/.

In the same directory add an (untraced) file called platform.local.txt with the following lines:

compiler.minsize=
compiler.c.extra_flags=-DUSE_CUSTOM_H -DPUYA_SUPPORT=0 -DCONFIG_FREERTOS_ASSERT_DISABLE -DCONFIG_LWIP_ESP_GRATUITOUS_ARP -DCONFIG_LWIP_GARP_TMR_INTERVAL=30 -DCORE_POST_2_5_0 -DCORE_POST_2_6_0 -DNDEBUG -DICACHE_FLASH -DWEBSERVER_RULES_DEBUG=0 -DVTABLES_IN_FLASH -mtarget-align -Werror=unused-variable {compiler.minsize}
compiler.c.elf.extra_flags=-DUSE_CUSTOM_H -DPUYA_SUPPORT=0 -DCONFIG_FREERTOS_ASSERT_DISABLE -DCONFIG_LWIP_ESP_GRATUITOUS_ARP -DCONFIG_LWIP_GARP_TMR_INTERVAL=30 -DCORE_POST_2_5_0 -DCORE_POST_2_6_0 -DNDEBUG -DICACHE_FLASH -DWEBSERVER_RULES_DEBUG=0 -DVTABLES_IN_FLASH -mtarget-align -Werror=unused-variable {compiler.minsize}
compiler.S.extra_flags=-DUSE_CUSTOM_H -DPUYA_SUPPORT=0 -DCONFIG_FREERTOS_ASSERT_DISABLE -DCONFIG_LWIP_ESP_GRATUITOUS_ARP -DCONFIG_LWIP_GARP_TMR_INTERVAL=30 -DCORE_POST_2_5_0 -DCORE_POST_2_6_0 -DNDEBUG -DICACHE_FLASH -DWEBSERVER_RULES_DEBUG=0 -DVTABLES_IN_FLASH -mtarget-align -Werror=unused-variable {compiler.minsize}
compiler.cpp.extra_flags=-DUSE_CUSTOM_H -DPUYA_SUPPORT=0 -DCONFIG_FREERTOS_ASSERT_DISABLE -DCONFIG_LWIP_ESP_GRATUITOUS_ARP -DCONFIG_LWIP_GARP_TMR_INTERVAL=30 -DCORE_POST_2_5_0 -DCORE_POST_2_6_0 -DNDEBUG -DICACHE_FLASH -DWEBSERVER_RULES_DEBUG=0 -DVTABLES_IN_FLASH -mtarget-align -Werror=unused-variable {compiler.minsize}
compiler.ar.extra_flags=
compiler.objcopy.eep.extra_flags=
compiler.elf2hex.extra_flags=

Board definitions¶

In Arduino IDE you must prepare the environment variables yourself.

Board: “Generic ESP8266 Module”
Flash Size: Pick the one reflecting your board (4M flash 1M FS is the most used)
Flash Mode: “DOUT”

The other settings are likely to be correct when using the defaults. See the screenshot to be sure.