Quick Start Guide

Table of Contents

Introduction

This guide is intended to assist users in the initial setup and demonstration of a CC32XX Azure application using the CC32XX Azure IoT Plugin. The guide explains how to configure the boards, compile the software artifacts, program the CC32XX device, set up your Azure account and run an Azure application.

Hardware Requirements

Software Requirements

Installing CC32XX Azure IoT Plugin in CCS

  1. Download and open the CC32XX Azure IoT Plugin Installer (replace x’s with version number):
    • Windows: azure_cc32xx_x_xx_xx_xx.exe
    • Linux: azure_cc32xx_x_xx_xx_xx.run

  2. Select an installation directory. This will be referred to as <AZURE_INSTALL_DIR> in the rest of this document. It’s recommended that you install it in your CCS installation directory (default c:/ti) so it can be discovered automatically.

  3. Click Next > and finish the installation

  4. Open CCS (close and re-open if already running)

  5. If you see the Install Discovered Products window, select the CC32XX Azure IoT Plugin and click Install

Hardware Setup

Jumper settings

The SOP[2…0] jumpers are used to set different flash programming modes/states.

  1. SOP[2…0] mode ‘100’ is used for programming the serial flash with the application binary and/or the service pack. After flashing, the board should be reset and the mode set to ‘000’ (no jumpers in place) to run/execute the contents of flash

  2. SOP[2…0] mode ‘010’ is the flash and execute mode which is similar to the ‘100’ mode except that after flashing, the contents of flash are executed immediately without having to reset or remove all jumpers. This mode is also used when using the CCS to connect to the device for loading and debugging

Connect the Launchpad

  1. Plug the CC32XX Launchpad into a USB port on your PC.

Azure IoT Developer Setup

In order to run the example applications, it is necessary to complete the following steps:

  1. Setup your IoT hub

  2. Provision your device and get its credentials

Building and running Examples in CCS

Several examples are provided in the CC32XX Plugin and can be found in the examples/ subdirectory. These steps refer to the simplesample_http application for the CC3220SF device, but the same procedure applies to the CC3220S and to other examples, as well.

  1. It is assumed that the CC32XX SDK has already been installed in a directory we will refer to as CC32XX_SDK_INSTALL_DIR. You should install it if you have not already done so, as the CC32XX Azure IoT Plugin depends on the CC32XX SDK.

  2. Open Code Composer Studio.

  3. In CCS, import the simplesample_http by first selecting File > Import…

  4. In the Import window, select C/C++ > CCS Projects and hit the Next button

  5. In the Import CCS Eclipse Projects window, hit the browse button to browse to the location corresponding to <AZURE_INSTALL_DIR>\examples\rtos\CC3220SF_LAUNCHXL\azure\simplesample_http. Select the checkbox next to the simplesample_http for tirtos for CCS and hit the Finish button.

  6. Update the example to use your Azure connection string and WiFi Access Point information, as specified in the section Example Pre-Build Steps

  7. Two projects should appear in the Project Explorer tab in CCS: one for the simplesample_http example itself (ie. simplesample_http_CC3220SF_LAUNCHXL_tirtos_ccs), and the other is a project corresponding to the OS chosen (e.g. azure_cc32xx_tirtos_builds_CC3220SF_LAUNCHXL_release_ccs). If tirtos is your OS, you can simply right-click on the simplesample_http project, and select Build Project to build.

  8. If you are using TI-RTOS and compiling with GCC, semihosting needs to be enabled in the OS project by uncommenting the following line in release.cfg for the program output to appear in the CCS console:

    var SemiHost = xdc.useModule('ti.sysbios.rts.gnu.SemiHostSupport');

    Rebuild the OS and example projects after the change. See this page for more details on semihosting if desired.

  9. If you are using FreeRTOS, you need to set the installation directory of FreeRTOS in both projects before building:
    1. Right-click on the simplesample_http project
    2. Select Properties
    3. Navigate to Resource > Linked Resources
    4. Double-click on the entry FREERTOS_INSTALL_DIR. If no entry exists, click New… to add it.
    5. Enter the installation directory of FreeRTOS into the Location box
    6. Hit OK until you get back to the main window in CCS
    7. Repeat the same steps for the FreeRTOS OS project, freertos_builds_CC3220SF_LAUNCHXL_release_ccs
    8. To build the simplesample_http project, right-click on it, and select Build Project.

  10. The example comes with a README.html file that contains more details specific to the example. Be sure to take a look.

Setting Up Code Composer Studio Before Running The Examples

  1. In Code Composer Studio, open the CCS Debug Perspective - Windows menu > Perspective > Open Perspective > CCS Debug

  2. Open the Target Configurations View - Windows menu > Show View > Target Configurations

  3. Right-click on User Defined. Select New Target Configuration.

  4. Use CC32xx.ccxml as “File name”. Hit Finish.

  5. In the Basic window, select “Texas Instruments XDS110 USB Debug Probe” as the “Connection”, and then type “CC3220” in the “Board or Device” text field. Check the box next to “CC3220SF” or “CC3220S” (depending on your launchpad). Hit Save.

  6. Right-click “CC32xx.ccxml” in the Target Configurations View. Hit Launch Selected Configuration.

  7. Under the Debug View, right-click on “Texas Instruments XDS110 USB Debug Probe_0/Cortex_M4_0”. Select “Connect Target”.

Running an Example in CCS

  1. Optional: If you have not yet run any applications on your CC32XX since powering it on, then skip to step 2. Otherwise, if you have recently run an application on the CC32XX since powering it on, it is necessary to reset the board. Disconnect and reconnect the CC32XX’s USB cable in order to power cycle the hardware, and then reconnect in CCS. For best results, it is recommended to do this before loading and running an application every time, in order to reset the CC32XX’s network processor.

  2. Select Run menu > Load > Load Program…, and browse to the file simplesample_http_CC3220SF_LAUNCHXL_tirtos_ccs.out, found in your project. Hit OK. This will load the program onto the board. (The same procedure applies to other examples by substituting simplesample_http with the name of the example you are working with)

  3. Run the application by pressing F8. The output will appear in the CCS console window (this is true for all examples except for lp_monitor_demo, which outputs to a serial terminal. See that example’s README.html for more details): 

    Starting the simplesample_http example
Current time: Mon Jul 23 23:52:04 2018

CC32XX has connected to AP and acquired an IP address.
IP Address: 192.168.1.128
Flashing certificate file ...successfully wrote file /cert/ms.pem to flash
IoTHubClient accepted the message for delivery
Message Id: 1 Received.
Result Call Back Called! Result is: IOTHUB_CLIENT_CONFIRMATION_OK

Building and running Examples in IAR

Download and Installation of IAR

For instructions on downloading and setting up IAR properly for use with the CC32XX SDK and its plugins, please refer to the Quick Start Guide document that is included in the SimpleLink CC32XX SDK. As part of the procedure, make sure to import the custom argvars for the SDK.

Configuring the IAR environmental variables specific to the Azure IoT Plugin

Before starting to work with any of the Azure IoT example projects in the plugin, you need to load a set of environment variables that will be set to your current workspace (custom argvars), in addition to the ones from the SDK.

  1. The custom argvars can be found at <AZURE_INSTALL_DIR>/tools/iar/AZURE_CC32XX_SDK.custom_argvars. If you need to modify the default path argument variable, edit the variables with the correct path.

  2. Open the IAR IDE

  3. Choose Tools > Configure Custom Argument Variables

  4. Click Global > Import

  5. Browse to <AZURE_INSTALL_DIR>/tools/iar. Import the custom argvars from the plugin.

  6. Restart IAR

Importing your First Project

You can choose to open an Example Project by either directly accessing the Example workspace (by double clicking on its *.eww file), or by importing the Example from the Example List in the IDE.

Directly accessing an Example from the Example Folder

All Code Examples that are shipped with the plugin come with an IAR workspace. Double-Clicking the specific workspace allows you to open the project on disk and build it. Be sure to update the example to use the proper certificates, Azure account and WiFi Access Point information, as specified in the section Example Pre-Build Steps

Importing an Example in the Example List

  1. In the IAR-IDE, select File > Open File… from the menu and open <AZURE_INSTALL_DIR>/tools/iar/Examples.html

  2. All the Azure IoT Plugin example projects that are available in IAR are listed in the html page.

  3. Scroll through the page and click on the project you are interested in. In this guide we choose to work with simplesample_http for the CC3220SF based on TI-RTOS.

  4. When prompted, click Yes to save a copy of the project workspace in a specific folder, No will save the workspace in a default folder.

  5. After clicking Yes, browse to the location where you want to save this workspace. Click Choose

  6. When importing any example, the related kernel project will be imported automatically

  7. Update the example to use the proper certificates, Azure account and WiFi Access Point information, as specified in the section Example Pre-Build Steps

  8. To compile the example and the kernel projects, Choose Project > Make

Start a debug session

  1. Select Project > options from the menu, and select the Debugger category.

  2. By default, the project Debug settings are configured for the TI XDS110, but the user may change them as needed.

  3. In case you are working with the CC3220SF device, check the Use flash loader(s) checkbox in the Debugger > Download tab.

  4. Go to the TI XDS Category, the settings should be TI XDS110 Emulator as the emulator, and JTAG (4-pin) as the interface

  5. You can override the path for code composer studio base according to the code composer installation path.

Load and run the Example

  1. Select Project > Download and Debug

  2. Click the Go button in IAR to run the Example

  3. Select View > Terminal I/O to open the console window. The Example output is displayed in the window in IAR, as shown here. Only exception is the lp_monitor_demo example, which outputs to a serial terminal. Refer to that example’s README.html file for details.

Building with makefiles

To build the simplesample_http application on the command-line using the provided makefile:

  1. Update the imports.mak file in the <AZURE_INSTALL_DIR> root folder with the appropriate path(s). This file relies on the settings in the imports.mak file of the CC32XX SDK, so please ensure you have updated the latter with the appropriate paths as well if you have not done so previously.

  2. Navigate to the OS directory corresponding to your OS of choice. For example, <CC32XX_SDK_INSTALL_DIR>/kernel/tirtos/builds/CC3220SF_LAUNCHXL/release/ccs for tirtos.

  3. If you are using TI-RTOS and compiling with GCC, semihosting needs to be enabled in the OS configuration by uncommenting the following line in <CC32XX_SDK_INSTALL_DIR>/kernel/tirtos/builds/CC3220SF_LAUNCHXL/release/release.cfg for the program output to appear in the CCS console:

    var SemiHost = xdc.useModule('ti.sysbios.rts.gnu.SemiHostSupport');

    See this page for more details on semihosting if desired.

  4. Run ‘make’ to build the OS. If you develop on a Windows machine and do not have the ‘make’ utility, you can alternatively run ‘gmake’ from your TI XDCTOOLS installation (e.g. ‘C:\ti\xdctools_3_50_07_20_core\gmake.exe’). Normally XDCTOOLS are installed along with the CC32XX SDK, but if you need to download it, it is available here

  5. Update the example to use your Azure connection string and WiFi Access Point information, as specified in the section Example Pre-Build Steps

  6. Navigate to the example folder specific to your OS <AZURE_INSTALL_DIR>/examples/rtos/CC3220SF_LAUNCHXL/azure/simplesample_http/tirtos/ccs

  7. To build, run ‘make’ to generate simplesample_http.out

  8. You can load and debug the generated simplesample_http.out in CCS

  9. The Example output is displayed in the CCS console, as shown here.

Building the Azure PAL and SDK libraries

The libraries for the Azure Platform Adaptation Layer (PAL) and the Azure IoT C SDK are shipped pre-built as part of the plugin. If for some reason, you would like to rebuild them, follow the instructions in the section Build the Azure PAL and SDK libraries from <AZURE_INSTALL_DIR>\source\third_party\azure-iot-pal-simplelink\README.md. <AZURE_PAL_INSTALL_DIR> in the instructions corresponds to the directory <AZURE_INSTALL_DIR>\source\third_party\azure-iot-pal-simplelink.

Viewing data from the cloud

You can view the data that has been received on the cloud side in various ways, for example using the Device Explorer or the iothub-explorer from Microsoft, or creating an Azure Function App on the Azure portal itself. Please refer to online documentation from Microsoft to learn about the various ways to interact with the IoT Hub.

Example Pre-Build Steps

Before building a specific application, you must complete the following steps in order to successfully connect to Azure (these steps refer to the simplesample_http application for the CC3220SF device, but the same procedure applies to other examples as well):

Update the Azure connection string

Open the file simplesample_http.c in a text editor and replace the value of the “connectionString” variable with the device connection string you noted when you registered your device with the IoT hub. (Other examples similarly have a source file named <example_name>.c or NetMgr.c where the connection string can be set.)

Flash the root certificate

Note: In the examples, the root CA certificate - “Baltimore CyberTrust Root” is flashed to CC32XX Launchpad to the location /cert/ms.pem. This location must match the one referenced in <AZURE_INSTALL_DIR>\source\third_party\azure-iot-pal-simplelink\pal\inc\cert_sl.h, and is used by SimpleLink TLS stack.

Here’s why you need the Baltimore root CA - it’s the root CA for *.azure-devices.net, the IoT Hub endpoint and it’s the only way for the tiny CC32XX to verify the chain of trust:

The default behavior of the example is to automatically write the certificate to flash if it does not exist. This prevents the file from being written unnecessarily to the file system each time the program is run. If you wish to override this behavior, or if you wish to use a new certificate file, you can force the certificate to be flashed by passing “-DOVERWRITE_CERTS” to the compiler in the makefile. Otherwise it is best to not change anything here.

Update The Example With Your Wi-Fi Access Point Information

Open the file wificonfig.h, found in the simplesample_http project. Search for “USER STEP” and update the Wi-Fi SSID and SECURITY_KEY macros.

Other Info

More CCS project information can be found here and here.