4.2.4 BLE Proximity Monitor

Introduction

This section guides users configuration, programming, and validation of a BLE Proximity Monitor utilizing the WBZ351 Curiosity board, and also outlines the necessary hardware and software requirements, the BLE Proximity profile, and specific services involved. Additionally, it also includes step-by-step instructions and test cases to facilitate the implementation and verification of the application.

Hardware Requirement

Table 4-29. Hardware Requirement

Tool

Quantity

WBZ351 Curiosity Board

2

Micro USB Cable

2

Laptop

1

Software Requirements

  • MPLAB X IPE: For programming the precompiled hex file.
  • MPLAB X 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_pxpm_app\firmware\ble_pxpm_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_pxpm_app.X” located in <Harmony Content Path>\wireless_apps_pic32cxbz3_wbz35\apps\ble\advanced_applications\ble_pxpm_app\firmware\ ble_pxpm_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 beyond the range of a peer device, resulting in either a disconnection or an increase in path loss exceeding the preset level, causing an immediate alert. This alert is used to notify the user that the devices have disconnected. As a consequence of this alert, a device may take further action.

The BLE Proximity profile typically involves two roles:
  1. Proximity Reporter (Server): This refers to the tracked device, which could be an item like a key fob or any other asset whose proximity is to be monitored
  2. Proximity Monitor (Client): This device monitors the reporter's proximity, typically through a smart phone or tablet

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

Role/Service Relationships

The following figure illustrates the relationship between services and the two profile roles. The dotted line indicates that the service within this line is optional.
Figure 4-197. Role/Service Relationships

Proximity Monitor Requirements

The Proximity Monitor is designed to observe, connect, read, and configure a Proximity Reporter. Following are the detailed requirements and procedures for effective operation:

Service Discovery

The Proximity Monitor must perform service discovery to identify and connect to the following services by their respective UUIDs:

  • Link Loss Service: Identified by the “Link Loss” service UUID.
  • Immediate Alert Service: Identified by the “Immediate Alert” service UUID.
  • TX Power Service: Identified by the “TX Power” service UUID.
Link Loss Service
  1. Discovery and Configuration:
    • Upon discovering the Link Loss Service and its alert level characteristic, the Proximity Monitor will write the alert level characteristic to the required link loss alert level. This action is performed once the connection between the Proximity Monitor and the Proximity Reporter is established.
    • The required alert level can be set by the user of the Proximity Monitor.
  2. Connection Monitoring:
    • The Proximity Monitor can maintain an active connection with the Proximity Reporter and continuously monitor the RSSI of this connection.
    • If the connection is disconnected, the Proximity Reporter will alert at the level specified in the alert level characteristic, as defined by the Link Loss Service specification.
Immediate Alert and TX Power Services
  1. Discovery and Reading:
    • Upon discovering the Immediate Alert and TX Power Services, the Proximity Monitor can read the TX power level characteristic of the TX power service.
    • This action is performed once the connection between the Proximity Monitor and the Proximity Reporter is established.
  2. Connection and Path Loss Monitoring:
    • The Proximity Monitor can maintain an active connection with the Proximity Reporter and continuously monitor the RSSI of this connection.
    • The Proximity Monitor can calculate the path loss by subtracting the RSSI from the transmit power level of the Proximity Reporter, as determined by reading TX power procedure.
    • If the path loss exceeds a threshold set on the Proximity Monitor, it can write to the alert level characteristic of the Immediate Alert Service using the GATT Write without Response sub-procedure. This action will cause the Proximity Reporter to alert.

Summary

The Proximity Monitor ensures continuous monitoring and configuration of the Proximity Reporter by:

  • Discovering essential services and characteristics.
  • Writing and setting alert levels as required.
  • Monitoring the connection status and RSSI.
  • Calculating path loss and triggering alerts based on predefined thresholds.

These procedures ensure that the Proximity Monitor effectively manages the Proximity Reporter, providing timely alerts and maintaining robust connectivity.

Proximity Monitor Application

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

Working Flow

State machine:
  • APP_PXP_IND_STA_IDLE: application remains in the Idle mode.
  • APP_PXP_IND_STA_CONNECTED: application is prepared to transmit commands to the Proximity Reporter role.
  • APP_PXP_IND_STA_WITH_BOND_SCAN: application is prepared to reconnect with bond within timeout_with_bond_scan seconds duration.
  • APP_PXP_IND_STA_SCAN: application is prepared to initiate the connection within timeout_scan seconds duration.
Figure 4-198. Proximity Monitor State Machine

Input and Output Interface

Input

The application relies on Button 1 as the input.

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

APP_PXP_IND_STA_IDLE

Long press Button 1

Connect to a new device

APP_PXP_IND_STA_CONNECTED

Long press Button 1

Disconnect the existing connection and connect to a new device

APP_PXP_IND_STA_WITH_BOND_SCAN

Long press Button 1

Start a new pairing

Output

On board Green LED is used for the visual output information to the user. The Green LED is mainly used for two purposes:
  1. Current application State.
  2. Alert state.
The Green LED patterns to indicate the Current application State according to the following table:
Table 4-30. State Indication

APP Connection State

LED Behavior

APP_PXPR_STATE_IDLE

All LEDs are turned OFF.

APP_PXP_IND_STA_CONNECTED

User LED flashes twice every 1.5 seconds. (ON: 50 ms, OFF: 150 ms).

APP_PXP_IND_STA_WITH_BOND_SCAN

User LED flashes twice every 3 seconds. (ON: 50 ms, OFF: 50 ms).

APP_PXPM_STATE_SCAN

User LED flashes once every 3 seconds. (ON: 50 ms, OFF: 2950 ms).

Immediate Alert level will be issued according to the following table.

Table 4-31. Immediate Alert level

Distance

10 cm

3m

30m

Path loss

51

65

85

Zone

LOW_ZONE

MIDDLE_ZONE

HIGH_ZONE

The User LED pattern indicates the alert state according to the following table:
Table 4-32. Application Alert Level

APP Alert Level

LED Behavior

BLE_PXPR_ALERT_LEVEL_NO

User LED remains ON for 5 seconds.

BLE_PXPR_ALERT_LEVEL_MILD

User LED blinks once every second continuously for 5 seconds.

BLE_PXPR_ALERT_LEVEL_HIGH

User LED blinks five times every second continuously for 5 seconds.

Test Cases

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

Environment Setup:
  • Windows system.
  • Two WBZ351 Curiosity boards both connected to Windows machine using a USB cable. One WBZ351 Curiosity board will act as Proximity Monitor and other WBZ351 Curiosity boards will act as Proximity Reporter.
  • MPLAB X IDE.

Link Loss and Immediate Alert Test

The following section covers the test case scenarios that showcase the Link Loss service and Immediate Alert service usage.

The Link Loss Service test case covers demonstration of HIGH (Preset) alert level set at Proximity Monitor using the Alert Level characteristic to cause an alert in the device when the link is lost. The alert will be displayed on the Proximity Reporter on the event of disconnection.

The Immediate Alert Service test case covers demonstration of alert indication display on Proximity Reporter (Curiosity board) based on the distance between the Proximity Monitor (Curiosity board) and Proximity Reporter (Curiosity board).

The test case covers:

  • Establishing connection between Proximity Reporter and Proximity Monitor devices
  • Observing Link loss alert (HIGH) on Proximity Reporter
  • Observing Immediate Alert Levels on Proximity Reporter based on the distance between Proximity Reporter and Monitor via Green LED pattern.
  • Auto re-connection of Proximity Reporter and Proximity Monitor during the long range disconnection and forced removal of Proximity Monitor.

Application Demonstration

  1. In MPLAB X IDE, open ble_pxpr_app (Reporter) application, ensure that the BLE_PXPR_IAS_AUTH_ENABLE and BLE_PXPR_LLS_AUTH_ENABLE options are enabled. The corresponding macros are distinctly defined in the ble_lls.c and ble_ias.c. Compile and program the PXPR application on the Curiosity board A with the below configuration.
    Note: The Proximity Reporter application will be referred as Board A in this section.

    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. In the MPLAB, compile and program the PXPM (Monitor) application on the Curiosity board B with the configuration below.

    PIC32CX-BZ3_DFP

    1.2.183

    XC32 Compiler Version:

    V4.40

    Note: “PXPM” is used instead in the following section. The Proximity Monitor application will be referred as Board B in this section.

  3. PXPM (Board B) enters APP_PXPR_STATE_SCAN and establish a connection with PXPR (Board A) after receiving the advertising.

  4. The PXPM (Board B) enters APP_PXP_IND_STA_CONNECTED when the connection is established.

  5. On the PXPM (Board B) , the Link Loss Service will be issued with BLE_PXPR_ALERT_LEVEL_HIGH and trigger the pairing flow.

  6. When the PXPR (Board A) is within 10 cm of the PXPM (Board B), the BLE_PXPR_ALERT_LEVEL_NO alert level can be observed through PXPR (Board A) Green LED.

  7. PXPR (Board A) moves away from PXPM (board B) over 3m, the BLE_PXPR_ALERT_LEVEL_MILD alert level can be observed through PXPR (Board A) Green LED.

  8. PXPR (Board A) moves away from PXPM (Board B) over 30m, the BLE_PXPR_ALERT_LEVEL_HIGH alert level can be observed through the PXPR (Board A) Green LED.

  9. Range and Re-connect Test:

    1. Move PXPR (Board A) far away from the PXPM (Board B) curiosity board to disconnect.

      The PXPM (Board B) will enter APP_PXP_IND_STA_WITH_BOND_SCAN and scan for re-bonding.

    2. Move PXPR (Board A) close back to the PXPM (Board B).
    3. The PXPR (Board A) having pairing data will automatically reconnect to the PXPM (Board B).
    4. The PXPM (Board B) will enter APP_PXP_IND_STA_CONNECTED when reconnection is successful.
  10. Disconnect Re-connect Test:
    1. Unplug the Proximity Monitor (Board B)
    2. The PXPM (Board B) enters APP_PXP_IND_STA_WITH_BOND_SCAN state.
    3. The alert level set in step 5 of the Link Loss Service will be displayed as BLE_PXPR_ALERT_LEVEL_HIGH and can be observed through the PXPR Reporter (Board A)Green LED. Green LED blinks five times every second continuously for 5 seconds.
    4. Plug the Proximity Monitor (Board B) back to power. the PXPM (Board B) will be reconnected to the PXPR (Board A) and will enter APP_PXP_IND_STA_CONNECTED and the Green LED alert situation will be re-indicated as the corresponding alert level.