Перейти к содержимому

Доброго времени, уважаемые читатели!

Прочитав данную статью, вы узнаете: как перестать беспокоиться и начать жить о том, что Arduino IDE теперь недоступна, и начать писать код для Arduino core for ESP32 в современной и удобной IDE под названием Visual Studio Code (или просто VSCode). С поддержкой IntelliSence, автодополнениями кода, форматированием и прочими плюшками. Но стоит оговорится, что данный метод подойдет только для ESP32 и иже с ними, “обычные Arduino” тут не подходят.

В данной статье я расскажу, как создать проект для ESP32 на ESP-IDF, но с использованием Arduino core as component (то есть подключение Arduino как библиотеки), что позволяет писать код для Arduino ESP32 прямо из ESP IDE и дает гибкость в настройке проекта. Но конечно же, предлагаемый способ сложнее обычного варианта, который применялся в Arduino IDE.

Спойлер: общий план ваших действий должен быть примерно таков:

  1. Выбираем версию Arduino core, с которой мы будем работать. 
  2. По описанию версии (и release notes) определяем совместимые версии ESP-IDF и версию, для которой собиралась выбранная версия Arduino core.
  3. Устанавливаем версию ESP-IDF, с которой мы будем работать в качестве основы (если она еще не была установлена).
  4. Создаем новый пустой проект ESP-IDF для выбранной версии на шаге 3.
  5. Подключаем Arduino core из реестра компонентов через ESP-IDF components registry.

Итак, поехали!


Ядро Arduino для ESP32 (ESP32 Arduino Core)

ESP32 Arduino Core — это проект с открытым исходным кодом, разрабатываемый компанией Espressif с 2016 года. Он предоставляет библиотеки и инструменты, совместимые с Arduino, для программирования микроконтроллеров ESP32 без необходимости полного погружения в ESP-IDF. Это решение расширяет возможности платформы Arduino, позволяя использовать функционал ESP32, сохраняя при этом совместимость с существующей экосистемой библиотек и скетчей Arduino.

Поддержка Arduino для устройств Espressif в настоящее время реализована в виде двух отдельных программных продуктов: «Arduino Core для ESP32» (для Arduino IDE / PlatformIO) и «компонент Arduino core для ESP-IDF». Оба они построены на основе ESP-IDF.

Скетчи обращаются к API Arduino, который вызывает уровень аппаратной абстракции HAL, а тот, в свою очередь, взаимодействует с ESP-IDF. В основе всей этой структуры работает операционная система реального времени FreeRTOS, являющаяся неотъемлемой частью ESP-IDF.

В Arduino Core поддерживаются модели ESP32, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-H2, ESP32-P4, ESP32-S2 и ESP32-S3. Также поддерживаются ESP32-C2 и ESP32-C61, однако для них необходимо использовать режим Arduino as component ESP-IDF или выполнить пересборку статических библиотек.

Arduino Core включает поддержку Wi-Fi, Ethernet, BLE и Zigbee; работу с периферийными устройствами (GPIO, ADC, I2C, SPI, UART); основные встроенные библиотеки (WebServer, HTTP-клиент, OTA, Matter и другие), а также многозадачность на базе FreeRTOS.

 


Поддерживаемые аппаратные возможности и API в Arduino core

В настоящее время фреймворк Arduino ESP32 поддерживает практически все функции, доступные для семейства чипов ESP32, используя API, аналогичный Arduino. Но не все аппаратные функции доступны на всех SoC. Ниже представлена ​​таблица статуса поддержки библиотек для основных функций и периферийных устройств для каждого SoC:

  1. В ESP-IDF и ADC Continuous пока не поддерживаются схемы калибровки ESP32-P4, а также отсутствует поддержка IDF.
  2. ESP32-P4 поддерживает Wi-Fi и BLE только через другой SoC с использованием ESP-Hosted.
  3. Поддержка ESP-NOW отсутствует ESP-Hosted.
  4. SPI Ethernet поддерживается всеми семействами ESP32, а RMII — только ESP32 и ESP32-P4.
  5. Чипы, не поддерживающие Zigbee, также могут работать с Zigbee, но для этого им потребуется использовать другую микросхему с поддержкой Zigbee в качестве RCP-интерфейса, подключенного через UART/SPI.
  6. Технология Matter-over-Thread включена в предварительную сборку Arduino IDE для ESP32-C6 (двухстековая архитектура с Wi-Fi), ESP32-H2 (только потоки) и ESP32-C5, доступную через меню Tools → Matter Network → Thread.
  7. Технология Matter-over-Wi-Fi включена в предварительно собранную среду разработки Arduino IDE для ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C5 и ESP32-C6. ESP32-H2 не имеет Wi-Fi. Для ESP32-C2 и ESP32-C61 требуется Arduino в качестве компонента ESP-IDF или пересобранные статические библиотеки.
  8. Технология Matter-over-Ethernet работает только в сети (кластер ввода в эксплуатацию сети отсутствует; CHIPoBLE отключен). SPI PHY (W5500, DM9051, KSZ8851SNL) работают на всех Arduino Matter SoC; протестировано с ESP32 + W5500. Внутренний RMII EMAC работает только с оригинальным ESP32.

 


Стандартные библиотеки, встроенные в Arduino core for ESP32

В версию Arduino core 3.3.12 входят следующие стандартные библиотеки:

  • ArduinoOTA — Обеспечивает возможность обновления «по воздуху» (OTA) через Wi-Fi с использованием espota.py (запрос по протоколу UDP, загрузка по TCP). Предусмотрена поддержка mDNS-анонсов, благодаря чему скетч может быть обнаружен в среде Arduino IDE.
  • AsyncUDP — Асинхронная UDP-библиотека для ESP32
  • BLE — Функции BLE для ESP32. Эта библиотека обеспечивает поддержку технологии Bluetooth Low Energy (BLE) для ESP32 при использовании платформы Arduino.
  • BluetoothSerial — Простой мост UART через классический Bluetooth для ESP32
  • Console — Интерактивная консоль командной строки для ESP32, включающая REPL, историю команд, автодополнение по клавише Tab и разбор аргументов с помощью библиотеки argtable. Решение построено на базе компонента консоли из состава ESP-IDF. Автоматически поддерживает работу через интерфейсы UART и HWCDC (USB-JTAG).
  • DNSServer — Простой DNS-сервер для ESP32.
  • EEPROM — Обеспечивает чтение и запись данных в последовательно-адресуемое флеш-хранилище. Примечание: используйте только для обратной совместимости со старыми проектами, для новых проектов рекомендуется использовать Preferences.
  • ESPmDNS — Библиотека mDNS (Multicast DNS) для ESP32. Позволяет обращаться к устройству по имени (например, esp32.local) вместо IP-адреса.
  • ESP_HostedOTA — Библиотека для обновления сопроцессора ESP-Hosted, если таковой установлен на плате
  • ESP_I2S — Эта библиотека предназначена для работы с периферией I2S (Inter-IC Sound), это стандартный аппаратный интерфейс, используемый для подключения цифровых аудиоустройств, таких как микрофоны (например, INMP441) и усилители/ЦАП (например, MAX98357A).
  • ESP_NOW — Библиотека реализует протокол ESP-NOW от Espressif. Это протокол беспроводной связи без установления соединения, работающий непосредственно между устройствами, которому не требуется Wi-Fi маршрутизатор, и он подходит для сценариев с низкой задержкой и низким энергопотреблением для прямого обмена небольшими пакетами данных между устройствами.
  • ESP_SR — Библиотека для распознавания речи (Speech Recognition). Доступна не на всех чипах (в основном ESP32-S3).
  • ESP_Video — Библиотека для работы с видео (кодеки, обработка изображений). Также зависит от модели чипа.
  • Ethernet — Драйвер для проводного подключения через Ethernet-контроллер (например, LAN8720).
  • FFat — Файловая система FAT. Позволяет читать/писать данные на SD-картах или разделах флеш-памяти, отформатированных в FAT.
  • FS — Базовая библиотека файловой системы (абстрактный класс). Необходима для работы любой конкретной файловой системы.
  • Hash — Набор хеш-функций для ESP32. Эта библиотека предоставляет хеш-функции для скетчей, включая SHA-1/2/3, HMAC и PBKDF2-HMAC.
  • HTTPClient — Простой HTTP-клиент. Нужен, если ваше устройство должно запрашивать данные с сайтов или отправлять их на сервер.
  • HTTPUpdate — Эта библиотека позволяет ESP32 работать как HTTP-клиент: она подключается к указанному вами URL-адресу, скачивает файл прошивки (обычно .bin) и записывает его в раздел OTA.
  • HTTPUpdateServer — Эта библиотека реализует функцию сервера обновления: она добавляет в ваш существующий WebServer страницу загрузки, которую вы открываете в браузере, выбираете файл .bin и загружаете его, и устройство записывает полученные данные в раздел OTA.
  • Insights — ESP Insights – сервис для удаленной диагностики и мониторинга состояния устройства (сбор логов и метрик).
  • LittleFS — Современная и надежная файловая система (по сравнению со SPIFFS) для флеш-памяти.
  • Matter — Поддержка стандарта Matter (умный дом). Позволяет устройствам разных производителей работать вместе.
  • NetBIOS — Поддержка NetBIOS. Позволяет устройству быть видимым в сети Windows по имени.
  • Network — Базовый стек для работы с сетью, необходим для большинства сетевых функций (WiFi, Ethernet, PPP).
  • NetworkClientSecure — Клиент для защищенных соединений (TLS/SSL). Нужен для HTTPS-запросов или защищенных MQTT-соединений.
  • OpenThread — Поддержка протокола Thread (mesh сеть на основе IPv6).
  • PPP — Поддержка протокола PPP (Point-to-Point Protocol), который обычно используется для подключения через сотовые модемы (GSM/LTE).
  • Preferences — Удобная и современная библиотека для работы с NVS (энергонезависимой памятью) для хранения значений в формате ключ-значение.
  • RainMaker — ESP RainMaker – облачная платформа Espressif для удаленного управления устройством (мобильное приложение, дашборд).
  • SD — Драйвер для SD-карт, подключенных по шине SPI.
  • SD_MMC — Драйвер для SD-карт, подключенных через интерфейс SDMMC (работает обычно быстрее, чем по SPI).
  • SimpleBLE — Упрощенная библиотека для создания BLE-рекламы (advertising). Имеет только минимальный набор функций.
  • SPI — Драйвер для шины SPI (Serial Peripheral Interface). Нужен для подключения дисплеев, датчиков, SD-карт.
  • SPIFFS — Файловая система SPIFFS. Устаревшая, но все еще используемая для хранения небольших файлов во флеш-памяти.
  • Ticker — Программный таймер. Позволяет вызывать функцию через определенные интервалы времени.
  • Update — Библиотека для обновления прошивки (лежит в основе OTA).
  • USB — Поддержка USB в основном зависит от встроенного USB-периферийного модуля чипа (например, ESP32-S2, S3, P4), а не от программной библиотеки. Стандартное ядро Arduino предоставляет API для USB CDC (виртуальный последовательный порт) и USB MSC (эмуляция накопителя), а также поддерживает режим USB Host (хост) через TinyUSB.
  • WebServer — Простой HTTP-сервер. Позволяет устройству принимать запросы и отдавать веб-страницы (часто используется для страниц настройки).
  • WiFi — Основной драйвер Wi-Fi, без него не будет работать ничего, связанное с беспроводной сетью.
  • WiFiProv — Библиотека для “провижининга” Wi-Fi: позволяет настроить устройство на подключение к сети без перепрошивки (например, через BLE или точку доступа).
  • Wire — Драйвер для шины I2C (Inter-Integrated Circuit, IIC). Нужен для подключения датчиков, OLED-экранов и т.д.
  • Zigbee — Поддержка протокола Zigbee. Позволяет устройству быть частью Zigbee-сети.

Этот набор может отличаться от версии к версии, некоторые из них можно отключить через меню конфигурации.


Установка VSCode + Espressif IDE

Данная глава предназначена для тех, у кого еще не установлен Visual Studtio Code и плагин Espressif IDE – если таковые уже имеются на вашем контупере, смело листайте дальше.

Устанавливаем Visual Studio Code

Скачиваем и устанавливаем Visual Studio Code с официального сайта: https://code.visualstudio.com/download. Я рекомендую использовать System Installer, если это возможно. Сам процесс установки довольно прост, и я не буду его описывать.

Устанавливаем плагин русификации (по вкусу)

Если вам  больше по вкусу русифицированный интерфейс, то можно сразу же установить пакет русификации. Запускаем только что установленный VSCode, переходим на вкладку “Расширения” слева и вводим в строке поиска одно слово: Russian. В списке выбираем Russian Language Pack for Visual Studio Code и нажимаем Install:

У меня пакет русификации уже установлен, поэтому как есть

После этого VSCode попросит перезагрузку – перезагружаемся и наслаждаемся.

Если автоматической смены языка не произошло, нажмите Ctrl+Shift+P, чтобы открыть палитру команд, а затем начните вводить “display”, чтобы отфильтровать команду «Настроить язык отображения» (“Configure Display Language”). Выберите её и нажмите клавишу Ввод (Enter), после чего откроется список установленных языков по языковым стандартам, в котором необхоимо выбрать нужный языковой стандарт.

 

Установка плагина для IntelliSence

Подсветка синтаксиса, автодополнение кода и другие удобные функции – это не функция ESP-IDF, это “заслуга” специального расширения, которое называется С/С++ for Visual Studio Code:

 

Устанавливается оно ровно таким же образом, как и русификатор: переходим на вкладку “Расширения” → вбиваем С/С++ в поиске и устанавливаем. Опционально можно поставить C/C++ Extension Pack, который включает много мусора чего полезного, но это уж дело вкуса.

 

Установка ESP IDE

Осталось установить собственно ESPressif IDE. В каталоге расширений оно значится под кодовым именем ESP-IDF или ESP-IDF Extension for VS Code. Смотрите не запутайтесь – ESP-IDF это и фреймворк и расширение для VS Code.

При установке будьте внимательны! Вам нужна версия не ниже 2.0. Ставьте последнюю, не ошибетесь.

У вас пости все готово. Осталось установить “саму” ESP-IDF. Но для этого вначале необходимо определится с версией.


Краткий обзор расширения ESP-IDF для VS Code

Если вы в первый раз запустили Espressif IDE после простой и банальной Arduino IDE, то можете “потеряться” во множестве кнопочек, команд и меню. Давайте очень вкратце, по быстрому, познакомимся с VS Code и плагином ESP-IDF.

С некоторого обновления меню расширения и команды получили вполне грамотный русский перевод. И это не иишница “на лету”, а действительно перевод – файлы с переводами входят в состав расширения. Что не может не радовать, особенно начинающих пользователей.

Основное окно плагина ESP-IDF для Visual Studio Code ( ESPressif IDE )

Большинство команд по работе с проектом ESP-IDF можно выполнить несколькими способами:

  • С помощью утилиты idf.py и командной строки – введя соответствующую команду вручную, например idf.py build или idf.py menuconfig.
  • Выбрав соответствующую команду из списка команд – нажмите CTRL + SHIFT + P, отфильтруйте команды по префиксу ESP-IDF, выберите и запустите нужную вам.
  • Выбрав команду из главного меню ESPressif IDE в левой части экрана – некоторые команды находятся в расширенном меню и по умолчанию скрыты
  • Запустив команду из панели быстрого доступа (строки состояния), которая расположена в нижней части окна редактора.

Вы можете пользоваться одним или несколькими способами одновременно, в зависимости от ситуации. Например:

Одна и та же команда обычно доступна несколькими способами. Это не “огромное количество всего”, а много вариантов вызова

Перечислим основные команды, которые могут потребоваться при работе над прошивкой:

  • New Project | New Project Wizard | Новый проект | Мастер создания нового проекта — Cоздать новый, пустой проект ESP-IDF из шаблона или на базе готового примера (examples).
  • Select current ESP-IDF version | Выбор текущей версии ESP-IDF — Выбор версии ESP-IDF для текущего проекта из списка ранее установленных.
  • Open ESP-IDF Installation Manager | Откройте диспетчер установки ESP-IDF — Открыть ESP Installation Manager для установки новой версии ESP-IDF или управления уже установленными.
  • Select Current Project workspace folder | Выбор папки рабочей области текущего проекта — Выбор каталога, который будет считаться основным для текущей рабочей области. Полезно, если в рабочей области открыты одновременно несколько проектов (например основной проект и проект общей библиотеки).
  • Select Port to Use (COM, tty, usbserial) | Выбор порта (COM, tty, usbserial) — Выбор порта, через который будем прошивать и отлаживать устройство.
  • Set Espressif Device Target (IDF_TARGET) | Установка целевого устройства Espressif (IDF_TARGET) — Выбор цели (то есть серии чипов), для которой будет компилироваться проект.
  • ⚙️ | SDK Configuration Editor (menuconfig) | Редактор конфигурации SDK (menuconfig) — Настройка параметров проекта ESP-IDF.
  • ⭐️ | Select Flash Method | Выбор метода прошивки — Выбор метода прошивки: UART / JTAG / DFU
  • 🪣 | Full Clean | Полная очистка — Полное удаление ранее скомпилированного кода. Полезно выполнить при смене цели, изменении версии ESP-IDF и библиотек и т.д.
  • 🔧 | Build | Сборка | Собрать проект — Компиляция и сборка проекта
  • ⚡️ | Flash Device | Прошивка | Прошить проект — Прошить собранный ранее проект на flash-память
  • Erase Flash | Стереть Flash — Полностью стереть всю микросхему flash-памяти. Полезно при смене таблицы разделов
  • 📺 | Monitor Device | Монитор IDF — Открыть монитор последовательного порта для отладки
  • 🔥 | Build, Flash and Monitor | Сборка, прошивка и мониторинг — Последовательное выполнение сборки и прошивки, а затем будет автоматически открыт монитор порта

Конечно, команд ESP IDE гораздо больше, но вы можете познакомиться с ними самостоятельно, со временем… Более подробную информацию о работе с расширением можно получить, например, здесь: [github.com/espressif/vscode-esp-idf-extension].


Выбор версии Arduino core и ESP-IDF

Если вы когда-то писали программы (скетчи) для Arduino IDE, то можете помнить, что при установке поддержки ESP32 в Arduino IDE необходимо выбрать версию Arduino core. В случае с ESP-IDF + Arduino core as component всё ровно то же самое, но есть нюанс – дополнительно придется выбрать ещё и “правильную” версию ESP-IDF в качестве основы. Можно поступить и наоборот: подобрать актуальную версию Arduino core под уже установленную версию ESP-IDF.

Выбор версии Arduino core

Для начала определимся, с какой версией Arduino core мы будем работать. На момент написания статьи основной актуальной версией считается 3.3.12, но также можно воспользоваться и веткой 2.x (а также уже доступны для скачивания альфа и пре-релиз четвертой версии). Примечание: сия информация может довольно быстро устареть – не стоить воспринимать номер актуальной версии буквально.

Список версий компонента Arduino core

Чем отличается Arduino core 2.x от Arduino core 3.x?

На некоторых форумах иногда можно встретить рекомендации, что “новые версии Arduino ESP32 3.x “не рабочие”, “глючные”, и “сырые” – используйте версию 2.x, на ней все точно работает“. На самом деле это, конечно же, не совсем так. Я бы даже сказал, наоборот – новые версии как правило более стабильные, но опять же, как говорится, есть нюансы. 

Дело в том, что ветка Arduino core 2.x основана на устаревшей версии ESP-IDF 4.4.x, которая использует старые native API ESP-IDF (программные интерфейсы для приложений) – например API I2C. Новая версия Arduino core 3.x требует новых версий ESP-IDF >=5.3,<6.2,  и соответственно, использует уже новые API. То есть между этими ветками есть несовместимые изменения API, а поэтому старые проекты или библиотеки могут запросто перестать работать, если они были созданы “в старые времена”.

Отсюда и проблемы: пользователи находят в интернете примеры, проекты или библиотеки, собранные кем-то когда-то для устаревших версий API, и пытаются открыть и собрать их в новой версии Arduino core. В некоторых случаях ожидаемо возникает казус. Но вместо того, что бы разобраться с проблемой и исправить код под новые API, вешается ярлык “новая версия не работает“.

Espressif прямо предупреждает, что между основными версиями Arduino core есть существенные различия в API, и предоставляет отдельное руководство по миграции 2.x → 3.x. 

Arduino Core 2.x Arduino Core 3.x
Старое поколение ядра и API Текущее поколение с изменёнными API
Обычно используется в старых проектах и библиотеках Предпочтительнее для новых проектов
Не поддерживает новые цели ESP32-C6 и ESP32-H2 Добавлена поддержка ESP32-C6 и ESP32-H2
Часто используется для устаревших библиотек и проектов, которые давно не обновлялись Может потребоваться миграция библиотек и приложения
В описании версии такой информации нет, но имеется информация об ESP-IDF 4.4.6 Как правило используются любая версия, начиная с ESP-IDF 5.3.x, конкретная связка зависит от релиза core

Практический вывод

  • Для новых проектов выбирайте современную ветку 3.x и совместимую с конкретным релизом раннюю версию ESP-IDF. Обычно можно остановиться на Latest версии в списке на данный момент. Но при этом учтите, что некоторые старые библиотеки не будут работать без “переделки”.
  • Старый рабочий проект на 2.x: переходите на 3.x только после проверки собственных вызовов API и всех подключенных внешних библиотек. Не переносите проект на новую платформу заменой одной цифры версии: сначала изучите официальный migration guide 2.x → 3.x и исправьте вызовы для несовместимых API.

 

Если ваш проект или библиотека должны собираться с любыми поколениями Arduino core, то в этом случае рекомендуется применять условную компиляцию, например так:

#ifdef ESP_ARDUINO_VERSION_MAJOR
  #if ESP_ARDUINO_VERSION >= ESP_ARDUINO_VERSION_VAL(3, 0, 0)
    // Код для Arduino core 3.x
  #else
    // Код для Arduino core 2.x
  #endif
#else
  // Код для Arduino core 1.x
#endif

Кстати, версию Arduino core можно вывести в монитор порта прямо во время работы:

Serial.printf("ESP32 Arduino Core: %s\n", ESP_ARDUINO_VERSION_STR);

 


Определение версии ESP-IDF

Когда вы выбираете версию Arduino core в Arduino IDE, это автоматически “подтягивает” к проекту нужные версии предварительно скомпилированных библиотек ESP-IDF, с которыми она была собрана “на заводе”. Ничего дополнительно делать не требуется. Эти библиотеки уже скомпилированы и Arduino IDE их никогда  “не трогает” при сборке проекта.

При использовании режима “Arduino как компонент” это совсем не так: система сборки всегда собирает весь проект целиком “из исходников”, включая сам ESP-IDF и Arduino core (именно эта особенность дает вам уникальную возможность настройки Arduino-проекта с помощью sdkconfig в режиме Arduino-as-component, о чем мы поговорим ниже). Но здесь есть один важный нюянс, который вам обязательно придется учитывать: версия базового фреймворка ESP-IDF должна быть совместима с выбранной вами версией Arduino core. Например: нельзя собрать проект с Arduino core 3.3 и ESP-IDF 4.4.3, а также не получится собрать проект для комбинации Arduino core 2.2 и ESP-IDF 5.5.6 – они просто не совместимы друг с другом.

Как это проверить? Откройте станицу компонента Arduino core for the ESP32 family of SoCs и загляните на вкладку Dependencies. Примечание: если вы планируете использовать версию, отличную от Latest, необходимо вначале выбрать нужную версию на вкладке Versions. Здесь нас интересует вот эта запись:

Это означает, что выбранная версия компонента arduino-esp32 теоретически должна быть совместима с любой версией ESP-IDF, начиная с 5.3 и заканчивая 6.2.

Но имеет некий сакральный смысл использовать туже самую версию ESP-IDF, с которой была собрана текущая версия Arduino core изначально – это избавит вас от проблем несовместимости, если разработчики где-то что-то недоглядели. Как же узнать версию, на которой была собрана Arduino core? Да очень просто!

В правом верхнем углу страницы компонента Arduino core for the ESP32 family of SoCs найдите ссылку Repository. Перейдите по ней и в правой панели найдите ссылку Releases. Остается только найти в списке релизов нужную вам версию, где черным по белому четко написано, на какой версии ESP-IDF собран данный релиз:

Делаем вывод, что в данном конкретном случае Arduino core 3.3.12 лучше всего собирать на базе ESP-IDF версии 5.5.5. А заодно и список исправлений и дополнений почитаете.


Установка фреймворка ESP-IDF

Установка фреймворка ESP-IDF производится с помощью специальной программы – установщика eim. Запустить его можно прямо из VSCode, воспользовавшись командой Open ESP-IDF Installation Manager, которую можно вызвать через меню расширения (слева) или через общую палитру команд, нажав Ctrl+Shift+P, а затем введя слово manager для поиска:

Далее воспользуйтесь инструкцией по установке, которая была описана в другой статье: [Установка ESP-IDF с помощью ESP-IDF Installation Manager (EIM)], выбрав версию ESP-IDF, которую мы определили ранее (выше по тесту).

Скачивать и как-то устанавливать Arduino core “вручную” совсем не обязательно – менеджер компонентов ESP-IDF сделает это автоматически. Ну а дальше мы узнаем как подключить его к проекту. Хотя, если вы будете использовать его в нескольких проектах одновременно, имеет смысл скачать его заранее в определенный каталог и подключить к проекту, но это уже другая история.

 


Создание проекта ESP-IDF + Arduino ESP32

Некоторое время назад мастер создания проектов ESP-IDF имел специальный шаблон, в котором можно было создать проект ESP-IDF + Arduino core as component легко и просто. Сейчас эту возможность почему-то убрали, поэтому придется создавать такой проект “вручную”. Но есть и альтернативный вариант – создать готовый проект ESP-IDF + Arduino core as component с уже подключенными компонентами из шаблона – его мы тоже рассмотрим.

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

Откройте расширение ESP-IDF и в меню Advanced найдите команду Мастер создания нового проекта. Другой вариант – нажмите Ctrl+Shift+P, а затем найдите и выполните команду ESP-IDF: New Project или ESP-IDF: Новый проект:

Первым делом вам будет предложено выбрать версию ESP-IDF, для которой будет создан проект. Выберите версию, которую мы “вычислили” ранее, например 5.5.5:

Затем необходимо выбрать шаблон, на основании которого будет создан проект. На момент написания статьи он всего один – sample_project:

Далее выбираем и заполняем свойства проекта: имя, каталог, целевой чип и т.д.:

Примечание: в разделе “Add your ESP-IDF component directory” можно сразу же подключить папку с компонентом Arduino-ESP32, если вы её скачали ранее и распаковали в какой-то каталог. В противном случае оставьте это поле пустым, мы сделаем это позже.

Не забудьте нажать Create Project, после чего откройте его. Вашему взору откроется новый, девственно чистый проект, который содержит одну-единственную функцию app_main():

Девственно чистый проект ESP-IDF

Как бы не очень похоже на привычные setup() и loop()? Я вам раскрою небольшую тайну, забегая немного вперед: их придется написать “руками”, так как IDE сама их не создает. А если выключена опция Autostart Arduino setup and loop on boot, то и цикл внутри app_main() придется организовывать самому, иначе app_main() отработает и завершит работу всей вашей программы, до следующего сброса CPU. Но об этом подробнее будет сказано ниже.

Пердуперждение: Если при этом в верхней части окна IDE появится предупреждение о “небезопасном содержимом”, кликните по нему и нажмите на кнопку Доверять, чтобы можно было работать с проектом:

Перед тем, как начать дальнейшую работу, совершенно не лишним будет попробовать скомпилировать проект (да, да, совершенно пустой проект). Для компиляции нужно нажать кнопку Build или выполнить команду Build Your Project, что тоже самое:

После этого так же не помешает настроить IntelliSence, как это было описано здесь: [Настройка IntelliSense в VSCode для работы с ESP-IDF]. Иначе для чего мы всё это затевали?

Но, прежде чем добавлять в проект компонент Arduino core, необходимо немного настроить проект, иначе можно нарваться на ошибку:

CMake Error at managed_components/espressif__arduino-esp32/CMakeLists.txt:449 (message):
  esp32-arduino requires CONFIG_FREERTOS_HZ=1000 (currently 100)

Это связано с тем, что по умолчанию в настройках проекта выставлена частота тиков FreeRTOS 100 Гц, а для нормальной работы Arduino core требуется 1000 Гц.


Утилита idf.py и где её найти

Прежде чем мы перейдем к дальнейшему описанию работы с проектом, необходимо немного прояснить за утилиту idf.py и где её найти, так как она нам может понадобится во многих случаях: для подключения компонентов (библиотек), для настройки проекта и т.д. Впрочем, многие действия можно выполнить и без командной строки, воспользовавшись UI-командами, которые мы рассматривали выше.

idf.py — это специальный скрипт, написанный на python-е, который полностью управляет процессом настройки, сборки и загрузки проекта ESP-IDF. Он перекрывает весь жизненный цикл разработки — от создания проекта до его запуска на чипе. Я не буду здесь подробно описывать этот и другие инструменты ESP-IDF, вы можете почитать об них в других статьях на сайте [Внутренняя кухня ESP32: система сборки и загрузки прошивки – как это работает?], [Система сборки ESP-IDF] и официальной документации.

Скрипт – утилита idf.py — это инструмент, в первую предназначенный для запуска в терминале или командной строке Windows. Но если вы попытаетесь набрать эту команду в “обычном окне” терминала, то скорее всего получите ошибку:

C:\Users\username>idf.py
"idf.py" не является внутренней или внешней
командой, исполняемой программой или пакетным файлом.

И это нормально. Обычный процессор командной строки Windows (или PowerShell, или терминал Linux) в душе не знают, что такое ESP-IDF, какая у него версия, где он лежит, что такое pdf.py и esptool.py,  а поэтому пошлют вас в пешее сами-знаете-какое путешествие.

Все инструменты ESP-IDF используют для работы несколько системных переменных окружения:

  • IDF_PATH – путь к выбранной версии ESP-IDF, например C:\Espressif\esp-idf\v5.5.5\esp-idf
  • IDF_TOOLS_PATH – путь к каталогу с инструментами сборки, например C:\Espressif\tools
  • IDF_PYTHON_ENV_PATH – путь к каталогу виртуального окружения python, например C:\Espressif\tools\python\v5.5.5\venv

По умолчанию этих переменных окружения просто нет. Есть несколько вариантов решения данной проблемы.

Самый простой путь решения – вызвать специальный терминал ESP-IDF прямо в VSCode:

Самый простой способ выполнить команды idf.py, esptool.py и т.д.

Второй вариант (для Windows) – использовать специальный ярлык ESP-IDF xxx Powershell:

Этот ярлык создается автоматически eim при установке каждой версии ESP-IDF на рабочем столе.

Для справки: содержит он такую команду:

C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe -NoExit -ExecutionPolicy Bypass -NoProfile -Command "& {. 'C:\Espressif\tools\Microsoft.v5.5.5.PowerShell_profile.ps1'}"

Если вам интересно – посмотрите содержимое файла Microsoft.v5.5.5.PowerShell_profile.ps1 – именно он “пропишет” нужные переменные в окружение, но только на время текущего сеанса!

Запустите его – он откроет окно PowerShell и выполнит тоже самое, что и в предыдущем случае, но только пока отрыто это окно.

Здесь есть важный нюанс: по умолчанию терминал будет открыт в домашнем каталоге текущего пользователя. Если ваш проект располагается в другом каталоге, необходимо воспользоваться командой cd каталог/вашего/проекта для того, чтобы перейти в каталог проекта. Таки да, этот способ немного сложнее, зато удобнее в некоторых случаях – например для пакетной компиляции сразу многих проектов или конфигурации проекта.

Ну и третий вариант – просто воспользоваться соответствующей готовой командой через левое меню плагина ESP-IDF, например Classic manuconfig…


Конфигурация проекта ESP-IDF

Самое “вкусное”, что вы получаете, воспользовавшись сборкой ESP-IDF + Arduino core as comonent – это возможность самому настраивать параметры сборки ESP-IDF, как вам этого хочется, а не так как за вас это решил какой-то “дядечка”. Вы можете подключить любую удобную вам таблицу разделов, включить опции вывода списка задач для оптимизации их стека,  включить динамические буферы TLS и много чего ещё.

Несколько способов, как открыть конфигуратор проекта

Для того, чтобы запустить конфигуратор проекта ESP-IDF, можно воспользоваться несколькими способами:

Вариант 1. Используйте команду idf.py menuconfig в командной строке или терминале

Откройте “терминал ESP-IDF” как это было описано выше и введите команду idf.py menuconfig:

Как открыть menuconfig, используя PowerShell на Windows

Не забудьте перед этим перейти в каталог проекта! В результате вы должны получить нечто следующее:

 

Вариант 2. Графическое древовидное меню

Более простой способ. Просто воспользуйтесь командой ESP-IDF: SDK Configuration Editor (Menuconfig) или левым меню плагина ESP IDE, что то же самое:

“Графическое” меню SDK Config

Лично мне этот вариант не очень нравится, так как в нем легко запутаться, но “на вкус и цвет все фломастеры разные”…

 

Вариант 3. Классическое меню прямо из интерфейса VS Code

Ещё один способ, если сам не нравится “графический” вариант. Для этого воспользуйтесь командой ESP-IDF: Open Classic Menuconfig Terminal или соответствующей командой из расширенного меню:

Как по мне, так это самый удобный способ. Но решать, конечно вам.

 

Настройки проекта ESP-IDF

А теперь обсудим что нужно и можно подкрутить и поднастроить… Тут следует сразу оговориться, что в редактор конфигурации нам придется зайти дважды – перед тем как добавить компонент arduino-esp32 в проект (иначе проект просто не соберется и даже в menuconfig не пустит) и после, чтобы настроить параметры самого Arduino core. Итак, первая часть…

1. Component config → FreeRTOS → Kernel

Самое главное, что нужно изменить – это частоту тиков FreeRTOS: для корректной работы Arduino core должна быть 1000 Hz:

Без этой настройки проект с Arduino core просто не собирается

 

2. Component config -> mbedTLS -> TLS Key Exchange Methods -> Enable pre-shared-key ciphersuites

Ещё одна обязательная опция, которую требуется включить для работы с arduino-esp32: Component config -> mbedTLS -> TLS Key Exchange Methods -> Enable pre-shared-key ciphersuites и Enable PSK based ciphersuite modes:

Включите обе отмеченные красным прямоугольником опции. Без них проект собирается, но с предупреждениями

По большому счету, этого уже достаточно – можно добавлять компонент arduino-esp32 в проект. Для того, чтобы сохранить изменения, просто нажмите S на клавиатуре, а затем подтвердите сохранение клавишей Enter. Но можно прогуляться по меню и кое-что подправить по вкусу.

 

3. Необязательные модификации

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

  • Serial flasher config – параметры FLASH-памяти и прошивки через UART-порт, например можно включить опцию Detect flash size when flashing bootloader для автоматического определения размера FLASH-памяти перед прошивкой.
  • Partition Table – здесь вы можете выбрать одну из нескольких готовых таблиц разделов FLASH-памяти, либо подключить свою. Как это сделать, описано в статье [Таблицы разделов FLASH-памяти для ESP32].
  • Component config → Bluetooth – включите программную поддержку Bluetooth, если вы планируете его использовать
  • Component config → ESP PSRAM – включите поддержку PSRAM, если таковая установлена на вашей плате / модуле
  • Component config → ESP System Settings → CPU frequency – выберите частоту CPU, на которой он будет работать. Чем выше частота, тем выше быстродействие, но больше потребление.
  • Component config → ESP System Settings → Main task stack size – размер стека для “главной” задачи app_main(). Для Arduino core размер стека по умолчанию считается 8192 байта.
  • Component config → ESP System Settings → Main task core affinity – на каком ядре будет запущена app_main(). Если вы планируете использовать app_main() только для запуска других задач – можно оставить CPU0, если внутри app_main() будет работать весь основной код проекта – рекомендуется изменить на CPU1 (разумеется, если вы используете двухядерный чип).
  • Component config → Log → Log Level → Default log verbosity – уровень отладочных сообщений для системных “по умолчанию”
  • Component config → LWIP → Local netif hostname – здесь вы можете задать сетевое имя хоста вашей ESP32, по умолчанию это “espressif”
  • Component config → LWIP → SNTP – параметры службы синхронизации времени
  • Component config → mbedTLS → Using dynamic TX/RX buffer – если вы используете TLS-соединения “время от времени”, то можно включить эту опцию, чтобы удалять из памяти буферы TLS-соединения. Но это несколько замедлит процесс рукопожатия и подключения. Если TLS-соединение используется постоянно (например MQTT), то смысла в этом нет.
  • Component config → Modbus configuration – параметры библиотеки esp_modbus

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

В данном списке пока отсутствуют пункты, которые относятся к самому ядру Arduino core – их мы обсудим позже. Возможно также, что в список “забыли попасть” некоторые пункты, на которые тоже стоило бы обратить внимание, но вы можете сделать это в комментариях…


Подключение к проекту компонента Arduino-ESP32

Теперь можно подключить компонент Arduino core for ESP32 к нашему проекту.

Забегая вперед, скажу, что он подключается к проекту ESP-IDF ровно также, как и любые другие компоненты ESP-IDF (библиотеки в терминологии Arduino IDE) — вся эта “кухня компонентов” была более подробно описана в статье [Компоненты ESP-IDF и их подключение к проекту] (рекомендую ознакомится, если вы ещё не читали). Статья эта довольно большая (потом почитаете), а в данной статье рассмотрим конкретные способы применительно к Arduino ESP32. Способов, собственно, имеется сразу несколько – выберите один по своему вкусу.

Вариант 1. С помощью командной строки и утилиты idf.py

Если вы любите командную строку – выполните команду idf.py add-dependency, указав какой конкретно компонент мы ходим добавить в проект и какой версии. Например:

idf.py add-dependency "espressif/arduino-esp32^3.3.12"

Результатом выполнения данной команды будет следующий вывод: 

Как видим, данная команда просто создала файл ваш_проект\main\idf_component.yml,  в котором находится описание всех “внешних” компонентов, которые должны быть подключены к проекту. Мы можем открыть его и посмотреть:

## IDF Component Manager Manifest File
dependencies:
  ## Required IDF version
  idf:
    version: '>=4.1.0'
  # # Put list of dependencies here
  # # For components maintained by Espressif:
  # component: "~1.0.0"
  # # For 3rd party components:
  # username/component: ">=1.0.0,<2.0.0"
  # username2/component2:
  #   version: "~1.0.0"
  #   # For transient dependencies `public` flag can be set.
  #   # `public` flag doesn't have an effect dependencies of the `main` component.
  #   # All dependencies of `main` are public by default.
  #   public: true
  espressif/arduino-esp32: ^3.3.12

Что означают ^, =, ~ , >= и прочие символы, а также про этот файл и его содержимое вы можете узнать из статьи [Компоненты ESP-IDF и их подключение к проекту] или в оригинале  [https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/manifest_file.html]. 

 

Вариант 2. Через палитру команд

Можно не мучаться с командной строкой – нажмите CTRL+SHIFT+P, затем введите фильтр-фразу Добавить Arduino ESP32 как компонент – и просто выполните найденную команду.

Легко и очень просто. Результат будет точно такой же, что и в предыдущем случае.

 

Вариант 3. Через создание файла idf_component.yml вручную

Если вы владеете навыками работы с текстовыми файлами формата .yml, то вам, возможно, проще и быстрее будет создать его в любом “условном блокноте”, да хоть в том же самом VSCode. Не обязательно писать все эти комментарии, можно ограничиться только зависимостями, например так:

dependencies:
  espressif/arduino-esp32: ^3.3.12

Файл idf_component.yml должен находится “рядом” с файлом main.c, то есть в подкаталоге main вашего проекта.

Теперь можно попытаться скомпилировать проект заново. Если вы все сделали правильно, то процесс компиляции также должен быть завершен успешно.

При компиляции менеджер компонентов ESP-IDF создаст папку managed_components и натаскает в нее всякого мусора:

Компоненты, автоматически загружаемые вместе с Arduino Core

Как видим, сразу же загружаются и esp-modbus, и esp_modem, и esp_rainmaker, и много чего ещё… Не совсем понятно для чего все это сразу нужно, но пусть будет.

 

Вариант 4. Использование общей копии Arduino ESP32 для нескольких проектов одновременно

Все рассмотренные выше способы подразумевают, что фреймворк Arduino core for ESP32 подключается к проекту через менеджер компонентов. И при компиляции этот самый менеджер компонентов самостоятельно скачает свежую версию arduino-esp32, и поместит её в подкаталог managed_components, как было показано выше. Это далеко не всегда удобно, например если у вас несколько подобных проектов и вы не желаете иметь на диске несколько копий arduino-esp32 одновременно (в каждом проекте будет своя личная копия).

Этого можно избежать, если разместить заранее скачанный компонент в некой общей папке arduino-esp32, доступной для других ваших проектов. Допустим “корневая” папка всех моих проектов для этой платформы – C:\Projects\Espressif\Arduino\, тогда можно представить следующую структуру:

C:\Projects\Espressif\Arduino\
├── arduino-esp32\          ← общая копия Arduino Core
├── project1\
│   └── main\
│       └── idf_component.yml
├── project2\
│   └── main\
│       └── idf_component.yml

В CMakeLists.txt каждого проекта добавьте set(EXTRA_COMPONENT_DIRS "C:/Projects/Espressif/Arduino/arduino-esp32") перед строкой project():

set(EXTRA_COMPONENT_DIRS "C:/Projects/Espressif/Arduino/arduino-esp32")
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my_project)

Тогда ESP-IDF найдёт компонент из общей папки. Минус такого подхода: проект с абсолютным путем будет непереносимым между компьютерами, но это бывает необходимо редко. Можно также использовать переменную окружения, например $ENV{ARDUINO_ESP32_PATH}.

 


Настройка компонента Arduino core for ESP32

После того, как мы добавили в проект компонент arduino-esp32, в меню конфигурации появятся два новых пункта: Arduino Configuration ---> и ESP RainMaker Config --->. Второе в данном случае нам не очень интересно, а вот в меню Arduino Configuration заглянуть стоит…

Меню настройки Arduino core for ESP32

Arduino target variant (board)

Название целевого варианта (название конкретной платы) в папке variants/, например: «heltec_wifi_lora_32_V2». Название чувствительно к регистру. Указание варианта, отличного от цели ESP-IDF (серии чипов), позволяет выполнить дополнительную настройку — например, задать назначение контактов GPIO. Список вариантов можно посмотреть \managed_components\espressif__arduino-esp32\variants\, но в режиме Arduino Core as component там не так уж и много вариантов.

Autostart Arduino setup and loop on boot

Включение этой опции приведет к реализации функции  app_main() “по умолчанию” и автоматическому запуску Arduino core. В этом случае в файле main.cpp вам достаточно реализовать функции setup() и loop() и подключить заголовочный файл #include <Arduino.h>. Если эта опция отключена, вам необходимо самостоятельно реализовать цикл loop(), а также вы можете вызвать initArduino() для выполнения всех подготовительных действий, необходимых для работы фреймворка Arduino core. Это мы подробнее обсудим в следующем разделе.

Core on which Arduino’s setup() and loop() are running

Выберите ядро, на котором будут выполняться функции setup() и loop() в Arduino, если вы выбрали опцию [*] Autostart Arduino setup and loop on boot. Можно выбрать ядро ARDUINO_RUN_CORE0, или ARDUINO_RUN_CORE1 (рекомендуется), или ARDUINO_RUN_NO_AFFINITY – это позволяет ядру автоматически выбрать ядро при запуске задачи в зависимости от текущей загрузки ядер.

Loop thread stack size

Объем стека в байтах, доступный для основной задачи Arduino core, по умолчанию 8192. Это значение работает, только если вы выбрали опцию [*] Autostart Arduino setup and loop on boot. В противном случае вы сами реализуете функцию app_main() и размером её стека управляет другая опция (CONFIG_ESP_MAIN_TASK_STACK_SIZE – её мы рассматривали выше) или задаете вы сами – в зависимости от вашей реализации.

Core on which Arduino’s event handler is running

Выберите, на каком ядре будет выполняться функция WiFi.onEvent() в Arduino core. Значения: ARDUINO_RUN_CORE0, или ARDUINO_RUN_CORE1 (по умолчанию), или ARDUINO_RUN_NO_AFFINITY.

При инициализации Wi-Fi Arduino core создает специальную очередь _arduino_event_queue и запускает специальную задачу FreeRTOS, которая “слушает” эту очередь. Именно для этой задачи применяется данная настройка из меню конфигурации. Когда Wi-Fi стек генерирует какое-либо событие (например, подключение или разрыв соединения), оно помещается в очередь задачи, задача извлекает его и вызывает функцию обратного вызова, зарегистрированную через WiFi.onEvent(). Таким образом, код внутри onEvent выполняется в контексте этой задачи, а не в основном цикле loop() и не в системном обработчике прерываний. Другими словами, обработчик onEvent — это не прерывание (ISR), поэтому в нем можно использовать большинство функций (например, Serial.print, delay), но тем не менее, не стоит выполнять слишком длительные операции, чтобы не блокировать обработку других Wi-Fi событий.

По умолчанию используется Core 1 (там же, где обычно работает loop() в Arduino). Если вы активно нагружаете Core 1 в основном цикле, перенос обработчика Wi-Fi событий на Core 0 может помочь избежать задержек в обработке событий сети. Опция ARDUINO_RUN_NO_AFFINITY (без привязки) позволяет планировщику FreeRTOS самому выбрать ядро.

 

Core on which Arduino’s Serial Event task is running

Выберите, на каком ядре будет выполняться задача Serial Event task в Arduino core. Значения: ARDUINO_RUN_CORE0, или ARDUINO_RUN_CORE1, или ARDUINO_RUN_NO_AFFINITY (по умолчанию).

По аналогии с событиями WiFo-стека, события Serial.onReceive()  также обслуживаются отдельной задачей FreeRTOS, а не выполняются в основном цикле loop(). Когда вы вызываете Serial.begin(), Arduino core создаёт задачу с именем uart_event_task. Именно для этой задачи применяется рассматриваемая настройка из меню конфигурации. Опция передаёт значение ARDUINO_SERIAL_EVENT_TASK_RUNNING_CORE в функцию создания задачи FreeRTOS, определяя, на каком ядре она будет работать.

Serial Event task stack size

Объем стека в байтах, доступный для рассмотренной выше задачи Serial Event task (uart_event_task), по умолчанию 2048.

 

Priority of the Serial Event task

Здесь вы можете задать приоритет выполнения для рассмотренной выше задачи Serial Event task (uart_event_task).

 

Core on which Arduino’s UDP is running

Выберите, на каком ядре будет выполняться задача асинхронной обработки UDP-пакетов в Arduino core. Можно выбрать ARDUINO_UDP_RUN_CORE0 (по умолчанию), или ARDUINO_UDP_RUN_CORE1, или ARDUINO_UDP_RUN_NO_AFFINITY.

Эта задача является частью механизма AsyncUDP в Arduino core for ESP32. Когда в сетевой стек LwIP поступает UDP-пакет, он не вызывает напрямую ваш код (callback). Вместо этого пакет помещается в очередь, а задача UDP-обработчика извлекает его и передаёт вашему обработчику. Если бы обработка выполнялась непосредственно в контексте LwIP, медленный обработчик мог бы заблокировать весь сетевой стек, выделенная задача решает эту проблему. При переполнении входящей очереди новые пакеты отбрасываются, а не блокируют поток LwIP, что обеспечивает стабильность сети – это компромисс между стабильностью и гарантией доставки.

Этот параметр в первую очередь связан с асинхронным API AsyncUDP. Если вы используете классический синхронный WiFiUDP с parsePacket() в loop(), то ваша логика приёма пакетов по-прежнему зависит от частоты вызовов в loop() (хотя задача AsyncUDP по прежнему работает в фоне).

 

Priority of the UDP task

Выберите приоритет для задачи асинхронной обработки UDP-пакетов AsyncUDP для Arduino core for ESP32, по умолчанию 3.

 

UDP task stack size

Размер стека для задачи асинхронной обработки UDP-пакетов AsyncUDP для Arduino core for ESP32, по умолчанию 4096.

 

Run interrupts in IRAM

Опция “Run interrupts in IRAM” в Arduino core for ESP32 определяет, будут ли обработчики прерываний (ISR) и связанные с ними функции размещаться в IRAM (Instruction RAM — внутренней оперативной памяти), а не во внешней флеш-памяти. Имейте в виду, что это потенциально опасная настройка, включайте ее только в том случае, если полностью осознаете последствия.

Главная причина использовать IRAM для прерываний — это две критические ситуации, в которых код во флеш-памяти становится недоступным:

  • Операции с флеш-памятью: когда ESP32 записывает данные во внешнюю флеш-память (например, при сохранении файла в SPIFFS или обновлении прошивки OTA), кэш, который обычно ускоряет доступ к коду из флеша, отключается. Если в этот момент сработает прерывание, а его обработчик находится во флеш-памяти, процессор не сможет его выполнить, что приведёт к сбою (Guru Meditation Error). Размещение ISR в IRAM гарантирует, что он продолжит работать даже при отключённом кэше.
  • Снижение задержек: ESP32 читает код из флеш-памяти через кэш. Если нужного фрагмента кода в кэше нет (cache miss), возникает задержка, необходимая для копирования нужно фрагмента в кэш. Для время-затратных задач (например, обработка высокочастотных сигналов) размещение ISR в IRAM (который работает на полной скорости процессора) уменьшает эту задержку и делает реакцию на прерывание более предсказуемой.

Важное ограничение: Если ISR размещён в IRAM, он может вызывать только те функции, которые также находятся в IRAM или в ROM. Вызов обычной функции из флеш-памяти внутри такого ISR приведёт к сбою, если кэш в этот момент отключён. Если вы используете функцию attachInterrupt() и хотите, чтобы ваш обработчик был в IRAM, одного включения опции недостаточно — вам нужно явно пометить функцию атрибутом IRAM_ATTR в коде.

По умолчанию в Arduino core для ESP32 эта опция обычно отключена. Включать её стоит, если вы пишете код, который активно работает с флеш-памятью (запись файлов, OTA-обновления) и при этом полагаетесь на прерывания, или если у вас есть критичные ко времени ISR, где важна каждая микросекунда. Можно оставить выключенной, если вы не выполняете операции с флешем во время работы прерываний и не предъявляете повышенных требований к их быстродействию. Это экономит ценное пространство IRAM (которого не так много) для других нужд.

 

Disable mutex locks for HAL

Если включить эту опцию, все аппаратные абстракции уровня HAL будут выполняться без блокировок. В этом случае обмен данными с внешним оборудованием будет происходить несколько быстрее, но необходимо исключить риск того, что в вашем приложении нет возможностей для одновременного использования одной и той же шины из другого потока или прерывания. Эту опцию лучше всего использовать в коде, реализованном только в функциях setup() / loop() и обратных вызовах только в основной задаче Arduino.

 

Debug Log Configuration

Набор опций Debug Log Configuration в конфигурации Arduino core for ESP32 управляет тем, как и какие отладочные сообщения будут выводиться в последовательный порт. Это инструмент для разработчиков, позволяющий заглянуть “под капот” работы ядра Arduino core и стандартных библиотек.

Это подменю, которое содержит следующие опции:

  • Default log level (Уровень логирования по умолчанию): Это главная опция, она задает порог, ниже которого сообщения просто игнорируются. В Arduino IDE эта настройка называется “Core Debug Level“. Доступны следующие уровни (от наименее до наиболее подробного):
    • ARDUHAL_LOG_DEFAULT_LEVEL_NONE – Полностью отключает вывод логов.
    • ARDUHAL_LOG_DEFAULT_LEVEL_ERROR – Показывает только сообщения об ошибках (по умолчанию).
    • ARDUHAL_LOG_DEFAULT_LEVEL_WARN – Предупреждения и ошибки.
    • ARDUHAL_LOG_DEFAULT_LEVEL_INFO – Информационные сообщения, предупреждения и ошибки.
    • ARDUHAL_LOG_DEFAULT_LEVEL_DEBUG – Подробные отладочные сообщения.
    • ARDUHAL_LOG_DEFAULT_LEVEL_VERBOSE – Максимально подробный вывод, включая все внутренние детали.
  • Use ANSI terminal colors in log output. Если включить эту опцию, сообщения разных уровней будут окрашены в разные цвета в мониторе порта (при условии, что ваша терминальная программа поддерживает ANSI-коды управления цветом). Это помогает визуально быстро различать ошибки и информационные сообщения.
  • Forward ESP_LOGx to Arduino log output: Эта опция перенаправляет вывод логов из системы ESP-IDF (макросы ESP_LOGx) в систему логирования Arduino. Это может быть полезно, если вы используете библиотеки, написанные для ESP-IDF (например mqtt или modbus), и хотите при этом видеть все сообщения в едином формате Arduino.
    Чтобы включить эту функцию в своем приложении, добавьте после директив include следующее:

    #ifdef ARDUINO_ARCH_ESP32
    #include "esp32-hal-log.h"
    #endif

Для обычной работы часто достаточно уровня ERROR или NONE. Включение DEBUG или VERBOSE приводит к генерации большого объема логов, что может замедлить работу и замусорить ваш собственный вывод в последовательный порт. Используйте подробные уровни только тогда, когда вам нужно диагностировать проблему на низком уровне (например, разобраться в сбоях Wi-Fi или файловой системы).

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

 

Used partition scheme (Default)

Выберите схему (таблицу) разметки flash-памяти в стиле Arduino:

  • ARDUHAL_PARTITION_SCHEME_DEFAULT – используйте таблицу разделов ESP-IDF, выбранную для опции Partition Table, которую мы рассматривали выше
  • ARDUHAL_PARTITION_SCHEME_MINIMAL – используйте схему Minimal (for 2MB FLASH) для Arduino
  • ARDUHAL_PARTITION_SCHEME_NO_OTA – используйте схему No OTA (for large apps) для Arduino
  • ARDUHAL_PARTITION_SCHEME_HUGE_APP – используйте схему Huge App (for very large apps) для Arduino
  • ARDUHAL_PARTITION_SCHEME_MIN_SPIFFS – используйте схему Minimal SPIFFS (for large apps with OTA) для Arduino

Стандартный набор схем разметок для Arduino IDE

То есть эта опция позволяет воспользоваться несколькими готовыми схемами из Arduino IDE, если вы к ним привыкли.

 

Autoconnect WiFi on boot

Если этот параметр включен, Wi-Fi будет автоматически подключаться к последнему использованному SSID (если режим станции была включен), в противном случае подключение будет установлено только после вызова WiFi.begin(ssid, password).

 

Include only specific Arduino libraries

Позволяет вам выбрать только необходимые для проекта стандартные библиотеки Arduino core. Это позволяет экономить ресурсы (флеш-память и RAM), подключая только то, что действительно нужно вашему проекту.

Сетевые и коммуникационные

  • Enable Networking: Базовый стек для работы с сетью, необходим для большинства сетевых функций (WiFi, Ethernet, PPP).
  • Enable WiFi: Основной драйвер Wi-Fi, без него не будет работать ничего, связанное с беспроводной сетью.
  • Enable Ethernet: Драйвер для проводного подключения через Ethernet-контроллер (например, LAN8720).
  • Enable PPP: Поддержка протокола PPP (Point-to-Point Protocol), который обычно используется для подключения через сотовые модемы (GSM/LTE).
  • Enable WiFiProv: Библиотека для “провижининга” Wi-Fi: позволяет настроить устройство на подключение к сети без перепрошивки (например, через BLE или точку доступа).

Веб-серверы и протоколы прикладного уровня

  • Enable HTTPClient: Простой HTTP-клиент. Нужен, если ваше устройство должно запрашивать данные с сайтов или отправлять их на сервер.
  • Enable WebServer: Простой HTTP-сервер. Позволяет устройству принимать запросы и отдавать веб-страницы (часто используется для страниц настройки).
  • Enable DNSServer: Простой UDP DNS-сервер. Часто используется в связке с WebServer для создания Captive Portal (страницы авторизации в Wi-Fi).
  • Enable ESPmDNS: Поддержка mDNS (Multicast DNS). Позволяет обращаться к устройству по имени (например, esp32.local) вместо IP-адреса.
  • Enable AsyncUDP: Асинхронный UDP-клиент/сервер. Работает в фоновой задаче, не блокируя основной цикл (как раз то, что мы обсуждали ранее).
  • Enable NetworkClientSecure: Клиент для защищенных соединений (TLS/SSL). Нужен для HTTPS-запросов или защищенных MQTT-соединений.
  • Enable ArduinoOTA: Библиотека для обновления прошивки “по воздуху” (Over-The-Air) через Wi-Fi.
  • Enable NetBIOS: Поддержка NetBIOS. Позволяет устройству быть видимым в сети Windows по имени.

Периферия и файловые системы

  • Enable SPI: Драйвер для шины SPI (Serial Peripheral Interface). Нужен для подключения дисплеев, датчиков, SD-карт.
  • Enable Wire: Драйвер для шины I2C (Inter-Integrated Circuit, IIC). Нужен для подключения датчиков, OLED-экранов и т.д.
  • Enable FS: Базовая библиотека файловой системы (абстрактный класс). Необходима для работы любой конкретной файловой системы.
  • Enable SPIFFS: Файловая система SPIFFS. Устаревшая, но все еще используемая для хранения небольших файлов во флеш-памяти.
  • Enable LittleFS: Более современная и надежная файловая система (по сравнению со SPIFFS) для флеш-памяти.
  • Enable FFat: Файловая система FAT. Позволяет читать/писать данные на SD-картах или разделах флеш-памяти, отформатированных в FAT.
  • Enable SD: Драйвер для SD-карт (подключенных по SPI).
  • Enable SD_MMC: Драйвер для SD-карт, подключенных через интерфейс SDMMC (работает обычно быстрее, чем по SPI).
  • Enable EEPROM: Эмуляция EEPROM. Позволяет сохранять небольшие объемы данных (настройки) в энергонезависимой памяти (NVS). Только для совместимости с древними проектами, вместо нее рекомендуется использовать Preferences.
  • Enable Preferences: Более удобная и современная библиотека для работы с NVS (энергонезависимой памятью) для хранения значений в формате ключ-значение.
  • Enable Ticker: Программный таймер. Позволяет вызывать функцию через определенные интервалы времени.
  • Enable Update: Библиотека для обновления прошивки (лежит в основе OTA).

Беспроводные технологии BLE, Zigbee, Thread

  • Enable BLE: Стек Bluetooth Low Energy (BLE). Позволяет устройству работать как BLE-периферия или центральное устройство.
  • Enable BluetoothSerial: Классический Bluetooth (SPP), работает только на классическом ESP32. Позволяет организовать последовательный порт по Bluetooth.
  • Enable SimpleBLE: Упрощенная библиотека для создания BLE-рекламы (advertising). Имеет только минимальный набор функций.
  • Enable Zigbee: Поддержка протокола Zigbee. Позволяет устройству быть частью Zigbee-сети.
  • Enable OpenThread: Поддержка протокола Thread (mesh сеть на основе IPv6).
  • Enable Matter: Поддержка стандарта Matter (умный дом). Позволяет устройствам разных производителей работать вместе.

Облачные и специализированные сервисы

  • Enable ESP-SR: Библиотека для распознавания речи (Speech Recognition). Доступна не на всех чипах (в основном ESP32-S3).
  • Enable ESP-Video: Библиотека для работы с видео (кодеки, обработка изображений). Также зависит от модели чипа.
  • Enable RainMaker: ESP RainMaker – облачная платформа Espressif для удаленного управления устройством (мобильное приложение, дашборд).
  • Enable Insights: ESP Insights – сервис для удаленной диагностики и мониторинга состояния устройства (сбор логов и метрик).

Поскольку мы работаем в режиме компонента, мы можем отключить всё лишнее. Например, если вы делаете датчик с передачей данных по Wi-Fi, но без дисплея и Bluetooth, вы можете смело отключить Enable BLE, Enable Wire, Enable SD, Enable ESP-SR и т.д. Это заметно уменьшит итоговый размер прошивки и потребление памяти.

 


Создание скетча

Измените расширения файлов с .c на .cpp

Поскольку библиотеки Arduino используют возможности C++, вам нужно будет вручную заменить расширения файлов с .c на .cpp.

  1. В основной папке переименуйте файл main.c в main.cpp.
  2. В основной папке откройте файл CMakeLists.txt и измените main.c на main.cpp.
    idf_component_register(SRCS "main.cpp"
                        INCLUDE_DIRS ".")
    

Не забудьте включить Arduino.h в начале файла: #include Arduino.h!

 

Выбор режима работы

Создание заготовки для будущего скетча будет зависеть от того, какой вариант вы выбрали в разделе menuconfig → Arduino Configuration → Autostart Arduino setup and loop on boot.

  • Для использования функций setup() и loop() — включите опцию Autostart Arduino setup and loop on boot
  • Для использования функции app_main() и полного контроля над процессом — отключите Autostart Arduino setup and loop on boot

Затем нажмите Сохранить [S] → подтвердите имя файла по умолчанию [Enter] → закройте окно подтверждения [Enter] или [Пробел] или [Esc] → Выйти [Q]

 

Вариант 1. Использование Arduino функций setup() и loop()

Этот вариант работает, если активирована опция Autostart Arduino setup and loop on boot. В этом случае main.cpp должен быть оформлен точно так же, как и любой другой скетч Arduino IDE. Параметры основной задачи Arduino берутся из параметров, указанных выше в разделе Arduino Configuration → Loop thread stack size и т.д.

Просто сотрите из файла всё, что уже есть, а затем введите, например, следующее:

// Содержимое файла: main.cpp

#include "Arduino.h"

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

void loop()
{
    Serial.println("Arduino loop");
    delay(1000); // <-- На самом деле это vTaskDelay(1000 / pdMS_TO_TICKS);
}

 

Вариант 2. Использование ESP-IDF функции appmain()

Этот вариант работает, если опция Autostart Arduino setup and loop on boot отключена. В main.cpp необходимо “по прежнему” реализовать app_main() и вызвать initArduino(); в этом блоке. Имейте в виду, что в этом случае функции setup() и loop()  нужно реализовать самостоятельно (в случае необходимости). Кроме того, обязательно учитывайте, что app_main() — это однократно выполняемая обычная функция; поэтому, если вам нужен бесконечный цикл, как loop() в Arduino – создайте его самостоятельно.

// Содержимое файла: main.cpp

#include "Arduino.h"

extern "C" void app_main()
{
    // Инициализация Arduino core
    initArduino();

    // Однократный setup()
    Serial.begin(115200);

    // Бесконечный цикл, подобный loop() Arduino
    while(true) {
       Serial.println("Arduino loop");
       delay(1000); // <-- На самом деле это vTaskDelay(1000 / pdMS_TO_TICKS);
    }

    // ПРЕДУПРЕЖДЕНИЕ: Если программа достигнет конца функции app_main(), CPU перезапустится.
}

В этом случае вам предоставляется полный контроль над процессом запуска и выполнения скетча. Размер стека в этом случае берется из пункта Component config → ESP System Settings → Main task stack size (как, собственно, и другие параметры главной задачи – привязка с ядру, приоритет).

 


Альтернативный вариант создания проекта ESP-IDF + Arduino ESP32 из шаблона

Как мы выяснили, процесс создания базовой части проекта ESP-IDF + Arduino as component не сильно сложный. Теперь вы понимаете, надеюсь, суть процесса, и сможете повторить в случае необходимости.

Но есть способ ещё проще, который оставляет многие вещи “за ширмой”: можно просто создать проект на основе уже готового шаблона espressif/arduino-esp32:hello_world. Например так:

idf.py create-project-from-example "espressif/arduino-esp32^3.3.12:hello_world"

Но для этого придется либо воспользоваться “внешним” терминалом, чтобы сразу поместить проект в нужный каталог. Либо вручную переместить папку с проектом в нужное место по завершении.

Процесс выглядит так:

  1. Откройте IDF Powershell нужной версии (для Windows | для Linux необходимо открыть терминал и выполнить ./export.sh из нужной вам версии ESP-IDF)
  2. Перейдите в каталог, годе вы планируете создать проект, например cd C:\Projects\Espressif\dzen
  3. Создайте проект из шаблона: idf.py create-project-from-example "espressif/arduino-esp32:hello_world"
  4. Переименуйте каталог проекта как вам требуется, например у меня это arduino32-as-component, но вы можете использовать любое другое имя.
  5. При необходимости настройте ESP-IDF и Arduino Component, как это описано выше. Хотя в данном случае это не строго обязательно – нужные значения по умолчанию уже предустановлены через файл sdkconfig.defaults.
  6. Enjoy!

Подключение к проекту сторонних библиотек

Если вы создавали скетчи в Arduino IDE, то, наверное, помните как там подключаются сторонние библиотеки: зашли в менеджер библиотек, выбрали нужную, нажали “установить”. В ESP-IDF нет “визуального” каталога библиотек, как в Arduino IDE. Да, есть централизованный реестр компонентов, но это в основном компоненты для работы c самой ESP-IDF, а не Arduino core.

Шеф! Всё пропало!!!!? Отнюдь! Подключить привычные вам сторонние библиотеки можно, только для этого придется приложить чуть больше усилий, чем многие привыкли.

Как я уже упомянул выше, в режиме ESP-IDF + Arduino core as comonent придется подключать сторонние компоненты (т.е. “бывшие” библиотеки) по общим правилам ESP-IDF. про которые можно почитать тут: [Компоненты ESP-IDF и их подключение к проекту]. Настоятельно рекомендую ознакомится, дабы понимать “физику процесса”. Если кратко: любой компонент ESP-IDF просто обязан иметь файл CMakeLists.txt, в котором описаны правила сборки и зависимости от других компонентов. Если ваша библиотека уже имеет такой файл в формате ESP-IDF – прекрасно, просто следуйте способам, изложенным в [Компоненты ESP-IDF и их подключение к проекту]. 

Если ваша библиотека не имеет “своего личного”CMakeLists.txt, вам придется создать его самостоятельно, либо использовать CMake-механизмы для её подключения. И для этого у вас есть как минимум три путя (на самом деле можно придумать больше, но пока не будем усложнять)…

Вариант 1: Локально — добавить как компонент проекта (рекомендуется)

Создайте папку components в корне вашего проекта и скачайте библиотеку в эту папку (любым удобным вам способом – через Git, через файловый менеджер и т.д.), затем создайте для неё CMakeLists.txt вручную. 

Например для библиотеки components/my_library1/  создайте файл components/my_library1/CMakeLists.txt:

idf_component_register(SRCS "new_library.cpp" "another_source.c"
                      INCLUDE_DIRS "."
                      REQUIRES arduino-esp32
                      )

Укажите в нем реальные исходные файлы библиотеки в SRCS [Adding arduino library].

 

Вариант 2: Глобально — добавить библиотеку в папку arduino-esp32

Если вы хотите, чтобы ваша библиотека была доступна во всех ваших проектах, которые основаны на платформе arduino-esp32, можно добавить её к официальным библиотекам, которые уже имеются в составе фреймворка. Но этот способ подойдет вам, только если вы также используете глобальный каталог Arduino Core (см. Вариант 4. Использование общей копии Arduino ESP32 для нескольких проектов одновременно).

Шаг 1. Добавьте её в каталог libraries пакета arduino-esp32, например сюда: C:\Projects\Espressif\Arduino\arduino-esp32\libraries\my_library1.

Шаг 2. Отредактируйте файл CMakeLists.txt, который находится в папке пакета arduino-esp32, например C:\Projects\Espressif\Arduino\arduino-esp32\CMakeLists.txt так:

  • Добавьте исходники в блок set(LIBRARY_SRCS ...):
    set(LIBRARY_SRCS
      ...
      libraries/my_library1/src/my_library1.cpp
      libraries/my_library1/src/my_library1_extra_file.c
  • Добавьте путь к заголовкам в блок set(includedirs ...):
    set(includedirs
      ...
      libraries/my_library1

 

Вариант 3: Глобально, но отдельно от arduino-esp32

Можно также модифицировать этот вариант, и расположить вашу библиотеку “вне” arduino-esp32, но всё равно отдельно от проектов – в этом случае вам все равно придется создать CMakeLists.txt как в первом варианте, и подключать к проекту, как мы это сделали с самим Arduino.

idf_component_register(SRCS "new_library.cpp" "another_source.c"
                      INCLUDE_DIRS "."
                      REQUIRES arduino-esp32
                      )

В CMakeLists.txt каждого проекта добавьте:

set(EXTRA_COMPONENT_DIRS 
    "C:/Projects/Espressif/Arduino/arduino-esp32"
    "C:/Projects/Espressif/Arduino/my_library1"
)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my_project)

Этот способ, лично на мой взгляд, самый правильный, если вы работаете над несколькими проектами одновременно.


Использование ESP_LOG вместо Serial.println() в Arduino + ESP-IDF

Обычно в Arduino используют для отладки Serial.println() и аналоги. Но это не всегда удобно – например нельзя быстро “отключить” логи, как это можно провернуть с ESP_LOG. Но, поскольку мы в данном случае используем связку ESP-IDF + Arduino, то бонусом получаем возможность пользоваться макросами ESP_LOGI(), ESP_LOGW(), ESP_LOGE() и т.д..

В вашем .cpp файле просто включите заголовок #include "esp_log.h" и пользуйтесь на здоровье:

#include "esp_log.h"

static const char* TAG = "MyModule";

void setup() {
    ESP_LOGI(TAG, "Hello from setup!");
    ESP_LOGD(TAG, "Debug value: %d", 42);
    ESP_LOGE(TAG, "Something went wrong!");
}

Вывод в лог будет выглядеть следующим образом:

I (56) MyModule: Hello from setup!
D (57) MyModule: Debug value: 42
E (58) MyModule: Something went wrong!

Напомню, отключить логи полностью или частично можно через меню Component config → Log → Default log verbosity.

Если вы пишете код, который должен компилироваться и в обычной Arduino IDE, можно добавить совместимость:

#ifdef ARDUINO_ARCH_ESP32
#include "esp32-hal-log.h"
#endif

 

Ну а на этом у меня все, разрешите откланяться… До следующих встреч!


Ссылки

Оцените по шкале от 1 до 5 - насколько эта статья была Вам полезна?
[ 0 из 5, всего 0 оценок ]

-= Каталог статей (список по разделам) =-   -= Архив статей (плитками, все подряд) =-

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

98  −    =  96