Добрый день, уважаемые читатели!
Работая над одним из проектов, я понял, что набор моих библиотек для ESP32, которые я использую в своих проектах уже несколько лет, нужно срочно и кардинально переделывать. Я, как мог, откладывал этот момент, но дальше тянуть стало уже нельзя. Я просто “уперся” в некоторые ограничения, которые сам же себе и создал когда-то; а изменить это все “на лету” сложнее и дольше, чем переписать все с нуля. Что называется “назрело”… На этот раз я решил не разбивать код на множество мелких отдельных библиотек, а реализовать в виде нескольких относительно “крупных” библиотек-компонент – это упростит подключение их к проекту и настройку. Кроме того, при создании библиотек я решил отказаться от platformio и использовать “родной” для ESP32 инструмент – Espressif IDE. Поэтому я и решил заново обновить на своем компьютере Espressif IDE в виде плагина для Visual Studio Code (давненько я им не пользовался и версия существенно устарела).
Читатели, которые уже пробовали устанавливать ESP-IDF на свой компьютер, возможно спросят – “а на… какого х..удожественного замысла” нужна эта статья? Ведь процесс установки ESP-IDF в windows, в общем-то, не представляет никаких особых трудностей – “нажал пару кнопок, и готово”. Но, оказывается, с китайскими продуктами не всегда всё так просто, как это может показаться на первый взгляд. Вот сейчас и обсудим тонкие моменты и подводные камни, которые могут встретиться на этом пути. А также поговорим о том, как установить несколько версий ESP-IDF на один компьютер.
Примечание автора: все нижесказанное относится к моменту выхода статьи (~ ноябрь 2024 года). Cпустя некоторое время процесс установки (каталоги, последовательность действий и т.д.) может измениться, скриншоты перестанут соответствовать действительности. Но, тем не менее, статья не должна особо потерять в актуальности. Просто учтите этот момент при чтении.
Варианты установки Espressif IDE
Как я уже писал ранее, программную среду для разработки под ESP32 – ESP-IDF можно скачать и установить на компьютер в виде двух плагинов: Eclipse Plugin и VSCode Extension. Eclipse Plugin, хоть и плагин, но устанавливается с намертво интегрированной внутри сторонней IDE Escipse CDT, поэтому выглядит как полноценная программа – поэтому этот вариант часто называют просто Espressif-IDE ( подробнее о инструментах для ESP32 здесь ).
Eclipse plugin ( Espressif IDE )
Visual Studio Code plugin
Договоримся, что в данной статье под термином Espressif-IDE мы будем понимать Eclipse plugin, а плагин (иногда пишут расширение) для VSCode так и будем называть – плагин для VSCode или VSCode Extention. Запомним этот факт, чтобы не путаться в дальнейшем.
Лично мне больше нравится более строгий и лаконичный интерфейс Visual Studio code, но, конечно же каждый разработчик волен сам решать, какой плагин-IDE выбрать для своей работы. Но тут приходится признать, что Espressif IDE иногда предоставляет более удобные способы выполнения некоторых действий, чем плагин VSCode, поэтому желательно иметь на компьютере сразу обе версии IDE. Хуже не будет (но это не точно). А почему “не точно” – вам станет из текста ниже.
На момент написания статьи мне известны три способа установки ESP-IDF на компьютер с windows:
- С помощью online-инсталлятора ESP-IDF Eclipse Plugin (Espressif-IDE)
- С помощью offline-инсталлятора ESP-IDF Eclipse Plugin (Espressif-IDE)
- С помощью внутренних инструментов VSCode Extention
В принципе, все три варианта устанавливают один и тот же фреймворк – ESP-IDF и набор инструментов к нему. Но VSCode Extention не устанавливает автоматически ярлыки для запуска командных файлов из операционной системы, которые могут быть нам очень полезны в дальнейшем. Кроме того, на момент написания статьи установщик VSCode Extention имеет довольно досадный баг, который, впрочем никак не проявляется при “обычной установке”.
Если вы планируете использовать только какой-то один вариант IDE (Eclipse Plugin либо VSCode Extention), то проблем с установкой у вас возникнуть не должно. Просто скачайте плагин или программу-установщик и следуйте инструкциям. Дальше статью можно не читать ))).
Но если Вы планируете, как и я, установить и использовать сразу оба варианта – Eclipse Plugin и VSCode Extention, то вас ждут заботливо расставленные индусскими китайскими программистами грабельки.
Дело в том, что все они устанавливают одну и ту же версию ESP-IDF, но в разные каталоги! То есть, если вы захотите одновременно установить Espressif IDE “саму по себе” и плагин для VSCode, то при настройках “по умолчанию” вы получите две копии одного и того же фреймворка, но в разных каталогах на диске. Мало того, что это лишние гигабайты, так еще и поддерживать этот бардак в рабочем состоянии будет гораздо сложнее. Да, я таки знаю о том, что все способы установки предполагают возможность “подхватить” ранее установленные версии ESP-IDF и toolchain, но программные “косяки” установщиков не позволяют сделать это просто и беззаботно. Да и “каталоги по умолчанию”, которые используются при установке, меня мало устраивают.
То есть в данной статье мы постараемся добиться, чтобы при одновременной установке VSCode Extention и Espressif IDE использовались одни и те же каталоги ESP-IDF и toolchain. Но прежде чем мы решим эту задачу, нам придется хотя бы немного разобраться со “внутренним устройством” ESP-IDF.
Структура ESP-IDF и каталоги установки
ESP-IDF состоит из двух основных частей:
- Собственно фреймворка ESP-IDF, в котором содержаться все компоненты и API, используемые при создании программного кода.
- Набора инструментов, называемых tools или toolchain – здесь находится все необходимое для компиляции вашего проекта и загрузки его в SoC:
Пути к указанным каталогам обозначены как:
- IDF_PATH – путь (каталог) к выбранной в текущий момент версии фреймворка ESP-IDF
- IDF_TOOLS_PATH – путь к набору инструментов toolchain
Это две основные системные переменные, которые нам понадобятся в дальнейшем для понимания сути процессов. Кроме них, система сборки использует и другие переменные вида IDF_что-то-там_PATH, но они получаются из двух указанных выше и нам не важны.
Версий ESP-IDF в системе может быть несколько (например 4.4, 5.0, 5.1 и т.д.), а вот toolchain набор инструментов – как правило один на всех (но это не точно – например версия python-а может различаться). Поэтому IDF_PATH может быть разным от проекта к проекту (например если вы используете разные версии фреймворка для тестирования), а вот IDF_TOOLS_PATH, скорее всего, будет одинаковым.
При установке важно помнить, что IDF_PATH не должен совпадать с IDF_TOOLS_PATH, но при этом один может легко помещаться в другом. Поэтому логично разместить IDF_PATH внутри IDF_TOOLS_PATH, просто ради того, чтобы не разводить бардак на диске компьютера.
Каталоги установки по умолчанию
Espressif-IDE. Если вы устанавливаете ESP-IDF с помощью offline или online-установщика в виде сборки с Eclipse (Espressif-IDE), то по умолчанию вам будут будут предложены следующие каталоги (для версии 5.3.1 и windows):
- IDF_PATH = C:\Espressif\frameworks\esp-idf-v5.3.1
- IDF_TOOLS_PATH = C:\Users\%USERPROFILE%\.espressif, где %USERPRIFILE% – имя вашей учетной записи в системе
Зачем было так кардинально разносить каталоги с фреймворком и инструментами – мне совершенно не понятно. Тем более, что инструменты ставятся в профиль пользователя, а фреймворк доступен всем и сразу.
VSCode Extention. Если вы устанавливаете ESP-IDF с помощью плагина для VSCode, то пути установки для фреймворка по умолчанию будут несколько другими:
- IDF_PATH = C:\Users\%USERPROFILE%\esp\v5.3.1\esp-idf
- IDF_TOOLS_PATH = C:\Users\%USERPROFILE%\.espressif
Причем “хвост” пути (v5.3.1\esp-idf) мало того, что “задом наперед”, так его еще и изменить невозможно.
Как видите, если вы установите оба варианта IDE (и для VSCode, и для Eclipse) с каталогами по умолчанию, то получите две копии фреймворка. Что ж будем исправлять ситуацию и “сливать” все в одно, строго определенное место.
Мой вариант
Для себя я выбрал несколько другую структуру каталогов. Это не обязательно должно быть “только так и именно так”, вы можете выбрать другие каталоги, на другом разделе / диске, например.
- IDF_PATH = c:\Projects\Espressif\.esp-idf\frameworks\esp-idf-v5.3.1\
- IDF_TOOLS_PATH = c:\Projects\Espressif\.esp-idf
То есть в моем случае IDF_PATH располагается внутри IDF_TOOLS_PATH в подкаталоге frameworks, что позволяет удобно хранить в одном месте множество разных фреймворков разных версий. Ну а toolchain и так всегда один. Пример моей структуры каталогов вы видите на рисунке:
Целевая структура каталогов.
Примечания:
1. Точка в имени “базового” каталога – “.esp-idf” нужна только для того, чтобы при сортировке по имени он находился вверху списка каталогов. С тем же успехом можно назвать каталог как “!esp-idf” или “#esp-idf” или даже “#esp-idf#” – я иногда этим пользуюсь чтобы расположить отдельные подкаталоги нужным мне образом.
2. Префикс C:\Projects не обязателен – он нужен мне только для того, чтобы хранить в одном общем каталоге разные проекты разных языков и сред программирования.
Последовательность установки
Теперь давайте попробуем установить оба варианта IDE (и для VSCode, и для Eclipse) так, чтобы и фреймворк и тулчайн установились в выбранные выше каталоги и всё это добро работало нормально. Установить ещё мало – нужно правильно настроить и пользоваться.
Зачем мне нужны оба? VSCode, лично на мой взгляд, более красив, удобен и лаконичен. Но вместе с Eclipse ставятся необходимые мне пакетные файлы, которые почему-то “забыли” в версии для VSCode. Да и лишним он точно не будет – в отличие от собственно фреймворка, IDE много места не просит.
Все варианты установки предполагают вариант сценария, когда вместо скачивания и копирования новых файлов, можно “подхватить” с диска ранее установленные копии ESP-IDF и toolchain-а. Кажется – вот оно – счастье! Пользуйся и радуйся. Установил одно IDE, подхватил другой… Но…. “если бы да кабы мешают как столбы”… Как это часто бывает, в одном случае сломано одно, в другом – совершенно другое.
Начинать установку с VSCode с одной стороны кажется глупо – путь установки испорчен скриптом установки – то самое обязательное корявое окончание \v5.3.1\esp-idf, и не подлежит ручному исправлению. Можно конечно, смириться с этим прискорбным фактом и принять этот как есть, тогда все станет несколько проще. Но мои природное упрямство и перфекционизм не оставили мне такой возможности.
“Ха!” – скажете вы – “а в чем проблема вначале установить “полную” IDE, а потом подхватить её каталоги из VSCode“? А вот в этом:
Нажмите для увеличения
При попытке выбрать в VSCode ранее установленную “извне” версию ESP-IDF вылетает ошибка: “c:\Projects\Espressif\.esp-idf\tools\idf-python\3.11.2\python.exe -m pip” is not valid (ERROR_INVALID_PIP). Выяснилось, что оба варианта установщика для ESP-IDF Eclipse Plugin (Espressif-IDE) некорректно устанавливают python в toolchain. Да, да, вот именно так – один установщик “криво” ставит одно, другой – другое.
Если кратко, то на текущий момент я выяснил следующее:
- При установке VSCode Extention не устанавливаются командные файлы для запуска idf.py вне IDE (из командной строки windows), что делает невозможным пакетную сборку нескольких проектов последовательно. Кроме того, путь к фреймворку я считаю не совсем корректным
- При установке Eclipse Plugin (Espressif-IDE) некорректно устанавливается локальная копия python. На работу из собственно самой IDE это, кажется, не влияет, но делает невозможным использовать эту же самую копию ESP-IDF и, самое главное, toolchain в VSCode Extention.
В общем – все как всегда. Тут недопилили, тут сломали – хотели как лучше, получилось как всегда. У меня сложилось впечатление, что работают над этими вариантами разные команды разработчиков, которые мало общаются между собой.
Поэтому, единственно рабочий вариант для текущих версий установщиков и софта такой:
- Скачать плагин для VSCode и с его помощью установить ESP-IDF и toolchain в каталог c:\Projects\Espressif\.esp-idf\, но “хвост” пути к фреймворку будет “не по феншую”. И не будет “батников” для запуска ESP-IDF из командной строки вне VSCode
- Вручную исправить пути к фреймворку до правильного, например c:\Projects\Espressif\.esp-idf\frameworks\esp-idf-v5.3.1\. Таки да, в VSCode она пока перестанет корректно работать. Не обязательно
- С помощью offline или online инсталлятора выполнить установку Espressif IDE с использованием уже установленной копии.
- Вернуться в VSСode и повторить установку, но уже в режиме USE EXISTING SETUP, что бы настроить плагин на внесенные изменения. Только если вы выполняли пункт 2.
Приступим к практической реализации.
Установка ESP-IDF VSCode Extention
Вначале было слово нам необходимо установить сам плагин. Если он у вас еще не установлен. Для этого перейдите на вкладку Plugins и введите в строке поиска “ESP-IDF”:
Нажмите кнопку Install или Установить. При этом в систему пока не ставится никаких инструментов и фреймворков, поэтому процесс протекает очень быстро – буквально через пару секунд слева появится фирменный значок Espressif. Жмякаем на него и попадаем в главное меню Espressif-IDE. Нам нужен самый верхний пункт – вот тут уже начинается процесс установки собственно ESP-IDF и набора инструментов к ней.
Выбираем режим ADVANCED, а в нем нужную версию и обязательно указываем желаемые пути:
Нажимаем кнопку Configure Tools и …. вот теперь придется изрядно подождать – идем пить чай с печеньками. Когда ESP-IDF будет скачана, установщик выдаст еще один запрос – устанавливать ли toolchain, подтверждаем и ждем завершения.
Если вы планируете далее устанавливать Espressif IDE вне VSCode, то после установки закрываем VSCode, находим папку с установленным фреймворком и вручную исправляем путь к нему. Впрочем – можете оставить все как есть, на работоспособность это не повлияет. Но мой внутренний перфекционист выражает протест!
Установка Eclipse Plugin (Espressif-IDE)
Для установки Espressif-IDE предусмотрено аж два варианта: online и ofline установщик.
- Online версия имеет небольшой размер, быстро скачивается и запускается, но в процессе работы в свою очередь уже сама скачивает необходимые пакеты с сервера. Этот вариант предлагает гораздо больше опций и возможностей – например предлагает дополнительно установить плагин для языка Rust. Его можно использовать для установки нескольких версий ESP-IDF на ваш компьютер.
- Ofline версия уже содержит внутри себя весь необходимый софт и больше подходит для автономной установки на компьютер с флешки, например.
Я воспользовался online версией. Заходим на страницу dl.espressif.com/dl/esp-idf/, нажимаем на кнопку Universal Online Installer и после скачивания файла запускаем его. На первом экране мастер проверяет настройки операционной системы.
Если в результате проверки кнопка “Apply Fixes” будет доступна, то можно сразу же внести изменения в реестр путем её нажатия. После этого можно нажать кнопку Next и мы попадаем в окно выбора режима установки.
Если вы уже установили копию ESP-IDF с помощью VSCode Extention – выбираем “Use an existsing ESP-IDF directory” (использовать уже существующий каталог с ESP-IDF), иначе – “Download ESP-IDF” (Скачать и установить новую копию ESP-IDF).
В случае с “Use an existsing ESP-IDF directory” под списком нажимаем кнопку “Browse…” и указываем каталог, куда мы ранее установили ESP-IDF (не toolchain!), то есть в моем случае это c:\Projects\Espressif\.esp-idf\frameworks\esp-idf-v5.3.1\.
Впрочем, порядок работы в режиме “Download ESP-IDF” не сильно отличается от “Use an existsing ESP-IDF directory“.
Опять таки нажимаем кнопку Next.
Здесь выбираем каталог уже для набора инструментов – c:\Projects\Espressif\.esp-idf\ в моем случае и идем далее.
Выбираем компоненты, которые будут установлены. Если вы хотите запускать Espressif-IDE, не забудьте отметить соответствующую опцию. Стоит проверить и список целевых платформ (ESP32, ESP32-S и т.д.), которые вам могут понадобиться в ваших проектах.
На следующем экране еще раз проверяем каталоги установки и параметры установки:
После нажатия Install начинается собственно процесс установки. Если мы использовали режим “Use an existsing ESP-IDF directory“, то ESP-IDF не скачивается и не переустанавливается, а вот toolchain устанавливается всегда, но “поверх” старой установки, затирая только существующие файлы и не удаляя “лишние”. Что нам и требуется.
По окончании установки будет показано вот такое окно:
Во многих инструкциях настоятельно рекомендуется обязательно выполнить скрипты “Run ESP-IDF PowerShell Enviropment” и “Run ESP-IDF Command Prompt Enviropment“, якобы эти действия “прописывают” переменные окружения IDF_PATH и IDF_TOOLS_PATH в системе.
На самом деле – это не совсем так. Дело в том, что скрипты действительно регистрируют переменные окружения IDF_PATH и IDF_TOOLS_PATH в системе, но… только для текущего сеанса командной строки. То есть как только вы закроете текущее окно Command Prompt, данные переменные исчезнут бесследно.
Поэтому выполнять данные скрипты смысл, конeчно, есть, но только для того, чтобы проверить, что они работают корректно. Устанавливаем галочки (одну или обе) и нажимаем Finish. В открывшемся окне командного интерпретатора введите команду idf.py. Если установка прошла успешно, вы должны получить примерно такой ответ:
На этом установку Espressif IDE можно считать законченной.
Настраиваем ESP-IDF VSCode Extention для работы с ранее установленной ESP-IDF
Теперь настала очередь “восстановить” ранее созданную установку ESP-IDF в VSCode.
Это нужно сделать только если вы переименовали каталог c:\Projects\Espressif\.esp-idf\frameworks\v5.3.1\esp-idf\ в c:\Projects\Espressif\.esp-idf\frameworks\esp-idf-v5.3.1\! В противном случае выполнять данный этап не требуется. Но данная инструкция может пригодится при добавлении новых версий ESP-IDF, установленных с помощью менеджера версий (подробнее ниже).
Запускаем Visual Studio Code, переходим на вкладку Espressif и выбираем пункт меню “Configure ESP-IDF Extention“. Здесь нам потребуется выбрать “Use exisiting setup“:
Здесь можно сразу выбрать одну из ранее установленных версий (будьте, пожалуйста, внимательны) или найти новую на диске:
Укажите параметры подключаемой версии:
После этого нажмите “Install” и дождитесь завершения работы мастера. На этом подготовка к работе закончена.
Через это-же меню “Configure ESP-IDF Extention” можно изменить версию ESP-IDF, которая будет использоваться для сборки проектов.
Установка дополнительных версий ESP-IDF
Время идет, разработчики ESP-IDF не стоят на месте и всё время что-то меняют. Со временем когда-то установленная ESP-IDF рано или поздно устареет. А может быть и обратная ситуация – проект собранный, например, для ESP-IDF 4.4 откажется собираться для ESP-IDF 5.1. То есть вам могут понадобиться одновременно несколько версий ESP-IDF на одном и том же компуктере. И таки это сравнительно несложно организовать.
Проще всего воспользоваться online-установщиком. Запустите его (при необходимости скачав с сервера свежую версию) и выберите режим “Download ESP-IDF” (Скачать и установить новую копию ESP-IDF). После этого выберите версию которая вам необходима и выполните установку.
Не забудьте подкорректировать путь к ESP-IDF в соответствии с нашими правилами. Путь к toolchain, разумеется, должен остаться прежним.
Другой вариант – воспользоваться менеджером фреймворков в самой Espressif IDE. Запустите Espressif IDE и выберите пункт меню “ESP-IDF Manager“.
На скриншоте видно, что у нас установлена только одна версия ESP-IDF:
Нажмите кнопку “Add ESP-IDF” для добавления новой версии.
После нажатия кнопки “полный финиш” IDE самостоятельно скачает и установит выбранную версию ESP-IDF на ваш компьютер. Причем toolchain опять установится “поверх” в очередной раз.
В списке вы можете выбрать любую из установленных версий как активную для текущего проекта.
Если вы работаете в VSCode Extention, добавьте установленную версию через “Configure ESP-IDF Extention“, как я это описывал в предыдущем разделе.
Работа с ESP из командной строки windows
Обе версии Espressif IDE относительно нормально работают в самих IDE – VSCode или Eclipse. Но часто бывает необходимость выполнить какую-либо команду “извне”. Зачем?
Во первых – для потоковой сборки нескольких проектов одновременно. Например если вносишь какие-либо изменения в общие для всех проектов библиотеки и необходимо перекомпилировать все существующие проекты и получить образы прошивок для загрузки на устройства через ОТА.
Вторая насущная необходимость – menuconfig. Не знаю, как вам, но мне не понравился подход, предложенный в Espressif IDE и ESP-IDF VSCode Extention.
Я все-таки предпочитаю старый добрый MS-DOS вид. Запустить его можно в окне терминала VSCode, но для этого придется использовать команду “ESP-IDF Terminal“:
Только вот выглядит это “не очень”, и самое главное – в терминале VSCode не работают клавиши “вверх” и “вниз” для перемещения по меню. Проблема эта была известна еще 5 лет назад, но её еще не решили, и не собираются решать, видимо.
Поэтому я предпочитаю делать это “извне” любой IDE, прямо из командной строки Windows (коли я пока еще ей пользуюсь). Но если вы попытаетесь просто открыть cmd.exe и выполнить “idf.py“, то получите скорее всего ошибку: “idf.py” не является внутренней или внешней командой, исполняемой программой или пакетным файлом или “idf.py” is not recognized as an internal or external command, operable program or batch file.
При установке Espressif IDE нам были заботливо созданы два ярлычка для запуска командной строки или PowerShell.
Если запустить один из них и попытаться вновь выполнить команду idf.py, то все работает прекрасно! Но нужно “вручную” переходить в каталог проекта.
Давайте попробуем понять, что такого “хитрого” делает этот батник. Если вам интересно, конечно.
Этот ярлык “смотрит” на файл “C:\Projects\Espressif\.esp-idf\idf_cmd_init.bat“, но при этом рабочий каталог у него настроен как “C:\Projects\Espressif\.esp-idf\frameworks\esp-idf-v5.3.1\“, то есть каталог текущей версии ESP-IDF. Находим этот файл и смотрим.
Во-первых он устанавливает переменные IDF_PATH и IDF_TOOLS_PATH, но только на время текущего сеанса работы (пока батник запущен).
А во-вторых, он добавляет “макросы” DOSKEY (опять же только на время текущего сеанса):
set PREFIX=%IDF_PYTHON% %IDF_PATH% DOSKEY idf.py=%PREFIX%\tools\idf.py $* DOSKEY esptool.py=%PREFIX%\components\esptool_py\esptool\esptool.py $* DOSKEY espefuse.py=%PREFIX%\components\esptool_py\esptool\espefuse.py $* DOSKEY espsecure.py=%PREFIX%\components\esptool_py\esptool\espsecure.py $* DOSKEY otatool.py=%PREFIX%\components\app_update\otatool.py $* DOSKEY parttool.py=%PREFIX%\components\partition_table\parttool.py $*
То есть набирая в командной строке “idf.py” мы фактически выполняем команду “%IDF_PYTHON%\tools\idf.py“. Вот и весь секрет.
Ну и в заключение приведу только некоторые из команд, которые могут быть полезны при работе над проектами.
- idf.py clean – Удалить скомпилированные файлы из каталога проекта
- idf.py all или idf.py build – Компилировать проект
- idf.py menuconfig – Запустить меню конфигурации проекта
- idf.py flash – Записать прошивку в микроконтроллер
- idf.py monitor – Запустить монитор COM-порта
- idf.py docs – Открыть документацию в браузере
Конечно же, команд гораздо больше, для вывода полного списка просто наберите idf.py в терминале.
На этом пока всё. До следующих встреч на сайте и на telegram-канале!
💠 Полный архив статей вы найдете здесь
Пожалуйста, оцените статью: