Migration Guide for SimpleLink MSP432P4 SDK

Table of Contents

The SimpleLink™ MCU portfolio offers a single development environment that delivers flexible hardware, software and tool options for customers developing wired and wireless applications. With 100% code reuse across host MCUs, Wi-Fi™, Bluetooth® low energy, Sub-1GHz devices and more, you can choose the MCU or connectivity standard that fits your design. A one-time investment with the SimpleLink software development kit (SDK) allows you to reuse often, opening the door to create unlimited applications. For more information, visit www.ti.com/simplelink

The SimpleLink MSP432 Software Development Kit (SDK) is a set of software development tools that enable engineers to develop applications specifically on the MSP432 micro-controller family. This powerful software toolkit provides a cohesive and consistent software experience for MSP432 users by packaging essential software components such as TI RTOS, peripheral drivers and easy-to-use examples in one easy-to-use software package. Developing code with the MSP432 SDK ensures future-proofed portability and scalability.

The SimpleLink MSP432 SDK is the successor to MSP432Ware, and brings with it many advantages that are highlighted in Section 3.

This SDK brings users into a software development framework that allows for a consistent look and feel among multiple TI embedded products spanning both connectivity and host MCUs. The following are key advantages of the SDK:

3. Migration Overview

This document is intended for current MSP432 users that are using MSP432Ware v3.50.00.02 as a development platform for the MSP432P4x family of devices. It details migration considerations for users accustomed to software components delivered via MSP432Ware and is a helpful guide to locate these components in the context of the MSP432 SDK.

If the MSP432 SimpleLink SDK is your starting point, refer to the document SimpleLink MCU SDK User’s Guide and Quick Start Guide

This document does not apply to MSP430 users developing with the MSP430Ware ecosystem.

The SimpleLink SDK is made up of multiple components that offers differing layers of abstraction. This enables full control for the developer, allowing them the flexibility to turn the dial up and down between code portability and code optimization. While the SDK has changed the method of how TI components such as device header files are delivered, it does not change the actual contents of these components.

If you are an MSP432Ware user and your existing project:

4.1 Minimum Requirements for using the SDK

IDE Requirements

When using the SimpleLink MSP432 SDK package, it is recommended to use Code Composer Studio. The SDK is also supported by IAR and KEIL. Version information is given below.

Hardware Requirements

It is important to note that the MSP432P401x Revision C or newer is required to use the SDK. Older device revisions are not compatible with the SDK.

If you are using MSP432P401x Revision A/B or the MSP-EXP432P401R Black LaunchPad, please order new samples from http://www.ti.com/product/msp432p401R or the MSP-EXP432P401R Red LaunchPad from http://www.ti.com/tool/msp-exp432p401R prior to using the SDK.

You can also use XMS432P401R Revision C or MSP432P401R Revision C devices with the MSP-TS432PZ100 Target Socket Board or any custom board of your choice.

4.2 SDK Overview

This section serves as a quick introduction to the SDK file structure and key components. To understand the detail about the core components delivered by TI RTOS refer to the document SimpleLink MCU SDK User’s Guide

The SimpleLink MSP432 SDK is a single installer that delivers the following key components:

  1. Examples: A wide range of examples are provided. Their purpose is to make it easy to start writing applications in the context of the SDK. The examples take advantage of the other components in the SDK to implement meaningful and representative functionality. Each example comes with its own documentation and project files for a selection of the supported IDEs and code generation tools.

  2. TI Drivers API: This API layer exposes functionality of the hardware-specific drivers in the same way across all TI SimpleLink devices. For example, though the hardware implementation of the UART may be different on different devices, the TI Drivers API used to access its common functionality is the same. Note that TI Drivers are intended to be “full functional” drivers and include calls to the hardware abstraction layer (driver library), TI RTOS etc. An example of a TI Driver API to read the ADC: ADC_convert(adc, &adcValue0);

  3. MSP432 Driver Library: For the MSP432 product family, Driver Library is available in the device ROM. These are hardware-specific drivers that are primarily intended to serve as a hardware abstraction layer and configure bits at the register-level for the user. MSP432 driver library APIs handle interrupts, timing, memory management etc. MSP432 Driver Library is the abstraction layer below TI Drivers APIs. An example of an MSP432 Driver Library API to read the ADC: uint_fast16_t ADC14_getResult(uint32_t memorySelect);

  4. TI RTOS: The RTOS kernel offers services such as timing and scheduling of tasks. All TI SimpleLink SDKs come with the TI-RTOS kernel (SYS/BIOS). Some SDKs also offer examples that use alternative RTOS kernels (such as FreeRTOS) or examples that do not use an RTOS. Note that FreeRTOS requires a separate install from http://www.freertos.org/

  5. Device Header Files: These are the .h files that map device-specific registers and bit fields to addresses in the CPU address map.

Understanding the SDK directory structure helps to easily locate the above components. The SDK directory structure is organized as follows:

  1. Docs: This folder contains all the software documentation relevant to understanding and using the MSP432 SimpleLink SDK. This includes both Users and API Guides as well as release notes.

  2. Source: This folder contains the source files, Device-specific header files,TI Drivers API, MSP432 Driver Library and other peripheral libraries such as grlib, iqmathlib etc.

  3. OS: This folder contains the source for TI RTOS and components required to support FreeRTOS

  4. Examples: The example folder is split in “OS” and “non-OS” sections. The “non-OS” section provides register-level (bare metal) code examples that are implemented without the framework of TI RTOS.

4.3 SDK FAQ

  1. Is this update optional or mandatory?

    For new or early MSP432 Users, it is strongly recommended to start your software development using the SDK and TI Drivers. This prevents the need for future software migration and ensures you can always receive the latest device header files, updated libraries etc. Leveraging TI Drivers when creating application code ensures portability across all MCUs in the SimpleLink family as well as lowers the complexity of software design.

    For existing MSP432Ware users, the SDK update is currently not mandatory. TI will continue to make available as a stand-alone installer, MSP432Ware 3_50_00_02. However all future maintenance efforts will be directed towards the SDK and MSP432Ware will no longer be updated for bug fixes, patches or new device support.

5. Migration Considerations

This section only covers the non-OS aspects of migration. For TI RTOS users, refer to Section 6 of this document to understand how to migrate to the latest version of TI RTOS.

Also, as stated before the SDK supports MSP432P401x Revision C or later. If you are currently using XMS432P401x Revision A/B devices refer to this application report to understand the device-specific considerations when migrating to Revision C.

If you are an existing MSP432 user, before you begin migrating your project to the SDK framework, review the components in your code base.

Project Components Review

First, it is important to understand which TI-provided components are being used in your project. The sections below address how to migrate each of these components from the MSP432Ware to the SDK framework.

1. Device Header Files

Check and note down source files that use include paths in your project for files such as msp432.h or msp432p401r.h

If your project was built from the ground up using custom libraries or direct register access code, then your only dependency is the IDE-provided header file. In this case, the migration to the SDK is very simple. Follow the steps below to migrate your project to the SDK-based header file:

  1. Download and install SDK
  2. Ensure you are using the correct CCS version
  3. Open your project in CCS via Project –> Import CCS Projects
  4. Change the header file include path to point to the SDK-based header file. Directions on how to do this are provided in the step-by-step examples below.
  5. Build your project

2. MSP432P Driver Library

Your project may include driver library either as a source or link directly to the ROM-based driverlib.lib

In such cases, the recommendation is to delete the driver library source and link to the latest SDK-provided version. This ensures any changes or bug fixes to driver library are automatically utilized by your SDK-based project.

For detailed instructions on how to do this, refer to step 5 and step 6 in section 5.1.2.

3. Additional TI libraries

Check if your project includes either source or library components from any of the following TI-provided libraries:

Each of these libraries may require unique migration steps. Refer to the corresponding release notes for library-specific information.

5.1 Step-by-Step Migration Examples using CCS

As mentioned previously, this section only covers non-OS based projects. Many of the specific migration tasks such as using the SDK-based header files remain the same for OS-based projects. However the user needs to ensure that the RTOS-based components are migrated first (see section 6) before working on the MSP432-specific header files and libraries.

There are two ways to migrate your existing MSP432 project:

Option 1: Use a standard SDK template and copy source code and header files from any existing project into the SDK template project.

OR

Option 2: Keep your existing project as-is and only migrate the TI-provided header files and libraries to use the SDK-based versions instead of the MSP432Ware version.

We highly recommend Option 1 i.e. using the standard SDK template and copying over source files since the SDK-based components are pre-setup and it is the fastest and most efficient migration path especially if multiple TI libraries are being used.

Also, this document assumes the SDK package was installed in the default directory location of C:/TI. All file names and paths are referenced to C:/TI.

5.1.1 Migrating to a new project by using the standard SDK template

The easiest way to get started with migration is by using the standard SDK template project as a starting point and then copying over custom source and header files.

The SDK template project is available in your SDK install directory (default: C:/TI) under the Examples -> nortos folder.

To migrate your project using the standard SDK template:

Change header file include paths as shown below:

`#include "driverlib.h"` =====> `#include <ti/devices/msp432p4xx/driverlib/driverlib.h>`
`#include "grlib.h"` =====>  `#include <ti/grlib/grlib.h>`

Now, you have successfully migrated your existing project to use the SimpleLink SDK.

Important Note: the IDE’s ‘Create New Project’ options does NOT support the SDK template by default. So do not use this option to setup an SDK project.

5.1.2 Retaining existing project and migrating TI components only

This option is only useful if you prefer not to change the file or folder structure of your existing project code. In such cases, you can follow the steps below to modify an existing project and port it to use SDK resources such as libraries and headers.

Also, you can only use this approach if your existing project did not use an RTOS. For migrating TI RTOS based projects refer to Section 6.

The steps provided below are intended to teach you the process of migration by using an MSP432Ware example project as a starting point. Alternatively you can use any custom MSP432 project (direct register access or driver library based) as your starting point.

Step 1: Open an existing (non-SDK) MSP432 project

Open a non-SDK MSP432Ware project in the preferred CCS workspace. If you have MSP432Ware installed, you can find example projects under C:\ti\msp\MSP432Ware_3_50_00_02\driverlib\examples\MSP432P4xx

Note that this exercise uses an MSP432Ware project as a starting point. Alternatively you can use your custom project code base or other example projects from MSP432Ware.

Step 2: Setting up the environment variable

To setup the environment variable to point to the SDK Install path, right click on the Project name.

If this step is executed correctly, you should be able to see the SDK install path in the environment variables tab as per below screen capture.

If no variables are seen, check the “show system variables” box in the screen capture below.

Step 3: Using SDK provided device header files

To migrate to the SDK-provided device header files,

Step 4: Using SDK provided CMSIS files

To migrate to the SDK-provided CMSIS files,

Remove ${CCS_BASE_ROOT}/arm/include/CMSIS

Add ${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source/third_party/CMSIS/Include

The final setup from steps #3 and #4 should look like image below.

Step 5: Using SDK provided Startup and System files

To migrate to the SDK-provided startup/system files,

These files can be found in the following directories: ${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source/ti/devices/msp432p4xx/startup_system_files/ccs/startup_msp432p401r_ccs.c ${COM_TI_SIMPLELINK_MSP432_SDK_INSTALL_DIR}/source/ti/devices/msp432p4xx/startup_system_files/system_msp432p401r.c

Note that the start up file no longer sets up interrupts as “default ISR” instead each ISR is assigned a unique name. Depending on how your project was setup you may need to port the ISR name into the start up file.

Step 6: Using the SDK provided TI Libraries

The preferred method to use TI libraries is to link the pre-built library instead of copying the source into the project. Although copying library source into your project will produce working results, using a linked library makes it easier to port/maintain a project when updating to a newer SDK.

MSP432 Driver Library

To migrate to the SDK-provided Driver Library,

Under “Add dir to #include search path (–include_path, -I)”: If this path is included, then remove it "${PROJECT_ROOT}/driverlib/MSP432P4xx"

Refer to the image below for how to link Driver Library:

After Driver Library is linked in your project, you will also need to change the Driver Library include path to point to the SDK-provided files.

Graphics Library

Migrating Graphics Library from MSP432Ware to MSP432 SDK requires additional changes to LCD Drivers, Refer to Graphics Library Migration Guide for further instructions

IQMath Library

To migrate to the SDK-provided IQMath Library,

Refer to the image below for how to link IQMath Library:

Now all project components have been migrated to the SDK and you can build your project successfully!

5.2 Step-by-Step Migration Examples using IAR

As mentioned previously, this section only covers non-OS based projects. Many of the specific migration tasks such as using the SDK-based header files remain the same for OS-based projects. However the user needs to ensure that the RTOS-based components are migrated first (see section 6) before working on the MSP432-specific header files and libraries.

Configuring Custom Argument Variables

Before starting to work with any of the projects in the SDK, you need to load a set of variables that will be set for your current workspace. This is done using the following steps: