How to use X-CUBE-ST67W61 STM32CubeMX pack

This message will disappear after all relevant tasks have been resolved.

Semantic MediaWiki

There are 1 incomplete or pending task to finish installation of Semantic MediaWiki. An administrator or user with sufficient rights can complete it. This should be done before adding new data to avoid inconsistencies.


	Back to main page

1. Introduction

The X-CUBE-ST67W61.pack is available in the STM32CubeMX ecosystem.
It can be installed from the “Software Packs” menu, more precisely from the "Manage Software packs” (Alt+U) and “Select Components” (Alt+O) panels.

STM32CubeMX Packages Manager

The projects provided in the X-CUBE-ST67W61 are generated using the STM32CubeMX for NUCLEO-U575ZI-Q, NUCLEO-H7S3L8, NUCLEO-H563ZI and NUCLEO-N657X0-Q boards and defined as below:

Project name	NUCLEO-U575ZI-Q	NUCLEO-H7S3L8	NUCLEO-H563ZI	NUCLEO-N657X0-Q
ST67W6X_BLE_Commissioning	MX	-	-	-
ST67W6X_BLE_p2pClient	MX	-	-	-
ST67W6X_BLE_p2pServer	MX	-	-	-
ST67W6X_CLI	MX	MX	MX	MX
ST67W6X_CLI_LWIP	MX	MX	MX	-
ST67W6X_Echo	MX	MX	MX	MX
ST67W6X_FOTA	MX	-	-	-
ST67W6X_HTTP_Server	MX	-	-	-
ST67W6X_HTTPS_Client	MX	-	-	-
ST67W6X_WiFi_Commissioning	MX	-	-	-
ST67W6X_MQTT	MX	-	-	-
ST67W6X_MQTT_LWIP	-	-	MX	-

The scope of X-CUBE-ST67W61.pack within STM32CubeMX is to help users:

Create their own project
Port existing application examples to other devices
Combine both of the above tasks

The prerequisites are to have the latest:

STM32CubeMX version installed - version 6.15.0 was used to make this tutorial
X-CUBE-ST67W61 installed - version 1.1.0 was used for this tutorial

1.1. Hardware requirements

256 KB of flash memory
48 KB of RAM memory
At least, SPI and DMA must be present

Remember to flash the updated code in the ST67W611M1, refer to How to flash the ST67W611M1.

1.2. FreeRTOS

All the applications available in the X-CUBE-ST67W61 expansion package are based on FreeRTOS.

STM32N6 requires at least X-CUBE-FREERTOS V1.3.1 expansion package based on FreeRTOS 10.6.2 version
CM33 core-based families need at least X-CUBE-FREERTOS V1.3.0
Old devices use legacy FreeRTOS (that is, FreeRTOS provided directly in the middleware without the need to select the X-CUBE-FREERTOS expansion package) and the version of such FreeRTOS depends on the device families.
- STM32L0, STM32F0, use FreeRTOS v10.2.1
- STM32H7, STM32L4, STM32G0 and STM32F4 use FreeRTOS v10.3.1
- STM32H7Rx/7Sx uses FreeRTOS V10.6.2

Required adjustments:

For STM32 on CM0/CM0+ cores with FreeRTOS version older than 10.6 (for example: STM32G0): xPortIsInsideInterrupt CM0 workaround.
Setting the heap size bigger than default size (set to xxx by default by the STM32CubeMX). In the provided examples, it is set to 30 KB. Refer to Heap Size adjustment.
Setting the stack size of the default task to 512 KB (set to 128 KB by default by the STM32CubeMX, which leads to stack overflow during initialization). Refer to Stack Size adjustment.
For few device families, the associated FreeRTOS version can be wrongly detected. In such case, it might be necessary to change the Appli/App/main_app.c to include the correct FreeRTOS API file (app_freertos.h or FreeRTOS.h).

1.3. User code sections limitations

The X-CUBE-ST67W61 applications implement some basic support of USER CODE SECTION to be compatible with STM32CubeMX methodology but not with the intention to cover all cases.
The STM32CubeMX GUI (within component selector) provides the user application which allows the user to write his own application code within USER CODE SECTION.

2. X-CUBE-ST67W61.pack configuration

2.1. Component Selector overview

The pack consists of various layers and components.
The Component Selector lets the user choose which modules are compiled and linked to the project. Some modules are always required, some depend on the chosen application, and others are optional (for example for enhanced logs, statistics, performance measures, trace dumping, low power, and more).

STM32CubeMX Packages Manager

Warning

After selecting components in the Component Selector, they must also be activated in the Mode panel.

Enabling components

2.1.1. Main components

These two components must always be selected to use the applications delivered in the X-CUBE-ST67W61.

Component	Description
ST67 architecture	T01: Wi-Fi^® stack, Bluetooth^® LE stack, network over LwIP and MQTT are embedded in ST67W611M1. T02: Wi-Fi^® stack and Bluetooth^® LE stack are embedded in ST67W611M1. Network over LwIP and MQTT are implemented in the host code.
ServiceAPI	Wi-Fi^®, Bluetooth^® LE, Network, HTTP, MQTT, OTA and system APIs. Required to provide interfaces to the chosen application.
ATDriver	Implementation of AT layer driver and SPI Bus Management. Required to exchange with the ST67W611M1 module.

2.1.2. Applications component

Component	Description
Application	X-CUBE-ST67W61 contains ten functional applications and one user application. Applications menu If the user wants to create its own application based on the ST67W6X_Network_Driver Middleware, it is suggested to select the user application as a starting point. Refer to Application projects page.

Some applications provided in the X-CUBE-ST67W61 are extended compared to what STM32CubeMX generates starting from an empty directory.
In particular:

FOTA application for NUCLEO-U575ZI-Q implements also the host firmware to be updated. The related code strongly depends on the host device and on its flash memory. Refer to FOTA application for details.
HTTP server and Wi-Fi commissioning applications embeds an HTTP Server. Refer to How to generate html_page.h for details.
MQTT and HTTPS client applications are functional with the embedded (default) certificate. Refer to Security and certificates to generate your own certificates.

Warning

Only CLI and MQTT applications are compatible with the ST67 architecture T02. Selecting another application with the architecture T02 is possible, but not currently supported, and it is the user's responsibility to complete the implementation.

2.1.3. Utilities

These three elements are optional but may be required, depending on the application chosen.
If a component is not selected, the associated files are not linked in the project structure.

Component	Description
Logging	Redirect all middleware and application traces to the selected hardware output. By default, UART is chosen as the output solution. If the Logging component is not selected in the Component Selector, printf / putchar is used instead. Users have the option to implement their own module by adhering to the API, which can be achieved by overriding the function vLoggingPrintf(). When Logging is selected in the Component Selector, the default settings configure the OUTPUT_MODE to OUTPUT_MODE_USART and the LOG_LEVEL to DEBUG for all applications. Users can modify these settings through the GUI in the parameter settings panel.
Service Shell	Shell functions to manage the API functions directly into the UART terminal. The Shell utility is required to use the Service Shell features.
Shell utility	Provide a command line interface solution for the user to interact with the program via a serial command. When the component is selected, the feature is disabled by default. The SHELL_ENABLE parameter can be modified in the Parameter Settings tab.
Statistics	Provide some tools to evaluate the performances of the RTOS or network. When the component is selected, the features are disabled by default. The TASK_PERF_ENABLE, MEM_PERF_ENABLED, IPERF_ENABLED parameters can be modified in the Parameter Settings tab.

When using the Shell utility, all Service Shell functions must be placed in specific region of the flash memory.

Note

When Logging or Shell utility are selected and UART is chosen, the implementation requires to enable the UART callback function.

In the Project Manager Menu, under Advanced Settings, enable the UART register callback.

STM32CubeMX UART register callback

Depending on the IDE chosen, the following change must be applied to the project structure:

IDE

Shell utility specific region requirement

EWARM

In the linker script file (as example stm32u575xx_flash.icf):

keep { section FSymTab };
place in ROM_region   { readonly, ro section FSymTab };

STM32CubeIDE

In the linker script file (as example STM32U575ZITXQ_FLASH.ld):

 /* The program code and other data into "FLASH" Rom type memory */
 .text :
 {
   *(.text)           /* .text sections (code) */
   ...
   . = ALIGN(4);
   __fsymtab_start = .;
   KEEP(*(FSymTab))
   __fsymtab_end = .;
   _etext = .;        /* define a global symbols at end of code */
 } >FLASH

MDK-ARM

In Misc controls field of the project Linker options (Project->Options->Linker->Misc controls) add the following options:

--keep *.o(FSymTab) --diag_suppress L6319W

The diag suppress is needed to avoid the warning about the unused section.

2.1.4. Third-party middlewares

These five optional components provide specific features for some applications.

Component	Description
LwIP	Small independent implementation of the TCP/IP protocol suite. Mandatory when ST67 architecture T02 is selected.
MQTT-C	Lightweight publisher-subscriber-based messaging MQTT protocol. Compliant with ST67 architecture T02 and LwIP component.
cJSON	Ultralightweight JSON parser used by several applications (CLI, MQTT, HTTPS client, FOTA).
LittleFS	Minimal File System used by projects to export certificates files to the ST67W611M1 module. These certificates are needed for the security methods (HTTPS, MQTTS, SSL).
TraceRecorder	Percepio Trace tool used to analyze the real-time operating system execution. More details : How to debug with Percepio Trace

2.1.5. Low-power

The tiny low-power mode (LMP) provides a set of macros to enter and exit a chosen low-power mode (Sleep, Stop, Standby).
When selected, FreeRTOS tickless may be required to manage low power directly in the operating system sequencer.
The feature is disabled by default. The LOW_POWER_MODE parameter can be modified in the Parameter Settings tab.

The low-power code is provided for the STM32U5 family. For other platforms, a warning is raised to inform the user to verify compatibility.

2.1.6. Components used by projects

The projects available in the X-CUBE-ST67W61 are defined with the following components:

AT Driver, service API and utility logging are always enabled
FreeRTOS tickless and utility LPM are enabled for all projects based on NUCLEO-U575ZI-Q host board

Project name	Application	ST67 Architecture	Service Shell/Utility shell	Utility statistics	LwIP	MQTT-C	cJSON	LittleFS
ST67W6X_BLE_Commissioning	BLE_Commissioning	T01	No	No	No	No	No	No
ST67W6X_BLE_p2pClient	BLE_p2pClient	T01	No	No	No	No	No	No
ST67W6X_BLE_p2pServer	BLE_p2pServer	T01	No	No	No	No	No	No
ST67W6X_CLI	CLI	T01	Yes	Yes	No	No	Yes	Yes
ST67W6X_CLI_LWIP	CLI	T02	Yes	Yes	Yes	Yes	No	Yes
ST67W6X_Echo	Echo	T01	No	No	No	No	No	No
ST67W6X_FOTA	FOTA	T01	No	No	No	No	Yes	No
ST67W6X_HTTP_Server	HTTP_Server	T01	No	No	No	No	No	No
ST67W6X_HTTPS_Client	HTTPS_Client	T01	Yes	No	No	No	Yes	Yes
ST67W6X_WiFi_Commissioning	WiFi_Commissioning	T01	No	No	No	No	No	No
ST67W6X_MQTT	MQTT	T01	No	No	No	No	Yes	Yes
ST67W6X_MQTT_LWIP	MQTT	T02	No	No	Yes	Yes	Yes	Yes

Note

cJSON and Littlefs are only dependent on the application implementation.

cJSON is used to decode:
- The MQTT frames in ST67W6X_MQTT projects
- The weather API responses in ST67W6X_HTTPS_Client project
- The FOTA header description in ST67W6X_CLI and ST67W6X_FOTA projects
LittleFS is used to store the certificates in a host file system when the application requires a secure connection. This service can be replaced by a direct storage solution in the application code or just disabled if secure connection is not needed.

Warning

Despite certain restrictions imposed in the configuration of the package, combinations other than those used in the projects can be activated. This may result in compilation or execution errors.

2.2. Configuration panel

The "Parameters Setting" panel is used to select the features to be initialized (Wi-Fi^®, Bluetooth^® LE, Network, etc.) and configure the ST67W6X_Network_Driver.
The "Platform Settings" is used to map the IPs instances (for example: SPI, USART, and more).

ST67W6X User application

2.2.1. Parameter Settings tab

Parameters are spread across several configuration files:

Section	Description
W6X Init Modules	The ST67W6X_Network_Driver Service API and AT Driver components are composed by different "modules" (Wi-Fi^®, Bluetooth^® LE, network, MQTT). The user can choose which module to initialize: WIFI_STATION WIFI_SAP BLE NET MQTT The API code for these modules is always generated, but it is not linked if not initialized.
Basic parameters	Setup the global common configuration used by the application and the middleware components.
Logging-Shell parameters	Setup the Logging and Shell components in the "logging_config.h" and "shell_config.h" files.
W6X parameters	Setup the API default configurations (mainly used at initialization) in the "w6x_config.h" file.
W61 driver parameters	Setup the AT drivers default configuration in the "w61_driver_config.h" file.

2.2.2. Platform Settings tab

Mapping between the IPs used by the ST67W61 applications versus the IPs that have been enabled on the device.

IP	Description
SPI	Communication to the modem uses SPI.
USART	User can decide to not output log, use ITM or use its own system. However, when shell component is enabled USART is mandatory.
LPTIM	Required only in case FreeRTOS tickless component is selected (used for low-power with STM32U5)

3. How to generate projects

Three cases are covered:

3.1. How to generate a project starting from an existing ioc

This can be done for one of the devices available in the pack (NUCLEO-U575ZI-Q, NUCLEO-H563ZI, NUCLEO-H7S3L8 and NUCLEO-N657X0-Q).
For other devices than NUCLEO-U575ZI-Q, the X-CUBE-ST67W61 only provides two projects (CLI and Echo), This method allows to generate easily the other projects for the other mentioned devices.

Steps	Description	Graphical view
Step 1	Copy an ioc file in a new directory.	copy and rename the ioc in a new directory
Step 2	Choose the application you want to generate (for example: User).	Application list
Step 3	Adapt the parameters values if needed (Parameter Settings, Platform Settings).	Update Module Initialization generation
Step4	Select the IDE and Press Generate code button.	User application generated from X-CUBE-ST67W61 directory structure
Step5 (Optional)	Skip the step5, enable the Flat directory structure, select the IDE and Press Generate code button. To use flat directory structure (that is, driver and MW directories copied into your project directory) select Use Default Firmware Location and Copy only the necessary library files in the menu Project Manager > Code Generator.	Self content project creation

If the component shell is used, the linker file has to be customized, see Utilities.

The examples above demonstrate how to generate the user application, but this method can be applied to any applications not provided for a specific target (for example, it can be applied to NUCLEO-H7S3L8, NUCLEO-H563ZI, and NUCLEO-N657X0-Q).
Remember that USER CODE SECTIONS for applications other than user may not meet all requirements.

3.2. How to export a project to a pinout compatible MCU

Exporting a project is done by starting from an existing IOC file and using the “Pinout compatible MCU” feature. The feature is deeply described in the chapter 15 of the following STM32CubeMX tutorial:
UM1718 - STM32CubeMX for STM32

Within the IOC provided in the pack (NUCLEO-U575ZI-Q, NUCLEO-H563ZI, NUCLEO-H7S3L8 or NUCLEO-N657X0-Q), choose the one with the package, board, and pinout most similar to the device needing the application port.
For example, to generate for STM32L552ZCTxQ, the IOC provided for NUCLEOS U575ZI-Q are a good starting point because STM32L552ZCTxQ is full pin compatible.

If the device to which user wishes to port the code is available and if it is Pinout Fully compatible, the expected exporting time is rather quick.
If the device to which user wishes to port the code is available, but it needs HW changes, additional work (and time) is required, depending on the incompatibilities.
If the device to which user wishes to port the code is not available, porting becomes more complex. Refer to next chapter: Generate from scratch.

Pinout Compatible MCU results

Double-clicking on the desired device creates a new IOC, based on that device.
Note that all IPs (SPI, UART) and GPIO labels and settings are automatically ported.

Pinout Compatible MCU STM32L5 : ioc created

The user might need to apply minor adaptations:

The interrupt priority if they are not in the same range.
When passing from a device using X-CUBE_FreeRTOS to a device family using legacy FreeRTOS, the FreeROS must be reenabled and reconfigured. Refer to X-CUBE-ST67W61-pack_FreeRTOS.
The X-CUBE-ST67W61 parameters might also need to be updated, in particular the platform settings. Refer to X-CUBE-ST67W61-pack_configuration.
Check the SPI clock settings, where the transmission speed must be a maximum of 40 Mbps (clock domain adjustment may be required).

Once everything is configured, press the "Generate code" button.
The image below shows the code generated for the selected family. In this example STM32L5xx_HAL_Driver is included.

STM32L5 code generated

If the shell component is used, the linker file must be customized, refer to Shell.

3.3. How to generate a project starting from scratch

This is necessary to generate a project from scratch when the device family, the type of package or the shield are not pin-compatible with the IOC delivered as examples.
A step by step description based on a NUCLEO-G0B1RE board is shown below. The following flow can be applied to other Nucleo family boards (STM32U5, STM32H7Rx/7Sx, STM32H5, ...).

3.3.1. Step 1: Project creation

Open STM32CubeMX and create the new project

Open STM32CubeMX and do access to the board selector

Select the STM32 Nucleo-64 development board

Note: Nucleo-64 is selected since STM32G0 is chosen as a target example, but Nucleo-144 could be chosen for other STM32.

3.3.2. Step 2: Pinout & Configuration

Provides all the different steps to configure the hardware pinouts and the relevant middleware

3.3.2.1. Pinout

When generating an application from scratch and if X-NUCLEO-67W61M1 is used, the pinout must be set in accordance with the ST67W61M1 Arduino interfaces.
The table below summarizes the available Arduino interfaces:


Pin function	Arduino Connector	NUCLEO pin name	GPIO mode	GPIO pull mode	GPIO speed
SPI_CLK	CN5.D13	PA5	AF PP	No pull	Very high
SPI_MISO	CN5.D12	PA6	AF PP	No pull	Very high
SPI_MOSI	CN5.D11	PA7	AF PP	No pull	Very high
SPI_CS	CN5.D10	PB0	Output PP	No pull	High
USER_BUTTON	N/A	PC13	EXTI Falling	Pull-up	N/A
CHIP_EN	CN9.D5	PB4	Output PP	No pull	High
BOOT	CN9.D6	PB4	Output PP	No pull	Low
SPI_RDY	CN9.D3	PB3	EXTI Falling/Rising	No pull	N/A

For reference, the X-NUCLEO-67W61M Arduino view is shown below:

X-NUCLEO-67W61M1 top view

Setting

Description

UART GPIO

USART2

Mode: Asynchronous
UART GPIOs setting (in accordance with X-NUCLEO-67W61M1):

PA2: USART_TX
PA3: USART_RX

UART GPIO Settings

UART Parameter Settings

In the Project Manager Menu, under Advanced Settings, enable the UART register callback.

STM32CubeMX UART register callback

SPI GPIO

SPI1

Mode: Full-duplex Master
SPI GPIOs setting (on accordance with X-NUCLEO-67W61M1):

PA5: SPI_SCK
PA6: SPI_MISO
PA7: SPI_MOSI

SPI GPIO Settings

SPI Parameter Settings

Channels DMA

DMA1

Channels DMA setting - association with SPI

DMA Channel0:
- Request: SPI_TX
- Direction: Memory to peripheral
- Channel priority: High
- Source address increment: Enabled
DMA Channel1:
- Request: SPI_RX
- Direction: Peripheral to memory
- Channel priority: High
- Destination address increment: Enabled

DMA Settings

3.3.2.2. Configuration

Setting

Description

Low Power Timer

The following LPTIM1 setting is just given as a "how to do" in case of low-power application requirements.
This low-power and FreeRTOS tickless requirement are only available on STM32U5 platform. Refer to Low Power requirements.

LPTIM1 setting

GPIO

GPIO Settings

Warning

During pinout setting with STM32CubeMX Pinout & Configuration tool, GPIO mode requires special attention. Pinout

Each GPIO pin has to respect the exact GPIO mode.
As example, SPI_RDY GPIO mode must be set to "External Interrupt Mode with Rising/Falling edge trigger detection"

Timer

Sys mode configuration: TIM1 in place of systick

NVIC Settings

NVIC Settings

3.3.3. Step 3: Clock configuration

In the ''Clock Configuration'' panel, set the SPI clock to a maximum of 40 MHz. In this example, the system clock is set to maximum frequency of 64 MHz, prescaler set 2, increasing the SPI clock speed to 32 MHz

Clock Configuration

3.3.4. Step 4: Middleware and software packs

After having configured the hardware pinouts, the real time kernel and software package must be selected and configured.

3.3.4.1. FreeRTOS parameters adjustments

FreeRTOS component can be either selected from middleware (FREERTOS) or from the software pack (X-CUBE-FREERTOS) depending on the chosen STM32.

The size heap value should be set at least to 40 Kbytes. In order to optimize the memory, this value can be adjusted during integration and validation tests of the application.

Heap size adjusted to a value equal to 40'000 bytes

Warning

Legacy FreeRTOS: If the used device embeds an Arm^® Cortex^®M0+ (for example: STM32G0) and its FreeRTOS version is older than of V10.6, the definition below must be added manually after the project is generated.

The definition of xPortIsInsideInterrupt() must be added in portmacro.h (Project/Middlewares/Third_Party/ FreeRTOS/Source/Portable/ARM_CM0)

 #define portINLINE              __inline
 #ifndef portFORCE_INLINE
    #define portFORCE_INLINE    inline __attribute__( ( always_inline ) )
 #endif  
   portFORCE_INLINE static BaseType_t xPortIsInsideInterrupt( void )
   {
       uint32_t ulCurrentInterrupt;
       BaseType_t xReturn;
       /* Obtain the number of the currently executing interrupt. */
       __asm volatile ( "mrs %0, ipsr" : "=r" ( ulCurrentInterrupt )::"memory" );
       if( ulCurrentInterrupt == 0 )
       {
           xReturn = pdFALSE;
       }
       else
       {
           xReturn = pdTRUE;
       }
       return xReturn;
   }

3.3.4.2. X-CUBE-ST67W61 software component

By selecting the X-CUBE-ST67W61 software component, up to 10 different applications (Echo, WiFi_Commissioning, CLI, BLE_Commissioning, BLE_p2p_Client, BLE_p2p_Server, FOTA, HTTP_Server, HTTPS_Client, MQTT) and one user project can be selected.

X-CUBE-ST67W61 software component - mode and configuration

See Component Selector overview for more details.

After selecting an application (in this case, "Echo"), enable the software pack components using the associated checkboxes.

The platform setting tab must also be set.

X-CUBE-ST67W61 software component - configuration and platform setting

See Configuration panel for more details.

3.3.5. Step 5: Generate and build the project

After completing the "Project Manager" setting, press "Generate Code" button.

For STM32 on CM0/CM0+ cores with FreeRTOS version older than 10.6, add the definition of xPortIsInsideInterrupt() as defined in macroport.h cf legacy FreeRTOS

Click on "Open Project". At this point, two options are displayed:

Launch directly a "Rebuilt all" IAR command to generate a new executable. The user can face compilation issues, which can be solved using manual user modifications described above.
Enter "Manual user modifications" before launching the "Rebuilt all" IAR command to generate a new executable.

Whatever the options chosen, the final build should be OK

IAR Embedded IDE

Now, binary is ready to download and run on the target device, allowing you to debug the application if any functional issues arise.