Table of Contents

About

The simple_central project implements a simple Bluetooth Low Energy Central Device with GATT client functionality. This example uses a command line interface (cli) that allows the user to exercise most of the common BLE scenarios. By default, the example works out-of-box with the sensor_booster_pack example and then project_zero example, both of which are available in the SimpleLink SDK Bluetooth Plugin.

This simple_central project supports a 2-chip configuration. The supported Host MCU is a MSP432E401Y, and the supported Network Processor is a CC26x2R1. The CC26x2R1 is flashed with a modified host_test project, which implements a pure BLE Network Processor (NWP) for use with an external microcontroller. Host Test supports all GAP roles, but is configured to be in the Central role for this application. The NWP incorporates the TI BLE Host and Controller components of the protocol stack on the CC26x2, while the application resides on the external microcontroller, which for this application is the MSP432E4. For more information on Host Test, please view the Host Test README.

Communication between the CC26x2 and the MSP432E4 occurs through a UART serial interface using the Host Controller Interface (HCI) protocol. This application uses TI Vendor Specific HCI commands and a limited subset of Bluetooth LE HCI commands/events to implement a Bluetooth application. By using TI Vendor Specific commands and events, the application can communicate with and access the BLE stack.

![](../../docs/example_images/sc8.png)

The source code and list of supported TI Vendor Specific HCI APIs can be found in <PLUGIN_INSTALL_DIR>/source/ti/ble5stack/central

For more detailed information on the HCI Protocol, please view the SimpleLink CC26x2 SDK BLE5-Stack User’s Guide.

For more detailed information on the TI Vendor Specific APIs, please view the Vendor Specific Guide.

Set-up

Setting up CC26x2 as a BoosterPack

By default, the CC26x2 device is setup to act as a LaunchPad. A few changes need to be made to enable it to act as a BoosterPack so it can be stacked on top of the MSP432E4 device.

  1. By default, R51 is populated on the CC26x2, which enables LP_RESET. This causes a conflict with the LP_RESET pin on the MSP432E4, so we want R52 populated in order to enable BP_RESET instead. Ensure that R52 is populated with a zero ohm resistor.

  2. Flash the CC26x2 with the host_test image that is in <PLUGIN_DIR>/tools/host_test/ble5stack. Follow the directions in the SimpleLink SDK Bluetooth Plugin User’s Guide to do so. This is a custom host_test image that switches the UART TX/RX pins on the CC26x2 to avoid a conflict with the TX/RX pins on the MSP432E4. Additionally, there are two host_test images available that allow the user to choose whether or not to have power management enabled or disabled.

  3. Stack the CC26x2 device onto the MSP432E4 LaunchPad header that is closest to the XDS110 (Headers J1 to J4).

  4. On the CC26x2, ensure the XDS110 jumpers are disconnected, and the ‘Extern Pwr’ jumper is connected.

  5. Flash the simple_central example onto the MSP432E4.

Alternatively, the user can avoid having to make changes to the CC26x2 device by using jumper cables to make the connections as shown in the table below between the MSP432E4 and the CC26x2. Note that if you do this, you need to flash the original host_test image that can be found in the SimpleLink CC13X2_26X2 SDK.

Pin MSP432E4 CC26x2
Power 3v3 3v3
GND GND GND
UART PC4 (RX) DIO2(TX)
UART PC5 (TX) DIO3(RX)
Reset PL5 BPRST
MRDY PN2 IOID_13
SRDY PN3 IOID_14

Power Management

Power management over UART includes the usage of configurable GPIO pins Master Ready (MRDY) and Slave Ready (SRDY). These pins allow the external hos to wake the network processor from lower power modes. A handshake sequence with the pins must occur in order to start a data transmission between devices.

By default, power management is disabled in this application. This can be easily modified by going to the hci_tl.c file and modifying the POWER_SAVING define from a value of ‘0’ to a value of ‘1’.

Important: Ensure that the host_test image that you flash to the CC26X2 matches whether or not you have power management enabled in the application. In the file name for the host_test image, ‘pm’ indicates power management is enabled, and ‘xpm’ indicates it is disabled.

If you are using HCI with UART with power management disabled, then the application does not require the MRDY and SRDY pins.

For more information, please view the CC26x2 BL5Stack User’s Guide.

Terminal Commands

Command Description Usage
help Display list of commands help
h Alias for help h
scan Scan for BLE devices. Prints the devNum/RSSI/Name/Address scan
elink Establish a link with a specified BLE device elink [devNum]
tlink Terminate a link with a specified BLE device tlink [connHandle]
llinks List all established BLE links and print the connection handle/name of each connection llinks
write Write a characteristic value to a GATT server write [connHandle] [charHandle] [value] [valueLength]
writeled Write to Project Zero demo LEDs - Usage: writeled writeled [connHandle] [red/green/blue]
readled Read LED value of Project Zero demo - Usage: readled readled [connHandle]
notify Enable notifications of a sensor data on the Sensors BoosterPack notify [temp/light/humidity]
update Update connection event interval for a connected device update [connHandle] [connInt]

Detailed Usage

help

help: Displays a list of all the available commands to the user that can

Usage:

help

scan

Description: Perform a scan for nearby BLE devices.

Usage:

scan

The scan commands calls the API GapScan_Enable() with the following parameters:

This performs a scan for 800 ms, and zero advertisement reports will be saved during scanning. The found devices are printed out in a list with the following format:

DevNum: [device number] RSSI: [RSSI] Name: [name] Address: [address]

Example Usage

scan

Description: Establishes a connection to a nearby BLE device.

Usage:

elink <device number>

<device number>: The number of the device to connect to. The device number is assigned to devices found during the scan command.

The elink commands calls the API GapInit_Connect() with the following parameters:

If a successful connection is made, a message will be printed to the terminal window stating the success and the connection handle of the connection. Connection handles are assigned in order of the peripherals connected, starting at 0.

Precondition: scan has been called.

Example Usage:

elink 0

Description: Terminates a connection to a connected BLE device.

Usage:

tlink <connection handle>

<connection handle>: The connection handle that identifies a specific connection. This is assigned during the elink command.

The tlink command calls the API GAP_TerminateLinkReq() with the following default parameters:

Precondition: elink has been called and a connection has been made to a device

Example Usage:

tlink 0

Description: List all established BLE links and print the connection handle/name of each connection

Usage:

llinks

The connected devices are printed out in a list with the following format:

TODO

Example Usage:

llinks

write

Description: Writes a GATT characteristic value

Usage:

write <connection handle> <characteristic handle> <value> <value length>

<connection handle>: The connection handle that identifies a specific connection. This is assigned during the elink command. 

<characteristic handle>: The characteristic handle of the characteristc to write to.

<value>: The characteristic value to write

<value length>: The length in bytes of the value to write

Note: The write command uses little-endian ordering for the data, so the LSB should be placed first. i.e. The unsigned hexadecimal 0x1234 should be written to the command as 0x3412.

The write command calls the API GATT_writeCharValue() with the following default parameters:

Precondition: elink has been called and a connection has been made to a device

Example Usage:

write 0 0x001E 0x0000FF 3

writeled

Description: Control LED color of a connected Project Zero peripheral

Usage:

writeled    - Usage: writeled <connection handle> <red/green/blue> 

<connection handle>: The connection handle that identifies a specific connection. This is assigned during the elink command. 

<red/green/blue>: Possible values to change the LED color to

Precondition: elink has been called and a connection has been made to a device running the project_zero example from the SimpleLink SDK Bluetooth Plugin

Example Usage:

writeled 0 green

Example Usage:

write 0 0x001E 0x0000FF 3

readled

Description: Read the LED value of a connected Project Zero peripheral

Usage:

readled    - Usage: writeled <connection handle>

<connection handle>: The connection handle that identifies a specific connection. This is assigned during the elink command.

The LED characteristic is a three byte hex string that equates to RGB values. The highest byte is the red value, the middle byte is the green value, and the lowest byte is the blue value.

Precondition: elink has been called and a connection has been made to a device running the project_zero example from the SimpleLink SDK Bluetooth Plugin

Example Usage:

readled 0

notify

Description: Enable notifications of a sensor data on the Sensors BoosterPack

Usage:

notify <temp/light/humidity> <connection handle>

<temp/light/humidity>: Sensor to enable notifications for. Valid sensors include 'temp' (TI TMP007 temperature sensor), 'light' (TI OPT3001 ambient light sensor), or 'humidity' (Bosch BME280 humidity sensor).

Note: This command assumes that all connected peripherals are running the Sensors BoosterPack example, and will enable sensor notifications of the selected sensor for all connected peripherals.

Note: The BOOSTXL-SENSORS BoosterPack that is used with the Sensors BoosterPack example may not have the TI TMP007 temperature sensor populated. If you try to enable sensor notifications for ‘temp’, and the BOOSTXL-SENSORS BoosterPack does not have the TMP007, then the command will not work.

The notify command first performs a discovery to obtain the handles of the relevant characteristics. This is done through the API GATT_DiscCharsByUUID() with the following default parameters:

The type parameter is determined by the sensor that the user inputs into the terminal window. The UUIDs for each sensor characteristic is hard-coded into the application. These UUIDs can be found in <PLUGIN_INSTALL_DIR>/source/ti/bluetooth or in the README of the sensors_booster_pack example.

The application will perform discovery to obtain the handles of three characteristics: the notification period, the client characteristic configuration, and the sensor data. After obtaining these three characteristics, the application will use write to them using the API GATT_writeCharValue(). First, the Central Device will write to the notification period characteristic and update the period to 3 seconds. Next, the Central Device will write a value of ‘1’ to the client characteristic configuration - if a value of 0 is written here, it will subsequently halt notifications. Last, the Central Device writes to the data characteristic which is a notification characteristic of the actual read sensor value.

Sensor notifications can be halted by pressing Board_GPIO_BUTTON0 on the MSP432E401Y device. This write a value of 0 to the client characteristic configuration.

Precondition: elink has been called and a connection has been made to a device running the sensors_booster_pack example

Example Usage:

notify humidity

update

Description: Update connection event interval for a connected device

Usage:

update <connection handle> <connection interval>

<connection handle>: The connection handle that identifies a specific connection. This is assigned during the elink command.

<connection interval>: The new connection event interval value to set for the specified connection

The update command sends a request to a specified connected peripheral to update the connection interval parameter of the connection. The entered connection interval is set for both the minimum and maximum connection interval. This is done through the API GAP_UpdateLinkParamReq() with the following parameters:

Precondition: elink has been called and a connection has been made to a peripheral that accepts parameter updates

Example Usage:

update 0 80

This sets the connection interval to a value of 80 (100 ms) for the connection with connection handle 0.

Usage

Setup

  1. Connect your MSP432E4 to your computer with a USB cable, and flash the simple_central application to your MSP432E4.
  2. Open a terminal window and select the port that is shown as XDS110 Class Application/User UART. Set the Baud Rate to 115200.
  3. Start the application. On your terminal window, you should see the Initialization message.
  4. Ensure your peripheral device is powered and advertising.

Sensors BoosterPack Usage

This application works out-of-box to enable sensor data notifications from the sensors_booster_pack example that is included within the SimpleLink SDK Bluetooth Plugin, and then display the sensor data on the terminal window. View the sensors_booster_pack README to learn how to setup the device to be used as a peripheral. Once the Central Device is connected to the Sensors BoosterPack, using the notify command in the terminal window will cause the Central Device to write to three different sensor characteristics. First, the Central Device will write to the notification period characteristic and update the period to 3 seconds. Next, the Central Device will write a value of ‘1’ to the client characteristic configuration - if a value of 0 is written here, it will subsequently halt notifications. Last, the Central Device writes to the data characteristic which is a notification characteristic of the actual read sensor value.

The UUIDs for these characteristics have been hard-coded into this application as macros, which can be found in simple_central.h. These UUIDs can be found in the service tables in <PLUGIN_INSTALL_DIR>/source/ti/bluetooth or in the README of the sensors_booster_pack example.

  1. Ensure you have followed the steps in the ‘Setup’ section. For this demo, we are going to connect to the Sensors Boosterpack peripheral. On the peripheral, click SW1 button on the left-side of the MSP432 to start advertising. While it is advertising (and while connected), LED D1 will turn on to green to signify activity.

  2. Type scan into the terminal window. The central device will perform a scan of nearby BLE devices, and then list the found BLE devices in the format of

    DevNum: [devNum] RSSI: [RSSI] Name: [Name] Address: [Address]

  3. Find your peripheral device in the list and look at its device number. Type elink [device number] to establish a link and connect to your peripheral device. If the connection is successful, you will see a message displaying the Connection Handle of the established connection.

  4. Next, we will enable notifications of one of the sensors on the Sensors Boosterpack. Type notify [temp/humidity/light] [connection handle]. You will see on the terminal window that the central device will begin to print out the incoming notifications of the sensor data it is receiving from the Sensors Boosterpack.

  5. To stop notifications, press SW1 on the MSP432E4. This will write a value of ‘0’ to the data characteristic to halt notifications.

Note: If you are connected to multiple peripherals and perform a notify command, this application will assume that all the connected peripherals are running the sensors_booster_pack example and attempt to enable notifications for all connected peripherals. Pressing SW1 will halt notifications for all connected peripherals.

Project Zero Usage

This application also showcases how the user can write characteristic values if you do not have the characteristic UUID, but you do have the characteristic handle. We will demonstrate this with a peripheral that is running the project_zero example that is available in the SimpleLink SDK Bluetooth Plugin. View the project_zero README to learn how to setup the device to be used as a peripheral. The project_zero example has the LED service, which will allow us to easily demonstrate how to write to the LED characteristic and control the on-board LED.

The writeled and readled commands showcase talking to the project_zero when the characteristic handle is already known. In this case, the LED0 characteristic handle has been hard-coded into the application and can be found as PROJECT_ZERO_LED_HANDLE in simple_central.h.

  1. Ensure you have followed the steps in the ‘Setup’ section. For this demo, we are going to connect to the Project Zero peripheral. Once it is powered, this peripheral begins advertising automatically.

  2. Type scan into the terminal window. The central device will perform a scan of nearby BLE devices, and then list the found BLE devices in the format of

    Device Number: [devNum] RSSI: [RSSI] Name: [Name] Address: [Address]

  3. Find your peripheral device in the list and look at its device number. Type elink [device number] to establish a link and connect to your peripheral device. If the connection is successful, you will see a message displaying the Connection Handle of the established connection.
  4. We are going to control the color of the tricolor LED that is on the peripheral MSP432 device by using the writeled command. Type writeled 0 blue. This sets the LED color for the connection with connection handle 0 to blue. The possible supported arguments for the sensor color for this command are red, green, or blue.

  5. To read the LED color on the MSP432, type readled 0. This reads the LED color for the connection with connection handle 0. The terminal window should print out the LED value as a hex string. The highest byte is the red value, the middle byte is the green value, and the lowest byte is the blue value. If the LED is set to red, then the printed out value will be 0xFF0000.

Alternatively, we can control the color of the tricolor LED that is on the peripheral MSP432 device by using the write command and directly entering the LED characteristic handle.

  1. Type write 0 0x001E 0x0000FF 3. The LED on the peripheral MSP432 should change color to blue. To breakdown how the command was performed:
    • Command: write
    • Connection Handle: 0
      • Established when we made the connection with the peripheral.
    • Characteristic Handle: 0x001E
      • View the ‘Obtaining Characteristic Handle’ section of this README to learn how we obtained this handle.
    • Value: 0x0000FF
      • The LED characteristic is a three byte hex string that equates to RGB values. The highest byte is the red value, the middle byte is the green value, and the lowest byte is the blue value. Therefore, the value 0x0000FF sets red and gree to 0, and blue to a maximum value of 255.
    • Data Length: 3
      • The length of the value to write in bytes, in this case three bytes.

The write command can be used to specify the characteristic handle and value to write.