X-CUBE-ST67W61 Overview

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. X-CUBE-ST67W61 Pack content

This page addresses the content of the X-CUBE Expansion Package archive.
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 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 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 middleware (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 middleware offers an API "Zephyr like" for the Wi-Fi and the network operations (socket API).
The core directory implements an adaptation layer offering a "service API" versus the W61 AT driver API.
The W61 AT driver formats the AT commands to be sent and it implements a receive task to decode the received messages from the W61 and dispatch them to the corresponding module.
The layers "on the top" of the receive task are separated in modules (Wi-Fi, Bluetooth LE, Net, HTTP, MQTT) that are independent between them, making the development modular and simpler.
The receive tasks (implemented in w61_at_rx_parser.c/h), and few other files (w61_at_common.c/h and the w61_at_api.h) are common to all modules.

The physical communication between the host and W61 happens through the SPI.
The AT driver is designed to work also when replacing SPI by UART (this has not been tested, as it would require a coprocessor firmware for support as well).

Utility directories:

Performance: Iperf, memory, and task performance utilities (serves the application, some are based on the service API (for example, iperf)
Shell: Shell utility managing the command line interface (serves the service API and the applications)
Logging: Utility managing the print traces over UART or ITM (serves the driver, the service API, and the applications)
Misc: Common functionalities, such as internet protocol, parsing to serve the driver, the service API and the applications

ST67W6X Network driver directories

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

Basically, a project consists in five main entities:

Application: The application directory contains the application files, for simple project can be just main_app.c/h.
Core: files related to the device (U5, H7RS, H5, N6, etc.) typically generated with STM32CubeMX. Interrupt handling, MSP HW configuration (UART, DMA, TIM, etc)
ST67W6X driver configuration and low level IO bus: Configuration files of the W61 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).
Tracealyzer: It contains the configuration for the Percepio trace analyzer. It is disabled by default.
IDEs: These directories contain the workspace for different IDEs (EWARM, STM32CubeIDE, Keil (in future releases)).

3.1. Application

While the above files and directories remain similar for different projects, the code that makes them different from one to the other is the application, placed in the directory "App_xxx".
X-CUBE-ST67W61 proposes nine simple applications and one demonstration. For all these, the main part of the code is concentrated in a file called "/main_app.c".
The "app_conf.h" is also important as it contains application related configuration definitions such as access point SSID and password, URL to be pinged, URL to the MQTT broker, and other application parameters.

3.2. Core

These files are generated by CubeMX depending on the IPs selected and their configuration.
SPI and DMA are always required. All projects use UART for logging messages and for console inputs (for example, CLI project).
LPTIM is used for low power, this feature is demonstrated only for STM32U5 projects.

3.3. ST67W6X driver configuration and low-level IO bus

Configuration files are placed in the "ST67W6X/Target" directory.
It contains the following configuration files: w61_driver_config.h, w6x_config.h, logging_config.h and shell_config.h.
Additionally, the file spi_port.c is placed here because it can be specific to the SPI and DMA versions IP available on the host board (e.g. NUCLEO-U575ZI-Q or other) but the SPI instance (NCP_SPI_HANDLE) is defined in the App_xxx/Target/spi_port_conf.h due to a STM32CubeMX constraint.

3.4. Tracealyzer

The configuration code of the Tracealyzer is placed in the "ta4recorder" directory, the remaining code is placed in the Middlewares/Third_Party.

3.5. IDEs: build and install

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

3.5.1. STM32CubeIDE

Open the STM32CubeIDE project file.
Right click on the project, and Rebuild all.

3.5.2. EWARM

Open the EWARM project file.
Right click on the project, and Rebuild all.

3.5.3. MDK-ARM

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

3.5.4. STM32CubeProgrammer

If the binaries are already installed, flash the board with STM32CubeProgrammer:

Start STM32CubeProgrammer.
Connect to the board with STLINK.
Go to Erasing & Programming section.
Select your file.
Click Start Programming.

STM32CubeProgrammer usage

3.6. 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 by 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 guide users with the choice of the requested components.

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.

A dedicated wiki page for X-CUBE-ST3276W61.pack usage and for porting projects to other platforms by means of 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 is set to 200'000 bytes, but can be reduced.
Currently, the projects consume between 25'000 and 50'000 bytes of HEAP depending on the project.

By example, for the ST67W6X_Echo project:

About 9'000 bytes are allocated for the SPI communication, with 1'200 bytes at boot and at least 7'000 bytes during execution.
About 1'300 bytes are allocated for logging.
About 2'200 bytes are allocated for the default task. This value depends on the size of the user application.
About 4'000 bytes are allocated for the ST67W6X_Network_Driver tasks.
About 9'500 bytes are allocated for the ST67W6X_Network_Driver internal modules.

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 calling the function "mem_perf_report()", typically when the application ends.

4.1.2. Static RAM memory

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

About 1'000 to 4'000 bytes used by the ST67W6X_Network_Driver.
About 2'000 bytes used by the Toolchain (startup plus EWARM or GCC lib).
About 1'000 to 5'00 bytes used by the application (depends on applications).

static RAM memory table (excluding HEAP)

4.2. ROM/flash memory

Flash memory required depends on the project because the applications have a relevant impact on the code size. The application impacts the application code itself, but the whole project, for example:

Project	Wi-Fi module	BLE module	Net module	HTTP module	MQTT module	FOTA module	Logging	Shell
ST67W6X_BLE_Commissioning	Yes	Yes	Yes	No	No	No	Yes	No
ST67W6X_BLE_p2pClient	No	Yes	No	No	No	No	Yes	No
ST67W6X_BLE_p2pServer	No	Yes	No	No	No	No	Yes	No
ST67W6X_CLI	Yes	No	Yes	No	Yes	Yes	Yes	Yes
ST67W6X_Echo	Yes	No	Yes	No	No	No	Yes	No
ST67W6X_FOTA	Yes	No	Yes	Yes	No	Yes	Yes	No
ST67W6X_HTTP_Server	Yes	No	Yes	No	No	No	Yes	No
ST67W6X_HTTPS_Client	Yes	No	Yes	Yes	No	No	Yes	Yes
ST67W6X_MQTT	Yes	No	Yes	No	Yes	No	Yes	No
ST67W6X_WiFi_Commissioning	Yes	No	Yes	No	No	No	Yes	No

The following picture summarizes the flash usage:

ROM memory table

5. Debug: logs, trace, performance measurements

5.1. Task and memory statistics utilities

Utils/Performance/util_task_perf.c implements a set of functions that allow printing 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().

To 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

Utils/Performance/util_mem_perf.c implements a set of functions that allow printing statistics on the hyper terminal about the FreeRTOS allocated memory in HEAP.

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

To 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 STM32 host CLI application.
To exchange of data packets it is requested an iperf client/server in front.

On Android™ smartphone : Testing the performance of ST67W6X devices against smartphones is described here: How to measure Wi-Fi throughput with Android smartphones
On Linux®: iPerf should be available in the native package management system.
On Windows®: It is recommended to visit one of the websites below. No installation is needed, once downloaded and unzipped, the user must navigate to the extracted folder, open the command prompt and launch the iPerf commands.
- https://files.budman.pw/
- https://github.com/ar51an/iperf3-win-builds

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):

Examples:
/** 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".

More information is available in the file:
"Middlewares\ST\WW6x_Network_Driver\Utils\Logging\Documentation\WW6x_Network_Driver_Logging.chm".

5.3.2. Application configuration for logs routing

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

LOG_OUTPUT_PRINTF: log uses standard printf (it doesn't 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 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 Cube Programmer dedicated windows.

IDEs and Cube Programmer ITM windows

5.4. Shell configuration

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

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

Examples:
/** Maximum length of the string to be printed */
#define SHELL_FREERTOS_MAX_PRINT_STRING_LENGTH     1000
/** Shell receive thread stack size */
#define SHELL_FREERTOS_RX_THREAD_STACK_SIZE        2048

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

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

In case of LOG_OUTPUT_PRINTF or LOG_OUTPUT_UART, any hyper terminal can be used, the below configuration example comes from 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 [STMicroelectronics STLink Virtual COM Port]. For the screenshot below, this is COM5 but it could vary for different users and boards.

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

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

6. References

↑ TeraTerm download website

[1] TeraTerm download website

[1]