I bought an ESP32 core board to play with. The appeal was straightforward: relatively high clock speed for an MCU, good performance, built-in Wi-Fi and Bluetooth, and a development toolchain that feels more modern than the usual embedded setup.
A couple of months earlier I had put together a project that used CMake in place of Keil uVision. Under the hood it still called the MDK-Arm toolchain from Keil through the command line, so I had a little CMake experience. VSCode was already installed, while Arduino IDE was not. I decided to skip Arduino IDE for ESP and start directly with ESP-IDF.
What is ESP-IDF?
At its core, ESP-IDF is Espressif's command-line development framework for its ESP MCUs. It bundles build, flash, configuration, and monitor/debug functions. It relies on CMake and Ninja, much like the Keil-to-CMake project I had set up before. One difference is that ESP-IDF's CMake files are mostly built from its own special functions, such as idf_build_set_property() and idf_component_register().
Getting ESP-IDF running
ESP-IDF needs CMake, Ninja, Python, and other tools, but you do not have to install each dependency manually. In fact, ESP-IDF prepares and uses its own environment; even if you have separate installations, it will not call those. The practical route is to install the ESP-IDF extension from the VSCode marketplace. After it installs, a welcome page appears. Click Configure Extension to open the extension's configuration page. If you miss that page, press F1 in VSCode and search for > ESP-IDF: configure ESP-IDF Extension. There you can select an ESP-IDF kit already downloaded on the computer or let the extension download one for you.
If this is your first time installing the extension and no ESP-IDF kit exists on the machine, you can click EXPRESS for a quick setup, or ADVANCED to choose a specific path. I would usually prefer the latter so I know where everything is being installed. If you later open another ESP project and the configuration page appears again, choose USE EXISTING SETUP to reuse the previous installation. The first download can take a while; later projects will not need to download it again.
Once configured, try flashing a minimal example. ESP-IDF ships with many sample projects. Go to the folder where ESP-IDF was installed, open examples, and find get-started/hello-world. Open that folder in VSCode, then configure, build, and flash your first ESP32 project.
At the bottom of the window, choose the build and flash settings that match your board. Mine came from an obscure online shop and is probably a non-official model. It has a CH340, no exposed JTAG interface, and only a USB Type-C connector, so I selected UART for flashing. For the port, I used the COM port that appeared in Device Manager after plugging the board in. For the Espressif target, I selected esp32/custom board, then built and flashed the project. The basic workflow was simple enough.
There was one hiccup: ESP-IDF reported that COM5 could not be opened. Yet when I used a serial tool such as SSCOM, I could read output from the program already flashed on the MCU over COM5. Looking closely at the ESP-IDF message, I saw that it said the MCU was not in download mode. After some digging, I found that GPIO0 needs to be held low during flashing; while it is low, pulling EN low and then high puts the chip into download mode. The core board schematic showed that GPIO0 and EN are connected to the BOOT and EN buttons. So the sequence was: hold BOOT, press EN, release EN, start flashing in ESP-IDF, and then release BOOT. That worked, and once flashing had started it did not matter when I let go of BOOT.
First impressions
The initial experience with ESP-IDF was quite positive. It looks more professional on the surface, but more importantly, using it with VSCode feels much better than working in an IDE as sluggish as Keil uVision.