RTLS System

Table of Contents

• General Information
• Introduction
• Angle of Arrival - Setup
  • Software Setup
  • Hardware Setup
  • Running The Example
• Time of Flight - Setup
  • Software Setup
  • Hardware Setup
  • Running The Example
• RTLS Control Commands
  • Requests
  • Responses

General Information

1. To get usage information for the RTLS Node Manager scripts and GUI please refer to: tools\blestack\rtls_agent\README.md
2. In order to edit and view how the RTLS subsystem handles uNPI commands, please refer to the following file: tools\blestack\rtls_agent\rtls\ss_rtls.py
3. In order to see a usage example, please refer to tools\blestack\rtls_agent\rtls\test_rtls.py which shows how to use a RTLS Master + RTLS Slave + RTLS Passive combination
4. To access GUI, please refer TI Gallery and look for RTLS Monitor project.

Introduction

This readme contains the following information: 1. How to setup AoA demo 2. How to setup ToF demo 3. Description of commands accepted by RTLS Control and their meaning

Angle of Arrival - Setup

Software Setup

AoA is currently supported on all roles with the following caveats:

RTLS Master

• For RTLS Master and RTLS Slave projects, the configuration -DRTLS_LOCATIONING_AOA in build_config.opt file that is located in the project directory, controls the build.
• To build AoA, keep the option uncommented: -DRTLS_LOCATIONING_AOA
• Master role will not collect I/Q samples

RTLS Slave

• For RTLS Master and RTLS Slave projects, the configuration -DRTLS_LOCATIONING_AOA in build_config.opt file that is located in the project directory, controls the build.
• To build AoA, keep the option uncommented: -DRTLS_LOCATIONING_AOA
• Slave will send out a constant tone at the end of connection packet and it will not collect I/Q samples

RTLS Passive

• RTLS_LOCATIONING_AOA must be defined in predefined symbol/preprocessor symbol.
• Passive will collect I/Q samples
• When using AoA raw output mode (AOA_MODE_RAW), consider the following:
  1. Connection interval of BLE must be at least 300ms to accomodate outputing all of the samples (a large 2k bytes chunk)
  2. Large amounts of heap will be used to support this mode

Hardware Setup

AoA requires 3 devices: RTLS Master/Passive/Slave. The devices should be flashed with the rtls_master/rtls_passive/rtls_slave applications as described above (with AoA flags). Compile and flash your applications - note that the LaunchPad with BOOSTXL-AOA should be used as the RTLS Passive.

• RTLS Master/Slave - These will be CC2640R2F LaunchPad
• RTLS Passive - Requires a special setup with BOOSTXL-AOA

For the RTLS Passive hardware setup, please take a look at Angle of Arrival BoosterPack

Running The Example

The steps to run the out of box example is described in tools\blestack\rtls_agent\README.html

Time of Flight - Setup

Software Setup

RTLS Master

• For RTLS Master and RTLS Slave projects, the configuration -DRTLS_LOCATIONING_AOA in build_config.opt file that is located in the project directory, controls the build.
• To build ToF, comment out the option in the following manner: /* -DRTLS_LOCATIONING_AOA */

RTLS Slave

• For RTLS Master and RTLS Slave projects, the configuration -DRTLS_LOCATIONING_AOA in build_config.opt file that is located in the project directory, controls the build.
• To build ToF, comment out the option in the following manner: /* -DRTLS_LOCATIONING_AOA */s

RTLS Passive

• To enable ToF, RTLS_LOCATIONING_AOA must not be defined (can be left as xRTLS_LOCATIONING_AOA)

Hardware Setup

ToF requires 3 devices: RTLS Master/Passive/Slave. The devices should be flashed with the rtls_master/rtls_passive/rtls_slave applications as described above (with ToF flags).

Calibration

This part is relevant when using TOF_MODE_DIST * To calibrate your devices, keep the RTLS Slave 1m apart from RTLS Master/Passive before starting ToF * Once ToF is started and results start appearing, it means that the device is calibrated and started collecting samples

Using BOOSTXL-AOA on a ToF board

It is possible to have a board that is modified to be used for AoA and still being able to perform ToF with. The user must set the relevant antenna pins (IOID28, IOID29, IOID30) to act as output. For reference, see AOA_openPins function under AOA.c.

Running The Example

The steps to run the out of box example is described in tools\blestack\rtls_agent\README.html

RTLS Control Commands

The commands are split into Requests and Responses and to Sync/Async requests/responses

Sync Requests/Responses

Sync requests will always be answered with Sync responses and usually used to tell RTLS Node Manager that a certain operation has been started successfuly

Async Requests

Async requests will be used by RTLS Control to send out information to RTLS Node Manager and usually used for various types of results

Requests

Requests are the way of the RTLS Node Manager to request actions from RTLS Control - essentially a sort of RPC (Remote Procedure Call) * Note that all requests coming from RTLS Node Manager to RTLS Control are SyncRequests and will always be answered by SyncResponses

---

RTLS_CMD_IDENTIFY

Request a unique identifier from the device

Params

None

RTLS_CMD_RESET_DEVICE

Soft resets the device

Params

None

---

RTLS_CMD_SCAN

Request the RTLS Master device to perform a scan

Params

None

RTLS_CMD_TERMINATE_LINK

Requests the node to terminate the active connection (will work only when connected)

Params

None

RTLS_CMD_CONNECT

Requests to connect to a specific BLE address

Params

• addrType - BLE address type
• peerAddr - BD address for our peer
• connInterval - Latency of the synchronization events (in this case BLE connection interval)

RTLS_CMD_CONN_PARAMS

Sets BLE connection parameters for RTLS Passive

Params

• accessAddress - BLE AccessAddress
• connInterval - BLE Connection Interval
• hopValue - BLE Hop Value
• mSCA - BLE mSCA
• currChan - BLE current channel (used to synchronize RTLS Passive)
• chanMap - BLE Channel Map
• crcInit - CRC Init value

RTLS_CMD_TOF_SET_SEC_SEED

Sets the seed for ToF Security

Params

• seed - the seed itself

RTLS_CMD_TOF_GET_SEC_SEED

Used to extract the seed from RTLS Master and distribute to RTLS Passive nodes

Params

None

---

RTLS_CMD_AOA_SET_PARAMS

Sets AoA parameters

Params

• aoaRole - AoA Role for this node: AOA_SLAVE/AOA_MASTER/AOA_PASSIVE
• aoaResultMode - Result Mode for this node: AOA_MODE_ANGLE (on-chip calculation)/AOA_MODE_PAIR_ANGLES (on chip-partial calculation)/AOA_MODE_RAW (off-chip calculation)
• cteScanOvs - Scan Oversampling - should be left set to 4 at this point
• cteOffset - Timing offset - should be left set to 4 at this point
• cteTime - Length of the tone - should be left set to 20 at this point

RTLS_CMD_AOA_ENABLE

Request the device to start AoA. Must call RTLS_CMD_AOA_SET_PARAMS beforehand

Params

• enable - setting this parameter to 1 means enable, setting it to 0 means disable

---

RTLS_CMD_TOF_SET_PARAMS

Sets ToF parameters

Params

• tofRole - ToF Role for this node: TOF_SLAVE/TOF_MASTER/TOF_PASSIVE
• numSamples - number of ToF samples sent in each ToF run. Note that the amount of samples cannot be greater than the time between two synchronization events (e.g has to fit between two BLE connection events)
• numFreq - number of frequencies used in each ToF run
• autoTofRssiThresh - if runMode is set to TOF_MODE_AUTO, use this value to determine the threshold from which ToF will start running
• resultMode - the way in which results are reported: TOF_MODE_DIST (on-chip calculation)/TOF_MODE_STAT (on chip-partial calculation)/TOF_MODE_RAW (off-chip calculation)
• runMode - ToF operation mode: TOF_MODE_CONT (non-stop ToF runs)/TOF_MODE_ONE_SHOT (a single ToF run once a connection has been established)/ TOF_MODE_AUTO (continuous ToF runs once a RSSI threshold is crossed)
• constSyncwords - Setting this to True will cause RTLS Control to generate syncwords only once per RTLS_CMD_TOF_SET_PARAMS command (as opposed to generating every ToF run when this parameter is set to false)
• frequencies - list of frequencies to use for each ToF Syncword (interval between frequencies is decided in TOF.c)

RTLS_CMD_TOF_ENABLE

Request the device to start ToF. Must call RTLS_CMD_TOF_SET_PARAMS beforehand

Params

• enable - setting this parameter to 1 means enable, setting it to 0 means disable

RTLS_CMD_TOF_CALIBRATE

Enables ToF for calibration - RTLS_CMD_TOF_ENABLE must be called for calibration to start! ToF calibration is only performed in TOF_MODE_DIST - this is because DIST is the only mode that calculates a final result. If the requirement is to perform the final calculation off chip when using TOF_MODE_STAT/RAW, then the user should store calibration values and offsets on the host side

Params

• enable - set this parameter to 1 to enable, 0 to disable calibration
• samplesPerFreq - required samples per frequency (see note below)
• calibDistance - the distance from which the calibration was performed. This distance will be added to the final calculation.

  Notes

Calibration will run depending on the setting of samplesPerFreq:

• If samplesPerFreq is 0, calibration will run until a disable command is issued
• If samplesPerFreq is greater than 0, calibration will deduct 1 for each run. Once 0 is reached, calibration will stop and output a AsyncReq to the host.

• If ToF is not calibrating and a disable command is sent, all calibration information will be reset

  Enabeling calibration and using TOF_MODE_ONE_SHOT

• Even when using TOF_MODE_ONE_SHOT, calibration will still run before results are reported!

---

Responses

RTLS_CMD_IDENTIFY

Sends back the RTLS Node's capabilities and a unique identifier

Params

capabilities - capabilities supported by each device (described by capabilities ENUM) identifier - unique identifier per device

RTLS_CMD_ERROR

If an internal error occurs in RTLS Control, it will notify RTLS Node Manager

Params

status - a status code described by RtlsStatus ENUM

RTLS_CMD_RESET_DEVICE

Device is reset

Params

status - a status code described by RtlsStatus ENUM

RTLS_EVT_DEBUG - This command is used by the user to debug the application, a sort of logging message

A debug event has been sent

Params

• debug_value - Any 32 bit value can be given here
• debug_string - Any 32 byte string can be given here

---

RTLS_CMD_SCAN - SyncRsp

Used to tell RTLS Node Manager that a scan has started

Params

status - a status code described by RtlsStatus ENUM

RTLS_CMD_SCAN - AsyncReq

Contains information found in the BLE scan packet

Params

• eventType - GAP event type
• addrType - BLE address type
• addr - BD Address for the device
• rssi - rssi that the scan/adv response was received at
• dataLen - length of data
• data - data found inside of the scan/adv response

RTLS_CMD_SCAN_STOP - AsyncReq

A scan procedure has finished (if nothing is found a scan can be restarted)

Params

status - a status code described by RtlsStatus ENUM

RTLS_CMD_CONNECT - SyncRsp

This will inform the RTLS Node Manager that RTLS Control has requested the stack to form a connection

Params

status - a status code described by RtlsStatus ENUM

RTLS_CMD_CONNECT - AsyncReq

This will inform the RTLS Node Manager that a connection has been formed (or failed to form)

Params

status - a status code described by RtlsStatus ENUM

RTLS_CMD_CONN_PARAMS - SyncRsp

Informing that Connection Parameters will be set

Params

status - a status code described by RtlsStatus ENUM

RTLS_CMD_CONN_PARAMS - AsyncReq

Sends out the connection params as soon as they are available

Params

• accessAddress - BLE AccessAddress
• connInterval - BLE Connection Interval
• hopValue - BLE Hop Value
• mSCA - BLE mSCA
• currChan - BLE current channel (used to synchronize RTLS Passive)
• chanMap - BLE Channel Map
• crcInit - CRC Init value

---

RTLS_CMD_AOA_SET_PARAMS - SyncRsp

Indicates that RTLS Control will set AoA parameters

Params

status - a status code described by RtlsStatus ENUM

RTLS_CMD_AOA_ENABLE - SyncRsp

Indicates that RTLS Control will enable/disable AoA

Params

status - a status code described by RtlsStatus ENUM

RTLS_CMD_AOA_RESULT_ANGLE - AsyncReq

Contains the results for a single AoA run when using AOA_MODE_ANGLE

Params

• angle - angle that was calculated on-chip
• rssi - rssi of the packet that contained the tone
• antenna - the antenna array that this result was captured on (the one with the stronger rssi will be used)
• channel - channel that the tone was transmitted on

RTLS_CMD_AOA_RESULT_PAIR_ANGLES - AsyncReq

Contains the results for a single AoA run when using AOA_MODE_PAIR_ANGLES

Params

• rssi - rssi of the packet that contained the tone
• antenna - the antenna array that this result was captured on
• channel - channel that the tone was transmitted on
• pairAngle - for an array of 3 antennas, a result will be reported for each array

RTLS_CMD_AOA_RESULT_RAW - AsyncReq

Outputs the raw array of I/Q samples collected in RF Core RAM. The output is quite large (around 2K bytes) and will be output over uNPI in chunks of 32 samples per chunk.

Params

• rssi - rssi of the packet that contained the tone
• antenna - the antenna array that this result was captured on
• channel - channel that the tone was transmitted on
• offset - the offset of the current chunk of samples (starting from 0)
• samplesLength - total length of the samples array (length is given in samples, not bytes)
• samples - the samples themselves arranged in {q,i} tuples

---

RTLS_CMD_TOF_ENABLE - SyncRsp

RTLS Control will enable/disable ToF

Params

status - a status code described by RtlsStatus ENUM

RTLS_CMD_TOF_SET_PARAMS - SyncRsp

RTLS Control will set ToF parameters

Params

status - a status code described by RtlsStatus ENUM

RTLS_CMD_TOF_SET_SEC_SEED - SyncRsp

RTLS Control will set ToF Security seed (used for RTLS Passive nodes)

Params

status - a status code described by RtlsStatus ENUM

RTLS_CMD_TOF_GET_SEC_SEED - SyncRsp

RTLS Control will send out the ToF Security seed (passed onto RTLS Passive nodes)

Params

seed[32] - a seed of 32 bytes

RTLS_CMD_TOF_RESULT_STAT - AsyncReq

RTLS Control will send out this result when using TOF_MODE_STAT TOF_MODE_STAT will average tick values for each frequency used in a ToF run (partial calculation)

Params

• freq - frequency that this result was captured on
• tick - average tick time for this freq
• tickVariance - variance between ticks
• rssi - rssi for this ToF run
• numOk - number of good samples captured on this frequency

RTLS_CMD_TOF_RESULT_DIST - AsyncReq

RTLS Control will hold an average of all ToF runs and report over and over for each ToF run that the user requests

Params

• distance - the distance calculated on chip
• rssi - rssi captured by RTLS Control's rssi filter (smoothens RSSI for auto-tof)

RTLS_CMD_TOF_RESULT_RAW - AsyncReq

Raw results reported directly by ToF driver

Params

• tick - measured time
• freqIdx - index that tick was measure on
• rssi - rssi that this tick was captured on (each tick has it's own RSSI value)

RTLS_CMD_TOF_CALIBRATE - SyncRsp

RTLS Control will enable/disable ToF

Params

status - a status code described by RtlsStatus ENUM

RTLS_CMD_TOF_CALIBRATE - AsyncReq

RTLS Control will output the calibration array to the host once calibration is complete

Params

• freq - calibration for this frequency
• tick - average tick time for this freq
• tickVariance - variance between ticks
• rssi - rssi for the calibration
• numOk - number of good samples that were found during calibration