Silicon Labs Silicon Labs Community
silabs.com
Language
  • 简体中文
  • 日本語
  • MCUs
    • 8-bit MCU
    • 32-bit MCU
  • Wireless
    • Bluetooth
    • Proprietary
    • Wi-Fi
    • Zigbee & Thread
    • Z-Wave
  • More Products
    • Interface
    • Isolation
    • Power
    • Sensors
    • Timing
  • Development Tools
    • Simplicity Studio
    • Third Party Tools
    • Thunderboard
  • Expert's Corner
    • Announcements
    • Blog
    • General Interest
    • Projects
  1. Community - Silicon Labs
  2. Blog

How to use Bluetooth Low-Energy for Wi-Fi commissioning

06/179/2019 | 03:10 PM
Juan Benavides
Employee

Level 4


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.

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:

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.

 

 

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

  • Bluetooth Low Energy
  • Blog Posts
  • Wi-Fi
web_ble_v2.zip

Tags

  • Wireless
  • High Performance Jitter Attenuators
  • EFR32MG21 Series 2 SoCs
  • Blue Gecko Series 2
  • Zigbee SDK
  • ZigBee and Thread
  • Internet Infrastructure
  • Sensors
  • Blue Gecko Bluetooth Low Energy SoCs
  • Z-Wave
  • Micrium OS
  • Blog Posts
  • Low Jitter Clock Generators
  • Bluetooth Classic
  • Makers
  • Flex SDK
  • Tips and Tricks
  • Smart Homes
  • IoT Heroes
  • Reviews
  • RAIL
  • Simplicity Studio
  • Mighty Gecko SoCs
  • Timing
  • Blue Gecko Bluetooth Low Energy Modules
  • Clocks
  • Ultra Low Jitter Clock Generators
  • General Purpose Clock Generators
  • Industry 4.0
  • Giant Gecko
  • 32-bit MCUs
  • blue-gecko-xpress-modules
  • Bluetooth Low Energy
  • 32-bit MCU SDK
  • Gecko
  • Microcontrollers
  • News and Events
  • Industrial Automation
  • Wi-Fi
  • Bluetooth SDK
  • Community Spotlight
  • Biometric Sensors
  • General Purpose Jitter Attenuators
  • Giant Gecko S1
  • Flex Gecko
  • Internet of Things
  • 8-bit MCUs
  • Isolation
  • Powered Devices

Top Authors

  • Avatar image Mark Mulrooney
  • Avatar image Siliconlabs
  • Avatar image Nari Shin
  • Avatar image lynchtron
  • Avatar image deirdrewalsh
  • Avatar image Lance Looper
  • Avatar image lethawicker

Archives

  • 2014 December
  • 2015 January
  • 2015 February
  • 2015 March
  • 2015 April
  • 2015 May
  • 2015 June
  • 2015 July
  • 2015 August
  • 2015 September
  • 2015 October
  • 2015 November
  • 2015 December
  • 2016 January
  • 2016 February
  • 2016 March
  • 2016 April
  • 2016 May
  • 2016 June
  • 2016 July
  • 2016 August
  • 2016 September
  • 2016 October
  • 2016 November
  • 2016 December
  • 2017 January
  • 2017 February
  • 2017 March
  • 2017 April
  • 2017 May
  • 2017 June
  • 2017 July
  • 2017 August
  • 2017 September
  • 2017 October
  • 2017 November
  • 2017 December
  • 2018 January
  • 2018 February
  • 2018 March
  • 2018 April
  • 2018 May
  • 2018 June
  • 2018 July
  • 2018 August
  • 2018 September
  • 2018 October
  • 2018 November
  • 2018 December
  • 2019 January
  • 2019 February
  • 2019 March
  • 2019 April
  • 2019 May
  • 2019 June
  • 2019 July
  • 2019 August
  • 2019 September
  • 2019 October
  • 2019 November
Silicon Labs
  • About Us
  • In the News
  • Email Newsletter
  • Cookies
  • Contact Us
  • Community
  • Site Feedback
  • Investor Relations
  • Blog
  • Privacy and Terms
  • Corporate Citizenship
Copyright © Silicon Laboratories. All rights reserved.
粤ICP备15107361号-1