SimpleLink MSP432 SDK Bluetooth Plugin is made as a complimentary software package that adds full BLE capabilities to your
SimpleLink MSP432 SDK projects. This training/exercise session is designed to provide a detailed introduction to the SimpleLink MSP432 SDK Bluetooth Plugin as well provide an in-depth view of the mechanics behind the various components included within the plugin itself. The concepts of a
simple application processor and a
simple network processor are also examined and the relevant software libraries are described in detail.
Suggested SimpleLink Academy Labs
- TI-RTOS Basics
- Bluetooth low energy Fundamentals
- Bluetooth low energy Custom Profile
- SimpleLink SDK Plugins Overview
- Code Composer Studio v7.1.0 and newer or Code Composer Studio for Cloud
- Generic BLE Application
Attach the CC2650 BoosterPack on top of the MSP432 LaunchPad while being very careful not to bend any pins. When finished, the stacked configuration should look similar to the image below:
Alternatively, the CC2640R2 LaunchPad can be used in lieu of the CC2650 BoosterPack. In this case the CC2640R2 LaunchPad should be stacked on the MSP432 LaunchPad as seen below. Make sure to disconnect the jumpers between the debugger and the CC264R2 as seen below:
SDK Plugin Overview
Plugins are intended to extend functionality of each individual platform SDK to include specialized use-cases. These specialized use cases can range anywhere from adding wireless functionality to extending a platform SDK's example base.
While all of the plugins have the same basic structure and look-and-feel of an SDK, they are not meant as standalone applications and rely heavily on components from the platform SDK. The SimpleLink MSP432 SDK Bluetooth Plugin, for example, relies heavily on the TI-Drivers, RTOS kernels, DriverLib, and GraphicsLib components from the platform SDK. A high level block diagram of these dependencies can be seen in the image below:
It is important to note that each plugin contains all of the necessary components to function fully alongside the base SDK. Plugins do not install inside of the SDK, but rather in a folder next to the SDK. This is to simplify the maintenance model as well as provide customers with an organic experience for updating and switching between plugin versions.
Currently, the planned plugins focus on wireless connectivity. Future plugins are planned to expand the base functionality of the SDK for application specific use cases. The SimpleLink MSP432 SDK Bluetooth Plugin is designed to add BLE radio functionality to your MSP432 project. This has the benefit in leveraging the horsepower, extended analog, and rich memory footprint available on the MSP432 while still utilizing the BLE functionality on the CC26xx device.
SimpleLink SDK Plugins on Resource Explorer
A full list of plugins can be found in the "SDK Plugins" folder on TI Resource Explorer
SimpleLink Academy Plugin Lab
For a more in-depth look into the concept of SimpleLink SDK Plugins, please refer to the SimpleLink SDK Plugins Overview SimpleLink Academy module.
About the Simple Network/Application Processor
Before getting started with the labs, let's go over some of the basics of network processor projects tat are included within the SimpleLink MSP432 SDK Bluetooth Plugin. TI has created a wealth of resources to support these application processor projects. For supplementary reading, it is recommended that the user take a look at the resources in the table below:
|BLE Network Processor Wiki||A high level page describing network processor options for the CC2640|
|Unified Network Processor Interface||Page describing the technical implementation of the transport layer between NP and AP devices|
|Simple Network Processor API Guide||PDF that explains the commands that can be sent to the SNP over a serial link. This guide can be found in the documents folder of the BLE-Stack|
A block diagram of the simple network/application processor system is shown below.
Simple Network Processor (SNP)
simple_np (referred to simply as SNP from here forward) is the simplified network processor. In the context of the MSP432 + CC26xx solution this is the CC26xx device that the MSP432 relies on for BLE communication. From the diagram above it can be seen that the entire BLE stack resides on the
SNP. This means that all of the BLE protocol processing is done by the
SNP, thus freeing up the application processor for other tasks.
Remote procedure calls
The application processor can configure the
SNP in a number of ways, using an API that is based on serial
Remote Procedure Calls. The serial protocol used to encode the procedure calls is called
Unified Network Processor Interface (UNPI). The
UNPI is a transport layer that is developed by TI to implement a link to the
SNP that is standardized across multiple physical transports such as SPI and UART. It can also be used for user-implemented procedure calls, for example offloading control of an external sensor to the network processor.
UNPI will be covered in greater depth later in the lab. A link to the detailed UNPI protocol description is given in the table above.
UNPI as the serial transport protocol, the
SNP can be configured and controlled using the specific
SNP serial API described in the
Simple Network Processor API Guide in the table above.
Modes of operation
SNP supports the
Peripheral GAP role, and thus is ideal for a dual MCU solution to allow connections to be made to the device from, for example, a smart phone.
Covered in more detail later, the
SNP API allows the user to define specific services on the application processor, which will be visible to peer devices over the air, and to control the content of the always present
Generic Access Service and
Device Information Service. As these are always present, and requests to read these are handled by the
SNP, no space is wasted on the application processor.
Project Zero Code Example
ProjectZero project for MSP432 is provided as a sample application processor task which controls the CC26xx network processor device via a serial interface. It provides a mechanism to broadcast/expose multiple properties of components residing on the MSP432 application processor.
Mechanics of the Code
The code model of the Project Zero code example is separated into three main components/tasks:
- BLE Connection/Advertising Management Thread - Manages broadcasting the BLE device as well as interaction to the underlying SAP driver. All callbacks from the
SAPlayer call back to this task where event handling occurs.
- SNP Update Thread - This thread is tasked with updating the
SNPdevice with a firmware image stored in the MSP432's local flash memory
- Button Management Thread - This thread is responsible for managing button presses for the button service
Advertised BLE Characteristics
Every BLE application that is part of the
SimpleLink MSP432 SDK Bluetooth Plugin will include one or more BLE "profiles". These profiles are source files that consist of all descriptor information and logic needed to expose several BLE "services" and "characteristics" over BLE. These services and characteristics are the bridge between the user application and the BLE client.
For the Project Zero example, the profile information is contained in the
led_service.c, button_service, and data_service files under the
Profile folder. As stated in the documentation for the code example, these characteristics are listed below:
|LED Color Control||F0001111-0451-4000-B000-000000000000||Integer||Read/Write||led_service.c|
|S1 Button Status||F0001121-0451-4000-B000-000000000000||Integer||Notification||button_service.c|
|S2 Button Status||F0001122-0451-4000-B000-000000000000||Integer||Notification||button_service.c|
|Data String Storage||F0001131-0451-4000-B000-000000000000||UTF-8 String||Read/Write||data_service.c|
|Data Stream||F0001132-0451-4000-B000-000000000000||Integer||Notification/Write No Response||data_service.c|
Profiles describe how certain Services should be used. Services are a collection of characteristics, which in turn are the primary vehicle for transmitting data over BLE. To learn more about services and how they work, complete the Bluetooth low energy Basics and Bluetooth low energy Custom Profile labs.
Every profile that is included in the plugin is documented in detail in the User's Guide. In the case of the button profile, both exposed characteristics are of the
Notification variety. This means that when a button press happens on the LaunchPad a notification is sent out over BLE to any attached subscribers.
The application processor (the MSP432 in this case) is responsible for maintaining custom profiles. When data from custom profile is requested by a wireless peer device, a serial UNPI request is received by the application processor. The application processor then has the choice of remembering a stored value and transmitting that back, or actively computing the requested value. Similarly when the application processor wants to write data to a central device, it will notify the
Extended MSP432 Support
Currently the SimpleLink MSP432 SDK Bluetooth Plugin only supports the MSP432 as the application processor, however support for other SimpleLink devices (such as the CC3220) is currently planned for a follow-on release.
Simple Application Processor (SAP)
Simple Application Library (shortened to
SAP from here forward) is a reference project provided in source by TI to translate local
SNP API function calls into remote serial requests to the network processor and to parse the response.
Contained in the SAP library project is
- A master-side implementation of the Unified Network Processor Interface(UNPI)
- The entire BLE SNP subsystem that handles framing
UNPIcommands to be sent to the
- An abstraction / translation layer for these commands.
The user needs to only build the
SAP library for their selected RTOS capable processor and interface with the API to get started with BLE. Since the library is provided both in source and library form, the low level functionality may be modified, such as adding a custom
UNPI subsystem to handle peripheral control in addition to
SNP commands. See the graphic below for the composition of the
What services are manged by the SNP?(multiple correct answers)
Select the layers encapsulated in the SAP Library.(multiple correct answers)
The Unified Network Processor interface handles the framing and sending of serial data between the application processor and the
SNP supports UART or SPI transport layers, UNPI sits above these protocols and interfaces with their drivers.
To better understand how the system works and how the two processors interact, we will trace a Characteristic Write Indication from the
SNP to the application processor.
When the central device (i.e. a mobile application) writes a characteristic such as char3, the
SNP does the necessary BLE protocol stack processing, and then-if the characteristic is managed by the application processor-forwards this request to the application processor task for further processing. A sample logic capture of the
UNPI frame corresponding to a write request is shown below.
Look at the Unified NPI Frame Format taken from the Unified Network Processor Interface wiki page shown below. Try to decode the frame format.
Based on the
UNPI frame from the logic trace above, what is the value of the CMD0 field?
Now try and match the payload of the above frame to this excerpt from the
simple_np API guide on the Characteristic Write Indication command. All supported SNP API commands are detailed in this document.
Does the application processor need to respond to this indication?
UNPI interface is implemented as a task running on the SAP device (in our case the MSP432). Upon receiving this command the over serial interrupts and callbacks will be triggered in the
UNPI code to read the frame into the application processor. The CMD0 field indicates whether the command was synchronous or asynchronous. Based on CMD0, corresponding RPC will be kicked off. This is forwarded up the SAP abstraction layer, which will then trigger the proper callback within the application layer. Since this is all in the provided library, the application processor developer doesn't need to modify this code except for custom use cases.
Project Zero Task
After opening the SAP module using SAP_open the application processor is ready to send and receive
UNPI frames. Before this however, the application processor task (i.e. ProjectZero) makes a call to
LEDService_registerAppCBs(), ButtonService_registerAppCBs(), and DataService_registerAppCBs() in it's init function, which allows the application layer to be notified of changes in the LED service, button service, and data service. Specifically the
ProjectZero_processLEDServiceCB callback function is executed whenever the
SNP sends a write indication to the application processor for a characteristic in the LED service.
Running/Using Project Zero
Importing Project Zero into your IDE
From the TI Resource Explorer, navigate to the
Project Zero code example under the
Examples menu item. This code example is located under Software->SimpleLink SDK Plugins->Connectivity->SimpleLink MSP432 SDK Bluetooth Plugin->Examples->Development Tools->MSP-EXP432P401R->Bluetooth->project_zero->TI-RTOS->CCS Compiler->project_zero:
Note that version numbers might slightly vary from your configuration to the screenshots below.
Before any code examples can be imported into your local CCS installation, the SDK Plugin and the SDK both need to be made available offline. To do this, click the Install on Desktop button to the top right of the code example and select Make Available Offline.
Code Composer Cloud Support
All of the code examples included in the SimpleLink MSP432 SDK Plugin are supported with Code Composer Studio Cloud Tools. When using Code Composer Studio and TI Resource Explorer from the cloud the software packages do not need to be made available offline.
Note that while this training module uses Code Composer Studio and TI-RTOS, third party IDEs and FreeRTOS are completely supported by the SimpleLink MSP432 SDK Bluetooth Plugin.
This will prompt you to install the SimpleLink MSP432 SDK Bluetooth Plugin to the desktop to make available for offline use.
SimpleLink MSP432 SDK Requirement
As the SimpleLink MSP432 SDK Bluetooth plugin requires the base SimpleLink MSP432 SDK, TI Resource Explorer will prompt you to install the SimpleLink MSP432 SDK if it is not already installed. Make sure to follow the prompts to also make the SDK available offline.
To import the project into your workspace, click the Import to IDE button.
Once your project has been imported into your IDE it can be built and run the same as any regular Code Composer Studio project.
Programming the SNP
Note that before using the CC2650 or CC2640R2 as a network processor the user must first ensure that the appropriate
SNP firmware is flashed onto the CC26xx device. Various configuration of this
SNP image exist such as different power saving modes and bootloader options. As the MSP432 is marketed as a "high performance low power" device, we will be using the power saving mode with internal bootloader enabled. Once the Bluetooth Plugin has been installed to your local directory, the hex images for each configuration will be found in the install_root/source/ti/snp folder. Each hardware configuration will have a different hex image associated with it, however the two recommended configurations can be found below:
- CC2650 BoosterPack - simple_np_cc2650bp_uart_pm_sbl.hex
- CC2640R2 LaunchPad - simple_np_cc2640r2_uart_pm_sbl.hex
Find these images and program to your device using the appropriate method documented below.
External/XDS Direct Programming - CC2650 BoosterPack
The user can directly attach the CC2650 BoosterPack to an external programmer and program the CC2650 using the TI SmartRF Flash Programmer 2. To do this the user must first download and install the TI SmartRF FlashProgrammer 2 software utility from TI. Next, an external programmer must be attached to the CC2650 BoosterPack. This can be an external XDS debugger, however the XDS110 debugger that is embedded on the MSP432 LaunchPad can also be used with a standard 10-pin ARM programmer cable. Note that this cable also comes packaged with the CC2650 BoosterPack. To use the MSP432 LaunchPad’s XDS110 programmer, first remove all of the jumpers between the MSP432 and XDS110 with the exception of GND and 3V3 as shown belown.
GND and 3V3 are required to power the CC2650 during the programming process.
Next, attach the ARM programmer cable between the XDS110 and the CC2650 BoosterPack and stack the CC2650 BoosterPack on the MSP432 LaunchPad as shown in the following picture:
After attached, open up the SmartRF FlashProgrammer 2 program. Once opened, the program should show the XDS110 in the list of devices on the left. Note that if an “Unknown Device” is shown under the XDS110 instead of the CC2650, click the “Unknown Device” and then follow the prompts for updating the XDS110’s firmware. Once the CC2650 is detected (this should happen immediately), click the “Browse” button and locate the SNP hex image that you would like to download to the CC2650:
Once the SNP hex file is selected, press the “Play” button and the firmware should be downloaded/verified to the CC2650:
Once programmed, disconnect the programming cable and reconnect the jumpers in between the XDS110 and the MSP432 on the LaunchPad.
External/XDS Direct Programming - CC2640R2 LaunchPad
Programming the CC2640R2 LaunchPad with an external programmer is a bit simpler than the CC2650 BoosterPack as the CC2640R2 LaunchPad has an XDS110 debugger embedded on the LaunchPad. To program the CC2640R2 LaunchPad simply plug in the device to your computer through USB (make sure the jumpers between the debugger and LaunchPad are all connected):
After attached, open up the TI SmartRF Flash Programmer 2. program. Once opened, the program should show the XDS110 in the list of devices on the left. Note that if an “Unknown Device” is shown under the XDS110 instead of the CC2640R2, click the “Unknown Device” and then follow the prompts for updating the XDS110’s firmware. Once the CC2650 is detected (this should happen immediately), click the “Browse” button and locate the SNP hex image that you would like to download to the CC2640R2:
Once the SNP hex file is selected, press the “Play” button and the firmware should be downloaded/verified to the CC2640R2:
Once programmed, disconnect the programming cable remove the jumpers on the CC2640R2 LaunchPad that run between the CC2640R2 and the XDS110:
Running Project Zero
Build and run your application. After running your application it will initialize the
SNP and then automatically start to advertise over BLE. Once advertising, both LED1 and LED2 on the LaunchPad will illuminate red as seen below:
Once advertised, open up your BLE mobile application (as described in the software requirements section for this lab). Making sure Bluetooth is enabled on your phone, a device list should appear at the device list of your application. Note that in the screenshots below we use the LightBlue Explorer for iOS, however BLE Scanner for Android will have comparable functionality:
Note that due to caching on iOS devices that it may be necessary to disable and re-enable Bluetooth in order for the correct BLE name to display.
Touch the entry for your device name. After negotiation/handshaking, the device information will be shown and the button, LED, and data characteristics will be shown (you may have to scroll down):
How to manipulate and control these profiles/characteristics is described in detail in the sections below:
LED Service (UUID: F0001110-0451-4000-B000-000000000000)
The LED service allows users to remotely control and manipulate the on-board tricolor LED of the LaunchPad. This LED is connected to the LED2 pin at the bottom of the MSP432 LaunchPad. The sole characteristic of the LED Service is a three byte hex string. This string equates to RGB values on the LED. The highest byte represents the red value, middle byte represents the green value, and lowest byte represents the blue value. By default, this value is set to 0x000000:
If this value was set to 0x0000FF, for example:
This would result in the LED on LED2 being set to blue:
Values can be combined in any fashion or manner to create any color combination that you want. A value of 0xFF00FF being written to the characteristic:
Would result in a purple color being shown on the LED (full blue plus full red):
Button Service (UUID: F0001120-0451-4000-B000-000000000000)
The button service of Project Zero provides a way for an application to monitor and observe the state of a button press on the LaunchPad. This feature might be useful for applications such as key pads or remote access door bells. In order, the map of the button service's UUIDs to the LaunchPad's buttons are as follows:
- UUID: F0001121-0451-4000-B000-000000000000 - S1
- UUID: F0001122-0451-4000-B000-000000000000 - S2
The buttons' physical location on the LaunchPad can be seen in the image below:
From the main device menu, select the first characteristic (UUID: F0001121-0451-4000-B000-000000000000) that corresponds to button S1:
For this characteristic, a numerical value of 1 represents that the button is pressed and a value of 0 means that the button is released. Select enable notifications for the characteristic and then press and hold S1 on the LaunchPad. A notification value of 1 should appear in the window:
Now release the button. A notification value of 0 should show up in the notifications:
The previous process can be followed on the second UUID to enable notifications for S2. Note that notifications can be enabled/disabled for as many characteristics as desired in parallel.
Data Service (UUID: F0001130-0451-4000-B000-000000000000)
The data service for Project Zero demonstrates a couple of different data storage/streaming capabilities. The first property in this service simply holds an UTF-8 string that can be up to 40 bytes long. Once written, a response in automatically generated and read. Open up the characteristic and try to write a new string value (you may need to set your mobile application to display in string format):
Once written, the new value should be persisted to the characteristic and immediately read back through a response:
The second characteristic demonstrates the use of the SNP_GATT_PROP_WRITE_NORSP property. A characteristic with this property signifies that the BLE device will not send a response to the host after the write is successful. This is useful when transferring large chunks of data by reducing response overhead. This characteristic also has notification enabled to illustrate the writing of data. Open this characteristic and enable notifications. With notifications enabled, write an arbitrary value to the characteristic:
Once written, the new value will show up through the notification stream:
SimpleLink SDK Explorer
SimpleLink SDK Explorer is a customized mobile application from Texas Instruments that is designed to compliment various aspects of the SimpleLink SDK mobile ecosystem. Currently this application is available for iOS devices. Android support is currently not available. The code examples included in the SimpleLink MSP432 SDK Plugin are fully modeled and showcased as a part of SimpleLink SDK Explorer. From the Apple AppStore search for SimpleLink SDK and download the SimpleLink SDK Explorer. Open the mobile application once it has been downloaded.
From the main screen select the Profile Examples menu item. This will take you to a list of profile examples that correspond to each code example in the SimpleLink MSP432 SDK Bluetooth Plugin:
Select the Project Zero menu item. On the next screen SimpleLink SDK Explorer will automatically scan for BLE devices in your vicinity. By default the Project Zero application advertises and shows up as "Project Zero":
Press on Project Zero to connect to the device. After negotiation the view for the LED service will appear. This view contains a color wheel and brightness view that will change the color of the tri-color LED on the MSP432 LaunchPad. Press different parts on the color wheel to change the LED's color.
Select the button service on the tab bar at the bottom of the screen. This will switch to the view for the button service. Whenever a button or combination of buttons is pressed on the MSP432 LaunchPad (either S1 or S2) the buttons displayed on this screen will highlight and a tone will play (make sure your device is not muted). Press S1 and S2 on your LaunchPad to see the buttons toggle on the application.
Select the data service on the tab bar at the bottom of the screen. This will switch to the data service view. On this screen you can select the normal WRITE characteristic or the WRITE_NO_RSP characteristic. Try to write to either of these characteristics. For the WRITE characteristic a response value is read after the write and displayed in the log window. For the WRITE_NO_RSP characteristic a write will result in a notification being sent out and displayed in the log view.
Expanding your Application / Support
The code examples included in the
SimpleLink MSP432 SDK Plugin are meant to showcase the capabilities of the MSP432 application processor and the CC2650 network processor, however for a customer's application they will need to be expanded in order to be meaningful.
Specifically, the user will have to make a new BLE profile that exposes the features and functionality that they desire. It is best to use one of the provided code examples as a base and modify it to support your application. Refer to the User's Guide for a detailed description of each code example and for functional descriptions of each BLE profile. Please visit the e2e forum for product support and feedback.
This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.