Bluetooth Low Energy Fundamentals#
Introduction#
This workshop is an introduction to the Bluetooth® Low Energy (LE) part of the SimpleLink™ CC13xx and CC26xx Software Development Kit (SDK). The 4 tasks in this lab session are targeted to be completed within a 2-hour time frame. An intermediate level of knowledge of the C programming language and some experience with embedded software development is needed to be able to complete the tasks.
This lab session uses the LAUNCHXL-CC26X2R1, a SimpleLink multi-standard CC26X2R wireless MCU LaunchPad™ development kit to demonstrate the tasks in this module. The first task shows how to download a project to the device and run it, and the subsequent tasks will explore the wireless Bluetooth LE interface and make some small changes to the Bluetooth LE application.
For the latter tasks, either a Bluetooth LE enabled cell-phone or a LaunchPad
development kit running the TI host_test
Sample Application is required. The
advantage of using host_test
is that the TI tools, such as BTool
, can be
used.
Note
Kit and SDK compatibility
Multiple of the CC13xx and CC26xx development kits support Bluetooth LE operation. See the Hardware Requirement for details. In this lab we will use the CC26x2R Launchpad as an example, but the same applies for all.
It is recommended to read the TI BLE5-Stack User’s Guide (When reading older TI documentation, you may see references to the TI BLE Software Developer’s Guide. This guide was renamed to the TI BLE5-Stack User’s Guide in conjunction with the added support of Bluetooth 5) alongside this lab for details and further information. Some references will also be made to this document.
Prerequisites#
Hardware#
For this lab, you need one or two Bluetooth-enabled development boards. Supported devices are:
For testing:
Additional SimpleLink LaunchPad to run
host_test
ORMobile device for testing
Software#
CCS 12.1 or IAR 8.50.9 installed with support for CC13xx/CC26xx devices.
For testing, a Bluetooth client application is required:
BTool (located in the
tools\ble5stack
directory of the SimpleLink™ SDK installation) ORBluetooth mobile apps:
Android: TI SimpleLink Starter - available on the Google Play store
iOS: TI SimpleLink Starter - available on the App Store
Recommended Readings#
The CC13xx or CC26xx SDK Platform Chapter of the TI BLE5-Stack User’s Guide
Getting started – Desktop#
Install the Software#
Open Resource Explorer via View → Resource Explorer and find the SDK you want to install.
Download the offline installer from the SDK links above under
Prerequisites
Run the SimpleLink CC13XX-CC26XX SDK installer:
simplelink_cc13xx_cc26xx_sdk_x_xx_xx_xx.exe
. These instructions assume you have installed to the default directory:C:\ti\
In this case you don’t need to install anything on your PC. You can navigate to the project within TI-Rex and import it into CCS Cloud.
Then click the Cloud Import button on the top right hand corner:
Note that this will not install BTool on your computer.
This gives you:
The SimpleLink CC13XX-CC26XX SDK at
C:\ti\simplelink_cc13xx_cc26xx_sdk_x_xx_xx_xx
BTool accessible via the
\tools\ble5stack\btool
directory of the SimpleLink CC13XX-CC26XX SDK install directory.
Task 1 – Run ProjectZero Project#
The first task is to simply run the Project Zero example project on the LaunchPad and verify that the project runs as intended.
Error
Over the Air Download and the BIM project
Please note that this project is configured for updates over the air (OAD) by default. This means that you can upload a new version or a totally different project to the LaunchPad from your mobile phone.
It also means that the project is compiled and linked in such a way that you
MUST have the bim_offchip
project present in the internal
flash of the device first for the project to work correctly. More on this
later.
Note
Customer Configuration (CCFG)
This configuration section is used to tell the device how to behave after boot, such as where the reset vector is, what the clock sources are, etc.
Note
Boot Image manager (BIM)
The Boot Image Manager (BIM) project is placed at the last sector of the
internal Flash along with the CCFG section and is responsible for loading new
images (if any) from the external flash, and to launch the internal image. In
our case the internal image is Project Zero
.
If BIM is not present, debugging and starting Project Zero from the IDE will normally work, because the IDE overrides the boot configuration and jumps straight to where it thinks the project start address is. After a reset however, the device will not know what to do unless BIM is already present.
Note that when working on an OAD enabled project, you only need to download BIM once.
Import Projects in CCS Desktop#
Open Code Composer Studio and import the Project Zero app and stack library projects:
Open TI Resource Explorer (View → Resource Explorer) or go to https://dev.ti.com/tirex/#/
In the navigation panel on the left side, expand to find Project Zero in the SimpleLink CC13XX-CC26XX SDK.
Wireless connectivity → Embedded Software → SimpleLink CC13XX-CC26XX SDK - v:x.xx.xx.xx → Examples → Development Tools → CC26x2R LaunchPad → BLE5-Stack → project_zero → TI-RTOS7 → TI Clang Compiler → project_zero
Click the project folder marked above. Import the project into your workspace by clicking the Import button in the top right of the Resource Explorer view.
Using CCS Desktop, the button shows as:
Using CCS Cloud, the button shows as:
Alternatively, you can hover the mouse over the right of the project name until three vertical dots show up. Clicking on the dots exposes a context menu that allows importing the project
The projects will appear in your Project Explorer window as shown below.
You may need to import the BIM project separately. In this case, import it from the following path:
Wireless connectivity → Embedded Software → SimpleLink CC13XX-CC26XX SDK - v:x.xx.xx.xx → Examples → Development Tools → CC26x2R LaunchPad → bim → bim_offchip → No RTOS → TI Clang Compiler → bim_offchip
Connect the LaunchPad#
Start by making sure your kit is assembled, turned on, and connected to the PC via the USB cable.
When the Launchpad is connected, the Windows Device Manager (Start → Control Panel → Device Manager, or Win+X, M on Windows 10) will show you the following devices connected:
The Application/User UART
serial port is used for application output in this
example.
Connect a Terminal Program#
To see the serial output from the kit it is necessary to use a terminal emulator. Start this up now. There are several options:
Or even just going to the command prompt and typing for example
type COM4:
.Type
help mode
to learn how to set the port parameters.
Start your terminal program
Choose 115200 baud as the speed, 8 bit data, 1 stop bit, no parity, no flow control.
Open the serial port
Build the Projects and Flash the Device#
bim_offchip_CC26X2R1_LAUNCHXL_nortos_ticlang#
Build the BIM project by right-clicking on it and selecting
Build Project
.Alternatively build all the projects by pressing Ctrl + B.
Program the project by right clicking on it and selecting Debug As → Code Composer Debug Session
When the IDE is halted at the
bim_main
function, terminate debugging session by clicking Ctrl + F2 or the square red stop icon.
Note
Debugger Update
The first time you program your device, you may be prompted by CCS to update the XDS debugger on the LaunchPad. You will need to do this in order to be able to program the device with CCS. Make sure you only run the update once at a time.
project_zero_app_CC26X2R1_LAUNCHXL_tirtos7_ticlang#
Build the
project_zero_app_CC26X2R1_LAUNCHXL_tirtos7_ticlang
project by right-clicking on it and selecting Build Project.Download and run the project by either
Right clicking on it and selecting Debug As → Code Composer Debug Session, or
Pressing F11 when the project is marked as active (see image above)
Clicking the green bug icon in the toolbar
When the project is downloaded and halted at
main()
, press F8 or the Play/Pause button to start executing the code.
After the application runs you should observe something like the following in your terminal application:
This shows the user application initializing the three services LED, Button and Data, and set initial values for the characteristics in those services. Finally, callbacks are received from the stack that the device is ready and has started advertising its presence.
Take a note of your device address for later use.
Task 3 – Get Notified#
Warning
If you are using a mobile device
This task is demonstrated using BTool because it provides the most thorough GATT Table. Instructions on enabling notifications on your mobile device are provided at the end of this task but you are strongly encouraged to go through the BTool instructions for a better understanding of Bluetooth notifications.
You have connected. You have read and written values to control a Bluetooth device and turned on and off LEDs. How about getting some data back from a sensor on your device, like the state of the buttons?
In this task you will learn how instead of polling the value you are
interested in, which could waste a lot of energy, you can configure the device
to transmit Notifications
(Notifications are ATT Handle Value Notification
messages sent from a GATT Server
when a value is updated. They
are sent without being polled first, but the GATT Client
must subscribe by
writing to the configuration attribute first.) to you when the value changes.
When you are connected to a Peripheral device conforming to the
Project Zero Profile
(I just made that up. But there was actually some
thought behind how Project Zero services should be used.), this is possible to
do for the button states because of three things:
The
properties
for each BUTTONx State Characteristic includes theGATT_PROP_NOTIFY
flag.The BUTTONx State Characteristics include a
Client Characteristic Configuration Descriptor
orCCCD
attribute. Writing to this allows aGATT Client
to enable or disableNotifications
.The application cares about the value of the
CCCD Attribute
and also tries to send aNotification
when the state of theCharacteristic Value
changes.
If we have a look at the Button Service
in BTool things may become clearer:
In the figure above, the Access Properties
of each Characteristic Declaration
can be seen in the right column. This is also signified by the “12” in leading byte
of the Characteristic Declaration
Value. You will also notice there is a
Client Characteristic Configuration
attribute that the LED service did not have.
Access Properties#
Each characteristic has properties, which are made known in its declaration via a bit-map. The list below is an excerpt from the definitions in the SimpleLink CC13XX-CC26XX SDK.
/** @defgroup GATT_PROP_BITMAPS_DEFINES GATT Characteristic Properties Bit Fields
* @{
*/
#define GATT_PROP_BCAST 0x01 //!< Permits broadcasts of the Characteristic Value
#define GATT_PROP_READ 0x02 //!< Permits reads of the Characteristic Value
#define GATT_PROP_WRITE_NO_RSP 0x04 //!< Permits writes of the Characteristic Value without response
#define GATT_PROP_WRITE 0x08 //!< Permits writes of the Characteristic Value with response
#define GATT_PROP_NOTIFY 0x10 //!< Permits notifications of a Characteristic Value without acknowledgement
#define GATT_PROP_INDICATE 0x20 //!< Permits indications of a Characteristic Value with acknowledgement
#define GATT_PROP_AUTHEN 0x40 //!< Permits signed writes to the Characteristic Value
#define GATT_PROP_EXTENDED 0x80 //!< Additional characteristic properties are defined in the Characteristic Extended Properties Descriptor
/** @} End GATT_PROP_BITMAPS_DEFINES */
Client Characteristic Configuration#
The behavior and usage of attributes with the type 0x2902
is defined by the
Bluetooth Core Specification. Luckily, it’s not very complicated.
The Value
of the attribute is a 16-bit wide field. Writing 01:00
, which can
be translated to 0x0001
, will tell the device that it’s allowed to send
Notifications
of value changes to you. If you write 00:00
you disable
transmissions. If you write 02:00
you allow Indications
instead. That is not
permitted for the button characteristics.
Warning
Notifications are enabled a bit differently in the mobile devices.
For SimpleLink Starter, click on the Project Zero device. Then select the Service Explorer view. Next, find the Button Service and select it. Finally, you are in the characteristics view. Here, select a characteristic (Button 0 State is shown below), and then click “Set notify state”.
Note
Action!
Enable notifications for both BUTTON0 and BUTTON1.
Try to press the buttons.
Observe serial output and the value apparent in the GUI. Can you follow the sequence of events in the code?
Task 4 – Customize the Application#
This task teaches you to customize how the device appears to the outside, to make it more personal.
There are three main ways you can set your mark on the device:
The
GAP_ADVTYPE_LOCALNAME_(SHORT|COMPLETE)
field in either AdvData or Scan Response.The
Device Name
Characteristic in theGeneric Access Service
, andVarious strings in the
Device Information Service
The GAP_ADVTYPE_LOCALNAME
is the field that is displayed by most end-equipment
when scanning for Bluetooth devices, and it’s that field we’ll change now. After
a connection is established, and the Service Discovery is complete, many types
of end-equipment will then use the value from Device Name
for display.
Note
Read the Device Name
Using BTool or your Bluetooth LE Central device of choice, find the service
called Generic Access Service (UUID 0x2800)
, expand it if necessary to find
Device Name (UUID 0x2A00)
, and then read this value, if not done already.
Change the Advertisement data#
The two variables advertData
and scanRspData
contain the data the device
will transmit while advertising its existence. This data is available to any
interested parties so they can see the device and connect to it.
Note
Change LOCAL_NAME
Open SysConfig (project_zero.syscfg
) and on the left-side pane, go to
RF STACKS → BLE →. Once there, in the center pane find General
Configuration → Device Name and give the device a new name.
To make the new name show up in the device advertisement we need to change it in the advertisement data as well. In SysConfig, open Broadcaster Configuration → Advertisement Set 1 → Advertisement Data 1. Here you can change the GAP_ADTYPE_LOCAL_NAME_COMPLETE of the device.
You will have to change the Complete Local Name of the Scan Response Data section too as shown below.
When you have done this, right-click on the Project Zero project and select
Build Project
. When this is completed, download to the target, run the changed
code and observe that when you scan for Bluetooth Devices, the name has changed.
The change will also show up in the serial output.
Warning
Note that some mobile devices tend to cache previously known device names and may not update yours. In order to see your new device name, look up how to clear the Bluetooth cache on your mobile device. Often it’s a matter of disabling Bluetooth in the system menu and re-enabling it.
Hint
That’s it!
Well done!