X-CUBE-ST67W61 Overview

home.png Back to main page

1. X-CUBE-ST67W61 package content

This page addresses the content of the X-CUBE-ST67W61 Wi-Fi® expansion software package.

To recapitulate from other pages, the ST Wi-Fi® solution is composed of two ST devices: the host (MCU) based on STM32 architecture and the ST67W611M1.
The X-CUBE-ST67W61 expansion software package contains the code to be executed on the MCU host (STM32U575, STM32H563, STM32H7S3L8, and STM32N657X0). It also contains the binaries to be loaded into the ST67W611M1 module.
The X-CUBE-ST67W61 expansion software package is organized in the typical way as most of the packs delivered by STMicroelectronics.
This wiki page focuses on the part of the pack specific to the Wi-Fi®, giving a brief description of the organization of the middleware and application folders.
Third-party middlewares (such as FreeRTOS, etc.) are not covered by this page, because their folder structure is inherited from the public code.

X-CUBE-ST67W61 Expansion Package

2. ST middleware

2.1. ST67W6X_Network_Driver

This ST67W6X_Network_Driver middleware offers an API for the Wi-Fi®, Bluetooth® LE and the network operations (Net socket, HTTP, MQTT).

ST67W6X Network driver directories
  • Api : Exposed APIs available for the application.
  • Conf : This middleware configuration template files.
  • Core : Implementation of API and common components to different drivers and few higher-layer functionalities (check states, blocking calls, etc).
  • Driver/W61_at : ST67W611M1 AT commands implementation with parser and formatter processing.
  • Driver/W61_bus : ST67W611M1 communication interface over SPI bus.
  • Utils/Logging : Logging utility to manage the print traces over UART or ITM.
  • Utils/Misc : Miscellaneous utility functions.
  • Utils/Performance : Iperf, memory and task performance utilities.
  • Utils/Shell : Shell utility to manage the command line interface.

For more details, refer to X-CUBE-ST67W61 Architecture page.

3. Projects

Ten projects are provided for the NUCLEO-U575ZI-Q board:

The ST67W6X Echo and ST67W6X CLI projects are also available for NUCLEO-H563ZI, NUCLEO-H7S3L8 and NUCLEO-N657X0-Q boards.

Each project has a similar structure.

Projects directories
  • Appli/App: Application files, main_app.c/h by default, specific applicative files depending of the project.
  • Appli/Target: Application target files to manage the logging, shell, host low power porting implementation.
  • Core: files related to the device (U5, H7RS, H5, N6, etc.) and generated with STM32CubeMX. Interrupt handling, MSP HW configuration (UART, DMA, TIM, etc)
  • ST67W6X/App: Entry point of the ST67W6X Application, to configure the main task and the main_app call.
  • ST67W6X/Target: Configuration files of the ST67W6X_Network_Driver (based on the provided templates) and device family dependent low layer (e.g part of the bus driver depending on the device U5, H7RS, H5, N6, etc).
  • IDEs: These directories contain the workspace for different IDEs (EWARM, STM32CubeIDE, Keil).

3.1. Appli

While the above files and directories remain similar for different projects, the application code located in the "Appli" directory is what differentiates one project from another.
X-CUBE-ST67W61 offers ten applications and two demonstrations.
For all of these, the main part of the code is concentrated in the following file "Appli/App/main_app.c".
The file "Appli/App/app_config.h" is also important, as it contains application-related configuration definitions, including the access point SSID and password.

3.2. Core

These files are generated by STM32CubeMX, depending on the IPs selected and their configuration.

  • SPI and DMA are always required to communicate with the ST67W611M1.
  • UART is used for logging messages in all applications. It is also required when the shell service is enabled for console inputs (as ST67W6X_CLI project).
  • LPTIM is used for low power. This feature is demonstrated only for projects based on the STM32U5 family.

3.3. ST67W6X

The configuration files are placed in the "ST67W6X/Target" directory and contain the following files:

  • w61_driver_config.h: configuration for the W61 AT module.
  • w6x_config.h: configuration for the W6X services.
  • logging_config.h: configuration for the logging component to set the log level.
  • shell_config.h: configuration for Shell component (enable, command level, color, memory usage).
  • bsp_conf.h: configuration of IP instances used for UART, SPI and LPTIM (if low-power host enabled) defined in the platform settings.

Additionally, the file spi_port.c is placed in this directory to implement the SPI board specific porting file required by the ST67W6X_Network_Driver bus implementation.

3.4. IDEs: build and load

Applications are delivered with STM32CubeIDE, MDK-ARM, and EWARM project environments.

3.4.1. STM32CubeIDE

  • Import the STM32CubeIDE project in an existing workspace or open it directly with ST67W6X_**/STM32CubeIDE/.project file.
  • Select the targeted configuration: debug or release.
  • Build the project

For more information about STM32CubeIDE, refer to UM2553 STM32CubeIDE Quick start guide.

3.4.2. EWARM

All EWARM application projects in the X-CUBE-ST67W6X expansion software package are developed with the EWARM 9.30.1. Lower version of the IDE cannot open these projects.
If the chosen board is not supported by the EWARM version installed, it is required to install the patch available in Utilities/PC_Software/EWARMv9_STM32**.zip

  • Open the EWARM Project.eww file.
  • Right click on the project and Rebuild all.

3.4.3. MDK-ARM

  • Open the MDK-ARM project file.
  • Right click on the project, and Rebuild

3.4.4. STM32CubeProgrammer

If the binaries are already generated, it is possible to flash the board with STM32CubeProgrammer:

Open STM32CubeProgrammer and connect an USB cable from the board on ST-LINK connector to the computer.

STM32CubeProgrammer usage
  1. Select your board from the serial number list.
  2. Connect to the board as ST-LINK.
  3. Go to Erasing & Programming section.
  4. Select your file.
  5. Click Start Programming.
  6. The download is completed.

3.5. STM32CubeMX overview

Applications are delivered with the corresponding *.ioc files for STM32CubeMX.
X-CUBE-ST67W61 pack is available in the "Embedded Software Packages Manager" (Alt-U).

The pack is composed of different layers and components, as explained at the beginning of this chapter.
Depending on the application some components are optional and can be disabled.
Once the application is selected in the "Component Selector" panel (Alt-O), STM32CubeMX guides the users is choosing the requested components.

If the user wants to create his/her own application based on the ST67W6X_Network_Driver Middleware, it is suggested to select the application user as a starting point.

A dedicated wiki page for X-CUBE-ST67W61.pack usage and for porting projects to other platforms via the STM32CubeMX is provided here: How to use X CUBE ST67W61 STM32CubeMx pack

4. Memory

4.1. Read-Write (RW) memory setting

4.1.1. Dynamic memory

Dynamic memory is allocated in the FreeRTOS heap instead of the Lib-C heap.
The classical heap memory instantiated in the linker file is therefore no longer used and can be minimized. On the other hand, the FreeRTOS HEAP is configured depending on the project.
Configuration is done in the "Core/Inc/FreeRTOSConfig.h". In this release, it is set to 200,000 bytes but can be reduced.
Currently, the projects consume between 13 000 and 40 000 bytes of heap depending on the project.

For example, in the ST67W6X_Echo project:

  • About 4300 bytes are allocated for the SPI communication, with 1300 bytes at boot and at least 3000 (2 * W61_MAX_SPI_XFER) for the receive process.
  • About 1300 bytes are allocated for logging.
  • About 4300 bytes are allocated for the ST67W6X task. This value depends on the size of the user application.
  • About 4200 bytes are allocated for the modem handler (task, semaphores and local buffer).
  • About 1900 bytes are allocated for the ST67W6X_Network_Driver internal modules.
Note white.png Note
W61_MAX_SPI_XFER is defined at 1520 bytes by default but can be modified to increase performance throughput to a maximum of 6000 bytes.
dynamic RAM memory table

The application code in "ST67W6X_Network_Driver/Utils/Performance/util_mem_perf.c" allows to report information on the heap memory usage.
The information is displayed on the Hyper Terminal when the function "mem_perf_report()" is called, typically at the end of the application.

4.1.2. Static RAM memory

Currently, the projects consume on average about 5000 bytes of static RAM.

  • About 1000 to 4000 bytes used by the ST67W6X_Network_Driver.
  • About 2000 bytes used by the toolchain (startup plus EWARM or GCC lib).
  • About 1000 to 5000 bytes used by the application (depends on applications).
Warning white.png Warning

Additionally, the projects with LwIP consume also 46 KB of memory:

  • 34 KB for the ram_heap buffer used for TX frames
  • 12 KB for the memp_memory (mem_PBUF, mem_TCP, ...) used to manage the pbuf allocation

These values can be adjusted in "LWIP\Target\lwipopts.h" by MAC_TXQ_DEPTH define (default value is 32) where:

  • ram_heap is defined by
  • memp_memory is defined by


static RAM memory table (excluding HEAP)

4.2. ROM/flash memory

The flash memory required depends on the project, as the applications significantly affect the code size. The applications impact the application code itself, and the whole project. For example:

Project Wi-Fi® module Bluetooth® LE module Net module HTTP module MQTT module FOTA module Logging Shell
ST67W6X_BLE_Commissioning Yes Yes Yes No No No Yes(LOG_DEBUG) No
ST67W6X_BLE_p2pClient No Yes No No No No Yes(LOG_INFO) No
ST67W6X_BLE_p2pServer No Yes No No No No Yes(LOG_INFO) No
ST67W6X_CLI Yes Yes Yes No Yes Yes Yes(LOG_DEBUG) Yes
ST67W6X_CLI_LWIP Yes Yes No No No No Yes(LOG_DEBUG) Yes
ST67W6X_Echo Yes No Yes No No No Yes(LOG_DEBUG) No
ST67W6X_FOTA Yes No Yes Yes No Yes Yes(LOG_DEBUG) No
ST67W6X_HTTP_Server Yes No Yes No No No Yes(LOG_INFO) No
ST67W6X_HTTPS_Client Yes No Yes Yes No No Yes(LOG_INFO) Yes
ST67W6X_MQTT Yes No Yes No Yes No Yes(LOG_DEBUG) No
ST67W6X_WiFi_Commissioning Yes No Yes No No No Yes(LOG_INFO) No

The following picture summarizes the flash usage:

ROM memory table

By default, the Shell commands list is reduced. To enable all available commands, it is required to modify the define in the ST67W6X/Target/shell_config.h as below:
+ 30 KB of memory is required:

/** Default shell commands list level (0: Minimal, 1: Full) */
#define SHELL_CMD_LEVEL                         0

The logging level can be modified to reduce memory usage (but important traces can be lost). As an example, in the ST67W6X_CLI project, setting the LOG_LEVEL define to LOG_DEBUG allows memory reduction as described below:

LOG_LEVEL ROM Memory reduction (relative to LOG_DEBUG)
LOG_INFO -2kb
LOG_WARN -14kb
LOG_ERROR -16kb
LOG_NONE (trace disabled) -31kb

By default, the logging module is defined with the level set to either LOG_DEBUG or LOG_INFO. For each module, it is possible to enable/disable the traces in the ST67W6X/Target/w61_driver_config.h as below (all enabled by default):

/** Enable/Disable Wi-Fi module logging */
#define WIFI_LOG_ENABLE                         1

/** Enable/Disable Network module logging */
#define NET_LOG_ENABLE                          1

/** Enable/Disable BLE module logging */
#define BLE_LOG_ENABLE                          1

/** Enable/Disable MQTT module logging */
#define MQTT_LOG_ENABLE                         1

/** Enable/Disable System module logging */
#define SYS_LOG_ENABLE                          1

To enable the traces for all AT operations, modify the define in the ST67W6X/Target/w61_driver_config.h as below:
+ 1 KB of memory is required

/** Debugging only: Enable AT log, i.e. logs the AT commands incoming/outcoming from/to the NCP */
#define W61_AT_LOG_ENABLE                       1

To enable the assert for all functions in the ST67W6X_Network_Driver, modify the define in the ST67W6X/Target/w61_driver_config.h as below:
+ 2 KB of memory is required:

/** Enable/Disable NULL pointer check in the AT functions.
 * 0: Disabled, 1: Enabled */
#define W61_ASSERT_ENABLE                       1

5. Debug: logs, trace, performance measurements

5.1. Task and memory statistics utilities

The file Utils/Performance/util_task_perf.c implements a set of functions that print task statistics on the Hyper Terminal about the tasks used.

  • To add this feature, call the functions task_perf_start() and task_perf_stop() respectively at the beginning and at the end of the application.
  • To display the report, call the function task_perf_report().

Register the following hooks in the FreeRTOSConfig.h file:

 #if defined(__ICCARM__) || defined(__ARMCC_VERSION) || defined(__GNUC__)
 void mem_perf_malloc_hook(void *pvAddress, size_t uiSize);
 void mem_perf_free_hook(void *pvAddress, size_t uiSize);
 #endif
 #define traceMALLOC mem_perf_malloc_hook
 #define traceFREE mem_perf_free_hook


The file Utils/Performance/util_mem_perf.c implements a set of functions that print task statistics on the Hyper Terminal about the FreeRTOS allocated memory in heap.

To display the report, call the function mem_perf_report().

Register the following hooks in the FreeRTOSConfig.h file:

 #if defined(__ICCARM__) || defined(__ARMCC_VERSION) || defined(__GNUC__)
 void task_perf_in_hook(void);
 void task_perf_out_hook(void);
 #endif
 #define traceTASK_SWITCHED_IN task_perf_in_hook
 #define traceTASK_SWITCHED_OUT task_perf_out_hook

5.2. Throughput performance measurements

iPerf is a widely used network testing tool that can create TCP and UDP data streams and measure the throughput of a network. It is particularly useful for diagnosing network issues and testing the performance (throughput) of a network.
Use the command iperf -h on the ST67W6X_CLI or ST67W6X_CLI_LWIP applications.
To exchange data packets, a Iperf client/server is required in front.

Note: Linux® is a registered trademark of Linus Torvalds. Windows® is a trademark of the Microsoft group of companies.
For more information: How to measure Wi-Fi throughput

5.3. Logs configuration

5.3.1. Middleware configuration

Four log levels are defined: (LOG_NONE,) LOG_ERROR, LOG_WARN, LOG_INFO and LOG_DEBUG.
The flag LOG_LEVEL in the file "ST67W6X\Target\logging_config.h" is used to change the verbosity.

Note: All the log messages with a log level lower than LOG_LEVEL are stripped from the final application binary.

Buffers of the log can also be tuned to save memory (the smaller the buffers, the smaller should be the verbosity):

/** Max message length */
#define MAX_LOG_MESSAGE_LENGTH                  2000

/** Max queue length */
#define MAX_LOG_QUEUE_LENGTH                    200

/** Max log level */
#define MAX_LOG_MEMORY                          4096

Refer to all available tuning in the "Middlewares\ST\ST67W6X_Network_Driver\Conf\logging_config_template.h".

5.3.2. Application configuration for logs routing

The flag LOG_OUTPUT_MODE in the file "Appli\App\app_config.h" is used for routing the logs.

  • LOG_OUTPUT_PRINTF: Log uses standard PRINTF (it does not use Utils/Logging/ implementation in the middleware)
  • LOG_OUTPUT_UART: Log output through UART using HAL_UART_Transmit_IT() (it uses Utils/Logging/ implementation in the middleware and the flow is shown in the picture below)
  • LOG_OUTPUT_ITM: Log is output via ITM (instrumentation trace macrocell) Cortex feature.
Logging flow overview
Logging flow overview when configuring LOG_OUTPUT_UART or LOG_OUTPUT_ITM output mode

5.3.3. Details about logs through ITM

Instead of outputting the logs over UART, it is possible to output them through ITM (instrumentation trace macrocell).
The result logs are displayed in the IDEs or STM32Cube Programmer dedicated windows.

CubeIDEs and CubeProgrammer ITM windows
IDEs and Cube Programmer ITM windows

5.4. Shell configuration

Shell can be enabled or disabled in the file ST67W6X\Target\shell_config.h

Buffers of the shell can be tuned to save memory or augmented if some messages are lost:

/** Maximum length of the string to be printed */
#define SHELL_FREERTOS_MAX_PRINT_STRING_LENGTH  2000

/** Shell receive thread stack size */
#define SHELL_FREERTOS_RX_THREAD_STACK_SIZE     3072

Refer to all available tunings in "Middlewares\ST\ST67W6X_Network_Driver\Conf\shell_config_template.h".

Logging flow diagram
Dual channel log and shell data flow when LOG_OUTPUT_UART is selected

Note that logging and shell can have separate outputs; in particular when logging uses LOG_OUTPUT_ITM, shell is automatically redirected on UART through PRINTF (without queue sharing but using putchar/fputc).

5.5. Hyper terminal setup

For LOG_OUTPUT_PRINTF or LOG_OUTPUT_UART, any Hyper Terminal can be used. The configuration example below is based on Tera Term.
Tera Term is an open-source and freely available software terminal emulator, which is used to display log messages through a serial connection. Users can download and install the latest version available from the TeraTerm download website[1]. Otherwise they should be able to use any other terminal emulator software.

Once the Nucleo board is connected to the PC, start Tera Term and select the proper connection featuring the following: [STMicroelectronics STLink Virtual COM Port]. In the screenshot below, the port shown is COM5, but this may vary depending on the user and the board.

Tera Term connection

Set the terminal parameters from the menu command Setup > Serial_Port...:

Tera Term Serial Port parameters

Set the terminal parameters from the menu command Setup > Terminal...:

Tera Term terminal parameters

6. References