Run a simple C sample on a SimpleLink device

---

Table of Contents

• Introduction
• Step 1: Prerequisites
• Step 2: Build and Run the Sample
• DPS support
• Next Steps

Introduction

About this document

This document describes how to connect a TI SimpleLink device to Microsoft Azure using the Azure IoT SDK. This multi-step process includes:

• Configuring Azure IoT Hub
• Registering your IoT device
• Build and deploy Azure IoT SDK on device

The instructions in this file apply specifically to a user who has directly cloned or downloaded the "azure-iot-pal-simplelink" PAL repository. Please note that it is highly recommended to alternatively install the TI SimpleLink SDK Plugin for Microsoft Azure, versus cloning or downloading this repository directly. The repository by itself only provides a basic example running on TI-RTOS with makefiles for the TI compiler. Full support for TI, GCC and IAR toolchains and FreeRTOS is provided via the Plugin installation.

If you have installed the Plugin for Azure IoT (i.e. did not just clone/download this repository), then please refer to the Quick Start Guide that is included with your Plugin installation (you should be able to access this via the "docs" folder of the Plugin for Azure IoT installation). The Quick Start Guide provides more accurate instructions that apply specifically to the Plugin installation.

Step 1: Prerequisites

• Computer with Git client installed and access to azure-iot-pal-simplelink, i.e. this public repository.
• One of the following boards:
  • CC3220SF LaunchPad
  • CC3220S LaunchPad
  • CC3235SF LaunchPad
  • CC3235S LaunchPad
  • MSP432E4 LaunchPad
• Setup your IoT hub
• Provision your device and get its credentials

These instructions refer to the folder that contains the Azure PAL repository on your local machine as <AZURE_PAL_INSTALL_DIR>.

While not strictly required, we recommend that you install the following tools from TI in the same directory and that you use directory names without any whitespace. This documentation assumes that you install everything in C:\ti.

• Install Code Composer Studio (CCS) IDE, v10.0 or compatible

• Install TI SimpleLink Wi-Fi CC32XX Software Development Kit 4.10 or compatible (for SimpleLink CC32XX only)

• Install TI SimpleLink MSP432E4 Software Development Kit 4.10 or compatible (for SimpleLink MSP432E4 only)

Please ensure that your device has been updated with the latest firmware and or service pack. Also ensure it uses a certificate catalog that contains the Baltimore CyberTrust Root CA. (instructions for updating the firmware, service pack, and/or certificate catalog are included with the SimpleLink SDK installation if applicable).

Step 2: Build and Run the sample

Build the Azure PAL and SDK libraries

1. Edit the products.mak file in <AZURE_PAL_INSTALL_DIR>\build_all using your favorite text editor. The variables XDC_INSTALL_DIR and SIMPLELINK_<YOUR DEVICE>_SDK_INSTALL_DIR must point to the locations where you installed these products. The variable ti.targets.arm.elf.M4 for CC32xx or ti.targets.arm.elf.M4F for MSP432E4 should point to the installation location of the TI ARM compiler, which can be found in CCS. After modification, these variable definitions should look similar to the following. Note the use of "/" in the path.

XDC_INSTALL_DIR ?= c:/ti/xdctools_3_61_00_16_core
SIMPLELINK_CC32XX_SDK_INSTALL_DIR   ?= c:/ti/simplelink_cc32xx_sdk_4_10_xx_xx
ti.targets.arm.elf.M4  ?= c:/ti/ccs1000/ccs/tools/compiler/ti-cgt-arm_20.2.0.LTS

It is also recommended that you add the xdc tools folder (C:/ti/xdctools_3_61_00_16_core) to your path in order to avoid errors related to finding gmake.exe during the build process.

2. Open a Windows command prompt.

3. In the Windows command prompt, run the following commands (be sure to replace the paths with your installation paths).

cd <AZURE_PAL_INSTALL_DIR>\build_all
C:\ti\xdctools_3_61_00_16_core\gmake.exe clean
C:\ti\xdctools_3_61_00_16_core\gmake.exe all

Build the OS

1. Update the settings in the imports.mak file of your device's SDK in <SIMPLELINK_CC32XX_SDK_INSTALL_DIR> or <SIMPLELINK_MSP432E4_SDK_INSTALL_DIR> with the appropriate paths if you have not done so previously.

2. In the Windows command prompt, navigate to the OS directory corresponding to your OS of choice. For example, <SIMPLELINK_CC32XX_SDK_INSTALL_DIR>/kernel/tirtos/builds/CC3220SF_LAUNCHXL/release/ccs for tirtos on CC3220SF.

3. In the Windows command prompt, enter the following commands to build the OS:

C:\ti\xdctools_3_61_00_16_core\gmake.exe clean
C:\ti\xdctools_3_61_00_16_core\gmake.exe

Build a sample application

The following instructions refer to the simplesample_http sample application in this PAL repository. Before building the application, complete the following steps:

1. Open the simplesample_http.c file from the directory <AZURE_PAL_INSTALL_DIR>\sample in a text editor and replace the value of the "connectionString" variable with the device connection string you noted earlier.

2. (For CC32xx only) Open the file CC3220SF_LAUNCHXL/wificonfig.h (substitute 'CC3220SF' with the variant of the LaunchPad you have). Search for "USER STEP" and update the WIFI SSID and SECURITY_KEY macros.

3. In the Windows command prompt, enter the following commands to build the application (replace CC3220SF_LAUNCHXL with your platform name):

cd <AZURE_PAL_INSTALL_DIR>\sample\CC3220SF_LAUNCHXL\tirtos\ccs
C:\ti\xdctools_3_61_00_16_core\gmake.exe clean
C:\ti\xdctools_3_61_00_16_core\gmake.exe all

Flash the root certificate

For CC32xx devices

Note: In the sample applications, the root CA certificate - "Baltimore CyberTrust Root" is flashed to the location /cert/ms.pem. This location must match SL_SSL_CA_CERT in <AZURE_PAL_INSTALL_DIR>\pal\inc\cert_sl.h, and is used by the SimpleLink TLS stack.

The Baltimore root CA certificate is needed as it's the root CA for *.azure-devices.net, the IoT Hub endpoint, and it's the only way for the device to verify the chain of trust.

The default behavior of the sample application 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.

For MSP432E4 devices

Note: In the sample applications, the root CA certificate - "Baltimore CyberTrust Root" is loaded into into an object named /cert/ms.pem. This location must match SL_SSL_CA_CERT in <AZURE_PAL_INSTALL_DIR>\pal\inc\cert_sl.h, and is used later when connecting to the IoT Hub endpoint.

The Baltimore root CA certificate is needed as it's the root CA for *.azure-devices.net, the IoT Hub endpoint, and it's the only way for the device to verify the chain of trust.

Setting Up Code Composer Studio Before Running The Examples

We show the procedure for CC32xx devices below, but the same procedure can be followed for MSP432E4 by replacing CC32xx with MSP432E4.

1. Plug the LaunchPad into a USB port on your PC

2. Open Code Composer Studio.

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

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

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

6. Use CC32xx.ccxml as "File name". Hit Finish.

7. In the Basic window, select "Texas Instruments XDS110 USB Debug Probe" as the "Connection", and then type "CC32" in the "Board or Device" text field. Check the box next to the device you have (depending on your LaunchPad). Hit Save.

8. Right-click "CC32xx.ccxml" in the Target Configurations View. Hit Launch Selected Configuration.

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

Running An Example

1. Disconnect and reconnect the LaunchPad's USB cable to power cycle the hardware, and then reconnect in CCS.

2. Select Run menu -> Load -> Load Program..., and browse to the file simplesample_http.out in <AZURE_PAL_INSTALL_DIR>\sample\CC3220SF_LAUNCHXL\tirtos\ccs (replace CC3220SF_LAUNCHXL depending on your board). Hit OK. This will load the program onto the board.

3. Run the application by pressing F8. The output will appear in your CCS console window, similar to the following:

Starting the simplesample_http example
Current time: Fri Jul 20 20:56:27 2018

CC32XX has connected to AP and acquired an IP address.
IP Address: 192.168.1.172
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

The Device Explorer can be used to monitor the data sent by the application. Under the "Data" tab in Device Explorer, "Monitor" option should be selected before running the application. Later when the application is run, a message similar to the following message is displayed on "Event Hub Data" window.

5/19/2017 5:26:44 PM> Device: [devicee43522cd755d463b9331e55d1cab2f13], Data:[{"DeviceId":"myFirstDevice", "WindSpeed":12, "Temperature":23.000000, "Humidity":68.000000}]Properties:'temperatureAlert': 'false'

Device Provisioning Service support

Support for Device Provisioning Service (DPS) is enabled by using the provisioning version of the libraries, e.g. common_sl_prov_release.a. However, using these libraries expect DPS to be used at the application level. As a result, it causes applications that are not using DPS to fail to build, including the simplesample_http sample application in this PAL repository, given it does not implement the HSM interface required by DPS.

If you are interested in turning on DPS support, it is recommended to download and install the TI SimpleLink SDK Plugin for Microsoft Azure. There is an example (prov_dev_client_ll_sample) in the Plugin that uses DPS and would be a more suitable starting point.

Next Steps

You have now learned how to run a sample application that collects sensor data and sends it to your IoT hub. To explore how to store, analyze and visualize the data from this application in Azure using a variety of different services, please click on the following lessons:

• Manage cloud device messaging with iothub-explorer
• Save IoT Hub messages to Azure data storage
• Use Power BI to visualize real-time sensor data from Azure IoT Hub
• Use Azure Web Apps to visualize real-time sensor data from Azure IoT Hub
• Weather forecast using the sensor data from your IoT hub in Azure Machine Learning
• Remote monitoring and notifications with Logic Apps