ST67W611M Bluetooth® LE – Wi-Fi Commissioning

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.

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
WW6 Commissioning Description


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
WW6 Commissioning Description


3.1. Commissioning profile overview

The table below describes the structure of the commissioning service:

Bluetooth® LE commissioning service specification
Service Characteristic Mode UUID size
Wi-Fi commissioning 0000FF9A-cc7a-482a-984a-7f2ed5b3e58f
Wi-Fi Control Write with Response/Read 0000FE9B-8e22-4541-9d4c-21edae82ed19 1
Wi-Fi Configure Write with Response/Read 0000FE9C-8e22-4541-9d4c-21edae82ed19 240
Wi-Fi AP List Notify 0000FE9D-8e22-4541-9d4c-21edae82ed19 240
Monitoring Notify 0000FE9E-8e22-4541-9d4c-21edae82ed19 240

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
Byte Index 0
Name Action
Value 0x01: Wi-Fi Start Scan
0x03: Wi-Fi Connect
0x04: Wi-Fi Disconnect
0x05: Wi-Fi Ping


  • Wi-Fi configure characteristic:
    • Used to setup the Wi-Fi parameters before establishing a connection
Wi-Fi commissioning - Wi-Fi configure
Byte Index 0 1
Name Type Data[ ]
Value 0x01: AP-SSID
0x02: PWD
“ASCII”
"ASCII"


  • Wi-Fi access point list characteristic:
    • Used to notify information about scanned access points
Wi-Fi Commissioning - Wi-Fi AP List
Byte Index 0 1 2 to 3 4 to 7 8 to 40
Name SSID Length Channel Signal level Security Flag SSID
Value 0x00 ... 0x20 0x00 ... 0xFF 0x00 ... 0xFFFF Security_Flag[ ] Data[ ]
  • Monitoring characteristic:
    • Used to notify information about Wi-Fi network.
Wi-Fi commissioning - Wi-Fi monitoring
Byte Index 0 1 up to 239
Name Type Data[ ]
Value 0x03: Connecting
0x04: Connection established
0x05: Ping response
0x06: Error
X
SSID
Refer to table below
0x01: Connection Timeout
Wi-Fi ping response format
Byte Index 0 1 to 2 3 4 to 7
Value 0x05:
ping response
Number of pings
High byte -> Low byte
Packet loss
in %
Average ping value
High byte -> Low byte

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
Description Length AD Type Value
Device Name 11 0x09 ST_WiFi_XX (XX: last byte of BD address)
Manufacturer Data 15 0xFF See table below
Flags 2 0x01 0x06
(GeneralDiscoverable, BrEdrNotSupported)


Manufacturer data are encoded following STMicroelectronics BlueST SDK v2 as described below:

STMicroelectronics manufacturer advertising data
Byte Index 0 1 2-3 4 5 6 7 8 9 10-15
Function Length Manufacturer ID Company BlueST SDK Version Device ID Firmware ID Option 1 Option 2 Option 3 Device Address
Value 0x0F 0xFF 0x0030 STMicro 0x02 0x9A - ST67W611 0xFE - Commissioning 0x00 0x00 0x00 0xXXXXXXXXXXXX

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
WiFi Commissioning Flow Diagram


4.3. Project structure

The software project structure with the most important parts is shown below.

Commissioning project structure
WiFi Commissioning Flow Diagram


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
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
WiFi 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
WiFi 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
WiFi Ping 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®
Connection from Web Bluetooth®

Once connected, click on the Wi-Fi Commissioning button to open the commissioning dedicated interface.

Wi-Fi commissioning interface
WiFi 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
WiFi connection interface


Once the connection request is done, the connection status is displayed in the interface.

Wi-Fi connection status
WiFi 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
WiFi 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.

ST67W6X_BLE_Commissioning Read Only memory footprint.

The picture below shows the middleware ST67W6X_Network_Driver read-only memory (flash) used by Wi-Fi commissioning over the Bluetooth® LE application.

ST67W6X_Network_Driver Read Only memory footprint used by ST67W6X_BLE_Commissioning application.

4.8.2. Read-Write (RW) memory footprint

Info white.png Information
The FreeRTOS Heap is not part of the below chart.
The dynamic memory allocation adds 200'000 bytes (value set for the TOTAL_HEAP_SIZE FreeRTOS parameter).

The ST67W6X_BLE_Commissioning project uses only 28kb of the heap. Refer to Dynamic memory overview wiki page.

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.

ST67W6X_BLE_Commissioning Read Write memory footprint

5. References