UG514: Using the Bluetooth ® Direction Finding Tool Suite
A Real Time Locating System (RTLS) consists of many locators that pick up the signals of asset tags to locate them in 3D space.
To calculate the positions of the asset tags, one must know each locator’s position, orientation, and configuration (such as antenna array type, switching pattern, and so on). The Silicon Labs’ Real Time Locating (RTL) library also needs some configuration parameters, such as estimation mode, azimuth, elevation constraits, and so on, to provide the best estimation for a given environment. The Bluetooth Direction Finding Tool Suite is meant to ease development with the Silicon Labs’ RTL library.
It provides multiple tools to configure the system, and also helps development with analyzer tools that calculate many output parameters from the observed IQ samples.
KEY POINTS
• Direction Finding project generation
• AoA Configurator
• AoA Analyzer
• AoA Positioning Tool
Introduction 1 Introduction
Beginning with Bluetooth SDK v3.1, Silicon Labs’ Bluetooth stack supports CTE transmitting and receiving features and can take phase measurements on the incoming signal as specified by the Bluetooth standard. Note, however, that the determination of the angle of incidence from the phase measurements is outside of the scope of the standard and must be implemented in the application. To reduce the Time to Market for its customers, Silicon Labs also offers a reference implementation of a Bluetooth-based Real Time Locating System (RTLS), which provides both an out-of-box experience to evaluate the solution and a flexible framework that makes it possible for every- one to create their own RTLS. To get started with the reference implementation, refer to AN1296: Application Development with Silicon Labs’ RTL Library.
The implementation described in AN1296 requires you to configure and build both individual locators and a locator host application in order to test the system. While the SDK examples provide the openness to customize and add new features to your direction finding project using RTL library APIs directly, the manual configuration of the locators and their topologies may not be a trivial task. It is simpler to configure a single locator and multi-locator setup through interactive graphical interfaces available through the Direction Finding Tools Suite.
AoA Analyzer can:
• Create a locator configuration file without the need to manually edit the .json file, to ease the configurations process.
• Apply the configuration for a single locator board and run the RTL library to estimate angles from the incoming data (without the need to build and run any host sample application).
AoA Analyzer is available through Simplicity Studio’s Tools menu, and through the Direction Finding Dashboard’s editor, as described next.
While it is easy to test a single locator with a single configuration, in a multi-locator use case multiple configurations are needed, not only because there are multiple locators, but also because their relationships must be configured. Simplicity Studio supports a project type called Direction Finding project, which stores configuration files for the multi-locator use case. That project is configured using tools in the Direction Finding Dashboard, including:
MultiLocator Builder: Used to create a multi-locator configuration setup using topologies and individual locator’s configurations, and link them to produce a multi-locator configuration file.
Editor: Used to review and edit a multi-locator configuration and its building blocks, namely the topology and single locator configurations.
The Editor provides a framework that draws on other tools in the Suite:
• The AoA Positioning Tool demonstrates the location estimation of the RTL library. Global RTL settings can also be configured in the tool, and those settings are saved into the multi-locator configuration file.
• AoA Configurator provides an editable 3D representation of a topology and locator devices. Use the tool to add locators, drag them to the desired position, and rotate them to the best orientation.
• AoA Analyzer, described above, to help manage the configurations of individual locators.
Import & Export: Used to migrate configuration files to and from the SDK’s AoA host projects.
2 Single Locator Use Case
2.1 AoA Analyzer
The AoA Analyzer tool can be used to demonstrate the capabilities of the RTL library with regard to the Angle of Arrival (AoA) estimation from Constant Tone Extension (CTE) signals. The tool can be used to configure and connect to a locator, define one or more estimators to pair with asset tags, and evaluate the performance of the RTL library in real-time in various AoA modes.
AoA Analyzer aggregates a set of user-friendly tools that are used for configuring and visualizing direction finding using a single locator.
These include the following tools, described in more detail in the next sections:
LOCATOR: Used for setting locator board-specific parameters.
ESTIMATOR: Used for creating and configuring estimators. Estimator configs contain RTL parameters that are used in angle calculation.
3D VIEW: Used for visualizing the direction of assets with respect to a locator in 3D.
ANALYZER: Used for creating charts using the real-time data stream from asset tags.
Each tool is accessed through a button on the AoA Analyzer’s tool bar.
To launch AoA Analyzer:
1. From Simplicity Studio 5’s Launcher perspective, click Tools.
2. In the Tools Dialog, select AoA Analyzer.
3. Click OK. AoA Analyzer opens in the Simplicity IDE perspective.
Single Locator Use Case
2.1.1 LocatorUse the LOCATOR tool to set locator board-specific configurations. The LOCATOR tool’s functions are annotated in the following figure.
Figure 2-1. Locator Tool (a) Choose the antenna array type: 4x4 URA, 3x3 URA or 1x4 ULA.
(b) Select the switch slot duration: 1 µS, 2 µS
(c) Add the addresses of the allowed list of devices (that is, CTE transmitting tags).
(d) Select the locator device and connect to it.
2.1.2 Estimators
Use the ESTIMATORS tool to configure the RTL Library parameters used in angle calculation based on the data stream collected from an asset tag. These include the AoX Mode, CTE length, and angle constraints. Connect to a locator using the LOCATOR tool before using ESTIMATORS. The ESTIMATORS tool’s functions are annotated in the following figure.
Figure 2-2. Estimators Tool
The functions are grouped as follows:
(a) Shows a list of tags discovered. Here you can:
(d) Record IQ samples for post analysis (replay) (see section 2.1.5 Recording and Playback, or (e) Pause recording and activate live mode.
(b) See a list of estimator configs. The default estimator config is generated automatically. Here you can:
(f) Add a new estimator config or remove the selected estimator config.
(g) Edit the selected estimator config.
(c) See arrows representing combinations of each asset and estimator configs.
You can add as many estimators as you want, and generate multiple arrows representing the direction of an asset tag using different estimator configs. To generate an arrow, select an asset tag in (a), then an estimator config in (b), and click the arrow (→).
To edit an estimator, click Edit (g in Figure 2-2) next to the selected estimator config. The Estimator Settings dialog opens. The settings are annotated in the following figure.
Figure 2-3. Estimator Settings (a) Rename the estimator config.
(b) Select the AoX mode. For more information about the available AoX modes, see the API description page on docs.silabs.com.
(c) Select the CTE length using the sliding bar.
(d) Mark the estimator config as the Default. If this is enabled, the selected estimator config will be used in the export files.
(e) Insert direction (angle) constraints.
Note that you can add as many azimuth and elevation angle constraints as you want. Click the plus sign (e) to add azimuth and elevation constraints, as shown in the following figure.
Figure 2-4. Direction Constraints
Single Locator Use Case
2.1.3 3D ViewUse the 3D VIEW tool to visualize the direction of one or more asset tags based on the estimator configs explained in section 2.1.2 Estimators. The asset tags are indicated by arrows pointing to the direction of the tag with respect to a locator device. An arrow is generated for each combination of asset tag and estimator. As such, one asset tag can be pointed by multiple arrows with different colors.
The real-time azimuth and elevation angles are indicated in a table in the right bottom corner ((a) in the following figure). You can also edit the RTL parameters of the estimators from the 3D View (b). Click Update to see the effect in real time.
Figure 2-5. 3D View
2.1.4 Analyzer
Use the ANALYZER tool to visualize different parameters of an asset tag measured by a locator device in real time using charts. You can create up to 20 charts in one step by combining asset tags, estimators, and the chart types.
To create charts using the ANALYZER tool:
1. Click Charts.
2. Select the number of charts and how they will be displayed in rows and columns.
3. A corresponding grid of chart placeholders is displayed.
4. Click the symbol in the middle of a placeholder. The Add new chart dialog opens. Here you can select the asset tag, estimator, and chart type. Click OK.
5. Repeat for each chart placeholder to populate the Charts display with real-time graphs. For each chart, you can (a) zoom X, (b) zoom Y, (c) go to full screen, or (d) delete the chart.
Single Locator Use Case
2.1.5 Recording and PlaybackUse the recording button in the ESTIMATORS tool to start recording IQ samples (button (d) in Figure 2-2. Estimators Tool). When prompted, save the file into your workspace.
You must save the file in your workspace to play it back or post process it later using the AoA Viewer. You can use the DirectionFind- ingProject/aoaRecords directory (discussed in section 3.3 MultiLocator Builder: Creating a New Configuration) to save the IQ sample recordings of your asset tags.
Stop the recording using the Live mode activating button (button (e) in Figure 2-2. Estimators Tool).
To play back or postprocess the recording, from your project directory, right-click on the recording file and select Open With > AoA Viewer.
Figure 2-6. Opening IQ Sample Recording Files in AoA Viewer
The AoA Viewer provides a 3D View, an Analyzer, and Export functions, accessed through tabs on the toolbar. The Overview tab’s functions are annotated in the following figure.
Figure 2-7. AoA Viewer (a) Choose the AoX Mode
(b) Enable pseudo-spectrum calculation (requires huge computational resources and can be slow) (c) Start the IQ sample processing
Use the 3D VIEW tool ((a) in the following figure) to start the playback. Click/move inside the scroll bar (b) to view the azimuth (A), and Elevation (E) angles for each corresponding event counter value (C).
Figure 2-8. 3D VIEW of the Playback
Use the ANALYZER tool to draw line charts and histograms. If you enabled the pseudo-spectrum calculation, you can also graph a heat map to visualize the pseudo-spectra computation.
Figure 2-9. Drawing Line Charts Using the ANALYZER Tool
Use the EXPORT tool to export the postprocessing results of your IQ sample recordings in either JSON or CSV format.
Multi-locator Direction Finding Projects 3 Multi-locator Direction Finding Projects
While it is easy to test a single locator with a single configuration, in a multi-locator use case multiple configuration files are needed, not only because there are multiple locators, but also because their relationships must be configured. A workspace is required to store the files that belong together. Simplicity Studio supports a project type called Direction Finding project, which is meant to store configuration files for the multi-locator use case.
Before describing the tools used with the multi-locator use case, it is essential to understand how to create a Direction Finding Project and how to populate it with configuration files.
3.1 Project Generation
To create a Direction Finding Project in SSv5:
1. Go to File > New > Project.
2. In the New Project dialog, select Simplicity Studio > Direction Finding Project and click Next.
3. Name the project and click Finish to generate the project.
Figure 3-1. Generating a Direction Finding Project
DirectionFindingProject
└───aoaConfigs
| └───locatorconfig
| └───multilocatorconfigs
| └───topologies
└───aoaRecords
| project1.dfp
The *.dfp project automatically opens in the Direction-Finding Dashboard in the Simplicity IDE. You can also open the dashboard at any time by right-clicking the *.dfp file and selecting Open With > AoA Dashboard.
Figure 3-2. Opening the Direction Finding Dashboard
3.2 Direction-Finding Dashboard
The Direction-Finding Dashboard aggregates a set of user-friendly tools used for setting up, configuring, editing, and migrating configu- ration files.
Figure 3-3. Direction Finding Dashboard MultiLocator Builder: Used for first time setup and configuration.
Editor: Used to review and edit existing configurations and the relationships between them.
Import & Export: Used to migrate configuration files to and from the SDK’s AoA host projects.
Manuals & Tutorials: Contains manuals and tutorials related to Bluetooth direction finding.
3.3 MultiLocator Builder: Creating a New Configuration
Use the MultiLocator Builder tool to create a multi-locator configuration setup using topologies and individual locator’s configurations, and link them to produce a multi-locator configuration file (*.mlc). One direction finding project can host multiple setups.
To create a new multi-locator configuration setup:
1. If the dashboard is not open, double-click the *.dfp file to open it.
2. In the MultiLocator Builder card, click Build.
Multi-locator Direction Finding Projects
3. The MultiLocator Builder tool opens. Each step in the build process is shown across the top of the interface. Name the multi-locatorconfiguration file and click Continue.
4. In the Select Topology dialog, select an existing topology or create a new one by clicking CREATE NEW TOPOLOGY.
5. In the Create New Topology dialog:
(a) Name the topology.
(b) Select locator devices for the topology from the list of connected devices (left side) by clicking plus (
+
) next to the device. You can also add a custom device by clicking the green ‘Add’ symbol (right side).(c) Click CREATE.
When the topology creation is completed, an *.aoaconf file will be created inside the topology directory.
DirectionFindingProject
└───aoaConfigs
| └───locatorconfig
| └───multilocatorconfigs
| └───topologies
| TestSetupTopology.aoaconf
└───aoaRecords
| project1.dfp
6. Next, link the single locator configuration files (*.lc) and the locator devices in the setup. You can use the single locator configuration file (*.lc) that you created using the AoA Analyzer (section 2.1 AoA Analyzer) by copying them to the locatorconfig directory inside your Direction Finding Project.
You can also create a new locator configuration file in the Link Locator config files dialog by clicking the green symbol (a), or open and edit the file in the AoA analyzer by clicking the arrow (b). To use one locator config file for all locator devices, select the config file from the left side and drag it to the plus symbol (c) on the right side. You can also drag and drop a locator config file directly to specific locator device(s).
7. Click Finish (d) and the multi-locator configuration is ready to be opened using the Positioning Tool (see section 4.3 AoA Positioning Tool).
DirectionFindingProject
└───aoaConfigs
| └───locatorconfig
| WallLocatorConfig.lc
| CeilingLocatorConfig.lc
| └───multilocatorconfigs
| └───topologies
| TestSetupTopology.aoaconf
└───aoaRecords
| project1.dfp
Multi-locator Direction Finding Projects
When linking the locator config files is completed, a multi-locator configuration *.mlc file is generated in the corresponding directory.3.4 Editor: Managing the Configuration Structure
In summary, a multi-locator configuration comprises a topology, which defines the coordinates and orientation of the locators, and the single locator configurations of each locator device that forms the topology. The structure of a multi-locator configuration can be visualized better using the Editor tool in the Direction-Finding Dashboard.
1. If the dashboard is not open, double-click the *.dfp file to open it.
2. In the Editor card, click Edit.
The structure of a multi-locator configuration is illustrated in the following figure.
Figure 3-4. Structure of a Multi-locator Configuration a) Multi-locator configurations
b) Topologies
c) Single locator configurations.
All the multi-locator configuration setups hosted in the Direction Finding Project are displayed in order (a). Below each multi-locator configuration, linked AoA configurations/topologies containing two or more locator devices are displayed (b), followed by the device with their respective single locator configuration (c).
DirectionFindingProject
└───aoaConfigs
| └───locatorconfig
| WallLocatorConfig.lc
| CeilingLocatorConfig.lc
| └───multilocatorconfigs
| OfficeSetup.mlc
| └───topologies
| TestSetupTopology.aoaconf
└───aoaRecords
| project1.dfp
3.4.1 Multi-locator Configuration
The Editor tool provides a lot of flexibility to modify a multi-locator configuration and its building blocks, namely the topology and single locator configurations. As shown in the following figure, for a selected multi-locator configuration level the tool exposes all existing topol- ogies that are available in the Direction Finding Project (a). From here, you can replace the topology you want to change by clicking Replace (b), modify the topology by clicking Edit (c), or add a new topology by clicking Add (d).
Figure 3-5. Changing a Topology
3.4.2 Topology Configuration
Under each topology configuration level, as shown in the following figure, the tool lists the locator devices linked with their respective configurations listed below the topology. The tool also exposes devices physically connected to your computer with a debug adapter, or detected on a local network (a). From here, you can link additional locator devices to the selected topology configuration (b).
Figure 3-6. Linking New Devices to a Topology Configuration
Multi-locator Direction Finding Projects
To add new devices manually, click Add (c). In the Add New Device dialog, enter the address type and device address.Figure 3-7. Adding a New Locator Device
3.4.3 Single Locator Configuration
The last configuration item in the multi-locator configuration structure is the single locator configuration. At this level you can see the locator device and the linked single locator configuration file with it. For a selected device, you can:
(a) Remove a device.
(b) Create a new single locator configuration file.
(c) Link a single locator configuration file to a multi-locator setting.
(d) Open a single locator configuration file using AoA Analyzer.
Figure 3-8. Single Locator Configuration
3.5 Import & Export: Migrating Configuration Files
Use the Import & Export tool to migrate configuration files to and from the SDK AoA Locator and Positioning host example projects..
The Direction Finding tool suite provides you with an easy way to configure, test and evaluate the performance of the RTL library in estimating angle of arrivals and locations of asset tags in a 3D plane. You can then export the configuration files to the SDK directory to continue developing your direction-finding project. The Import & Export tool converts the *.lc and *.mlc files to JSON formats that the SDK AoA locator and positioning host applications can consume (and vice versa).
To import or export configuration files:
1. If the dashboard is not open, double-click the *.dfp file to open it.
2. In the Import & Export card, click Open.
Figure 3-9. Import & Export Tool
Tools for the Multi-Locator Use Case 4 Tools for the Multi-Locator Use Case
4.1 AoA Analyzer
In a multi-locator scenario, many locators work independently of each other. These locators must be configured individually the same way as in the Single Locator Use Case. Use AoA Analyzer to create a configuration file for a single locator (.lc), as described in section 2.1 AoA Analyzer.
Multiple locators may need the same configuration. In this case, it is enough to create one configuration file which can be applied to multiple locators later.
4.2 AoA Configurator
In a multi-locator scenario, it can, at times, be a daunting task to determine the orientations of locator boards, especially when the boards are rotated over multiple axes to suit the setup environment. AoA Configurator simplifies this process by providing an editable 3D repre- sentation of your topology and locator devices. With this tool, you can add as many locators as you wish, drag them to the position you want, and rotate them to the best orientation that your actual setup environment allows.
The AoA Configurator can be opened in two ways:
1. In the topology configuration directory, right-click the *.aoaconf file. Select Open With > AoA Configurator.
2. In the Direction-Finding Dashboard, open the Editor tool. Select a topology configuration and click Open 3D Editor.
The AoA Configurator functions are annotated in the following figure.
Figure 4-1. AoA Configurator (a) Add a new locator.
(b) Select a locator, edit a locator’s ID, delete a locator.
(c) Manually edit a locator’s coordinates and orientations.
(d) Translate the axes of a locator.
(e) Rotate a locator to the desired orientation.
When you finish configuring the topology, save the changes and close the tool.
4.3 AoA Positioning Tool
The AoA Positioning Tool is a 3D demo application that demonstrates the location estimation of the RTL library. Global RTL settings can also be configured in the tool, and those settings are saved into the multi-locator configuration file (*.mlc).
The AoA Positioning Tool can be opened in two ways.
1. In the multi-locator configuration directory, right click the *.mlc file. Select Open With > AoA Positioning Tool.
Tools for the Multi-Locator Use Case
2. In the Direction-Finding Dashboard, open the Editor tool. Select a multi-locator configuration and click Open Positioning Tool.The Positioning Tool displays the AoA locator devices configured in your topology configuration on a 3D plane, as shown the following figure.
Figure 4-2. AoA Positioning Tool
(a) Configure the global RTL settings, including the estimation mode, validation method, and filter amount. For more information about these RTL parameters, see https://docs.silabs.com/rtl-lib/latest/group-sl-rtl-loc .
(b) Select a locator.
(c) Connect a selected locator to a locator device physically connected to your computer with a debug adapter or detected on a local network. Note that the locator must be programmed with the Bluetooth – NCP AoA Locator firmware. See QSG175: Getting Started with Silicon Labs’ Direction Finding Solution for more information.
(d) Expand/minimize the sidebars.
After connecting the locators, you are ready to track asset tags and locate them in the positioning tool. Program one or more asset tags with Bluetooth - SoC AoA Asset Tag firmware. Power them up and check the result in the Positioning Tool window.
The tags are displayed on the left panel (a). Select a tag to read the actual x, y, z figures in real time (b).
Figure 4-3. Tracking Asset Tags Using the Positioning Tool
IoT Portfolio
www.silabs.com/IoT SW/HW
www.silabs.com/simplicity Quality
www.silabs.com/quality Support & Community
www.silabs.com/community
Simplicity Studio
One-click access to MCU and wireless tools, documentation, software,
source code libraries & more. Available for Windows, Mac and Linux!
Disclaimer
Silicon Labs intends to provide customers with the latest, accurate, and in-depth documentation of all peripherals and modules available for system and software imple- menters using or intending to use the Silicon Labs products. Characterization data, available modules and peripherals, memory sizes and memory addresses refer to each specific device, and “Typical” parameters provided can and do vary in different applications. Application examples described herein are for illustrative purposes only. Silicon Labs reserves the right to make changes without further notice to the product information, specifications, and descriptions herein, and does not give warranties as to the accuracy or completeness of the included information. Without prior notification, Silicon Labs may update product firmware during the manufacturing process for security or reliability reasons. Such changes will not alter the specifications or the performance of the product. Silicon Labs shall have no liability for the consequences of use of the infor- mation supplied in this document. This document does not imply or expressly grant any license to design or fabricate any integrated circuits. The products are not designed or authorized to be used within any FDA Class III devices, applications for which FDA premarket approval is required or Life Support Systems without the specific written consent of Silicon Labs. A “Life Support System” is any product or system intended to support or sustain life and/or health, which, if it fails, can be reasonably expected to result in significant personal injury or death. Silicon Labs products are not designed or authorized for military applications. Silicon Labs products shall under no circumstances be used in weapons of mass destruction including (but not limited to) nuclear, biological or chemical weapons, or missiles capable of delivering such weapons. Silicon Labs disclaims all express and implied warranties and shall not be responsible or liable for any injuries or damages related to use of a Silicon Labs product in such unauthorized applications.
Note: This content may contain offensive terminology that is now obsolete. Silicon Labs is replacing these terms with inclusive language wherever possible. For more information, visit www.silabs.com/about-us/inclusive-lexicon-project
Trademark Information
Silicon Laboratories Inc.®, Silicon Laboratories®, Silicon Labs®, SiLabs® and the Silicon Labs logo®, Bluegiga®, Bluegiga Logo®, EFM®, EFM32®, EFR, Ember®, Energy Micro, Energy Micro logo and combinations thereof, “the world’s most energy friendly microcontrollers”, Redpine Signals®, WiSeConnect , n-Link, ThreadArch®, EZLink®, EZRadio®, EZRadioPRO®, Gecko®, Gecko OS, Gecko OS Studio, Precision32®, Simplicity Studio®, Telegesis, the Telegesis Logo®, USBXpress® , Zentri, the Zentri logo and Zentri DMS, Z-Wave®, and others are trademarks or registered trademarks of Silicon Labs. ARM, CORTEX, Cortex-M3 and THUMB are trademarks or registered trademarks of ARM Holdings. Keil is a registered trademark of ARM Limited. Wi-Fi is a registered trademark of the Wi-Fi Alliance. All other products or brand names mentioned herein are trademarks of their respective holders.
