Table of contents

RoadTest: SimpleLink™ Wi-Fi® CC3220x Wireless MCU LaunchPad™

Author: david.long

Creation date: 11 Sep 2017

Evaluation Type: Evaluation Boards

Did you receive all parts the manufacturer stated would be included in the package?: True

What other parts do you consider comparable to this product?: NXP FRDM K82F

What were the biggest problems encountered?: Debugging communication issues with AWS IoT client

Detailed Review:

Introduction

I came across the invitation to apply for this RoadTest after watching a Texas Instruments webinar on Embedded Systems Security. I applied since I am intending to put together a tutorial for beginners in this area: the SimpleLink CC3220 Launchpad seemed like an ideal board to base it around. My application was successful and Element 14 kindly sent me the CC3220SF version.

This RoadTest report describes the steps that I took to become familiar with this board, the SimpleLink Software Development Kit (SDK) and a simple example of using the CC3220 as a “thing” in an AWS IoT application.

Overview of Board

The CC3320 is an SoC built around an ARM Cortex-M4F cpu. In addition to the memory and peripherals found on other Cortex-M4 MCUs, the CC3220 also includes a “network processor” that provides a Wi-Fi (IEEE 802.11 b/g/n) transceiver and advanced security features

.

There are 2 versions of the CC3320. They both provide “secure boot” to guard against attacks that attempt to change the start-up code:

The CC3320S boot loader copies its program from external serial flash to internal RAM on start-up. The program is stored in flash as a “secure file” with encryption and a “trusted root-certificate” that is validated as the program is loaded. If the signature is invalid, the programming fails.

The CC3320SF has an on-chip executable flash memory that contains the program. It also has an external serial flash, just like the CC3320, that is used to download the encrypted program to the development board. On first boot up, the boot loader reads the program in serial flash, decrypts it and then writes it to the internal flash. On subsequent boot-ups, the contents of the internal flash image are compared against the serial flash content – any differences are flagged as a tamper attempt and can cause the internal flash contents to be erased.

Both versions support a development mode that enables the internal memory to be programmed over a USB cable from the Code Composer Studio IDE.

As with other boards in the LaunchPad family, the CC3220 comes with various I/O devices such as LEDs, push-button switches, a temperature sensor and a 3-axis accelerometer. GPIO pins can be accessed via the usual rows of header pins that can also be used to add the CC3320 to a stack of “BoosterPack” boards. A view of the board (taken from the CC3320 User Guide) is shown below.

Security Features

I was attracted to this RoadTest by the extensive security features provided by the CC3220. An overview of these features is given in the following table (taken from Application Report SWRA509A “SimpleLink™ CC3120, CC3220 Wi-Fi® Internet-on-a-chip™ Solution Built-In Security Features”

The security features covered in this RoadTest include the use of trusted root-certificates, public/private keys, secure boot and initial secure programming.

Comparison with other boards

Another board that I was considering as a basis for a tutorial was the NXP FRDM K82F. This is also based around an ARM Cortex-M4F CPU and contains hardware components for security (such as an AES encryption engine). The NXP board does not feature a Wi-Fi transceiver but does include a socket for connecting a wireless module such as the Nordic Semiconductor nRF24L01+ (using SPI). However, the integrated network processor in the CC3220 gives it significant advantages:

1. Better hardware security since the interface between the CPU and network processor is not accessible
2. Wireless communication protocols and Transport Layer Security (TLS) are managed by the network processor so the workload of the Cortex-M4 is reduced (this also reduces the development effort required for an application and its code size)
3. No need to integrate software packages from multiple sources/vendors (e.g. mbedTLS)

Getting Started

There is a lot of good information available for anyone using the CC3220 on the Texas Instruments web site. In particular, it is worth looking first at the “SimpleLink Academy” pages

http://dev.ti.com/tirex/#/DevTool/CC3220SF-LAUNCHXL/?link=Software%2FSimpleLink%20CC3220%20SDK%2FSimpleLink%20Academy%2FOverview

The SimpleLink Academy contains a series of tutorial modules, with “lectures” and “labs” to complete. Each module is based on a particular feature of the SDK. There are versions of most labs that work with either TI-RTOS or FreeRTOS (the FreeRTOS functions have Posix-style “wrappers” around them to allow the example code to use a consistent API for both versions). Each lab consists of a Code Composer Studio (CCS) project that can be imported and run.

Since I was already familiar with FreeRTOS, I mostly used the FreeRTOS versions of the labs.

Out-of-Box Application

Before looking at any code or development tools, you can get an idea of the CC3220 capabilities by running the factory-installed application. The CC3220 can act as a Wi-Fi access point (AP) – you can connect to it from any Wi-Fi enabled computer/tablet/phone and use a browser to display a web page, hosted by the CC3220.

To run the out-of-box demo, simply connect the supplied USB cable to the micro USB port on the board and a suitable USB power supply (or USB socket on your computer). The AP mode is selected by pressing the SW2 switch on the LaunchPad board. Then, from your computer/tablet/phone connect to the wireless network being broadcast by the board. It will have a name “mysimplelink-xxyyzz” where xxyyzz will be replaced by the 3 least-significant bytes of the boards MAC address.

Once connected, open a suitable browser (Firefox, Safari, Chrome, etc) and enter the URL http://mysimplelink.net (the http:// prefix is required). It may take a few seconds for the web page to fully download. Clicking the “Start” button will start the demo: this enables the browser to change the state of an LED and shows an animated image of the board (it changes its orientation and (x,y,z) vector if you pick up the board and move it around).

Clicking on the settings tab (at the left of the OOB banner) brings up a page showing the network settings.

Installing tools and programming device

I followed the instructions in the “Getting Started Guide” (SWRU461) http://www.ti.com/lit/ug/swru461/swru461.pdf

First of all I downloaded and installed the following

1. CC3220 Software Development Kit (SDK) version 1.40.01.00 from http://www.ti.com/tool/download/SIMPLELINK-CC3220-SDK
2. Uniflash tool from http://www.ti.com/tool/uniflash
3. SimpleLink CC32XX SDK AWS IoT Plugin from http://dev.ti.com/tirex/#/?link=Software%2FSimpleLink%20SDK%20Plugins%2FSimpleLink%20CC32XX%20SDK%20AWS%20IoT%20Plugin
4. Code Composer Studio (CCS) Eclipse-based IDE from http://www.ti.com/tool/ccstudio Note that it is necessary to select CC32xx Device Support and TI ARM Compiler (from SimpleLink Wireless CPUs) during installation.
5. FreeRTOSv9.0.0 (I already had this installed – otherwise it can be downloaded from https://sourceforge.net/projects/freertos/files/latest/download?source=files ). A patch is required to make this compatible with the SDK – the patch files are in the SDK directory. I needed to copy the contents of C:\ti\simplelink_cc32xx_sdk_1_40_01_00\tools\cc32xx_tools\FreeRTOS_patch\CCS to the portable directory in my FreeRTOS install (on my computer that was C:\FreeRTOSv9.0.0\FreeRTOS\Source\portable\CCS)
6. XDS110 Drivers (used to connect USB port to CCS programmer/debugger and terminal from http://processors.wiki.ti.com/index.php/XDS_Emulation_Software_Package#XDS110_Reset_Download
7. A terminal emulator (if you do not already have one). The SimpleLink tutorials assume you are using Tera Term (https://osdn.net/projects/ttssh2/releases/ )

The Getting Started Guide uses the example “Network Terminal” to walk through the steps to program the CC3220. You can build the required binary file in CCS – you need to import the Network Terminal project (from C:\ti\simplelink_cc32xx_sdk_1_40_01_00\examples\rtos\CC3220SF_LAUNCHXL\demos\network_terminal\freertos\ccs) and then build the project. Since I was using the FreeRTOS version, I needed to define the variable FREERTOS_INSTALL_DIR with the path to my FreeRTOS install directory (use the Windows->Preferences->Code Composer Studio->Build-Variables menu). The binary file is in the project’s Debug folder.

The next step is to connect your board to your computer (using the USB cable) and run the UniFlash tool. It should automatically detect your board, otherwise you can select CC3220 from the displayed list.

The guide takes you through the steps to create a new project. There are two important recommendations:

1. Install the latest service pack for the CC3220. This is found in the SDK install directory
2. Set the device to “Development mode” to allow it to be programmed over the JTAG interface (via the USB port from within CCS).

The serial flash content will be encrypted. It is therefore necessary to specify the certificate and key used for the encryption. There are some example certificates that may be used for demo projects in the SDK directory (C:\ti\simplelink_cc32xx_sdk_1_40_01_00\tools\cc32xx_tools\certificate-playground )

You also need to select the certificate files from the certificate playground and add them to the set of user files together with the MCU Image (the binary file created in CCS).

The final step before generating the image and downloading it, is to add the key and set the other security options:

After programming, the CC3220 loads the new application when it is next reset. Opening a Tera Term enables you to interact with the Network Terminal application – it provides various network utilities such as ping, scan and connect. Tera Term should automatically detect the COM port used by the XDS110 UART but you need to change the baud rate from its default value to 115200, otherwise you will not see any messages in the terminal. I set 115200 to be the new default baud rate so I did not need to do this again. I also found that disconnecting and reconnecting the USB cable to the LaunchPad board disabled the COM port: I was not able to reconnect Tera Term to the board again, until my Windows 7 laptop was rebooted. This was not unexpected – boards from other MCU vendors that I am familiar with, also suffer from this problem.

AWS IoT Application

I was keen to connect the CC3220 to a cloud server to explore some other security issues. Amazon’s AWS IoT service is widely-used and there is a SimpleLink AWS plug-in available, with some example projects to try out, so this made an obvious choice.

The default install options for the AWS plug-in adds the code, documentation and example projects to the TI directory (the same place as CCS, the SimpleLink SDK and other tools).

The Quick Start Guide (AWS_Quick_Start_Guide.html ) refers to the AWS IoT Developer Guide (http://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html ) for the instructions to set up AWS IoT.

The first step is to install and configure the AWS Command Line Interface tool (aws-cli). The instructions for this step are found in the AWS Command Line Interface User Guide (http://docs.aws.amazon.com/cli/latest/userguide/installing.html ). The aws-cli install is managed by a Python script that runs in pip.

The next step is to set up an AWS account. You need to provide credit card detail for billing. However you only pay for the services that you use and the “AWS IoT Free Tier” allows you 250,000 free messages per month for the first 12 months so it should not be expensive to try out!

The sign in page for AWS IoT is at http://docs.aws.amazon.com/iot/latest/developerguide/iot-console-signin.html

Once you are connected to your AWS account, you can add and set-up a “thing”. The example in the AWS IoT Developer Guide assume that your thing will be an “Amazon IoT Button” but the steps for setting up any other thing are very similar. Note that you should pick a server location (ideally somewhere close) – each thing is associated with a single location.

Click the Get started button and then in the IoT console, select Register

Selecting the Registry->Things menu allows you to create and name your thing:

Communication between the CC3220 and AWS IoT is protected by a “X.509” certificate. AWS IoT can generate a certificate for each of your things - you need to attach this certificate to the thing that you have created.

Once the certificate is created, a form appears that allows you to download the certificate and keys.

YOU MUST DOWNLOAD THESE AS THEY NEED TO BE ADDED INTO YOUR APPLICATION!

Once this form is closed, I was not able to find a way to re-display it so needed to delete the certificate and create a new one (with new keys).

You also need the root CA – this is a public certificate for the AWS IoT site that can be downloaded from the link. You only need to download it once since it should not change for several years.

Communication between the CC3220 and AWS IoT consists of a sequence of MQTT messages. You need to add a policy to the certificate to enable subscribe and publish messages. To get started, it is easiest to add a policy with no restrictions but don’t do this for “real” applications!

Finally, you need to attach the certificate to your thing.

The application needs to know the “REST API endpoint” to connect to – this can be copied from “Interact” menu of the completed thing

To use the AWS-IoT plug-in with CCS, it needs to be downloaded and installed. The instructions to do this did not seem very clear! Eventually I discovered that this can be done from the “Resource Explorer” menu in CCS

I decided to try the “subscribe_publish_sample” project. This application connects to the specified AWS IoT “thing” and sends simple MQTT messages to it and receives callback notifications that it prints on the terminal. The project to import is C:\ti\aws_cc3220_1_10_00_07\examples\rtos\CC3220SF_LAUNCHXL\aws\subscribe_publish_sample.  The code needs edits with the details of your AWS IoT thing and the certificates. There are instructions for this at the end of the Quick Start guide.

In the file wificonfig.h, update the macro definitions SSID and SECURITY_KEY with a string giving the name and WPA key of your Wi-Fi access point

In the file aws_iot_config.h, update the macro definitions:

AWS_IOT_MQTT_HOST needs the name of the REST endpoint described above

AWS_IOT_MQTT_CLIENT_ID needs the name of your thing (e.g. “myCC3220SF”)

AWS_IOT_MY_THING_NAME needs the name of the thing shadow (e.g. “myCC3220SF”)

In the file certs.h, copy the contents of the downloaded certificate files to the arrays root_ca_pem, client_ca_pem and client_private_key_pem. Note that the contents of each downloaded file represents a single string so you will need to add backslash characters at the end of each line after pasting the contents into CCS., e.g. the root CA should look like this:

The application start-up thread awsThreadxn() copies the content of these arrays to the files "/cert/ca.der", "/cert/cert.der" and "/cert/key.der" in flash.  By default, these files are only written once. During development you might want to write these files every time the application is run (e.g. because the keys have changed). To do this, you can define the macro OVERWRITE_CERTS. If you are programming a CC3220 using UniFlash, you can add the certificates to the set of user files instead of adding them to certs.h. The calls to the flashCerts() function in awsThreadFxn should then be commented out.

I built the application and tried running it. This is the output from the terminal:

So it appears my application can connect to the Internet (the CC3220 has an IP address and can talk to the time-server) but it will not connect to the AWS server. How should I debug this? Is there a problem with the code or with my AWS IoT thing?

Stepping through the debugger, the program was failing in the file aws_iot_mqtt_client_connect.c – a call to the function pClient->networkStack.connect(...) was returning an error status (-1).

Searching the TI E2E Community forums revealed that others had experienced similar problems. Two threads were especially useful:

"CC3220: Creating Certs for CC3220 using Amazon AWS"

http://e2e.ti.com/support/wireless_connectivity/simplelink_wifi_cc31xx_cc32xx/f/968/t/593513?tisearch=e2e-sitesearch&keymatch=cc3220%20aws#pi239031350=4

"RTOS/CC3220SF-LAUNCHXL: CC3220SF LaunchPad Connect to AWS IoT"

https://e2e.ti.com/support/wireless_connectivity/simplelink_wifi_cc31xx_cc32xx/f/968/t/621358

One suggestion was that there might be a problem with the pasted in certificates (e.g. the editor might have inserted tabs into the string). Adding the string length into the messages printed by the flashCerts() function confirmed that the certificates were the expected lengths.

Another suggestion was to correct a bug in network_sl.c where the connect() function return value was not tested to see if it failure due to an unknown root CA. I made the suggested changes but this did not fix the error.

Another suggestion was to try connecting to a different MQTT host – “iot.eclipse.org” (using the corresponding root CA). This was successful and confirmed that the MQTT connection mechanism was working. So if the problem was with the AWS IoT, how to debug that?

The SimpleLink  AWS IoT plug-in is based on the AWS IoT C SDK, published by Amazon. The AWS IoT Developer Guide describes the steps required to build the subscribe_publish_sample for a Raspberry Pi. Since I had a spare Raspberry Pi I followed the instructions to download and install the AWS IoT SDK. I copied the certificates for the “myCC3220SF”thing to the Raspberry Pi and built the application using the provided Makefile. When I ran the application, I saw similar output to that from the CC3220. The Developer Guide has a section at the back on “Troubleshooting the AWS IoT – this suggested using the OpenSSL s_client command to test the connection to the AWS IoT endpoint:

This command successfully connected the Raspberry Pi to my AWS IoT endpoint, proving that the certificates were OK.

The next suggestion in the Developer Guide was to set up “CloudWatch Logs” in AWS. The CloudWatch logs service allows you to capture and view the progress events generated as messages from your devices pass through the AWS IoT message broker and rules engine.

The instructions in the Developer Guide were not very clear – I managed to enabled logging by clicking on the Settings menu in the AWS IoT page

With CloudWatch logs enabled, I re-ran the application on the Raspberry Pi and checked the results.

So it was a security issue. When I checked the certificate in AWS IoT I discovered that it did not have a policy attached – the default policy is no access!

I edited the certificate to make sure my policy was properly attached – it should look like this:

Running the application again, I now saw the expected results in the console window and in the logs:

I then tried running the application on the CC3220 again. This time, it worked as expected!

Terminal output:

CC3220 Log:

Once communication is working correctly, the MQTT messages picked up in the AWS IoT client can be displayed in real time by clicking on the Test button

Further experiments

The CC3220 LaunchPad includes a temperature sensor that is accessed over an I2C interface. The “portable” example (C:\ti\simplelink_cc32xx_sdk_1_40_01_00\examples\rtos\CC3220SF_LAUNCHXL\demos\portable ) includes a thread to access the temperature sensor (using a mutex) and another thread that enables a console to print the current temperature on demand. I was hoping to add the temperature sensor thread to my working subscribe_publish_sample project so that live temperature readings could be stored in the myCC3220SF thing shadow in AWS IoT.

This should have been a reasonably simple modification but for some reason that I was not able to determine, the temperature reading thread blocked forever while writing to the I2C port. I did not have time to hook up a logic analyser to help with debugging the issue or to step through the pre-built driver code in CCS.

Debug issues

On a previous project using the SimpleLink MSP432 LaunchPad, I found the ability to connect a Segger J-Link probe to the board’s JTAG socket really useful. The SimpleLink CC3220SF LaunchPad also has a JTAG socket (although it is enabled via jumpers rather than a single switch). Unfortunately it seems that the J-Link probe is not yet supported by this board: it cannot be set as the programming interface in the CCS project settings and if you attempt to create a debug configuration using J-Link you get an error message

I found an E2E forum thread from 2016 where someone had asked about this problem with a CC3200. It appears it has still not been resolved?

http://e2e.ti.com/support/wireless_connectivity/simplelink_wifi_cc31xx_cc32xx/f/968/p/484003/1777783#1777783

Summary

I enjoyed doing this RoadTest on the CC3220SF LaunchPad board and learnt lots about how it could be used to develop an IoT application. The documentation and tutorials available in the SimpleLink Academy and the ti.com web site are impressive but can seem a bit overwhelming when trying to work out how to get started. I was not familiar with AWS IoT before starting this RoadTest so that was another steep learning curve! Overall, it took much longer to complete this RoadTest than I had expected.

I found answers provided on the E2E forum were very useful and informative when looking to solve particular issues. I didn’t ask any questions myself as I was able to find all of the answers I was looking for (except for the I2C driver).

The integrated network processor on the CC3220 greatly simplified the code that would be required for Wi-Fi communications and higher-level security such as TLS. It also meant that these tasks do not need to be executed on the Cortex-M4 core.

At some point in the future I am intending to write this up properly and create an online tutorial for beginners. This will be available for free download in the KnowHow section of the Doulos web site https://www.doulos.com/knowhow/

Finally I would like to thank TI and Element14 for the opportunity to participate in this RoadTest