Skip to main content

Getting Started

While exploring my local network, I stumbled upon several devices named espressif, and after some searching online I found the ESP32 was the likely culprit. I've always been interested in hardware and have experience working with electrical circuits from 120-480 volts, but I have never identified a resistor or even considered purchasing a breadboard.

So, I bought thisa board on Amazon because it was fast shipping and I had a long weekend coming up. I won't share an Amazon link here for several reasons, but the exact model that I purchased was the ESP32-DevKitC V4 which comes with the ESP32-WROOM chip soldered on.

TutorialsI specificlove smart devices. In fact, that's exactly how the ESP32 ended up on my local network. I tracked the espressif devices down to thismy boardcat's arewater here.

and

Somefood other tutorials / refrences I collected going down this rabbit hole -

Development Methods

There are different ways to organize ESP32 projects, below is a brief on formatsthat I'ved explored.

Arduino IDE

The Arduino IDE can be used to load sketches easily and flash to your ESP32.

This is easiest for a beginner, but you will havelike to use the ArudinoESP32 IDE.for some wifi controlled 'smart' task.

DownloadWhen the board first arrived, I tried out the Arduino IDE. It was fine for learning purposes, but it felt like the IDE was doing a lot for me without having the chance to really understand everything going on behind the scenes. Personally I (barely) prefer CLion, and I wanted to get back to the IDE that was familiar to me. More importantly, I wanted to work on the ESP32 without tethering myself to any IDE. I wanted the project to be completely stand-alone, and to document and install any dependencies manually. Using Sketches in the Arduino IDE here

wasn't 
unzip arduino-ide_2.3.4_Linux_64bit.zip -d ./arduino-ide_2.3.4
cd arduino-ide_2.3.4/
sudo chown root:root /home/shaun/Downloads/arduino-ide_2.3.4/chrome-sandbox
# Maybe
sudo chmod 4755 /home/shaun/Downloads/arduino-ide_2.3.4/chrome-sandbox

# For permissionsgoing to accessget USBme devicesthere.

newgrp
Enter uucpthe newgrpEspressif dialoutIoT #Development StartFramework, IDEor ./arduino-idethe

ESP-IDF (CMakefor /short. CLion)

This looks slightly intimidating at first, but if you're at all familiar with C programming you'll get along fine. Before we dive into the ESP-IDF, lets take a step back and gain our bearings.

Ecosystems

ThisTypically isthe ESP32 examples recommended for advancedbeginners setupswill only.be Ifusing justthe gettingarduino-esp32 startedAPIs I- Espressif provides one such example called WiFiClient. These examples are also made available in the Arduino IDE's menus where you can create a new project (sketch) based on this WiFiClient example. This example uses higher level C++ APIs than what you'll find in the ESP-IDF examples.

But why would recommendEspressif, creators of the sectionESP32 aboveand not the Arduino, want to support Arduino APIs? Simply because they are a popular point of entry for learning programming on Arduinomicrocontrollers, IDE.

and

github.com/espressif/esp-idfsupporting these APIs lowers the barrier of entry for ESP32 devices.

The ESP-IDF build system supports using arduinothose same Arduino APIs via an IDKIDF component configuration.configuration marking arduino-esp32 as a dependency. See the officialEspressif GitHub example here

,

paired with the OfficialIDF Arduinocomponent documentation from espressif. forFeel free to use these simpler APIs and examples to get familiar with deploying to the ESP32 using Arduino as anthe ESP-IDF component.before jumping into the lower-level ESP APIs.

ESP-IDF

Installing

InstallFirst esp-idfwe need to install the ESP-IDF following GitHub instructions on ubuntu 24.04

WARNING: PayIf you are using arduino-esp32 APIs mentioned above, pay attention to Arduino-arduino-esp32 releases for the latest supported esp-idfESP-IDF version. The latest esp-idfESP-IDF version is likely not currently supported by Arduino-arduino-esp32. At the time of this writing, the latest Arduino-arduino-esp32 release is based on ESP-IDF 5.3.2, so below we checkout the v5.3.2 branch of github.com/espressif/esp-idf.git.

Install the prerequisites required for the ESP-IDF

# https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html#step-1-install-prerequisites
sudo apt-get install -y git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
#

Clone the ESP-IDF using the v5.3.2 esp-idfbranch and installinstall. (installThere /will exportbe a lot of output removed)produced from these commands that is not shown below.

git clone -b v5.3.2 git@github.com:espressif/esp-idf.git
cd esp-idf
./install.sh
. ./export.sh
#

Switching Versions

To switch versions after previously installing esp32-idfthe ESP-IDF

cd /path/to/esp-idf
git checkout v5.3.2
git submodule update --init --recursive
./install.sh
. ./export.sh

If everything worked correctly, you should end up with this final output in your terminal -

Done! You can now compile ESP-IDF projects.
Go to the project directory and run:

  idf.py build

Project Example

First set up your environment to use esp-idfESP-IDF tools,tools and to have the correct exports required for building with CMake. Unfortunately the way this is done is by sourcing a script in the ESP-IDF repository, after you've installed the ESP-IDf.

# Source esp-idf script
source /home/shaun/Code/Clones/esp-idf/export.sh
#
Make

You IDF_PATHshould andnow esp-idfhave toolsidf.py available automaticallyin #your Otherwiseshell.

you
idf.py
Usage: idf.py [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

  ESP-IDF CLI build management tool. For commands that are not known to idf.py an attempt to execute
  it as a build system target will needbe tomade. Selected target: None

To make this simpler I threw an alias in my .bash_aliases file. I prefix all my alias commands with a comma. It looks strange, but it clearly separates an alias from a typical command.

echo "alias ,esp='source the$HOME/Code/Clones/esp-idf/export.sh'" `export.sh`>> script~/.bash_aliases
every

So next time youwhen I want to usework idf.pyon orESP similarthings commandsI echocan "exportjust IDF_PATH=$HOME/esp/v5.4/esp-idf"run >>,esp $HOME/.bash_aliasesin echoa "exportterminal PATH=\"$IDF_PATH/tools:$PATH\""to >>initialize $HOME/.bash_aliasesmy environment.

Building

Now we can configure and build the project

# My example project directory
cd ~/Code/klips/esp/cpp/04_esp-idf-arduino
idf.py set-target esp32
# IMPORTANT: We set the 3.1.1 version because the release is compatible with esp-idf v5.3.2 we installed in the first step
# https://github.com/espressif/arduino-esp32/releases/tag/3.1.1
idf.py add-dependency "espressif/arduino-esp32^3.1.1"

# Autostart Arduino for use of `loop()` and `setup()` functions
# You can also use the esp-idf `app_main()` function if preferred
# https://docs.espressif.com/projects/arduino-esp32/en/latest/esp-idf_component.html#configuration
# You can alternatively do this in the GUI tool `idf.py menuconfig`
echo "CONFIG_AUTOSTART_ARDUINO=y" >> sdkconfig
sed -i -e 's/CONFIG_FREERTOS_HZ=100/CONFIG_FREERTOS_HZ=1000/' sdkconfig

# Build the project
idf.py build

ESP-IDF example using app_main()
ESP-IDF example using Arduino loop() and setup()

If everything completed normally, the build output will end with

Project build complete. To flash, run:
 idf.py flash
or
 idf.py -p PORT flash
or
 python -m esptool --chip esp32 -b 460800 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size 2MB --flash_freq 40m 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/main.bin
or from the "/home/shaun/Code/klips/esp/cpp/04_esp-idf-arduino/build" directory
 python -m esptool --chip esp32 -b 460800 --before default_reset --after hard_reset write_flash "@flash_args"

Flashing

Find the device for the ESP32. Mine is /dev/ttyUSB0 in the output below.

$ ls /dev/tty*
/dev/tty    /dev/tty16  /dev/tty24  /dev/tty32  /dev/tty40  /dev/tty49  /dev/tty57  /dev/tty8       /dev/ttyS14  /dev/ttyS22  /dev/ttyS30
/dev/tty0   /dev/tty17  /dev/tty25  /dev/tty33  /dev/tty41  /dev/tty5   /dev/tty58  /dev/tty9       /dev/ttyS15  /dev/ttyS23  /dev/ttyS31
/dev/tty1   /dev/tty18  /dev/tty26  /dev/tty34  /dev/tty42  /dev/tty50  /dev/tty59  /dev/ttyprintk  /dev/ttyS16  /dev/ttyS24  /dev/ttyS4
/dev/tty10  /dev/tty19  /dev/tty27  /dev/tty35  /dev/tty43  /dev/tty51  /dev/tty6   /dev/ttyS0      /dev/ttyS17  /dev/ttyS25  /dev/ttyS5
/dev/tty11  /dev/tty2   /dev/tty28  /dev/tty36  /dev/tty44  /dev/tty52  /dev/tty60  /dev/ttyS1      /dev/ttyS18  /dev/ttyS26  /dev/ttyS6
/dev/tty12  /dev/tty20  /dev/tty29  /dev/tty37  /dev/tty45  /dev/tty53  /dev/tty61  /dev/ttyS10     /dev/ttyS19  /dev/ttyS27  /dev/ttyS7
/dev/tty13  /dev/tty21  /dev/tty3   /dev/tty38  /dev/tty46  /dev/tty54  /dev/tty62  /dev/ttyS11     /dev/ttyS2   /dev/ttyS28  /dev/ttyS8
/dev/tty14  /dev/tty22  /dev/tty30  /dev/tty39  /dev/tty47  /dev/tty55  /dev/tty63  /dev/ttyS12     /dev/ttyS20  /dev/ttyS29  /dev/ttyS9
/dev/tty15  /dev/tty23  /dev/tty31  /dev/tty4   /dev/tty48  /dev/tty56  /dev/tty7   /dev/ttyS13     /dev/ttyS21  /dev/ttyS3   /dev/ttyUSB0

To flash run the following commands.

# Manually selecting port with above output
# Baud rate matters: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/establish-serial-connection.html#connect-esp32-to-pc
idf.py -p /dev/ttyUSB0 -b 115200 flash

# Let esp-idf automatically detect port and baud rate
idf.py flash

To open serial monitor with esp-idf via the commandline -

idf.py monitor -b 115200

Or in CLion the Serial Monitor extension works well.

Personal notes

this board on Amazon

Tutorials specific to this board are here.

Some other tutorials / refrences I collected going down this rabbit hole -

Development Methods

There are different ways to organize ESP32 projects, below is a brief on formats I've explored.

Arduino IDE

The Arduino IDE can be used to load sketches easily and flash to your ESP32.

This is easiest for a beginner, but you will have to use the Arudino IDE.

Download Arduino IDE here

unzip arduino-ide_2.3.4_Linux_64bit.zip -d ./arduino-ide_2.3.4
cd arduino-ide_2.3.4/
sudo chown root:root /home/shaun/Downloads/arduino-ide_2.3.4/chrome-sandbox
# Maybe
sudo chmod 4755 /home/shaun/Downloads/arduino-ide_2.3.4/chrome-sandbox

# For permissions to access USB devices
newgrp uucp
newgrp dialout

# Start IDE
./arduino-ide

ESP-IDF (CMake / CLion)

This is recommended for advanced setups only. If just getting started I would recommend the section above on Arduino IDE.

github.com/espressif/esp-idf

The ESP-IDF supports using arduino APIs via an IDF component configuration. See the official GitHub example here, paired with the official documentation from espressif.

Official Arduino documentation for using Arduino as an ESP-IDF component.

Back to top