|
Coming soon |
Please understand this is draft, thank you
1. X-CUBE-WW4 Pack content
The X-Cube Firmware is organized in the typical way as most of packs delivered by STM.
This Wiki page will focus on the part of the pack specific to the Wi-Fi,
giving a brief description of the Middlewares and Applications folder organization.
Third party Middlerewas (LWIP, MbedTLS, FreeRTOS, etc) are not covered by this page, because their folder structure is inherited from the public code.
2. Middlewares
2.1. WLAN_Driver
It is basically the code allowing the two chips communication (host and ww4) and ww4 fw download.
Umac interface, RPC (Remote Procedure Call) and COM abstraction.
It is provided in source code.
Linux oriented. Folders shared `between MCU host, MPU host and with STM32WW4 device.
It occupies about 10 kb (mw) + 5 kb (sdio) flash (on the host)
2.2. WLAN_Lib and WPA supplicant
WLAN_API, wpa_supplicant, wpa_supplicant MCU customization.
WPA supplicant is given is source code, this comes from Linux distribution.
The customization of the WPA supplicant for MCU devices is given in library.
The WLAN_Lib is a bridge between application, WPA Supplicant, LWIP and WLAN_Driver.
This code is given in libraries.
Part of the WLAN_Lib is given in source code and part as a compiled libraries (.a)
These the principal directories of the WLAN_Lib middleware:
- Api: include files with type definitions and functions prototypes offered by the WLAN_Lib to the application.
- Config: wlan_lib_config_template.h should be copied to the project space and to be used to configure the WLAN_Lib according to the specific project needs.
- Interface: the Wlan_Lib requests via these include files a set of callbacks or functions that the project must provide to allow the Wlan_Lib to be functional. Few examples, a way to allocate memory, a way to log messages, an interface with an IP stack, etc.
- Libraries: part of the implementation not provided in source. libwlancore.a and libwlancommon.a are always required by the linker. The other libraries only for projects requiring the correspondent features.
- WLAN_Driver_Shim: It is a specific interface WLAN_Lib vs WLAN_Driver.
- wpa_supplicant_bsd3: pubblic WPA supplicant from Linux world.
- wpa_supplicant/ST_customization: Customisation to STM32 MCUs.
Big code size, depends on the config and the libraries linked.
3. Projects
Projects are available for U5 and H7 boards.
Each project has similar structure, the picture below refers to CLI project, but other project are similar.
Basically, a project consists in five main entities:
- IDEs: directories containing the workspace for different IDEs (IAR, CubeIDE, Keil in future).
- Core: files related to the device (U5, H7, etc.) typically generated with CubeMX. Interrupt handling, MSP HW configuration (uart, dma, tim, etc)
- MWs configuration and interfaces: Similarly to WLAN_Lib above described, often MWs modules need to be configures and requires some interfaces. The directories LWIP/, MBEDTLS/, Trace/, WLAN_DRIVER/ are meant to provide to the correspondent MW the necessary code to be functional.
- WW4 binary: It is placed in WLAN_Lib_Driver/Target. It is downloaded to the STM32WW4 by the application during initialization. Remind: STM32WW4 does not have flash memory.
- Application: The application resides on the top, it uses several middleware modules and drivers. It needs to be centralized in a common place; due to some CubeFw restriction, it is decided to place* the application in the WLAN_Lib/App directory (in spite it handles also other MWs then WLAN_LIb).
(*) The project WLAN_Driver_Prod is an exception, since it does not use WLAN_Lib middleware, the application is placed in WLAN_Driver/App
Depending on the project other directories might be added for specific cases:
- iperf : used by WLAN_Lib_CLI project to group iperf2 files
- dbgww4 : used by WLAN_Driver_Prod and WLAN_Lib_CLI projects to have direct communication with STM32WW4.
- Eeprom: used by WLAN_Lib_Fota and WLAN_Lib_Provisioning to emulate EPROM (read/store data in flash memory).
- Html: used by WLAN_Lib_HTTP_Server and WLAN_Lib_Provisioning to keep the web pages of the server.
other might come.
3.1. Applications
While the above files and directories remains pretty similar between different projects, the code that makes them different between one and the other is the application, placed in the directory WLAN_Lib/App.
Here there are several files and again most of them are common between applications, few are completely different.
Let's see this more in detail.
Most applications use a "didactical" layer, providing functions that groups a sequence of LWIP and WLAN_Lib functions call, and other functions to print out on the hyper terminal didactical messages about the state of the application. This layer also provides function for facilitate the debug and to get performance or memory usage statistics.
This layer is constituted by files like : "app_common.c, app_handlers.c, uart_if.c, util_led_pb.c, util_net_address.c, util_net_mem.c, util_net_perf.c "
Actually, only WLAN_Lib_Ping does not use this "didactical" layer, because is targeted for experienced developers that want to start writing their application from zero, by interfacing directly with the MWs with minimal overhead.
The file that that really change from one application to the other is : "main_app.c" (in the WLAN_Lib/App )
It is the entry point, often other specific files come to complement it depending on the application, for example:
"generic_mqtt.c, httpserver.c, ping_addr.c, ping_url.c, console.c, etc"
More details about them will be given in the wiki pages specific to each application.
Other three files deserve to be mentioned because users need to configure them for adapting any application to their environment:
The files are "app_conf.h", "msg.h" and "credentials_and_ip_static_addr.h".
3.1.1. Logging
There are many flags to be tune for enabling/disabling the logs, each Middleware has its own, and the application as well.
Sometime the verbose level is selectable dynamically sometime at compilation time.
Sometimes it saves ROM memory (the sting to be printed is removed from the binary) sometime not.
In all cases the logs reach the hyper terminal via the utility ADV_TRACE that uses the the DMA to send a circular buffer of characters on the UART.
3.1.2. Application logs (file msg.h)
Application logs are enabled/disabled at compilation time in the file msg.h \ Disabling these logs allows reducing the memory footprint, but be aware that most of logs are not in the application; so this will only allow to save about 5k flash memory.
#define ENABLE_APP_MSG_DEBUG 0 #define ENABLE_APP_MSG_INFO 1 #define ENABLE_APP_MSG_WARNING 1 #define ENABLE_APP_MSG_ERROR 1 #define ENABLE_APP_MSG_ASSERT 1 #define ENABLE_IPERF2_MSG 1
The file msg.h includes a descriptive part to tell where to enable\disable MWs logs, which is also done in the next paragraph of thei WiKi page.
To be described:
- how to save FLASH memory
- WLAN_Lib trace level and bufer sizing
- how to configure the different MWs
- ADV_trace
3.1.3. WLAN_Lib/Target
tbd
3.1.4. Utils: net perf and memory report
tbd
3.1.5. FreeRTOSConfig.h and FreeRTOS heap
tbd
3.1.6. LWIP options and pull buffers Pull buffers (lwipopts.h and lwippools.h)
tbd
3.1.7. Memory footprint
Should an overview be given here, for example depending on the above options (logs, pulls, tracealyzer, etc)
3.1.8. LwIP gpio indicator
tbd
3.1.9. Tracealyzer
tbd
3.2. IDEs / Build and Install
/* (copied from readme.md). Can be done better */
- Build the chosen project
- Open your preferred toolchain
- Rebuild all files and load your image into target memory
- (Optional) Attach to the running target if you want to debug
- Use the application through the serial link
- Open a Terminal client connected to the Host ST-LINK COM port
- UART Config = 921600, 8b, 1 stopbit, no parity, no flow control
- (Optional) Connect an additional STLINK-V3SET on the X-NUCLEO-WW432 expansion board (CN1 -STDC14 debug header) and open another serial link
- Open a Terminal client connected to the STLINK-V3SET COM port
- UART Config = 921600, 8b, 1 stopbit, no parity, no flow control
- Press Reset button of the Host board