Quick Start Guide

Introduction

This guide is intended to assist users in the initial setup and demonstration of a MSP432E4 Azure IoT application using the MSP432E4 Plugin for Azure IoT, which augments the Azure IoT C SDK by providing support on TI MSP432E4 devices. The guide explains how to configure the boards, compile the software artifacts, program the MSP432E4 device, set up your Azure account and run an Azure application.

Hardware Requirements

• TI MSP432E4 LaunchPad

Software Requirements

• SimpleLink MSP432E4 SDK 4.10
• A computer running a supported operating system listed in the Release Notes
• At least one of the following IDEs supported by the SimpleLink MSP432E4 SDK:
  • CCS 10.0.0 or compatible
  • IAR for ARM 8.50.1
  • GNU ARM Embedded Toolchain, 9-2019-q4-major
• FreeRTOSv10.2.1 (Optional)
  • If the User wants to use FreeRTOS with the Plugin, the user is expected to download the FreeRTOS sources from www.freertos.org

Installing MSP432E4 Plugin for Azure IoT

1. Download and open the MSP432E4 Plugin for Azure IoT Installer (replace x’s with version number):
   • Windows: azure_msp432e4_x_xx_xx_xx.exe
   • Linux: azure_msp432e4_x_xx_xx_xx.run
   • macOS: azure_msp432e4_x_xx_xx_xx.app
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 on Windows) so it can be discovered automatically
3. Click Next > and finish the installation

Hardware Setup

Connect the LaunchPad

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

2. Connect the Ethernet port to your router/AP using an Ethernet cable.

   

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.

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 Plugin and can be found in the examples/ subdirectory.

These steps refer to the simplesample_http application, but the same procedure applies to other examples as well.

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

2. Open Code Composer Studio (close and re-open if already running before Plugin or SDK installation).

3. In CCS, import the simplesample_http example by first selecting Project > Import CCS Projects…

4. In the Import CCS Projects window, hit the browse button to browse to the location corresponding to <AZURE_INSTALL_DIR>\examples. Select the checkbox next to the simplesample_http example for tirtos (or freertos) for CCS and hit the Finish button.

   

5. Two projects should appear in the Project Explorer tab in CCS: one for the simplesample_http example itself (i.e. simplesample_http_MSP_EXP432E401Y_tirtos_ccs), and the other is a project corresponding to the OS chosen (e.g. tirtos_builds_MSP_EXP432E401Y_release_ccs).

6. The example comes with a README.html file that contains more details specific to the example. Be sure to take a look as it may contain additional instructions.

7. Update the example to use your Azure connection string, as specified in the section Example Pre-Build Steps

8. If you are using FreeRTOS, you need to set the installation directory of FreeRTOS 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

9. Right-click on the simplesample_http project, and select Build Project to build.

   

Load and Run the Example

1. Plug the LaunchPad into a USB port on your PC.
2. Right-click on the simplesample_http project, and select Debug As > Code Composer Debug Session.
3. Run the application by pressing F8. The output will appear in your serial terminal session.

Example Output

```
Service Status: DHCPC    : Enabled  :          : 000
Service Status: DHCPC    : Enabled  : Running  : 000
Starting the simplesample_http example
Network Added: If-1:192.168.1.106
Service Status: DHCPC    : Enabled  : Running  : 017
Current time: Mon Jul 23 21:56:37 2018

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

For instructions on downloading and setting up IAR properly for use with the SimpleLink MSP432E4 SDK and its Plugins, please refer to the MSP432E4 SDK’s Quick Start Guide document. As part of the procedure, make sure to configure the custom argument variables for the SDK.

Configuring Custom Argument Variables Specific to the 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 for your current workspace, in addition to the ones from the SimpleLink SDK.

1. The custom argvars can be found at <AZURE_INSTALL_DIR>/tools/iar/AZURE_MSP432E4_SDK.custom_argvars, if you need to modify the default path argument variables, 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.

Importing Your First Project

These steps refer to the simplesample_http application, but the same procedure applies to other examples as well.

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 (*.eww file). Double-Clicking the specific workspace allows you to open the project on disk and build it.

Each example comes with a README.html file. Be sure to take a look in case it has additional instruction specific to the example you wish to run. Update the example to use your Azure connection string, 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 Plugin for Azure IoT 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 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

Building the Project

1. Two projects should appear in the Workspace tab in IAR: one for the simplesample_http example itself (i.e. simplesample_http_MSP_EXP432E401Y_tirtos_iar), and the other is a project corresponding to the OS chosen (e.g. tirtos_builds_MSP_EXP432E401Y_release).
2. The example comes with a README.html file that contains more details specific to the example. Be sure to take a look as it may contain additional instructions.
3. Update the example to use your Azure connection string, as specified in the section Example Pre-Build Steps
4. Make/Build the Example Project by first selecting the OS project tab on the Workspace window and select Project > Make. Once done, select the simplesample_http tab on the Workspace window and select Project > Make.

Load and Run the Example

1. Plug the LaunchPad into a USB port on your PC.
2. Select Project > Download and Debug
3. Run the application by pressing F5.
4. The Example output is displayed in the serial terminal, as shown here.

Building with Makefiles

These steps refer to the simplesample_http application, but the same procedure applies to other examples as well.

1. It is assumed that the SimpleLink MSP432E4 SDK has already been installed in a directory we will refer to as <SIMPLELINK_MSP432E4_SDK_INSTALL_DIR>. You should install it if you have not already done so, as the MSP432E4 Plugin for Azure IoT depends on the MSP432E4 SDK.
2. 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 SimpleLink MSP432E4 SDK, so please ensure you have updated the latter with the appropriate paths as well if you have not done so previously.
3. Navigate to the directory corresponding to your OS and toolchain of choice. For example, <SIMPLELINK_MSP432E4_SDK_INSTALL_DIR>/kernel/tirtos/builds/MSP_EXP432E401Y/release/ccs for tirtos and TI (CCS) toolchain.
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_x_xx_xx_xx_core\gmake.exe). Normally XDCTOOLS are installed along with the MSP432E4 SDK, but if you need to download it, it is available here.
5. Navigate to the example folder: <AZURE_INSTALL_DIR>/examples/rtos/MSP_EXP432E401Y/azure/simplesample_http
6. Read the README.html file of the example, and follow any additional instructions specific to the example if present.
7. Update the example to use your Azure connection string, as specified in the section Example Pre-Build Steps
8. Navigate to the example folder specific to your OS and toolchain <AZURE_INSTALL_DIR>/examples/rtos/MSP_EXP432E401Y/azure/simplesample_http/tirtos/ccs
9. To build, run ‘make’ to generate simplesample_http.out
10. You can load and debug the generated simplesample_http.out in CCS (or IAR)
11. The Example output is displayed in the serial terminal, 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 these steps:

1. Fill out imports.mak file from the MSP432E4 SDK with the paths to your XDC tools installation (XDC_INSTALL_DIR) and the compiler toolchain(s) of your choice. Leave empty the *_ARMCOMPILER variables for the toolchains you don’t wish to build for.

2. Update the imports.mak file in the <AZURE_INSTALL_DIR> root folder with the appropriate path(s)

3. Open a Windows command prompt or Linux terminal.

4. In the terminal window, run the following commands (be sure to replace <AZURE_INSTALL_DIR> with your installation path, and use gmake.exe from your XDC tools installation in <XDC_INSTALL_DIR> instead of make if you are a Windows user).

   cd <AZURE_INSTALL_DIR>\source\third_party\azure-iot-pal-simplelink\build_all
   make clean
   make all
   

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, 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.)

This step does not apply to the examples that use the Device Provisioning Service (DPS), which obtains the device credentials through a registration process.

Load the Root Certificate

Note: In the examples, the root CA certificate - “Baltimore CyberTrust Root” is loaded into an object named /cert/ms.pem. This name must match SL_SSL_CA_CERT in <AZURE_INSTALL_DIR>\source\third_party\azure-iot-pal-simplelink\pal\inc\cert_sl.h, and has been setup correctly for you by default.

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.

Other Info

More CCS project information can be found here and here.