Přeskočit na hlavní obsah

Platforma EmBi

Modul EmBi_Platform poskytuje jednotný způsob inicializace, strukturování a správy projektů založených na STM32. Automatizuje vytváření projektu, nastavení adresářů a inicializaci BSP pro zvolenou rodinu MCU STM32.

Obsah​

Tento modul obsahuje:

  • Nástroje pro práci s artefakty – Nástroje pro správu a zpracování build artefaktů (např. stahování, verzování, ověřování).
  • Šablony projektů STM32CubeIDE – Připravené struktury projektů pro mikrokontroléry STM32.
  • Pomocné skripty CMake – Sada pomocných skriptů, které zjednodušují integraci s build systémy založenými na CMake.
  • Společné utility – Univerzální nástroje znovupoužitelné napříč moduly RAL (např. hashování, určování cest nebo parsování konfigurace).
  • Updater – Nástroj zajišťující potřebné aktualizace EmBi_Platform.

Integrace​

1. Přidejte EmBi_Platform jako Git submodul​

V kořenovém adresáři svého projektu spusťte:

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

Tip: Doporučuje se přidat submodul přímo pod kořen projektu, aby cesty zůstaly konzistentní se skripty CMake.

2. Spusťte instalační skript​

Windows​

Setup.bat

Linux / macOS​

./Setup.sh

Skript zobrazí menu s několika volbami. Chcete-li inicializovat nový projekt, zvolte možnost „Configuration“ zadáním jejího čísla. Zobrazí se několik podvoleb, které jsou popsány níže.

Volba: Initialize project necessary files​

Toto je nutné provést jednou při první inicializaci projektu.

Tato volba zkopíruje do projektu soubory spravované uživatelem.

CMakeLists.txt​

Kořenový soubor CMakeLists projektu. Uživatel zde může přidat kroky před buildem a po něm, zadat požadované build flagy a vlastní funkcionalitu.

ArtifactsConfig.txt​

Konfigurační soubor handleru artefaktů. Uživatel zde může zadat požadované artefakty, jejich verze a podverze pomocí syntaxe:

<artifact_name>;<binary_version>;<handler_version>

Příklad:

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

Volba: Initialize STM32CubeIDE project​

Tato volba zkopíruje soubory projektu STM32CubeIDE do repozitáře projektu (do složky STM32CubeIDE/ na nejvyšší úrovni — viz Struktura projektu, jak to souvisí s kopií šablony dodávanou v EmBi_Platform/STM32CubeIDE).

Volba: Configure application layer​

Toto je nutné provést jednou při první inicializaci projektu.

Vygeneruje se struktura složek aplikačního modulu a zkopírují se hlavičkový soubor hlavního vstupního bodu aplikace a soubory s funkcemi.

Volba: Configure BSP module​

Toto je nutné provést jednou při první inicializaci projektu nebo při změně rodiny MCU.

Skript vypíše všechny dostupné rodiny MCU STM32 podporované systémem BSP.

Příklad výstupu:

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

Zadejte číslo odpovídající požadované rodině MCU (např. 0 pro rodinu STM32G4). Položky s příponou _Dev sledují vývojovou větev dané rodiny; master sleduje nejnovější nevydané změny BSP napříč všemi rodinami a je určena spíše pro vývoj/testování platformy než pro produkční projekty.

Po zvolení rodiny MCU instalační skript automaticky:

  • Přidá všechny potřebné submoduly BSP
  • Provede checkout správných větví a commitů
  • Aktualizuje konfigurace CMake pro zvolenou rodinu MCU

Volba: Update documents module​

Tato volba obnoví lokální kopii obsahu modulu Docs používaného projektem (např. generovanou/referenční dokumentaci načtenou ze zdroje dokumentace platformy).

Volba: Configure Middleware module​

Spusťte jednou pro každou komponentu middlewaru, kterou chcete použít, a znovu pokaždé, když chcete tuto komponentu přepnout na jinou verzi.

Skript nejprve vypíše všechny dostupné komponenty middlewaru deklarované v katalogovém repozitáři Middlewares a po výběru jedné z nich vypíše všechny dostupné verze (Git tagy) repozitáře dané komponenty.

Příklad výstupu:

[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ýběru obou položek instalační skript:

  • Přidá komponentu jako Git submodul pod Middlewares/ThirdParty/<Name> s checkoutem zvolené verze.
  • Pouze poprvé vytvoří kostru projektové handler složky Middlewares/<Name> — sem patří váš vlastní glue/port kód a konfigurace komponenty; pozdější rekonfigurace ji nikdy nepřepíše.
  • Zapojí obě složky do Middlewares/Middlewares.cmake pomocí add_subdirectory() (složku ThirdParty/<Name> pouze pokud tato vendorovaná složka obsahuje vlastní CMakeLists.txt).

Pokud tuto volbu spustíte znovu pro již přidanou komponentu s jiným ID verze, checkout Middlewares/ThirdParty/<Name> této komponenty se přepne na nově zvolenou verzi, aniž by se dotkl vaší handler složky.

Volba: Update Middleware module​

Aktualizuje jednu, již přidanou komponentu middlewaru na její nejnovější dostupnou verzi — její nejnovější Git tag, nebo poslední commit výchozí větve, pokud zatím nemá žádné tagy. Nejprve se zobrazí stejný seznam middlewaru jako výše, abyste mohli vybrat, kterou komponentu aktualizovat.

Volba: Update EmBi_Platform​

Spustí nástroj Updater, který porovná aktuálně integrovanou verzi EmBi_Platform s nejnovějším dostupným vydáním a aplikuje aktualizaci, přičemž znovu provede konfigurační kroky, které se v důsledku toho změnily.

Použití​

Modul EmBi_Platform je určen k použití jako podpůrná vrstva v rámci frameworku Embedded Abstraction. Sám neobsahuje žádné komponenty související s hardwarem, ale poskytuje sdílenou funkcionalitu a vývojové nástroje, na kterých stavějí ostatní moduly závislé na hardwaru (Application, Bsp, Middlewares).

Typické použití zahrnuje:

  1. Práce s artefakty — skripty pro správu a ověřování stažených nebo cachovaných artefaktů používaných napříč build systémem.
  2. Integrace s CMake — pomocné skripty pro automatizované nastavení, validaci prostředí a registraci modulů.
  3. Podpora STM32CubeIDE — šablony projektů pro generování konfigurací kompatibilních s IDE a testovacích prostředí.

Poznámka: Modul EmBi_Platform není pro běh firmwaru na cílovém hardwaru potřeba, ale pro vývoj a workflow CI/CD se důrazně doporučuje.

Požadavky​

  • Git 1.7.10+
  • Bash (Linux/macOS) nebo přibalený Setup.bat (Windows)
  • CMake 3.19+
  • STM32CubeIDE 1.4.0+
  • Podporované hostitelské OS: Windows, Linux, macOS

Struktura 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 případě potřeby obsahovat externí open-source utility.
  • Všechny interní skripty jsou psány tak, aby byly pokud možno nezávislé na platformě.
  • Změny tohoto modulu by měly být pečlivě zkontrolovány, protože mohou ovlivnit více modulů napříč build systémem.

Licence​

Tato platforma se skládá z komponent ze dvou různých zdrojů, které jsou licencovány samostatně:

  • Komponenty třetích stran (např. balíčky pocházející od STMicroelectronics a dalších výrobců) si ponechávají své původní licence. Podrobnosti najdete ve složce/README jednotlivých komponent.
  • Komponenty vytvořené Embedbits (samotná EmBi_Platform, pomocné skripty CMake, nástroje pro práci s artefakty, Updater a další původní nástroje nepřipsané třetí straně) jsou licencovány pod PolyForm Noncommercial License 1.0.0: lze je volně používat, kopírovat, upravovat a distribuovat pro nekomerční účely. Komerční použití vyžaduje samostatnou písemnou licenci od Embedbits.

Vybraným společnostem může být udělena bezplatná licence k použití komponent vytvořených Embedbits pro komerční účely na základě samostatné písemné dohody. O její udělení požádejte na nobody@embedbits.com.

Autoři​

Příspěvky jsou vítány pro nekomerční vylepšení! Otevřete prosím pull request.