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.
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.
- 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 customhost_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 twohost_test
images available that allow the user to choose whether or not to have power management enabled or disabled. Stack the CC26x2 device onto the MSP432E4 LaunchPad header that is closest to the XDS110 (Headers J1 to J4).
On the CC26x2, ensure the XDS110 jumpers are disconnected, and the ‘Extern Pwr’ jumper is connected.
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:
- period (Default): 0 sec
- duration (Default): 80 (800 ms)
- max number of records (Default) : 0
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
elink
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:
- peer address type (Default): 0x00 (PEER_ADDRTYPE_PUBLIC_OR_PUBLIC_ID)
- peer address: [peer address obtained during
scan
] - phys: 0x01 (INIT_PHY_1M)
- timeout: 0x00 sec
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
tlink
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:
- connection handle: [connection handle of the link to terminate]
- reason: 0x13 (Remote User Terminated Connection)
Precondition: elink
has been called and a connection has been made to a device
Example Usage:
tlink 0
llinks
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:
- connection handle: [connection handle of the link to terminate]
- reason: 0x13 (Remote User Terminated Connection)
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:
- connection handle: [default connection handle]
- start handle: 0x0001
- end handle: 0xFFFF
- type: [UUID of the characteristic to discover]
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:
- connection handle: [connection handle of the link to terminate]
- interval min: [value (*1.25 ms) to set for connection event interval]
- interval max: [value (*1.25 ms) to set for connection event interval]
- connection latency (default): 0x0000
- connection timeout (default): 0x07D0 (20 sec)
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
- Connect your MSP432E4 to your computer with a USB cable, and flash the
simple_central
application to your MSP432E4.
- Open a terminal window and select the port that is shown as XDS110 Class Application/User UART. Set the Baud Rate to 115200.
- Start the application. On your terminal window, you should see the Initialization message.
- 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.
- 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.
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 ofDevNum:
[devNum]
RSSI:[RSSI]
Name:[Name]
Address:[Address]
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.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.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
.
- 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.
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 ofDevice Number:
[devNum]
RSSI:[RSSI]
Name:[Name]
Address:[Address]
- 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. - We are going to control the color of the tricolor LED that is on the peripheral MSP432 device by using the
writeled
command. Typewriteled 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. 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.
- 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.