How to use Bluetooth Low-Energy for Wi-Fi commissioning
06/179/2019 | 03:10 PM
Introduction
If your Wi-Fi connected product is headless, then technically speaking, the obvious solution for exchanging the Wi-Fi credentials required to commission the product onto the customer’s Wi-Fi network is SoftAP.
SoftAP stands for Software Enabled Access Point. Some product manufacturers use SoftAP to create a temporary access point for the unique purpose of getting the customer’s Wi-Fi network name (SSID), security mode and password as illustrated in the following diagram:
Figure 1 Wi-Fi commissioning using SoftAP
The customer connects his smartphone to the connected product’s SoftAP, and then uses either a mobile app or web page that displays the list of Access Points available to select and enter the password.
The connected product, once it has the customer’s Wi-Fi network information (SSID, Password and Security Mode) it connects to the Access Point.
The Access Point lets the connected product join the network and gain access to the Internet.
SoftAP used to be the Wi-Fi commissioning solution of choice for early IoT devices, but the two fundamental problems listed below have made it an unreliable solution:
Once the customer’s smartphone connects to a SoftAP, it will lose Internet connection.
If the customer’s smartphone loses Internet connection, then the phone’s logic may switch to a different Access Point and thus disconnect from the product.
In order to improve the out-of-box experience, product manufacturers have turned to Bluetooth as a solution for commissioning. For the Wi-Fi connected products that already support Bluetooth for a different purpose (e.g. streaming audio or video) then Bluetooth is the go-to mechanism for Wi-Fi commissioning as illustrated in the following diagram:
Figure 2 Wi-Fi commissioning using Bluetooth
The customer installs the product manufacturer’s BLE Mobile Application and pairs with the connected product.
The mobile application displays a list of Access Points, the customer selects one of them and enters its password.
The connected product, once it has the customer’s Wi-Fi network information (SSID, Password and Security Mode) it connects to the Access Point.
The Access Point lets the connected product join the network and gain access to the Internet.
Because of how important the out-of-box experience is to a product’s success, many product manufacturers should consider going to the extremes of adding a Bluetooth chip exclusively to support the Wi-Fi commissioning of the product. Silicon Labs has BLE chips such as the EFR32MG12 that not only supports BLE but also other wireless protocols in the same chip.
Whatever your case may be, this blog shows you one simple way to use Bluetooth for Wi-Fi commissioning by covering the following topics:
BLE GATT Server Design
BLE Mobile Application
Theory of Operation
Prerequisites
It is assumed that you are familiar with Web Technologies such as HTML and JavaScript, and more important, that you are familiar with your own Wi-Fi and Bluetooth stacks regarding the following topics:
BLE Stack
Tool to create a BLE Generic Attribute Profile (GATT) database.
Callbacks to handle the BLE Characteristics Read and Write requests.
API to send Notifications to BLE clients.
Wi-Fi Stack
API to start a Wi-Fi scan
Callback to handle the Wi-Fi scan results
API to join an Access Point
API to store the Access Point’s credentials in non-volatile memory
Hardware Requirements
Any Wi-Fi chip/module (e.g. Silicon Labs WF200 module)
Any BLE chip/module (e.g. Silicon Labs EFR32MG12 chip)
Web Server to host a static web page (e.g. AWS account)
Software Requirements
BLE GATT Configurator
Google Chrome Web Browser
BLE GATT Server Design
Using your GATT Configuration tool, you need to create two BLE GATT Services:
Wi-Fi Scanner Service
This service allows a Bluetooth Client to initiate the scanning of visible Wi-Fi networks and its corresponding information such as SSID, Security Mode and Signal Strength.
Wi-Fi Configurator Service
Allows a Bluetooth Client to configure the connected product with the information necessary to connect to a Wi-FI Access Point (i.e. SSID, Security Mode and Password).
The table below shows an example of such GATT database. Notice that the UUIDs have been truncated for sake of simplicity. In reality, they should be 128-bit and it’s important you keep them documented in a table similar to this.
BLE GATT Configuration
Service
Characteristic
Name
UUID
Name
BLE Variable
UUID
Value Settings
Properties
Type
Length
Read
Write
Indicate
Wi-Fi Configurator
2b42…5ab3
State
gattdb_wifi_ cfg_state
c519…07da
user
1
Yes
Yes
Yes
SSID
gattdb_wifi_ cfg_ssid
a4a3…5da7
user
32
No
Yes
No
Password
gattdb_wifi_ cfg_password
1d4b…c315
user
16
No
Yes
No
Security
gattdb_wifi_ cfg_security
0420…278c
user
1
No
Yes
No
Wi-Fi Scanner
9b51…af7d
State
gattdb_wifi_ scan_state
cc89…81c8
user
1
Yes
Yes
Yes
AP List Part 1
gattdb_wifi_ scan_ap_list_1
d07c…d141
user
255
Yes
No
No
AP List Part 2
gattdb_wifi_ scan_ap_list_2
7e44…99d6
user
255
Yes
No
No
AP List Part 3
gattdb_wifi_ scan_ap_list_3
d3c1…b004
user
255
Yes
No
No
AP List Part 4
gattdb_wifi_ scan_ap_list_4
a2a0…7ee0
user
255
Yes
No
No
AP List Part 5
gattdb_wifi_ scan_ap_list_5
8907…2823
user
255
Yes
No
No
Table 1 BLE GATT Configuration
Characteristics
Both services have a characteristic called State that is used to communicate the state of the corresponding operation. Therefore, both characteristics support Read, Write and Notification.
Code Listing 1 Wi-Fi Scanner and Wi-Fi Configurator Service States
The rest of characteristics are meant to exchange the actual data. Notice that the results from the Wi-Fi Scanner need to be communicated in multiple characteristics because of limitations on the maximum length of a BLE Characteristic’s value (i.e. 255 bytes).
Here is an example of the value exchanged by one of such characteristics. It is in JSON format and it is sorted by signal strength such that the closest access point is displayed on top:
Code Listing 2 List of Access Points in JSON format
BLE Mobile Application
For the BLE mobile application you have the choice of creating a native BLE application to support iOS and Android as a minimum or use Web Bluetooth.
Web Bluetooth allows a web browser (e.g. Google Chrome) to see and interact directly with Bluetooth devices as illustrated in the following image:
Figure 3 Web Bluetooth
The BLE mobile application is actually a web page (i.e. HTML and JavaScript) and it's hosted in the product manufacturer's web server.
The customer opens a web browser (e.g. Google Chrome) and goes to the web server’s URL to download the web page.
The web page displays a list of nearby BLE devices and pairs with the BLE device you want to connect.
The advantages of Web Bluetooth over traditional native BLE mobile applications are:
One single web page hosted in a web server allows much easier updates.
One single web page can be used to support all mobile devices
One single web page can also be used not only to connect via Web Bluetooth but also to host in the connected device in SoftAP mode for a line of products that does not support BLE.
Developers with HTML and JavaScript skills are a lot easier to find than those with BLE Mobile App development skills for iOS and Android.
If Web Bluetooth is used instead of a traditional native BLE mobile app, then the revised block diagram for the Wi-Fi commissioning system using Web BLE would look like the following:
Figure 4 Wi-Fi commissioning using Web BLE
The BLE mobile application is actually a web page (i.e. HTML and JavaScript) and it's hosted in the product manufacturer's web server. The web page allows the user to select from a list of Wi-Fi Access Points and enter the Access Point’s password.
The customer opens a web browser (i.e. Google Chrome) and goes to the web server’s URL to download the web page. The web page displays a list of nearby BLE Devices and pairs with the device you want to connect.
The web page sends a scan request to the BLE device which in turn calls the Wi-Fi stack APIs to scan and get the results. Finally, the web page displays a list of Access Points, the customer selects one of them and enters its password.
The connected product, once it has the customer’s Wi-Fi network information (SSID, Password and Security Mode) it connects to the Access Point.
The Access Point lets the connected product join the network and gain access to the Internet.
Theory of Operation
The diagram below summarizes the way the entire system works:
Connected Product
(BLE GATT Server)
Smartphone
(BLE Client)
To initiate a Wi-Fi Scan procedure, the BLE Client sends a request to write:
BLE GATT characteristic: gattdb_wifi_scan_state
Value: WIFI_SCANNER_STATE_SCAN
The BLE GATT Server receives the request to write:
BLE GATT characteristic: gattdb_wifi_scan_state
Value: WIFI_SCANNER_STATE_SCAN
If the Wi-Fi Scanner State Machine's state is WIFI_SCANNER_STATE_IDLE then it will call the Wi-Fi API to start a scan
The Wi-Fi stack returns the scan results by calling a callback function. There, the list of access points is stored in a data structure with a global scope for general purposes
The Wi-Fi stack signals the completion of the scan procedure by calling another callback function
The embedded application prepares a multi-part JSON payload to be stored in a data structure with a global scope for BLE purposes
The embedded application sets the characteristic gattdb_wifi_scan_state to WIFI_SCANNER_STATE_SCANNED and notifies BLE clients that this characteristic has changed
The BLE client receives the notification and sends requests to read the following BLE GATT characteristics: gattdb_wifi_scan_ap_list_1
gattdb_wifi_scan_ap_list_2
gattdb_wifi_scan_ap_list_3
gattdb_wifi_scan_ap_list_4
gattdb_wifi_scan_ap_list_5
The BLE GATT server receives the requests to read the following characteristics and responds with the values: gattdb_wifi_scan_ap_list_1
gattdb_wifi_scan_ap_list_2
gattdb_wifi_scan_ap_list_3
gattdb_wifi_scan_ap_list_4
gattdb_wifi_scan_ap_list_5
The BLE client receives indication that the values of the characteristics have changed and calls the corresponding event handlers
The handler for the event characteristic value changed parses the JSON payload into a JavaScript object, merges each part into a single array of access points, sorts the array by signal strength and populates the drop-down box
The customer selects the Wi-Fi Access Point he wants to join from the web page's drop-down box and enters the password in an input box
The BLE client sends a request to write the following BLE characteristics: gattdb_wifi_cfg_ssid
gattdb_wifi_cfg_password
gattdb_wifi_cfg_security
The BLE GATT server receives the requests to write to the following characteristics: gattdb_wifi_cfg_ssid
gattdb_wifi_cfg_password
gattdb_wifi_cfg_security
The BLE GATT server updates the variables only if there is not any Wi-Fi configuration in progress
The BLE GATT server changes the state of the Wi-Fi Configuration state machine to WIFI_CFG_STATE_ONGOING and sends notification to the BLE client that this state has changed
The BLE client receives the notification and to save the Access Point credentials in non-volatile memory, it sends a request to write:
BLE GATT characteristic: gattdb_wifi_cfg_state
Value: WIFI_CFG_STATE_SAVE
The BLE GATT server receives the request to write:
BLE GATT characteristic: gattdb_wifi_cfg_state
Value: WIFI_CFG_STATE_SAVE and if not saving process in progress, it calls the API to store variables in non-volatile memory
The BLE GATT server changes the state of the Wi-Fi Configuration state machine to WIFI_CFG_STATE_SAVED and sends notification to the BLE client that this state has changed
The BLE client receives the notification and to restart the Wi-Fi interface and connect to the new Access Point, it sends a request to write:
BLE GATT characteristic: gattdb_wifi_cfg_state
Value: WIFI_CFG_STATE_JOIN
The BLE GATT server receives the request to write:
BLE GATT Characteristic: gattdb_wifi_cfg_state
Value: WIFI_CFG_STATE_JOIN and calls the Wi-Fi API to join a network
Figure 5 Flow Diagram
Source Code
To keep the blog relevant to any Wi-FI and BLE stack, the source-code-level details on how to perform the different functions outlined in the previous flow diagram have been omitted.
The following Wi-Fi and BLE APIs are better described in their corresponding documentation and are beyond the scope of this blog:
Callbacks to handle the BLE Characteristics Read and Write requests.
API to send Notifications to BLE clients.
API to start a Wi-Fi scan
Callback to handle the Wi-Fi scan results
API to join an Access Point
API to store the Access Point’s credentials in non-volatile memory
The web page that makes the actual BLE mobile application however, is provided as an attachment (web_ble.zip) and if you like this approach, feel free to modify it and use it under the terms of the Apache License.
Figure 6 Web Bluetooth Mobile Application
Security Considerations
Because of the sensitive nature of the information exchanged, you should consider using the security features of your Bluetooth stack:
Pairing
Bonding
Device Authentication
Encryption
Data Signing
Check your Bluetooth stack documentation for more information on these security features.
How to use Bluetooth Low-Energy for Wi-Fi commissioning
Introduction
If your Wi-Fi connected product is headless, then technically speaking, the obvious solution for exchanging the Wi-Fi credentials required to commission the product onto the customer’s Wi-Fi network is SoftAP.
SoftAP stands for Software Enabled Access Point. Some product manufacturers use SoftAP to create a temporary access point for the unique purpose of getting the customer’s Wi-Fi network name (SSID), security mode and password as illustrated in the following diagram:
SoftAP used to be the Wi-Fi commissioning solution of choice for early IoT devices, but the two fundamental problems listed below have made it an unreliable solution:
In order to improve the out-of-box experience, product manufacturers have turned to Bluetooth as a solution for commissioning. For the Wi-Fi connected products that already support Bluetooth for a different purpose (e.g. streaming audio or video) then Bluetooth is the go-to mechanism for Wi-Fi commissioning as illustrated in the following diagram:
Because of how important the out-of-box experience is to a product’s success, many product manufacturers should consider going to the extremes of adding a Bluetooth chip exclusively to support the Wi-Fi commissioning of the product. Silicon Labs has BLE chips such as the EFR32MG12 that not only supports BLE but also other wireless protocols in the same chip.
Whatever your case may be, this blog shows you one simple way to use Bluetooth for Wi-Fi commissioning by covering the following topics:
Prerequisites
It is assumed that you are familiar with Web Technologies such as HTML and JavaScript, and more important, that you are familiar with your own Wi-Fi and Bluetooth stacks regarding the following topics:
BLE Stack
Wi-Fi Stack
Hardware Requirements
Software Requirements
BLE GATT Server Design
Using your GATT Configuration tool, you need to create two BLE GATT Services:
Wi-Fi Scanner Service
This service allows a Bluetooth Client to initiate the scanning of visible Wi-Fi networks and its corresponding information such as SSID, Security Mode and Signal Strength.
Wi-Fi Configurator Service
Allows a Bluetooth Client to configure the connected product with the information necessary to connect to a Wi-FI Access Point (i.e. SSID, Security Mode and Password).
The table below shows an example of such GATT database. Notice that the UUIDs have been truncated for sake of simplicity. In reality, they should be 128-bit and it’s important you keep them documented in a table similar to this.
BLE GATT Configuration
Table 1 BLE GATT Configuration
Characteristics
Both services have a characteristic called State that is used to communicate the state of the corresponding operation. Therefore, both characteristics support Read, Write and Notification.
Here are the possible states:
Code Listing 1 Wi-Fi Scanner and Wi-Fi Configurator Service States
The rest of characteristics are meant to exchange the actual data. Notice that the results from the Wi-Fi Scanner need to be communicated in multiple characteristics because of limitations on the maximum length of a BLE Characteristic’s value (i.e. 255 bytes).
Here is an example of the value exchanged by one of such characteristics. It is in JSON format and it is sorted by signal strength such that the closest access point is displayed on top:
Code Listing 2 List of Access Points in JSON format
BLE Mobile Application
For the BLE mobile application you have the choice of creating a native BLE application to support iOS and Android as a minimum or use Web Bluetooth.
Web Bluetooth allows a web browser (e.g. Google Chrome) to see and interact directly with Bluetooth devices as illustrated in the following image:
The advantages of Web Bluetooth over traditional native BLE mobile applications are:
If Web Bluetooth is used instead of a traditional native BLE mobile app, then the revised block diagram for the Wi-Fi commissioning system using Web BLE would look like the following:
Theory of Operation
The diagram below summarizes the way the entire system works:
Connected Product
(BLE GATT Server)
Smartphone
(BLE Client)
To initiate a Wi-Fi Scan procedure, the BLE Client sends a request to write:
BLE GATT characteristic: gattdb_wifi_scan_state
Value: WIFI_SCANNER_STATE_SCAN
The BLE GATT Server receives the request to write:
BLE GATT characteristic: gattdb_wifi_scan_state
Value: WIFI_SCANNER_STATE_SCAN
gattdb_wifi_scan_ap_list_1
gattdb_wifi_scan_ap_list_2
gattdb_wifi_scan_ap_list_3
gattdb_wifi_scan_ap_list_4
gattdb_wifi_scan_ap_list_5
gattdb_wifi_scan_ap_list_1
gattdb_wifi_scan_ap_list_2
gattdb_wifi_scan_ap_list_3
gattdb_wifi_scan_ap_list_4
gattdb_wifi_scan_ap_list_5
gattdb_wifi_cfg_ssid
gattdb_wifi_cfg_password
gattdb_wifi_cfg_security
gattdb_wifi_cfg_ssid
gattdb_wifi_cfg_password
gattdb_wifi_cfg_security
BLE GATT characteristic: gattdb_wifi_cfg_state
Value: WIFI_CFG_STATE_SAVE
BLE GATT characteristic: gattdb_wifi_cfg_state
Value: WIFI_CFG_STATE_SAVE and if not saving process in progress, it calls the API to store variables in non-volatile memory
BLE GATT characteristic: gattdb_wifi_cfg_state
Value: WIFI_CFG_STATE_JOIN
BLE GATT Characteristic: gattdb_wifi_cfg_state
Value: WIFI_CFG_STATE_JOIN and calls the Wi-Fi API to join a network
Figure 5 Flow Diagram
Source Code
To keep the blog relevant to any Wi-FI and BLE stack, the source-code-level details on how to perform the different functions outlined in the previous flow diagram have been omitted.
The following Wi-Fi and BLE APIs are better described in their corresponding documentation and are beyond the scope of this blog:
The web page that makes the actual BLE mobile application however, is provided as an attachment (web_ble.zip) and if you like this approach, feel free to modify it and use it under the terms of the Apache License.
Security Considerations
Because of the sensitive nature of the information exchanged, you should consider using the security features of your Bluetooth stack:
Check your Bluetooth stack documentation for more information on these security features.
Further Reading