ESP-IDF + Arduino + Bluepad32 template app

This is a template application to be used with Espressif IoT Development Framework.

Please check ESP-IDF docs for getting started instructions.

Requires ESP-IDF v5.3.2.

Includes the following ESP-IDF components, with a pre-configured sdkconfig file:

• Arduino Core for ESP32 component
• Bluepad32 component
• BTStack component

How to compile it

Clone the template project:

git clone --recursive https://github.com/ricardoquesada/esp-idf-arduino-bluepad32-template.git my_project

After cloning the template you have the following options:

• A) Using PlatformIO
• B) Visual Studio Code + ESP-IDF plugin
• C) CLion (personal favorite)
• D) ESP-IDF from command line

Note: Arduino IDE is not supported in this "template app" project

A) Using PlatformIO + ESP-IDF

1. Open Visual Studio Code, select the PlatformIO plugin
2. Click on "Pick a folder", and select the recently cloned "my_project" folder

That's it. The PlatformIO will download the ESP-IDF toolchain and its dependencies.

It might take a few minutes to download all dependencies. Be patient.

Note: You might need to remove previously installed PlatformIO packages. Just do rm -rf ~/.platformio and reinstall the PlatformIO plugin.

After all dependencies were installed:

1. Click on one of the pre-created boards, like esp32-s3-devkit-1. Or edit platformio.ini file, and add your own.
2. Click on build

Finally, click on "Upload and Monitor":

• It will upload your sketch
• And will enter into "monitor" mode: You can see and use the console. Try typing help on the console.

Further reading: PlatformIO Espressif IoT Development Framework

B) Visual Studio Code + ESP-IDF plugin

Open Visual Studio Code and install the ESP-IDF plugin.

Features:

• All the regular Visual Studio Code regular features
• ...plus configure, build, flash and monitor your project
• ...and much more

C) CLion

CLion is a great IDE, and my personal favorite. It works very well with ESP-IDF based projects.

To integrate your project with CLion, follow the steps in the CLion official documentation.

D) ESP-IDF from command line

For Windows

1. Install ESP-IDF v5.3. For further info, read: ESP-IDF Getting Started for Windows

   • Either the Online or Offline version should work
   • When asked which components to install, don't change anything. Default options are Ok.
   • When asked whether ESP can modify the system, answer "Yes"

2. Launch the "ESP-IDF v5.3 CMD" (type that in the Windows search box)

3. Compile it

   # Compile it
   cd my_project
   idf.py build
   
   # Flash + open debug terminal
   idf.py flash monitor

For Linux / macOS

1. Requirements and permissions

   Install ESP-IDF dependencies (taken from here):

   # For Ubuntu / Debian
   sudo apt-get install git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

   And in case you don't have permissions to open /dev/ttyUSB0, do: (taken from here)

   # You MUST logout/login (or in some cases reboot Linux) after running this command
   sudo usermod -a -G dialout $USER

2. Install and setup ESP-IDF

   # Needs to be done just once
   # Clone the ESP-IDF git repo
   mkdir ~/esp && cd ~/esp
   git clone -b release/v5.3 --recursive https://github.com/espressif/esp-idf.git
   
   # Then install the toolchain
   cd ~/esp/esp-idf
   ./install.sh

3. Compile the template

   Clone the template:

   # Do it everytime you want to start a new project
   # Clone the template somewhere
   mkdir ~/src && cd ~/src
   git clone --recursive https://github.com/ricardoquesada/esp-idf-arduino-bluepad32-template.git my_project

   Export the ESP-IDF environment variables in your shell:

   # Do it everytime you open a new shell
   # Optional: add it in your ~/.bashrc or ~/.profile
   source ~/esp/esp-idf/export.sh

   And finally compile and install your project.

   # Compile it
   cd ~/src/my_project
   idf.py build
   
   # Flash + open debug terminal
   idf.py flash monitor

Using 3rd party Arduino libraries

To include 3rd party Arduino libraries in your project, you have to:

• Add them to the components folder.
• Add CMakeLists.txt file inside the component's folder

Let's use a real case as an example:

Example: Adding ESP32Servo

Suppose you want to use ESP32Servo project. The first thing to notice is that the source files are placed in the src folder. We have to create a CMakeLists.txt file that tells ESP-IDF to look for the sources in the src folder.

Example:

# 1) We clone ESP32Servo into components folder
cd components
git clone https://github.com/madhephaestus/ESP32Servo.git
cd ESP32Servo

And now create these files inside components/ESP32Servo folder:

# 2) Create CMakeLists.txt file
# Copy & paste the following lines to the terminal:
cat << EOF > CMakeLists.txt
idf_component_register(SRC_DIRS "src"
                    INCLUDE_DIRS "src"
                    REQUIRES "arduino")
EOF

Finally, update the dependencies in the main/CMakeLists.txt. E.g:

cd main
edit CMakeLists.txt

...and append ESP32Servo to REQUIRES. The main/CMakeLists.txt should look like this:

idf_component_register(SRCS "${srcs}"
        INCLUDE_DIRS "."
        REQUIRES "${requires}" "ESP32Servo")

And that's it. Now you can include ESP32Servo from your code. E.g:

// Add this include in your arduino_main.cpp file
#include <ESP32Servo.h>

Further info

• Bluepad32 for Arduino
• Arduino as ESP-IDF component
• ESP-IDF VSCode plugin

Support

• Discord: any question? Ask them on our Discord server.