STMicroelectronics FP-AI, I-CUBE, STM32TRUSTEE, X-CUBE Series Embedded Software User manual

UM2312

User manual

Development checklist for STM32Cube Expansion Packages

Introduction

STM32Cube is an STMicroelectronics original initiative to significantly improve designer's productivity 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 the conception to the realization, among which STM32CubeMX , a graphical software configuration tool, STM32CubeIDE , an all-in-one development tool, and STM32CubeProgrammer ( STM32CubeProg ), a programming tool.

• STM32Cube MCU and MPU Packages , comprehensive embedded-software platforms specific to each microcontroller and microprocessor series (such as STM32CubeL4 for the STM32L4 Series), which include STM32Cube hardware abstraction layer (HAL), STM32Cube low-layer APIs, a consistent set of middleware components, and all embedded software utilities.

• 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, and examples.

For a more complete description of STM32Cube, refer to

What is STM32Cube?

Evaluation boards

Figure 1. STM32Cube MCU and MPU Package components

Discovery boards

Application level demonstrations

STM32 Nucleo boards

Dedicated boards

User application

Utilities

CMSIS

USB

Middleware level (1)

Touch library Graphics FAT file system RTOS

Utilities

Board support package (BSP)

HAL and LL APIs

(1) The set of middleware components depends on the product Series.

Low-layer APIs (LL) Hardware abstraction layer APIs (HAL)

The proper development of the STM32Cube Expansion Package depends on criteria related to quality, packaging, middleware support, documentation and others.

This document is a checklist describing all criteria together with their level of importance. These must be met to ensure the compliance of the STM32Cube Expansion Package with each STM32Cube MCU and MPU Package and, further, overall

coherence with the global STM32Cube offering. Report the status for all criteria in the tables from Table 2 to

Table 9

.

UM2312 - Rev 4 - February 2021

For further information contact your local STMicroelectronics sales office.

www.st.com

1

Note:

UM2312

General information

General information

The STM32Cube MCU and MPU Packages and STM32Cube Expansion Packages run on STM32 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.

1.1

Term

API

BSP

CMSIS

DHCP

FTP

HAL

HTTP

HW

LL

SW

TCP/IP

TLS/SSL

References and acronyms

•

•

•

The following document available on www.st.com

are references for the development of STM32Cube Expansion

Packages:

• Development guidelines for STM32Cube Expansion Package ( UM2285 )

Development guidelines for STM32Cube firmware Packs

STM32Cube BSP drivers development guidelines (

( UM2388

UM2298 )

)

How to create a software pack enhanced for STM32CubeMX using STM32 Pack Creator tool ( UM2739 )

Table 1

presents the definitions of the relevant acronyms for a better understanding of this document.

Table 1. List of acronyms

Definition

Application programming interface

Board support package

Cortex Microcontroller Software Interface Standard

Dynamic host configuration protocol

File transfer protocol

Hardware abstraction layer

Hypertext transfer protocol

Hardware

Low-layer

Software

Transmission control protocol / Internet protocol

Transport layer security/secure socket layer

UM2312 - Rev 4 page 2/17

2

UM2312

What is STM32Cube?

What is STM32Cube?

STM32Cube is an STMicroelectronics original initiative to significantly improve designer's productivity 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

– STM32CubeProgrammer ( STM32CubeProg ), a programming tool available in graphical and commandline versions

– STM32CubeMonitor ( STM32CubeMonitor , STM32CubeMonPwr , STM32CubeMonRF ,

STM32CubeMonUCPD ) powerful monitoring tools to fine-tune the behavior 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 STM32CubeL4 for the STM32L4 Series), which include:

– STM32Cube hardware abstraction layer (HAL), ensuring maximized portability across the STM32 portfolio

– STM32Cube low-layer APIs, ensuring the best performance and footprints with a high degree of user control over hardware

– A consistent set of middleware components such as FAT file system, RTOS, USB Host and Device,

TCP/IP, Touch library, and Graphics

– 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

UM2312 - Rev 4 page 3/17

3

STM32Cube Expansion quality criteria

Table 2. Quality criteria

ID

C.Q1

Item description

•

•

BSP drivers, middleware and projects developed within the STM32Cube Expansion Package (add-on to the

STM32Cube MCU Package) must meet the minimum requirements below:

Ensure compilation with all supported toolchains (IAR Systems EWARM, Keil ® MDK-ARM, and

STMicroelectronics STM32CubeIDE ) on Windows ® and Linux ® platforms, without errors neither warnings.

Note: warnings are accepted only in SW components not owned by the developer of the Expansion

Package.

Perform functional tests with evidence reports with no known bugs left.

Note: minor bugs are accepted provided they are documented in the component release notes.

C.Q2

Middleware, BSP and component drivers developed within the STM32Cube Expansion Package (add-ons with respect to the STM32Cube MCU Package) must be compliant with MISRA C ® coding standard and checked with static code analysis, with evidence reports.

Note: any deviation must be precisely justified.

C.Q3

All source code provided must be documented through comments explaining the functional behavior.

1. PASSED / FAILED / NOT APPLICABLE. If FAILED, provide additional comments.

Importance

Mandatory

Recommended -

Mandatory

-

-

Comments

(1)

4

STM32Cube Expansion packaging criteria

ID

C.P1

C.P2

C.P3

C.P4

C.P5

C.P6

C.P7

C.P8

Table 3. Packaging criteria

Item description

The STM32Cube Expansion Package must have the same repository hierarchy as the STM32Cube MCU

Package (refer to section 4.3 Packaging model in UM2388 ).

Native software components provided within the STM32Cube MCU Package must not be modified (it is for instance forbidden to delete a release note or an unused file, or to modify any source code).

•

•

•

•

•

A global release note must be provided for the STM32Cube Expansion Package. It must contain the following sections:

Main changes

Lists the main changes with respect to the previous release

Content

Lists all the software components developed for the STM32Cube Expansion Package and those reused from the STM32Cube MCU Package

Development toolchains and compilers

Lists the supported toolchains and their versions

Supported devices and hardware boards

Lists the supported STM32 devices and the boards (together with their versions) used to run the examples

Known limitations

Lists the main known limitations if any

A release note must be provided for each software component. It must contain the date and version number of the software component files.

Note: date and version are not required to be within the software components files.

Application specific files and added software components must have a license information in the source file header and release note.

New BSP drivers must be added under \Drivers\BSP\<Board-Name> . If a new hardware component driver is needed, it must be added under \Drivers\BSP\Components .

Note: <Board-Name> must comply with the rules described in section “6.4.4 Description of BSP Class drivers” of

UM2388 .

Third-party new middleware component (not part of the STM32Cube Expansion Package) must be located under

\Middlewares\Third_Party .

•

•

•

Example projects must be added under \Projects\<Board-Name> and classified as follows:

Examples: using only HAL and BSP

Applications: using middleware

Demonstration: using HAL, BSP and middleware

Note: <Board-Name> must be the board part number as referenced in in the STM32 Nucleo boards page of the www.st.com

website, and also described in section “6.4.4 Description of BSP Class drivers” of UM2388 .

Importance

Mandatory

Mandatory

Mandatory

Mandatory

Recommended -

Mandatory

Mandatory

Mandatory -

-

-

-

-

-

-

Comments

(1)

ID

C.P9

C.P10

C.P15

C.P16

Item description

Example projects must respect either the basic structure or advanced structure organization as described in

UM2388 .

Note: examples generated by STM32CubeMX are by default in the advanced structure.

Example projects must be generated using STM32CubeMX . Peripheral initialization and middleware configuration must be generated by STM32CubeMX .

C.P11

Files *.ioc

, and .extSettings

(optional, if available) must be provided at the same location as the readm e.txt

in the example folder.

Note: these files are generated by STM32CubeMX .

C.P12

The *.ioc

file must comply with the following convention: Application#N.ioc

.

C.P13

All media files (such as. images, audio, videos and others), when used, must be located under \Utilities\

Media and a readme file explaining the copyright/license of each used media file must be added.

C.P14

Each software file (that is any application running on a PC compatible platform), when used, must be located under \Utilities\PC_Software and a readme file explaining the tool license and how to use it must be added.

For each example; a preconfigured project must be provided for IAR Systems EWARM, Keil

STMicroelectronics STM32CubeIDE toolchains.

® MDK-ARM, and

Non-user files must not be present in the STM32Cube Expansion Package.(such as. tmp files, object files generated by IDE, CMP files ( .git

, .svn

or others)).

1. PASSED / FAILED / NOT APPLICABLE. If FAILED, provide additional comments.

Importance

Mandatory -

Mandatory

Mandatory

Mandatory

Mandatory

Mandatory

Mandatory

Mandatory -

-

-

-

-

-

-

Comments

(1)

5

STM32Cube Expansion BSP criterion

Table 4. BSP criterion

ID

C.B1

Item description

Any new BSP driver (not part of the STM32Cube MCU Package) must comply with STM32Cube BSP drivers development guidelines (refer to UM2298 ).

1. PASSED / FAILED / NOT APPLICABLE. If FAILED, provide additional comments.

Importance

Mandatory -

Comments

(1)

6

STM32Cube Expansion middleware criterion

Table 5. Middleware criterion

ID

C.M1

Item description

Middleware must be hardware and platform independent and the link with the low layers must be provided by means of an interface file.

1. PASSED / FAILED / NOT APPLICABLE. If FAILED, provide additional comments.

Importance

Mandatory -

Comments

(1)

7

STM32Cube Expansion documentation criteria

Table 6. Documentation criteria

ID Item description

C.D1

Each newly added software component (such as BSP or middleware) must have its API documented in a user manual. This user manual can be in .pdf

format or in a format for on-line documentation such as .html

or .c

hm .

C.D2

Each example project must come with detailed explanation, functional description and hardware set-up.

1. PASSED / FAILED / NOT APPLICABLE. If FAILED, provide additional comments.

Importance

Mandatory

Mandatory -

-

Comments

(1)

8

STM32Cube Expansion terminology criteria

Table 7. Terminology criteria

ID

C.T1

C.T2

Item description

When referring to products (both HW and SW), always use the full and correct part number (for instance, use NUCLEO-F401RE , all uppercase, for the STM32 Nucleo-64 development board with STM32F401RE MCU , instead of “Nucleo F4” or similar inappropriate terms). The “STM32 Nucleo” brand must be used exactly as in the

STM32 Nucleo boards page of the www.st.com

website, without any modifications (such as spaces, upper/lower case and others).

When referring to boards that can be plugged onto STM32 Nucleo boards, always use the term “STM32 expansion board” . No other name is allowed (such as shield or others).

1. PASSED / FAILED / NOT APPLICABLE. If FAILED, provide additional comments.

Importance

Mandatory

Mandatory

-

-

Comments

(1)

9

STM32Cube Expansion Package commercial offering criteria

Table 8. Commercial offering criteria

ID

C.C1

C.C2

Item description

•

•

For a commercial STM32Cube Expansion Package, a free version of this software Expansion Package must be provided for evaluation. Each ST partner can choose its own strategy for the free evaluation version, such as:

Middleware delivered as a binary, and time limited (time bombed, reset after a timeout or others)

Middleware delivered as a binary, with limited features

An example must be provided, running on an STM32 board (Discovery board, Nucleo board or Evaluation board) or a board widely available at STM32 distributors.

1. PASSED / FAILED / NOT APPLICABLE. If FAILED, provide additional comments.

Importance

Mandatory

Mandatory

-

-

Comments

(1)

10

STM32Cube Expansion Package enhanced for ST toolset criteria

ID

C.X1

C.X2

C.X3

C.X4

C.X5

C.X6

C.X7

Table 9. ST toolset criteria

Item description

The STM32Cube Expansion Package enhanced for ST toolset must comply with the rules described in user manual Development guidelines for STM32Cube firmware Packs ( UM2388 ).

Note: all deviations must be justified.

Note: the STM32PackCreator tool in STM32CubeMX displays a tooltip for this rule.

•

•

The STM32Cube Expansion Package name must be <vendor>.<name>-<Feature>.<version> where:

<name> is:

– X-CUBE for STMicroelectronics Expansion Packages

– I-CUBE for partner and third-party Expansion Packages

<Feature> is the application domain

Note: the STM32PackCreator tool in STM32CubeMX displays a tooltip for this rule.

The STM32Cube Expansion Package PDSC file must be checked with Arm ® PackChk.exe

.

Note: information about the PackChk.exe

used must be provided .

The STM32Cube Expansion Package release note must contain the URL of the software license agreement

(SLA).

•

•

•

•

The <keyword> tags of the STM32Cube Expansion Package PDSC file must be used to provide additional relevant information such as: minimum memory requirements supported STM32 Series(such as STM32F4, STM32F7or others) supported boards supported core

Note: the STM32PackCreator tool in STM32CubeMX displays a tooltip for this rule.

In the STM32Cube Expansion Package PDSC file, a new <release> field must be added each time a new pack is released, containing a significative list of changes described using clear and short messages. The mindset must be similar to the one applied to GIT Kernel comments.

Note: the STM32PackCreator tool in STM32CubeMX displays a tooltip for this rule.

•

•

•

In the STM32Cube Expansion Package PDSC file, the <apis> section must contain all the APIs relative to the elements in the .pack

file, pointing to: a header file using the <header> attribute, where the APIs are presented in terms of function prototypes a CHM file using the <doc> attribute, describing the APIs and parameters through Doxygen comments

Note: the STM32PackCreator tool in STM32CubeMX displays a tooltip for this rule.

Importance

Mandatory

Mandatory

Mandatory

Mandatory

Mandatory

Mandatory

Recommended -

-

-

-

-

-

-

Comments

(1)

ID Item description

C.X8

A doc/ folder, containing the CHM file describing APIs and parameters of middleware elements, must be located at the same level as the middleware Release_Notes .

C.X9

All non-user comments must be removed from the PDSC file.

C.X10

•

•

Any change in the APIs for a component must be identifiable by means of a new cVersion value in the PDS

C , according to the following rules:

<x.y.z>

–

where: x is a major change: new features, API compatibility break with previous version, or both

–

– y is a minor change: implementation enhancement, bug fix, or both z is a patch

<x.y.z-aaa+bbbbb> syntax must be used for internal or intermediated beta deliveries, where aaa and bbbbb are optional

Note: the STM32PackCreator tool in STM32CubeMX displays a tooltip for this rule.

C.X11

All non-user comments must be removed from the IPconfig and IPmodes files, when available.

C.X12

To improve packs traceability, Cversion must be aligned with the git-repo tag If a <component> contains two or more repositories (like MEMS where BSP and Component Drivers are combined), the

Cversion is determined by the highest level in the SW stack (BSP).

C.X13

To ensure compatibility with underlying pack new versions, conditions must include version numbers in the

STM32Cube Expansion Package PDSC file, such as:

<require Cbundle="BlueNRG-MS" Cclass="Wireless" Cgroup="Controller"

Cversion="4.4.0">

The following line must be removed from the .ioc

included in the example folder:

C.X14

ProjectManager.FirmwarePackage=

1. PASSED / FAILED / NOT APPLICABLE. If FAILED, provide additional comments.

Importance

Recommended

Mandatory -

-

Mandatory -

Mandatory

Recommended -

-

Mandatory -

Mandatory -

Comments

(1)

UM2312

Revision history

Date

14-Nov-2017

6-Sep-2019

9-Sep-2020

18-Feb-2021

2

3

4

Table 10. Document revision history

Revision

1

Changes

Initial release.

Updated Importance of C.Q2

in Table 2: Quality criteria and C.M1

in Table

4: Middleware criteria . Updated the description of STM32Cube on the cover page and in Chapter 3 .

Document entirely revisited.

•

•

•

•

•

•

•

Updated:

STM32Cube Expansion quality criteria

STM32Cube Expansion packaging criteria

STM32Cube Expansion middleware criterion

STM32Cube Expansion documentation criteria

STM32Cube Expansion Package commercial offering criteria

References and acronyms

What is STM32Cube?

•

•

•

Added:

STM32Cube Expansion BSP criterion

STM32Cube Expansion terminology criteria

STM32Cube Expansion Package enhanced for ST toolset criteria

Updated criterion C.P16

in

STM32Cube Expansion packaging criteria .

Removed criterion C.P17.

Updated criterion C.X2

in STM32Cube Expansion Package enhanced for ST toolset criteria

.

UM2312 - Rev 4 page 14/17

UM2312

Contents

Contents

1 General information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2

1.1

References and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 What is STM32Cube? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

3 STM32Cube Expansion quality criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

4 STM32Cube Expansion packaging criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

5 STM32Cube Expansion BSP criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

6 STM32Cube Expansion middleware criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

7 STM32Cube Expansion documentation criteria. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

8 STM32Cube Expansion terminology criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

9 STM32Cube Expansion Package commercial offering criteria . . . . . . . . . . . . . . . . . . . . .11

10 STM32Cube Expansion Package enhanced for ST toolset criteria. . . . . . . . . . . . . . . . . .12

Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14

Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

List of tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

UM2312 - Rev 4 page 15/17

UM2312

List of tables

List of tables

Table 1. List of acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Table 2. Quality criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Table 3. Packaging criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Table 4. BSP criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Table 5. Middleware criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Table 6. Documentation criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Table 7. Terminology criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Table 8. Commercial offering criteria. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Table 9. ST toolset criteria. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Table 10. Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

UM2312 - Rev 4 page 16/17

UM2312

IMPORTANT NOTICE – PLEASE READ CAREFULLY

STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgement.

Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of

Purchasers’ products.

No license, express or implied, to any intellectual property right is granted by ST herein.

Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.

ST and the ST logo are trademarks of ST. For additional information about ST trademarks, please refer to www.st.com/trademarks . All other product or service names are the property of their respective owners.

Information in this document supersedes and replaces information previously supplied in any prior versions of this document.

© 2021 STMicroelectronics – All rights reserved

UM2312 - Rev 4 page 17/17