Silicon Labs AN1296 User manual
AN1296: Application Development with
Silicon Labs’ RTL Library
This application note provides guidance on how to start
developing Bluetooth 5.1 Direction Finding (DF) applications
using the Silicon Labs Bluetooth LE stack and the Real Time
Locating Library (RTL lib).
Silicon Labs provides sample projects including examples for asset tags and locators
to demonstrate Bluetooth LE 5.1-based DF applications. This document provides an
overview of the sample projects, software architecture and a step-by-step guide on
how to create your own applications using Simplicity Studio 5 and Bluetooth SDK v3.x.
Readers of this document should be familiar with the basics and terms of Direction Finding. To learn more about the theory of Direction Finding, see UG103.18: Bluetooth® Di-
rection Finding Fundamentals. To get started with Silicon Labs Direction Finding Solution, read QSG175: Silicon Labs Direction Finding Solution Quick-Start Guide.
KEY POINTS
• Overview of Silicon Labs’ sample applications
• Connection-based asset tag
• Connectionless asset tag
• Silicon Labs Enhanced asset tag
• AoA locator
• AoA multilocator
• Aoa multilocator GUI
silabs.com | Building a more connected world. Rev. 0.3
AN1296: Applic ation Development w ith Silicon Labs’ RTL Library
Introduction
1 Introduction
Silicon Labs provides modularized software sample projects for Angle of Arrival (AoA) asset tags and locators that can be easily extended
to address different use case scenarios.
In general, the sample applications can be grouped in two main categories:
• AoA asset tag sample app—demonstrates a Constant Tone Extension (CTE) transmitter.
• AoA locator sample app—demonstrates a CTE receiver.
1.1 AoA asset tags—CTE Transmitters
The Bluetooth SDK in Gecko SDK Suite v3.x provides an AoA asset tag sample project (Bluetooth - SoC AoA Asset-Tag) that can
easily be extended to address the following three scenarios by simply installing software components using Simplicity Studio 5’s Project
Configurator.
• Bluetooth 5.1 Connection-based AoA asset-tag
• Bluetooth 5.1 Connectionless AoA asset-tag
• Silicon Labs enhanced AoA asset-tag
1.2 AoA Locators—CTE Receivers
The Bluetooth SDK v3.x also provides sample projects for AoA locators. Due to the resource-constrained nature of the EFR32 device, all
the locator sample applications supported in Bluetooth SDK v3.x work in NCP (Network Co-Processor) mode. Thus, two sample applications are provided in the SDK to support both the NCP target and the NCP host of the locator:
• NCP AoA locator sample app
• AoA locator host sample app
The Bluetooth stack runs on the EFR32 (AoA locator target) and the application runs on a host (MCU or PC). While the NCP AoA locator
is generic for all variants, the AoA locator host sample app must be compiled for the desired type of CTE receiver (that is, connectionbased, connectionless, or Silicon Labs enhanced).
AoA can be measured accurately using a single locator. However, a single locator can only provide a rough estimation of the asset tag’s
position. To determine the precise position of the asset tag, using multiple locators is recommended. By using multiple antenna arrays,
the position of an asset tag can be determined using triangulation.
To demonstrate position estimation using multiple locators, the Gecko SDK Suite v3.x also provides a sample project for supporting
multiple locators—the multi-locator AoA locator host application
In summary, the Bluetooth SDK v3.x offer the following examples projects in the GSDK folder that can be adapted for different use case
scenarios:
• Studio Examples
• soc_aoa_asset_tag— Bluetooth – SoC AoA Asset Tag
• ncp_aoa_locator—Bluetooth - NCP AoA locator
• Host Examples (app/Bluetooth/example_host)
• aoa_locator—AoA locator host (single locator)
• aoa_multilocator—AoA locator host (multi-locator)
Additionally, two more host sample apps are provided for visualization purposes:
• aoa_compass (see QSG175: Silicon Labs Direction Finding Solution Quick-Start Guide for a detailed description)
• aoa_multilocator_gui
silabs.com | Building a more connected world. Rev. 0.3 | 2
AN1296: Applic ation Development w ith Silicon Labs’ RTL Library
Introduction
1.3 Software Architecture
The following diagram provides an overview of the software architecture for the asset-tag, NCP AoA locator, and host sample applications
provided by Silicon Labs.
Figure 1-1. Software Architecture for the Asset-Tag, NCP AoA Locator, and Host Sample Applications
The yellow and orange boxes represent the AoA asset tag and NCP AoA locator sample projects, respectively. These example projects
are meant to run on an EFR32xG22 device.
The green box represents the AoA locator host sample app. This sample app is meant to run on a host machine (for example, x86,
Raspberry Pi). The orange and green boxes logically form a single locator (a CTE receiver).
The AoA locator host (green box) connects to the NCP AoA locator (orange box) via a serial port (VCOM) or TCP/IP. In the latter case,
the AoA locator host and NCP AoA locator can be in different locations.
Silicon Labs AoA sample projects utilize the MQTT messaging protocol for sending and receiving the asset tag’s angle and position
information. MQTT is a publish and subscribe messaging exchange protocol where a publisher sends, and the subscriber receives topics
of interest via a message broker. The subscribers and publishers in the MQTT protocol do not interact with each other. The connection
between them is handled by the broker. The broker filters all incoming messages and distributes them to the subscribers.
The AoA locator host controls the Bluetooth stack running on the NCP AoA locator and receives the CTE IQ samples (In-Phase and
Quadrature-Phase pair of readings) using BGAPI protocol. Using the RTL library, the AoA locator host calculates the Angle of Arrival of
an asset tag and publishes the result to the MQTT broker (white box in the figure above).
The box in blue represents the multi-locator host sample project. This host application subscribes to MQTT topics (related to the angle
data) published by single locators to calculate and publish the exact position of an asset tag in an X, Y, Z coordinate.
silabs.com | Building a more connected world. Rev. 0.3 | 3
AN1296: Applic ation Development w ith Silicon Labs’ RTL Library
Introduction
1.4 Prerequisites
To get started with AoA application development, you will need the following:
• EFR32xG22-based device serving as a tag (for example, Thunderboard BG22).
• 4x4 antenna array board: one for single locator sample apps, more than one for multi-locator sample app.
• A Wireless Starter Kit (WSTK) for each antenna array board.
• Simplicity Studio v5 installed on your PC.
• Bluetooth 3.1.0 or higher SDK installed from Gecko SDK Suite v3.1.0 or later.
• MinGW64 for building the AoA locator host applications, if you are using a Windows PC as a host.
• Mosquitto MQTT Broker— https://mosquitto.org/download/
• MQTT Explorer (optional)— http://mqtt-explorer.com/.
• Python 3.7 for visualization purposes.
.
silabs.com | Building a more connected world. Rev. 0.3 | 4
AN1296: Applic ation Development w ith Silicon Labs’ RTL Library
Bluetooth - SoC AoA Asset Tag
2 Bluetooth - SoC AoA Asset Tag
Asset tags are relatively simple as their only goal is to send CTEs on a single antenna. However, CTEs can be sent in several different
ways depending on the use case. Bluetooth SDK v3.1 provides an asset tag sample project, Bluetooth - SoC AoA Asset Tag, that can
easily be extended to address the following three scenarios by installing software components using Simplicity Studio 5’s Project Configurator.
• Bluetooth 5.1 Connection-based AoA asset-tag—sends CTE responses on a connection when a CTE request is received.
• Bluetooth 5.1 Connectionless AoA asset-tag— sends CTE in periodic advertisements.
• Silicon Labs Enhanced (Silicon Labs proprietary) AoA asset-tag—sends CTE in extended advertisements.
Figure 2-1. Bluetooth – SoC Asset Tag
At its core, the Bluetooth - SoC AoA Asset-Tag sample is simply a Bluetooth – SoC Empty sample project extended with a CTE
transmitter and an Asset Tracking Profile (ATP) in its GATT database. These properties can be added by installing one or two of the
following software components, depending on the use case.
• Constant Tone Extension GATT Service (Connection)
• Constant Tone Extension GATT Service (Connectionless)
• Constant Tone Extension GATT Service (Silabs proprietary)
By default, the Bluetooth - SoC AoA Asset Tag has the Constant Tone Extension GATT Service (Connection) and Constant Tone
Extension GATT Service (Silabs proprietary) component preinstalled in the project. The Constant Tone Extension GATT Service (Connection) component has dependency on AoA Transmitter; and hence it is installed in the background. The AoA Transmitter component
enables initializing the CTE transmitter.
In addition to enabling the AoA transmitter, the Constant Tone Extension GATT Service (Connection) component also contributes to the
Bluetooth GATT configuration, which is the Constant Tone Extension Service with a Constant Tone Extension Enable characteristic, as
shown by (a) in the following figure. The Constant Tone Extension Enable characteristics is mandatory, and thus must be included in
Connection, Connectionless, and Silicon Labs proprietary tag implementations.
On the other hand, the Constant Tone Extension GATT Service (Silabs Proprietary) component allows to achieve broadcasting CTEs in
extended advertisements. This component contributes the following characteristics to the Constant Tone Extension GATT Service which
can be used to alter different CTE parameters:
• Advertising Constant Tone Extension Minimum Length
• Advertising Constant Tone Extension Minimum Transmit Count
• Advertising Constant Tone Extension Transmit Duration
• Advertising Constant Tone Extension Interval
• Advertising Constant Tone Extension PHY
These characteristics are mandatory when CTE transmission is supported on advertising channels, which is the case for the Connectionless and Silicon Labs proprietary samples.
silabs.com | Building a more connected world. Rev. 0.3 | 5
AN1296: Applic ation Development w ith Silicon Labs’ RTL Library
Bluetooth - SoC AoA Asset Tag
Figure 2-2. Bluetooth SoC – AoA Asset Tag Sample Project
Currently the ATP profile is not among the predefined profiles by the Bluetooth SIG, therefore custom 128-bit UUIDs are used for the
Constant Tone Extension Service (CTE Service) and characteristics that are related to it. It is important to advertise the CTE service (see
“advertise service” checked in the Bluetooth GATT configurator), because the locator applications will find the asset tags by looking for
this service in the advertisement packet.
2.1 Connection-Based Asset Tag Sample Application
A connection-based asset tag needs to implement:
• A connectable Bluetooth peripheral that starts advertising itself
• CTE transmitter to be able to send CTE responses, and
• ATP in its GATT database.
As mentioned above, the Constant Tone Extension GATT Service (Connection) component implements both the CTE transmitter and
ATP in the GATT database of your project. As such, for the connection-based tag, the Bluetooth - SoC AoA Asset-Tag sample app
works out of the box without having to install any additional software components. You can uninstall the Constant Tone Extension GATT
Service (Silabs Proprietary) component, if your custom project does not need to send CTEs on extended advertising.
The CTE transmitter is initialized by calling the sl_bt_class_cte_transmitter_init() API. This API is automatically added in the
Bluetooth initialization by the AoA Transmitter component. This component is added to the project (in the background) when the Constant
Tone Extension GATT Service (Connection) is installed, which is the default in the Bluetooth - SoC AoA Asset-Tag sample app.
main() -> sl_system_init() -> sl_stack_init() -> sl_bt_init() -> sl_bt_class_cte_transmitter_init()
CTE transmission is enabled by sl_bt_cte_transmitter_enable_connection_cte() after a remote device (the locator) connects to
the tag and writes 0x01 into the Constant Tone Extension Enable characteristics. This process is handled by
sl_gatt_service_cte_on_event() when the sl_bt_evt_gatt_server_user_write_request event is triggered.
sl_gatt_service_cte_on_event() is defined in sl_gatt_service_cte.c, which is generated inside the gecko_sdk_3.1.x/app/Blue-
tooth/common/gatt_service_cte directory by the Constant Tone Extension GATT Service (Connection).
It is important that the “Write” property of the Constant Tone Extension Enable characteristics is enabled in the Bluetooth GATT configu-
rator service (see “Write” checked under Properties).
To test a connection-based asset tag application:
1. Create a Bluetooth - SoC AoA Asset Tag project in Simplicity Studio 5.
2. Build the project.
3. Flash it to an EFR32xG22 device. Note: If you use a new Thunderboard, push its reset button before programming. On some
boards the factory default firmware puts the device into EM4 after 30 seconds, and in this case the device must be restarted to be
accessible by the programmer.
silabs.com | Building a more connected world. Rev. 0.3 | 6
AN1296: Applic ation Development w ith Silicon Labs’ RTL Library
Bluetooth - SoC AoA Asset Tag
4. The sample does not contain a bootloader. If you have not flashed any bootloader into your device, flash an xG22 bootloader sample
app (for example C: \SiliconLabs\SimplicityStudio\v5\developer\sdks\gecko_sdk_suite\v3.1\platform\bootloader\sample-apps\boot-
loader-storage-internal-single-512k\efr32mg22c224f512im40-brd4182a\ bootloader-storage-internal-single-512k.s37).
2.2 Connectionless Asset Tag Sample Application
A connectionless asset tag needs to implement:
• A periodic advertiser.
• CTE transmitter – to be able to send CTEs in periodic advertisements.
• ATP (Asset Tracking Profile) in its GATT database.
The CTE transmitter is initialized by calling the sl_bt_class_cte_transmitter_init() API. This API is automatically added in the
Bluetooth initialization by the AoA Transmitter component. This component is added to the project (in the background) when the Constant
Tone Extension GATT Service (Connection) is installed, which is the default in the Bluetooth - SoC AoA Asset Tag sample app.
main() -> sl_system_init() -> sl_stack_init() -> sl_bt_init() -> sl_bt_class_cte_transmitter_init()
The connectionless version of the asset tag is rather simple. It starts periodic advertising with CTE enabled, and that is all. To achieve
this, remove the Constant Tone Extension GATT Service (Silabs Proprietary) and install the Constant Tone Extension GATT Service
(connectionless) component. In the background, installing this component will also install the Periodic Advertising component, which
initializes and enables the Periodic Advertising feature using sl_bt_init_periodic_advertising(). This API is automatically added
in the Bluetooth initialization when the Constant Tone Extension GATT Service (Connectionless) component is installed.
main() -> sl_system_init() -> sl_stack_init() -> sl_bt_init() -> sl_bt_init_periodic_advertising()
The Constant Tone Extension GATT Service (Connectionless) component also contributes to the Bluetooth GATT configurator. It adds
the following characteristics to the Constant Tone Extension GATT Service, which can be used to alter different CTE parameters:
• Advertising Constant Tone Extension Minimum Length
• Advertising Constant Tone Extension Minimum Transmit Count
• Advertising Constant Tone Extension Transmit Duration
• Advertising Constant Tone Extension Interval
• Advertising Constant Tone Extension PHY
It is important that the “Write” property of each of these characteristics is enabled in the Bluetooth GATT configurator service (see “Write”
checked under Properties).
In a nutshell, when the tag is booted, it initializes the CTE transmitter and periodic advertising feature, and enters an infinite loop of
processing Bluetooth stack events.
void sl_bt_process_event(sl_bt_msg_t *evt)
{
sl_bt_ota_dfu_on_event(evt);
sl_gatt_service_cte_on_event(evt);
sl_gatt_service_cte_adv_on_event(evt);
sl_bt_on_event(evt);
}
The sl_gatt_service_cte_adv_on_event() handles events related to system boot and user write requests. When a system boot event
is triggered, CTE advertising is initialized and started automatically by this handler using adv_cte_init() and adv_cte_start(), re-
spectively. These functions are defined in sl_gatt_service_cte_adv.c and sl_gat_service_cte_connectionless.c, generated
inside gecko_sdk_3.1.x/app/Bluetooth/common/gatt_service_cte_adv directory when the Constant Tone Extension GATT Service
(Connectionless) component is installed.
adv_cte_init() is called only once during the init phase. It sets the default parameter values for the CTE advertising. In contrast,
adv_cte_start() is triggered during the initialization and when the user write request for updating the value of one of the connectionless
CTE characteristics (listed above) is completed. The adv_cte_start() normally sets the advertising phy, starts a connectionless
advertising, and adds CTEs to the periodic advertisements using sl_bt_cte_transmitter_enable_connectionless_cte().
To test the connectionless asset tag application:
1. Create Bluetooth - SoC AoA Asset-Tag project in Simplicity Studio 5.
2. Uninstall the Constant Tone Extension GATT Service (Silabs Proprietary) component.
silabs.com | Building a more connected world. Rev. 0.3 | 7
AN1296: Applic ation Development w ith Silicon Labs’ RTL Library
Bluetooth - SoC AoA Asset Tag
3. Install the Constant Tone Extension GATT Service (Connectionless) component using the Project Configurator.
4. Build the project.
5. Flash it to an EFR32xG22 device. Note: If you use a new Thunderboard, push its reset button before programming. On some boards
the factory default firmware puts the device into EM4 after 30 seconds, and in this case the device must be restarted to be accessible
by the programmer.
6. The sample does not contain a bootloader. If you have not flashed any bootloader into your device, flash an xG22 bootloader sample
app (for example C:\SiliconLabs\SimplicityStudio\v5\developer\sdks\gecko_sdk_suite\v3.1\platform\bootloader\sample-apps\boot-
loader-storage-internal-single-512k\efr32mg22c224f512im40-brd4182a\ bootloader-storage-internal-single-512k.s37).
Note that you cannot uninstall the Constant Tone Extension GATT Service (Connection) in a connectionless asset tag as it is the only
component that installs the AoA Transmitter and contributes the Constant Tone Extension Enable characteristic, which is mandatory for
the Constant Tone Extension Service.
2.3 Silicon Labs Enhanced (Silabs proprietary) Asset Tag Sample Application
The Silicon Labs asset tag sample app sends CTEs in extended advertisements, which is not a standard solution, and therefore can only
be used with Silicon Labs locators. The advantage of this solution is that it uses extended advertisements, in which case no synchronization information need to be stored on the locator for each tag, in contrast to connections and periodic advertisements. This solution
scales much better than the other two and can be used with hundreds of tags.
This sample app implements:
• An advertiser broadcasting extended advertisements.
• CTE transmitter – to be able to send CTEs in extended advertisements.
• ATP (Asset Tracking Profile) in its GATT database.
The difference between the connectionless version and the Silicon Labs proprietary version of the asset tag sample app is that the Silicon
Labs solution starts extended advertising with CTE instead of periodic advertising. This offers better scalability since it puts no RAM
constraints on the receiver side, like connections and periodic advertisement synchronizations.
The CTE transmitter is initialized by calling the sl_bt_class_cte_transmitter_init() API. This API is automatically added in the
Bluetooth initialization by the AoA Transmitter component. This component is added to the project (in the background) when the Constant
Tone Extension GATT Service (Connection) is installed, which is the default in the Bluetooth - SoC AoA Asset Tag sample app.
main() -> sl_system_init() -> sl_stack_init() -> sl_bt_init() -> sl_bt_class_cte_transmitter_init()
To broadcast CTEs in extended advertisement, the Constant Tone Extension GATT Service (Silabs Proprietary) software component
must be installed, which is the default in the Bluetooth - SoC AoA Asset-Tag sample app. As such, for the Silicon Labs proprietary tag,
the Bluetooth - SoC AoA Asset-Tag sample app works out of the box without having to install any additional software components.
Similar to the connectionless version, the Constant Tone Extension GATT Service (Silabs Proprietary) component adds the following
characteristics to the Constant Tone Extension GATT Service, which can be used to alter different CTE parameters:
• Advertising Constant Tone Extension Minimum Length
• Advertising Constant Tone Extension Minimum Transmit Count
• Advertising Constant Tone Extension Transmit Duration
• Advertising Constant Tone Extension Interval
• Advertising Constant Tone Extension PHY
It is important that the “Write” property of each of these characteristics is enabled in the Bluetooth GATT configurator service (see “Write”
checked under Properties).
In a nutshell, when the tag is booted, it initializes the CTE transmitter, and enters an infinite loop of processing Bluetooth stack events.
void sl_bt_process_event(sl_bt_msg_t *evt)
{
sl_bt_ota_dfu_on_event(evt);
sl_gatt_service_cte_on_event(evt);
sl_gatt_service_cte_adv_on_event(evt);
sl_bt_on_event(evt);
}
The sl_gatt_service_cte_adv_on_event() handles events related to system boot and user write requests. When a system boot event
is triggered, CTE advertising is initialized and started automatically by this handler using adv_cte_init() and adv_cte_start(),
silabs.com | Building a more connected world. Rev. 0.3 | 8
AN1296: Applic ation Development w ith Silicon Labs’ RTL Library
Bluetooth - SoC AoA Asset Tag
respectively. These functions are defined in sl_gatt_service_cte_adv.c and sl_gat_service_cte_silabs.c, generated inside
gecko_sdk_3.1.x/app/Bluetooth/common/gatt_service_cte_adv directory when the Constant Tone Extension GATT Service (Silabs Proprietary) component is installed.
adv_cte_init() is called only once during the init phase. It sets the default parameter values for the CTE advertising. Whereas,
adv_cte_start() is triggered during the initialization and when a user write request for updating the value of one of the connectionless
CTE characteristics (listed above) is completed. The adv_cte_start() normally sets the advertising phy, starts a connectionless
advertising, and adds CTEs to the extended advertisements using sl_bt_cte_transmitter_enable_silabs_cte().
To test the Silicon Labs proprietary asset tag application:
1. Create a Bluetooth - SoC AoA Asset-Tag project in Simplicity Studio 5.
2. Build the project.
3. Flash it to an EFR32xG22 device. Note: if you use a new Thunderboard, push its reset button before programming. On some boards
the factory default firmware puts the device into EM4 after 30 seconds, and in this case the device must be restarted to be accessible
by the programmer.
4. The sample does not contain a bootloader. If you have not flashed any bootloader into your device, flash an xG22 bootloader sample
app (for example C:\SiliconLabs\SimplicityStudio\v5\developer\sdks\gecko_sdk_suite\v3.1\platform\bootloader\sample-apps\boot-
loader-storage-internal-single-512k\efr32mg22c224f512im40-brd4182a\ bootloader-storage-internal-single-512k.s37).
Note that you cannot uninstall the Constant Tone Extension GATT Service (Connection) in a Silicon Labs proprietary asset tag as it is
the only component that installs the AoA Transmitter and contributes the Constant Tone Extension Enable characteristic, which is man-
datory for the Constant Tone Extension Service.
The Bluetooth specification allows CTEs to be added to periodic advertisements only, therefore this is a proprietary, non-standard solution.
It can, however, help you scale your system. In the case of periodic advertisement, the locator must keep track of each periodic advertiser
one-by-one. For each, it needs to know when and on which channel to expect the next packet. With hundreds of tags this can result in
huge RAM consumption, making this solution less scalable. In contrast to this, to receive an extended advertisement the locator must
scan on the primary advertising channels only, listen for legacy advertisements that point to extended advertisements, and jump to the
reported channel at the reported time. No time/channel tracking is needed; therefore, hundreds of tags can be followed.
silabs.com | Building a more connected world. Rev. 0.3 | 9
AN1296: Applic ation Development w ith Silicon Labs’ RTL Library
Single Locator Sample Application
3 Single Locator Sample Application
Locators are much more complicated than asset tags. They control an array of antennae (not a single antenna), they must precisely
sample the incoming signal and must also calculate the angle and position estimations from the received signal. Because of the limited
capabilities of the EFR32, all the locator sample applications supported in Bluetooth SDK v3.x work in NCP (Network Co-Processor)
mode, meaning that the Bluetooth stack runs on the EFR32 (NCP target) and the application runs on a host (MCU or PC).
The Bluetooth SDK v3.x provides one sample project for the EFR32 NCP AoA locator target (Bluetooth - NCP AoA locator) and one
sample app for a locator host. The NCP target sample project can be found in Simplicity Studio and the host sample app can be found in
the SDK folder inside app/bluetooth/example_host/aoa_locator. The full path is:
C:\SiliconLabs\SimplicityStudio\v5\developer\sdks\gecko_sdk_suite\<version>\app\bluetooth\example_host\aoa_locator
While the NCP AoA locator application is unified for all variants (connection-based, connectionless and Silicon Labs proprietary), the
locator host should be compiled for each variant separately.
Figure 3-1. AoA Locator
The physical interface between the AoA locator host and NCP AoA locator can be either virtual COM port over USB (VCOM) or TCP/IP.
In the latter case, the WSTK with the antenna board can be decoupled in space from the host, as long as the host reaches the NCP AoA
locator using its IP address.
3.1 NCP AoA Locator Sample Application
The Bluetooth SDK v3.x provides the Bluetooth - NCP AoA locator example project to support an NCP AoA locator that can receive
and sample CTEs transmitted by asset tags.
The NCP AoA locator (EFR32) is responsible for:
• Running the Bluetooth stack
• Initializing the CTE transmitter and receiver classes
• IQ sampling
• Antenna switching
• Mirroring the BGAPI interface to UART
silabs.com | Building a more connected world. Rev. 0.3 | 10
Loading...