|
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.
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).
- 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:
- Echo application project
- CLI application project
- HTTP server application project
- HTTPS client application project
- Wi-Fi Commissioning over WiFi AP server application project
- Wi-Fi Commissioning over BLE application project
- Peer to Peer Server and Peer to Peer Client application projects
- Firmware update Over The Air project
- MQTT demo project
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.
|
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.
- Select your board from the serial number list.
- Connect to the board as ST-LINK.
- Go to Erasing & Programming section.
- Select your file.
- Click Start Programming.
- 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.
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).
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:
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.
- 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.
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.
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.
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".
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.
Set the terminal parameters from the menu command Setup > Serial_Port...:
Set the terminal parameters from the menu command Setup > Terminal...:
6. References