Preskočiť na hlavný obsah

EmBi Platform

Modul EmBi_Platform poskytuje jednotný spôsob inicializácie, štruktúrovania a správy projektov založených na STM32. Automatizuje vytváranie projektov, nastavenie adresárov a inicializáciu BSP pre zvolenú rodinu MCU STM32.

Obsah​

Tento modul obsahuje:

  • Nástroje na prácu s artefaktmi – Nástroje na správu a spracovanie build artefaktov (napr. sťahovanie, verzovanie, overovanie).
  • Šablóny projektov STM32CubeIDE – Okamžite použiteľné štruktúry projektov pre mikrokontroléry STM32.
  • Pomocné skripty CMake – Zbierka pomocných skriptov, ktoré zjednodušujú integráciu s build systémami založenými na CMake.
  • Spoločné nástroje – Univerzálne nástroje opakovane použiteľné vo viacerých moduloch RAL (napr. hashovanie, určovanie ciest alebo parsovanie konfigurácie).
  • Updater – Nástroj zabezpečujúci potrebné aktualizácie EmBi_Platform.

Integrácia​

1. Pridajte EmBi_Platform ako Git submodul​

V koreňovom adresári vášho projektu spustite:

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

Tip: Odporúča sa pridať submodul priamo pod koreň projektu, aby boli cesty konzistentné so skriptami CMake.

2. Spustite inštalačný skript​

Windows​

Setup.bat

Linux / macOS​

./Setup.sh

Skript zobrazí menu s viacerými voľbami. Na inicializáciu nového projektu zvoľte možnosť „Configuration“ zadaním jej čísla. Zobrazí sa niekoľko podvolieb, ktoré sú popísané nižšie.

Voľba: Initialize project necessary files​

Toto sa musí vykonať raz pri prvej inicializácii projektu.

Táto voľba skopíruje do projektu súbory spravované používateľom.

CMakeLists.txt​

Koreňový súbor CMakeLists projektu. Používateľ do neho môže pridať kroky pred buildom a po builde, zadať požadované build príznaky a vlastnú funkcionalitu.

ArtifactsConfig.txt​

Konfiguračný súbor handlera artefaktov. Používateľ v ňom môže zadať požadované artefakty, ich verzie a podverzie pomocou syntaxe:

<artifact_name>;<binary_version>;<handler_version>

Príklad:

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

Voľba: Initialize STM32CubeIDE project​

Táto voľba skopíruje súbory projektu STM32CubeIDE do repozitára projektu (do priečinka STM32CubeIDE/ na najvyššej úrovni — vzťah k šablóne dodávanej v EmBi_Platform/STM32CubeIDE nájdete v časti Štruktúra projektu).

Voľba: Configure application layer​

Toto sa musí vykonať raz pri prvej inicializácii projektu.

Vygeneruje sa adresárová štruktúra aplikačného modulu a skopírujú sa hlavičkový súbor a súbory funkcií hlavného vstupného bodu aplikácie.

Voľba: Configure BSP module​

Toto sa musí vykonať raz pri prvej inicializácii projektu alebo pri zmene rodiny MCU.

Skript vypíše všetky dostupné rodiny MCU STM32 podporované systémom BSP.

Príklad výstupu:

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

Zadajte číslo zodpovedajúce požadovanej rodine MCU (napr. 0 pre rodinu STM32G4). Položky s príponou _Dev sledujú vývojovú vetvu danej rodiny; master sleduje najnovšie nevydané zmeny BSP naprieč všetkými rodinami a je určená na vývoj/testovanie platformy, nie na produkčné projekty.

Po výbere rodiny MCU inštalačný skript automaticky:

  • Pridá všetky potrebné submoduly BSP
  • Vykoná checkout správnych vetiev a commitov
  • Aktualizuje konfigurácie CMake pre zvolenú rodinu MCU

Voľba: Update documents module​

Táto voľba obnoví lokálnu kópiu obsahu modulu Docs používaného projektom (napr. generovanú/referenčnú dokumentáciu stiahnutú zo zdroja dokumentácie platformy).

Voľba: Configure Middleware module​

Spustite to raz pre každý middleware komponent, ktorý chcete použiť, a znova vždy, keď chcete daný komponent prepnúť na inú verziu.

Skript najprv vypíše všetky dostupné middleware komponenty deklarované v katalógovom repozitári Middlewares a po výbere jedného z nich vypíše všetky dostupné verzie (Git značky) repozitára daného komponentu.

Example output:

[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):

Po výbere oboch inštalačný skript:

  • Pridá komponent ako Git submodul do Middlewares/ThirdParty/<Name> s checkoutom zvolenej verzie.
  • Iba pri prvom spustení vytvorí kostru priečinka handlera na strane projektu Middlewares/<Name> — sem patrí váš vlastný glue/port kód a konfigurácia komponentu; neskoršia rekonfigurácia ho nikdy neprepíše.
  • Zapojí oba priečinky do Middlewares/Middlewares.cmake cez add_subdirectory() (priečinok ThirdParty/<Name> iba vtedy, ak tento vendorovaný priečinok obsahuje vlastný CMakeLists.txt).

Opätovné spustenie tejto voľby pre už pridaný komponent s iným ID verzie prepne checkout Middlewares/ThirdParty/<Name> daného komponentu na novo zvolenú verziu bez zásahu do vášho priečinka handlera.

Voľba: Update Middleware module​

Aktualizuje jeden, už pridaný middleware komponent na jeho najnovšiu dostupnú verziu — jeho najnovšiu Git značku, alebo najnovší commit predvolenej vetvy, ak ešte nemá žiadne značky. Najprv sa zobrazí rovnaký zoznam middlewarov ako vyššie, aby ste si mohli vybrať, ktorý komponent aktualizovať.

Voľba: Update EmBi_Platform​

Spustí nástroj Updater, ktorý porovná aktuálne integrovanú verziu EmBi_Platform s najnovším dostupným vydaním a aplikuje aktualizáciu, pričom znova spustí všetky konfiguračné kroky, ktoré sa v dôsledku toho zmenili.

Použitie​

Modul EmBi_Platform je určený na použitie ako podporná vrstva v rámci frameworku Embedded Abstraction. Sám neobsahuje žiadne komponenty súvisiace so hardvérom, ale poskytuje spoločnú funkcionalitu a vývojové nástroje, na ktorých stavajú ostatné moduly viazané na hardvér (Application, Bsp, Middlewares).

Typické použitie zahŕňa:

  1. Prácu s artefaktmi — skripty na správu a overovanie stiahnutých alebo cachovaných artefaktov používaných v celom build systéme.
  2. Integráciu s CMake — pomocné skripty na automatizované nastavenie, validáciu prostredia a registráciu modulov.
  3. Podporu STM32CubeIDE — šablóny projektov na generovanie konfigurácií kompatibilných s IDE a testovacích prostredí.

Poznámka: Modul EmBi_Platform nie je potrebný na spustenie firmvéru na cieľovom hardvéri, ale dôrazne sa odporúča pre vývoj a workflow CI/CD.

Požiadavky​

  • Git 1.7.10+
  • Bash (Linux/macOS) alebo priložený Setup.bat (Windows)
  • CMake 3.19+
  • STM32CubeIDE 1.4.0+
  • Podporované hostiteľské OS: Windows, Linux, macOS

Štruktúra projektu​

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

Poznámky​

  • Modul EmBi_Platform môže v prípade potreby obsahovať externé open-source nástroje.
  • Všetky interné skripty sú písané tak, aby boli, kedykoľvek je to možné, nezávislé od platformy.
  • Úpravy tohto modulu by sa mali starostlivo posúdiť, pretože môžu ovplyvniť viacero modulov v celom build systéme.

Licencia​

Táto platforma pozostáva z komponentov z dvoch rôznych zdrojov, ktoré majú samostatné licencie:

  • Komponenty tretích strán (napr. balíky pochádzajúce od STMicroelectronics a ďalších výrobcov) si ponechávajú svoje pôvodné licencie. Podrobnosti nájdete v priečinku/README príslušného komponentu.
  • Komponenty vytvorené Embedbits (samotný EmBi_Platform, pomocné skripty CMake, nástroje na prácu s artefaktmi, Updater a ďalšie pôvodné nástroje, ktoré nie sú pripísané tretej strane) sú licencované pod PolyForm Noncommercial License 1.0.0: možno ich voľne používať, kopírovať, upravovať a distribuovať na nekomerčné účely. Komerčné použitie vyžaduje samostatnú písomnú licenciu od Embedbits.

Vybraným firmám môže byť udelená bezplatná licencia na komerčné použitie komponentov vytvorených Embedbits na základe samostatnej písomnej zmluvy. Požiadať o ňu môžete na nobody@embedbits.com.

Autori​

Príspevky sú vítané pre nekomerčné vylepšenia! Otvorte prosím pull request.