Table of Contents
Introduction
The BLE Wi-Fi Provisioning example is an example that is designed to showcase the provisioning of Wi-Fi parameters (SSID, network key, etc.) over a BLE connection in a secure manner to a CC3220 host microcontroller. Wi-Fi provisioning over BLE provide various tangible benefits such as eliminating the need to explicitly connect to a shared network and simplified confirmation processes.
It is important to note that while the CC3220 (either CC3220S or CC3220SF) is used for this code example, the host microcontroller is used as it would be for any other code example. All of the logic and BLE services/characteristics are handled on the CC3220 microcontroller and the CC26xx device is used in SNP mode as a “black box radio”. Once the SNP image is flashed onto the CC26xx device (see programming the SNP image section in the main user’s guide), no explicit programming on the CC26xx device needs to take place.
This example also allows the user to switch the provisioning mode from BLE provisioning to Access Point/SmartConfig (AP/SC) provisioning, as well as enabling the user to perform a SBL firmware update of the firmware running on the CC26xx SNP device.
Hardware Prerequisites
The BLE Wi-Fi Provisioning code example uses the standard CC26xx BLE radio (either a CC2650 LaunchPad or CC2640R2 BoosterPack) connected to either a CC3220S LaunchPad or CC3220SF Launchad. Either LaunchPad configuration will have identical source code (with the exception of the board/hardware configuration files).
Note that because of pin assignments and the existence of “do not populate pins” on the CC3220S and CC3220SF LaunchPads, a couple of minor rerouting of signals must be done in order to facilitate the pre-build CC26xx SNP image.
The following pins must be connected in order for the CC3220 to be able to successfully communicate with the CC26xx device. Pin numbers are given as reference to the CC32XX LaunchPad (and not the CC26xx SNP):
- P58 connects to P61
- P07 connects to P18
An example of these connections can be seen in the picture below:
Alternate Pin Mapping
Alternate SNP images are provided which remap the MRDY and SRDY signals of the CC26xx to different pins on the CC26xx LaunchPad or BoosterPack in order to simplify the hardware setup required when working with the CC3220 as the host. The alternate SNP images can be found in the source/ti/snp/cc3220_custom folder of the plugin installation. When working with the alternate SNP images, the MRDY and SRDY signals (from the perspective of the CC26xx) are moved to the following LaunchPad/BoosterPack headers:
- J1-5 configured as SRDY
- J1-8 configured as MRDY
In order to support the new locations of MRDY and SRDY from the host side, the GPIO pin configuration in the CC3220x_LAUNCHXL.c file of the host application must be updated. The MRDY and SRDY definitions in gpioPinConfigs[] must be updated as follows:
- MRDY moved to GPIOCC32XX_GPIO_07
- SRDY moved to GPIOCC32XX_GPIO_06
Once updated, gpioPinConfigs[] in CC3220x_LAUNCHXL.c should look as follows:
The actual digital IOs that the headers correspond to are different on the CC2640R2 LaunchPad and CC2650 BoosterPack. However, the following CC3220 pin must still be rerouted when working with the alternate SNP images. Pin numbers are given as a reference to the CC32XX LaunchPad:
- P07 connects to P18
An example of the connection for the alternate SNP image can be found below:
Software Prerequisites
This code example has been tested with IAR Embeded Workbench 8.20, Code Composer Studio v8.0, and gcc-arm-none-eabi-7-2017-q4-major. For more information on how to import this project into your IDE workspace and build/run, please refer to the main user’s guide.
Service/Profile Table
| Purpose | UUID | Format | Properties | Profile Source |
|---|---|---|---|---|
| Provisioning Status | FFF2 | Integer | Read/Write | ble_wifi_provision_profile.c |
| Provisioning Notify | FFF3 | Integer | Read/Write | ble_wifi_provision_profile.c |
| SSID | FFF4 | String | Encrypted Read/Encrypted Write | ble_wifi_provision_profile.c |
| Security Key | FFF5 | String | Encrypted Read/Encrypted Write | ble_wifi_provision_profile.c |
| Device Name | FFF6 | String | Read/Write | ble_wifi_provision_profile.c |
| Provisioning Start | FFF7 | Integer | Read/Write | ble_wifi_provision_profile.c |
Provisioning Process
The BLE provisioning process implemented in this example provides a method for programmers to fully configure and provision their CC3220 Wi-Fi device over BLE, which are described in the steps below:
- Provisioner (mobile phone) connects to advertised BLE service
- Passkey is displayed to user, which is entered into the provisioner to establish secure pairing
- SSID, Security Key, and Device Name are written to corresponding BLE characteristics
- Provisioning is initiated by writing 0x01 to “Provisioning Start” characteristic
- CC32xx device disconnects from BLE, attempts to connect to provisioned profile over Wi-Fi
- Once IP is obtained the device pings the resolved gateway to verify connectivity
- After successful ping the Wi-Fi radio disconnects and BLE is again advertised
- Provisioner reconnects to device over BLE and reads “Provisioning Status” characteristic
- If the status signifies success the provisioner writes 0x02 to the “Provisioning Start” characteristic to signify confirmation
- If the status signifies failure the provisioner reports the failure to the user and disconnects.
- After successful confirmation the device disconnects from BLE and reconnects to the provisioned network
- Once connected the device will go into a “ping loop” where gateway is repeatedly pinged
A graphical representation of the entire provisioning process can be seen in the flow chart below:
When a device has not been provisioned (or the device cannot connect with any of the provisioned profiles) it will enter a “provision loop” mode. In this mode the device will cycle infinitely between the following two steps:
- Advertising over BLE and waiting for a connection
- Trying to connect to any provisioned profiles.
The reasoning for this loop is to allow the opportunity for the device to connect to a provisioned network that might have come within range from device startup. The BLE will disconnect and try to connect to a provisioned network every thirty seconds.
As seen, if at any point during the provisioning process the device runs into an error state (such as gateway ping failure or failure to obtain an IP) the provisioning process bails out and the device returns to its “provisioning loop” stage.
Confirmation Status
As described in step eight of the provisioning process from the section above, the BLE central device (mobile phone) must reconnect to the CC32xx after initially writing the provisioning information to perform a confirmation. During this step the value of the “Provision Status” characteristic is read.
This characteristics can have one of the following values:
- BLE_WIFI_PROV_GOOD - 0x00 - Provisioning completed without error
- BLE_WIFI_PROV_FAIL_IP - 0xFC - Could not obtain IP from provided provisioning information
- BLE_WIFI_PROV_FAIL_CON - 0xFD - Could not connect to provisioned network
- BLE_WIFI_PROV_FAIL_PING - 0xFE - Could not ping gateway after connecting to provisioned network
- BLE_WIFI_PROV_TIMEOUT - 0xFF - Timeout occurred
Re-Provisioning Device
Once the device has been successfully provisioned the device will enter a “ping loop” mode where the device will repeatedly ping the resolved gateway and report the result over UART terminal:
If at any point during the ping loop the user would like to re-provision the device the SW3 button should be quick pressed (if held longer than five seconds a SBL update will be initialized).
This will force the ping loop to start, the Wi-Fi to disconnect, and the BLE radio to start advertising to begin provisioning. If a timeout happens after a re-provision event has been initialized the Wi-Fi thread will connect back to the previously provisioned network and the ping loop will continue.
Coexistence of BLE/Wi-Fi Radio
In order to foster low noise across different wireless radios this application implements a form of coexistence between the BLE radio and the Wi-Fi radio. This means that whenever the Wi-Fi radio is active the BLE radio is disabled (and vice-versa). To signify when the BLE radio is active the LED attached to D10 is illuminated. When the BLE radio is inactive the LED attached to D10 is turned off.
Switching Provisioning Modes
This example also supports the AP/SC provisioning mode. To enable this mode, SW3 button should be held for at least three seconds (if held longer than five seconds a SBL update will be initialized). This will switch from BLE provisioning to AP/SC provisioning, and vice-versa. After the device is connected to a provisioner, the provisioning mode cannot be switched until the device is disconnected.
For an in-depth explanation of the AP and SC provisioning processes and how to connect to a network with this mode, please visit the SimpleLink Academy Wi-Fi Provisioning Lab.
Anatomy of the Code
The code in this code example is segregated into three different threads:
- bleThread
- wifiThread
- apThread
The bleThread and the wifiThread are active when BLE provisioning is being used.
The bleThread is responsible for managing the communication between the configured peripheral device (the CC32XX) and the central device connecting and configuring each of the configured BLE characteristics. Furthermore, the bleThread is responsible for initiating and performing the SBL firmware update of the firmware running on the CC26xx SNP device.
The following image shows the provisioning state machine that is implemented in the bleThread. The events that cause the transitions between states are shown.
The wifiThread is responsible for managing all aspects of the Wi-Fi connection the the CC32XX network processor. This involves communicating and configuring the Wi-Fi on startup, persisting provisioning parameters, and managing confirmation logic. Once a device is successfully provisioned the “ping loop” which perpetually pings the gateway is also setup in the ping loop itself.
The following image shows the provisioning state machine that is implemented in the wifiThread. The events or conditions that cause the transitions between states are shown.
The apThread is active when AP/SC provisioning is being used. This thread is responsible for configuring the device to run AP provisioning and SmartConfig provisioning simultaneously. Once the device is successfully provisioned, feedback is displayed to the user on the terminal window and the provisioning process ends.
The following image shows the provisioning state machine that is implemented in the apThread. The events or conditions that cause the transitions between states are shown.
Warning Codes
In the case that the state machine receives an unexpected event, a message will be displayed to the terminal window stating which thread received the event, and the event number that was received. The possible events that can be received are listed in the tables below. These events can also be found in ble_provisioning.h and ap_provisioning.h.
| bleThread Event Name | Value (Decimal) |
|---|---|
| BLE_NONE | 1 |
| BLE_EVT_PUI | 2 |
| BLE_EVT_ADV_ENB | 4 |
| BLE_EVT_ADV_END | 8 |
| BLE_EVT_CONN_EST | 16 |
| BLE_EVT_CONN_TERM | 32 |
| BLE_EVT_BUTTON_RESET | 64 |
| BLE_EVT_START_ADV | 128 |
| BLE_EVT_START_PROVISION | 512 |
| BLE_EVT_PROV_COMPLETE | 1024 |
| BLE_EVT_START_PAIR | 1536 |
| BLE_EVT_PAIRED | 1792 |
| BLE_EVT_WRONG_PASSKEY | 1872 |
| BLE_EVT_BSL_BUTTON | 2048 |
| BLE_EVT_SWITCH_PROV | 2128 |
| BLE_EVT_ERROR | 2147483648 |
| wifiThread Event Name | Value (Decimal) |
|---|---|
| WIFI_NONE | 1 |
| WIFI_EVT_BLE_INITI | 2 |
| WIFI_EVT_RESET | 4 |
| WIFI_EVT_BLE_PROV_START | 8 |
| WIFI_EVT_SL_STARTED | 16 |
| WIFI_EVT_SL_CONNECTED | 32 |
| WIFI_EVT_BLE_PROV_COMPLETE | 64 |
| WIFI_EVT_REPROVISION | 128 |
| WIFI_EVT_BLE_TIME | 512 |
| WIFI_EVT_CONF_FAIL | 1024 |
| WIFI_EVT_ERROR | 2147483648 |
| apThread Event Name | Value (Decimal) |
|---|---|
| PrvnEvent_Triggered | 0 |
| PrvnEvent_Started | 1 |
| PrvnEvent_StartFailed | 2 |
| PrvnEvent_ConfirmationSuccess | 3 |
| PrvnEvent_ConfirmationFailed | 4 |
| PrvnEvent_Stopped | 5 |
| PrvnEvent_WaitForConn | 6 |
| PrvnEvent_Timeout | 7 |
| PrvnEvent_Error | 8 |
| PrvnEvent_Max | 9 |
BLE Mobile Provisioning
SimpleLink SDK Explorer
SimpleLink SDK Explorer is an open source/cross-SimpleLink mobile application that is used to configure/showcase many different components of SimpleLink software collateral. One of the features added to SimpleLink SDK Explorer is the ability to provision a CC32xx device’s Wi-Fi configuration using BLE.
SimpleLink SDK Explorer is available publicly from the Apple AppStore and from the Google Play store at the following URLs:
Apple AppStore: https://itunes.apple.com/us/app/simplelink-sdk-explorer/id1237329921?ls=1&mt=8
Google Play Store: https://play.google.com/store/apps/details?id=com.ti.simplelinksdkexplorer
Once the application is opened up ensure that the Current SimpleLink SDK selected is the SimpleLink C3x20 Wi-Fi SDKs option. If not press the SDK button to select the correct SDK from the list.
Once SimpleLink C3x20 Wi-Fi SDKs is selected, the Provisioning menu option becomes available on the main screen. Select Provisioning to move to the next screen.
On this screen a list of provisioning options are displayed. Select BLE Provisioning.
The next screen displays a description of the BLE Provisioning scheme as well as some background on the provisioning method. Press Start to begin the setup.
The next screen automatically starts to scan for BLE peripherals in the vicinity that contain the “BLE Provisioning” service UUID (0xFFF0). At this point run your code example and make sure that BLE advertisement is active (see the re-provisioning section if your device is already provisioned). Select your device from the list to connect to it.
If this is your first time connecting to the BLE device, the mobile application will ask to pair with the device. To complete pairing, a passkey will appear on the terminal window. If you do not have your terminal window set up, please refer to the main user’s guide for help. Enter this passkey into your mobile application. If the correct passkey is entered, pairing is complete and the device is now bonded, so if the device is disconnected and then reconnects, the mobile phone will remember the device and a passkey does not need to be entered. Bonded devices can be forgotten through the phone’s Bluetooth settings.
On the next screen you will be prompted with the Wi-Fi network parameters of the router/access point that you want to provision over BLE to you CC32XX device. Fill in the relevant information. Note that the security key type (WPA vs. WEP) is not required. When dealing with secured networks WPA authentication will be attempted first and WEP authentication will occur only if WPA failed. If the network is open leave the security key field blank. Once all of the relevant information is filled out touch the Provision button to begin Wi-Fi provisioning. The next screen will walk you through all of the steps for provisioning and report the status back as pass or fail.
Note that provisioning status is also outputted to the terminal window.
At any point if provisioning needs to be canceled the back button can be pressed. The Complete button is only enabled once a successful provision has taken place. Once provisioning has succeeded, press the Complete button.
This will return the application back to the main menu. Press the Provisioned Devices menu item to display all previously provisioned devices.
From here you can select your device to see the log and provisioned information.
SimpleLink Starter Pro
BLE Provisioning
In addition the the SimpleLink SDK Explorer, the SimpleLink Starter Pro mobile application that is released with the CC32XX SDKs also supports BLE provisioning. This applications supports both Android and iOS and supports advanced features such as SmartConfig, access point provisioning, and BLE provisioning. Legacy versions of iOS are supported and the program (for iOS) is written entirely in ObjectiveC. To download and use SimpleLink SDK Starter Pro please refer to the link below:
https://www.ti.com/tool/wifistarterpro
Note the screenshots below show iOS, however the interface/steps are identical for Android.
Open SimpleLink Starter Pro. From the main screen select BLE Provisioning from the tab bar on the bottom.
Touch on the BLE Devices drop down and select the device that is being advertised.
If this is your first time connecting to the BLE device, the mobile application will ask to pair with the device. To complete pairing, a passkey will appear on the terminal window. If you do not have your terminal window set up, please refer to the main user’s guide for help. Enter this passkey into your mobile application. If the correct passkey is entered, pairing is complete and the device is now bonded, so if the device is disconnected and then reconnects, the mobile phone will remember the device and a passkey does not need to be entered. Bonded devices can be forgotten through the phone’s Bluetooth settings.
Once the device is selected, fill out the relevant information about your network setup.
After all of the information is populated, press Start Configuration to start the configuration process and provision the device.
AP/SC Provisioning
The SimpleLink Starter Pro mobile application also supports AP/SC provisioning. These steps are listed in detail in the SimpleLink Academy Wi-Fi Provisioning Lab.
Generic Mobile Application
In addition to the specialized mobile applications that TI provide, generic mobile applications can also be used to directly provision the CC3220 device at a more low level. Any BLE application can be used, but TI recommends:
When using these applications the following flow can be used to provision the device in a simple barebone manner. These screenshots show how to provision the device with LightBlue for iOS, however other BLE applications will have a similar flow.
Connect to advertised BLE device (device name as “CC32XX WiFi” byte default)
If this is your first time connecting to the BLE device, the mobile application will ask to pair with the device. To complete pairing, a passkey will appear on the terminal window. If you do not have your terminal window set up, please refer to the main user’s guide for help. Enter this passkey into your mobile application. If the correct passkey is entered, pairing is complete and the device is now bonded, so if the device is disconnected and then reconnects, the mobile phone will remember the device and a passkey does not need to be entered. Bonded devices can be forgotten through the phone’s Bluetooth settings.
Write SSID (required), security key (optional), and device name (optional)
Write 0x01 to “Provision Start” characteristic
Wait for IP to be acquired (this will be displayed on the terminal output). Once acquired, reconnect to the device and read the “Provision Status” register. Verify that it is 0x00 (provision success):
Write 0x02 to the “Provision Start” register and the device will disconnect. The device is now provisioned. In the terminal window the ping loop will display.
SBL Update
Updating the firmware on the CC26xx device uses the SBL libraries to invoke the CC26xx’s bootloader and transfer the new firmware over serial. For LCD BoosterPack Text, the method to trigger this invocation is to hold down the SW3 on the LaunchPad for a duration of at least five seconds. Note that in order to trigger the firmware update, no active BLE device can be connected. Once SW3 is held down for five seconds, a message will be displayed on the UART terminal and LED2 on the LaunchPad will illuminate to signal the BSL start.
The image for the SNP resides on the CC32XX device’s external flash must be explicitly programmed by the user using the Uniflash programming tool. When the SBL is invoked, the device will disconnect from BLE and Wi-Fi and enter in “SBL” mode. The CC32XX device will then open the file located at /cc26xx/snp_image.bin and attempt to program the CC26xx device using the CC26xx’s external UART bootloader. The CC26xx SBL interface is documented in the CC26xx Bootloader Interface document.
Note that the path to the SNP image on the CC3220’s external flash can be programmed by changing the SNP_FIRMWARE_PATH variable in sbl_wifi_snp_update.h.
The console screen will print the status of the firmware update as well as signal when the update has finished. At the end of the update the status of the update will be printed over the serial port and the CC32xx will reboot itself:
Use of an External LCD
It is entirely possible to connect an external LCD BoosterPack such as the 430BOOST-SHARP96 or BOOSTXL-K350QVG-S1 to the hardware configuration. The main purpose of having a dedicated LCD would be to have a mechanism to display the pairing/bonding pass code during the connection process without explicitly requiring the user to hook their LaunchPad up to a UART terminal.
When using an external LCD one consideration is that there will likely be pin conflicts with the CC3220 LaunchPad and the CC26XX SNP radio. Since many of the pins on the LCD BoosterPacks conflict with those used for the CC3220<->CC32XX communication interface there will likely be a physical modification of the signals on the LCD BoosterPack that needs to occur. In actual design this will not be an issue as a custom layout/PCB will be made, but for evaluation be mindful that the signal requirements of the LCD BoosterPack will need to be made compatible with the CC32XX<->CC26XX communication.
Once the correct hardware modifications are made, displaying the passcode for use in the pairing process can be easily done using the Graphics Library that is included in the CC3220 SDK. Specifically, the Display to LCD example of the platform SDK will show the required software hooks necessary to display a text string to an external LCD using the Display driver.