Introduction

This workshop is a simple introduction for using TI Drivers within the Simplelink™ SDK. The goal for this project is to get you familiarized with your TI LaunchPad™ development kit, introduce you to TI Resource Explorer and the content delivered within, as well as create & compile a simple code example using CCS Cloud.

To get our feet wet, we are going to start basic & will learn how to blink an LED on our LaunchPad using the SimpleLink SDK. Specifically, we are going to be using "TI Drivers", a collection of easy-to-use APIs that provide abstracted, functional access to various peripherals. Note that TI Drivers are compatible across the entire portfolio SimpleLink MCU devices. To do so, we'll start with a code example...

Here's what we'll learn:

• Navigating TI Resource Explorer
• Getting familiar with the SimpleLink SDK & TI Drivers
• Importing projects into CCS Cloud

• Editing, building & flashing a TI LaunchPad using the browser-based IDE

  

Prerequisites

Software for desktop development

This tutorial can be done 100% with a web browser in the cloud. However, the exercises can also be completed using desktop/offline tools as well. If you want to run the exercises offline, you will need to download & install the following:

• CCS (refer to the SimpleLink SDK's Release Notes for recommended version)
• SimpleLink SDK for your given LaunchPad

Hardware requirements

• A SimpleLink LaunchPad Development Kit

Recommended Reading

• SimpleLink SDK Quick Start Guide
• SimpleLink SDK User Guide

Task 1 - Finding the Blink LED code example

a. Finding code examples using TI Resource Explorer

TI Resource Explorer has the ability to filter all of the development resources for a given context. In this case, we can filter & expose all content that is related to this specific LaunchPad. To do so, we can search for the device using the search bar on the top-left corner. Please type in "MSP432E4" (or whatever device you are using) into TI Resource Explorer.

Once filtered, developers can browse the available resources provided in TI Resource Explorer, which is broken up into 3 categories: Development Tools, Device Documentation, and Software. Also, while TI Resource Explorer is cloud-enabled, any of the delivered content can be downloaded locally onto your machine (i.e. to import code examples into a traditional IDE like Code Composer Studio). Alternatively, we can stay in the cloud & import code examples into TI's cloud-connected CCS Cloud IDE, which is what we'll be using for this example.

b. Look inside the "Software" category in TI Resource Explorer.

Here, you will see all of the SDKs that are available for your device/LaunchPad. In this case, we will be using the SimpleLink™ MSP432E4™ MCU SDK, so expand that folder to find documentation & code examples that are available within the SDK. You can learn more about the SimpleLink MSP432E4 SDK here, but for now, we will use one of the TI Drivers code examples.

You can find the code examples that showcase how to use the "TI Drivers" at Software > [SimpleLink SDK] > Examples > Development Tools > [LaunchPad] > TI Drivers > [Examples]

TI Drivers is a set of common, consistent functional APIs that are supported across the TI SimpleLink portfolio, enabling maximum code portability.

Few things of note. TI Drivers can be used with an RTOS or without one. All devices in the SimpleLink platform have support for TI-RTOS. Most SimpleLink devices also support FreeRTOS. However, rather than make direct calls to kernel-specific API calls, the TI Driver code examples leverage a Driver Porting Layer (DPL) to provide a consistent API layer on top of a desired kernel.

c. Let's look at the "empty" example.

The "empty" project is a template file that builds a framework for a new SimpleLink SDK-based project. In short, it creates a single-threaded application using POSIX APIs that toggles an LED pin high & low using TI Driver APIs. Note that there are several versions of each TI Driver example. An example is available based on TI-RTOS (and FreeRTOS for most SimpleLink devices). Additionally, there are variants that use either the CCS or GCC compiler. Select any version you like. In the screenshot below, we are going to use the TI-RTOS variant that uses the CCS compiler.

Software > [SimpleLink SDK] > Examples > Development Tools > [LaunchPad] > TI Drivers > Examples > empty

Additionally, note that each code example is packaged with a readme.html page, which includes helpful documentation offering an overview of each example. A Board.html page is also provided to show how some hardware resources can be accessed in your software (i.e. on-board LEDs, pushbuttons, etc.).

Lastly, without having to download or unzip anything, developers can easily explore the contents of the project. To see the code example source, click on the file within the project & the source will be presented within TI Resource Explorer. The main application for this project is "empty.c"

Task 2 - Importing code example into IDE

a. Import into CCS Cloud IDE

Now that we've identified our code example, we will go ahead and import it into CCS Cloud. We can do so by clicking on the cloud icon when the project folder is highlighted (shown in screenshot below). Clicking this will import the entire project into CCS Cloud, our cloud-based IDE. From there, we will have the ability to edit, compile, flash & even debug our code.

Note that developers also have the option to download this code example & its dependencies locally, which allows you to import these examples into a traditional offline IDE like CCS & IAR. However, for this quick tutorial, we'll stick with the cloud.

If you haven't already, click the cloud icon to import the "empty" example into CCS Cloud. You may be requeste to log into CCS Cloud

b. Getting familiarized with CCS Cloud

At this point, we have the ability to edit the code, compile/debug & more. This particular code example shows us how to use the GPIO TI Driver APIs to toggle an I/O pin high & low to blink an LED. You can learn more about this particular code example by again clicking on the Readme.html page that is provided with each example.

The CCS Cloud IDE offers a powerful development environment capable of running in a web browser (Chrome recommended). Within this tool, users can modify their code example, build their project & even debug.

CCS Cloud code editor offers lots of nifty features, including:

• Code folding
• F3 to jump to definition
• Code auto-completion
• Integrated serial monitor/terminal
• More!

CCS Cloud also offers debug capabilities

• Watch variables (and graph them too!)
• Set breakpoints
• Step through code line-by-line
• More!

c. Familiarizing ourselves with TI Drivers resources & documentation

Explore these files to get a quick introduction to this code example. Each example is packaged with one.

Board.html

This file provides an high-level overview of your board file & shows how you may address different resources available on your LaunchPad kit (LEDs, switches, I/O pins, etc.).

README.html/README.md

This file provides an overview for each example.

d. Taking a closer look at the source files

Let's take a look at the empty.c source file - simply double-click the file to open it up in CCS Cloud. In general, this "empty" project provides you with a framework that you can use as a starting point for your own project. It shows you where to include the header files for the TI Drivers you want to use (only the GPIO driver is used in this example). It also provides a framework for your main loop, which is running inside of a single thread called "mainThread."

Further down mainThead, we see our while(1) loop, which is our main loop for this simple example. Within this loop, we use another GPIO Driver API to toggle the pin. We do this once every second, which is determined by the sleep() function, which takes a parameter for number of seconds. The sleep() function is provided by the unistd.h header that is included in the "empty" project by default.

Another file to take a look at is "main_tirtos.c" or "main_freertos.c" - each example includes one of these files depending on the underlying kernel being used. However, since we are using POSIX in our TI Driver examples, these files are largely identical. Within this file, we configure the kernel, create & configure our thread(s) and set their priorities. For instance, we see that we use the POSIX API pthread_create() to create our mainThread, which is what we saw in our main empty.c source file.

Task 3 - Build your project

a. Build/compile your source code

To build your project, simply click the hammer icon. This will compile your code in the cloud & provide a .out file, which you can flash into your device. Alternatively, you can click on the Debug icon, which will compile your code & flash your hardware. It will also jump you into a debug session, where you can step through your code, set breakpoints & watch variables.

b. Let's load our LaunchPad!

To program our LaunchPad, we can click on the "Run" button in CCS Cloud. This will build our project & flash our hardware with the newly compiled image. This will take a minute or so. Once programmed, your LaunchPad will automatically start to execute the code & the LaunchPad's LED should start blinking!

Task 4 - Introducing UART Driver

We're going to focus on a more substantial driver now: the UART Driver.

a. Introducing the TI Drivers API Guide

First, the TI Driver APIs are fully documented within a doxygen-generated API Guide. The API Guide is available in TI Resource Explorer & is delivered within the SimpeLink SDK. You can find the TI Drivers API Guide here:

If using TI Resource Explorer:

[SimpleLink SDK] > Documents > Drivers > TI Drivers Runtime APIs (doxygen)

If browsing the downloaded product in your file system:

<SimpleLink SDK>\docs\drivers\tidriversAPIs.html

For each TI Driver, you will find a generic usage example, as well as instructions on how to configure & initialize the driver. All functions available for each TI Driver are fully documented to help you exercise the capabilities exposed by the driver.

b. The UART API set

The API documention is split between the high level UART interface (which might be the only UART APIs you use) and the device specific interface (which you might use for advanced features).

Click the UART.h file and you'll see the UART "Overview", "Usage", "Examples", and the APIs descriptions.

UART is like most of the other drivers. There are 3 main areas for the APIs

• init: All driver's init function UART_init must be called before any other driver APIs can be called. Before the drivers are initialized, the driver configuration must be completed.
• open: each peripheral instance (e.g. UART0, UART1, etc.) must be opened before it can be used. The open takes a parameter structure which sets up the driver instance.
• action APIs: once opened, a driver instance can be acted on. For example UART_read can be done with the handle returned from UART_open.

c. Import/Build/Run UART Echo

Back in Resource Explorer, Import UART Echo

Once imported, build and run it.

d. Using CCS Cloud's built-in Serial Monitor/Terminal.

You can open up a terminal by going to: Target > Connect COM Port

Select the COM port your LaunchPad is connected to. The UART Echo example defaults to 115200 Baud.

To see your incoming UART messages, take a look at the Debug tab & enable the "Serial" filter to see your messages echo'd back. Note: your need to type the message in the yellow highlight section.

Great! Now what?

Now that you're a bit more familiar with TI Resource Explorer, have some exposure with the SimpleLink SDK & have successfully built & downloaded a project to your LaunchPad using CCS Cloud, we recommend you start exploring the rest of the SimpleLink SDK and other modules of SimpleLink Academy.