㈚

ESP-IDF

  • esp32
  • c

Working with Espressif’s official toolkit

Official docs: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/index.html
Version notes: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/versions.html

Intro

This document gives succinct installation & setup information for ESP-IDF with VSCode, and a few useful tips & warnings.

Note: This was written while v5.5.1 was the latest. Change the scripts as appropriate.

What about Arduino?

Use it as a component inside ESP-IDF.

What about PlatformIO?

ESP32 development on PlatformIO is dead and buried.

Installation Goals

  • ESP-IDF framework directory (default: ~/esp/esp-idf)
  • ESP-IDF tools directory
  • Plugin for VSCode
  • A USB-Serial driver (often included in your OS)
  • A couple of environment variables

Warning: The tools directory will also include a python virtual environment, which is rather important, as it will be used for compiling and tools. Make very sure you know which python is being used to create it.

Prerequisites

GCC, python, cmake ninja, ccache.

I strongly recommend using your system version of python, not an alias from pyenv or whatever. Too many things are hard-coded, especially on Windows. You’ve been warned.

MacOS

brew install cmake ninja dfu-util

Debian/Ubuntu

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

Arch

sudo pacman -S --needed gcc git make flex bison gperf python cmake ninja ccache dfu-util libusb python-pip

Windows

Just use the installer, below.

Installation

MacOS/Linux

Framework

Repo: https://github.com/espressif/esp-idf

The recommended installation location is ~/esp/vX.X.X, but you can use whatever you want.

mkdir -p ~/esp
cd ~/esp
git clone -b v5.5.1 --recursive https://github.com/espressif/esp-idf.git

Tools

Warning: installation directory will be ~/.espressif unless you optionally override it with an environment variable. (Change the below path to what you want).

Tip: Save some time later by installing the files for the esp32 versions you plan to develop with. Comma-separated example here, or use “all”.

cd ~/esp/v5.5.1
export IDF_TOOLS_PATH="$HOME/required_idf_tools_path"
export IDF_GITHUB_ASSETS="dl.espressif.com/github_assets"
./install.sh esp32,esp32s3,esp32c6

Environment variables

Make sure these are sane and sourced before moving on.

IDF_PATH=~/esp/v5.5.1
IDF_TOOLS_PATH=~/.espressif

export.sh

Important: The export script sets up a virtual environment required for all tools and compilation. It must be sourced with the same version of python you used to create it.

. $HOME/esp/v5.5.1/export.sh

Verify it worked

idf.py --version

Warning: If this does not work. Go back and fix it now.

For convenience, you might want to put an alias in .bash_profile/.zprofile, but only activate it when you’re working with ESP-IDF:

alias get_idf='. $HOME/esp/v5.5.1/export.sh'

Windows

Warning: As of this writing, the Windows installation scripts are inconsistent, use hard-coded paths, and the documentation often does not match the scripts. Therefore, I strongly recommend using the VSCode plugin to install and manage the framework for you.

VSCode Plugin

Note: Eclipse is also a fine option, but I don’t use it, so I have not tried to document it.

Install the official ESP-IDF Extension from Espressif Systems.

Docs: https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/ Marketplace: https://marketplace.visualstudio.com/items?itemName=espressif.esp-idf-extension Repo: https://github.com/espressif/vscode-esp-idf-extension

Use either VSCode commands or open the new ESP-IDF pane on the left, and choose Configure ESP-IDF Extension.

MacOS/Linux

“Use Existing Setup”, enter paths.

Windows

“Express installer”. Really. Change the framework directory if you like, but do not change the tools directory.

USB-Serial Driver (if necessary)

Tip: Most operating systems have these built in. Ignore this section unless you need them.

Most esp32s use CP210x chipset. A few use the CH340/CH341 chip requiring the CH9102 driver. Check the product notes, or look on the board itself.

Warning: Always get your drivers straight from the chip manufacturer.

CP210x: https://www.silabs.com/software-and-tools/usb-to-uart-bridge-vcp-drivers?tab=downloads

CH9102: - WIndows: http://www.wch.cn/downloads/CH343SER_ZIP.html - MacOS: http://www.wch.cn/downloads/CH34XSER_MAC_ZIP.html - Linux: https://www.wch-ic.com/downloads/CH341SER_LINUX_ZIP.html

Useful Tools

idf.py

idf.py is a command-line python script that handles configuration, building, etc. Most commands are also handled by VSCode commands.

Docs: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/tools/idf-py.html

Enable the virtual environment, then:

idf.py --help

idf.py menuconfig

You’ll likely need to (often) run menuconfig to set esp32 system options.

Common uses are setting CPU speed, RAM configuration, and enabling/disabling firmware modules.

You can use the GUI by running the VSCode command “ESP-IDF: SDK Configuration Editor (Menuconfig)” or in a terminal:

Enable the virtual environment, go to your project directory, then:

idf.py menuconfig

esptool

esptool reads and writes to esp32s.

docs: https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/basic-commands.html

It can also simply get information about your chip:

esptool flash-id

Projects

idf.py create

Examples

The ESP-IDF example projects are all quite good, and they all work. Don’t edit them directly — use the VSCode command “ESP-IDF: Create Project from Extension Template”.

CMakeLists.txt

There is one CMakeLists.txt for the project and another in main. (And more if you add components). The vast majority of the time, you’ll only be changing the one in the main directory.

Inside the idf_component_register command, you’ll need to define SRCS (your c files), INCLUDE_DIRS (for header files), PRIV_REQUIRES (drivers), etc.

Full documentation for this file is at: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/build-system.html

Compiling

idf.py create

But generally, you’re fine just letting the extension run your builds. Look on the bottom row of your window. Make sure:

  • The desired version of ESP-IDF is chosen
  • UART for basic install, change to JTAG if you own a debugger
  • The correct serial port
  • The target esp version (e.g. esp32s3)

And hit the little flame icon: “ESP-IDF: Build, Flash and Monitor”

Tip: If you see gibberish in your output window, make sure the baud rate matches everywhere (program, menuconfig, VSCode, etc.)

EOF