Run a Program on an ESP32 Microcontroller

This is a guide on how to run a program on an ESP32 microcontroller using ESP-IDF on Linux (Debian 13). For more information, see the Getting Started documentation, the IDF Frontend documentation, and the Build System documentation.

Install ESP-IDF and Required Tools

These steps only need to be completed once:

Install the dependencies required by ESP-IDF:

sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

Install ESP-IDF:

mkdir ~/esp
cd ~/esp
git clone -b <stable_release> --recursive https://github.com/espressif/esp-idf.git

where <stable_release> is a stable release of ESP-IDF, which is noted in the ESP-IDF documentation.

Install the required tools for all ESP32 targets:
```
cd ~/esp/esp-idf
./install.sh all
```
To install the required tools for individual targets, see the ESP-IDF documentation.

Setup Environment and Configure Project

Connect the microcontroller to your computer.
Export the required environment variables:
```
. ~/esp/esp-idf/export.sh
```
Ensure that the program file is located in a subdirectory of the project directory named main. For example, if the program file is hello_world.c and the project directory is ~/hello_world, the program file must have as its path ~/hello_world/main/hello_world.c.
Ensure that the required CMakeLists.txt file exists in the project directory. The file must contain the following (see the documentation):
```
cmake_minimum_required(VERSION 3.5)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(<project_directory>)
```
where <project_directory> is the name of the project directory (e.g. hello_world).
Ensure that the required CMakeLists.txt file exists in the main subdirectory. The file must contain the following (see the documentation):
```
cmake_minimum_required(<version>)
idf_component_register(SRCS "<program_file>" INCLUDE_DIRS "")
```
where <version> is the minimum CMake version number (for example, VERSION 3.5) and <program_file> is the name of the program file (for example, hello_world.c).

The project structure will look like this:
```
<project_directory>
    main
        <program_file>
        CMakeLists.txt
    CMakeLists.txt
```
Note that there are two different CMakeLists.txt files, one in the project directory and the other in the main directory, each with different requirements.
Within the project directory, set the target and run the project configuration utility:
```
cd ~/<project_directory>
idf.py set-target <target>
idf.py menuconfig --style monochrome
```
where <project_directory> is the name of the project directory and <target> is the hardware target. To obtain a list of all possible targets, run:
```
idf.py --list-targets
```
Note that the --style monochrome option and argument pair above are optional, used to change the default white menuconfig display to black.

In the menuconfig settings, choose the desired settings. Then press s to save, Esc or Enter if necessary to remove the save confirmation dialogue, and q to quit.

Build, Flash, and Monitor the Program

Build the project within the project directory:
```
cd ~/<project_directory>
idf.py build
```
where <project_directory> is the name of the project directory.
Flash the binaries onto the device:
```
idf.py -p <port> -b <baud_rate> flash
```
where <port> is the port on which the device is connected and <baud_rate> is the baud rate. Specifying the port and the baud rate is optional. By default, ESP-IDF will use a USB port and a baud rate of 460800, per the documentation. The port on which the device is connected can be found by running:
```
ls /dev/tty*
```
For example, the port may be /dev/ttyUSB0.
Monitor the serial output, if applicable:
```
idf.py -p <port> monitor
```
where <port> is the port on which the device is connected.

Exit the monitor by pressing Ctrl + ].