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.
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 required is the following (minimum IDEs version):
- STM32CubeIDE toolchain V1.18.1 [1].
- IAR Embedded Workbench for ARM (EWARM) toolchain V9.30.1
- RealView Microcontroller Development Kit (MDK-ARM) toolchain V5.39
Programmer:
- STM32CubeProgrammer [2] : To flash the board with a previously generated binary
Hyper terminal:
- Use the application through the serial link
- Open a hyper terminal client connected to the Host ST-LINK COM port
The serial COM port must be configured as shown below:
| Baud rate | 921600 |
| Data | 8b |
| Stopbit | 1b |
| Parity | None |
| Flow control | None |
| Rx | LF |
| Tx | LF |
| Local Echo | Off |
For more details see 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 Wi-Fi 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 encoded following STMicroelectronics BlueST SDK v2 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 1 /** NCP clock mode : 1: Internal RC oscillator, 2: External passive crystal, 3: External active crystal */ #define W6X_CLOCK_MODE 1
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 DHCP configuration : 0: NO DHCP, 1: DHCP CLIENT STA, 2:DHCP SERVER AP, 3: DHCP STA+AP */
#define W6X_WIFI_DHCP 1
/** Define if the DNS addresses are set manually or automatically */
#define W6X_WIFI_DNS_MANUAL 0
/** String defining DNS IP 1 address to use
* @note: This address will be used only if W6X_WIFI_DNS_MANUAL equals 1 */
#define W6X_WIFI_DNS_IP_1 {208, 67, 222, 222}
/** String defining DNS IP 2 address to use
* @note: This address will be used only if W6X_WIFI_DNS_MANUAL equals 1 */
#define W6X_WIFI_DNS_IP_2 {8, 8, 8, 8}
/** String defining DNS IP 3 address to use
* @note: This address will be used only if W6X_WIFI_DNS_MANUAL equals 1 */
#define W6X_WIFI_DNS_IP_3 {0, 0, 0, 0}
/** 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
/** String defining Wi-Fi hostname */
#define W6X_WIFI_HOSTNAME "ST67W61_WiFi"
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 50 /** Maximum number of BLE connections */ #define W61_BLE_MAX_CONN_NBR 1 /** Maximum number of BLE services */ #define W61_BLE_MAX_SERVICE_NBR 5 /** Maximum number of BLE characteristics per service */ #define W61_BLE_MAX_CHAR_NBR 5 /** Maximum number of detected peripheral during the scan. Cannot be greater than 50 */ #define W61_BLE_MAX_DETECTED_PERIPHERAL 30 /** 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 below:
Logging configuration
The logging traces can be configured in the file "ST67W6X\Target\logging_config.h".
The trace level can be configured to print only the required information, thereby reducing memory footprint usage.
Set the desired trace level using the following define:
#define LOG_LEVEL LOG_DEBUG
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 "App_BLE_Commissioning/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 "App_BLE_Commissioning/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 "App_BLE_Commissioning/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. ST BLEToolbox 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 commissioning 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.7. 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 and click on "Connect" button.
| 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.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.
