SimpleLink SDK Wi-Fi Plugin Users Guide

Table of Contents

Introduction

The SimpleLink™ SDK Wi-Fi Plugin is a companion software package that enables the use of a Wi-Fi radio on any standard MSP432 platform including the MSP432P401, MSP432P4111, and MSP432E401 families, as well as on the CC26X2R platform, including the CC2642R and CC2652R family of devices. By having the ability to seamlessly and modularly add Wi-Fi functionality to an embedded system, a programmer can enable their embedded device to become a gateway to various IOT infrastructures.

This plugin leverages the use of the Wi-Fi host driver that is standard within the SimpleLink CC32xx SDK. Through a simple porting layer interaction with the network processor (NWP) is abstracted out to enable code compatibility between a one chip CC32xx solution and a two chip host microcontroller + CC31xx solution. A SPI connection is used by the host microcontroller to manipulate and configure all aspects of the Wi-Fi network processor.

SimpleLink SDK Plugins are designed to work in tandem to the microprocessor specific SDK. This plugin is designed to work alongside both the the SimpleLink MSP432P4 SDK, SimpleLink MSP432E4 SDK, and SimpleLink CC26X2 SDK. It relies heavily on several core elements within these SDKs. Without a prior installation of the SimpleLink SDK, the SimpleLink SDK Wi-Fi Plugin will not work. While testing of this software package was performed on release 2.30.00.xx of the SimpleLink SDKs, it is likely that it will also work with newer and older versions.

Plugin Architecture / General Overview

All of the code examples written for this software package leverage a combination of various host controller LaunchPads. The supported host microcontroller LaunchPad configurations are listed below:

The network processors that can be used in this plugin as the main vessel of communication are listed below:

A BoosterPack is used in conjunction with the host LaunchPad to provide the benefits of a full capability host microcontroller coupled with the modularity of a separate network processor for Wi-Fi communication.

The communication between the host and the C31xx has been abstracted away using a simple porting layer that sits above the Wi-Fi host driver on the host microcontroller. While the underlying host driver is identical to what you would see in the CC32xx SDK, the porting layer translate all of the high level Wi-Fi calls to a physical SPI layer that communicates with the CC31xx as a black box solution. This allows for the programmer to call SimpleLink Wi-Fi APIs (such as sl_Start, sl_Fs, etc.) calls as they would on a CC3220. A brief block diagram of the various software connections and driver interworkings can be seen below:

WiFi Layers

The physical interface between the host and the CC31xx is a simple SPI connection with two interrupt lines for synchronization and power management added. The physical hardware specification and interworkings are explained in detail in the CC3120 BoosterPack User’s Guide. It is important to note that while the default pin configurations used in the example projects in this plugin package are mapped to the LaunchPad pins, they are fully reconfigurable to match the end application requirements. Reconfiguring the pin configurations and SPI driver parameters is explained in detail in the Customizing Parameters section of this document.

Folder Structure

The folder structure for the SimpleLink SDK Wi-Fi Plugin is made to compliment the standard folder structure that the platform SDK adheres to. From the root directory, the following folders are available:

The source/ folder contains the code that is likely to end up seeing its way into an end application. Within there is the following folders:

The ti/ folder contains the bulk to the TI provided collateral to interact with and control the CC31xx Wi-Fi Device. This folder is structured as follows:

The entirety of code provided by TI is provided as an open source BSD license and generally include both prebuilt static libraries for each supported IDE as well as full source code. The ota folder does not contain prebuilt libraries as much of the ota implementation is dependent on end user requirements and parameters.

The third_party/ folder contains the mbedtls library that is used by the MSP432 for SHA256 generation in lieu of a hardware SHA256 module (that the CC3220 contains).

Back in the root directory, the tools/ folder consists of the following two folders:

The cc31xx_tools/ directory contains various collateral needed to enable functionality of various functions. This includes the following subdirectories:

Updating the CC31xx (Service Pack and User Files)

It will become necessary for the user to update both the user files stored on the CC31xx’s flash storage and the service pack running on the CC31xx itself. User files that need to be updated can range from specific application-centric files required for operation (such as html pages) to updated certificates and trusted root certificate files.

The service pack updates are done on a regular basis to patch fixes for the services running on the NWP as well as to ensure that the NWP is running with the most up-to-date security patches. It is the same process to program the CC3120 and the CC3135, with the only differences being that the user needs to ensure that the correct service pack and Device Type are chosen for the specific device.

The CC3120 and the CC3135 use different servicepacks, but the same user files.

The service pack for the CC3120 is located in the plugin in tools/cc31xx_tools/servicepack-cc3x20. This is identical to the service pack distributed in the CC32xx SDK in tools/cc32xx_tools/servicepack-cc3x20.

The service pack for the CC3135 is located in the plugin in tools/cc31xx_tools/servicepack-cc3x35. This is identical to the service pack distributed in the CC32xx SDK in tools/cc32xx_tools/servicepack-cc3x35.

The sections below describe not only how to update the service pack and user files running on the CC31xx via a direct USB connection, but also how to use over-the-air updates (OTA) to dynamically load a customized update package via the device’s Wi-Fi connection.

Uniflash / CC31XXEMU-BOOST

The most common and obvious way to update the user files on in CC31xx is to use the C31XXEMUBOOT BoosterPack along with Uniflash’s Image Creator. The C31XXEMUBOOST is a specialized BoosterPack that connects on top of the CC31xx BoosterPack to program and update the user files stored on the CC31xx’s flash memory. Uniflash has a specific utility (called Image Creator) that is used to communicate with the CC31XXEMU boost and create/manage software packages.

To get started first download the latest Uniflash package from the the link below:

https://processors.wiki.ti.com/index.php/Category:CCS_UniFlash

Next, connect the CC31XXEMUBOOST to the CC31xx BoosterPack as seen below while being careful not to mount the pins upside down.

WiFi Layers

Note that while connected to the CC31XXEMUBOOST, the normal programming of the MSP432 LaunchPad will not work correctly. Also note that it is not required for the CC31xx to be connected to the MSP432 when programming with the CC31XXEMUBOOST.

Plug the USB cable from your computer into the right USB port of the CC31XXEMUBOOST (as seen above).

Once connected, open up the UniFlash application. In the device list, scroll down (to the very bottom) and select CC31xx/CC32xx.

WiFi Layers

Once selected, click Start Image Creator to start the image creator application. This will start the SimpleLink Wi-Fi Image Creator. On this screen you can manage various project settings as well as program external images. To get started, clock on the New Project button as seen below.

WiFi Layers

On the next screen fill out a project name of your choice. Make sure that you choose the BoosterPack that you are using (CC3120 or CC3135) as the Device Type and make sure that the Device Mode is set to Develop. Develop mode allows the user to open up the filesystem and make changes via Uniflash during the development phase. When you wish to secure your device and program it for production the Production mode should be used.

WiFi Layers

On the next screen you will see the new project page as it exists for Development Mode. In Development Mode you can change and manipulate all aspects of the CC31xx device. At a minimum when creating an image to flash on the CC31xx, it is recommended to start with specifying a service pack. The service pack provides various patches and security fixes for the NWP image running on the CC31xx. To specify a service pack select the Service Pack menu item on the left.

WiFi Layers

On the next page click browse next to the file name field and navigate to the service pack release that is included with the SimpleLink SDK Wi-Fi plugin release. The file name generally starts with sp_ and ends with .bin.

Important Note: Ensure that you are using the correct service pack for your device.

The service pack for the CC3120 can be found at: /tools/cc31xx_tools/servicepack-cc3x20. The service pack for the CC3135 is located in the plugin in tools/cc31xx_tools/servicepack-cc3x35.

WiFi Layers

Note that when you select this file it persists within Uniflash- meaning if you save the project and reopen it the service pack file will exist within Uniflash’s internal memory. The next portion of the project that is common to update is the user files section. The user files are all files that are user accessible that are stored on the flash memory of the CC31xx. These can include anything from application files such as html pages to certificates used for validation and security. To manage the user files contained within your image select the User Files menu item from the left.

On the next screen the file manager view will be displayed. Since this is a new project there are no files currently populated. Let’s add some files. Click on the small file icon located on the top of the file view.

WiFi Layers

A common file to add to the user files is a root ca certificate. This certificate is responsible for securing a client connection and provides a level of security that ensures that users are legitimately connected to a trusted source. As part of the plugin release a “dummy” certificate is provided. To add this certificate to your project navigate to the /tools/cc31xx_tools/certificate-playground folder and select the dummy-trusted-ca-cert file to add to the project. On the file options window select Failsafe (this adds a certain level of redundancy for safety) and select Write. As stated before, the same user files can be used between the CC3120 and the CC3135.

WiFi Layers

As with the service pack, once a file is added to the Uniflash project it will persist in the Uniflash project (even if the file is deleted from the file system on your PC). Now it is time to program your CC31xx device. Note that when programming through Uniflash all files that are not included in the user files are erased and the new files are persisted. The exceptions are system files (such as the factory reset image). First connect to the device using the Connect button on the side.

WiFi Layers

Once connected various information such as the MAC address and hardware version is displayed on the right. To program the image, first select the Generate Image icon on the right.

WiFi Layers

On the next screen select the Program Image (Create & Program).

This will proceed to program the new image (both the service pack and the user file that you added) to the flash memory on the CC31xx BoosterPack.

WiFi Layers

Once finished, click Close and then reconnect to the device using the Connect button from the previous step. After connected, select the User File Browser icon on the right next to the Disconnect button.

WiFi Layers

This will probe the CC31xx and display all files that currently exist on the flash file system. Other than the required system files, you will notice that the service pack file exists as sys/servicepack.ucf and that the dummy-root-ca-cert file exists in the root directory as programmed.

WiFi Layers

Over-the-Air Updates

The second way to update user files on the CC31xx is to use an over-the-air (OTA) update scheme. OTA update is currently only supported on the MSP432P4 (MSP432P401R and MSP432P4111) family. This method uses the device’s active Wi-Fi connection to dynamically download a prebuilt package and update relevant files on the network processor. This method also has the added benefit of being able to update the firmware image running on the MSP432 itself.

Two different code examples are provided that showcase the various methods of updating the firmware and user files over-the-air:

Cloud OTA – Update the firmware of the MSP432 and the service pack/user files of the CC31xx using cloud providers such as GitHub and DropBox

Local OTA – Update the firmware of the MSP432 and the service pack/user files of the CC31xx using a local HTTP server web interface

Both of these examples rely on having an image created in a specific format in order to operate correctly. These images are created using the Uniflash tool. It is important that the latest version of Uniflash is used (post 4.2.1) as the newer versions of Uniflash enable secure over-the-air firmware updates via SHA256 hash calculation.

When creating a Uniflash OTA image the firmware image for the MSP432 must be placed at /sys/hostmcuimg.bin of the CC31xx’s file system. Furthermore, the file must be marked with the Failsafe option in Uniflash during image creation. It is imperative to also have the OTA certificate file programmed in the root directory of the OTA image. This certificate is used for SHA256 validation and verification of the programmed image and the firmware update will fail in the absence of this certificate. A dummy certificate for demonstration purposes is located at /tools/cc31xx_tools/ota-example-cert/dummy_ota_vendor_cert.der

In an OTA enabled application for MSP432 (either MSP432P401 or MSP432P111) the first 32KB of flash memory is reserved for a customized bootloader. This bootloader will startup a small NoRTOS implementation of the CC31xx host driver, open the image programmed at /sys/hostmcuimg.bin on the CC31xx, and dynamically program that image to the MSP432’s flash memory with a starting base address of 0x8000. The memory map of a typical MSP432 OTA enabled device can be seen below. Note that this example is for an MSP432P401, however on an MSP432P4111 the structure will be the similar but adjusted for the MSP432P111’s larger memory footprint.

WiFi Layers

Initially, when the Uniflash tar file is being programmed to the CC31xx over the active Wi-Fi connection, the firmware running on the MSP432 will detect if a new MSP432 firmware image exists in the package. If so, the MSP432’s firmware will set a flag in a specific area of SRAM and initiate a hard reset of the device (causing execution to be handed over to the custom bootloader).

A flow chart of the custom OTA bootloader in the presence of a MSP432 firmware image can be seen below:

WiFi Layers

Mobile Applications

Mobile applications are essential for provisioning an unconfigured SimpleLink device. “Provisioning” can be described as telling the SimpleLink device what router/access point to connect to and the relevant security information such as SSID/security key, etc. The various offerings of mobile applications provided by TI are described below.

This is a Swift based program written to take advantages of some of the new networking/Wi-Fi features that iOS11 provides. Notably, SimpleLink SDK Explorer uses the new features added in NetworkExtension to allow the user to connect directly to their SimpleLink devices in-application (without the need to switch back and forth to the iOS settings page). Currently this application is only available for iOS, however an Android version is planned and due out on a subsequent release.

In addition to being able to provision your Wi-Fi device using the direct access point mode, SimpleLink SDK Explorer also offers the full breadth of functionality from the SimpleLink SDK BLE Plugin (such as BLE firmware updates and sensor hub over BLE).

Note that before provisioning the device the correct certificate files will have to be installed and stored on the file system on the CC31xx. At a minimum, the following certificates and keys are required:

WiFi Layers

These certificates can be found in the /tools/cc31xx_tools/certificate-playground folder. Note that because these are development certificates most web browsers (mobile browsers included) will give a warning stating that these certificates are invalid. For development these errors can be ignored, however for production a valid certificate should be used. For more information on how to program user files/certificates on Uniflash please refer to the REPLACE ME section of this guide.

After downloading SimpleLink SDK Explorer from the Apple AppStore, touch the SDK selector button at the bottom of the screen:

WiFi Layers

This will open up the SDK selection screen. For the SimpleLink SDK Wi-Fi plugin, select the SimpleLink Wi-Fi SDKs. This will select the SimpleLink CC3x20 SDK line of projects (the provisioning application can be used either for CC3220 or CC3120).

WiFi Layers

Next select the Provisioning menu item on the top of the list.

WiFi Layers

On the next screen select the Direct Access Point as a provisioning mode.

WiFi Layers

On the next screen you will be prompted for information on your SimpleLink Wi-Fi device.

WiFi Layers

The SSID here generally starts with mysimplelink- and ends with the last six characters of the device’s MAC address. This can either be found by going directly to the Wi-Fi menu in your iOS settings:

WiFi Layers

Or by directly looking at the UART terminal on a provisioning application:

WiFi Layers

The key/security type are used if your SimpleLink device has been setup for any additional level of security (it generally isn’t unless you explicitly set it up). The device name is a unique identifier that is used to name the device and differentiate it from other provisioned devices (this can be anything with valid alphanumeric characters). Once this information is filled out touch Router on the top right to go to the router configuration page.

WiFi Layers

On this page you will provide information about the router/access point that you want to tie your SimpleLink device to. This will be the Wi-Fi configuration that is persisted in the non-volatile memory on your SimpleLink device. Fill in the appropriate values that correspond to your router/access point’s configuration and press the Summary button on the top right of the screen.

WiFi Layers

On this screen the previously entered information is displayed. If everything looks correct press the Provision button on the bottom to begin provisioning. On the provisioning screen the first thing that will happen will be for the application to prompt you to join the access point that was created by your SimpleLink device. Press OK to join the Wi-Fi network.

WiFi Layers

Next the device will probe the SimpleLink device for the version URL. Note that it can take iOS a good sixty seconds to actually be able to resolve the URL of the SimpleLink device in order to get the version number. Once the version number has been determined the router provisioning information will be sent over to the SimpleLink device and the internal provisioning state machine on the device will be progressed.

The next step that will happens involves confirmation of the provisioned device. Essentially what this entails is SimpleLink SDK Explorer connecting to the “common” router, listening for multicast UDP packets containing the address of the SimpleLink device on the common network, and SimpleLink SDK Explorer sending a “confirmation” to the device via the shared IP to signify the final confirmation. SimpleLink SDK Explorer will prompt you to join the common network.

WiFi Layers

After the provisioning process is complete touch the Done button to open up the configured device in the Safari web browser. Note that the application might prompt you one last time to join the commonly provisioned network if you are not already connected.

WiFi Layers

WiFi Layers

Once a device has been provisioned it will be saved to the Provisioned Devices list. To access this list touch the Provisioned Devices menu item from the main menu.

WiFi Layers

This will take you to a list of all devices that you have provisioned using the local SimpleLink SDK Explorer installed on your device. Touch one of the devices that you have provisioned to display the provisioning history screen.

WiFi Layers

This screen will provide all parameters used to provision the device as well as a full log of the provisioning process. If you touch the Open button the device will open up in the Safari web browser.

WiFi Layers

Note that the success of the provisioning process hinges on the underlying iOS software recognizing the Wi-Fi device. If the SimpleLink device is not broadcasting its SSID or iOS does not pick up on it the provisioning will fail. It may take several times for iOS and your SimpleLink device to sync up correctly.

For a more detailed explanation on the embedded side of the provisioning process please refer to the application note below:

https://www.ti.com/lit/ug/swru472/swru472.pdf

SimpleLink SDK Starter Pro is an application written as way to specifically provision CC3xx family of devices (both Gen1 and Gen2). This applications supports both Android and iOS and supports advanced features such as SmartConfig and access point 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

Serial Port Logging/Debugging

Note that for logging/debugging messages the back channel serial port of the LaunchPad is used. In order to read these messages, use your favorite serial terminal program (such as Tera Term or PuTTY). The COM port number will be different depending on the system configuration, however it should show up as XDS110 Class Application/User UART.

Device Manager

Make sure to use the Application/User UART and not the Auxiliary Data Port. Along with the COM port of the XDS110 UART, the back channel UART defaults to the following serial port values:

Serial port values

Customizing Parameters

As the SimpleLink SDK Wi-Fi Plugin leverages a two chip solution that uses SPI as a communications vessel between the two chips, it is necessary to have an easily accessible way to configure the SPI parameters from the host MCU’s firmware. For this reason an additional configuration parameter was added to the board file of each application example that controls the various configuration settings for the master SPI interface.

/*
 *  =============================== Wi-Fi ===============================
 *
 * This is the configuration structure for the Wi-Fi module that will be used
 * as part of the SimpleLink SDK Wi-Fi plugin. These are configured for SPI mode.
 */
\#include <ti/drivers/net/wifi/porting/SIMPLELINKWIFI.h>
    
const SIMPLELINKWIFI_HWAttrsV1 wifiSimplelinkHWAttrs =
{
.spiIndex = MSP_EXP432P4111_SPIB0,
.hostIRQPin = MSP_EXP432P4111_HOST_IRQ,
.nHIBPin = MSP_EXP432P4111_nHIB_pin,
.csPin = MSP_EXP432P4111_CS_pin,
.maxDMASize = 1024,
.spiBitRate = 3000000
};

const uint_least8_t WiFi_count = 1;

const WiFi_Config WiFi_config[1] =
{
{
    .hwAttrs = &wifiSimplelinkHWAttrs,
}
};

This example is shown for an MSP432P4111, however the parameters will be similar for both the other SimpleLink devices. Here the SPI bit rate, the physical pins used for the various CC31xx signals, and the buffer size for DMA transfers between the host and CC31xx can be specified. Note that on MSP432 devices that 1024 is the maximum size that can be used for DMA transfers.

Code Examples

Cloud OTA – Update the firmware of the MSP432 and the service pack/user files of the CC31xx using cloud providers such as GitHub and DropBox

Local OTA – Update the firmware of the MSP432 and the service pack/user files of the CC31xx using a local HTTP server web interface

MQTT Client – Example implementation of an MQTT client communicating to a cloud MQTT cloud server

MQTT Client Server – MQTT server implementation that demonstrates use of CC31xx in both MQTT server and client roles

Network Terminal – Full featured code example that allows users to configure and manipulate all aspects of the CC31xx through an interactive UART terminal

Power Measurement – Showcases power numbers for various modes of operation and hibernation modes.

Provisioning – Interacts with various host provisioning applications to provision the CC31xx to a central access point/router

Trigger Mode – Demonstrates how to use “trigger mode” to awake the device from hibernation using a specific packet on a predefined socket

TCP Echo using Ethernet and Wi-Fi – Showcases the tandem use of the Ethernet module and the Wi-Fi module using a TCP echo.

Wi-Fi Ethernet Sockets – Showcases how SlNetSock API’s will choose the correct interface on an automatic setting.

MSP432P401 BootLoader – Source code of the custom MSP432P401 bootloader used to update the firmware of the MSP432 over Wi-Fi

MSP432P4111 BootLoader – Source code of the custom MSP432P4111 bootloader used to update the firmware of the MSP432 over Wi-Fi

IDE/Software Configurations

This software package supports and has been tested with TI Code Composer Studio 8.2 as well as IAR Embedded Workbench for ARM v8.20.2. The GCC toolchain for ARM has also been tested within CCS as well as directly through command line invocation. Both FreeRTOS and TI-RTOS are fully supported in this release as well as addition “NoRTOS” support.

Code Composer Studio Project Guide

The SimpleLink SDK Wi-Fi Plugin is designed to integrate seamlessly with the Code Composer Studio Integrated Development Environment from Texas Instruments. After installing the plugin (it is recommended to use the default installation directory), CCS should automatically detect and install the plugin software package without any special interaction from the user. To check to see if the plugin has installed correctly, go to the Windows->Preferences menu item. Under the Code Composer Studio->Products item you should see “SimpleLink SDK Wi-Fi Plugin” installed (with a version number):

Product installed

Note that the installation path of the plugin needs to be present in the Product Discovery Path:

Product installed

IAR Embedded Workbench Project Guide

IAR Embedded Workbench is fully supported under the SimpleLink SDK Wi-Fi Plugin ecosystem. Setting up your development environment to work with IAR involves pointing IAR to the plugin and SDK directories as mentioned below.

To get started, a list of external variables needs to be imported in IAR in order to let the IDE know the paths for all of the relevant software installations. An example configuration file that uses the default paths can be found in the tools/iar/simplelink_sdk_wifi_plugin.custom_argvars file of the SimpleLink SDK Wi-Fi Plugin installation directory. This file might have to be changed depending on specific installation paths and version numbers; however it should work if the user chose to use the default installation paths (note the version numbers might slightly vary from the picture below):

Import external variables

To import this file into your IAR IDE, navigate to Tools->Configure Custom Argument Variables.

Import external variables

From here, click the “Global” tab and navigate to the directory where the custom_argvars file is stored (by default in the tools/iar/ directory of the installation path). Note that there are separate sets of custom_argvars for the supported host devices.

Add variables

After importing this file the custom variables will show up in the text box in the middle of the screen. Click OK to closeout and save the dialog. Note that these custom variables need only be imported once and the settings will persist.

Variables have been imported

Once the external symbols have been imported you can either open the project manually on the file system or use IAR’s built-in example project explorer. To open the project manually, simply go to File->Open->Workspace: Navigate to the example project’s eww file. For example, the network terminal’s eww file would be located at:

install_directory/examples/rtos/MSP_EXP432P401R/demos/network_terminal/tirtos/iar/network_terminal_template.eww

Once you have opened the workspace in IAR you are able to download and debug the program as you would any other IAR project.

Ready to go

Note that if you upgrade or change versions of the SimpleLink SDK Wi-Fi Plugin or the base SDK, the external tools variables will have to change to point to the correct version of the software.

Support

Please post on the MSP432 E2E Forum for device support questions.