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:

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:

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.

Here are the possible states:

// Wi-Fi Scanner State Machine States
const WIFI_SCANNER_STATE_IDLE     = 0;
const WIFI_SCANNER_STATE_SCAN     = 1;
const WIFI_SCANNER_STATE_SCANNING = 2;
const WIFI_SCANNER_STATE_SCANNED  = 3;
const WIFI_SCANNER_STATE_ERROR    = 4;

// Wi-Fi Config State Machine States
const WIFI_CONFIG_STATE_IDLE      = 0;
const WIFI_CONFIG_STATE_SAVE      = 1;
const WIFI_CONFIG_STATE_SAVING    = 2;
const WIFI_CONFIG_STATE_SAVED     = 3;
const WIFI_CONFIG_STATE_JOIN      = 4;
const WIFI_CONFIG_STATE_JOINING   = 5;
const WIFI_CONFIG_STATE_JOINED    = 6;
const WIFI_CONFIG_STATE_ERROR     = 7;

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:

[
 {
   "ssid": "WHIFERAPPS",
   "rcpi": "156",
   "sec": "2"
 },
 {
   "ssid": "SiliconLabsMobile",
   "rcpi": "129",
   "sec": "2"
 },
 {
   "ssid": "SiliconLabsGuest",
   "rcpi": "128",
   "sec": "2"
 },
 {
   "ssid": "SiliconLabs",
   "rcpi": "118",
   "sec": "2"
 },
 {
   "ssid": "DIRECT-bc-HP M203 LaserJet",
   "rcpi": "108",
   "sec": "2"
 },
 {
   "ssid": "GLC-WESTON",
   "rcpi": "86",
   "sec": "2"
 },
 {
   "ssid": "FCAAC",
   "rcpi": "81",
   "sec": "2"
 },
 {
   "ssid": "KENGOLENDESIGNS",
   "rcpi": "67",
   "sec": "2"
 },
 {
   "ssid": "DreamPlanTrack",
   "rcpi": "60",
   "sec": "2"
 },
 {
   "ssid": "Ameriprise Guest",
   "rcpi": "60",
   "sec": "2"
 },
 {
   "ssid": "Ketamine1290",
   "rcpi": "55",
   "sec": "2"
 }
]

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 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:

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.

 

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.

 

 

Further Reading

• Silicon Labs GATT Configurator User's Guide: https://www.silabs.com/documents/login/user-guides/ug365-GATT-configurator-users-guide.pdf
• Silicon Labs BLE API Reference: https://www.silabs.com/documents/login/reference-manuals/bluetooth-api-reference.pdf
• Silicon Labs Non-Volatile Data Storage Fundamentals: https://www.silabs.com/documents/public/user-guides/ug103-07-non-volatile-data-storage-fundamentals.pdf
• Silicon Labs Wi-Fi Solutions: https://www.silabs.com/products/wireless/wi-fi
• Web Bluetooth Samples: https://googlechrome.github.io/samples/web-bluetooth/
• Interacting with Bluetooth devices on the Web: https://developers.google.com/web/updates/2015/07/interact-with-ble-devices-on-the-web