Introduction

In this lab, we will learn the basics of provisioning and review the provisioning methods available for the SimpleLink™ Wi-Fi® CC32xx wireless microcontroller and CC31xx wireless network processor. We will build and run the Provisioning example in the SimpleLink CC32xx SDK to demonstrate the use of each provisioning method and how easily it can be embedded into a wireless application.

The lab contain several tasks:

Task 1: Download the Mobile App

Task 2: Build and Load the Example

Task 3: Connect with AP Provisioning

Task 4: Connect with SmartConfig™

At the end of this training, you will

  • Have a high-level understanding of various methods for provisioning
  • Have an understanding of the basic code flow for the provisioning process
  • Be familiar with provisioning related API
  • Be able to use Code Composer Studio (CCS) to compile, build, and execute the SimpleLink Provisioning application on the CC32xx LaunchPad
  • Be able to run the mobile application provided by TI on Android/iOS to enable the CC32xx to connect to a desired Access Point via AP or SmartConfig Provisioning

Prerequisites

Software

Hardware

Instead of using a CC32xx LaunchPad, the following hardware can also be used:

Provisioning Overview

Wi-Fi Provisioning is the process of connecting a Wi-Fi device (station) to a Wi-Fi network (access point). The provisioning process involves loading the station with the network name (often referred to as SSID) and its security credentials. For networks with personal Wi-Fi security, loading security credentials simply involves typing in a pre-defined password. In this lab, we will focus on personal Wi-Fi security networks and how a user can load an IoT Wi-Fi station with the network name and password.

Note

The Wi-Fi security standard distinguishes between personal security (mostly used in homes and businesses) and enterprise security (used in large offices and campuses). Provisioning a station for a network with enterprise security usually involves installing certificates, which are used to verify the integrity of the station and the network by interaction with a security server that is managed by the IT department. This will not be covered in this lab.

Motivation for Built-in Provisioning Features

IoT Wi-Fi stations are typically headless devices, meaning that they lack a user interface (i.e. keyboard, display, etc.) for providing the network information directly to the station. These headless devices need alternate methods to obtain a network name and password from a user. Multiple solutions for provisioning headless devices have been developed to address this challenge. The SimpleLink Wi-Fi CC3x20, CC3x3x Internet-on-a-chip family of solutions offers built-in Wi-Fi provisioning capabilities, which enable end users to easily configure their IoT devices wirelessly from smartphones and tablets.

The SimpleLink Wi-Fi platform supports a variety of provisioning methods to ensure every application has a great user experience:

  • Access Point (AP) - Access Point provisioning is the most common provisioning method. During AP provisioning, an unprovisioned Wi-Fi device temporarily operates as an AP. This allows a device such as a smartphone or tablet to connect to it over Wi-Fi and transmit the network information for the desired network connection.

  • SmartConfig (SC) - SmartConfig is a TI proprietary provisioning method that uses a smartphone or tablet to broadcast network credentials to a TI Wi-Fi device. The unprovisioned device can scan for SmartConfig broadcasts while operating in station mode or access point mode.

  • External Configuration - External configuration allows for alternate provisioning methods to be managed at the host level (such as WAC - an Apple MFi licensed technology).

  • Wireless Protected Set-up (WPS) - Certain APs that support WPS allow Wi-Fi devices to establish a connection during a brief time period, upon pressing a button. This method is not recommended due to its security limitations.

Note

The SimpleLink Wi-Fi CC31xx wireless network processor and CC32xx wireless microcontroller allow multiple provisioning methods to be used simultaneously to provide flexibility in the provisioning process. The following combinations of provisioning methods are supported:

  • AP + SC
  • AP + SC + External Configuration.

General Provisioning Flow Diagram

A general flow diagram of the provisioning process for the SimpleLink Wi-Fi solution can be found below. The device will first enter the configuration state, where it will wait to receive the network's parameters. After receiving the parameters, the device will then attempt to connect to the network and provide feedback to the user upon success.

AP Provisioning Flow

The first step of AP provisioning is for the SimpleLink Wi-Fi solution to start as an AP with a predefined network name. In the configuration stage, a user can connect to the SimpleLink AP with a dedicated provisioning application to configure the wireless network parameters through an HTTP client/server relationship. Once received, the device will store the information in a profile and move to the confirmation stage. In the confirmation stage, the device will connect to the network, obtain an IP address, and then wait to perform a handshake over HTTP with the mobile application. The provisioning process succeeds after the handshake is complete.

SmartConfig Provisioning Flow

SmartConfig is a TI proprietary provisioning method that uses a mobile application to broadcast network credentials to an unprovisioned device. During SmartConfig, the SimpleLink Wi-Fi solution can be in either STA or AP mode while scanning for SmartConfig data broadcasts. SmartConfig allows a user to broadcast the network parameters of the network that the mobile device is currently connected to. This can save time by eliminating the need to switch the mobile device's Wi-Fi connection to a network created by the SimpleLink Wi-Fi solution. The complete flow of successful SmartConfig Provisioning can be found below.

Note

The SmartConfig provisioning mode does not support wireless access points that are MIMO devices.

External Configuration: WAC Provisioning Flow

The external configuration flow is different from AP and SmartConfig provisioning because it is managed at the host level instead of being managed by the SimpleLink Wi-Fi Network Processor. When the host identifies that a user has started the provisioning process through external configuration, it must order the networking subsystem to stop the internal provisioning process. Once stopped, the host can continue with its own provisioning process. One specific type of external configuration is WAC. This is an MFi licensed technology that is designed for MFi accessories. Detailed information about WAC is available to Apple MFi Development and Manufacturing licensees. The overall flow of WAC provisioning can be found below.

Host Driver Provisioning API and Events

API

The host driver API command used to initiate the provisioning process is sl_WlanProvisioning.

This API command has the following key parameters:

  • ProvisioningCmd: WLAN mode to start CC3xxx device
  • RequestedRoleAfterSuccess: Desired role (AP or STA) that the device should switch to after provisioning
  • InactivityTimeoutSec: Time period the system waits before automatically stopping the provisioning process
  • pSmartConfigKey: SmartConfig key (public key for SmartConfig process)
  • Flags - Defines whether to use external confirmation or not

sl_WlanProvisioning returns a STATUS_OK notification upon successful completion, or an error code otherwise.

Note

For complete documentation on the sl_WlanProvisioning API function, refer to the host driver documentation in the SDK (simplelink_cc32xx_sdk_X_XX_XX_XX/docs/wifi_host_driver_api/index.html)

Events

The Provisioning Status Event is used to provide the application with feedback on the provisioning process and state.

There are the following parameters for the Provisioning Status Event:

  • Status: A status can be one of many options related to the success or error with provisioning
  • Role: The active role (AP/STA) after the provisioning process ended
  • WlanStatus: If the active role is STA, this parameter will show the WLAN connection status after provisioning has ended
  • SsidLen: If WlanStatus is connected, this parameter will provide the length of the SSID for the AP connection
  • Ssid: If WlanStatus is connected, this parameter will give the connection SSID

Additionally, as part of the provisioning process the following events may occur:

  1. Provisioning Profile-Added Event - Occurs when a profile is successfully added
  2. Reset Request Event - The device requires a restart

More detail regarding the API and Events can be found in the Provisioning Application Note for the CC3x20 and CC3x3x.

Task 1: Download the Mobile App

The first step in this lab is to download the SimpleLink Wi-Fi Starter Pro Mobile application for your Android or iOS device. The SimpleLink Wi-Fi Starter Pro application will be used to communicate network information to SimpleLink Wi-Fi family devices and to detect SimpleLink Wi-Fi family devices connected to the network.

https://www.ti.com/tool/wifistarterpro

Task 2: Build and Load the Example

  1. In CCS, go to the menu Project → Import CCS Projects...
  2. Follow the appropriate step below to import the provisioning example depending on which device you are using.

    • Be sure you select your desired project "flavor" (CC3235S-LAUNCHXL, CC3220SF-LAUNCHXL, TI-RTOS, Free-RTOS, CCS, GCC, etc.).
    • We will be using the CC3220 TI-RTOS CCS example for this lab: provisioning_CC3220SF_LAUNCHXL_tirtos_ccs

      Browse to the SimpleLink CC32XX SDK on your local hard drive and select the provisioning example: simplelink_cc32xx_sdk_x_xx_xx_xx\examples\rtos\<LaunchPad>\demos\provisioning\<RTOS>\ccs

      Browse to the SimpleLink SDK Wi-Fi Plugin on your local hard drive and select the provisioning example: simplelink_sdk_wifi_plugin_x_xx_xx_xx\examples\rtos\<supported host>\demos\provisioning

  3. Plug in your LaunchPad, build the project, and flash the provisioning application.

    • If you are using the CC32xx LaunchPad, plug in your LaunchPad before building the project and then select the Flash button from the top menu. This will launch the SysConfig ImageCreator tool inside CCS to flash the device.
    • If you are using the CC31xx, plug in your host LaunchPad and select the Debug button to load the application.
  4. Open up a terminal on your device's COM port. We want to use the XSD110 Class Application/User UART port with the following parameters:

    UART Configuration
    Baud rate: 115200
    Data: 8 bit
    Parity: None
    Stop: 1 bit
    Flow control: None

Task 3: Connect with AP Provisioning

We will first connect the SimpleLink Wi-Fi device to the network using AP Provisioning.

Start the Provisioning Application

Once the program is loaded on the device and the terminal is connected, press the reset button on the LaunchPad to run the application.

If successful, the terminal emulation program should output the text below. This indicates that the device has entered the provisioning state for the mode shown (in this case mode = 2, which is AP + SmartConfig).

Configure the Mobile App for AP Provisioning

Now that the device has started and is ready to be provisioned, open the SimpleLink Wi-Fi Starter Pro App on your iOS or Android device. After installing the mobile application, AP Provisioning should be enabled by default. To make sure that AP Provisioning is enabled, follow these steps:

  1. Select the Settings tab in the SimpleLink Wi-Fi Starter Pro App
  2. Make sure Enable Smart Config is OFF
  3. Select the Provisioning tab to return to the Configuration Page

Your settings should look as follows:

Once you are back on the Configuration Page, select Device to Configure and choose your device. You will be able to identify your device based on the default SSID, which is mysimplelink-xxxxxx (where xxxxxx is the last 6 characters of the device MAC address). Optionally, you can also give your device a name to use when it joins the network.

Note

On iOS, a message will prompt you to connect to the desired AP using the Settings App. Navigate to the Settings App, choose your device from the network list, then re-open the SimpleLink Wi-Fi Starter Pro App to continue.

Enter the Network Credentials

Fill-in the network credentials for the 802.11 b/g/n wireless AP you want to connect your device to by selecting the SSID in the Wi-Fi Network field and entering the Network Password.

Once the credentials are entered, press START CONFIGURATION to begin AP Provisioning. You can verify that the provisioning process succeeded by checking the terminal output or the mobile application notification.

The terminal output will show that the profile is added, that the device connected to the network, and that an IP was acquired by the device when provisioning ends successfully.

Note

Provisioning results in network credentials being saved to the serial flash and stored as a network profile. A device reset will allow the SimpleLink Wi-Fi device to attempt to reconnect to any stored profiles before starting the provisioning process if the Auto Connect policy is enabled.

Task 4: Connect with SmartConfig

Now we will repeat the provisioning process with SmartConfig. This will require removing any existing profiles on the serial flash so that the SimpleLink Wi-Fi device does not automatically connect to a network and skip the provisioning process.

Restart the Provisioning Application

After successful AP Provisioning, you can reset the SimpleLink Wi-Fi solution by performing the following actions:

  • Disconnect the terminal application
  • Plugin in your CC32xx LaunchPad and select the Flash button to format the serial flash contents and re-load the application/user files. (If you are using CC31xx, you will have to program a new image using the UniFlash ImageCreator tool.)
  • Reconnect the terminal application and restart the device to run the application again

Enable SmartConfig in the Mobile App

Open the SimpleLink Wi-Fi Starter Pro App on your iOS or Android device and select the Settings tab. Enable SmartConfig by setting Enable Smart Config to ON, then return to the Provisioning tab.

Enter the Network Password and Start SmartConfig

Provide the network credentials for the 802.11 b/g/n (non-MIMO) wireless AP by selecting your SSID from the Network Name field and entering the password in the Network Password field. Then press the Start Configuration button to begin SmartConfig. You can verify successful provisioning by checking the terminal output or the mobile application notification.

Note

The Device to Configure field is not displayed on the Configuration page since the CC3xxx device will be automatically detected and receive the SmartConfig broadcast.

References

To learn more about the provisioning process or to get additional assistance during development, please refer to the following resources:

Technical support

For any questions you might have, please search on the Wi-Fi E2E Forum

Creative Commons License
This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.