Multi Role
Introduction
The multi_role
project demonstrates the capabilities of the Texas Instruments BLE stack to function in multiple simultaneous connection roles.
Specifically, the project is capable of functioning as a master and a slave simultaneously, in any combination, while maintaining up to the amount of connections defined by MAX_NUM_BLE_CONNS
. Check on this preprocessor define for the default value.
The project is capable of connecting to any central/peripheral device. Any type of legacy pairing/bonding is possible. Parameter updates are supported. Connections can be established in any role. The project supports multiple simultaneous GATT discoveries and/or pairings/bondings.
This project has the following app configurations available:
App Build Configuration | Description |
---|---|
FlashROM_Release (default) | All TI-RTOS debug features disabled but application-logging to UART remains enabled. The application uses the config file ble_release.cfg and the defines are in <app name>_FlashROM_Release.opt . |
FlashROM_Debug | All TI-RTOS debug features enabled. The application uses the config file ble_debug.cfg and the defines are in <app name>_FlashROM_Debug.opt . |
All application configurations use the stack library configuration, FlashROM_Library. This build configuration will yield additional flash footprint optimizations by the linker since the application and stack can share contiguous flash pages. This configuration is further discussed in the Stack Library Configuration section of the BLE5-Stack User’s Guide provided in the SDK.
Hardware Prerequisites
The default Multi Role board configuration uses the device’s LaunchPad development kit. This hardware configuration is shown in the below image:
For custom hardware, see the Running the SDK on Custom Boards section of the BLE5-Stack User’s Guide.
Software Prerequisites
For information on what versions of Code Composer Studio and IAR Embedded Workbench to use, see the Release Notes file provided in the SDK. For information on how to import this project into your IDE workspace and build/run, please refer to the device’s Platform section in the BLE5-Stack User’s Guide.
Assumptions/Considerations
In this document, the terms master/central and slave/peripheral are used synonymously. It is assumed that the master/central devices are GATT clients and slave/peripheral devices are GATT servers. Once the connection limit (set with the MAX_NUM_BLE_CONNS
preprocessor define) is reached, the multi_role
device won’t be allowed to advertise/scan until there is a disconnection.
When connected in the master role, the multi_role
device will query the slave device for the simpleGATTProfile service in order to demo some basic GATT procedures (read/write characteristic). However, it is not necessary for the slave device to contain this service in order for a connection to be established. That is, it is possible for the peripheral devices in the system to have differing attribute tables since the multi_role
device will perform a service/characteristic discovery after each connection is formed.
By default, the multi_role
application is configured to filter and connect to peripheral devices with the TI Simple Profile UUID, such as devices with the simple_peripheral
project. To modify this behavior, set DEFAULT_DEV_DISC_BY_SVC_UUID
to FALSE
in multi_role.c
.
If the project is configured for too many connections (via the MAX_NUM_BLE_CONNS
preprocessor define) and also security, it is possible for heap allocation failures to occur which will break the stack. Therefore, the project should be stress-tested for its intended use case to verify that there are no heap issues by including the HEAPMGR_METRICS
preprocessor define. See the Debugging section of the BLE5-Stack User’s Guide for more information on how to do this.
When at least one connection is already formed, in order to allow enough processing time to scan for a new connection, the minimum possible connection interval (in milliseconds) that can be used is:
12.5 + 5*n
where n is the amount of current connections. For example, if there are currently four connections, all four connections must use a minimum connection interval of 12*5 + 5*4 = 32.5 ms
in order to allow scanning to occur to establish a new connection.
Usage
The multi_role
project uses the two buttons on the LaunchPad to accept user input and outputs information through the UART. This application uses the UART peripheral to provide an interface for the application. The UART is only used for display messages. This document will use a terminal program (Tera Term, PuTTY, etc.) to serve as the display for the output of the LaunchPad. Note that any other serial terminal can be used. The following default parameters are used for the UART peripheral for display:
UART Param | Default Values |
---|---|
Baud Rate | 115200 |
Data length | 8 bits |
Parity | None |
Stop bits | 1 bit |
Flow Control | None |
Upon powering on or resetting the device, the user will see the main menu. When in the main menu, the left button will scroll through the possible actions, which are:
- Discover Devices
- Advertise
Other options will become available once devices are scanned, and again once a connection is formed.
The device will report upon startup that it is initialized, advertising, and connected to 0 devices:
The right button is used to select one of the available options. Each option will be covered in the following sections.
Advertise
Selecting this option will toggle advertising on and off. It will display “Adv Set 0 Disabled” when advertising is off and “Adv Set 0 Enabled” when advertising is on. By default, advertising is on which will send out connectable advertisements from the device.
Discover Devices
Selecting this option will start a device discovery to search for advertising devices. It will then display the number of devices found:
Connect
After selecting Discover Devices
, the option to connect to a device will now become available. Selecting the +Connect
option to allow you to scroll through the discovered devices:
A device can then be selected to initiate a connection. The connect option can be chosen again to connect with additional peripheral devices. The terminal window will display the number of devices that are connected to the Multi Role device. With a device now connected, select +Work with
and select the appropriate connected device.
At this point, the following options are present to be selected:
- GATT Read
- GATT Write
- Connection Update
- Disconnect
It is also possible to select “Upper Menu” to return to the main menu.
GATT Read
This option is used to send read requests to the peripheral device. Pressing the right button once will send a read request to the connected device and will print the returned value of the characteristic. Note that this characteristic can be written to with the GATT Write
option:
GATT Write
This option is used to write predetermined values (0x00, 0x55, 0xAA, etc.) to the device’s characteristic. Note that this characteristic can be read from with the GATT Read
option:
Connection Update
This option updates the connection parameters based on the values set by the following constants in multi_role.c
:
- DEFAULT_UPDATE_MIN_CONN_INTERVAL
- DEFAULT_UPDATE_MAX_CONN_INTERVAL
- DEFAULT_UPDATE_SLAVE_LATENCY
- DEFAULT_UPDATE_CONN_TIMEOUT
The update was successful if it states that it has been “Updated” and displays the new connection timeout value.
Disconnect
This option will send a link termination request to terminate the connection with the connected device. The following shows a successful disconnection: