Basics of Design CC Blog Design Solutions Research & Design Hub

How to Program an ESP32

Written by Pedro Bertoleti

Using VS Code and ESP-IDF

In this article, I’ll show how to program an ESP32 System-on-a-Chip (SoC) using VS Code and ESP-IDF together as a development environment. This combination allows the developer to take full advantage of all the official libraries, APIs, and tools available in ESP-IDF, while enjoying the good-looking and intuitive VS Code integrated development environment (IDE). Together, these tools make software development for the ESP32 a more comfortable and productive process.

  • How can I program an ESP32?
  • What are the advantages of using VS Code and ESP-IDF together?
  • What is the best IDE for ESP32?
  • ESP32
  • VS Code
  • ESP-IDF
  • Espressif Systems
  • Visual Studio Code

The ESP32 System-on-a-Chip (SoC) has lately received a lot of attention as a target hardware choice for embedded systems projects. It offers enticing hardware—WI-FI and Bluetooth, powerful CPUs (up to two cores, both running up to 240MHz), and a good amount of RAM (from 320kB SRAM to 8MB PSRAM options, depending on the model)—all at an affordable price. It’s a state-of-the-art SoC for embedded and connected solutions, especially those involving the Internet of Things (IoT).

With any microcontroller (MCU) and SoC, good documentation and a good development environment are as important as the hardware’s capabilities. Fortunately, ESP32 has these too. This article covers how to comfortably and efficiently program ESP32 series SoCs with an integration of ESP-IDF and VS Code. I’ll also detail an example project that uses this combined development environment.

VS CODE

If you’re unacquainted, allow me to introduce you to Visual Studio Code, or VS Code, developed by Microsoft. VS Code consists of a light source code editor and an integrated development environment (IDE). There are also a lot of extensions, most of which are available for free—VS Code can be much more than just a text editor. All kinds of developers use VS Code to write code for a large variety of languages and projects—from simple web applications to complex embedded software solutions.

VS Code behaves much like a miniature version of the well-known Visual Studio. But it’s faster to launch, lighter to use, and a more efficient development environment than the full-size Visual Studio. VS Code can also run smoothly even in low-end machines. And although it’s a light text editor, it has many useful and intuitive features that simplify code writing, such as auto-complete, syntax highlighting, automatic suggestions to fix typos and errors in the code, and much more.

VS Code is free to use and available for every popular operating system (OS) around, such as Windows, Linux, and macOS. Also, it’s highly customizable, with many available extensions, making it a great IDE option for every programming language and for different software development needs (such as embedded software development for the ESP32).

Further, VS Code offers interesting visual/theme options. Of course, this doesn’t necessarily affect the software development itself, but as many developers can attest, a comfortable theme can matter when you’re writing code for many hours. Figure 1 shows an example VS Code, in this case as a development environment for the ESP32.

FIGURE 1
A speed comparison between a hard-disk drive, solid-state drive, and RAM disk drive.
FIGURE 1
A speed comparison between a hard-disk drive, solid-state drive, and RAM disk drive.
ESP-IDF

The ESP-IDF is Espressif System’s official IoT Development Framework for the ESP32, ESP32-S, ESP32-C, and ESP32-H series SoCs. It provides a powerful software development kit (SDK) for any generic application development on ESP32 devices, using as programming languages C and C++. Importantly, ESP-IDF is open-source, and a link to its repository (which contains useful examples) can be found at Circuit Cellar’s Article Materials and Resources webpage [1]. That page also has a link to ESP-IDF’s full documentation [2].

ESP-IDF allows developers to explore the full power of ESP32 series SoCs, allowing them to use ESP32’s complex features, such as the ability to:

  • change specific configurations, like Flash parametrization (clock frequencies, type of Flash, Flash partition, and so forth), RAM parametrization (size, type, and so forth), CPU clock configuration, and more.
  • enable and configure security features in ESP32, like secure boot and Flash encryption.
  • enable and configure connectivity support, from network names and passwords to encryption communication parameters.
  • enable and configure hardware resources, such as GPIOs, PWM outputs, analog inputs and outputs, USART, I2C, and so on.

Besides all the libraries, APIs, and examples that ESP-IDF offers to the developer, two particular items that make this development framework easy to use and scalable: its configuration source code tool, and its build system.

Configuration source code tool: ESP-IDF uses menuconfig, a well-known tool for configuring source code, which allows a huge number of customizations that are easy to apply. This is the same configuring interface used by several famous open-source projects, like Linux kernel, Apache NuttX, and Buildroot. The menuconfig tool allows developers to configure every aspect of the current project that uses ESP-IDF as a framework. See Figure 2 for an example of what menuconfig looks like.

FIGURE 2
Example of the menuconfig interface used for ESP-IDF for source code configuration
FIGURE 2
Example of the menuconfig interface used for ESP-IDF for source code configuration

Build system: There are three items ESP-IDF uses to compile ESP32 projects, and to flash an ESP32:

  • CMake, which configures the ESP32 project to be built;
  • Ninja, which builds the project for the selected ESP32 target;
  • esptool.py, a Python tool for flashing ESP32 series SoCs.

In practical terms, developers must populate CMake files with all the project source files, specific configurations, and extra modules that must be taken into consideration during the compilation process, and then the ESP-IDF build system does all the rest to generate the binaries to be flashed into the ESP32. For those who are familiar with using CMake and Ninja to compile solutions for embedded Linux and embedded Android, it will be straightforward to compile ESP32 projects using ESP-IDF.

SETTING UP VS CODE WITH ESP-IDF

As I discussed in the introduction, it’s possible to use VS Code and ESP-IDF together to program your ESP32. In fact, they’re a match made in heaven. ESP-IDF lets you explore the full power of the ESP32, while the VS Code IDE provides a wealth of useful software development resources.

VS Code’s many extensions make it highly flexible and suited for a great variety of development environments, and ESP-IDF is no exception. The Espressif IDF extension (Figure 3) integrates ESP-IDF into VS Code, transforming VS Code into an IDE for ESP32 software development [3]. Let’s look at how to set this up.

FIGURE 3
Espressif IDF extension description
FIGURE 3
Espressif IDF extension description

Installing VS Code: One great thing about VS Code is its portability; you can use it in Windows, Linux, or macOS. (This makes it an especially excellent option for companies counting on developer teams from different software development strands.) You can get VS Code for free in your OS’s software store, or via its official website [4]. Its installation is straightforward.

Installing and configuring ESP-IDF extension for VS Code: Next, let’s install and configure the Espressif IDF extension for VS Code:

  1. In VS Code, click on the Extensions button, found in the configuration bar on the left side of the screen.
  1. Type “Espressif IDF” in the search box. It should be the first option listed, as in Figure 4.
  2. Click on Espressif IDF, and then click on the install button. Wait for the installation to complete.
  3. Before configuring the Espressif IDF extension, its prerequisites must be installed. Espressif has documentation covering this process [5]; the prerequisites and the methods to install them depend on the OS.
  4. Once the prerequisites are successfully installed, it’s time to configure the Espressif IDF extension. To do this, press the F1 key in VS Code, type “Configure ESP-IDF extension” and press the Enter key. This brings up the configuration screen. Select the “Express” option.
  5. On the “ESP-IDF version” drop-down list, select the ESP-IDF version that you’ll be using. I strongly recommend that you choose the most recently released version (as of the writing of this article, that’s v5.1.1). Click on the Install button.
  6. The installation will take a few minutes. After it’s finished, ESP-IDF is ready to be used with VS Code.
FIGURE 4
Espressif IDF search in VS Code
FIGURE 4
Espressif IDF search in VS Code
HELLO WORLD

Now let’s put it all together—from code, to software deployment, to testing—with a classic example project, “Hello, World!” This gets some hardware information from the ESP32 that runs it, and prints this information on verbose debug messages. To run through this example yourself, you will need:

  • An ESP32 module. I used a DOIT ESP32 DevKit v1 (Figure 5);
  • One micro USB to USB cable, which will be used to program and power DOIT ESP32 DevKit v1. If you are using a newer ESP32 DevKit, you might need a USB-C to USB cable instead.
FIGURE 5
DOIT ESP32 Devkit V1
FIGURE 5
DOIT ESP32 Devkit V1

Now, to create the Hello World project:

  1. In VS Code, press the F1 key, type “example projects” and press the Enter key.
  2. If asked to choose which ESP-IDF to use, select the “Use current ESP-IDF” option.
  3. A new tab will appear in VS Code, presenting all the available example project options (Figure 6). Click on “hello_world” (highlighted in blue in Figure 6), and then click on the “Create project using example hello_world” button (highlighted in red in Figure 6).
  4. You’ll be asked to choose where to save the project. Choose a suitable folder to save it.
  5. Now, your Hello World project for ESP32 is created. All the source files of these projects can be accessed in the source code tree, which is found on the left side of the screen (Figure 7).
FIGURE 6
Example projects available for ESP-IDF and VS Code
FIGURE 6
Example projects available for ESP-IDF and VS Code
FIGURE 7
Source code tree of the Hello World example project
FIGURE 7
Source code tree of the Hello World example project

With these steps completed, let’s take a closer look at the source code. All the source code needed to understand what the Hello World example does is in the hello_world_main.c file. It contains only one function, named app_main(). This is the first function executed in every application source code in the projects that use ESP-IDF. For Hello World, the implementation of this function does the following:

  1. Print “Hello world!” in verbose debug messages.
  2. Acquire and print (in debug messages) some information about the ESP32 hardware, including the ESP32 chip type, the number of CPU cores it contains, and which connectivities (WiFi, Bluetooth, and/or Bluetooth Low Energy) it supports. The app_main() function also obtains and prints the silicon revision number, the amount and type (embedded or external) of Flash memory, and the minimum allowed heap size. These operations are shown in Listing 1.
  3. Finally, after a 10-second countdown, the ESP32 restarts (see Listing 2).
LISTING 1
Getting ESP32 hardware information

esp_chip_info_t chip_info;   esp_chip_info(&chip_info);   printf(“This is %s chip with %d CPU core(s), WiFi%s%s, “,        CONFIG_IDF_TARGET,        chip_info.cores,        (chip_info.features & CHIP_FEATURE_BT) ? “/BT” : “”,        (chip_info.features & CHIP_FEATURE_BLE) ? “/BLE” : “”);   printf(“silicon revision %d, “, chip_info.revision);   printf(“%dMB %s flash\n”, spi_flash_get_chip_size() / (1024 * 1024),        (chip_info.features & CHIP_FEATURE_EMB_FLASH) ? “embedded” : “external”);    printf(“Minimum free heap size: %d bytes\n”, esp_get_minimum_free_heap_size());
LISTING 2
10-second countdown and ESP32 restart operations

for (int i = 10; i >= 0; i--) {      printf(“Restarting in %d seconds...\n”, i);      vTaskDelay(1000 / portTICK_PERIOD_MS);   }   printf(“Restarting now.\n”);   fflush(stdout);   esp_restart();

You need to be aware of a few settings and important features in order to compile and test the Hello World program correctly—these are all found in the blue status bar located at the bottom of VS Code (Figure 8). As you can see in Figure 8, I’ve numbered items that are important for developing and testing ESP32 software.

FIGURE 8
Status bar, containing some important buttons/settings to program the ESP32
FIGURE 8
Status bar, containing some important buttons/settings to program the ESP32

Button 1: This is UART/COM port for ESP32 communication. By clicking it, you can configure which UART/COM port will be used to communicate to your ESP32, in order to flash it and get its debug messages. But before clicking, make sure your ESP32 DevKit is connected to one of the available USB ports in your computer. In my case, as shown in Figure 8, DOIT ESP32 Devkit V1 is connected to the COM3 port.

Button 2: This is the target ESP32 chip to compile. As the official software development framework for ESP32, ESP-IDF supports all ESP32 series SoCs. Clicking this button allows you to select the target ESP32 series SoC for which the software will be compiled. In the case of the DOIT ESP32 Devkit v1, the target “esp32,” as seen in Figure 8.

Button 3: This cleans the ESP32 compilation—sometimes, due to specific compilation errors, we need to clean all compilation files so as to ensure the next compilation will be made from scratch. In VS Code with ESP-IDF, this is as simple as clicking this button.

Button 4: To compile the software for the selected ESP32 target, click this button.

Button 5: After successfully compiling the software, the next step is to flash it to your target ESP32. This can be done by using this button.

Button 6: After successfully flashing the software into your ESP32, click this button to get all its debug messages; a terminal screen will appear in VS Code containing all the messages generated by the software you just flashed.

Once all the relevant settings are okay, it’s time to compile the software (Button 4 in Figure 8). It may take a few minutes to complete, after which a summary, including final binary metrics, will be shown on the terminal screen (Figure 9). Now, the software is ready to be flashed into the ESP32 (Button 5 in Figure 8).

FIGURE 9
Compilation summary of Hello World project
FIGURE 9
Compilation summary of Hello World project

Once done, the message “Flash Done” will appear on the terminal screen. At this point, your ESP32 has the Hello World project flashed on it, and is already running the software. All that’s left is checking the debug messages (Button 6 in Figure 8). You should see something like that shown in Figure 10.

FIGURE 10
Debug messages of the Hello World project
FIGURE 10
Debug messages of the Hello World project
CONCLUSION

This concludes my introduction to VS Code and ESP-IDF. In my opinion, they make for a powerful combination of development tools, and, together, provide a comfortable and simplified development environment for ESP32 applications, regardless of the OS you’re using. Using VS Code with ESP-IDF enables the development of highly scalable solutions. Thus, I hope this article serves as a solid starting point for larger and more complex ESP32 solutions. 

REFERENCES
[1] ESP-IDF GitHub Repository: https://github.com/espressif/esp-idf
[2] ESP-IDF Programming Guide: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/
[3] “Getting Started with VS Code IDE,” Espressif: https://docs.espressif.com/projects/esp-idf/en/v4.2.3/esp32/get-started/vscode-setup.html
[4] Visual Studio Code Official Website: https://code.visualstudio.com/
[5] “Step 1: Install Prerequisites,” Espressif: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html#get-started-prerequisites

RESOURCES
Espressif Systems | www.espressif.com
Visual Studio Code | code.visualstudio.com

Code and Supporting Files

PUBLISHED IN CIRCUIT CELLAR MAGAZINE • DECEMBER 2023 #401 – Get a PDF of the issue

Keep up-to-date with our FREE Weekly Newsletter!

Don't miss out on upcoming issues of Circuit Cellar.


Note: We’ve made the Dec 2022 issue of Circuit Cellar available as a free sample issue. In it, you’ll find a rich variety of the kinds of articles and information that exemplify a typical issue of the current magazine.

Would you like to write for Circuit Cellar? We are always accepting articles/posts from the technical community. Get in touch with us and let's discuss your ideas.

Sponsor this Article

Supporting Companies

Upcoming Events


Copyright © KCK Media Corp.
All Rights Reserved

Copyright © 2024 KCK Media Corp.

How to Program an ESP32

by Pedro Bertoleti time to read: 10 min