Skip to content

Начало работы

Предварительные условия

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

Программное обеспечение для установки

Пожалуйста, установите следующее программное обеспечение, если оно у вас еще не установлено:

  • GIT - Для работы с исходным кодом
  • VSCode — IDE для разработки.
  • Node.js — для сборки интерфейса с помощью npm.

Плагины и настройка VSCode

Пожалуйста, установите следующие обязательные плагины для VSCode:

  • PlatformIO — платформа для разработки встраиваемых систем.
  • Prettier — автоматический форматировщик кода.
  • Svelte for VS Code — значительно облегчает работу со Svelte.
  • Svelte Intellisense — дополнительный инструмент для Svelte.
  • Tailwind CSS Intellisense — упрощает работу с Tailwind CSS.
  • Prettier plugin for Tailwind CSS — автоматически сортирует классы Tailwind в рекомендуемом порядке.

Наконец, если вы хотите использовать Materials for MkDocs в качестве движка документации, установите Material for MkDocs, введя следующую команду в терминале VSCode:

pip install mkdocs-material

[!TIP] Возможно, вам потребуется запустить это от имени администратора, если возникнет ошибка.

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

Ресурс Описание
.github/ Конвейер Github CI для развертывания MkDocs на gh-pages и сборки прошивки
docs/ Файлы документации MkDocs
interface/ Фронтенд на базе SvelteKit5
lib/framework/ C++ бэкенд для устройства ESP32
src/ Основной файл main.cpp
logs/ Каталог с логами Serial-monitor
scripts/ Скрипты, собирающие интерфейс в рамках сборки PlatformIO
platformio.ini Конфигурационный файл проекта PlatformIO
mkdocs.yaml Конфигурационный файл проекта MkDocs

Работа с Git и внесение вклада (Contributing)

Если вы хотите внести изменения в проект или адаптировать его под свои нужды, следуйте этому руководству по Git.

1. Создание форка (Fork)

Форк — это ваша личная копия репозитория, где вы можете свободно проводить эксперименты.

  1. Перейдите на страницу оригинального репозитория на GitHub.
  2. Нажмите кнопку Fork в верхнем правом углу.
  3. Выберите свой аккаунт. Теперь у вас есть копия проекта по адресу github.com/ваш_логин/название_репозитория.

2. Клонирование и настройка

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

# Клонирование вашего форка
git clone <https://github.com/ваш_логин/название_репозитория.git>
cd название_репозитория

# Добавление оригинала в качестве удаленного репозитория
git remote add upstream [https://github.com/оригинальный_автор/название_репозитория.git](https://github.com/оригинальный_автор/название_репозитория.git)

3. Работа с ветками (Branches)

Никогда не делайте изменения напрямую в ветке main. Всегда создавайте новую ветку для каждой задачи.

4. Создание и изменение Merge Request (MR)

После того как вы отправили (push) ветку в свой форк, GitHub предложит вам создать Merge Request.

Создание MR:

  • Зайдите в свой форк на GitHub.

  • Вы увидите желтую плашку "Compare & pull request". Нажмите её.

  • Опишите ваши изменения и нажмите Create pull request.

Изменение существующего MR:

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

# Создание новой ветки и переключение на неё
git checkout -b feature/название-вашей-задачи

# После внесения изменений в файлы:
git add .
git commit -m "Краткое описание изменений (например: добавлена поддержка SD-карты для STM32)"
git push origin feature/название-вашей-задачи
Ваш Merge Request на GitHub обновится автоматически.

5. Синхронизация с оригиналом

Чтобы ваш форк не отставал от основного проекта:

git checkout main
git pull upstream main
git push origin main

Учебное видео по работе по теме

Настройка PlatformIO

Настройка целевой сборки

[!DANGER] Не используйте интерфейс PlatformIO для редактирования platformio.ini Использование UI PlatformIO для добавления зависимостей или параметров удалит всю «нерелевантную» информацию, такую как комментарии, из файла. Пожалуйста, редактируйте файл напрямую в редакторе.

platformio.ini — это центральный файл, управляющий всем процессом сборки. Он поставляется с предварительно настроенными платами на базе различных чипов ESP32. Его необходимо адаптировать под плату, которую вы хотите прошить.

Процесс сборки и прошивки

Процесс сборки в данном проекте автоматизирован: PlatformIO не только компилирует C++ код, но и запускает скрипты для сборки фронтенда на SvelteKit.

1. Подготовка конфигурации

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

Откройте файл platformio.ini в корне проекта.

Найдите параметр default_envs и установите значение, соответствующее вашему контроллеру (например, esp32-s3).

Важно: Не используйте графический интерфейс PlatformIO для редактирования этого файла, так как это удалит комментарии.

2. Запуск сборки и прошивки

Для начала процесса используйте панель инструментов PlatformIO (иконка "муравей" или "микросхемы" в боковом меню VSCode):

Выбор окружения: В списке Project Tasks выберите вашу плату (например, env:esp32-s3).

Действие: Нажмите Upload and Monitor.

Build: - собирает прошивку из исходного кода

Upload: Скомпилирует код и загрузит его в контроллер.

Monitor: Автоматически откроет терминал для просмотра логов через Serial-порт.

**Upload and Monitor ** Скомпилирует код и загрузит его в контроллер и затем автоматически откроет терминал для просмотра логов через Serial-порт.

Важно

При первой сборке происходит скачивание зависимостей проект, что может занимать длительное время. Дождитесь его окончания

3. Автоматические этапы сборки

При запуске сборки PlatformIO выполнит следующие действия:

  • Установка библиотек: Скачает необходимые зависимости для ESP32.

  • Сборка фронтенда: Выполнит команду npm install и соберет файлы интерфейса из папки interface/.

  • Скрипты: Запустит Python-скрипты из папки scripts/ для упаковки интерфейса в прошивку.

Собранные бинарные данные хранятся в каталоге - build в подкаталогах согласно собираемой платформы

4. Решение проблем

  • Первая сборка: Может занять несколько минут и иногда завершается ошибкой, если Python-скриптам нужно установить дополнительные пакеты. В этом случае просто запустите Upload повторно.

  • Терминалы: Вы можете держать открытыми несколько терминалов: один для мониторинга прошивки, другой для сервера разработки фронтенда (npm run dev в папке interface).

Настройка SvelteKit

Настройка прокси для разработки

Чтобы упростить разработку внешнего интерфейса, вы можете развернуть код внутреннего интерфейса на плате ESP32 и передавать вызовы веб-сокета и REST API через прокси-сервер сервера разработки. В файле vite.config.ts указано расположение сервисов, которые будет проксировать сервер разработки. Это определяется свойством target, которое необходимо изменить на IP-адрес или имя хоста устройства, на котором установлена прошивка. Измените это для обоих вариантов: «http://» и «ws://».

proxy: {
    // Proxying REST: http://localhost:5173/rest/bar -> http://192.168.1.83/rest/bar
    '/rest': {
    target: 'http://192.168.1.83',
    changeOrigin: true,
    },
    // Proxying websockets ws://localhost:5173/ws -> ws://192.168.1.83/ws
    '/ws': {
    target: 'ws://192.168.1.83',
    changeOrigin: true,
    ws: true,
    },
},

Совет

Чтобы изменения в расположении прокси вступили в силу, необходимо перезапустить сервер разработки.

Сервер разработки

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

cd interface
npm run dev

Перейдите по ссылке, чтобы открыть интерфейс в браузере.