Создание PlatformIO / ESP-IDF проекта и настройка platformio.ini

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

В данной статье я расскажу как создать проект, как настроить файл конфигурации PlatformIO, как подключить внешние библиотеки к вашему проекту. Это статья для начинающих, то есть для тех, кто будет переходить на ESP-IDF с Arduino. Если Вы всё это знаете и умеете – то вы можете поделиться своими знаниями и умениями в комментариях, если я что-то вдруг упустил (я ведаю настройками только в той части, которыми сам пользовался).

Итак, запускаем VSCode (если он у вас ещё не установлен, вы можете сделать это, используя одну из предыдущих статей), и попадаем на стартовую страницу:

Эта страница нам нисколько не поможет (в нашем случае), поэтому смотрим на нижнюю панель и ищем на ней кнопку ? “PlatformIO: Home“:

Если у вас нет такой кнопки, это означает, что PlatformIO у вас пока не установлен, более подробно об этом можно прочитать из другой статьи.

После нажатия на ? “PlatformIO: Home” откроется стартовая страница PlatformIO.

Несмотря на то, что мы русифицировали VSCode, на PlatformIO, увы, это никак не влияет. К этому моменту у Вас уже должна быть установлена платформа Espessiff 32, если это не так – используйте одну из предыдущих статей.

Дальше пока все просто – жмем кнопку “New Project” и выбираем параметры будущего проекта (плату пока подключать к USB-порту не обязательно):

Вначале вводим название проекта. Затем выбираем плату. Для ESP32-DevKitC я выбираю “Espressif ESP32 Dev Module” – всё отлично подходит и работает. В третьем поле выбираем framework, на котором будем писать наше первое приложение: Arduino или Espressif IoT Development Framework. В конце можно указать произвольную папку проекта, а можно и не указывать – тогда PlatformIO сам создаст папку “%базовый каталог проектов%\%имя проекта%”. И нажимаем Finish. Ждем секунд 10-20, пока PIO создает все необходимые файлы и папки. Пока ждем, PlatformIO покажет нам несколько подсказок по его использованию.

 

---

Каталоги проекта

PlatformIO создаст в выбранном каталоге несколько подкаталогов (подпапок):

• .pio\ – папка для “служебного пользования” PlatformIO, здесь будут создаваться файлы, здесь можно будет найти скомпилированный бинарник для загрузки в устройство “вручную”.
• .vscode\ – ещё одна папка для “служебного пользования” PlatformIO, здесь хранятся настройки VSCode. Здесь есть что можно поправить, в некоторых случаях.
• include\ – этот каталог предназначен для заголовочных файлов проекта. Надеюсь, вы знаете, что это такое ?.
• lib\ – сюда можно поместить локальные библиотеки проекта. “Локальные” в данном случае я понимаю как использующиеся только в данном проекте, но не в других. Сюда можно поместить части проекта, отвечающие за ту или иную функциональность проекта. Я, например, помещаю сюда файлы “прикладных” задач проекта, то есть конкретно ту автоматизацию, которую и будет выполнять данное устройство. Если у Вас есть библиотеки, которые используются сразу в нескольких ваших проектах, их лучше поместить в каталог “вне” каталога проекта для совместного использования. Я знаю, есть любители кидать в каждый проектов свои “локальные” копии общих библиотек, но я категорически не поддерживаю подобную практику, так как это приводит к огромным проблемам при дальнейшем обновлении кода.
• src\ – здесь, собственно, и находится исходники вашего проекта. У меня, обычно, здесь только файл main.c, которые только запускает все нужные задачи и сервисы, ну и файл настроек CMakeLists.txt. Но ничто не мешает накидать сюда прикладных файлов, игнорируя каталог lib (см. выше), но тогда заголовочные файлы прикладных задач вам придется положить в папку include.
• test\ – здесь будут ваши автоматизированные тесты вашего же кода, когда вы их создадите.

Кроме этого, в каталоге проекта появится и несколько файлов:

• .gitignore – файл, в котором вы можете указать, какие из файлов не нужно загружать в GitHub.
• CMakeLists.txt – настройки компонентов системы сборки CMake. Его пока не нужно трогать, PIO всё настроит за вас.
• platformio.ini – файл настроек собственно PlatformIO. Именно по этому файлу VSCode “понимает”, что это проект PlatformIO, а не какой-либо ещё. В этой статье мы рассмотрим этот файл поподробнее.
• sdkconfig.esp32dev – файл настроек компонентов ESP-IDF. В нем очень много опций, некоторые из них мы обсудим в следующей статье. Сюда же можно добавить и “прикладные” настройки, но я лично не люблю этот способ, и не пользуюсь им.

---

Настройка проекта

Как вы уже наверное поняли, существует несколько различных уровней настроек проекта:

• Параметры CMake (системы сборки, с помощью которой компилируется проект)
• Параметры проекта PlatformIO
• Параметры самой ESP-IDF, так называемый sdkconfig
• Файл конфигурирования разделов Flash-памяти
• Ну и файл настройки Вашего “прикладного” проекта, если Вы пожелаете таковой сделать. Опционально, строго по вашему желанию. Можно и все ваши личные настройки запихнуть в sdkconfig (как это сделать, я расскажу позже).

В этой статье я кратенько расскажу только о первых двух уровнях – CMake и PlatformIO. Как настроить SdkConfig, я расскажу в следующей статье; а разделы поначалу можно вообще не трогать, до того момента, пока Вам не понадобиться OTA или NVS (загадочные названия пока? – ничего, разберемся в дальнейшем).

 

Параметры CMake

Честно говоря, я сам пока не очень владею всеми приемами конфигурирования CMake. Да в начале и не нужно ничего конфигурировать – PlatformIO сам всё настроит при создании проекта. Упомяну лишь то, что параметры системы сборки хранятся в двух (как минимум) файлах:

%project_dir%\CMakeLists.txt
%project_dir%\src\CMakeLists.txt

В первом из них максимум, что можно поменять – так это название проекта:

Во второй нам в дальнейшем придется вносить кое-какие правки, например нужно будет добавить пути к файлам TLS-сертификатов. Но пока мы не будем обсуждать этот вопрос, просто отмечу этот файл:

На этом знакомство с файлами CMakeLists.txt пока закончим и перейдем к главной цели этой статьи – файлу platformio.ini.

 

platformio.ini

Этот файл относится к настройкам PlatformIO, это файл в стиле INI. В новом проекте он выглядит просто и незамысловато:

Если нажать на ссылку https://docs.platformio.org/page/projectconf.html в комментариях к файлу, то вы попадете в справочную систему PlatformIO, где вы сможете узнать обо всех доступных опциях. Здесь я упомяну только некоторые из них, которыми я чаще всего пользуюсь.

Единственная пока секция [env:esp32dev] задает параметры компиляции проекта:

• platform = espressif32 указывает, что для компиляции проекта будем использовать платформу espressif32
• board = esp32dev определяет, для какой именно платы собирать проект
• framework = espidf ну и собственно здесь мы можем указать, какой фреймворк будем использовать.

Файл platformio.ini позволяет указать сразу несколько таких секций. Например, вы можете собирать одновременно один и тот же проект сразу для нескольких разных плат, или для espidf и для arduino одновременно. Примеры смотрите в справочной системе https://docs.platformio.org/page/projectconf.html

Кроме секции [env:esp32dev] вы можете создать отдельную секцию [env] (то есть без указания целевой платформы) – в этом случае параметры этой секции будут считаться “общими” для всех указанных целей.

 

Скорость COM-порта

Что здесь стоит сразу же исправить? Во первых, нужно указать скорость обмена данными через USB / COM-порт в двух режимах: режиме монитора и режиме загрузки прошивки в плату. Номер COM-порта можно не указывать – если вы используете только одно подключение (одну плату), то автовыбор порта делает свою работу замечательно.

По умолчанию ESP-IDF настроена на вывод логов на скорости 115200 бод, поэтому в опции monitor_speed ставим цифру 115200, этого вполне достаточно в большинстве случаев. А вот для загрузки прошивки upload_speed можно выбрать скорость и повыше (чтобы снизить время прошивки); DevKitC прошиваются нормально на скорости 921600 бод, выше уже начинаются глюки.

Фильтры COM-монитора

Следующее, что можно поправить – настроить фильтры для монитора COM-порта. Доступны такие фильтры (подробнее смотри здесь):

• default – удалить типичные коды управления терминалом из ввода
• colorize – применение разных цветов для разного типа сообщений (хм, на самом деле это не работает)
• debug – выводить и отправленное и полученное
• direct – пересылать все данные без обработок, нужен для вывода цветных отладочных логов (ошибки – красным, предупреждения – желтым и т.д.)
• hexlify – печать данных в шестнадцатеричном представлении для каждого символа
• log2file – записывать данные в файл «platformio-device-monitor-%date%.log», расположенный в текущем рабочем каталоге
• nocontrol – удалить все контрольные коды, в т.ч. CR+LF
• printable – показать десятичный код для всех символов, отличных от ASCII, и заменить большинство управляющих кодов
• time – добавить временную метку с миллисекундами для каждой новой строки (но это будет временная метка компьютера, а не самого устройства)
• send_on_enter – отправить текст на устройство на ENTER
• esp32_exception_decoder – декодер исключений Espressif 32, удобно, но уж очень медленно, я не использую
• esp8266_exception_decoder – то же самое, но для Espressif 8266

Желаемые фильтры можно перечислить либо через запятую, либо в каждой строке, как вам удобнее (мне – в каждой строке, так как в таким случае их очень удобно “комментарить”). Сделать это можно в секции [env:esp32dev] для конкретного устройства, либо в секции [env] сразу для всех устройств, сколько бы секций вы не создали.

Я пользуюсь в основном direct и log2file – иногда очень записывать протоколы вывода в файл для последующего анализа. esp32_exception_decoder я в последнее время вообще не пользуюсь, но, как видите, его следы ещё остались. Эти опции я планирую обсудить в последующих статьях, посвященных как раз отладке через COM-порт (она несколько отличается от привычного Arduino-вского “Serial.println(…))”

---

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

В PlatformIO подключение библиотек на первый взгляд выглядит существенно сложнее, чем в Arduino IDE. Нет никакого “окошечка с кнопочками” для скачивания и установки библиотек. Но не всё так страшно.

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

Существует несколько вариантов подключения библиотек к вашему проекту, в том числе:

• Локальные библиотеки проекта – их достаточно просто закинуть в папку lib проекта и забыть про них, ничего настраивать не нужно. Но в этом случае вам придется хранить свою копию библиотек в каждом из ваших проектов. Когда проектов станет больше 10, вам начнут сниться кошмары.
• Общие локальные библиотеки. Допустим вы решили создать свою библиотеку (как создать – обсудим позже) и использовать в нескольких ваших проектах. Разместите их в отдельной папке PlatformIO (например у меня это C:\PlatformIO\libs) и подключите их с помощью опции lib_extra_dirs = C:\PlatformIO\libs. В этом параметре нужно указывать корневую папку с библиотеками, а не конкретные папки библиотек. Но если структура каталогов ваших библиотек содержит больше чем 1 уровень, как у меня, придется указать все “предпоследние” уровни (см. рисунок ниже):

• Публичные библиотеки. PlatformIO предоставляет очень удобный способ подключения публичных библиотек напрямую с GitHub или из каталога библиотек PlatfortmIO. Просто укажите прямые ссылки на них в параметре lib_deps – и вам не придется следить за скачиванием и обновлением этих библиотек – PlatformIO всё возьмет на себя:
  
  

  /wp-content/uploads/pio-first-project/img011.webp

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

Есть ещё несколько опций PlatformIO, которые я использую, но для начала этого вполне достаточно. Другие опции мы обсудим в другой статье. Более того, я пока “отключу” подключенные библиотеки, чтобы они не мешали в самом первом тестовом примере. В итоге получим следующий файл:

Не забудьте сохранить изменения в файле

---

Hello, world!

Не будем изменять традициям – напишем самую простую программу, которая просто выведет в терминал “Hello, world!”. Для этого нам потребуется файл \src\main.c.

Как видите – здесь нет никаких setup() и loop(). При необходимости – вы должны сделать это самостоятельно, например так:

Давайте напишем программу, которая через каждые 10 секунд будет выводить слова “Hello, world!”. Смотрите, как это будет выглядеть в ESP-IDF:

Во первых нам нужно подключить три внешние стандартные библиотеки:

• esp_log – позволяет выводить в терминал отладочные сообщения с очень удобным функционалом. Подробнее эту библиотеку я опишу в одной из следующих статей, пока не будем акцентировать внимание на этом.
• FreeRTOS.h и task.h мне понадобились, чтобы перевести задачу в режим ожидания на 10 секунд. Зачем это нужно. Стандартной (для Arduino) функции delay() здесь нет (но вы можете сварганить её самостоятельно). Функция vTaskDelay() не блокирует центральный процессор на 10 секунд, а переводит текущую задачу в режим ожидания 10 секунд, и планировщик задач FreeRTOS просто перестает выделять этой задаче процессорное время, пока заданный период не истечёт. Таким образом, vTaskDelay() не приводит к блокировке других процессов и задач (в отличие от delay() на Arduino). Это очень важно понять на первоначальном этапе.

Компиляция и заливка в чип

Нажимаем кнопку “PlatformIO : Build” ✔ на нижней панели и ждем. В первый раз PlatformIO скомпилирует все файлы, в том числе всю библиотеку ESP-IDF, что может занять длительное время. Не пугайтесь, при следующей компиляции все будет происходить гораздо быстрее (если только вы не внесете изменения в файл sdkconfig – в этом случае ESP-IDF будет вновь полностью перекомпилирован).

Если не допустили ошибок – результат на экране. Самая примитивная программа заняла что-то около 11 КБ оперативной памяти и почти 165 КБ на flash. Многовато, да, но FreeRTOS, такой FreeRTOS… куда ж без него.

Итак, программа успешно скомпилирована, можно заливать в чип. Настало время подключить вашу плату к компьютеру. При этом вам может потребоваться установить драйвера моста COM-to-UART, который распаян на вашей плате. Можно также настроить номер COM-порта в platformio.ini, но я никогда этого не делаю – если не использовать заливку прошивки в сразу несколько плат, то в этой нет никакой необходимости, автовыбор порта и так справляется с задачей.

Нажмите кнопку “PlatformIO : Serial Monitor” (электрическая вилка), тем самым вы откроете встроенный терминал. Если у вас новая, пустая плата, вы увидите что-то подобное:

Заметили выделение строк цветом? На самом деле, это очень удобно при отладке больших программ.

Заливаем прошивку, для этого необходимо нажать кнопку “PlatformIO : Upload” ➡ и опять подождать. Терминал закроется сам собой, а после окончания прошивки будет вновь автоматически запущен:

Обратите внимание: на некоторых экземплярах плат для начала прошивки необходимо нажать и удерживать кнопку Boot, когда пойдут точки внизу экрана. После начала передачи данных кнопку можно опустить. Подробности вы можете найти здесь, но походу, это просто китайцы косячат при сборке плат, потому что некоторые экземпляры прошиваются совершенно нормально, а некоторые – нет. Впрочем, меня это не сильно беспокоит, так как почти все устройства я прошиваю через провод только при первом изготовлении, потом все обновления – только “по воздуху”.

Что ж, мы с вами создали первую прошивку для ESP32, можете поэкспериментировать с ней, например поменять “уровень” сообщений на ESP_LOGE() и посмотреть, что получится.

---

Если вам понравилась статья и вы желаете отблагодарить автора – просто кликните по любому рекламному объявлению.

💠 Полный архив статей вы найдете здесь