3.15 Bluetooth Low Energy Proximity Monitor

Hardware Requirement

Table 3-29. Hardware Requirement
Tool	Quantity
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

Precompiled .hex file is located in “<Harmony Content Path>\wireless_apps_ble\apps\ble_pxpm_app\hex” folder.
For more information on the programming steps, refer to the Programming a Device in MPLAB IPE.
Note: Users must choose the correct device and tool information.

Programming the Application using MPLAB X IDE

Follow the steps mentioned in Running a Precompiled Example
Open and program the application example “ble_pxpm_app_xxxx.X” where xxxx refer to device (for example: WBZ451, project file: ble_pxpm_app_wbz451.X) located in “<Harmony Content Path>\wireless_apps_ble\apps\ble_pxpm_app\firmware” using MPLAB X IDE

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

Demo Description

For WBZ451 refer: BLE Proximity Monitor
For WBZ351 refer: BLE Proximity Monitor

Developing the Application from Scratch using MCC

This section explains the steps required by a user to develop this application example from scratch using MCC.

Note: It is recommended that new users of MCC to go through the MPLAB® Code Configurator (MCC) User's Guide.

Create a new MCC Harmony Project by selecting the device. For more details, refer to Creating a New MCC Harmony Project.
Launch the MPLAB Code Configurator from the toolbar as illustrated below. The project graph will open with the default components.
Figure 3-187. MCC
In the Device Resources window, expand Libraries > Harmony > Wireless > Application Services. Then, click the Plus Symbol to add the Proximity App Service Component to the project graph.
Figure 3-188. Proximity App Service
All BLE PXPM related components will be added into the project graph. Accept dependencies or satisfiers by selecting Yes.
For configuring BLE Config App Service component based on the device refer to Adding BLE Config App Service Component to Project Graph and Selecting the Device in Getting Started with WME Bluetooth Low Energy Applications from Related Links.
To enable digital and communication interfaces, refer to Enabling Digital Input/Output and Communication Interfaces Through System Hardware Definition (SHD) component in Getting Started with WME Bluetooth Low Energy Applications from Related Links.
Change FreeRTOS component settings as illustrated in the following figure. For more details, refer to the Configuring FreeRTOS in Getting Started with WME Bluetooth Low Energy Applications from Related Links.
Figure 3-189. FreeRTOS Configuration
Select the Proximity App Service Component. In the Configuration Options, select the Enable Monitor Role. Additionally, ensure that the Support Immediate Alert Service, Support TX Power Service and Enable App Code Generation option is enabled.
Figure 3-190. Proximity App Service Configuration
For WBZ451
1. Change WBZ451-CURIOSITY Component setting as illustrated in the following figure.
  Figure 3-191. WBZ451-CURIOSITY Configuration
2. Verify if the project graph window has all the expected components, as illustrated in the following figure:
  Figure 3-192. Project Graph
For WBZ351
1. Change WBZ351-CURIOSITY Component setting as illustrated in the following figure.
  Figure 3-193. WBZ351-CURIOSITY Configuration
2. Verify if the project graph window has all the expected components, as illustrated in the following figure:
  Figure 3-194. Project Graph
Enabling the Enable Monitor Role option in Proximity App Service component will configure BLE Stack component . Additionally, selecting the Enable App Code Generation option will generate the necessary application files related to the service during the code generation process. Verify the BLE Stack configuration.
Figure 3-195. BLE Stack Configuration
Figure 3-196. BLE Stack Configuration

Generating a Code

For more details on code generation, refer to the MPLAB Code Configurator (MCC) Code Generation.

Files Containing User Application Code

Source code for the application will be generated from the MCC interface by clicking Generate Code. User can add or edit the code in the highlighted files shown below.

Details on files that user can modify

Table 3-30. Source Files
Source Files	Usage
`app.c`	Application State machine, includes calls for Initialization of all BLE stack (GAP,GATT, SMP, L2CAP) related component configurations
`app_ble_callbacks.c`	All the event functions related to GAP, GATT, SMP and L2CAP events that user can use or modify .
`app_pxpm_callbacks.c`	All the event functions related to PXPM event handles that user can use or modify.
`app_utility.c`	Contains generic utility functions that serve the purpose of providing reusable, common functionalities that can be applied across various parts of a program.

Note: app.c is auto generated and has a state machine based application code sample. Users can use this template to develop their application. Main application logic is implemented in

void
                        APP_Tasks()

function.

Proximity Profile

In the context of Bluetooth Low Energy, “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 has disconnected. As a consequence of this alert, a device may take further action.

The BLE Proximity profile typically involves two roles:

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
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.

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

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.
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

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.
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.

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.

Table 3-31. Behavior of the Application Upon Button Press
State	Action	Behavior
`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 if available
`APP_PXP_IND_STA_WITH_BOND_SCAN`	Long press Button 1	Start a new pairing

On board RGB LED (for Alert Level) is used for the visual output information to the user.

Output

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

Table 3-32. Immediate Alert level
Distance	10 cm	3m	30m
Path loss	51	65	85
Zone	LOW_ZONE	MIDDLE_ZONE	HIGH_ZONE

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

Table 3-33. Application Alert Level
APP Alert Level	PXPM RGB LED Behavior	PXPR User LED
`BLE_PXPR_ALERT_LEVEL_NO`	Green Light	All LED keep lighting
`BLE_PXPR_ALERT_LEVEL_MILD`	Red Light	User LED blinks one time every second
`BLE_PXPR_ALERT_LEVEL_HIGH`	OFF	User LED blinks five times every second

References

Bluetooth Low Energy Proximity Monitor Application for: WBZ451
Bluetooth Low Energy Proximity Monitor Application for: WBZ351

3.15 Bluetooth® Low Energy Proximity Monitor

Recommended Reading