4.2.5 BLE Proximity Reporter

Introduction

The Proximity Reporter application provides comprehensive guidance on setting up, programming, and testing a BLE Proximity Reporter using the WBZ351 Curiosity board. This document details the necessary hardware and software requirements, the Bluetooth Low Energy (BLE) proximity profile, and specific services involved. It also includes step-by-step instructions and test scenarios for implementing and validating the application.

Hardware Requirement

Software Requirements

• MPLABX IPE: For programming the precompiled hex file.
• MPLABX IDE: For programming the application example.

Programming the Precompiled Hex File or Application Example

Programming the .hex File using MPLAB X IPE

1. Precompiled .hex file is located in <Harmony Content Path>\wireless_apps_pic32cxbz3_wbz35\apps\ble\advanced_applications\ ble_pxpr_app\firmware\ble_pxpr_app.X\dist\default\production folder.
2. For more details on the steps, go to Programming A Device
   Note: Ensure to choose the correct Device and Tool information.

Programming the Application using MPLAB X IDE

1. Follow the steps mentioned in Running a Precompiled Example section.
2. Open and program the application example “ble_pxpr_app.X” located in <Harmony Content Path>\wireless_apps_pic32cxbz3_wbz35\apps\ble\advanced_applications\ble_pxpr_app\firmware\ble_pxpr_app.X using MPLAB X IDE.

For more details on finding the Harmony content path, refer to Installing the MCC Plugin

Proximity Profile

In the context of Bluetooth Low Energy (BLE), “proximity” generally refers to the physical closeness between two BLE devices. The BLE Proximity profile is a standardized BLE profile that enables a device to alert a user when another device is near or far away from it.

The Proximity profile defines the behavior when a device moves away from a peer device so that the connection is dropped or the path loss increases above a preset level, causing an immediate alert. This alert can be used to notify the user that the devices have become separated.

The Proximity profile uses the RSSI (Received Signal Strength Indicator) to determine the approximate distance between the Monitor and the Reporter.

Role/Service Relationships

The following figure shows the relationship between services and the two profile roles. The dotted line indicates that the service within this line is optional.

Proximity Reporter Requirements

The Proximity Reporter must have one instance of the Link Loss Service and may have instances of both the Immediate Alert Service and the Tx Power Service. these services are described in detail below:

Link Loss Service

Link loss service in Bluetooth Low Energy (BLE) is a standard service defined by the Bluetooth Special Interest Group (SIG) to alert a device when it loses connection with another device.

Service Characteristics

The Alert Level Characteristic is used to expose the current link loss alert level that is used to determine how the device alerts when the link is lost.

Characteristic Behavior

The Alert Level characteristic can be set to “No Alert,” “Mild Alert,” “High Alert”.

Service Behaviors

Disconnection Behavior

The specific action that occurs in the device for the mild and high alerts is implementation specific. For example, this could include flashing lights, making noises, moving, or other methods to alert the user.

Immediate Alert Service

This service exposes a control point to allow a peer device to cause the device to alert immediately. The proximity monitor will calculate the path loss:

Path Loss = Tx Power Level - RSSI

If the path loss exceeds a certain threshold, the monitor can write the alert level characteristic of the IAS, thereby prompting the user to perform appropriate action to avoid disconnection.

The alert level characteristic can be written using the GATT Write without Response sub-procedure with an alert level of “No Alert,” “Mild Alert,” “High Alert,” to set the written alert level.

The specific action that occurs in the device for the mild and high alerts is implementation specific. For example, this could include flashing lights, making noises, moving, or other methods to alert the user.

Tx Power Service

The Tx Power Service uses the Tx power level characteristic to expose the current transmit power level of a device when in a connection.

The Tx Power Level characteristic returns the current transmit power level when read using the GATT Characteristic Read.

Proximity Reporter Application

In this section, the focus is on the Proximity Reporter application implementation specific details. In terms of the application design and testing methods.

Project Graph

The components illustrated in the project graph is used to create the Proximity Reporter application.

The MCC supports the proximity profile and associated services like Immediate Alert Service, Link Loss Service and Tx Power Service. And the other mandatory components listed below is also available as a drag and drop components in the MCC.

Working Flow

State machine:

• APP_PXPR_STATE_IDLE: application remains in the Idle mode.
• APP_PXPR_STATE_ADV: application is waiting for a connection without bond within timeout_adv seconds duration.
• APP_PXPR_STATE_BOND_ADV: application is waiting for a reconnection with bond within timeout_with_bond_adv seconds duration.
• APP_PXPR_STATE_CONN: application is prepared to respond to Proximity Monitor role.

Input and Output Interface

Input

The application relies on Button 1 as the input.

• Types of Pressing:
  • Press: Press the button for less than 500 ms.
  • Long press: Press the button for more than 500 ms.
• Application behavior on button press in different state co relation.

Output

The Green LED pattern indicates the alert state according to the following table:

Test Cases

The test case section covers separate test scenarios to test the Link Loss, Immediate Alert Services and Tx Power Service behavior implementation.

Link Loss

The below session covers the test case scenarios that showcase the Link Loss Service. The Link Loss Service provides provision to set the desired alert level using the alert level characteristic to cause an alert in the device when the link is lost. Based on the set alert level, the indication will be displayed on the Proximity Reporter on the event of disconnection.

The test case covers:

• How to use the mobile (Android) MBD application to establish the connection with PXPR curiosity board.
• Link Loss Service Alert level configuration.
• Testing scenarios to observe LED behavior during the disconnection.

1. In the MPLABX, open the ble_pxpr_app (Reporter) application. Compile and program the PXPR application on the Curiosity board with the below configuration.

   PIC32CX-BZ3_DFP	1.2.183
   XC32 Compiler Version:	V4.40

   1. After programming (or resetting) the device will be in APP_PXPR_STATE_ADV.

   2. APP_PXPR_STATE_ADV: The application is waiting for a connection without bond. That too within timeout_adv_seconds (60 seconds). After the completion of the timeout the device enters APP_PXPR_STATE_IDLE state.

      timeout_adv = 60 seconds - Timeout for advertisement without bond.

      LED Behavior

      APP_PXPR_STATE_ADV = Green LED flashes once in every 3 seconds.

      APP_PXPR_STATE_IDLE = Green LED will turn OFF.

2. Open the Microchip Bluetooth Data (MBD) app in Android and click BLE Connect feature.
3. Click START SCAN icon to see the nearby advertising devices. From the list of devices PXPR is the target device.

   

4. Click PXPR device to establish the connection. All the supported profiles in the proximity reporter will be displayed upon connection. At the peripheral side, the PXPR curiosity board will enter APP_PXPR_STATE_CONN when the connection is established.

   The on-board Green LED indicate the connection and advertisement state as follows.

   Table 4-40. Application State

   APP State	LED Behavior
   APP_PXPR_STATE_IDLE	All LEDs are turned OFF.
   APP_PXPR_STATE_ADV	The Green LED flashes once every 3 seconds. (ON: 50 ms, OFF: 2950 ms)
   APP_PXPR_STATE_CONN	The Green LED flashes twice every 1.5 seconds. (ON: 50 ms, OFF: 150 ms)

5. On the MBD app, press the Link Loss Service icon.

   

6. Select the desired Alert Level from the available option (No Alert, Mild Alert, High Alert).
   
7. Press the “←” icon on the top left corner of the screen twice to disconnect the “PXPR”. The Link Loss Service alert level will be shown as BLE_PXPR_ALERT_LEVEL_HIGH and can be observed through the PXPR Green LED LED.

   Table 4-39 4-41 4-42 4-44. APP Alert Level

   APP Alert Level	LED Behavior
   BLE_PXPR_ALERT_LEVEL_NO	Green LED remains lit for 5 seconds and then indicates the current connection state.
   BLE_PXPR_ALERT_LEVEL_MILD	Green LED blinks once every second continuously for 5 seconds and then indicates the current connection state.
   BLE_PXPR_ALERT_LEVEL_HIGH	Green LED blinks five times every second continuously for 5 seconds and then indicates the current connection state.

Immediate Alert Test case

The following session covers the test case scenarios that showcase the Immediate Alert Service usage. The usage includes how to set the range for different zone and what all alert level can be set in each zone so that the preset alert indication will be displayed on Proximity Reporter (Curiosity board) based on the distance between Proximity Monitor (Mobile) and Reporter.

Separate test cases are derived to showcase the application behavior with and without encryption and power control. The encryption feature will establish a paired connection and the power control. Disabling option excludes the auto adjust TX power configuration (based on the range) by the BLE firmware.

The test case covers:

• How to use the mobile (Android) MBD application to establish the connection with PXPR Curiosity board.
• Immediate Alert Service Range Bar configuration.
• Alert level configurations on each zone.
• Testing scenarios to observe LED behavior in each alert level in different distance range.

• Test Case 1: Without Encryption and Power Control

  This test case is based on a non-secure connection without encryption and power control features.

  1. In the MPLAB X, open the ble_pxpr_app (Reporter) application. Compile and program the PXPR application on the Curiosity board with the below configuration.

     PIC32CX-BZ3_DFP	1.2.183
     XC32 Compiler Version:	V4.40

     1. After programming (or resetting), the Proximity Reporter application will be in APP_PXPR_STATE_ADV state.

     2. APP_PXPR_STATE_ADV: The application is waiting for a connection without bond. Duration within timeout_adv_seconds (60 seconds). After the completion of the timeout the device enters APP_PXPR_STATE_IDLE state.
        Note: timeout_adv = 60 seconds - Timeout for advertisement without bond

        LED Behavior:

        APP_PXPR_STATE_ADV: Green LED flashes once in every 3 seconds

        APP_PXPR_STATE_IDLE: Green LED will turn OFF

  2. Open the Microchip Bluetooth Data (MBD) app in Android and click BLE Connect feature
  3. Click START SCAN icon to see the nearby advertising devices. From the list of devices PXPR is the target device

     

  4. Click PXPR device to establish the connection. All the supported profiles in the proximity reporter will be displayed upon connection. At the peripheral side, the PXPR curiosity board will enter APP_PXPR_STATE_CONN when the connection is established.
  5. Click Immediate Alert Service icon as illustrated below.

     

  6. Press the setting icon (Highlighted in green border) in the top right corner of the screen to configure the link budget threshold set to a proper value. It is based on the range bar value configuration in which the zone distance is calculated.

     

     1. The colored circles (Green, Orange, Red) shows the range for SAFE, MID, DANGER zone. The real time distance covered in each zone is user configurable. The configuration can be done in the range bar. The following figure illustrates the range bar configuration.

        

  7. The alert level at the PXPR (Curiosity board) which is based on the distance to the central device (Mobile) is user-configurable on the Immediate Alert Service settings page.
     User can configure for the alert level required for each zone. In The SAFE, MID, DANGER region are set as per the user configuration in the Range Bar.

     

  8. The on-board Green LED shows the indication based on the alert level set at each zone. As per the above configuration, when the mobile is near the Proximity Reporter (PXPR), the alert level will be BLE_PXPR_ALERT_LEVEL_NO. When the mobile phone moves away then the alert level will be BLE_PXPR_ALERT_LEVEL_MILD. If the Proximity Reporter (PXPR) moves further away the alert level will be BLE_PXPR_ALERT_LEVEL_HIGH.

     The LED behavior in each level will be as per the following table.

     Table 4-39 4-41 4-42 4-44. APP Alert Level

     APP Alert Level	LED Behavior
     BLE_PXPR_ALERT_LEVEL_NO	Green LED remains lit for 5 seconds and then indicates the current connection state.
     BLE_PXPR_ALERT_LEVEL_MILD	Green LED blinks once every second continuously for 5 seconds and then indicates the current connection state.
     BLE_PXPR_ALERT_LEVEL_HIGH	Green LED blinks five times every second continuously for 5 seconds and then indicates the current connection state.

     Note: The Green LED-based alert level indication at the Proximity Reporter (PXPR) will be observed only for 5 seconds. Further, the Green LED pattern will show the connection status. Similarly, for different zone entry and exit, the alert level indication based on below table will only be shown for 5 seconds and after that the connection state indication will be shows via Green LED.
     The Green LED patterns to indicate the current application state according to the following table:

     Table 4-38 4-43 4-45. APP Connection State

     APP Connection State	LED Behavior
     APP_PXPR_STATE_IDLE	All LEDs are turned off.
     APP_PXPR_STATE_ADV	The green LED flashes once every 3 seconds. (On: 50 ms, Off: 2950 ms)
     APP_PXPR_STATE_BOND_ADV	The Green LED flashes twice every 3 seconds. (On: 50 ms, Off: 50 ms)
     APP_PXPR_STATE_CONN	The Green LED flashes twice every 1.5 seconds. (On: 50 ms, Off: 150 ms)

• Test 2: With Encryption and Power Control

  This test case demonstrates the feature tested with security connection with encryption and power control features.

  1. In the MPLAB X, open the ble_pxpr_app (Reporter) application. Compile and program the PXPR application on the Curiosity board with the below configuration:
     • Uncomment the compile option BLE_PXPR_LLS_AUTH_ENABLE in ble_lls.c
     • Uncomment the compile option BLE_PXPR_IAS_AUTH_ENABLE in ble_ias.c
     • Uncomment the compile option POWER_CTRL_ENABLE in initialization.c

     PIC32CX-BZ3_DFP	1.2.183
     XC32 Compiler Version:	V4.40

     1. After programming (or resetting) the device will be in APP_PXPR_STATE_ADV state.
     2. APP_PXPR_STATE_ADV: The application is waiting for a connection without bond. Duration within timeout_adv_seconds. After the completion of the timeout the device enters into APP_PXPR_STATE_IDLE state.

        Note: timeout_adv = 60 seconds - Timeout for advertisement without bond.

     LED Behavior:

     APP_PXPR_STATE_ADV: Green LED flashes once in every 3 seconds

     APP_PXPR_STATE_IDLE: Green LED will turn OFF

  2. Open the Microchip Bluetooth Data (MBD) app in Android and click BLE Connect feature.
  3. Click START SCAN icon to see the nearby advertising devices. From the list of devices PXPR is the target device.

     

  4. Click PXPR device to establish the connection. All the supported profiles in the Proximity Reporter will be displayed upon connection. At the peripheral side, the PXPR Curiosity board will enter APP_PXPR_STATE_CONN when the connection is established.
  5. In the MBD app, press the Link Loss Service icon and select the alert level as BLE_PXPR_ALERT_LEVEL_HIGH / BLE_PXPR_ALERT_LEVEL_MILD.
  6. Notification for paring permission will appear, click Pair button to trigger the pairing flow.

     

  7. On the MBD app, press the “←” icon on the top left corner of the screen and press the Immediate Alert Service icon.
  8. Based on the configuration made on the settings page of Immediate Alert Service the alert level will be indicated on the device.

     

     When the mobile is near the Proximity Reporter (PXPR), the alert level will be BLE_PXPR_ALERT_LEVEL_NO. When the mobile phone moves away then the alert level will be BLE_PXPR_ALERT_LEVEL_MILD. If the Proximity Reporter (PXPR) moves further away the alert level will be BLE_PXPR_ALERT_LEVEL_HIGH.

     Note: The Green LED-based alert level indication at the Proximity Reporter (PXPR) will be observed only for 5 seconds. Further, the Green LED pattern will show the connection status. Similarly, for different zone entry and exit, the alert level indication based on below table will only be shown for 5 seconds and after that the connection state indication will be shows via Green LED.

     Table 4-39 4-41 4-42 4-44. APP Alert Level

     APP Alert Level	LED Behavior
     BLE_PXPR_ALERT_LEVEL_NO	Green LED remains lit for 5 seconds and then indicates the current connection state.
     BLE_PXPR_ALERT_LEVEL_MILD	Green LED blinks once every second continuously for 5 seconds and then indicates the current connection state.
     BLE_PXPR_ALERT_LEVEL_HIGH	Green LED blinks five times every second continuously for 5 seconds and then indicates the current connection state.

  9. Keep moving away from Proximity Reporter (PXPR) until it is disconnected. The PXPR enters APP_PXPR_STATE_ADV_BOND. The Link Loss Service alert level will be shown as what is set on “Link Loss Service”, which can be observed through the PXPR Green LED.

TX Power Service

The following session covers the test case scenarios that showcase the Tx Power Service. The TX Power Service uses the power level characteristic to return the current transmit power level when read using the GATT characteristic read.

The test case covers:

• How to use the mobile (Android) MBD application to establish the connection with PXPR Curiosity board.
• Read the Tx power level using the Tx Power service.

1. In the MPLAB X, open the ble_pxpr_app (Reporter) application. Compile and program the PXPR application on the curiosity board with the below configuration.

   PIC32CX-BZ3_DFP	1.2.183
   XC32 Compiler Version:	V4.40

2. In the MPLAB X, open the ble_pxpr_app (Reporter) application. Compile and program the PXPR application on the Curiosity board with the below configuration:
   • Uncomment the compile option BLE_PXPR_LLS_AUTH_ENABLE in ble_lls.c
   • Uncomment the compile option BLE_PXPR_IAS_AUTH_ENABLE in ble_ias.c
   • Uncomment the compile option POWER_CTRL_ENABLE in initialization.c

   PIC32CX-BZ3_DFP	1.2.183
   XC32 Compiler Version:	V4.40

   1. After programming (or resetting) the device will be in APP_PXPR_STATE_ADV state.

   2. APP_PXPR_STATE_ADV: The application is waiting for a connection without bond. Duration within timeout_adv_seconds. After the completion of the timeout the device enters into APP_PXPR_STATE_IDLE state.

      Note: timeout_adv = 60 seconds - Timeout for advertisement without bond

   LED Behavior:

   APP_PXPR_STATE_ADV: Green LED flashes once in every 3 seconds

   APP_PXPR_STATE_IDLE: Green LED will turn OFF

3. Open the Microchip Bluetooth Data (MBD) app in Android and click BLE Connect feature.
4. Click START SCAN icon to see the nearby advertising devices. From the list of devices PXPR is the target device.

   

5. Click PXPR device to establish the connection. All the supported profiles in the Proximity Reporter will be displayed upon connection. At the peripheral side, the PXPR Curiosity board will enter APP_PXPR_STATE_CONN when the connection is established.

   The on-board Green LED LED indicate the connection and advertisement state as following.

   Table 4-38 4-43 4-45. APP Connection State

   APP Connection State	LED Behavior
   APP_PXPR_STATE_IDLE	All LEDs are turned off.
   APP_PXPR_STATE_ADV	The green LED flashes once every 3 seconds. (On: 50 ms, Off: 2950 ms)
   APP_PXPR_STATE_BOND_ADV	The Green LED flashes twice every 3 seconds. (On: 50 ms, Off: 50 ms)
   APP_PXPR_STATE_CONN	The Green LED flashes twice every 1.5 seconds. (On: 50 ms, Off: 150 ms)

6. In the MBD app, press the Tx Power Service icon.

   

7. The highlighted portion shows the read Tx power level.