Introduction

This module is a study of the Angle of Arrival (AoA). AoA is a technique for finding the direction that an incoming packet is coming from. The estimated time to complete this lab is between 2-3 hours. It is assumed that the reader has a basic knowledge of embedded C tool chains and general C programming concepts.

This lab is based on the rtls_master, rtls_slave and rtls_passive projects that are part of the SimpleLink™ CC13X2 / CC26X2 SDK.

First, the lab will cover an overview on how to get started with the AoA projects. Subsequent tasks of this lab will guide the user on how to customize these projects in order to answer most of the common AoA questions.

Prerequisites

Recommended reading

These chapters in the TI BLE5-Stack User's Guide

• TI BLE5-Stack Quick Start
• The CC13x2 or CC26x2 SDK Platform
• Application
• BLE5-Stack
• RTLS Toolbox
• Network Processor Interface (NPI)

Project readme files:

• rtls_master Readme located in <SimpleLink CC13X2 / CC26X2 SDK> → examples → rtos → Board → ble5stack → rtls_master folder within the CC13X2 / CC26X2 SDK.
• All relevant information to rtls_slave and rtls_passive is contained in the rtls_master readme
• rtls_agent Readme located in <SimpleLink CC13X2 / CC26X2 SDK> → tools → ble5stack → rtls_agent folder within the CC13X2 / CC26X2 SDK. This will be covered in detail in Task 2.

Software for desktop development

• SimpleLink CC13X2-26X2 SDK 4.20
• Those listed under the Dependencies section of the CC13x2-26x2 SDK Release Notes

This module requires the following kits:

• 2x or 3x SimpleLink™ CC26x2R LaunchPad™
• 1x or 2x BOOSTXL-AoA

Getting started with AoA booster pack

Getting started – Desktop

At the end of this task you must have:

• SimpleLink CC13X2-26X2 SDK installed
• Working Python environment
• Used rtls_example.py script that sets up an RTLS network.
• A basic knowledge of the positioning techniques
• Used the RTLS toolbox and the RTLS UI

Install the Software

1. Run the SimpleLink CC13X2 / CC26X2 SDK installer.
2. Install Python 3.7 or later from the Python Download page.
3. Setup the Python environment as described in the README.md in <SimpleLink CC13X2 / CC26X2 SDK> → tools → ble5stack → rtls_agent folder.
4. If a bash environment doesn't exist on your system, install Git bash

This gives you:

• The SDK with TI-RTOS included at <SIMPLELINK_CC13X2_26X2_SDK_INSTALL_DIR> which defaults to C:\ti\simplelink_cc13x2_26x2_sdk_x_xx_xx_xx.
• Python 3.7 environment with all dependencies required by the RTLS Node Manager

Load the software

• Load Board #1 + BOOSTXL-AoA with rtls_passive project:
  <SimpleLink CC13X2 / CC26X2 SDK> → examples → rtos → CC26X2R1_LAUNCHXL → ble5stack → rtls_passive
• Load Board #2 with rtls_slave project:
  <SimpleLink CC13X2 / CC26X2 SDK> → examples → rtos → CC26X2R1_LAUNCHXL → ble5stack → rtls_slave
• Load Board #3 with rtls_master project:
  <SimpleLink CC13X2 / CC26X2 SDK> → examples → rtos → CC26X2R1_LAUNCHXL → ble5stack → rtls_master

Localization Techniques

A Real Time Localization System can be defined as a system capable of determining the position of a target within a defined physical area in real time. The physical area is normally defined through deployment of reference/locator nodes.

There are two fundamentally different approaches to location finding:

Trilateration, where you know the distance between a reference node and a target node. RSSI based techniques are typical examples of trilateration.

Triangulation, where you know the direction from a reference node to a target node. Angle of Arrival is a technique that can be used to measure the angle from the receiver to the transmitter.

RTLS Toolbox Introduction

In the previous paragraph, we discussed how multiple AoA nodes can combine angle information to perform triangulation. It is important to remember in the pictures above, it is not possible for one single node to localize an object using the TI sample applications. A single AoA node only produces one angle. By nature this is an ambiguous measurement. If there are at least two nodes providing AoA data, then localization can occur. This requires a fourth device that is capable of combining the samples from the individual nodes and finding the intersection.

The intersection between the angles (AoA) is the estimated location of the device. An overview of the topology is shown below. In the diagram below, the black, blue, and red boxes represent CC26x2R LaunchPads while the grey box is a PC.

For a comprehensive presentation of the RTLS toolbox and its software components, please see the TI BLE5-Stack User's Guide

RTLS Roles and Topology

Each node in an RTLS network utilizes the software components listed above in a different role to perform a specific task related to localization. There are three examples: rtls_master, rtls_slave, and rtls_passive. The capabilities of these examples are explained below.

Running the RTLS Visual Demo

In this sub-part, we are going to use the UI (User Interface). This tool runs on a computer. You will find RTLS_UI in <SimpleLink CC13X2 / CC26X2 SDK> → tools → ble5stack → rtls_agent → rtls_ui folder.

1. Apply any fixes from the RTLS known issues page on E2E

2. Build the projects and flash the LaunchPads as described before

3. Connect the master and passive devices to the computer. The slave device must be powered but does not require to be connected to the computer.

4. Execute the program rtls_ui (stored <SimpleLink CC13X2 / CC26X2 SDK> → tools → ble5stack → rtls_agent → rtls_ui)

5. This will open your default web-browser and connect you to a local server. If your default browser is not supported (typically if your default web browser is IE), you will have to copy-paste the address of the server in a supported web browser.

Review RTLS UI's welcome page, then click on "Get Started!"

1. The UI will display the devices detected. The UI only detects the RTLS receivers (i.e. the master and passive devices). The UI will NOT display the slave device(s) eventually connected to the computer.

2. Select the launchpad(s) to use. Only the master and (eventually) passive devices have to be selected. Once done, click on "Continue"

   

3. The system is ready! Click on "Auto Play" to start the demo:

   

4. This will automatically:

   • launch a scan to detect the slave device
   • connect the slave device
   • enable continuous connection information monitoring
   • enable AOA measurement

Running the RTLS Non-Visual Demo

In this sub-part we are going to use a Python script to directly interact with the nodes. This gives power to the developer to define custom behavior of the RTLS network and control the devices directly. Specifically, this will cover setting up the required Python dependencies and running the rtls_example_with_rtls_util.py template script provided in the SDK.

1. Install Python per steps in Getting started
2. Open a command prompt (Git Bash is recommended)

3. Create a Python virtual environment

   • Navigate to the SDK folder (e.g. C:\ti\simplelink_cc13x2_26x2_sdk_x_xx_xx_xx\tools\ble5stack\rtls_agent)
   • Execute py -3.7 -m venv .venv (windows) or python3 -m venv .venv (mac).
   • This will create a folder called .venv in the current directory that includes a copy of the python interpreter and a sandbox for installing packages.
   • Activate virtual environment using source .venv/Scripts/activate (bash) or .venv\Scripts\activate.bat (Windows cmd)
   • Observe that when a venv is activated (.venv) will appear before each cmd prompt
   • Notice that once the virtual environment is activated, the python command will use the local Python interpreter in the venv. See Virtual Environments for more info.

4. Install RTLS packages

   This step will use package.bat (for Windows) or package.sh (for Linux / Mac) to install the RTLS packages.

   Workaround to deal with hard-coding in package install scripts

   Unfortunately the package install script hard-codes the python 3 location. This does not work if you have created a virtual environment as per the previous step. To fix this:

   • In Windows, make the following change (code on right is fixed version):
     
   • In Linux/Mac, make the following change (code on right is fixed version):
     
   • In Windows, run winpty ./package.bat -c -b -u -i (winpty must be omitted if you are using PowerShell or CMD terminal). In Linux / Mac run package.sh -c -b -u -i

5. Install required external Python Dependencies into the newly created virtual environment

   • Execute python -m pip --proxy www.proxy.com install -r requirements.txt
   • Note that above --proxy www.proxy.com is only required if behind a proxy.
   • www.proxy.com is an example of a proxy. It should be replaced with the web address of your specific proxy if applicable.
   • This will install the required external Python packages that are needed by the RTLS Python suite (these are listed in requirements.txt).

6. Open the examples/rtls_example_with_rtls_util.py, find and update the following lines.

   Select text

   devices = [
     {"com_port": "COM37", "baud_rate": 460800, "name": "CC26x2 Master"},
     {"com_port": "COM29", "baud_rate": 460800, "name": "CC26x2 Passive"},
   

   Make sure to list all the master and passive LaunchPads used an to update properly the COM ports used. It is not required to add the slave device to this list.

   Note

   The "name" field above does not affect the functionality. It is simply used for logging purposes and therefore it is not required to modify this if not desired.

7. Save the file and run it using python -u examples/rtls_example_with_rtls_util.py.

   • The script will scan for RTLS devices, connect, and then print continuous connection information (RSSI, channel) for 5 seconds.
   • See below for sample output snippet (note that the addresses and COM ports will be different).
   • The out-of-box demo only reports continuous connection information (CCI). The following sections will help you to leverage all the capabilities of the provided scripts.

Master : <RTLSNode(CC26x2 Master, started 22068)>
Passives : [<RTLSNode(CC26x2 Passive, started 23740)>]
All : [<RTLSNode(CC26x2 Passive, started 23740)>, <RTLSNode(CC26x2 Master, started 22068)>]
Devices Reset
Start scan for 15 sec
Scan Results: [{'addr': '80:6F:B0:1E:3A:8B', 'addrType': 0, 'rssi': -61}]
Connection Success
CCI Callback Set
[08:10:2020 13:59:38:441627] : {"name": "CC26x2 Passive", "type": "conn_info", "identifier": "80:6F:B0:1E:37:14", "payload": {"rssi": -71, "channel": 13}}
[08:10:2020 13:59:38:443650] : {"name": "CC26x2 Master", "type": "conn_info", "identifier": "80:6F:B0:1E:3F:06", "payload": {"rssi": -51, "channel": 2}}
CCI Started
Going to sleep for 5 sec
[08:10:2020 13:59:38:544616] : {"name": "CC26x2 Passive", "type": "conn_info", "identifier": "80:6F:B0:1E:37:14", "payload": {"rssi": -72, "channel": 24}}
[08:10:2020 13:59:38:544616] : {"name": "CC26x2 Master", "type": "conn_info", "identifier": "80:6F:B0:1E:3F:06", "payload": {"rssi": -51, "channel": 13}}
[08:10:2020 13:59:38:644620] : {"name": "CC26x2 Passive", "type": "conn_info", "identifier": "80:6F:B0:1E:37:14", "payload": {"rssi": -75, "channel": 35}}
[08:10:2020 13:59:38:644620] : {"name": "CC26x2 Master", "type": "conn_info", "identifier": "80:6F:B0:1E:3F:06", "payload": {"rssi": -50, "channel": 24}}
[08:10:2020 13:59:38:746616] : {"name": "CC26x2 Passive", "type": "conn_info", "identifier": "80:6F:B0:1E:37:14", "payload": {"rssi": -74, "channel": 9}}
[08:10:2020 13:59:38:746616] : {"name": "CC26x2 Master", "type": "conn_info", "identifier": "80:6F:B0:1E:3F:06", "payload": {"rssi": -49, "channel": 35}}
[08:10:2020 13:59:38:845621] : {"name": "CC26x2 Passive", "type": "conn_info", "identifier": "80:6F:B0:1E:37:14", "payload": {"rssi": -70, "channel": 20}}

...

[08:10:2020 13:59:43:257107] : {"name": "CC26x2 Passive", "type": "conn_info", "identifier": "80:6F:B0:1E:37:14", "payload": {"rssi": -71, "channel": 23}}
[08:10:2020 13:59:43:259117] : {"name": "CC26x2 Master", "type": "conn_info", "identifier": "80:6F:B0:1E:3F:06", "payload": {"rssi": -49, "channel": 12}}
[08:10:2020 13:59:43:355919] : {"name": "CC26x2 Passive", "type": "conn_info", "identifier": "80:6F:B0:1E:37:14", "payload": {"rssi": -76, "channel": 34}}
[08:10:2020 13:59:43:359918] : {"name": "CC26x2 Master", "type": "conn_info", "identifier": "80:6F:B0:1E:3F:06", "payload": {"rssi": -49, "channel": 23}}
[08:10:2020 13:59:43:458910] : {"name": "CC26x2 Passive", "type": "conn_info", "identifier": "80:6F:B0:1E:37:14", "payload": {"rssi": -74, "channel": 8}}
[08:10:2020 13:59:43:461956] : {"name": "CC26x2 Master", "type": "conn_info", "identifier": "80:6F:B0:1E:3F:06", "payload": {"rssi": -49, "channel": 34}}
Try to stop CCI result parsing thread
STOP Command Received
CCI Stopped
Master Disconnected
Done

Building Custom RTLS Python Scripts

With the environment setup, it is time for us to use Python directly to control the RTLS nodes. The goal of this task is to explain the RTLS PC software and to walk through setting up a RTLS network.

RTLS Node Manager Python Overview

First, we will briefly discuss the important layers of the Python solution and their role.

/rtls_agent
    /examples/
      rtls_example_with_rtls_util.py - Example to exercise rtls_util functionality
      rtls_aoa_iq_with_rtls_util_export_into_csv.py - Example to store the IQ data (or AOA) to a file on your computer
      rtls_aoa_multi_conn_example.py - Example to exercice the multi-connections capability of the RTLS devices
    /rtls_util/
         Main interface for examples. Class that abstracts RTLSManager and RTLSNode
         functionality. Handles waiting for RTLS responses in order to provide synchronous
         API's.  Raises any unexpected functionality as an exception.
         Please review the README file for details.

    /rtls/
        /rtls/
            rtlsmanager.py - Class to manage multiple nodes in an RTLS network.
                             Subscribes to incoming data from the nodes, routes
                             outgoing data to each of the nodes. Distributes
                             connection parameters from master node to any
                             connected passive nodes when an connection is
                             established. Handles messages from rtls_agent_cli server
                             if one is provided.

            rtlsnode.py -    Class that implements the basic functionality of a node
                             in an RTLS network. This class will query the embedded
                             device connected to it and determine its capabilities.
                             Essentially this assigns a role in an RTLS context to
                             a COM port.

            ss_rtls.py       Defines the commands in the RTLS UNPI subsystem.
                             This file will define builder classes for the various
                             UNPI commands that the RTLS subsystem supports.

      /unpi/
          serialnode.py - Thread that manages serial communication from COM ports.
                          to higher layers.
                          Queues up messages and sends them to parser.
          unpiparser.py - Parser for Unified Network Processor Interface messages.
                          Implements UNPI frame format packing/unpacking.

RtlsUtil Summary

It is recommended to build RTLS based Python applications on top of the RtlsUtil class within rtls_util.py. This class forms the RTLS API set. A call to an RtlsUtil method translates to a sequence of one or more RTLS UNPI commands / responses from ss_rtls.py. In this way, RtlsUtil is an abstraction of both the RTLS UNPI communication as well as the RTLSManager which manages the various RTLSNode's.

Any errors in an RtlsUtil method will be reported as an exception raised to the RtlsUtil consumer (i.e. rtls_example_with_rtls_util.py). Alternatively, if the method returns, the functionality has been performed successfully.

Asynchronous localization data is received and stored into one of the following queues depending on the data:

• RtlsUtil.aoa_results_queue
• RtlsUtil.tof_results_queue
• RtlsUtil.conn_info_queue

RTLS Python Program Template

The rtls_example_with_rtls_util.py from the previous task shows how to perform basic initialization of RtlsUtil as well as setting up the networking and collecting localization data.

Here we highlight some of the important parts of the example:

The beginning of main() has several boolean variables to enable / disable example functionality. It is possible to combine any of these modes together.

• cci: Continuous Connection Information
• aoa: Angle of Arrival
• update_conn_interval: Updating Connection Interval

Common Initialization

There is initialization functionality that is common to all modes. First, construct an instance of the RTLSUtil class to serve as the RTLS Node Manager interface. The first parameter is the file to log debug information to and the second parameter is the logging level.

rtlsUtil = RtlsUtil(logging_file, RtlsUtilLoggingLevel.UTIL_ALL)

Then set the timeout property to specify how long (in seconds) to wait for a response to a synchronous rtls command. A RtlsUtilTimeoutException will be raised if no response is received in this time.

rtlsUtil.timeout = 30

Next, create a dictionary of devices and pass this to RTLS.set_devices() which will create RTLSNode's for each device and an RTLSManager class using these nodes.

devices = [
  {"com_port": "COM32", "baud_rate": 460800, "name": "CC26x2 Master"},
  {"com_port": "COM26", "baud_rate": 460800, "name": "CC26x2 Passive"},
]

RTLS.set_devices() will send RTLS_CMD_IDENTIFY to each node to identify it's capabilities and set the relevant master / passive(s).

Next, reset both nodes:

rtlsUtil.reset_devices()

The procedures above will appear, from a UNPI perspective, as the following:

RTLS Network Setup Procedure

At this point you should have a basic understanding of RTLS classes. Next we will cover the minimum commands required to setup an RTLS network.

In all cases a BLE connection is a prerequisite for performing localization. The sequence diagram below shows the UNPI commands required to establish a connection between rtls_master and rtls_slave.

As covered in the BLE connections lab, before connecting, a scan must be performed to see if the desired device is nearby. This is initiated by RtlsUtil.scan(). The scanning device will inspect the advertisement and optionally the scan response data to determine if it wishes to connect to a given advertiser. Usually the scanner is looking for a given token or string in the broadcast data of the advertiser. The RTLS master will look for the string {'R','T','L','S','S','l','a','v','e'} starting at the 3rd byte of the slave's advertisement data. If the advertising device matches the filter, then it will be reported to the PC/Node Manager as RTLS_CMD_SCAN responses which are returned from RtlsUtil.scan() as a list of devices. If the advertising device does not match the filter, it will be discarded.

RtlsUtil.ble_connect() can be used to form a connection to one of the devices in the scan results. This will inform rtls_master to form a connection by issuing an RTLS_CMD_CONNECT along with the peer device's address and address type. The address information can be extracted from the RTLS_CMD_SCAN responses coming from the master node.

If the connection is successful, the RTLS_CMD_CONNECT response will be received with status of RTLS_SUCCESS and RtlsUtil.ble_connect() will return. The RTLS examples do not consider a connection to be established between master and slave until the devices have paired and formed an L2CAP Connection Oriented Channel (CoC). The L2CAP CoC is used to send RTLS sync related information between master and slave. This can include AoA parameters or ToF parameters, or a command to enable AoA or ToF.

Immediately after the BLE connection is established (i.e. GAP_LINK_ESTABLISHED_EVENT received from the stack), the rtls_master will share the connection parameters with the PC/Node Manager via RTLS_CMD_CONN_PARAMS. This information is needed by the connection monitor inside rtls_passive in order to follow the connection between RTLS master and slave.

Setting up RTLS Network in Python

Now that we understand the basics behind the RTLS network and how to set it up, let's review how the rtls_example_with_rtls_util.py sample app sets up the RTLS network. Note that the rtls_example_with_rtls_util.py will do some additional processing after the network is setup. This is will be covered latter in this lab.

The commands required to setup a network belong to the RTLS UNPI subsystem and can be found in the ss_rtls.py file. The sending and receiving of these commands is abstracted through the RtlsUtil class.

Scanning for Devices

We will use the rtls_example_with_rtls_util.py as a starting point. From the sections above, we know that after the nodes are identified, we want to tell the master to scan. This is initiated as such:

  scan_results = rtlsUtil.scan(scan_time_sec)

Alternatively, it is possible to only scan for a specific device address by passing a second "address" parameter as such:

  scan_results = rtlsUtil.scan(scan_time_sec, slave_bd_addr)

After the scan completes (runs for scan_time_sec), the results are returned in scan_results as a list of the following dictionaries:

{
    "addr" : 6 byte address as string,
    "addrType" : address type as int,
}

Connecting to a Device

Now, we have collected a list of scan results and are ready to connect. It is required to specify an address to connect to. The address can be hard-coded:

  slave_bd_addr = "80:6F:B0:1E:38:C3"
  rtlsUtil.ble_connect(slave_bd_addr, connect_interval_mSec)

If you don't know the address, you can read it from the UART display of the slave device. Open a Serial terminal (like putty or Tera Term) on the user/UART port of the rtls_slave LaunchPad. Use 115200 baud, 8N1. It should show the following text:

Initialized
Dev Addr: 0x806FB01E3A8B
Advertising

Alternatively, the address can be extracted from the scan results as such:

  rtlsUtil.ble_connect(scan_results[0], connect_interval_mSec)

Remember, the rtls_master will automatically send the connection parameters once a BLE connection is formed with the rtls_slave. The RTLSManager python class will intercept this and distribute it to all rtls_passive nodes so we don't have to do this in our program. Upon receiving the connection parameters, the rtls_passive connection monitor will begin following the connection between master and slave. Note that it may take some time to establish a connection as this does include LE Secure Connections pairing as well as opening an L2CAP Connection Oriented Channel.

Enabling Localization

Now that the connection has been formed and the connection parameter information has been distributed, it is time to enable one or more localization modes.

Continuous Connection Information

CCI is the default functionality of the out-of-box rtls_example_with_rtls_util.py. It is the most simplistic method and only provides a received signal strength indicator (RSSI) and frequency channel index for each BLE connection event.

CCI can be enabled on both the master and the passive(s) by sending a RTLS_CMD_CONN_INFO UNPI request. This is abstracted and initiated from RtlsUtil as such:

  rtlsUtil.cci_start()

After being enabled, the respective node will send a RTLS_EVT_CONN_INFO UNPI Asynchronous Response after each master-slave connection event. This response contains the RSSI and the channel of the connection event. The master will send this after participating in the connection event with the slave and the passive will send this after it observes the connection event.

RtlsUtil will receive each response and append it to the RtlsUtil.conn_info_queue. This queue can then be processed as desired. The out-of-box example periodically reads and prints from this queue in results_parsing() in a separate thread.

This procedure is shown here:

Miscellaneous Functionality

Stopping the Example

After enabling the localization mode(s), rtls_example_with_rtls_util.py will sleep for 5 seconds then gracefully stop all ongoing over-the-air procedures and any spawned result-processing threads. If it is desired to run for longer than 5 seconds, simply update the timeout_sec in the following code:

  timeout_sec = 5
  print("Going to sleep for {} sec".format(timeout_sec))
  timeout = time.time() + timeout_sec
  while timeout >= time.time():
      time.sleep(0.1)

Updating Connection Interval

It is possible to dynamically update the connection interval of the master-slave BLE connection after the connection has been established via RtlsUtil.set_connection_interval():

new_connect_interval_mSec = 80
rtlsUtil.set_connection_interval(new_connect_interval_mSec)

The new connection parameters are automatically distributed from the node manager to the passive devices so that they capable of maintaining synchronization with the connection after the update occurs. The procedure is shown here:

Introduction to AoA

Bluetooth Core Specification Version 5.1 introduces AoA/AoD which are covered under Direction Finding Using Bluetooth Low Energy Device section.

AoA is for receivers that have RF switches, multiple antennas, can switch antennas and capture I/Q samples when receiving direction finding packets.

AoD is for transmitters that have RF switches, multiple antennas and can switch antennas when transmitting direction finding packets. And receivers only have one antenna but can capture I/Q samples when receiving direction finding packets.

On top of that, the Bluetooth Core Specification version 5.1 specifies the following states can support sending direction finding packets:

1. Periodic advertising; also called Connectionless CTE
2. Connection; also called Connection CTE

The theory behind AoA/AoD and Connectionless/Connection CTE is the same, therefore in this SimpleLink Academy training, we will only focus on Connection CTE AoA.

We will explain the AoA theory first and the walk through our SimpleLink CC13X2 / CC26X2 SDK offering.

AoA measurement is typically a 3-step process:

1. Collect phase information by sampling the I/Q
2. Calculate the phase difference among the antennas
3. Covert the phase difference into Angle of Arrival

1. Collect phase information by sampling the I/Q

When two (or more) antennas are placed at a given distance apart from each other, their received RF signals will have a phase difference that is proportional to the difference between their respective distances from the transmitter.

Typically, the signal from one antenna will be a delayed version of the signal from the other antenna. If they are sufficiently close (less than Λ(wavelength)/2 between phase centers), you can always determine which is closest to the transmitter.

These path length differences will depend on the direction of the incoming RF waves relative to the antennas in the array. In order to measure the phase difference accurately, the radio wave packet must contain a section of constant tone with whitening disabled where there are no phase shifts caused by modulation.

2. Calculate the phase difference among the antennas

Phase Difference (Φ) is measured by connecting at least two antennas to the same receiver sequentially (more antennas can be added).

In order to get a good estimate of Φ (phase), all other intentional phase shifts in the signal should be removed. Connection CTE AoA solution achieves this by adding CTE at the end of packets.

Connection CTE Packet Format

This gives the receiver time to synchronize the demodulator first, and then store the I/Q samples from the CTE into radio RAM. The I/Q data is then extracted by the application layer.

I/Q samples are used to estimate phase difference among antennas. When the receiver gets AoA packets, the RF core will trigger an event that will lead to start of the antenna switching. The RF core will start sampling the I/Q data after the guard period of the CTE and the sampled data will be stored in the radio RAM.

By comparing the I/Q data collected from different antennas, users can get the relative phase difference among antennas.

3. Convert the phase difference into Angle of Arrival

Last step is converting the phase shift (Φ) back to AoA (Θ). If Φ is negative, this means that antenna 2 is ahead of antenna 1. In this case Θ is negative too but this does not cause any mathematical problem as sin() and arcsin() functions are defined both for positive and negative numbers. To avoid any unnecessary complications we will consider here Φ to be positive.

The angle between the incident wave and antenna array is Θ. Base on the picture below we know that the sin(Θ) = r/d, and d is the distance between antenna 1 and antenna 2 which is known. Then all we need to find out is r.

r is the distance to antenna 2 that the incident wave needs to travel after arriving at antenna 1. We have found that the phase difference between antenna 1 and antenna 2 is Φ, so the extra distance r is equal to wavelength of the incoming signal * Φ/(2Π).

r= Λ* Φ/(2Π)

Task 1 – Running the AoA application

The SimpleLink CC13X2-26X2 SDK has three examples dedicated to performing AoA (rtls_master, rtls_slave and rtls_passive).

In the TI BLE5-Stack User's Guide → RTLS Toolbox → Angle of Arrival → AoA application Overview, we have covered how the application works.

Therefore, after following the instruction on running the RTLS visual demo, you should be able to get it up and running.

Task 2 – Modify AoA application to use the other antenna array

The out of box SimpleLink CC13X2-26X2 SDK example will always use the first antenna array.

• We will go from this configuration (using antenna array #1):

  

• To this configuration (using antenna array #2):

  

In the python script, modify the aoa_params structure as followed:

    "aoa_cc26x2": {
        "aoa_slot_durations": 1,
        "aoa_sample_rate": 1,
        "aoa_sample_size": 1,
        "aoa_sampling_control": int('0x20', 16),
        ## bit 0   - 0x00 - default filtering, 0x01 - RAW_RF no filtering,
        ## bit 4,5 - default: 0x10 - ONLY_ANT_1, optional: 0x20 - ONLY_ANT_2
        "aoa_sampling_enable": 1,
        "aoa_pattern_len": 3,
        "aoa_ant_pattern": [3, 4, 5]
    }

Task 3 – Modify AoA application to use only two antennas

We will use the out of the box example as the baseline and make the proper changes so we only use 2 antennas from the antenna array 1.

• Out of the box software is using all 3 antennas from A1:

  

• And the end goal is using the following:

  

The antenna toggling pattern is controlled by radio core, therefore the pattern and the pins are passed on to radio core through override list.

In the python script, modify the aoa_params structure as followed:

    "aoa_cc26x2": {
        "aoa_slot_durations": 1,
        "aoa_sample_rate": 1,
        "aoa_sample_size": 1,
        "aoa_sampling_control": int('0x10', 16),
        ## bit 0   - 0x00 - default filtering, 0x01 - RAW_RF no filtering,
        ## bit 4,5 - default: 0x10 - ONLY_ANT_1, optional: 0x20 - ONLY_ANT_2
        "aoa_sampling_enable": 1,
        "aoa_pattern_len": 2,
        "aoa_ant_pattern": [0, 1]
    }

Task 4 – Export raw IQ samples to CSV file

1- Where does the I/Q Samples come from?

So far we have worked on the application code to modify the rtls_passive and/or the rtls_master to work with custom HW. We will now spend some time looking into the I/Q data.

The reason for checking I/Q data is that different HW design will yield different result which will affect your own angle calculation algorithm. For example, if the rf switches you are using need longer settling time than the ones on BOOSTXL-AoA, then you will need to discard more I/Q samples when doing calculations.

To decide how many I/Q samples you can use, you will need to extract I/Q samples and calculate phase to determine at which samples antennas are changing.

We will first take a look at where I/Q samples are stored, in what format and how they are accessed.

• For the Passive device

  I/Q is stored in the radio core RAM(RFC_CTE_RFE_RAM_DATA) and each I/Q pair takes up 32 bits space where I is stored in the lower 16 bits and Q is stored in higher 16 bits.

  Select text

    void AOA_getRfIqSamples(RF_Handle rfHandle, RF_CmdHandle cmdHandle, RF_EventMask events)
    {
      uint8_t state = 0;
      uint8_t lastCapture;
      uint32_t *cteData;
      uint32_t *extCteData = NULL;
  
      if (events & RF_EventCmdDone)
      {
        lastCapture = HWREGB(RFC_CTE_LAST_CAPTURE);
        // check which RAM is capturing samples
        if ((lastCapture == RFC_CTE_CAPTURE_RAM_MCE) || (lastCapture == RFC_CTE_CAPTURE_RAM_RFE))
        {
          // wait while buffer is busy
          do
          {
            state = (lastCapture == RFC_CTE_CAPTURE_RAM_MCE)?HWREGB(RFC_CTE_MCE_RAM_STATE):HWREGB(  RFC_CTE_RFE_RAM_STATE);
          } while ((state == RFC_CTE_RAM_STATE_BUSY) || (state == RFC_CTE_RAM_STATE_DUAL_BUSY));
  
          // check if buffer is ready for reading
          if ((state == RFC_CTE_RAM_STATE_READY) || (state == RFC_CTE_RAM_STATE_DUAL_READY))
          {
            if (lastCapture == RFC_CTE_CAPTURE_RAM_MCE)
            {
              // get the MCE buffer address
              cteData = (uint32_t *)RFC_CTE_MCE_RAM_DATA;
              extCteData = (uint32_t *)RFC_CTE_RFE_RAM_DATA;
            }
            else
            {
              // get the RFE buffer address
              cteData = (uint32_t *)RFC_CTE_RFE_RAM_DATA;
            }
  
            // This will trigger the upper layer which polls samplesReady
            if (cteData != NULL && extCteData == NULL)
            {
              memcpy(gAoaReport.samples, cteData, AOA_RES_MAX_SIZE * sizeof(AoA_IQSample));
              gAoaReport.sampleState = SAMPLES_READY;
            }
  
            // release the RAM so it should be available for next CTE
            if (lastCapture == RFC_CTE_CAPTURE_RAM_MCE)
            {
              HWREGB(RFC_CTE_MCE_RAM_STATE) = RFC_CTE_RAM_STATE_EMPTY;
            }
            else
            {
              HWREGB(RFC_CTE_RFE_RAM_STATE) = RFC_CTE_RAM_STATE_EMPTY;
            }
          }
        }
      }
  
      // If we don't have samples at this point then they are not valid
      if (gAoaReport.sampleState != SAMPLES_READY)
      {
        gAoaReport.sampleState = SAMPLES_NOT_VALID;
      }
    }
  

  AOA.c

  In rtls_passive, the function AOA_getRfIqSamples is executed (more or less directly) by the function AOA_postProcess (which is itself called by RTLSCtrl_postProcessAoa, i.e. at the end of each connection event).

• For the Master device

  For the master device, the BLE stack is responsible for reading the I/Q samples from the radio core. The tables containing the I/Q samples (or at least pointers on them) are sent back by the BLE Stack through messages stored in the ICall queue. The message containing I/Q samples are handled by the function RTLSMaster_processRtlsSrvMsg (in rtls_master.c). This leads to the execution of the function RTLSCtrl_aoaResultEvt (in rtls_ctrl.c) which in turn enqueues a message of type AOA_RESULTS_EVENT in the RTLS message-queue.

  Finally (and as it is done on the passive's side) the AOA_RESULTS_EVENT triggers the function AOA_postProcess. The master does not execute the function AOA_getRfIqSamples (the I/Q samples are part of the pEvt structure passed to AOA_postProcess).

2- How to send the I/Q samples to the computer?

1. If you haven't done it yet, change the COM port used by the script. Of course, if you are not using the passive device, you can comment the corresponding line.

   Select text

    {"com_port": "COM12", "baud_rate": 460800, "name": "CC26x2 Master"},
    {"com_port": "COM14", "baud_rate": 460800, "name": "CC26x2 Passive"},
   

   Set up the COM ports used

2. To extract the I/Q data from embedded devices over UART, we need to make sure that we have enough time to flush the I/Q data before next AoA packet arrives.

   To achieve this, there are two options:

   • Increase the connection interval (it is what we are going to do in this lab). In the rtls_master readme file, it's mentioned that the connection interval should be larger than 300ms to accommodate outputting all the samples.

   • Increase the UART baudrate.

     Expand to see how to increase UART baudrate

     For SDK 3.30 and latter, the default UART baudrate is set to 460800. This value is set and can be modified in the function RTLSHost_openHostIf (in the file rtls_host_npi.c, stored in the folder RTLSCtrl.)

     Select text

       npiPortParams.portParams.uartParams.baudRate = 921600;
     

     Change baudrate (for example) to 921600

     Note: The procedure is the same for both passive and master.

     If you modify the baudrate in the embedded code, don't forget to modify the baudrate used by the python script to communicate with the devices...

     Select text

         {"com_port": "COM12", "baud_rate": 921600, "name": "CC26x2 Master"},
         {"com_port": "COM14", "baud_rate": 921600, "name": "CC26x2 Passive"},
     

     Set up the baudrates used

   In this lab we will increase connection interval to 500ms and leave the baudrate as is.

   → Change the connect_interval_mSec parameter to the following code in rtls_example_with_rtls_util.py.

   Select text

    connect_interval_mSec = 500 #100
   

   Set up connection interval to be 500ms

   Post Processing on Embedded Device

   For users that will do I/Q data post process on chip, there is no limitation on the connection interval.

3. Now we will build on top of the python script that is used in running the RTLS non-visual demo

   First we create a csv file to store I/Q data for analyzing later if needed. Normally, this code is already written in your rtls_aoa_iq_with_rtls_util_export_into_csv.py file, in the function initialize_csv_file. This function assumes that you have properly imported the csv package and declared the global variables csv_writer and csv_row. You can change the filename to whichever suits you better.

   Select text

    global csv_writer
    global csv_row
   
    # Prepare csv file to save data
    data_time = datetime.datetime.now().strftime("%m_%d_%Y_%H_%M_%S")
    filename = f"{data_time}_rtls_raw_iq_samples.csv"
    outfile = open(filename, 'w', newline='')
   
    csv_fieldnames = ['pkt', 'sample_idx', 'rssi', 'ant_array', 'channel', 'i', 'q']
    csv_row = namedtuple('csv_row', csv_fieldnames)
   
    csv_writer = csv.DictWriter(outfile, fieldnames=csv_fieldnames)
    csv_writer.writeheader()
   

   Create a csv file to log I/Q data

4. The devices must be reseted, then the master can scan and connect

   Select text

        ## Reset the passive and the master
        rtlsUtil.reset_devices()
   
        ##...
   
        ## Ask the master to scan
        scan_results = rtlsUtil.scan(scan_time_sec)
   
        ##...
   
        ## Ask the master to connect a device
        rtlsUtil.ble_connect(scan_results[0], connect_interval_mSec)
   

   Set the parameter to configure the devices

5. Once the slave and the master are connected, we can start the setup of AoA parameters

   To extract I/Q data, the AoA operation mode needs to be AOA_MODE_RAW. If needed, modify in the aoa_params structure, modify the aoa_run_mode to the following:

   Select text

        aoa_params = {
            "aoa_run_mode": "AOA_MODE_RAW",  ## AOA_MODE_ANGLE, AOA_MODE_PAIR_ANGLES, AOA_MODE_RAW
            "aoa_cc2640r2": {
                "aoa_cte_scan_ovs": 4,
                "aoa_cte_offset": 4,
                "aoa_cte_length": 20,
                "aoa_sampling_control": int('0x00', 16),
                ## bit 0   - 0x00 - default filtering, 0x01 - RAW_RF no filtering - not supported,
                ## bit 4,5 - 0x00 - default both antennas, 0x10 - ONLY_ANT_1, 0x20 - ONLY_ANT_2
            },
            "aoa_cc26x2": {
                "aoa_slot_durations": 1,
                "aoa_sample_rate": 1,
                "aoa_sample_size": 1,
                "aoa_sampling_control": int('0x10', 16),
                ## bit 0   - 0x00 - default filtering, 0x01 - RAW_RF no filtering,
                ## bit 4,5 - default: 0x10 - ONLY_ANT_1, optional: 0x20 - ONLY_ANT_2
                "aoa_sampling_enable": 1,
                "aoa_pattern_len": 3,
                "aoa_ant_pattern": [0, 1, 2]
            }
        }
   

   Set the parameter to configure the devices

6. Let's have a look to the mode that used after a BLE connection has been established. Basically, the data are written to the .csv file until a STOP command is received.

   Select text

        try:
            data = q.get(block=True, timeout=0.5)
            if isinstance(data, dict):
                data_time = datetime.datetime.now().strftime("[%m:%d:%Y %H:%M:%S:%f] :")
                print(f"{data_time} {json.dumps(data)}")
   
                offset = data['payload'].offset
                payload = data['payload']
   
                # If we have data, and offset is 0, we are done with one dump
                if offset == 0 and len(dump_rows):
                    pkt_cnt += 1
   
                    # Make sure the samples are in order
                    dump_rows = sorted(dump_rows, key=lambda s: s.sample_idx)
   
                    # Write to file
                    for sample_row in dump_rows:
                        csv_writer.writerow(sample_row._asdict())
   
                    # Reset payload storage
                    dump_rows = []
   
                # Save samples for writing when dump is complete
                for sub_idx, sample in enumerate(payload.samples):
                    sample = csv_row(pkt=pkt_cnt, sample_idx=offset + sub_idx, rssi=payload.rssi,
                                       ant_array=payload.antenna, channel=payload.channel, i=sample.i, q=sample.q)
                    dump_rows.append(sample)
   
            elif isinstance(data, str) and data == "STOP":
                print("STOP Command Received")
   
                # If we have data, and offset is 0, we are done with one dump
                if len(dump_rows):
                    # Make sure the samples are in order
                    dump_rows = sorted(dump_rows, key=lambda s: s.sample_idx)
   
                    # Write to file
                    for sample_row in dump_rows:
                        csv_writer.writerow(sample_row._asdict())
   
                break
            else:
                pass
        except queue.Empty:
            continue
   

   Script's main loop (in results_parsing subfunction)

   Log file

   By default, the script produces a log file. This file is stored in the same path as the .csv file (i.e. in the directory from where the script was run) and can be useful for debug.

7. After running the script, you can see the following format in the csv file.

   

   Remark 1: The names of the columns are chosen when the CSV is initialized.

   Select text

    csv_fieldnames = ['pkt', 'sample_idx', 'rssi', 'ant_array', 'channel', 'i', 'q']
    csv_row = namedtuple('csv_row', csv_fieldnames)
   
    csv_writer = csv.DictWriter(outfile, fieldnames=csv_fieldnames)
    csv_writer.writeheader()
   

   Remark 2: The data written in each column are chosen by the following code.

   Select text

    # Samples are prepared
    sample = csv_row(pkt=pkt_cnt, sample_idx=offset + sub_idx, rssi=payload.rssi,
                       ant_array=payload.antenna, channel=payload.channel, i=sample.i, q=sample.q)
    dump_rows.append(sample)
   
    #...
   
    # Samples are written to the CSV file latter
    for sample_row in dump_rows:
        csv_writer.writerow(sample_row._asdict())
   

3- How to treat the I/Q samples on the computer?

Here we are only interested in the payload part of the AOA_MODE_RAW command. The AOA_MODE_RAW payload has the following structure. In the python script provided above, we have extracted most of the information and save them to a csv file.

  struct = Struct(
      "rssi" / Int8sl,
      "antenna" / Int8ul,
      "channel" / Int8ul,
      "offset" / Int16ul,
      "samplesLength" / Int16ul,
      "samples" / GreedyRange(Struct(
          "q" / Int16sl,
          "i" / Int16sl,
      )),
  )

import matplotlib.pyplot as plt
import pandas as pd
import math

def cal_magnitude(q_value,i_value):

    return math.sqrt(math.pow(q_value,2)+math.pow(i_value,2))

def cal_phase(q_value,i_value):

    return math.degrees(math.atan2(q_value,i_value))

if __name__ == "__main__":
    df = pd.read_csv('sla_rtls_raw_iq_samples.csv')
    AOA_RES_MAX_SIZE=81

    # We only want one set of data per channel
    df = df.drop_duplicates(subset=['channel','sample_idx'] , keep='first')

    # We Calculate the phase and the margin
    df['phase'] = df.apply(lambda row: cal_phase(row['q'], row['i']), axis=1)
    df['magnitude'] = df.apply(lambda row: cal_magnitude(row['q'], row['i']), axis=1)

    # Plot all the I/Q collected. Each channel will have a plot which contains I/Q samples.
    # If you have collected I/Q data on 37 data channels, then there will be 37 windows popped up
    grouped = df.groupby('channel')
    grouped[['i', 'q']].plot(title="I/Q samples", grid=True)
    plt.show()

    # Create 4 plots and each plot has x number of subplots. x = number of channels
    indexed = df.set_index(['channel', 'sample_idx'])
    indexed.unstack(level=0)[['phase']].plot(subplots=True, title="Phase information", xlim=[0,AOA_RES_MAX_SIZE], ylim=[-190,+190])
    indexed.unstack(level=0)[['magnitude']].plot(subplots=True, title="Signal magnitude", xlim=[0,AOA_RES_MAX_SIZE])
    indexed.unstack(level=0)[['i']].plot(subplots=True, title="I samples", xlim=[0,AOA_RES_MAX_SIZE])
    indexed.unstack(level=0)[['q']].plot(subplots=True, title="Q samples", xlim=[0,AOA_RES_MAX_SIZE])
    plt.show()

After executing the small script provided above, if the angle between rtls_passive rtls_slave is not 0 degree, you can see that magnitude of the sine wave is not the same when you swap between antenna 1 and antenna 2 as shown below.

Another alternative to observe the magnitude of received signal is to calculate it based on I/Q data. Since each I/Q pair is a vector, the magnitude of a vector can be calculated by sqrt(I^2+Q^2).

Using the script provided above, you will see a plot called Signal magnitude. In this plot, you can clear see that received signal magnitude from antenna 2 is almost double as from antenna 1.

Task 5 – Antenna Switch Settling Time

Now that we are equipped with all the needed tools to manipulate I/Q data, we will try to identify when the antenna is toggling in order to help determine which I/Q samples can be used.

As mentioned in Calculate the phase difference among the antennas, I/Q samples can be presented with constellation diagram, each I/Q pair is a vector and its angle is within a range of +180 ~ -180. Therefore when we have an I/Q pair, to obtain the angle information, we can use arctan to get angle of a vector. Then based on the I and Q value, we can find out the corresponding angle.

Luckily in python, the math.atan2 function takes care of the aforementioned logic.

Let's take a look at the Phase Information plot.

A perfect sine wave, assuming it starts at 0 degree, the phase will first go towards +180 and then, once it crosses +180, it will start from -180 and then go back to 0 degrees. From the picture provided below, you can see that in the first 8us(32 samples), there is no abrupt phase change.

When the rf switches and the angle of incident wave is not 0 degree, you will see abrupt phase change. As shown below after 2 periods, we started to switch antennas. Then the phase we obtained is no long linear.

Hence by looking at the phase information plot, you will know how many I/Q samples you can keep per period.

This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.