Introduction to STM32Cube Expansion Packages

On this page, learn how to create your own STM32Cube Expansion Package to challenge the limit of the ecosystem.

1. What is an STM32Cube Expansion Package?

STM32Cube Expansion Packages are embedded software packages that complement the STM32Cube MCU Packages with additional software bricks, including specific drivers for external companion chips or application-specific middleware. They offer developers simplified implementations of real-world use cases in many application areas, such as sensing, power management, connectivity, and audio. They also contain preconfigured project examples for ST boards and supported IDEs to get started easily.

2. Design of an STM32Cube Expansion Package enhanced for the STM32 Toolset

An STM32Cube Expansion enhanced for the STM32 Toolset is an evolution of the initial concept of STM32Cube Expansion. The new packages contain now a part readable and configurable into STM32CubeMX (or STM32CubeIDE) on top of ready-to-use project samples.

It helps the integration of software components into the STM32Cube ecosystem. The role is to limit the manual work to integrate a software component (it limits but it remains some manual operations to be executed by the end user). The major advantage of integrating your software in STM32CubeMX is that you can allow the STM32CubeMX users to integrate your software component on any board or MCU from the STM32 galaxy.

3. Three webinars to start up

Three webinars have been prepared by our teams to show you a part of the capacity of the STM32Cube Expansion Do It Yourselves. Each video lasts approximately 1 hour and needs between half a day to one day to reproduce it.

  • Sequencer sample :
An utility for multi-tasking without an operating system, which is a hardware-independent code.
In the example, a LED is managed through a GPIO.
pc videol.png
Sequencer video
pc videol.png
Sequencer video (Chinese)
Download the sequencer sample code
  • DSPDemo sample :
This software component uses the DSP integrated in the core to generate an internal signal. This internal signal is then captured and displayed thanks to CubeMonitor. There is no interaction with the external hardware.
pc videol.png
DSPDemo video
pc videol.png
DSPDemo video (Chinese)
Download the DSPDemo sample code
  • STDIO sample
The application code frequently uses standard I/O library functions, such as printf(),scanf(), or fgetc() to perform input/output operations.The I/O library functions can be redirected to use different channels (peripheral) depending on the hardware and the application needs. The most common channels used for STDIN (scanf, getchar) and STDOUT (printf) are UART and USB Device Virtual COM port class. STDIN can retrieve data from a USB keyboard using the USB Host HID class.
pc videol.png
STDIO video
pc videol.png
STDIO video (Chinese)
Download the STDIO sample code

4. Auto-assessment

Any software component is not adapted to the development of an STM32Cube Expansion enhanced for the STM32 Toolset. Indeed, the possibility of configurations is huge and not covered completely by the tools. Some other methods may be feasible but are not considered in the normal flow.

We refer to this list of questions to identify the right candidates. The questions must be taken in the generic understanding of the Industry.

  • Did I already use STM32CubeMX or STM32CubeIDE to generate a project?
- If yes, move to the next question
The concept is based on the usage of STM32CubeMX. We recommend starting only when you have already acted as a standard user of STM32CubeMX. If not, start downloading and opening STM32CubeMX, pick up an STM32 MCU, configure peripherals, generate the project for your preferred IDE and look at the result.
  • Is <My SW component> well structured?
- If yes, move to the next question
My software is structured in functional units/components self-content from an architecture point of view.
  • Does <My SW component> have a standard build system?
- If yes, move to the next question
We exclude cases such as complex cases with different linker scripts, generating more than one binary file, if your software needs to dynamically adapt the run-time configuration. STM32CubeMX generates simple project structure (refer to the basic or advanced structure).
  • Am I ready to adapt my architecture to STM32Cube rules when interacting STM32Cube components?
- If yes, move to the next question
STMicroelectronics has defined some rules to interact between STM32Cube components to guarantee coherency between software components. There is no impact on your own software component architecture but on the structure of the project (such as the location of your software component into the project itself, the location of the HAL drivers, the usage of STM32Cube API, and others). Indeed, the project structure must be as expected by STM32CubeMX. Using STM32PackCreator and STM32CubeMX prevents most of the problems(UM2739).
  • Am I ready to add this delivery method on the long run?
- If yes, move to the next question
We value working with partners and customers on the long run. The work related to the STM32Cube Expansion Package is valuable if you intend to upgrade it regularly with new versions of your software component. Therefore, the method could be done one time but needs to be thought on the long run.
  • <My SW component> is hardware agnostic
- Check the DSPDEMO STM32Cube Expansion sample training
Your software component has no relation with any hardware components (no peripherals of STM32Cube ecosystem offer). This video training and the associated I-Cube describe the creation of STM32Cube Expansion in a simple software component.
  • <My SW component> has some hardware relation with UART, I2C, SPI, GPIO
- Check the Sequencer STM32Cube Expansion sample training
This video training and the associated I-Cube describe the creation of STM32Cube Expansion in a simple software component with the usage of GPIO.
  • <My SW component> has some hardware relation with timers
- Take care: refer to STM32PackCreator limitation
Basic usage of timers is supported. Complex and advanced features are too complex to be implemented in our tools.
  • <My SW component> has some hardware relation with other peripherals than the ones mentioned above
- Be cautious - check the STDIO STM32Cube Expansion sample training.

5. Three steps to design your STM32Cube Expansion enhanced for the STM32 Toolset

The design of an STM32Cube Expansion enhanced for the STM32 Toolset is usually done in three steps. In real work, several iterations are needed between step1 and step2 until the right result.

5.1. Step1: Design a pack enhanced for STM32CubeMX using STM32PackCreator

First and foremost, start STM32PackCreator: Go to $YourLocation$\STMicroelectronics\STM32Cube\STM32CubeMX\utilities\STM32PackCreator

The methods to develop the step1 are explained through the video listed above or in the Getting started Pack Creator, accessible in the help menu of the STM32PackCreator.

Ensure that you have activated the PACKAGES STM32Cube RULES COMPLIANT in the STM32PackCreator.

Intermediate steps in this step1 may be:

  • Design a CMSIS Pack
  • Design a simple configurable Pack
  • Integrate a hardware dependency
  • Integrate an application

To train yourself on the method, we recommend to go first to those Video & Tutorials, and then to read STM32PackCreator user manual.

You have obtained a pack enhanced for STM32CubeMX. This pack can be loaded, configured in STM32CubeMX and can generate the associated code.

5.2. Step2: Develop a few examples

You are going now to develop two to three examples on one or several STM32 boards. Those examples must of course be generated by the STM32CubeMX tool, using your pack enhanced for STM32CubeMX.

This step has two interests:

  • Validate your implementation of the pack on different hardware and different configurations,
  • Prepare some project examples that you will integrate into the STM32Cube Expansion Package itself. Your customers may indeed start directly from the example, without using the STM32CubeMX tool.

To execute it, you will act as a user of your pack enhanced for STM32CubeMX and execute the following actions:

  • Load your pack “enhanced for STM32CubeMX” inside STM32CubeMX (refer to the STM32CubeMX user manual for more details).

We recommend the usage of STM32CubeMX. Indeed, even if STM32CubeIDE integrates the STM32CubeMX plugin, it will be not possible to generate the projects for the three IDEs (IAR Systems® EWARM, Keil® MDK-ARM, and STM32CubeIDE) from STM32CubeIDE. It will be limited to STM32CubeIDE only.

  • Configure the peripherals, the software components, the clock, the project settings to be adequate to your need.
  • Copy and paste the drivers (HAL) that you need inside the Drivers directory inside your Package
  • Generate a project (check the project settings below to take into account the drivers from your Package).
  • Add some user code in the user section to make it demonstrable.
  • Save the STM32CubeMX configuration file (ioc) for each project. We recommend saving the name of the project like Name_Of_Application#N. It will be reflected also on the ioc file, which will be called Name_Of_Application#N.ioc.

The project settings must be reflected like that

STM32CubeMX Panel: project generator settings2

and

File:ProjectSettings.png
STM32CubeMX Panel: project generator settings
  • Generate your projects for the three IDEs (IAR Systems® EWARM, Keil® MDK-ARM, and STM32CubeIDE) and test them.
Info white.png Information
In the special case of STM32CubeIDE, take care to unselect Generate Under Root before generating that to have a coherent structure for the three IDEs.
File:CubeIDE.png
STM32CubeMX Panel: STM32CubeIDE specific settings

5.3. Step3: Deliver an STM32Cube Expansion Package (I-CUBE)

This is the final step. It integrates the outputs of step1 and step2 together into a package called STM32Cube Expansion Package. These packages are published on STMicroelectronics website with X-CUBE part numbers if they are distributed, maintained and supported by STMicroelectronics. Some packages distributed, supported and maintained by ST authorized partners are also exposed on STMicroelectronics website with I-CUBE part numbers. The interests of this step are that you deliver a single deliverable to your customer. - This .pack deliverable contains all necessary files to import software components and configure them in STM32CubeMX or STM32CubeIDE tool, and generate a project for any STM32-based hardware. - The .pack is in ZIP format and can also be unzipped and users can get started with ready-to-use project examples, pre-configured to compile in the 3 IDEs (IAR Systems® EWARM, Keil® MDK-ARM, and STM32CubeIDE) and run out-of-the-box on specific ST boards.

First, some cleanup actions are required:

  • The line ProjectManager.FirmwarePackage=XXXX must be removed from the file .ioc included in the examples folder. Indeed, STM32CubeMX versions continue to evolve. To avoid version issues, remove this line.
  • The STM32Cube Expansion Package pdsc file must be checked with the PackChk.exe provided by Arm.
  • All non-user comments must be removed from the IPconfig and IPmodes files, when available

Then, some documents must be written

  • A user getting started document (such as chm, rtf, or pdf) located under Documentation folder at the root of the Package is also expected. the contents must be:
    • How to use your specific STM32Cube Expansion in STM32CubeMX
    • The goals and usage of project examples
    • Remaining manual operation on the charge of the end user if any.
  • A release note document must be also included, describing the content release and the corrected issues.
  • A doc/ folder, containing the file describing APIs and parameters of the middleware elements, must be located at the same level as the middleware Release_Notes.

Several examples of such documents can be found into Expansion Packages.

The documents must be referenced in the pdsc file using the following options (according to CMSIS-pack standard):

  • For component or API documentation, use: <file category="doc" ...>
  • For bundle documentation, use: <doc ...>

You can add some files and example projects in the additional files to the existing package thanks to the STM32PackCreator. You need to use Additional Files button.

Info white.png Information
The .pack format is a compressed format, and so can be opened with Winzip or equivalent tool.

You are done! You can now deliver it as is to your customers and partners.

If you want to go further and make it exposed in the STM32CubeMX tool, you can contact your ST local representative.

6. STM32Cube Expansion structure

The STM32Cube Expansion structure top level is the following:

File:Toplevelstructure.png
Top level structure
  • STM32CubeMX: generated by STM32PackCreator (available in STM32CubeMX panel Tools). It contains the files required by STM32CubeMX in order to configure the software component.
  • Middlewares: contains your software component itself. Under ST subdirectories when coming from ST, under “Third_Party” when coming from your side or from a community.
File:MWstructure.png
Example of X-Cube-NFC4 package - Middleware structure
  • Projects (examples): contains the examples of projects (2 or 3). They have been generated by STM32CubeMX for several IDEs and for several boards. Here is an example of advanced structure.
File:Advancedstructure.png
Example of X-Cube-NFC4 package - Advanced project structure
Info white.png Information
starting from STM32CubeMX-6.0.0, code generation is in "advanced mode" by default - you can change it on the project generator panel

Here is an example of basic structure.

File:ExampleBasicstructure.png
Example of X-Cube-BLE1 package - Basic project structure
  • Drivers: contains the drivers that are required for the projects (examples). Copy paste them from the CubeFW Package of the series that you have taken as examples.
File:Driversstructure.png
Example of NFC STM32Cube Expansion Package - Drivers structure
  • Utilities: contains any PC software useful for your pack.
  • Documentation: contains the getting started and or any other documentation related to the package except the release note.

Other documents at the root of the package:

  • License.pdf: contains the license. It is displayed during the installation process
  • Release_Notes.html: contains information on the release such as goals, modified files, corrected bugs and limitation if any.
  • VendorName.CubeExpansionName.pdsc: the file pdsc contains the description of the file included into the packages.

The STM32Cube Expansion structure follows the standard STM32CubePackage structure. This structure is fully described into the document UM2285 Development guidelines for STM32Cube Expansion Packages.

In conclusion, if you want to map the "step1", "step2" and "step3", it will be like that

File:ExpansionPackage Step1.png
Step1: package useable in STM32CubeMX
File:ExpansionPackage Step2.png
Step2: stand alone project examples

7. Going further

  • UM2739 STM32PackCreator user manual - Creating software packs and STM32Cube Expansion Packages enhanced for STM32CubeMX, rev1
  • UM2285 Development guidelines for STM32Cube Expansion Packages, rev2
  • UM2388 STM32Cube Firmware Packs Specification, rev1
  • UM2298 STM32Cube BSP drivers development guidelines, rev2
  • UM2312 Development checklist for STM32Cube Expansion Packages, rev3 (XLS Checklist XLS version of the Development checklist for STM32Cube Expansion Packages, rev4)

8. Frequently asked questions

  • There are some existing plugins for Eclipse® to manage CMSIS pack. Could I use them with STM32CubeIDE on top of STM32CubeMX plugin?
We do not test external Eclipse® plugin.

  • Could I use STM32CubeIDE to test and generate an STM32Cube Expansion Package?
As a partner developing an STM32Cube Expansion Package, we recommend using STM32CubeMX. Indeed, the STM32Cube Expansion Package must include some examples for the three IDEs and this is feasible with STM32CubeMX.

  • I have analyzed several ST STM32Cube Expansion (X-CUBE-BLE1, X-CUBE-MEMS) but they cannot be re-opened with STM32PackCreator. Have they been designed with STM32PackCreator?
The first X-CUBE have not been designed with STM32PackCreator. So, you may find some tricks that are not feasible with STM32PackCreator. STMicroelectronics supports only the STM32PackCreator feature set.

  • There is an "Example" keyword in the CMSIS pack standard. Could I use it to describe the 2 to 3 examples (step2)?
So far, this keyword is not used by STM32CubeMX.

  • There is some beautiful User Interface into STM32CubeMX (for some peripherals). Could I reproduce the same with STM32PackCreator?
STM32CubeMX allows some integration of java code to design complex user interface. This feature is not exposed to external plugins.

  • Once the STM32Cube Expansion Package is selected into STM32CubeMX additional software management panel, I would like that some settings from dependent peripherals are automatically selected. Is it possible?
This is not possible and not expected. Indeed, your software component can be used with different series and so, this is not expected to pre-fill the parameters. Our recommendation is to provide some examples with a defined configuration to your users and also a “getting started” document.

  • Could I modify the XML files generated by STM32PackCreator?
STMicroelectronics does not support this case.

  • Could I use the Pack ARM CMSIS?
The pack ARM CMSIS can be opened with STM32CubeMX but as some components are also coming from STM32Cube MCU Packages, you may face some incompatibilities. Take care about them.

  • What is the difference between an STM32Cube Expansion Package and a CMSIS Pack?
The STM32Cube Expansion Package enhanced for the STM32 Toolset is in general configurable. The generated code by STM32CubeMX when using STM32Cube Expansion Package has always a similar structure. It is based on STMicroelectronics HAL and LL drivers. It embeds some ready to use examples with .ioc file.

  • Where are my packages stored?
Look at %HOME%\STM32Cube\Repository\Packs.