Install arduino-esp32 from the source
WipperSnapper is an Arduino application built on a board support package like the ESP32 Arduino Core. To build WipperSnapper, you will want the absolute latest version of the arduino-esp32 core installed into Arduino.
To do this, follow the steps below:
- Install the latest version of "Arduino Legacy IDE (1.8.X)" from arduino.cc/en/software
- After Installing Arduino IDE 1.8.X, open Arduino IDE. Then, after it loads, close it.
- Install the latest version of the Arduino-ESP32 board support package for your platform. Make sure to follow the instructions on the espressif documentation, rather than installing the board support package directly from Arduino IDE
- For Linux, follow the install instructions here...
- For MacOS, follow the install instructions here...
- For Windows, follow the install instructions here...
Verify Installation
Open Arduino IDE and navigate to the Tools->Board menu. From there, you should see "ESP32 Arduino (in sketchbook)". The (in sketchbook) part of the string identifies that you have installed the Arduino-ESP32 core manually, rather than using the Board Manager.
If your path exactly matches the one shown in the screenshot below, let's move onto the next step.
Install Arduino Dependencies for WipperSnapper Library
Since it supports a large portion of sensors, WipperSnapper brings in a lot of library dependencies. To install (most) of them, we'll use Arduino IDE.
In Arduino IDE, navigate to Sketch -> Include Library -> Library Manager
Within the library manager, search for WipperSnapper and install the latest version.
- If you aim to build off a pre-release of WipperSnapper, scroll to the bottom of the "Select Version" modal for alpha versions of WipperSnapper.
After installing, your Arduino installation should have most of the dependencies required for WipperSnapper. Due to how the CI for WipperSnapper is configured for specific build platforms, you will also need to manually install a few extra libraries, from the library manager:
- DallasTemperature
- OneWireNg
- Adafruit HX8357 Library
- Adafruit ILI9341
- Adafruit STMPE610
- Adafruit_TouchScreen
Next, locate your Arduino sketchbook's libraries subfolder and install two required libraries into this folder:
- To find this folder, visit https://support.arduino.cc/hc/en-us/articles/4415103213714-Find-sketches-libraries-board-cores-and-other-files-on-your-computer and look underneath "Libraries" for the directory that matches your operating system
Install the wippersnapper branch of LVGL to this folder (We freeze a specific version of LVGL for WipperSnapper):
git clone --depth 1 --branch wippersnapper https://github.com/brentru/lvgl.git
Also, install the LVGL_Glue library to this folder:
git clone --depth 1 --branch development https://github.com/brentru/Adafruit_LvGL_Glue.git
(Optional) Re-install WipperSnapper Library from Source
If you are developing WipperSnapper, you'll want to work from a fork of the latest master branch.
- Delete the current version of Adafruit_WipperSnapper_Arduino from the Arduino Sketchbook Library sub-folder.
- Create a fork of WipperSnapper on your git account by visiting https://github.com/adafruit/Adafruit_Wippersnapper_Arduino and clicking Fork.
- Using
git clone, clone the fork directly into the sketchbook library subfolder
Build WipperSnapper for a Specific Board
Building and uploading WipperSnapper to a board ensures everything is installed and working correctly. For this example, we'll use the Adafruit ESP32-S2 Feather.
From Arduino IDE, open the WipperSnapper example sketch by navigating to File->Adafruit WipperSnapper->Wippersnapper_demo
Select the board you're using by navigating to Tools->Board->ESP32 Arduino (in sketchbook)->{BOARD NAME}.
Then, ensure the board is plugged into your computer and navigate to: Tools->Port->{board_port}.
Upload the sketch to your board by clicking Tools->Upload
Get Compiler Artifacts/Output
If you would like to check artifacts produced by the compiler, such as the .bin and memory .map files, the end of the compiler output provides a directory for the .elf file.
Navigate to this folder for the build's artifacts:
Configure Arduino BSP Libraries
For memory optimization, I've found that Espressif provides a tool to simplify building your own compiled libraries for use in Arduino IDE called Library Builder. This tool contains scripts that produce the pre-compiled (.a) libraries included with esp32-arduino.
The tool's output is dictated by a set of configuration files (https://github.com/espressif/esp32-arduino-lib-builder/tree/master/configs) specific to each ESP32 platform. However, there is a common configuration that runs across all platforms.
- Note: using a custom sdkconfig works for only one specific platform. If you run menuconfig, you will need to copy over the sdkconfig to a configuration script instead as the sdkconfig file will get overwritten.
Documentation for running this tool is available at https://espressif-docs.readthedocs-hosted.com/projects/arduino-esp32/en/latest/lib_builder.html
After building (which takes about an hour-ish) the libraries, use the tools/copy-to-arduino.sh script to move the new libraries into the arduino-esp32 folder.
Finally, re-open Arduino IDE and, repeat "Build WipperSnapper for a Specific board" to initiate a new wippersnapper build with the libraries produced by esp32-arduino-lib-builder..