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

Visual Studio Code и PlatformIO: среда для больших проектов

Проект робота в VS Code и PlatformIO, связанный с платой микроконтроллера

Небольшой скетч удобно хранить в одном файле. Но проект робота быстро разрастается: появляется отдельное управление двигателями, чтение датчиков, обмен данными, настройки для платы и сторонние библиотеки. Visual Studio Code и PlatformIO помогают превратить набор файлов в воспроизводимый проект, который можно собрать, загрузить и проверить по единым правилам.

Коротко

Visual Studio Code — редактор кода с файлами проекта, подсказками, терминалом и расширениями. PlatformIO добавляет инструменты для разработки под микроконтроллеры: создаёт структуру проекта, выбирает плату и программную платформу, устанавливает зависимости, собирает прошивку, загружает её и открывает монитор последовательного порта.

Зачем это нужно​

Пока программа состоит из setup() и loop(), один файл кажется достаточным. Затем в нём оказываются десятки функций, константы для всех выводов и условия для разных вариантов робота. Изменение датчика начинает затрагивать управление моторами, а библиотека, установленная на одном компьютере вручную, отсутствует на другом.

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

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

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

Где VS Code нужен в этом репозитории​

В этой базе знаний VS Code полезен в двух разных ролях. Первая роль — редактор документации сайта: Markdown-статьи, изображения, поиск по docs, терминал для npm run build и просмотр изменений в Git. Вторая роль — среда для более крупных прошивок, где вместе с PlatformIO появляются platformio.ini, несколько исходных файлов и зависимости библиотек.

ЗадачаПодходит VS CodeНужен PlatformIO
править статью базы знанийданет
найти все упоминания терминаданет
проверить Docusaurus-сборкуда, через терминалнет
написать маленький скетч Blinkможно, но проще Arduino IDEнет
вести многофайловый проект роботадада
фиксировать библиотеки прошивки в проектедада

Сам репозиторий docs.reversi.tech является сайтом Docusaurus, а не проектом PlatformIO. Поэтому при правке документации основные команды берутся из README: установка зависимостей через npm ci, локальный запуск, npm run typecheck и npm run build. PlatformIO появляется уже в отдельных проектах прошивок, когда одного скетча Arduino IDE становится мало.

Главная идея​

VS Code отвечает за рабочее пространство редактора, а PlatformIO — за встроенный проект микроконтроллера и его операции. Они работают вместе, но выполняют разные роли.

файлы и редактор VS Code
          +
конфигурация и сборка PlatformIO
          ↓
готовая прошивка -> загрузка в плату -> наблюдение через монитор порта

Центр проекта PlatformIO — файл platformio.ini в корневой папке. Он описывает одно или несколько окружений сборки: используемую платформу, плату, фреймворк и дополнительные параметры. Когда конфигурация хранится рядом с кодом, её можно проверить в Git и передать вместе с проектом.

Путь проекта от исходных файлов и platformio.ini к прошивке, плате и монитору порта

Не путайте названия

Visual Studio Code и Visual Studio — разные продукты Microsoft. В этом уроке речь идёт о VS Code и официальном расширении PlatformIO IDE for VSCode.

Кто за что отвечает​

ИнструментОсновная рольЧто видит ученик
VS Codeредактирование и навигация по проектудерево файлов, вкладки, поиск, подсказки, терминал, систему расширений
PlatformIO IDEинтеграция задач микроконтроллера с VS Codeсоздание проекта, выбор окружения, кнопки Build, Upload, Clean и Serial Monitor
PlatformIO Coreвыполнение команд проектаустановка пакетов, сборка, загрузка, тесты и вывод диагностики
Компилятор и инструменты платформыпреобразование исходного кода в прошивку для выбранной платысообщения сборки и готовый бинарный результат
Микроконтроллервыполнение загруженной программысигналы на выводах, данные датчиков, сообщения последовательного порта

При установке PlatformIO IDE как расширения для VS Code отдельная установка PlatformIO Core обычно не нужна: официальная документация указывает, что Core встроен в расширение. Это снижает число ручных шагов в начальной настройке.

Структура проекта PlatformIO​

Команда инициализации PlatformIO создаёт знакомый каркас:

robot-project/
├── platformio.ini
├── include/
├── lib/
├── src/
│   └── main.cpp
└── test/

Папки имеют разные назначения:

ПутьЧто там хранитьПример для робота
platformio.iniконфигурацию окруженийплата Arduino Uno, фреймворк Arduino, скорость монитора
src/основной исходный кодmain.cpp, MotionController.cpp
include/заголовочные файлы проектаpins.h, robot_config.h
lib/собственные приватные библиотекимодуль драйвера двигателя
test/тестыпроверка преобразования показаний датчика

Каркас не требует немедленно заполнять каждую папку. Его смысл — дать каждому типу файла предсказуемое место. Начальный проект может содержать только platformio.ini и src/main.cpp, а модули добавляются по мере появления самостоятельных обязанностей.

Модуль

Модуль — часть программы с одной понятной ответственностью и собственным интерфейсом. Например, модуль двигателя принимает желаемые скорость и направление, а детали управления выводами скрывает внутри.

Что записано в platformio.ini​

Минимальная конфигурация для проекта на Arduino Uno может выглядеть так:

[env:uno]
platform = atmelavr
board = uno
framework = arduino
monitor_speed = 9600

Строка [env:uno] открывает окружение с именем uno. Параметр platform выбирает набор инструментов для семейства микроконтроллеров, board — конкретное описание платы, framework — программную основу, а monitor_speed — скорость обмена для последовательного монитора.

Это не код поведения робота. Файл отвечает на вопрос «как подготовить и обслуживать проект», тогда как src/main.cpp отвечает на вопрос «что должна делать программа».

В одном файле можно определить несколько окружений. Например, общий алгоритм может собираться для учебного макета и для другой платы:

[env:uno]
platform = atmelavr
board = uno
framework = arduino

[env:esp32]
platform = espressif32
board = esp32dev
framework = arduino

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

Исходный файл и Arduino-фреймворк​

В проекте PlatformIO исходный файл часто называется src/main.cpp. Для Arduino-фреймворка в нём явно подключают основной заголовок:

#include <Arduino.h>

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

void loop() {
  Serial.println("robot ready");
  delay(1000);
}

Функции setup() и loop() сохраняют привычные роли. Разница в том, что проект рассматривается как обычный набор C++-файлов с явными зависимостями. Это облегчает выделение классов и модулей, но требует внимательнее относиться к заголовочным файлам и объявлениям.

Сборка, загрузка и наблюдение​

Три действия часто воспринимают как одну кнопку, хотя они проверяют разные этапы.

  1. Build запускает сборку. Исходные файлы компилируются и связываются для выбранного окружения. Ошибка здесь означает, что готовая прошивка ещё не создана.
  2. Upload передаёт собранную прошивку на плату. Для этого нужен подходящий способ подключения и доступный порт.
  3. Serial Monitor показывает сообщения, которые контроллер отправляет через последовательный интерфейс. Скорость в программе и настройке монитора должна совпадать.

В панели PlatformIO для VS Code также доступны очистка результатов сборки и переключение окружения. Встроенный терминал VS Code позволяет запускать команды, не покидая рабочую папку проекта. Интерфейс удобен, но диагностировать лучше по тексту: имя активного окружения, первая содержательная ошибка компилятора, найденный порт и скорость монитора дают больше информации, чем цвет кнопки.

Зависимости вместо ручных копий​

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

Общий вид записи:

[env:robot]
; остальные параметры окружения
lib_deps =
  owner/library-name

owner/library-name здесь — схема записи, а не название библиотеки, которую нужно устанавливать. Для реального проекта выбирают пакет в реестре PlatformIO и используют указанную там спецификацию. Если проекту нужна определённая совместимая версия, ограничение версии также фиксируют в конфигурации.

Главное преимущество проявляется при переносе проекта. Вместо инструкции «найдите и установите несколько библиотек» разработчик получает список зависимостей рядом с параметрами платы. Git сохраняет изменения этого списка вместе с кодом.

Когда проект пора делить на файлы​

Разделение нужно не ради количества файлов. Новый модуль оправдан, когда у части программы появляется самостоятельная ответственность или чёткая граница.

Рассмотрим мобильного робота:

main.cpp              связывает подсистемы и задаёт основной цикл
MotorDriver.*         управляет направлением и скоростью двигателей
DistanceSensor.*      получает и подготавливает расстояние
SafetyController.*    решает, разрешено ли движение
robot_config.h        хранит выводы и настройки конкретной сборки

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

Есть и обратная крайность. Если вынести каждую функцию в отдельный файл, навигация станет труднее, а границы не дадут пользы. Сначала сформулируйте ответственность модуля одним предложением. Если это не получается, разделение ещё не созрело.

Пример: диагностика датчика расстояния​

Робот останавливается раньше, чем ожидалось. В большом однострочном цикле причина может скрываться между чтением датчика, фильтрацией и командой двигателя. В структурированном проекте диагностика идёт по цепочке:

сырое измерение -> обработанное расстояние -> решение безопасности -> команда моторам

Временные сообщения Serial показывают значения на границах модулей. Если измерение корректно, но решение запрещает движение, исследуется логика безопасности. Если ошибка уже в исходном значении, проверяются датчик, подключение и код чтения. PlatformIO Serial Monitor становится окном наблюдения, а не случайным потоком печати.

Пример: один код для двух стендов​

Команда может иметь Arduino Uno на учебном столе и ESP32 на прототипе. Два окружения в platformio.ini делают выбор явным. Сборка для каждого окружения проверяет, что используемые библиотеки и условные участки кода совместимы с выбранной платой.

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

Ошибки, которые стоит читать буквально​

СимптомЧто проверить первымПочему это связано с этапом
сборка не находит заголовочный файлимя подключения и lib_depsзависимость нужна до создания прошивки
код собирается не для той платыактивное окружение и boardнабор инструментов определяется конфигурацией
загрузка не начинаетсякабель, порт, права доступа и выбранное окружениеготовая прошивка ещё должна попасть на устройство
монитор показывает нечитаемые символыSerial.begin(...) и monitor_speedстороны обмениваются данными с согласованной скоростью
правка в одном модуле ломает другойинтерфейсы модулей и сообщения первой ошибкинарушение обнаруживается на границе частей проекта

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

Что запомнить о VS Code и PlatformIO​

VS Code даёт рабочее пространство для кода, а PlatformIO описывает и выполняет путь от проекта к плате. platformio.ini хранит параметры окружений и зависимости; src/, include/, lib/ и test/ разделяют обязанности файлов; Build, Upload и Serial Monitor проверяют разные этапы. Эта организация становится особенно полезной, когда у робота несколько подсистем, плат или участников разработки.

Практика​

Задание 1. Каркас проекта​

Создайте новый проект PlatformIO для доступной платы. Нарисуйте дерево созданных папок и для каждой укажите один тип файла, который мог бы понадобиться роботу с двумя двигателями и датчиком расстояния. Не добавляйте файлы без объяснения их ответственности.

Задание 2. Два модуля​

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

Задание 3. Диагностика по этапам​

Соберите проект, загрузите его и откройте Serial Monitor. Для каждого этапа запишите наблюдаемый признак успеха. Затем измените скорость монитора так, чтобы она не совпадала со скоростью в программе, опишите симптом и верните правильную настройку.

Задание 4. Конфигурация второго стенда​

Добавьте в учебную копию platformio.ini второе окружение для другой известной вам платы. Составьте список частей программы, которые могут потребовать адаптации. Не утверждайте переносимость, пока обе сборки и оба физических стенда не проверены.

Проверьте себя​

  1. Какие разные задачи выполняют VS Code и PlatformIO?
  2. Почему platformio.ini следует хранить вместе с исходным кодом?
  3. Чем Build отличается от Upload?
  4. Для чего предназначены папки src/, include/, lib/ и test/?
  5. Как lib_deps помогает перенести проект на другой компьютер?
  6. Почему успешная сборка для второй платы ещё не подтверждает работу робота?
  7. Какие две настройки нужно сравнить при нечитаемом выводе последовательного монитора?
Ориентиры для самопроверки

Сначала ответьте без подсказки. Ответ можно считать полным, если вы:

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

Если один из пунктов объяснить не получается, найдите соответствующую главу статьи, перечитайте её и повторите ответ.

Словарь статьи​

  • Редактор кода — программа для создания, навигации и изменения исходных файлов.
  • Расширение VS Code — устанавливаемое дополнение, которое добавляет редактору новые команды и представления.
  • PlatformIO Core — набор командных инструментов, выполняющих операции проекта PlatformIO.
  • Окружение — именованный набор параметров сборки в секции [env:имя].
  • Фреймворк — программная основа и API, на которых строится приложение микроконтроллера.
  • Сборка — преобразование и связывание исходных файлов в прошивку для выбранного окружения.
  • Зависимость — внешняя библиотека или пакет, необходимые проекту.
  • Serial Monitor — средство просмотра данных последовательного обмена с устройством.
  • Модуль — часть программы с одной ответственностью и определённым интерфейсом.

Связанные темы​

Источники​