Как настроить VS Code для ESP32 и ESP8266: два способа

Чтобы настроить VS Code для ESP, сначала определите точную плату и программный стек. ESP32, ESP32-S3, ESP32-C3 и ESP8266 нельзя считать одной и той же целью сборки. А проект Arduino и проект ESP-IDF могут использовать разные версии библиотек, команды и структуру каталогов.

Ниже два маршрута. Для разработки ESP32 на официальном SDK используем ESP-IDF. Для учебных Arduino-проектов на ESP32 или ESP8266 покажем PlatformIO. Выбирайте один маршрут для первого проекта, чтобы не отлаживать одновременно два установщика и две конфигурации.

Что проверить до установки расширений

Посмотрите маркировку модуля и документацию именно вашей платы. Запишите модель чипа, вариант платы и способ USB-подключения. У разных плат отличаются USB-UART преобразователи, доступные порты и возможности аппаратной отладки.

Для первого запуска нужны USB-кабель с передачей данных, стабильное питание и доступный последовательный порт. Кабель только для зарядки может питать плату, но компьютер не увидит её как устройство для прошивки.

Используйте учебную плату, содержимое которой можно заменить. Загрузка программы перезаписывает прошивку; не экспериментируйте на устройстве с нужными настройками без понимания процедуры восстановления. Подключение периферии и уровни напряжений проверяйте по документации платы, а не по случайной схеме для похожего ESP.

Какой путь выбрать

Задача	Стартовый вариант
Изучить официальный SDK семейства ESP32	Расширение Espressif ESP-IDF
Запустить Arduino-пример на поддерживаемой плате	PlatformIO с framework Arduino
Продолжить существующий проект	Его зафиксированный стек и версии
Работать с ESP8266	Поддерживаемая конфигурация ESP8266, например PlatformIO/Arduino

ESP8266 не нужно настраивать как обычную цель актуального ESP-IDF для ESP32. В PlatformIO для него существует отдельная платформа espressif8266. Конкретный пример NodeMCU ниже не подходит автоматически любой плате на ESP8266.

Вариант 1: ESP-IDF и официальный установщик

В VS Code установите ESP-IDF от Espressif Systems, идентификатор espressif.esp-idf-extension. Затем выполните в палитре команд:

ESP-IDF: Open ESP-IDF Installation Manager

Через Installation Manager установите совместимую с проектом стабильную версию ESP-IDF и необходимые инструменты. Не назначайте автоматически самую новую версию старому проекту: сначала изучите его требования и руководство миграции.

После установки используйте ESP-IDF: Select Current ESP-IDF Version. Расширение обнаруживает установки через файл конфигурации менеджера. Для диагностики доступна ESP-IDF: Doctor Command. Такой порядок приведён в актуальной инструкции Espressif.

Не прописывайте вручную десяток путей Python и компиляторов из старого руководства, если установщик уже подготовил согласованный набор. Если обнаружена не та версия, проверьте выбранный ESP-IDF и оставшиеся переменные окружения: ручная конфигурация может влиять на выбор инструментов.

Создайте ESP-IDF-проект и выберите чип

Выполните ESP-IDF: New Project, выберите установленный SDK и пример hello_world. Укажите новую папку проекта, правильные IDF_TARGET, плату и порт. Для классического ESP32 цель отличается от ESP32-C3 и ESP32-S3; выбирайте по устройству, а не по названию статьи.

Откройте созданный проект целиком. В корне должен находиться его CMakeLists.txt. Если открыть только файл из main, расширению будет не хватать контекста сборки. Настройка мастера описана в Create an ESP-IDF Project.

Соберите пример через команду сборки расширения. Либо откройте подготовленный ESP-IDF-терминал, в котором уже доступны инструменты, и выполните из корня проекта:

idf.py build

Сначала добейтесь успешной сборки без платы. Это позволяет отделить проблемы SDK от USB-подключения.

Прошейте плату и проверьте вывод

Укажите последовательный порт своего устройства. Пример для Windows с условным портом COM5:

idf.py -p COM5 flash monitor

В Linux порт может называться /dev/ttyUSB0 или /dev/ttyACM0, в macOS имя тоже зависит от устройства. Не копируйте COM5, если ваша плата появилась под другим номером. Убедитесь, что прошиваете именно выбранную учебную плату.

После загрузки в мониторе ожидается вывод примера hello_world. Из монитора ESP-IDF выходят через Ctrl+]. Команды сборки, загрузки и просмотра вывода описаны в ESP-IDF Programming Guide.

Если сборка успешна, но подключения нет, не переустанавливайте SDK сразу. Проверьте кабель, порт, драйвер USB-UART, отсутствие другого открытого монитора и предусмотренную изготовителем процедуру входа в загрузчик.

Вариант 2: PlatformIO для Arduino-проекта

Установите официальное расширение PlatformIO IDE, идентификатор platformio.platformio-ide. Дождитесь окончания первоначальной установки. Откройте PlatformIO Home → New Project, выберите точную плату и framework Arduino.

Отдельно устанавливать PlatformIO Core для этого маршрута обычно не требуется: он входит в расширение. При необходимости командной строки откройте терминал PlatformIO. Установка и задачи Build/Upload/Monitor описаны в руководстве PlatformIO для VS Code.

Пример platformio.ini для классического ESP32 Dev Module:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200

Идентификатор esp32dev относится к ESP32 Dev Module. Для ESP32-S3 или ESP32-C3 найдите соответствующую плату в каталоге и используйте её конфигурацию.

Для NodeMCU 1.0 (ESP-12E Module) на ESP8266 пример другой:

[env:nodemcuv2]
platform = espressif8266
board = nodemcuv2
framework = arduino
monitor_speed = 115200

Этот board ID подтверждается карточкой NodeMCU в PlatformIO. Для Wemos D1 mini или другой платы не оставляйте nodemcuv2 только из-за общего чипа.

В первом проекте достаточно одного блока окружения. В репозитории, который должен воспроизводиться через полгода, после успешной проверки зафиксируйте проверенные версии платформы и зависимостей. Примеры выше выбирают платформу без номера версии и потому сами по себе не гарантируют неизменный набор пакетов при будущей установке.

Первый пример: сообщение в Serial Monitor

В Arduino-проекте создайте или измените src/main.cpp:

#include <Arduino.h>

void setup() {
    Serial.begin(115200);
}

void loop() {
    Serial.println("COMRAD404: device is running");
    delay(1000);
}

Используем вывод в порт вместо мигания встроенным светодиодом: наличие LED и его GPIO зависят от платы. Для поддерживаемого Arduino-окружения пример должен регулярно печатать сообщение. Особенности native USB на отдельных вариантах ESP32 проверяйте отдельно по плате и настройкам framework.

Запустите Build, затем Upload и Serial Monitor. Те же действия доступны из терминала PlatformIO:

pio run
pio run --target upload
pio device monitor --baud 115200

Если настроено несколько окружений, выбирайте нужное явно или задайте default_envs. Не отправляйте сборку для одной платы на другую. Скорость монитора должна совпадать с Serial.begin(115200); ошибки чтения строк ещё не доказывают поломку прошивки.

Типичные ошибки и границы настройки

Симптом	Что проверить
Плата питается, но порта нет	Передаёт ли кабель данные, нужен ли USB-UART драйвер
`idf.py` не найден	Открыт ли подготовленный терминал выбранного ESP-IDF
`pio` не найден	Завершена ли установка; используется ли терминал PlatformIO
Порт занят	Не открыт ли Serial Monitor в другом приложении
Неверный чип при прошивке	IDF_TARGET или `board` в конфигурации
Успешная прошивка, но нет сообщения	Порт, скорость, перезапуск платы и USB-режим
Не работает breakpoint	Нужны ли JTAG/USB-JTAG и поддерживаемая конфигурация отладки

Обычное USB-подключение для прошивки не всегда даёт аппаратную отладку. Например, у описанного ESP32 Dev Module нет встроенного debug probe по карточке PlatformIO. Для F5 могут потребоваться отдельный адаптер и подходящие подключения.

Первый результат настройки: проект собирается под правильный чип, загружается на нужную плату, и вы видите ожидаемый вывод. Проверка на реальном устройстве обязательна для вашей комбинации платы, кабеля и драйвера; одних валидных файлов конфигурации недостаточно. После этого можно добавлять периферию и сохранять рабочую версию проекта в Git.