STMicroelectronics STM32U0 Series Original Initiative Improve Designer Productivity User Manual

STMicroelectronics STM32U0 Series Original Initiative Improve Designer

Productivity

Specifications

• Product Name: STM32CubeU0
• Compatibility: STM32U0 series microcontrollers
• Features: RTOS, USB Device Stacks, File System, Flash Memory Translation Layer, Middleware Components
• Licensing: Open-source BSD license

Product Usage Instructions

Overview of STM32CubeU0

The STM32CubeU0 is a comprehensive package that includes embedded software components for developing applications on STM32U0 series microcontrollers. It is highly portable and compatible with other STM32 series.

Main Features

The package includes low-layer (LL) and hardware abstraction layer (HAL) APIs covering microcontroller hardware, along with an extensive set of examples. It also features an integrated RTOS, USB Device stacks, file system support, and various libraries.

Architecture Overview

The architecture is built around three levels – Level 0 (HAL and basic peripheral examples), Level 1 (Applications and Libraries), and Level 2 (Evaluation boards and Demonstrations).

Hardware Abstraction Layer (HAL)

• BSP Drivers: Provide APIs for hardware components on boards like LCD, joystick, etc.
• Low-layer (LL): Offers basic peripheral usage examples and HAL core drivers.

Board Support Package (BSP)

This layer includes drivers for external devices on the board and provides APIs for BSP driver external components which can be portable across different boards.

Introduction

STM32Cube is an STMicroelectronics original initiative to improve designer productivity significantly by reducing development effort, time, and cost. STM32Cube covers the whole STM32 portfolio.
STM32Cube includes

• A set of user-friendly software development tools to cover project development from conception to realization, among which are:
• STM32CubeMX, a graphical software configuration tool that allows the automatic generation of C initialization code using graphical wizards
• STM32CubeIDE, an all-in-one development tool with peripheral configuration, code generation, code compilation, and debug features
• STM32CubeCLT, an all-in-one command-line development toolset with code compilation, board programming, and debug features
• STM32CubeProgrammer (STM32CubeProg), a programming tool available in graphical and command-line versions
• STM32CubeMonitor (STM32CubeMonitor, STM32CubeMonPwr, STM32CubeMonRF, STM32CubeMonUCPD), powerful monitoring tools to fine-tune the behaviour and performance of STM32 applications in real time
• STM32Cube MCU and MPU Packages, comprehensive embedded-software platforms specific to each microcontroller and microprocessor series (such as STM32CubeU0 for the STM32U0 series), which include:
• STM32Cube hardware abstraction layer (HAL), ensuring maximized portability across the STM32 portfolio
• STM32Cube low-layer APIs, ensure the best performance and footprints with a high degree of user control over hardware
• A consistent set of middleware components such as ThreadX, FileX / LevelX, USBX, touch library, embed-crypto, MCUboot, and OpenBL
• All embedded software utilities with full sets of peripheral and applicative examples
• STM32Cube Expansion Packages, which contain embedded software components that complement the functionalities of the STM32Cube MCU and MPU Packages with:
• Middleware extensions and applicative layers
• Examples running on some specific STMicroelectronics development boards

This user manual describes how to get started with the STM32CubeU0 MCU Package.
Section 2 describes the main features of the STM32CubeU0 MCU Package.
Section 3 and Section 4 provide an overview of the STM32CubeU0 architecture and MCU Package structure.

General information

Note

• The STM32CubeU0 application runs on the STM32U0 series 32-bit microcontrollers based on the Arm® Cortex®‑M processor.
• Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.

STM32CubeU0 main features

STM32CubeU0 gathers, in a single package, all the generic embedded software components required to develop an application for the STM32U0 series microcontrollers. In line with the STM32Cube initiative, this set of components is highly portable, not only within the STM32U0 series microcontrollers but also to other STM32 series.
STM32CubeU0 is fully compatible with the STM32CubeMX code generator for generating initialization code. The package includes low-layer (LL) and hardware abstraction layer (HAL) APIs that cover the microcontroller hardware, together with an extensive set of examples running on STMicroelectronics boards. The HAL and LL APIs are available in open-source BSD license for user convenience.
The STM32CubeU0 MCU Package also contains a comprehensive middleware component constructed around Microsoft® Azure® RTOS middleware and other in-house and open-source stacks, with the corresponding examples.
They come with free user-friendly license terms:

• Integrated and full-featured RTOS: ThreadX
• CMSIS-RTOS implementation with FreeRTOS™ open-source solution
• CMSIS-RTOS implementation with ThreadX
• USB Device stacks come with many classes: USBX
• Advanced file system and flash memory translation layer: FileX/LevelX
• OpenBootloader (OpenBL)
• MCUboot
• mbed-crypto libraries
• STM32_Touch library

Several applications and demonstrations implementing all these middleware components are also provided in the STM32CubeU0 MCU Package.
Figure 1 illustrates the STM32CubeU0 MCU Package component layout.

STM32CubeU0 architecture overview

• The STM32CubeU0 MCU Package solution is built around three independent levels that easily interact, as described in Figure 2.

Level 0
This level is divided into three sublayers:

• Board support package (BSP)
• Hardware abstraction layer (HAL)
• HAL peripheral drivers
• Low-layer drivers
• Basic peripheral usage examples

Board support package (BSP)
This layer offers a set of APIs relative to the hardware components in the hardware boards (such as LCD, joystick, and temperature sensor). It is composed of two parts:

• Component
• This is the driver relative to the external device on the board and not the STM32 device. The component driver provides specific APIs to the BSP driver’s external components and cab be portable onto any other board.
• BSP driver
• It allows linking the component drivers to a specific board and provides a set of user-friendly APIs. The API naming rule is BSP_FUNCT_Action().
• Example: BSP_LED_Init(), BSP_LED_On()

The BSP is based on a modular architecture allowing for easy porting on any type of hardware by implementing low-level routines.

Hardware abstraction layer (HAL) and low-layer (LL)
The STM32CubeU0 HAL and LL are complementary and cover a wide range of application requirements:

• The HAL drivers offer high-level function-oriented highly portable APIs. They hide the MCU and peripheral complexity from the end user.
• The HAL drivers provide generic multi-instance feature-oriented APIs that simplify user application implementation by providing ready-to-use processes. For example, for the communication peripherals (I2S, UART, and others), it provides APIs allowing the initialization and configuration of the peripheral, managing data transfer based on polling, interrupt, or DMA process, and handling communication errors that may arise during communication. The HAL driver APIs are split in two categories:
• Generic APIs that provide common and generic functions to all STM32 series.
• Extension APIs that provide specific and customized functions for a specific family or a specific part number.
• The low-layer APIs provide low-level APIs at register level, with better optimization but less portability. They require a deep knowledge of the MCU and peripheral specifications.
• The LL drivers are designed to offer a fast light-weight expert-oriented layer that is closer to the hardware than the HAL. Contrary to the HAL, LL APIs are not provided for peripherals where optimized access is not a key feature, or for those requiring heavy software configuration and/or a complex upper-level stack. The LL drivers feature:
• A set of functions to initialize peripheral main features according to the parameters specified in data structures.
• A set of functions used to fill initialization data structures with the reset values corresponding to each field.
• A function for peripheral de-initialization (peripheral registers restored to their default values).
• A set of inline functions for direct and atomic register access.
• Full independence from the HAL and capability to be used in standalone mode (without HAL drivers).
• Full coverage of the supported peripheral features.

Basic peripheral usage examples
This layer encloses the examples built over the STM32 peripherals using only the HAL and BSP resources.
Level 1
This level is divided into two sublayers:

• Middleware components
• Examples based on the middleware components

Middleware components
The middleware is a set of libraries constructed around Microsoft® Azure® RTOS middleware and other in-house (such as OpenBL) and open-source (such as mbed- crypto) libraries. All are integrated and customized for STM32 MCU devices and enriched with corresponding application examples based on promotional boards. Horizontal interactions between the components of this layer are done by calling the feature APIs while the vertical interaction with the low-layer drivers is done through specific callbacks and static macros implemented in the library system call interface.

The main features of each middleware component are as follows:

• ThreadX:
  A real-time operating system (RTOS), designed for embedded systems, with two functional modes:

  • Common mode: common RTOS functionalities, such as thread management and synchronization, memory pool management, messaging, and event handling.
  • Module mode: an advanced usage mode that allows the on-the-fly loading and unloading of prelinked ThreadX modules through a module manager.

• FileX / LevelX:

  • Advanced flash file system (FS) / flash translation layer (FTL): fully featured to support NAND/NOR flash memories.

• USBX:

  • USB Device stacks coming with many classes (USB Type-C®).

• OpenBootloader:
  This middleware component provides an open-source bootloader with exactly the same features and tools as the STM32 system bootloader.

• STM32 Touch Sensing Library:
  A software library used to support touch sensors with the Touch Sensing Controller peripheral (TSC).

• MCUboot.

• mbed-crypto:
  An open-source cryptography library that supports a wide range of cryptographic operations, including:

  • Key management.
  • Hashing.
  • Symmetric cryptography.
  • Asymmetric cryptography.
  • Message authentication (MAC).
  • Key generation and derivation.
  • Authenticated encryption with associated data (AEAD).

Examples based on the middleware components
Each middleware component comes with one or more examples (also called applications) showing how to use it. Integration examples that use several middleware components are provided as well.
Level 2
This level is composed of a single layer that consists of a global real-time and graphical demonstration based on the middleware service layer, the low- level abstraction layer, and the basic peripheral usage applications for board-based features.

Supported STM32CubeU0 series devices and hardware

• STM32Cube offers a highly portable hardware abstraction layer (HAL) built around a generic architecture. It allows the build-upon-layers principle, such as using the middleware layer to implement their functions without knowing what MCU is used. This improves the reusability of the library code and ensures easy portability to other devices.
• In addition, owing to its layered architecture, STM32CubeU0 offers full support of all STM32U0 series devices.
• The user only has to define the right macro in stm32u0xx.h.
• Table 1 shows which macro to define, depending on the STM32U0 series device used. This macro must also be defined in the compiler preprocessor.

Table 1. Macros for STM32CubeU0

STM32CubeU0 features a rich set of examples and applications at all levels, making it easy to understand and use any HAL driver and/or middleware components. These examples run on the STMicroelectronics boards listed in Table 2.
Table 2. Boards for STM32CubeU0 series

The STM32CubeU0 MCU Package can run on all compatible hardware. The user updates the BSP drivers to port the provided examples onto their own board if the latter has the same hardware features (such as LED, LCD, and buttons).

MCU Package Overview

The STM32CubeU0 MCU Package solution is provided in one single zip package, with the structure shown in Figure 3.

Figure 3. STM32CubeU0 MCU Package structure

For each board, a set of examples is provided with preconfigured projects for EWARM, MDK-ARM, and STM32CubeIDE toolchains.
Figure 4 shows the project structure for the STM32U0xx_Nucleo board.

The examples are classified according to the STM32Cube level they apply to, and are named as explained below:

• Level 0 examples are called “Examples”, “Examples_LL”, and “Examples_MIX”. They use, respectively, HAL drivers, LL drivers, and a mix of HAL and LL drivers without any middleware components.
• Level 1 examples are called applications. They provide typical use cases of each middleware component.

Any firmware application for a given board can be built quickly using the template projects available in the Templates and Templates_LL directories.
All examples have the same structure:

• A \Inc folder, containing all header files.
• A \Src folder for the source code.
• \EWARM, \MDK-ARM, and \STM32CubeIDE folders, containing the pre-configured project for each toolchain.
• A readme.txt file describing the example behavior and environment requirements to make it work.
• An *.ioc file, allowing users to open most of the firmware examples within STM32CubeMX (starting from STM32CubeMX 6.11).

Table 3. Number of examples for each board

Level| NUCLEO-U031R8| NUCLEO-U083RC| STM32U083C-DK| Total
---|---|---|---|---
Applications| 2| 8| 9| 19
Demonstration| 0| 0| 1| 1
Examples| 28| 104| 30| 162
Examples_LL| 3| 78| 1| 82
Examples_MIX| 0| 14| 0| 14
Templates| 1| 1| 1| 3
Templates_LL| 1| 1| 1| 3
Total projects| 35| 206| 43| 284

As shown in Table 3 above, the STM32CubeU0 package contains 284 examples dispatched on 3 boards, 193 of which are unique examples.

Getting started with STM32CubeU0

Running a first example
This section explains how to run a first example on a STM32U0 series board, toggling an LED on the NUCLEO-U083RC board.

Note

1. Download the STM32CubeU0 MCU Package and unzip it into a separate directory without modifying the package structure as shown in Figure 3. copy the package as close as possible to the root volume (for example C:\Eval or G:\Tests) because some IDEs can encounter problems when the path length is too long.
2. Browse to \Projects\NUCLEO-U083RC\Examples.
3. Open \GPIO, then the \GPIO_EXTI folders.
4. Open the project with a preferred toolchain. A quick overview on how to open, build, and run an example with the supported toolchains is given below.
5. Rebuild all files and load the image into the target memory.
6. Run the example: each time the USER pushbutton is pressed, the LED1 toggles (for more details, refer to the example readme file).

To open, build and run an example with the supported toolchains, follow the steps below.

EWARM

• Open the \EWARM subfolder in the example folder.
• Launch the Project.eww workspace.
• The workspace name may differ from one example to another.

Note

• Rebuild all files: [Project]>[Rebuild all].
• Load project image: [Project]>[Debug].
• Run program: [Debug]>[Go (F5)].

MDK-ARM:

1. Open the \MDK-ARM subfolder in the example folder. Launch the Project. uvprojx workspace.
2. The workspace name may differ from one example to another.
3. Rebuild all files: [Project]>[Rebuild all target files].
4. Load project image: [Project]>[Start/Stop Debug Session].
5. Run program: [Debug]>[Run (F5)].

STM32CubeIDE

1. Open the STM32CubeIDE toolchain.
2. Click [File]>[Switch Workspace]>[Other] and browse to the STM32CubeIDE workspace directory.
3. Click [File]>[Import], select [General]>[Existing Projects Into Workspace] and click [Next].
4. Browse to the STM32CubeIDE workspace directory and select the project.
5. Rebuild all project files: select the project in the Project Explorer window, then click the [Project]>[Build project] menu.
6. Run program: [Run]>[Debug (F11)].

Developing a custom application
Using STM32CubeMX to develop or update an application
In the STM32CubeU0 MCU Package, all example projects are generated with the STM32CubeMX tool to initialize the system, peripherals, and middleware.
The direct use of an existing example project from the STM32CubeMX tool requires STM32CubeMX 6.11 or higher.

• After the installation of STM32CubeMX, open and, if necessary, update a proposed project. The quickest way to open an existing project is to double-click on the *.ioc file so STM32CubeMX automatically opens the project and its source files.
• The initialization source code of such projects is generated by STM32CubeMX; the main application source code is contained by the comments USER CODE BEGIN and USER CODE END. In case the IP selection and settings are modified, STM32CubeMX updates the initialization part of the code but preserves the main application source code.

To develop a custom project in STM32CubeMX, follow this step-by-step process:

1. Select the STM32 microcontroller that matches the required set of peripherals.
2. Configure the required embedded software using a pinout-conflict solver, a clock-tree-setting helper, a power consumption calculator, and the utility-performing MCU peripheral configuration (such as GPIO or USART) and middleware stacks (such as USB).
3. Generate the initialization C code based on the selected configuration. This code is ready to use within several development environments. The user code is kept at the next code generation.

For more information about STM32CubeMX, refer to the user manual STM32CubeMX for STM32 configuration and initialization C code generation (UM1718).
For a list of the available example projects for STM32CubeU0, refer to the application note STM32Cube firmware examples for the STM32U0 series (AN6063).
HAL application
This section describes the steps required to create a custom HAL application using STM32CubeU0.

1. Create a project
   To create a new project, either start from the template project, provided for each board in \Projects\<STM 32xxx_yyy>\Templates, or from any available project in \Projects\\Examples or \ Projects\\Applications (where refers to the board name, such as NUCLEO-U083RC).
   The template project provides only an empty main loop function, which is a good starting point for understanding theSTM32CubeU0 project settings. The template has the following characteristics:

   • It contains the HAL source code and CMSIS, and BSP drivers that form the minimum set of components required to develop code on a given board.
   • It contains the include paths for all firmware components.
   • It defines the supported STM32U0 series devices, allowing the configuration of the CMSIS and HAL drivers.
   • It provides ready-to-use user files that are preconfigured as shown below:
   • HAL initialized with default time base with Arm® core SysTick.
   • SysTick ISR implemented for HAL_Delay() purpose.
   • When copying an existing project to another location, make sure all the include paths are updated.

2. Add the necessary middleware to the project (optional)
   The available middleware stacks are USBX library, Azure® RTOS, Touch Sensing. To identify the source files to be added to the project file list, refer to the documentation provided for each middleware component. Refer to the applications in \Projects\STM32xxx_yyy\Applications\ (where

   refers to the middleware stack, such as USBX) to know which source files and include paths to add.

3. Configure the firmware components
   The HAL and middleware components offer a set of build-time configuration options, using macros (#define) declared in a header file. A template configuration file is provided within each component that has to be copied to the project folder (usually the configuration file is named xxx_conf_template.h, and the word
   “_template” needs to be removed when copying it to the project folder). The configuration file provides enough information to understand the impact of each configuration option. More detailed information is available in the documentation provided for each component.

4. Start the HAL library
   After jumping to the main program, the application code must call the HAL_Init() API to initialize the HAL library, which carries out the following tasks:

   • Configuration of the flash memory prefetch and SysTick interrupt priority (through macros defined in stm3 2u0xx_hal_conf.h).
   • Configuration of the SysTick to generate an interrupt every millisecond at the SysTick interrupt priority TICK_INT_PRIORITY, defined in stm32u0xx_hal_conf.h, which is clocked by the MSI (at this stage, the clock has not been configured yet and the system is running from the internal 16 MHz MSI).
   • Setting the NVIC group priority to 0.
   • Calling the HAL_MspInit() callback function defined in the stm32u0xx_hal_msp.c user file to perform global low-level hardware initializations.

5. Configure the system clock
   The system clock configuration is done by calling the two APIs described below:
   – HAL_RCC_OscConfig(): this API configures the internal and/or external oscillators, as well as the PLL source and factors. The user chooses to configure one or all oscillators. They can skip the PLL configuration if there is no need to run the system at a high frequency.
   – HAL_RCC_ClockConfig(): this API configures the system clock source, the flash memory latency, the
   AHB preschoolers, and the APB preschoolers.
   Initialize the peripheral

   • First, write the peripheral HAL_PPP_MspInit function by proceeding as follows:
   • Enable the peripheral clock.
   • Configure the peripheral GPIOs.
   • Configure the DMA channel and enable DMA interrupt (if needed).
   • Enable peripheral interrupt (if needed).
   • Edit stm32xxx_it.c to call the required interrupt handlers (peripheral and DMA), if necessary.
   • Write the process complete callback functions if peripheral interrupt or DMA is going to be used.
   • In main.c, initialize the peripheral handle structure, then call the HAL_PPP_Init() function to initialize the peripheral.

6. Develop an application
   At this stage, the system is ready and the user application code development can start.

   • The HAL provides intuitive and ready-to-use APIs to configure the peripheral. It supports polling, interrupts, and a DMA programming model, to accommodate any application requirements. For more details on how to use each peripheral, refer to the rich example set provided in the STM32CubeU0 MCU Package.
   • If the application has real-time constraints, STM32CubeU0 provides a large set of examples showing how to use FreeRTOS™ and integrate it with all middleware stacks, making it a good starting point for developing an application

Caution

Caution: In the default HAL implementation, a SysTick timer is used as the timebase; it generates interrupts at regular time intervals. If HAL_Delay() is called from the peripheral ISR process, make sure that the SysTick interrupt has a higher priority (numerically lower) than the peripheral interrupt. Otherwise, the caller ISR process is blocked. Functions affecting timebase configurations are declared as __weak to make an override possible in case of other implementations in the user file (using a general- purpose timer or other time source). For more details, refer to the HAL_TimeBase example.

Application

• This section describes the steps needed to create a custom LL application using STM32CubeU0.

Create a project
To create a new project, either start from the Templates_LL project provided for each board in \Projects\\Templates_LL or from any available project in \Projects\\Example s_LL ( refers to the board name, such as NUCLEO-U083RC).
The template project provides an empty main loop function, which is a good starting point for understanding the STM32CubeU0 project settings. The template has the following characteristics: