AWS IoT MSP432E4 Quick Start Guide

Table of Contents

Introduction

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

Hardware Requirements

Software Requirements

Setup

It is assumed that the MSP432E4 SDK has already been installed in a directory we will refer to as MSP432E4_SDK_INSTALL_DIR.

Installing MSP432E4 Plugin for AWS IoT in CCS

  1. Download and open the MSP432E4 Plugin for AWS Installer (replace x’s with version number):
    • Windows: aws_msp432e4_2_20_xx_xx.exe
    • Linux: aws_msp432e4_2_20_xx_xx.run
    • Note: If you have downloaded a zip file of the Plugin, then you should simply unzip it using your favorite unzip tool. The location you choose to unzip it to will be the installation directory (AWS_INSTALL_DIR).

  2. Select an installation directory. This will be referred to as AWS_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) and you should see the Install Discovered Products window

  5. Select the MSP432E4 Plugin for AWS and click Install

Hardware Setup

This example does not require special jumpers settings. Please refer to the SimpleLink MSP432E4 SDK documentation for more information if desired.

An Ethernet cable should be connected to the Ethernet port on the LaunchPad to provide it with Internet access.

Setting up a serial terminal

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

  2. Open a serial session to the appropriate COM port with the following settings:

    Baudrate:     115200
Data bits:       8
Stop bits:       1
Parity:       None
Flow Control: None

  3. The output of the examples will be displayed in the terminal.

AWS IoT Developer Setup

In order to run the example applications, it is necessary to complete the steps of the AWS IoT Developer Guide. In particular, the following steps of the guide must be completed:

  1. Installing the AWS Command Line Interface

  2. Configuring the AWS Command Line Interface

  3. Sign in to the AWS IoT Console

  4. Register a Device in the Thing Registry

  5. Create and Activate a Device Certificate
    • Make sure you choose to download the certificate files, as these will be needed when setting up the examples.
    • Note: you will also need a root CA certificate. You can download the root CA from here.

  6. Create an AWS IoT Policy

  7. Attach an AWS IoT Policy to a Device Certificate

  8. Attach a Thing to a Certificate

Note that Amazon has recently tailored the AWS IoT Developer Guide instructions specifically for the “AWS IoT Button.” You can ignore the mentions of the button, as your TI embedded device will be used in place of this. For more details on AWS IoT, please refer to the What Is AWS IoT page.

Building and running Examples in CCS

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

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

  2. Open Code Composer Studio.

  3. In CCS, import the subscribe_publish_sample 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 AWS_INSTALL_DIR\examples\rtos\MSP_EXP432E401Y\aws\subscribe_publish_sample. Select the checkbox next to the subscribe_publish_sample for TIRTOS (or FreeRTOS) for CCS (or GCC) and hit the Finish button.

  6. Two projects should appear in the Project Explorer tab in CCS: one for the subscribe_publish_sample example itself, and another which corresponds to the OS chosen.

  7. Update the example to use the proper certificates and AWS account, as specified in the section Example Pre-Build Steps

  8. If TIRTOS is your OS, you can simply right-click on the subscribe_publish_sample project, and select Build Project to build.


  9. If you are using FreeRTOS for your OS, you need to set the installation directory of FreeRTOS in both projects before building:
    1. In CCS, select Window > Preferences
    2. Navigate to Code Composer Studio > Build > Variables
    3. Click Add
    4. For Variable name, enter FREERTOS_INSTALL_DIR
    5. For Type, select directory
    6. For Value, enter the installation directory of FreeRTOS
    7. Hit OK until you get back to the main window in CCS
    8. To build the subscribe_publish_sample project, right-click on it, and select Build Project.

Setting Up Code Composer Studio Before Running The Examples

  1. In Code Composer Studio, open the CCS Debug Perspective - Windows menu > 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 MSP432E4.ccxml as “File name”. Hit Finish.

  5. In the Basic window, select “Texas Instruments XDS110 USB Debug Probe” as the “Connection”, and then type MSP432E401Y in the “Board or Device” text field. Check the box next to “MSP432E401Y”. Hit Save.

  6. Right-click “MSP432E4.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. Ensure that your MSP432E4 device is connected in CCS.

  2. Select Run > Load > Load Program…, and browse to the file subscribe_publish_sample_MSP_EXP432E401Y_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 subscribe_publish_sample with the name of the example you are working with)

  3. Run the application by pressing F8. The output will appear in your serial terminal session: 

    Service Status: DHCPC    : Enabled  :          : 000

Service Status: DHCPC    : Enabled  : Running  : 000

Network Added:
If-1:192.168.1.109

Service Status: DHCPC    : Enabled  : Running  : 017

startSNTP: Current time: Tue Aug  7 19:05:49 2018

AWS IoT SDK Version 3.0.1-

Connecting...

Subscribing...

-->sleep

Subscribe callback

sdkTest/sub     hello from SDK QOS0 : 0

Subscribe callback

sdkTest/sub     hello from SDK QOS1 : 1

-->sleep

Building and running Examples in IAR

Download and Installation of IAR

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

Configuring the IAR environmental variables for the AWS IoT Plugin

Before starting to work with any of the AWS IoT example projects, 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 <AWS_INSTALL_DIR>/tools/iar/AWS_MSP432E4_SDK.custom_argvars. If you need to modify the default path for the plugin’s installation directory, edit the variable AWS_MSP432E4_INSTALL_DIR in the file to correct the paths.

  2. Open the IAR IDE

  3. Choose Tools > Configure Custom Argument Variables

  4. Click Global > Import

  5. Browse to <AWS_INSTALL_DIR>/tools/iar. Import the custom argvars from the Plugin.

  6. Restart IAR

Importing your First Project

All Code Examples that are shipped with the plugin under the examples directory come with an IAR workspace. Double-Clicking the specific workspace (e.g. subscribe_publish_sample.eww) from the file manager allows you to open the project on disk and build it.

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. Go to the TI XDS Category, the settings should be TI XDS110 Emulator as the emulator, and SWD as the interface

  4. 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. The Example output is displayed in the serial terminal, as shown here.

Building with makefiles

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

  1. Update the imports.mak file in the <AWS_INSTALL_DIR> root folder with the appropriate paths. This file relies on the settings in the imports.mak file of the MSP432E4 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 and toolchain of choice. For example, <MSP432E4_SDK_INSTALL_DIR>/kernel/tirtos/builds/MSP_EXP432E401Y/release/ccs for TI-RTOS and TI compiler.

  3. 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_51_00_15_core\gmake.exe’). Normally XDCTOOLS are installed along with the MSP432E4 SDK, but if you need to download it, it is available here

  4. Navigate to the example folder specific to your OS and toolchain <AWS_INSTALL_DIR>/examples/rtos/MSP_EXP432E401Y/aws/subscribe_publish_sample/tirtos/ccs

  5. To build, run ‘make’ to generate subscribe_publish_sample.out

  6. You can load and debug the generated subscribe_publish_sample.out in CCS

  7. The Example output is displayed in the serial terminal, as shown here.

Example Pre-Build Steps

The steps in this section are common to CCS, IAR and command line environments.

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

Update the AWS configuration file

  1. If you are using Windows, open a Windows command prompt. If you are using Linux, open a terminal window.

  2. Use the following AWS CLI command to to retrieve your AWS account-specific AWS IoT endpoint: aws iot describe-endpoint

  3. In a text editor, open the aws_iot_config.h file, found in the subscribe_publish_sample project.

  4. Update the value of the macro “AWS_IOT_MQTT_HOST” with string output from this command (for example, it will have a format similar to the following: <random-string>.iot.us-east-1.amazonaws.com)

  5. Update the value of the macro “AWS_IOT_MQTT_CLIENT_ID” to a unique name for your device

  6. Update the value of the macro “AWS_IOT_MY_THING_NAME” with the name of the thing you created during the steps on the Register a Device in the Thing Registry web page

  7. The certificate file variables “AWS_IOT_ROOT_CA_FILENAME”, “AWS_IOT_CERTIFICATE_FILENAME”, and “AWS_IOT_PRIVATE_KEY_FILENAME” can be updated to specify the location to where the files should be written in flash on the device. You can use the default values, if desired.

Update the Example to use the certificates

The certificate files used by the examples need to be obtained from the AWS CLI tool and/or the AWS IoT website directly. If you have not already done so, follow Amazon’s steps to get the certificates for your device.

  1. Open the file certs.h, found in the subscribe_publish_sample project.

  2. Search for “USER STEP” and update the CA root certificate string, the client certificate string, and the client (private) key string. These should be extracted from certificate (.pem) files downloaded from AWS. Each line of the certificate must be updated to end with the character sequence \r\n. A typical string would be similar to the following (example) format. Be sure to update the array using the contents of your actual root CA:

    unsigned char root_ca_pem[] =
"-----BEGIN CERTIFICATE-----\r\n"
"ABCD1234hxS39SFVT43STY#fdsiEIOFiu2=y!8cZxzXMh+12wDCy21h+8vJsDh4\r\n"
<...>
"rzcuMZt6oPq6YJMtP3kSaik+bWyzRkdMOPGVL4TiPLAuyAZP1NXl\r\n";
"-----END CERTIFICATE-----";

Other Info

More CCS project information can be found here and here.