makeEspArduino

A makefile for ESP8266 and ESP32 Arduino projects.

The main intent for this project is to provide a minimalistic yet powerful and easy configurable makefile for projects using the ESP/Arduino framework available at: https://github.com/esp8266/Arduino and https://github.com/espressif/arduino-esp32

Using make instead of the Arduino IDE makes it easier to do more production oriented builds of software projects.

This makefile gives you a command line tool for easy building and loading of the ESP/Arduino examples as well as your own projects.

The makefile can use the ESP/Arduino environment either from the installation within the Arduino IDE or in a separate git clone of the environment. The latter can be useful in project where you want stringent control of the environment version e.g. by using it as a git submodule.

You basically just have to specify your main sketch file and the libraries it uses. The libraries can be from arbitrary directories without any required specific hierarchy or any of the other restrictions which normally apply to builds made from within the Arduino IDE. The makefile will find all involved header and source files automatically. The search is made starting at the main sketch and the recursively continued through all #include statements that are found. All source files found in directories where include files were found will automatically be added to the build.

Rules for building the firmware as well as upload it to the ESP board are provided.

It is also possible to let the makefile generate and upload a complete flash file system based on an arbitrary directory of files.

The intention is to use the makefile as is. Possible specific configuration is done via via makefile variables supplied on the command line or in separate companion makefiles.

The makefile can be used on Linux, Mac OSX, Microsoft Windows (Cygwin or WSL) and OpenBSD.

The actual build commands (compile, link etc.) are extracted from the Arduino description files (platform.txt etc.).

Uploading of the built binary can be made via serial channel (esptool), ota (espota.py) or http (curl). Which method to use is controlled by makefile target selection. By default the serial channel is used.

Configuration files for Visual Studio Code can be generated by this makefile as well.

Installing

First make sure that you have the environment installed as described at: https://github.com/esp8266/Arduino

and

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

If you don't want to use the environment installed in the Arduino IDE, then you can clone it into a separate directory instead, see below.

Then start cloning the makeEspArduino repository.

cd ~
git clone https://github.com/plerup/makeEspArduino.git

After this you can test it. Attach your ESP8266 board and execute the following commands:

cd makeEspArduino
make -f makeEspArduino.mk DEMO=1 flash

The DEMO definition makes the the makefile choose a typical demo sketch from the ESP examples. After this you will have the example downloaded onto in your ESP.

If you want to use a clone of the ESP/Arduino environment instead, then do something like this for esp8266:

cd ~
git clone https://github.com/esp8266/Arduino.git esp8266
cd esp8266

Determine which version you want to use. See releases. Example:

git checkout tags/3.0.0

Then install the required environment tools by issuing the following commands:

git submodule update --init
cd tools
python3 get.py

Please note that you have to rerun the commands above if you checkout another label or branch in the git.

To test this installation you have to specify the location of the environment when running make

cd ~/makeEspArduino
make -f makeEspArduino.mk ESP_ROOT=~/esp8266 DEMO=1 flash

For ESP32 just change esp8266 in the commands above to esp32, i.e:

cd ~
git clone https://github.com/espressif/arduino-esp32.git  esp32
cd esp32
git submodule update --init
cd tools
python3 get.py

When building ESP32 projects the variable CHIP must always be defined, example:

make -f makeEspArduino.mk ESP_ROOT=~/esp32 CHIP=esp32 DEMO=1 flash

If you want to minimize your typing henceforth then there is a rule in the makefile which can be used to generate shortcut commands in /usr/local/bin. These commands are named espmake and espmake32. To achieve this when using a git clone type:

make -f makeEspArduino.mk ESP_ROOT=~/esp8266 install

make -f makeEspArduino.mk ESP_ROOT=~/esp32 CHIP=esp32 install

Sudo access will be required for this operation.

Getting help

A description of all available makefile functions and variables is always available via the following command:

make -f makeEspArduino.mk help

Building projects

You can now use the makefile to build your own sketches or any of the examples in the ESP/Arduino environment. The makefile will automatically search for a sketch in the current directory and build it if found. It is also possible to specify the location of the sketch on the command line.

Some examples

In current directory:

cd ~/.arduino15/packages/esp8266/hardware/esp8266/2.3.0/libraries/Ticker/examples/TickerBasic
espmake

Explicit naming of a default directory:

espmake -C ~/.arduino15/packages/esp8266/hardware/esp8266/2.3.0/libraries/Ticker/examples/TickerBasic

Explicit naming of the sketch:

espmake SKETCH=~/.arduino15/packages/esp8266/hardware/esp8266/2.3.0/libraries/Ticker/examples/TickerBasic/TickerBasic.ino
# Or like this
espmake SKETCH="\$(ESP_ROOT)/libraries/Ticker/examples/TickerBasic/TickerBasic.ino"

Advanced usage

The makefile has several variables which control the build. There are different ways to change the defaults of these variables.

The simplest and most direct way to do this is by specifying the variables and their values on the command line.

The more permanent way is to create a special makefile with the appropriate values for the variables and then include this in the build. This can be achieved either by including makeEspArduino.mk in this file or the other way around by letting makeEspArduino.mk include it. The advantage with the latter method is that the makefile doesn't need to know the location of makeEspArduino.mk, more about this in the examples below.

The most important variables in the makefile are listed below:

SKETCH is the path to the main source file. As stated above, if this is missing then makeEspArduino will try to locate it in the current directory.

LIBS is a variable which is used to specify your own additional library source or linker archive files. As stated above, makeEspArduino will do an automatic search for header files used by all involved source files in the build. This is achieved by checking for #include statements and for each found such statement, search for a corresponding existing header file anywhere in a list of directories. The search is started in the sketch source file and then recursively following any found file which in turn will be searched for new #include statements. By default this list contains all the directories underneath the ESP/Arduino libraries root and possible standard Arduino libraries, but the list can be extended using this variable.

This way you can specify an additional list of directories which contains header and/or source files that you want to be included in the build. The different entries in the list are separated with space. If an entry contains a path to a directory then that directory and all its sub directories will be included in the search list for header files. If a header file is found in that directory then all source files (*.cpp, *.c, *.S) also found there will be added to the build. This is due to the fact that there is not always a one-to-one relationship between a header file name and the corresponding implementation source file.

It is also possible to specify an explicit source file or a wildcard in a list entry. In that case only the source files matching this will be added and the corresponding directory will added to the header file directory search list.

Library files (.a or .lib) can also be specified here and these will be added to the linker command.

If the sketch is located in an /example/ directory the possible corresponding /src/ directory will automatically be added to the directory search list.

Example:

LIBS = $(MY_ROOT)/lib1 $(MY_ROOT)/lib2/my_file.cpp $(MY_ROOT)/lib3/*.c $(MY_ROOT)/lib3/my_lib.a

You can always use the rule list_lib to check what include directories and source files that was found during the search.

The automatic search for used files via included header files does not work if the corresponding implementation source file are located in another directory than the header file. If you have problem with this, you can set the variable EXPAND_LIBS and then all source files in the directories specified via the LIBS variable will be added to the build. This may lead to compiling unnecessary files though.

If you for some reason want to exclude some sub directories from the search list you can specify this using the variable EXCLUDE_DIRS. The value is interpreted a regular expressions so multiple directories must be separated with | . In the same way the variable EXCLUDE_INC can be used to exclude directories from the list of found include directories.

CHIP Set to either esp8266 (default) or esp32

BOARD The type of ESP8266 or ESP32 board you are using, use the rule list_boards to show what's available

BUILD_DIR All intermediate build files (object, map files etc.) are stored in a separate directory controlled by this variable. By default this is set to a name consisting of the project and board names. This is just the directory name, the root of this directory is controlled by the variable BUILD_ROOT. Default for this