|
Back to main page |
|---|
1. Wi-Fi® commissioning over Bluetooth® Low Energy presentation
This application aims to demonstrate how to provision Wi-Fi® credentials via Bluetooth® Low Energy to establish a Wi-Fi® connection to an access point.
It also provides an example of how to update the ST67W611M1 firmware over the air via BLE (see Bluetooth® Low Energy FUOTA).
The solution uses a vendor-specific, dedicated Bluetooth® Low Energy profile and a remote client interface (ST BLE Toolbox smartphone application or ST Web Bluetooth®).
| Bluetooth® Low Energy commissioning solution overview |
|---|
 |
2. Requirements
2.1. Software and system requirements
The software requirements are as follows (minimum IDE versions):
- STM32CubeIDE toolchain V2.1.0 [1].
- IAR Embedded Workbench for Arm (EWARM) toolchain V9.30.1
- RealView Microcontroller Development Kit (MDK-ARM) toolchain V5.39
Programmer:
- STM32CubeProgrammer [2] to program the board with a pre-generated binary file
HyperTerminal:
- Use the application through the serial link
- Open a HyperTerminal client connected to the host ST-LINK COM port
The serial COM port must be configured as shown below:
| Baudrate | 921600 |
| Data | 8b |
| Stopbit | 1b |
| Parity | None |
| Flow control | None |
| Rx | LF |
| Tx | LF |
| Local Echo | Off |
For further details, refer to the HyperTerminal setup page.
2.2. Hardware requirements
This example runs on the NUCLEO-U575ZI-Q [3] board combined with the X-NUCLEO-67W61M1 board.
The X-NUCLEO-67W61M1 board is plugged into the NUCLEO-U575ZI-Q board via the Arduino® connectors:
- The 5V, 3V3, GND through the CN6
- The SPI (CLK, MOSI, MISO), SPI_CS and USER_BUTTON signals through the CN5
- The BOOT, CHIP_EN, SPI_RDY and UART TX/RX signals through the CN9
The USER_BUTTON refers to the button mounted on the X-NUCLEO-67W61M1. Indeed, the user button on the STM32 Nucleo board is not used in external interrupt mode due to a conflict with another EXTI pin requirement. The button must be defined with the user label USER_BUTTON and EXTI falling mode.
3. Wi-Fi® commissioning profile
The Wi-Fi® commissioning profile is a Generic Attribute Profile (GATT)-based low-energy profile defined by STMicroelectronics with proprietary UUIDs (128 bits).
The Wi-Fi® commissioning application demonstrates point-to-point communication using proprietary service and characteristics.
It acts as a Peripheral device with one GATT service and four characteristics.
The Wi-Fi® commissioning server:
- Contains the Wi-Fi® commissioning service, which exposes four characteristics: Wi-Fi® Control (write), Wi-Fi® Configure (write), Wi-Fi® Access Point List (notification), Monitoring (Notification) in order to control and monitor a Wi-Fi® connection
- Is the GATT server
The Client Collector:
- Accesses the information exposed by the Wi-Fi® commissioning application, configures and controls the Wi-Fi® connection with the write characteristics, monitors the Wi-Fi® connection status by receiving notifications from it
- Is the GATT client
The diagram below describes how the ST67W6X_BLE_Commissioning application and the web client interface interact.
| Bluetooth® Low Energy commissioning and ST67W6X |
|---|
 |
3.1. Commissioning profile overview
The table below describes the structure of the commissioning service:
| Bluetooth® Low Energy commissioning service specification | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Wi-Fi® commissioning is exposed as a service.
- Wi-Fi® control characteristic:
- Used to control Wi-Fi® by launching scans, connecting, or disconnecting from a network
| Wi-Fi® commissioning - Wi-Fi® control | ||||||
|---|---|---|---|---|---|---|
|
- Wi-Fi® configure characteristic:
- Used to set up Wi-Fi® parameters before establishing a connection
| Wi-Fi® commissioning - Wi-Fi® configure | |||||||||
|---|---|---|---|---|---|---|---|---|---|
|
- Wi-Fi® access point list characteristic:
- Used to notify information about scanned access points
| Wi-Fi® Commissioning - Wi-Fi® AP List | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
- Monitoring characteristic:
- Used to notify information about the Wi-Fi® network.
| Wi-Fi® commissioning - Wi-Fi® monitoring | |||||||||
|---|---|---|---|---|---|---|---|---|---|
|
| Wi-Fi® ping response format | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
3.2. Advertising data
At startup, the commissioning application starts advertising.
Advertising data refers to information broadcast by a device and is composed as follows:
| Commissioning advertising packet | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Manufacturer data are based on the STMicroelectronics BlueST SDK v2 advertising format, as described below:
| STMicroelectronics manufacturer advertising data | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
4. ST67W6X_BLE_Commissioning application
4.1. Project directory
The "ST67W6X_BLE_Commissioning" application is available by downloading the X-CUBE-ST67W61 Expansion Package.
Refer to the Project directory wiki page for project directory information.
4.2. Project description
The application acts as a peripheral device embedding the commissioning profile and its four characteristics.
At startup, the application starts advertising.
ST Web Bluetooth® Interface (ST Web Bluetooth® application) or ST BLE Toolbox Android/iOS application (ST BLE Toolbox commissioning interface) can be used to scan and connect to the commissioning application.
Once connected, a Wi-Fi® commissioning interface is available on the remote connected application.
This interface allows you to:
- Scan Wi-Fi® networks
- Establish a connection to a Wi-Fi® network
- Disconnect from a Wi-Fi® network
- Ping a Wi-Fi® access point
| Example of flow diagram between ST67W61 and ST Web Bluetooth® Interface |
|---|
 |
4.3. Project structure
The software project structure with the most important parts is shown below.
| Commissioning project structure |
|---|
 |
API descriptions are available on the following page: X-CUBE-ST67W61 Architecture.
4.4. Build and Install
Refer to build and load chapter for details on how to build and download the software onto the device.
4.5. User setup
4.5.1. ST67W6X default configuration
The default System configuration can be modified in "ST67W6X/Target/w6x_config.h":
/** NCP power save mode : 0: NCP stays always active / 1: NCP goes in low power mode when idle */ #define W6X_POWER_SAVE_AUTO 0 /** NCP clock mode : 1: Internal RC oscillator, 2: External passive crystal, 3: External active crystal */ #define W6X_CLOCK_MODE 1
Note: An external clock oscillator must be used to support Bluetooth® Low Energy in low-power mode. If W6X_POWER_SAVE_AUTO is set to 1 but the clock mode is not correct, the W6X_Ble_Init() API disables low-power mode.
The default Bluetooth® Low Energy configuration can be modified in the "ST67W6X/Target/w6x_config.h" file:
/** String defining BLE hostname */ #define W6X_BLE_HOSTNAME "ST_WiFi"
The default Wi-Fi® API configuration can be modified in the "ST67W6X/Target/w6x_config.h" file:
/** Define the region code, supported values : [CN, JP, US, EU, 00] */ #define W6X_WIFI_COUNTRY_CODE "00" /** Define if the country code will match AP's one. * 0: match AP's country code, * 1: static country code */ #define W6X_WIFI_ADAPTIVE_COUNTRY_CODE 0
The default Net API configuration can be modified in the "ST67W6X/Target/w6x_config.h" file:
/** Define the DHCP configuration : 0: NO DHCP, 1: DHCP CLIENT STA, 2:DHCP SERVER AP, 3: DHCP STA+AP */ #define W6X_NET_DHCP 1 /** String defining Wi-Fi® hostname */ #define W6X_NET_HOSTNAME "ST67W61_WiFi" /** Timeout in ticks when calling W6X_Net_Recv() */ #define W6X_NET_RECV_TIMEOUT 10000 /** Timeout in ticks when calling W6X_Net_Send() */ #define W6X_NET_SEND_TIMEOUT 10000
The AT driver can be configured in "ST67W6X/Target/w61_driver_config.h":
/** Maximum number of detected AP during the scan. Cannot be greater than 50 */ #define W61_WIFI_MAX_DETECTED_AP 20 /** Enable/Disable Wi-Fi® module logging */ #define WIFI_LOG_ENABLE 1 /** Enable/Disable Network module logging */ #define NET_LOG_ENABLE 1 /** Maximum number of detected peripheral during the scan. Cannot be greater than 50 */ #define W61_BLE_MAX_DETECTED_PERIPHERAL 10 /** Enable/Disable BLE module logging */ #define BLE_LOG_ENABLE 1 /** Maximum SPI buffer size */ #define W61_MAX_SPI_XFER 6000 /** Enable/Disable System module logging */ #define SYS_LOG_ENABLE 1 /** Debugging only: Enable AT log, i.e. logs the AT commands incoming/outcoming from/to the NCP */ #define W61_AT_LOG_ENABLE 0
Additionally, some other options can be modified in the "ST67W6X/Target" directory with different configuration files, as outlined below:
- logging_config.h: This file provides configuration for the logging component, enabling the setting of the log level
- shell_config.h: This file provides configuration for the Shell component.
- w6x_config.h: This file provides configuration for the W6X APIs (used during init).
- w61_driver_config.h: This file provides configuration for the W61 configuration module.
All available defines are provided in the template directory "Middlewares/ST/ST67W6X_Network_Driver/Conf"
4.5.2. Application configuration
The logging output mode can be modified in "Appli/App/app_config.h":
/** Select output log mode [0: printf / 1: UART / 2: ITM] */ #define LOG_OUTPUT_MODE LOG_OUTPUT_UART
The host low-power mode can be modified in "Appli/App/app_config.h":
/** Low power configuration [0: disable / 1: sleep / 2: stop / 3: standby] */ #define LOW_POWER_MODE LOW_POWER_DISABLE
The host debugger pins can be modified in "Appli/App/app_config.h":
/** * Enable/Disable MCU Debugger pins (dbg serial wires) * @note by HW serial wires are ON by default, need to put them OFF to save power */ #define DEBUGGER_ENABLED 1
4.6. Bluetooth® Low Energy Client solutions
One of the following two Bluetooth® Low Energy client solutions must be used to scan, connect, and interface with the embedded Bluetooth® Low Energy commissioning application.
Note:
- Pressing USER button on the board while not connected clears the bonded device list of the platform.
- Pressing USER button on the board while connected disconnects from the remote client.
4.6.1. ST BLE Toolbox application
In order to interface with the embedded Wi-Fi® commissioning application, the STBLEToolbox Android/iOS application has been updated.
The versions supporting the Wi-Fi® commissioning service are v1.4.3 for Android and 1.2.8 for iOS.
Launch the smartphone application and enable the scan button, if it is not already activated.
You can filter scanned devices by clicking on the SHOW FILTERS button and select ST BLE Wi-Fi to show only devices with Wi-Fi® commissioning service.
Select your device, named ST_WiFi_XX where XX represents the last BD address digit, and connect to it.
| ST BLE Toolbox: Bluetooth® Low Energy scan filter |
|---|
 |
Once connected to the Bluetooth® Low Energy device, click on Wi-Fi Provisioning button to open the commissioning dedicated interface.
| ST BLE Toolbox: Wi-Fi® commissioning interface |
|---|
 |
From this interface, you can launch a Wi-Fi® scan (1), to detect and list all available networks (2).
Once the available networks are displayed, select the one you want to connect to (2), type a password if needed (3), and click on the CONNECT button (4).
| Wi-Fi® connection interface |
|---|
 |
Once the connection request is done, the connection status is displayed in the interface.
Clicking the Ping button starts a ping test with the Wi-Fi® access point and returns the results in the interface.
| Wi-Fi® status and ping |
|---|
 |
4.6.2. ST Web Bluetooth® commissioning interface
Another way to interface with the embedded Wi-Fi® commissioning application is to use the web interface developed by ST and available at the following link: ST Web Bluetooth® Interface, accessible from a computer, tablet, or smartphone.
Enable the Bluetooth® connection of the device, click on "Connect" button and select ST_WiFi_[...] device.
| Connection from web Bluetooth® |
|---|
 |
Once connected, click on the Wi-Fi Commissioning button to open the commissioning dedicated interface.
| Wi-Fi® commissioning interface |
|---|
 |
From this interface, you can launch a Wi-Fi® scan (1), to detect and list all available networks (2).
Once the available networks are displayed, select the one you want to connect to (2), type a password if needed (3) and click on Wi-Fi Connection Request button (4).
| Wi-Fi® connection interface |
|---|
 |
Once the connection request is done, the connection status is displayed in the interface.
| Wi-Fi® connection status |
|---|
 |
Clicking the Ping button starts a ping test with the Wi-Fi® access point and returns the results in the interface.
| Wi-Fi® ping status |
|---|
 |
4.7. Bluetooth® Low Energy FUOTA
This section describes the Bluetooth® Low Energy-based FUOTA mechanism integrated in the ST67W611M1 Bluetooth® Low Energy Commissioning application.
It enables:
- Updating the ST67W611M1 module firmware
- Updating the STM32 NUCLEO-U575ZI-Q host application image (STM32 NUCLEO-U575ZI-Q only)
The Bluetooth® Low Energy FUOTA design reuses the concepts of the Wi-Fi® FOTA workflow while adapting them to a write‑stream Bluetooth® Low Energy pattern (no per‑chunk acknowledgments). For generic concepts see:
4.7.1. Main Points
- Minimal GATT surface: one service, three characteristics (Control Point, Confirmation, Data)
- Write Without Response streaming
- Low ISR load: callbacks enqueue work; heavy operations deferred to a task
- Buffering: single linear buffer with automatic flush
4.7.2. GATT Service Model
The firmware update over the air (FUOTA) profile is intended to demonstrate the multiple capabilities of the ST67W611M1 Bluetooth® Low Energy solution. It acts as:
- GAP central & GATT server (Router service) device to be connected and controlled by a smartphone.
- GAP peripheral & GATT client device to control end device (Bluetooth® Commissioning FUOTA Server).
The FUOTA service is a generic attribute profile (GATT) based on the low-energy profile defined by STMicroelectronics with proprietary UUIDs (128 bits) including three characteristics, described below.
The structure of the FUOTA service is described below:
| Bluetooth® Low Energy FUOTA service specification | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
The FUOTA service is composed of three characteristics:
| FUOTA service - Base address characteristic | |||||||||
|---|---|---|---|---|---|---|---|---|---|
|
The smartphone or web Bluetooth® application uses this characteristic to indicate the action to perform. The address where to load the new application file is managed by the embedded application and not configurable from web Bluetooth® interface.
| FUOTA service - Confirmation characteristic | ||||||
|---|---|---|---|---|---|---|
|
Device (FUOTA server) used this characteristic to inform the smartphone or web Bluetooth® application about:
- Ready To Receive File: ready to receive the new binary application.
- Reboot: the new file is fully received.
- Error not free: not ready to receive a new binary application.
| FUOTA Service - Raw data characteristic | ||||||
|---|---|---|---|---|---|---|
|
The smartphone or web Bluetooth® application uses this characteristic to transfer the file.
Raw Data size is limited to 240 bytes, multiple of 16 bytes, the minimum flash writes access size.
240 bytes is the maximum size multiple of 16 bytes behind the negotiated maximum ATT MTU size 251 bytes.
Only size multiple of 16 bytes lower than 240 bytes are allowed.
4.7.3. FUOTA interfaces
To interface with the embedded Bluetooth® Low Energy FUOTA application, both the ST Web Bluetooth® solution and the ST BLE Toolbox Android/iOS application can be used.
4.7.3.1. ST Web Bluetooth® FUOTA interface
The ST Web Bluetooth® solution has been developed by ST and is available at the following link ST Web Bluetooth® Interface, accessible from a computer, tablet, or smartphone.
Enable the Bluetooth® connection of the device, click on "Connect" button and select ST_WiFi_[...] device.
| Connection from web Bluetooth® |
|---|
|
|
Once connected, click on the Firmware Update Over The Air button to open the FUOTA dedicated interface.
| BLE® FUOTA interface |
|---|
 |
From this interface, select the co-processor to update (1), select the binary file to upload (2) and (3), then start the update (4).
| Button descriptions |
|---|
 |
Upload progress is displayed in the web interface and a platform reboot is performed once it is completed.
4.7.3.2. ST BLE Toolbox FUOTA interface
In order to interface with the Bluetooth® Low Energy FUOTA service, the ST BLE Toolbox Android/iOS application has been updated.
The versions supporting the FUOTA service for the ST67 platform are v1.5.0 for Android and 1.2.10 for iOS.
Connect in the same way as described in the ST BLE Toolbox application chapter.
Then, click on Over The Air Update Server button to open the FUOTA dedicated interface.
| ST BLE Toolbox: FUOTA interface |
|---|
 |
From this interface, select the co-processor to update (1), select the binary file to upload (2), and start the update (3).
| Button descriptions |
|---|
 |
Upload progress is displayed in the web interface and a platform reboot is performed once it is completed.
4.7.4. Operation Flow
The Bluetooth® Low Energy FUOTA task is responsible for processing FUOTA events.
It uses a queue to decouple the Bluetooth® Low Energy event callback from the actual processing.
This way the processing can happen in the FUOTA task context, without blocking the Bluetooth® Low Energy stack.
BLE FUOTA event is received → event is queued → FUOTA task dequeues the event → processes data.
The queue contains a structure with the event type (control or data), the data length and a pointer to the data. The FUOTA task processes the events in the order they are received.
A buffer is allocated at START and freed at FINISH or STOP/CANCEL. This buffer acts as a staging area for incoming data chunks.
Incoming data chunks are appended to this buffer until it is full; at that point, it is flushed to the appropriate API (ST67W611M1 or STM32 NUCLEO-U575ZI-Q), which writes the data to the target flash memory.
If a FINISH command is received, any remaining data in the buffer is flushed before finalizing the update.
The FINISH operation consists of applying the update by bank swapping and rebooting to the new bank. For the ST67W611M1 path, finalize operations are handled internally, including an integrity check before rebooting on the new software.
File Upload indications (0x02: start, 0x01: reboot, 0x03: error) are sent only from the FUOTA task to acknowledge progress or raise an error.
Note that the data characteristic uses Write Without Response, so no per-chunk acknowledgment is sent.
The following tables show FUOTA service base address characteristic usage depending on the target to be updated.
4.7.4.1. ST67W611M1 Update
| Step | Trigger / Base address characteristic | Action Performed | Update Indication (if any) |
Notes |
|---|---|---|---|---|
| 1 | START ST67W611M1 update (0x02) | Allocate a buffer, set ST67W611M1 update mode | 0x02 | Session context initialized |
| 2 | Raw data chunks stream | Append to buffer; flush to module OTA API on full | – | Write Without Response |
| 3 | FINISH (0x07) | Flush remaining buffer data; the ST67W611M1 checks integrity and swaps to the new version if it passes | 0x01 | |
| Abort | STOP (0x00) / CANCEL (0x08) | In case of error or context reset; Free buffer; reset state | – | Partial image discarded |
Below is the flow diagram example of Bluetooth® Low Energy FUOTA for network co-processor binary:
| Example of flow diagram between STM32WBAs & ST Bluetooth® LE Toolbox smartphone application for Network co-processor FUOTA. |
|---|
 |
4.7.4.2. STM32 Update
| Step | Trigger / Base address characteristic | Action Performed | Update Indication (if any) |
Notes |
|---|---|---|---|---|
| 1 | START STM32 update (0x01) | Allocate buffer; select STM32 update mode; erase target flash bank | 0x02 | Done in task context |
| 2 | Raw data chunks stream | Append to buffer; when full write in secondary flash bank | – | Write Without Response |
| 3 | FINISH (0x07) | Flush remaining buffer data; STM32 NUCLEO-U575ZI-Q bank swap and reboot on the new version | 0x01 | Schedule bank swap / reboot sequence |
| Abort | STOP (0x00) / CANCEL (0x08) | In case of error or context reset; Free buffer; reset state | – | Partial image discarded |
Below is the flow diagram example of Bluetooth® Low Energy FUOTA for application binary :
| Flow diagram between STM32WBAs & ST Bluetooth® LE Toolbox smartphone application for Application co-processor FUOTA. |
|---|
 |
4.7.5. Client binary time upload
The following tables show indicative timing when using compressed and uncompressed ST67W611M1 binaries with varying connection intervals.
These results were obtained using the ST67W611M1 Bluetooth® Low Energy Web Application.
They give a general idea of expected time to upload a binary image to the ST67W611M1 module using Bluetooth® Low Energy FUOTA.
| XZ Compressed Image (806400 bytes) | |||
|---|---|---|---|
| Connection Interval (ms) | 55 | 20 | 7.5 |
| Avg Download Time (s) | 44 | 18 | 16 |
| RAW Image (1399872 bytes) | |||
|---|---|---|---|
| Connection Interval (ms) | 55 | 20 | 7.5 |
| Avg Download Time (s) | 75 | 34 | 30 |
4.7.6. Quick Reference Sequence (Module)
4.8. Memory footprint
| Module | Description |
|---|---|
| [Driver] HAL/CMSIS/BSP | STM32 CMSIS Cortex, HAL and LL, Board Specific Package drivers |
| [Project] Core | Native STM32 core components |
| [Project] App | Main part of the application |
| [Project] Target | Configuration files for ST67W6X_Network_Driver component |
| [MW] ST67W6X_Network_Driver | Core and API System, Wi-Fi®, Bluetooth® Low Energy and Network components Util/Logging: Utility to process shell and trace messages onto the UART interface (can be changed by ITM) |
| [MW] FreeRTOS | FreeRTOS kernel source |
| [Utility] lpm | Tiny Low-Power Management |
| [Toolchain] Startup | Int_vect, init routines, init table, CSTACK and HEAP |
| [Toolchain] EWARM Libraries | Native compiler libraries |
These values depend on the chosen toolset, and they can change in future releases.
4.8.1. ROM/Flash memory footprint
The picture below shows the sum of the read-only memory (flash) of the Wi-Fi® commissioning over Bluetooth® Low Energy application.
The picture below shows the middleware ST67W6X_Network_Driver read-only memory (flash) used by Wi-Fi® commissioning over the Bluetooth® Low Energy application.
4.8.2. Read-Write (RW) memory footprint
The picture below shows only the sum of the static read/write memory (static RAM) of the Wi-Fi® commissioning over the Bluetooth® Low Energy application.
