Windows

To get started with ESP32, read through their documentation considering that the devkit I chose uses the WROVER-E chip. The Get Started page is the best place to start. They have Visual Studio Code and Eclipse plugins, but as I use emacs, I opted to install the components separately. If you're using windows, you can follow their Toolchain from Scratch ¹ guide and install the following:

• CMake (3.29.3 as of this writing)
• ESP-IDF v5.2.1
• Ninja Build v1.12.1
• Python (3.12.1 as of this writing)
• xtensa-esp-elf toolchain

The guide also requests installation of other tools. Once again, I went the "from scratch" route to better understand the pieces in case they fall apart later. The guide mentions "ESP-IDF build system expects that all the necessary tools are installed somewhere, and made available in the PATH." Here's the list of required tools and their download links.

Anyway, the first step is to install CMake and Ninja and add them to PATH. Then extract ESP-IDF somewhere. Then set IDF_PATH environment variable to the path of esp-idf-vX.Y.Z directory. It appears idf.py expects python_env directory under IDF_TOOLS_PATH, so I had to set IDF_TOOLS_PATH to a directory and run python idf_tools.py install-python-env. I ended up using esp-idf-vX.Y.Z\tools as IDF_TOOLS_PATH, keeping everything bundled up. Alternatively, you can try going your own way buy creating a venv and using pip to install whatever is in $IDF_TOOLS_PATH\requirements\requirements.core.txt. By the way, you can see environment variables in powershell by using gci env:* and set them using $env:KEY = VALUE.

Once idf_tools.py installs the environment with its dependencies, you can activate the virtual environment it created, create your build directory, and run cmake -G Ninja /path/to/project/dir and then ninja in your build directory.

Congratulations! Now you have a bin and an elf file.

To upload the firmware, I used idf.py flash (make sure the virtual env is activated). Unfortunetaly, ESP32 doesn't support dfu-util. To monitor the serial connection, I'm using PuTTY (see Device Manager for serial port number COM<N>) with baud rate of 115200. Both idf.py flash and serial monitor use the serial port, so monitor has to be closed before flashing.

Linux

I prefer to work on Linux and so the setup was a bit easier. On linux I opted to use the master branch of their git repository rather than a release version.

1. Install the required packages, download crosscompiling toolchain, binutils for esp32, openocd for esp32, and ESP-IDF (clone recursively).

2. Add their respective paths to PATH. I added the following snippet in my $HOME/.profile.

   for d in $(find /home/armin/pkgs/esp32 -name bin -type d); do
       PATH="$d:$PATH";
   done
   
   IDF_PATH="$HOME/pkgs/esp32/esp-idf"
   IDF_TOOLS_PATH="${IDF_PATH}/components/esptool_py/esptool"
   IDF_TOOLS_PATH="${IDF_TOOLS_PATH}:${IDF_PATH}/components/espcoredump"
   IDF_TOOLS_PATH="${IDF_TOOLS_PATH}:${IDF_PATH}/components/partition_table"
   IDF_TOOLS_PATH="${IDF_TOOLS_PATH}:${IDF_PATH}/tools"
   
   PATH="${IDF_TOOLS_PATH}:$PATH"

3. If you're using ubuntu, also install python-is-python3 to squash the error about missing python.

4. Install python packages from esp-idf's requirements.txt.

5. idf.py menuconfig also requires libncurses header files (libncurses-dev in ubuntu).

Once all the tools are downloaded and added to PATH, we can compile and run a sample project. Make sure to add your user to group dialout if required. Check permissions on /dev/ttyUSB# and see what permissions are required to write into it.

To use the serial port on WSL, look into device manager and make a note of the COM port. The serial port on my setup is noted as Silicon Labs CP210x USB to UART Bridge which is the chipset used on the ESP32 kit I'm using (DevKitC-VE v4). Then within WSL, you can use /dev/ttyS# where # is the COM port number.

Next steps

Now you can configure Emacs and lsp for ESP32 development. Don't forget to configure esp32 for jtag debugging. I initially opted to use ESP-Prog board to debug the ESP32-DevKitC board I had, but I eventually upgraded to a WROVER-Kit as you can't program the ESP32-DevKitC board with the programming interface available on the esp-prog board. Jtag could be used to program the board through esp-prog (or any other ft2232 kit), but WROVER kit made things simpler to setup.

Footnotes