Программирование ESP32 на ESP-IDF в VS Code: вводное руководство

Перевод статьи Programming ESP32 with ESP-IDF using VS Code – Getting Started Guide — Rui Santos & Sara Santos, Random Nerd Tutorials.

В этом руководстве вы научитесь программировать платы ESP32 с помощью ESP-IDF (Espressif IoT Development Framework). ESP-IDF разработан компанией Espressif и предназначен для создания IoT-приложений с Wi-Fi, Bluetooth, управлением питанием и рядом других возможностей. Ставить ESP-IDF будем в VS Code (Microsoft Visual Studio Code); рассмотрим подготовку под Windows, macOS и Linux Ubuntu.

Знакомимся с ESP-IDF#

ESP-IDF (Espressif IoT Development Framework) — это «родной» фреймворк, разработанный самой Espressif (создателем чипов ESP32) для их программирования. Это SDK для разработки приложений под чипы ESP32 на языках C и C++, дающий низкоуровневый доступ к железу.

Будучи «официальным» способом программирования ESP32, SDK часто обновляется под выход новых версий чипов ESP32 — тогда как в Arduino IDE поддержка новых чипов может появляться с задержкой. Текущие поддерживаемые ESP-IDF серии SoC:

• ESP32;
• ESP32-S2, ESP32-S3;
• ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61;
• ESP32-H2;
• ESP32-P4.

ESP-IDF или Arduino IDE?#

По сравнению с Arduino IDE, ESP-IDF даёт больше возможностей для настройки, производительности и контроля над периферией, конфигурациями и задачами ESP32. Он использует ОС реального времени (FreeRTOS) с программированием на основе задач, тогда как Arduino IDE опирается на связку setup()/loop().

ESP-IDF заметно сложнее в использовании. Нужно куда глубже понимать, как работают система и железо, и разбираться с конфигурациями управления памятью, задачами FreeRTOS, инициализацией периферии и прочим. Эта сложность даёт больше контроля, но и повышает шанс столкнуться с ошибками и проблемами конфигурации. Поэтому, если вы не знакомы с Arduino IDE или только начинаете с ESP32, пока браться за ESP-IDF мы не рекомендуем.

Установка VS Code#

Зайдите на code.visualstudio.com и скачайте стабильную сборку под свою ОС (Windows, macOS или Linux). На Windows запустите мастер установки, примите соглашение и пройдите все шаги. На macOS перетащите приложение в папку Applications. На Linux Ubuntu установите скачанный .deb из терминала:

$ cd Downloads
~/Downloads $ sudo apt install ./code_1.49.1-1600299189_amd64.deb

Откройте VS Code — вас встретит вкладка Welcome.

Установка Python#

Для программирования ESP32 на ESP-IDF нужен установленный Python 3.14.X или новее.

• Windows: скачайте Python 3.14.X с python.org/downloads. Важно: отметьте галочку Add Python to PATH, затем нажмите Install Now.
• macOS: установите через Homebrew — brew install python3.
• Linux Ubuntu: проверьте версию python3 --version; при необходимости sudo apt install python3, а также sudo apt install python3-distutils.

Установка расширения ESP-IDF для VS Code#

Чтобы получить доступ к инструментам ESP-IDF, установите официальное расширение ESP-IDF:

1. откройте VS Code и нажмите иконку Extensions на левой панели (или Ctrl+Shift+X);
2. найдите «ESP-IDF»;
3. выберите ESP-IDF by Espressif Systems;
4. нажмите Install.

Нажмите Trust Publisher & Install, затем при необходимости Trust Workspace & Install. Установка займёт некоторое время.

Менеджер установки ESP-IDF#

Дальше настроим расширение:

1. откройте панель расширения ESP-IDF и разверните меню Advanced;
2. выберите Open ESP-IDF Installation Manager;
3. выберите зеркало Github;
4. запустите менеджер установки инструментов ESP-IDF.

Откроется окно менеджера установки — нажмите Start Installation. Если сообщат о недостающих требованиях (prerequisites), их можно установить автоматически. Затем доступен мастер «Easy Installation» (только выбор версии ESP-IDF); в руководстве используется «Custom Installation», чтобы пройтись по всем опциям.

Рекомендуем выбрать вариант All, чтобы установить поддержку всех вариантов чипов ESP32.

На экране выбора версии выберите ESP-IDF. На момент написания последняя версия — v6.0.2; рекомендуем версию 6.X. Можно оставить зеркала загрузки по умолчанию. Для большинства пользователей достаточно пакетов core и инструментов по умолчанию. Выберите папку установки кнопкой Browse и запустите установку.

В зависимости от скорости интернета и железа установка может занять больше часа — наберитесь терпения. По завершении нажмите Exit Installer.

Установка расширений C/C++ (необязательно)#

Шаг необязательный, но, поскольку с ESP-IDF вы программируете на C++, рекомендуем поставить расширения C/C++: откройте вкладку Extensions, найдите «C/C++» и установите первую опцию (можно также «C/C++ Extension Pack»).

Hello World на ESP-IDF в VS Code#

Установка ESP-IDF идёт с большой папкой примеров. Для первого запуска соберём и прошьём базовый Hello World.

1. откройте расширение ESP-IDF и разверните меню Advanced;
2. выберите New Project Wizard;
3. выберите Use ESP-IDF v6.0.2.

В левой панели, в ESP-IDF Examples folder, разверните раздел get-started и откройте пример hello_world. Откроется страница с описанием примера; вверху нажмите Create project using template hello_world.

Заполните поля:

• Project Name — имя проекта;
• Enter Project Directory — папка проекта. Не используйте папки Google Drive / OneDrive / Dropbox — при сборке создаётся много файлов, и в облачной папке это будет крайне медленно;
• ESP-IDF Target — целевой чип (в примере — esp32s3);
• ESP-IDF Board — для esp32s3 выберите конфигурацию ESP32-S chip (via builtin USB-JTAG);
• Serial Port — COM-порт вашего ESP32 (или оставьте автоопределение);
• Create Project — синяя кнопка создания.

Откроется окно с предложением открыть проект в новом экземпляре VS Code. Если внизу слева появится сообщение Restricted Mode — нажмите на него и добавьте папку проекта в доверенные. После этого внизу окна появится панель инструментов ESP-IDF.

Открыть код примера: откройте проводник проекта (первая иконка слева), разверните папку HELLO_WORLD и раздел main, кликните файл hello_world_main.c.

Полный код hello_world_main.c:

// SPDX-FileCopyrightText: 2010-2022 Espressif Systems (Shanghai) CO LTD
// SPDX-License-Identifier: CC0-1.0

#include <stdio.h>
#include <inttypes.h>
#include "sdkconfig.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_chip_info.h"
#include "esp_flash.h"
#include "esp_system.h"

void app_main(void)
{
    printf("Hello world!\n");

    /* Print chip information */
    esp_chip_info_t chip_info;
    uint32_t flash_size;
    esp_chip_info(&chip_info);
    printf("This is %s chip with %d CPU core(s), %s%s%s%s, ",
           CONFIG_IDF_TARGET,
           chip_info.cores,
           (chip_info.features & CHIP_FEATURE_WIFI_BGN) ? "WiFi/" : "",
           (chip_info.features & CHIP_FEATURE_BT) ? "BT" : "",
           (chip_info.features & CHIP_FEATURE_BLE) ? "BLE" : "",
           (chip_info.features & CHIP_FEATURE_IEEE802154) ? ", 802.15.4 (Zigbee/Thread)" : "");

    unsigned major_rev = chip_info.revision / 100;
    unsigned minor_rev = chip_info.revision % 100;
    printf("silicon revision v%d.%d, ", major_rev, minor_rev);
    if(esp_flash_get_size(NULL, &flash_size) != ESP_OK) {
        printf("Get flash size failed");
        return;
    }

    printf("%" PRIu32 "MB %s flash\n", flash_size / (uint32_t)(1024 * 1024),
           (chip_info.features & CHIP_FEATURE_EMB_FLASH) ? "embedded" : "external");

    printf("Minimum free heap size: %" PRIu32 " bytes\n", esp_get_minimum_free_heap_size());

    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();
}

Сборка и прошивка Hello World на ESP32#

Чтобы собрать и прошить код ESP-IDF: выберите метод прошивки (UART), COM-порт, целевой чип (ESP32), соберите код и прошейте на плату. Все команды — в нижней панели VS Code.

Если настройки неверны: кликните иконку «звезды» и выберите метод прошивки UART; при подключённой плате кликните иконку COM-порта (розетка) и выберите порт; выберите целевой чип по иконке чипа (в примере — esp32s3) и конфигурацию ESP32-S chip (via builtin USB-JTAG).

В этом руководстве код мы не меняем, так что просто соберите проект кнопкой Build Project (иконка гаечного ключа). Первая сборка занимает чуть дольше; по завершении в терминале появится Build Successfully.

Последний шаг — прошить проект кнопкой Flash Device (иконка молнии). Возможно, потребуется зажать кнопку BOOT на плате. По завершении появится Flash Done.

Откройте терминал кнопкой Monitor Device (иконка экрана). Там будет печататься Hello world!, сведения о плате, и через 10 секунд плата перезагрузится — и так по кругу.

Изменить строку вывода можно в файле hello_world_main.c:

printf("Hello world!\n");

Устранение частых проблем#

COM-порт недоступен — нет драйверов. Если COM-порт ESP не виден, значит не установлены драйверы. Посмотрите на чип рядом со стабилизатором: у платы ESP32 DEVKIT V1 DOIT это CP2102, у многих других — CH340. После установки драйверов перезапустите VS Code.

Не удаётся прошить плату. Ошибка вида A fatal error occurred: Failed to connect to ESP32-S3: No serial data received. обычно значит, что плата не в режиме прошивки. Зажмите кнопку BOOT на ESP32, когда в окне отладки пойдут точки.

Неверный аргумент чипа. Ошибка This chip is ESP32-S3 not ESP32. Wrong --chip argument? — проверьте, правильно ли выбран целевой чип, затем выберите нужный, пересоберите и прошейте.

Итог#

В этом руководстве вы научились программировать ESP32 через фреймворк ESP-IDF в VS Code. ESP-IDF — официальный способ от Espressif; он даёт больше контроля над железом, но и сложнее в освоении. Это было базовое вводное руководство.

Спасибо за чтение.