Перейти до основного вмісту

EmBi Platform

Модуль EmBi_Platform надає єдиний спосіб ініціалізації, структурування та керування проєктами на базі STM32. Він автоматизує створення проєкту, налаштування тек та ініціалізацію BSP для вибраної родини мікроконтролерів STM32.

Вміст​

Цей модуль містить:

  • Утиліти для роботи з артефактами – інструменти для керування артефактами збірки та їх обробки (наприклад, завантаження, версіонування, перевірка).
  • Шаблони проєктів STM32CubeIDE – готові до використання структури проєктів для мікроконтролерів STM32.
  • Допоміжні скрипти CMake – набір допоміжних скриптів, що спрощують інтеграцію із системами збірки на базі CMake.
  • Спільні утиліти – інструменти загального призначення, які можна повторно використовувати в модулях RAL (наприклад, хешування, розв'язання шляхів або розбір конфігурації).
  • Updater – інструмент, що виконує необхідні оновлення EmBi_Platform.

Інтеграція​

1. Додайте EmBi_Platform як Git submodule​

У кореневій теці вашого проєкту виконайте:

git submodule add <URL to EmBi_Platform GIT repository> ./EmBi_Platform

Порада: Рекомендується додавати submodule безпосередньо в корінь проєкту, щоб шляхи залишалися узгодженими зі скриптами CMake.

2. Запустіть скрипт налаштування​

Windows​

Setup.bat

Linux / macOS​

./Setup.sh

Скрипт відобразить меню з кількома опціями. Щоб ініціалізувати новий проєкт, виберіть опцію "Configuration", ввівши відповідний їй номер. Буде показано кілька підопцій, описаних нижче.

Опція: Initialize project necessary files​

Це потрібно виконати один раз під час першої ініціалізації проєкту.

Ця опція скопіює у проєкт файли, якими керує користувач.

CMakeLists.txt​

Кореневий файл CMakeLists проєкту. Користувач може додавати кроки до та після збірки, вказувати необхідні прапорці збірки та власну функціональність.

ArtifactsConfig.txt​

Конфігураційний файл handler артефактів. Користувач може вказати потрібні артефакти, їхні версії та підверсії, використовуючи синтаксис:

<artifact_name>;<binary_version>;<handler_version>

Приклад:

ninja;1.12.1;1
gcc-arm-none-eabi;13.2.rel1;2

Опція: Initialize STM32CubeIDE project​

Ця опція скопіює файли проєкту STM32CubeIDE у репозиторій проєкту (тека верхнього рівня STM32CubeIDE/ — див. Структуру проєкту, щоб дізнатися, як вона пов'язана з копією шаблону, що постачається в EmBi_Platform/STM32CubeIDE).

Опція: Configure application layer​

Це потрібно виконати один раз під час першої ініціалізації проєкту.

Буде згенеровано структуру тек модуля застосунку, а також скопійовано заголовок головної точки входу застосунку та файли функцій.

Опція: Configure BSP module​

Це потрібно виконати один раз під час першої ініціалізації проєкту або під час зміни родини MCU.

Скрипт виведе список усіх доступних родин MCU STM32, які підтримує система BSP.

Приклад виводу:

Available BSP Families:
[0]: STM32G4
[1]: STM32G4_Dev
[2]: STM32H5
[3]: STM32H5_Dev
[4]: STM32U5
[5]: master
Enter branch ID (numerical):

Введіть відповідний номер потрібної родини MCU (наприклад, 0 для родини STM32G4). Записи із суфіксом _Dev відстежують гілку розробки родини; master відстежує найновіші нерелізні зміни BSP для всіх родин і призначена для розробки/тестування платформи, а не для виробничих проєктів.

Після вибору родини MCU скрипт налаштування автоматично:

  • Додає всі потрібні submodules BSP
  • Виконує checkout правильних гілок і комітів
  • Оновлює конфігурації CMake для вибраної родини MCU

Опція: Update documents module​

Ця опція оновлює локальну копію вмісту модуля Docs, що використовується проєктом (наприклад, згенерованої/довідкової документації, підтягнутої з джерела документації платформи).

Опція: Configure Middleware module​

Виконуйте це один раз для кожного компонента middleware, який хочете використовувати, і повторно щоразу, коли хочете перемкнути цей компонент на іншу версію.

Спочатку скрипт виводить список усіх доступних компонентів middleware, оголошених у репозиторії каталогу Middlewares, а після вибору одного з них — список усіх доступних версій (теги Git) у власному репозиторії цього компонента.

Приклад виводу:

[0]: Return back
[1]: FreeRTOS
[2]: u8g2
Enter middleware ID (numerical):
Available versions for 'FreeRTOS':
[0]: Latest (V10.4.3)
[1]: V10.3.1
[2]: V10.4.3
Enter version ID (numerical, 0 = Latest):

Після вибору обох скрипт налаштування:

  • Додає компонент як Git submodule у Middlewares/ThirdParty/<Name> з checkout на вибрану версію.
  • Лише вперше створює каркас теки handler на боці проєкту Middlewares/<Name> — саме сюди потрапляє ваш власний glue/port-код і конфігурація компонента; його ніколи не буде перезаписано під час подальшої повторної конфігурації.
  • Підключає обидві теки до Middlewares/Middlewares.cmake через add_subdirectory() (теку ThirdParty/<Name> — лише якщо ця вендорна тека має власний CMakeLists.txt).

Повторний запуск цієї опції для вже доданого компонента з іншим ідентифікатором версії перемикає checkout Middlewares/ThirdParty/<Name> цього компонента на нову вибрану версію, не зачіпаючи вашу теку handler.

Опція: Update Middleware module​

Оновлює один, уже доданий компонент middleware до його останньої доступної версії — його найновішого тега Git або останнього коміту гілки за замовчуванням, якщо тегів ще немає. Спочатку показується той самий список middleware, що й вище, щоб ви могли вибрати, який компонент оновити.

Опція: Update EmBi_Platform​

Запускає інструмент Updater, щоб порівняти поточну інтегровану версію EmBi_Platform з найновішим доступним релізом, і застосовує оновлення, повторно виконуючи всі кроки конфігурації, які внаслідок цього змінилися.

Використання​

Модуль EmBi_Platform призначений для використання як допоміжний рівень у межах фреймворку Embedded Abstraction. Він сам не містить жодних компонентів, пов'язаних з апаратурою, але надає спільну функціональність та засоби розробки, на яких ґрунтуються інші, апаратно-залежні модулі (Application, Bsp, Middlewares).

Типове використання включає:

  1. Робота з артефактами — скрипти для керування та перевірки завантажених або кешованих артефактів, що використовуються в системі збірки.
  2. Інтеграція з CMake — допоміжні скрипти для автоматизованого налаштування, перевірки середовища та реєстрації модулів.
  3. Підтримка STM32CubeIDE — шаблони проєктів для генерації сумісних з IDE конфігурацій і тестових середовищ.

Примітка: Модуль EmBi_Platform не потрібен для виконання firmware на цільовій апаратурі, але його настійно рекомендовано для розробки та процесів CI/CD.

Вимоги​

  • Git 1.7.10+
  • Bash (Linux/macOS) або вбудований Setup.bat (Windows)
  • CMake 3.19+
  • STM32CubeIDE 1.4.0+
  • Підтримувані хост-ОС: Windows, Linux, macOS

Структура проєкту​

Project_root/
│
├── Application                   Application module
│   ├── AppCom                    Application communication interface
│   ├── AppComp                   Application components
│   ├── AppCore                   Application core handler
│   ├── AppFun                    Application functionality
│   └── AppMain                   Application main function
│
├── Bsp                           Board Support Packages
│   ├── Hal                       Hardware Abstraction Layer
│   ├── Linker                    Linker generator module
│   ├── Mcal                      Micro-Controller Abstraction Layer
│   ├── Ral                       Register Abstraction Layer
│   └── Startup                   Startup handler
│
├── Middlewares                   Middlewares module
│   ├── ThirdParty                Vendored middleware sources (added per-component as Git submodules)
│   │   ├── FreeRTOS              FreeRTOS sources, checked out at the selected version
│   │   ├── u8g2                  u8g2 sources, checked out at the selected version
│   │   └── ...
│   ├── FreeRTOS                  Project-side FreeRTOS handler (port layer, configuration)
│   ├── u8g2                      Project-side u8g2 handler (port layer, configuration)
│   ├── ...
│   └── Middlewares.cmake         Middlewares root CMake file
│
├── EmBi_Platform                 Platform root folder (this module, added as a submodule)
│   ├── CMake                     CMake build functionality
│   │   ├── ArtifactsManager      Artifacts handling module
│   │   │   ├── Artifacts.cmake   Artifacts core CMake file
│   │   │   └── README.md         Artifacts module documentation
│   │   │
│   │   ├── HelperTools           Reusable CMake helper scripts (hashing, path resolution, config parsing, etc.)
│   │   ├── Build.cmake           CMake core build script
│   │   ├── Flags.cmake           Build flags list
│   │   ├── Platform.c            Top level .c file
│   │   ├── Platform.h            Top level .h file
│   │   └── README.md             CMake component documentation
│   │
│   ├── STM32CubeIDE              STM32CubeIDE project *template* (source copied into the root STM32CubeIDE folder below)
│   └── README.md                 Template documentation
│
├── STM32CubeIDE                  Generated STM32CubeIDE project folder (created from the template above)
│   ├── .cproject                 STM32CubeIDE C project file
│   ├── .project                  STM32CubeIDE project file
│   ├── Debug                     Build output folder
│   └── ...
│
├── ArtifactsConfig.txt           Artifacts configuration file
├── CMakeLists.txt                Project root CMake file
└── README.md                     Project documentation

Примітки​

  • Модуль EmBi_Platform може за потреби включати зовнішні утиліти з відкритим кодом.
  • Усі внутрішні скрипти написано так, щоб за можливості бути незалежними від платформи.
  • Зміни в цьому модулі слід ретельно перевіряти, оскільки вони можуть вплинути на кілька модулів у системі збірки.

Ліцензія​

Ця платформа складається з компонентів із двох різних джерел, ліцензованих окремо:

  • Сторонні компоненти (наприклад, пакети від STMicroelectronics та інших вендорів) зберігають свої оригінальні ліцензії. Докладніше дивіться в теці/README кожного компонента.
  • Компоненти авторства Embedbits (сама EmBi_Platform, допоміжні скрипти CMake, утиліти для роботи з артефактами, Updater та інші оригінальні інструменти, не приписані третій стороні) ліцензуються за PolyForm Noncommercial License 1.0.0: їх можна вільно використовувати, копіювати, змінювати та поширювати у некомерційних цілях. Комерційне використання потребує окремої письмової ліцензії від Embedbits.

Окремим компаніям може бути надано безкоштовну ліцензію на використання компонентів авторства Embedbits у комерційних цілях за окремою письмовою угодою. Щоб її запросити, зверніться на nobody@embedbits.com.

Автори​

Запрошуємо до внеску у вигляді некомерційних покращень! Будь ласка, відкрийте pull request.