4.1.2.10 Path Loss Feature in Legacy Advertisements

Introduction

This document will help users to enable the Path Loss feature with BLE Advertisements on WBZ351 Curiosity board using the MPLAB Code Configurator(MCC)

The path loss is defined as the difference between the remote transmit power level and the average local RSSI measurement for the connection. In other words, Path loss refers to the attenuation or reduction in signal strength as it travels through the wireless channel from the transmitter (BLE device) to the receiver.

Path loss monitoring is a crucial feature in BLE, allowing for real-time assessment of signal strength and providing valuable insights for connection management.

Users can choose to just run the precompiled Application Example hex file on the WBZ351 Curiosity Board and experience the demo or can go through the steps involved in developing this Application from scratch

It is recommend to follow the examples in order, by learning the basic concepts first and then progressing to the more advanced topics.

Understanding Path Loss

Path Loss Zones

BLE path loss monitoring divides signal strength into specific zones to facilitate effective management. The core path loss zones are:

1. Low Zone
2. Middle Zone
3. High Zone

The BLE Controller continuously evaluates path loss and notifies the Host when it transitions between these zones, based on predefined boundaries.

Calculating Path Loss

Path loss is determined as the difference between the remote transmit power level (the power at which the remote BLE device transmits) and the average local Received Signal Strength Indication (RSSI) measurement for the connection.

Zone Transition Criteria

To prevent frequent zone switching, some hysteresis is provided. The upwards boundary should be greater than or equal to the downwards boundary, ensuring a smooth transition.

Correlation with Distance:

Path loss often correlates with the distance between BLE devices. A higher zone may indicate that the peer BLE device has moved farther away. This information can be invaluable for various applications, such as proximity detection and device localization.

Path Loss Measurement

Power Control Request procedure in context of path loss monitoring

The Power Control Request procedure is a critical component of path loss monitoring in Bluetooth Low Energy (BLE). This procedure enables the measurement of the remote transmit power level, which is essential for calculating path loss accurately.

Practical Applications

Recommended Reading

1. BLE Software Specification

2. FreeRtos BLE App Initialize

3. Low Power Notes

Hardware Requirement

SDK Setup

1. Gettting Started with Software Development

Software Requirement

1. TeraTerm

Programming the precompiled hex file or Application Example

Programming the hex file using MPLABX IPE

1. Precompiled Hex file is located in "<Harmony Content Path>\wireless_apps_pic32cxbz3_wbz35\apps\ble\building_blocks\peripheral\Legacy_ADV_Pathloss\dist\default\production\" folder

2. Follow the steps mentioned here

   Note: Ensure to choose the correct Device and Tool information

Programming the Application using MPLABX IDE

1. Follow steps mentioned in of Running a Precompiled Example document

2. Open and program the Application Example "Legacy_ADV_Pathloss.X.production.x" located in "<Harmony Content Path>\wireless_apps_pic32cxbz3_wbz35\apps\ble\building_blocks\peripheral\Legacy_ADV_Pathloss\firmware" using MPLABX IDE

For more details on how to find the Harmony Content Path, refer to Installing the MCC Pluggin

Demo Description

This application example implements the path loss feature into an peripheral legacy advertisement application. The testing of this application is done by connecting the path loss feature included peripheral legacy application to an Central connection application. After successfully connection, at the peripheral application serial console, the path loss and zone will be updated frequently.

Testing

Developing the Application from Scratch using MPLAB Code Configurator

1. Create a new MCC Harmony Project. For more details, refer to 3.4 Creating a New MCC Harmony Project.

2. Import component configuration: This step helps users setup the basic components and configuration required to develop this application. The imported file is of format .mc3 and is located in the path <Harmony Content Path>\wireless_apps_pic32cxbz3_wbz35\apps\ble\building_blocks\peripheral\legacy_ADV_Pathloss\firmware\legacy_ADV_Pathloss.X. Users must follow the instructions mentioned 13.3 Importing Existing App Example Configuration to import the component configuration.

3. Accept Dependencies or satisfiers, select Yes

4. Verify if the Project Graph window has all the expected configuration

   

5. Generate the code.

Files and Routines Automatically generated by the MCC

After generating the program source from MCC interface by clicking Generate Code, the BLE configuration can be found in the following project directories

The OSAL, RF System, BLE System initialization routine executed during program initialization can be found in the project files. This initialization routine is automatically generated by the MCC

The BLE stack initialization routine excuted during Application Initialization can be found in project files. This intitialization routine is automatically generated by the MCC. This call initializes and configures the GAP, GATT, SMP, L2CAP and BLE middleware layers.

During system sleep, clock (system PLL) will be disabled and syatem tick will be turned off. FreeRTOS timer needs to be componsated for the time spent in sleep. RTC timer which works in the sleep mode is used to accomplish this. RTC timer will be initialized after BLE stack initialization.

Autogenerated, adverisement Data Format

Header Files

• ble_gap.h: This header file contains BLE GAP functions and is automatically included in the app.c file

Function Calls

MCC generates and adds the code to initialize the BLE Stack GAP, GATT, L2CAP and SMP in APP_BleStackInit() function

• APP_BleStackInit() is the API that will be called inside the Applications Initial State -- APP_STATE_INIT in app.c

User Application Development

Include

• User action is required as mentioned in User Action

• definitions.h in all the files where UART will be used to print debug information

Set PUBLIC Device Address

• BLE_GAP_SetDeviceAddr(&devAddr);

This API can be called in APP_BleConfig() located in file app_ble.c

    BLE_GAP_Addr_T devAddr;
    devAddr.addrType = BLE_GAP_ADDR_TYPE_PUBLIC;
    devAddr.addr[0] = 0xA1;
    devAddr.addr[1] = 0xA2;
    devAddr.addr[2] = 0xA3;
    devAddr.addr[3] = 0xA4;
    devAddr.addr[4] = 0xA5;
    devAddr.addr[5] = 0xA6;

    // Configure device address
    BLE_GAP_SetDeviceAddr(&devAddr);

Start Advertisement

• BLE_GAP_SetAdvEnable(0x01, 0);

This API is called in the Applications initialstate - APP_STATE_INIT in app.c

Users can exercise various other BLE Advertisement functionalities by using BLE Stack API

Path Loss configuration

Initially create two new enum to effectively handle the callback between the application layer and BLE stack.

In the app_ble_handler.c file:

The path loss configuration is enabled after a successful connection establishment. The steps required to enable the path loss feature begin with the reception of the connected event (BLE_GAP_EVT_CONNECTED) in the app_ble_handler.c file.

Upon receiving the connection event, control is passed from the BLE Stack to the application layer using a queue mechanism with a specific message ID, namely APP_MSG_CONNECT_CB.

In the application layer under service tasks:

Upon receiving the APP_MSG_CONNECT_CB message, the path loss configurations, including the connection handle, threshold, hysteresis, and minimum time spent, are set.

The BLE_GAP_SetPathLossReportingParams function is called, and the earlier set path loss configurations are passed as parameters. It is recommended to wait until this function call returns with a success event.

Upon receiving the success event, a new message is initiated via the queue with the message ID set as APP_MSG_PATHLOSS_CB. Subsequently, the path loss reporting enable function is initiated with the connection handle as a parameter.

In the Path Loss Event Handler(BLE_GAP_EVT_PATH_LOSS_THRESHOLD):

Within the Path Loss Event Handler, include the following code to gather information about the path loss and determine the current zone that the device has entered. This data is then displayed on the console or printed to an output:

NOTE:

In Chimera , it has been observed that the Received Signal Strength Indicator (RSSI) readings may not accurately reflect the actual received power from a connected peer device when the incoming power level is approximately -50 dBm or higher.

Where to go from here

• BLE Connection