|
Back to main page |
|---|
1. Wi-Fi® commissioning over Bluetooth® LE presentation
This application aims to demonstrate how to provision Wi-Fi® credentials via Bluetooth® LE to establish a Wi-Fi® connection to an access point.
It also provides an example on how to update over the air the ST67W611M1 firmware via BLE (see Bluetooth® LE FUOTA).
The solution uses a vendor specific, dedicated, Bluetooth® LE profile and a remote client interface (ST BLE Toolbox smartphone application or ST web Bluetooth®).
| Bluetooth® LE commissioning solution overview |
|---|
 |
2. Requirements
2.1. Software and system requirements
The software requirements are the following (minimum IDEs version):
- STM32CubeIDE toolchain V1.19.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 below:
| Baudrate | 921600 |
| Data | 8b |
| Stopbit | 1b |
| Parity | None |
| Flow control | None |
| Rx | LF |
| Tx | LF |
| Local Echo | Off |
For more 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 as external interrupt mode due to conflict with other 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 UUID(128 bits).
The Wi-Fi® commissioning application must be used to demonstrate 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 client web interface interact together.
| Bluetooth® LE commissioning and ST67W6X |
|---|
 |
3.1. Commissioning profile overview
The table below describes the structure of the commissioning service:
| Bluetooth® LE commissioning service specification | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Wi-Fi® commissioning is exported as a service.
- Wi-Fi® control characteristic:
- Used to drive the Wi-Fi® by launching scans, connecting or disconnecting from a network
| Wi-Fi® commissioning - Wi-Fi® control | ||||||
|---|---|---|---|---|---|---|
|
- Wi-Fi® configure characteristic:
- Used to setup the 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 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 that is broadcasted by a device and is composed as follows:
| Commissioning advertising packet | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Manufacturer data are based on 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 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 to advertise.
ST Web Bluetooth® Interface must be used to scan and connect to the commissioning application: ST Web Bluetooth® Interface
Once connected, a Wi-Fi® commissioning interface is available on web Bluetooth® page.
This interface allows to:
- Scan Wi-Fi® networks
- Establish 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 in the following page: X-CUBE-ST67W61 Architecture.
4.4. Build and Install
Refer to build and install chapter for details on how to build and download to 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 will go by default in low power mode when NCP is in idle mode */ #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: External clock oscillator must be used to support Bluetooth® LE in low power mode, if W6X_POWER_SAVE_AUTO is set to 1 but clock mode is not correct W6X_Ble_Init() API disable the low power.
The default Bluetooth® LE 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 1520 /** Debugging only: Enable AT log, i.e. logs the AT commands incoming/outcoming from/to the NCP */ #define W61_AT_LOG_ENABLE 0 /** Enable/Disable System module logging */ #define SYS_LOG_ENABLE 1
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 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 available in 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® LE Client solutions
One of the two following Bluetooth® LE client solutions must be used to scan, connect and interface with Bluetooth® LE Commissioning embedded 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 disconnect from remote client.
4.6.1. ST BLE Toolbox application
In order to interface with the Wi-Fi® commissioning embedded application, the STBLEToolbox Andoid/iOS application has been updated.
The versions supporting 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® LE scan filter |
|---|
 |
Once connected to the Bluetooth® LE 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 CONNECT button (4).
| Wi-Fi® connection interface |
|---|
 |
Once the connection request is done, the connection status is displayed in the interface.
Clicking on the Ping button start a ping test with the Wi-Fi® access point and returns results in the interface.
| Wi-Fi® status and ping |
|---|
 |
4.6.2. ST Web Bluetooth® commissioning interface
Another way to interface with the Wi-Fi® commissioning embedded application, is to use the web interface that has been developed by ST and is available at the following link ST Web Bluetooth® Interface accessible from computer, table, 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 on the Ping button to start a ping test with the Wi-Fi® access point and return results in the interface.
| Wi-Fi® ping status |
|---|
 |
4.7. Bluetooth® LE FUOTA
This section describes the Bluetooth® LE-based FUOTA mechanism integrated in the ST67W611M1 Bluetooth® LE 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® LE FUOTA design reuses the concepts of the Wi‑Fi® FOTA workflow while adapting them to a write‑stream Bluetooth® LE 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® LE 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® LE 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. ST Web Bluetooth® FUOTA interface
In order to interface with the Bluetooth® LE FUOTA embedded application, use the web interface that has been developed by ST and is available at the following link ST Web Bluetooth® Interface accessible from computer, table, 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.4. Operation Flow
The Bluetooth® LE FUOTA task is in charge of processing FUOTA events.
It uses a queue to decouple the Bluetooth® LE event callback from the actual processing.
This way the processing can happen in the FUOTA task context, without blocking the Bluetooth® LE stack.
BLE FUOTA event is received → event is queued → FUOTA task dequeue the event → process 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 like a staging area for incoming data chunks.
Incoming data chunks are appended to this buffer until it is full, at this point it is flushed to the appropriate API (ST67W611M1 or STM32 NUCLEO-U575ZI-Q) which is written in flash memory of the target.
If a FINISH command is received, any remaining data in the buffer is flushed before finalizing the update.
The FINISH operation consist on applying the update by bank swapping and rebooting on the new bank. For the ST67W611M1 path, it will internally handle the finalize operations, it does 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 either acknowledge or raise an error.
Note that the data characteristic uses Write Without Response, so no per-chunk acknowledgment is sent.
The following tables shows the FUOTA service base address characteristic usage depending on target to be update.
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 reminding buffer data; The ST67W611M1 will check integrity and swap on new version if pass | 0x01 | |
| Abort | STOP (0x00) / CANCEL (0x08) | In case of error or context reset; Free buffer; reset state | – | Partial image discarded |
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 reminding buffer data ; STM32 NUCLEO-U575ZI-Q Bank Swap and reboot STM32 NUCLEO-U575ZI-Q on 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 |
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® LE Web Application.
They give a general idea of expected time to upload a binary image to the ST67W611M1 module using Bluetooth® LE 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® LE 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 the next 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 the Bluetooth® LE application.
The picture below shows the middleware ST67W6X_Network_Driver read-only memory (flash) used by Wi-Fi® commissioning over the Bluetooth® LE 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® LE application.
