The Texas Instruments SimpleLink™ Wi-Fi® CC3220SF LaunchPad™ development kit is an easy and cost effective way to get started with Wi-Fi connected devices.
Scan this tutorial to get familiar with it. Then complete each step in a sequential manner. Each step builds upon the previous one.
This tutorial supports Windows, macOS, and Linux.
This tutorial will teach you how to build the Xively C Client MQTT library, a custom build of WolfSSL (in case you want more TLS features than provided by the onboard TLS), and an example application for the CC3220SF. You will then learn how to sign the binary with a dummy signing certificate provided by TI, update your WiFi and Xively credentials, and flash the firmware to the board.
Texas Instruments SimpleLink™ Wi-Fi® CC3220SF Wireless Microcontroller LaunchPad™ development kit
SimpleLink Wi-Fi CC3220SF Wireless Microcontroller LaunchPad
Following the steps of this tutorial will have you install the following pieces of software:
- Code Composer Studio™ IDE v7.2
- SimpleLink CC32XX SDK, this tutorial uses version 1.60.
- ARM Code Generation Tools Compiler to cross-compile TI CC3220SF software from your host machine. This tutorial uses version 16.9.6.LTS.
- XDC Tools installed in the Code Composer Studio download archive. This tutorial uses XDC 3_50_04_43_core.
- UniFlash v4.2.2 firmware flasher for TI Microcontrollers
- xively-client-c IoT library
- WolfSSL v3.9.6 TLS library
Note: If your Compiler version doesn't match the one above then you will need to edit the Xively C Client makefile to update the toolchain's path. For more details please see the section Step 2 of 10: Build the Xively C Client Library which will guide you on how to determine your toolchain version and how to make the corresponding edits to your build system.
Note: If your SDK differs by a major version then there could be a breaking change. Edits could be required in the implementation of the Xively C Client Board Support Package (BSP) in
src/bsp/platform/cc3200sf. For more information about working with the BSP, please see the Xively C Client Porting Guide and/or report an Issue in the Xively C Client Github Repository.
Code Composer Studio includes the toolchain (compiler) you will need to build for the CC3220SF and a java-based IDE.
- Download the Code Composer Studio™ version 7.0 appropriate for your operating system (Windows, Linux or macOS): Code Composer Studio (CCS) Integrated Development Environment (IDE).
- Complete the free registration and validate your email address.
- Complete the brief export approval form and click Submit.
- Upon approval, click Download to proceed. Monitor the download process to completion.
- Once the download is complete, start the installation.
- Accept the license agreement and click Next >.
- Choose the default install folder and click Next >. Or, if you install into a custom directory, then note its path as you will need to refer to it later. By default, the path should be
c:\tion Windows and
- Enable SimpleLink CC3XX Wireless MCUs.
Note: If you use a CCS version older than 7.0, select SimpleLink Wireless MCUs and its two child options: CC32XX Device Support and TI ARM Compiler.
- Select the defaults through the rest of the installation screens to Finish the installation.
- Once installation completes, click Finish to leave the installer.
UniFlash is an application that loads firmware onto TI devices. Once the firmware is loaded, the device will always boot this firmware when powered on.
- Download UniFlash version appropriate for your host operating system (Windows, Linux, or macOS): UniFlash. Note: This tutorial was tested against UniFlash version 4.2.2 for Windows.
- Run the UniFlash installer.
- Once installation completes, check Launch UniFlash and click Finish to leave the installer.
This SDK contains the platform libraries that you will need to compile and link against when writing software for the CC3220SF.
- Launch Code Composer Studio.
- If prompted to Select a Workspace, click OK to select the default path.
- Select View > Resource Explorer from the top bar menu.
- Select CC32xx SimpleLink Wi-Fi from the list of available development tools.
- On the right side of the screen, click the Install on Desktop down-arrow icon and select Make Available Offline. Confirm Yes on the popup window.
- A Dependencies popup may appear. Click OK to download any software dependencies.
Note: Users may also download the CC32XX Simplelink™ Wi-Fi SDK directly outside of the Code Composer Studio™ if desired. Once downloaded, install using the default settings.
Download the library source code from the xively-client-c github repository.
Git clone the repository or download the source archive from the right side of the GitHub page.
WolfSSL is a third party TLS solution. While WolSSL isn't a requirement specifically, a TLS implementation that supports TLS v1.2 is a requirement. This tutorial includes source files for a Xively TLS Board Support Package that calls into WolfSSL for building secure sockets with TLS. If you require the use of a different TLS implementation then you will need to write a different TLS BSP. Please see the Xively C Client Porting Guide for more information about Board Support Package development.
- Download version 3.9.6 of WolfSSL from their GitHub repository.
- Uncompress the
- Move the resulting
$XI_CLIENT_C/src/import/tls/, and rename it to
Why is a WolfSSL TLS Library Required for this Tutorial?
The reason to supplant the on-chip TLS with WolfSSL is related to the new security process of flashing images onto TI CC3220, and the changes you will need to make Root CA list on the device to support firmware flashing. These changes will break the on-chip TLS' ability to authenticate the server side certificate. Therefore, we will add our own software TLS implementation to ensure that your device's TLS connection is secure.
For more information about these reasons, and potential avenues of further development, please see "Appendix A: Software vs Hardware TLS" and "Appendix B: Using on-board TLS without a CA-approved Code Signing Certificate/Key" near the end of this tutorial.
You will need to configure the make system's PRESET configuration for the CC3220SF to point to your downloaded toolchain and SDK for the device. This can be done by opening
$XI_CLIENT_C/make/mt-os/mt-cc3220sf.mk in your favorite editor.
The toolchain that Code Composer Studio™ downloaded might differ from the default that's configured in this
mt-cc3200sf.mk file. Verify the compiler paths:
- Browse to the path which you set in
- Open up the
compiler/directory and note the name of the toolchain.
- Compare this to the toolchain name stored in the
COMPILERvariable near the top of the file in
mt-cc3200sf.mk. Update the
COMPILERvariable as necessary.
Next, scroll down in the file
mt-cc3200sf.mk until you see the section devoted to you host system, either
MAC HOST OS,
WINDOWS HOST OS, or
LINUX HOST OS. Here you will configure the paths to the various TI SDKS you've installed.
XI_CC3220SF_PATH_CCS_TOOLSto the base directory of your CCSv7/tools directory.
XI_CC3220SF_PATH_XDC_SDKto the base directory of your TI installed
XI_CC3220SF_PATH_SDKto the base directory of your CC3220 SimpleLink SDK.
For instance, here are some example configurations for Windows and Mac OSX (click the tabs to toggle between the two), but your exact pathing might be different depending on software versions and installation configurations:
COMPILER ?= ti-cgt-arm_16.9.4.LTS XI_CC3220SF_PATH_CCS_TOOLS ?= C:/ti/ccsv7/tools XI_CC3220SF_PATH_SDK ?= C:/ti/simplelink_cc32xx_sdk_1_60_00_04 XI_CC3220SF_PATH_XDC_SDK ?= C:/ti/xdctools_3_50_03_33_core
COMPILER ?= ti-cgt-arm_16.9.4.LTS XI_CC3220SF_PATH_CCS_TOOLS ?= /Applications/ti/ccsv7/tools XI_CC3220SF_PATH_SDK ?= /Applications/ti/simplelink_cc32xx_sdk_1_60_00_04 XI_CC3220SF_PATH_XDC_SDK ?= /Applications/ti/xdctools_3_50_03_33_core
Once your make system is configured, then open a command line window and go to the base directory of the xively-client-c repository. Here type the following commands, depending on your host system which can be toggled via the tabs at the top of the box:
PATH=%PATH%;c:\ti\ccsv7\utils\bin PATH=%PATH%;c:\ti\ccsv7\utils\cygwin gmake PRESET=CC3220SF clean gmake PRESET=CC3220SF
make PRESET=CC3220SF clean make PRESET=CC3220SF
The first time you open CCS you'll be asked which Workspace you'd like to open. Create and select a folder for this project. e.g.
Import CCS Project...->
Check-off the following Discovered Projects:
Import CCS Project...->
Import CCS Project...->
In Code Composer Studio: Right click
In Code Composer Studio: Right click
Check the Troubleshooting section if either of these builds fail.
- Update the project settings to reflect your system's paths:
- Right click
If everything went well, you should now have the file
XivelyDemo.bin, which contains the Firmware we need to flash into the device. This file can be found here:
Before connecting a physical device to Xively, create its digital representation in the system. Log into the Xively management app to complete the following steps.
This operation will create a device template and a device instance in Xively to represent your CC3220SF board.
- Click on
Add another device.
- From the popup window select
Choose from our template libraryand click
- From the sections tabs at the top of the window go to
Quickstart Kits, select
TI CC3200, and click
In order for your device to securely talk to Xively it needs credentials that it will use to authenticate itself as a valid device within your account.
- Go to
All devicesand look for your sample CC3200 device. Click on its name.
- Click on
When the modal window pops-up, click the
A file named
MQTTCredentials.txtgets downloaded. It contains the device credentials that will be used in the next step. The file contains two data items:
- The first line is the Xively Device Secret.
- The second line is the Xively Device Id.
You now have a provisioned device in Xively that your CC3220SF will be able to connect as.
To allow your device to publish and subscribe to MQTT topics you will need your account ID.
- Click on the cogwheel in the top right-hand corner of the page and click the turquoise rectangle with your account id.
Your account id has been copied to the clipboard.
- Save your account id for later. It will be needed for
xively_demoapplication configuration in the next step.
Now you have all of the credentials for your device.
The UniFlash image is a ZIP file that contains the Xively client binary executable.
- Download the Xively CC3220SF UniFlash ZIP archive from the Xively C Client GitHub repository.
- Run UniFlash if it's not already running.
- In UniFlash, in the
Device Configurationfield, type "CC3220" and select
CC3120 / CC3220.
Note: Do not select the
CC3220SFdevice. If you did, click on the
Selected Deviceagain to change it to the
CC3120 / CC3220option.
Start Image Creator.
- Click the
- Select the UniFlash ZIP file that you downloaded from the Xively Github repository above, and click
- Highlight the new
XivelyProductionimage and click on the
Result: You have successfully imported the Xively Client image to UniFlash, and it is ready to be configured with your Xively credentials. At this stage UniFlash looks as follows:
- Delete the default
mcuflashimg.binwe included in the project:
Select MCU Image
- After selecting the binary, you'll be prompted with this configuration window. Set the path to your Code Signing Key, and select its associated certificate (it must be present in the device's SDK
Write, UniFlash will automatically sign your binary and link to the signature instead of your signing key.
TI Provides a Service Pack with most SDK releases which updates the underling device support on the platform. The Service Pack on your device should be kept in parity with your CC3220 SDK version.
Browseand locate the base directory of your CC3220 SDK. For instance
- Continue browsing to
- Highlight the file with the .bin extension. For instances, for SDK 1.6 the service pack is
- Click open. UniFlash will process for a moment and land you back on the Service Pack page.
The Xively Client for the CC3220SF reads your Wi-Fi and Xively credentials from a file stored in flash memory on the device. Prepare your Xively Device ID, Xively Device Secret, Xively Account ID, and Wi-Fi credentials to copy them to a text file so that the CC3220SF client may read them.
- In UniFlash, in the left-hand bar, click
- Hover your mouse over the file in
etc/xively_config.txtand click on the
- Save this file to your Desktop and open the file in your favorite text editor.
- Copy and paste your Xively AccountID, DeviceID, and DeviceSecret into the accountId, deviceId, and password fields, respectively.
- Enter your Wi-Fi SSID (name) and password into the corresponding fields.
- Ensure that your Wi-Fi security type is properly represented.
Tip: The default
"wpa2"value is the most popular and secure Wi-Fi security type. Other options include "open", "wep", "wpa", and "wpa_ent".
- Save the file.
- In UniFlash, hover over the xively_config.txt file and click the
A standard file manager opens.
- Browse to the
xively_config.txtfile that you have altered on your desktop and click
- Click the
- Click the
Result: The image for your device is now fully configured and ready to be flashed onto your device.
- Set the J15 jumper to
2on your device. This is the Sense on Power (SOP) jumper near the right-side button of the device.
Note: At the time of unboxing, the device has this jumper set to
1 which prevents the device from being flashed.
- Plug the USB cable that came with your device into the CC3220SF power socket at the top of the board, and connect the USB cable to your computer.
- In the UniFlash project, click the
Connectbutton and wait for the dialog box to disappear.
Note: This step gathers information from the device including it's MAC address, which is required before burning the firmware. When the dialog box disappears, you will see MAC and other device-specific information on the right side of UniFlash.
- Click the
Generate Imageicon in the bottom right.
- Click the
Program Image (Create & Program)button at the top.
UniFlash writes the image on your board and a progress bar appears. This may take about 30 seconds.
- Wait until you see
Programming complete, and click
Result: Your device reboots and runs the test program.
You did it! You now have a CC3220SF board connected and communicating with Xively.
To see the status of your device, go back to the device page in the Xively management app. The device status is now
Connected, and on the
Logs tab you see its
Device connected lifecycle log.
To see the graphical representation of data received from your device such as temperature and button states, go to Product Launcher. You can also turn on and off LEDs on the board using this web page interface.
If you have any problems with this tutorial that are not addressed by this Troubleshooting section, then please open up an issue in the Xively C Client Github Repository.
Older Toolchain Error
If you receive a message that the toolchain for a project is out of date, this because the Code Composer Studio project file in the Xively C Client github repository specifies a toolchain that you do not have on your host build machine. This is a simple problem to solve.
- Right click Project->Properties->CCS General for the project with the error
- Under Compiler Versions, click the pulldown and select the TI LTS toolchain that you built the Xively 3. Client Library with (above).
- Click OK
- Right click the failing Project and attempt to Build again.
TI RTOS Missing Dependency Error
If you encounter this error when attempting to build the Xively Example Application, please double check that you've imported the TIRTOS Debug and Release CCS projects as specified in Section 3: Setup a CCS Workspace above.
If you have, and you still have the error, then right click the Xively Example and select Properties->CCS Build and click the
tirtos_builds_CC3220SF_LAUNCHXL_release_css referenced project.
Add... and add the
tirtos_buids_CC3220SF_LAUNCHXL_release_css project that you have imported to your workspace in Step 3 of the tutorial above.
Compilation Problems SDK Mismatch
If your Application fails to build then your development environment might be using a different version of the SimpleLink SDK other than version 1.6. Please verify that you're using the correct SDK.
- Right-Click tirtos_builds_CC3220SF_LAUNCHXL_release and select Properties
- Select CCS General->Products
- Select SimpleLink CC3220 SDK 1.6.0.04
Next do the same for the project
The XiveyExample project inherits its SDK version from the
tirtos_builds_CC3220SF_LAUNCHXL_release PROJECT, and is therefore forced to use the same SDK version.
Application Crashes or Fails to Load
This usually occurs due to a Toolchain or SDK mismatch. Please see the section Compilation Problems SDK Mismatch above. Additionally, for the XivelyExample project, ensure that you're using the same SDK and toolchain version (CCS General->Products) as the one you used to compile the Xively C Client library on the command line.
Finally ensure that your Simplelink Service pack is the same as the one you were instructed to flash in section Step 8 of 10 above.
Xively Client Cannot Connect Error Code 10
This occurs if you're attempting to use a build on a Flashed CC3220 Image that does not circumvent the TLS shortcomings of the Dummy Certificate Playground.
Either you need to provide your own Root CA Signed Signature Certificate during the firmware update process in Uniflash, and reinstate the standard Root CA Certificate List (instead of the dummy one) or you need to build WolfSSL (or a custom TLS software library) into your application.
Please see the Appendix A: Software vs Hardware TLS and # Appendix B: Using on-board TLS without a CA-approved Code Signing Certificate/Key for more information.
The device's LEDs flash to indicate that the application is connecting to your Wi-Fi network and to the Xively service. Once connected, the LEDs turn off so they may be controlled by the Product Launcher.
If a connection problem persists, create a serial connection to the device (as described below in Creating a Serial Connection). The serial log may give you a specific reason for the failure.
A flashing green light indicates there is an error in parsing your Xively credentials and Wi-Fi credentials file. Please review Step 4 above.
If solidly lit, the green LED signifies that the
xively_cfg.txt file has been parsed correctly, and the application has progressed to the next stage: connecting to your Wi-Fi network.
A flashing orange light indicates there is a problem joining your Wi-Fi network. Check your Wi-Fi SSID, password, and security type in
xively_cfg.txt as described in steps 4.5 - 4.6 above.
If solidly lit, the orange LED signifies that the device has successfully connected to your Wi-Fi network and is attempting to connect to the Xively service.
A flashing red light indicates there is an error in connecting your device to Xively. Check your Xively device credentials in
xively_cfg.txt as described in steps 1 and 4.4 above.
Use serial connection to connect to your device in case your device fails to connect to Xively and you need to diagnose the problem, or you are curious about what the device is currently doing.
- Install a serial terminal program.
We recommend Putty (Windows) or Serial Tools (macOS).
- Ensure that UniFlash is closed.
Note: Depending on what UniFlash is currently doing, it might monopolize the serial connection that you are trying to establish. It's safest to close the program until you become more comfortable with UniFlash connection states.
- Use your serial terminal program to connect to your device.
The connection should have the following terminal properties:
- Baud Rate: 115200
- Data Bits: 8
- Stop Bits: 1
- Parity: None
- Flow Control: None
- Com Port: This is specific to your computer. This is usually
com3on Windows and
- Start the terminal session by clicking
Connecton your client.
- To get the full console log, reset your device. Press the button adjacent to the power cable at the top of your CC3220SF.
It might not be immediately obvious, but the reason for a Software TLS implementation in this tutorial is related to the process of securely burning development software onto the CC3220SF.
The flashing process of the TI CC3220SF requires the developer to provide a Certificate to sign the firmware image. This certificate must be signed by a valid Root CA authority for the flashing operation to be successful.
The signed firmware is generated by the UniFlash tool and then loaded into temporary memory on the device over serial. The device then attempts to authenticate the firmware signature against the Public Root Certificate Authority Certificates contained within the default Root CA Catalog on the device. This catalog has many public Root CA Certs from the common certificate authorities. Once the signature is authenticated, the device moves the firmware into secure storage.
TI has identified that procuring your own Root CA signed certificate for burning firmware isn't something that you'll want to do on day-one of platform investigation and validation. Therefore, TI provides a Certificate Playground directory which contains a Dummy Signing Certificate for signing your firmware images, and a Dummy Root CA List for authentication.
The Dummy Root CA List replaces the Root CA List on the device with a certificate list which does not have any Public Root Certificate Authority Certificates in it.
Unfortunately, this Dummy Root CA List installed on the device is used in other operations as well, mainly the on-chip TLS implementation which attempts to authenticate server certificates during TLS handshakes.
With the standard Root CA List replaced with a Dummy Root CA List, Server Certificates cannot be authenticated during TLS handshakes and all TLS connections will be denied.
To circumvent this problem, we install a Software TLS Library during development so that we can still securely connect to the Xively Service while also having the ease of the Dummy Root Certificate List.
For this tutorial we use the WolfSSL TLS implementation for this development configuration, but you can use your own.
You can configure the Xively C Client to ignore the Certificate Catalogue so a connection to the broker can be established even when the Dummy Root CA List is installed. However, this is NOT SECURE and is NOT VALID FOR REAL DEVICE DEPLOYMENTS.
To disable Server Certificate Checks in the on-chip TLS implementation, uncomment this line from
make/mt-os/mt-cc3220sf.mk and do a clean build of the Xively C Client library on the command line.
#XI_CONFIG_FLAGS += -DXI_CC3220SF_UNSAFELY_DISABLE_CERT_STORE
Please remember that disabling the Certificate Store/Catalogue will also disable checks on its Certificate Revocation List, so *this macro should NOT be used for production firmware images. You should use and maintain the Production Certificate Store provided by TI, or use a a Software TLS library.
Follow these steps only if you plan on using your own Signing Certificate that has been signed by a Root CA Certificate listed in the CC3220's default Root CA List, or if you are working on iterative building by loading the image via the CCS debugger interface (and not flashing the image.)
This is actually an easy change, building a different make configuration PRESET than the one in the tutorial above. Open a command shell to the base directory of the Xively C Client. Note, these commands assume that you've already configured your SDK paths and Toolchain paths in Step 2 of 10 above:
PATH=%PATH%;c:\ti\ccsv7\utils\bin PATH=%PATH%;c:\ti\ccsv7\utils\cygwin gmake PRESET=CC3220SF_TLS_SOCKET clean gmake PRESET=CC3220SF_TLS_SOCKET
make PRESET=CC3220SF_TLS_SOCKET clean make PRESET=CC3220SF_TLS_SOCKET
Once the build is complete, clean and rebuild your XivelyExample project in Code Composer Studio.
This tutorial was setup to teach you how to build a Xively C Client image to be flashed onto your CC3220SF as quickly as possible, but the resulting configuration is not the best for iterative development. Instead it would be better to use Code Composer Studio to load and test builds before flashing them to the device.
To setup the device a configuration that accepts temporary images in volatile memory, you will need to load a new firmware image onto your device using Uniflash. The new image must be marked for Development and should not contain an MCUImage file.
We have provided a Development Uniflash image just for this case. It's the one that we use for our own development purposes, and can be found in the Xively Github Repo that you cloned earlier in this tutorial under:
To use this image, simply import it into Uniflash. You will need to replace the provided
xively_cfg.txt file in the image with your own, just as you did in the tutorial above to setup your WiFi and Xively credentials. Once done, save the image, connect to the device, and Program the Image to your device just as you did with the previous Uniflash Project.
If you have an active serial connection to your device when you attempt to flash an image with Uniflash, then you will encounter an error that Uniflash could not communicate with the device.
Uniflash might warn you that the image you're loading is for the wrong device type, but continue onward and the image should be successfully loaded onto your device.
Following this, the device should boot but not execute any code. You will then be able to hit the Debug icon on Code Composer Studio to load a development version of Xively C Client onto your CC3220. Once loaded the debugger will automatically hit a breakpoint at the main() function. Simply hit the Resume/Continue button in the debug hotbar to proceed with the execution of the application.
Note that applications loaded via Code Composer Studio are temporary and will be lost when the device is rebooted or unplugged. You must flash the image onto the device for it to be permanently stored there.