| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Proximity Application
This example requires one of the following SoftDevices: S130, S132

Important: Before you run this example, make sure to program the SoftDevice.

The Proximity Application is an example that implements the Proximity Profile and the Find Me Profile using the hardware delivered in the nRF5 Development Kit. The Proximity Profile alerts the user when connected devices are too far apart, while the Find Me Profile is used to alert the remote device (for example, a phone).

The application includes the following services:

- For the Proximity Profile:
  - Link Loss Service
  - Immediate Alert Service
  - TX Power Service
- For the Find Me Profile:
  - Immediate Alert Service Client

In addition, use of the Battery Service is also demonstrated.

At each power up and disconnect, the Proximity Application will do 20 seconds of fast advertising with whitelist followed by 40 seconds of fast advertising without whitelist. It will then switch to slow advertising mode, and the state BSP_INDICATE_ADVERTISING_WHITELIST is indicated. When the link is lost, or when an alert is signaled using the Immediate Alert Service, an alert is indicated using the state BSP_INDICATE_ALERT_0 or BSP_INDICATE_ALERT_1, depending on the value of the Alert Level characteristic.

The example uses the ADC peripheral to measure the battery level every 2 minutes. If there is a change in the battery level, the application sends the current level as notification.

Note
  This application is not power optimized!
  - The device must be in bonded state to change any characteristic in this application.
  - The TX Power Level characteristic is not writable.
  - The application will stop advertising and go to system-off mode after 3 minutes and 30 seconds (if no advertising with whitelist was done) or after 4 minutes (if advertising with whitelist was done). Push button 1 to restart advertising, or push and hold button 1 for 5 seconds to erase all bonds and restart advertising.
  - Upon disconnecting a bonded connection, the application will advertise with whitelist for ADV_INTERVAL_FAST_PERIOD seconds. After this time-out, the application will be able to bond to a new central.

# Setup

You can find the source code and the project file of the example in the following folder: `<InstallFolder>\examples\ble_peripheral\ble_app_proximity`

Button assignments - in addition to those defined in BSP BLE Button Assignments:

- During Connection:
  - Button 1: Raise/clear High Alert to the central with an Immediate Alert Service instance.

# Testing

Test the Proximity Application with the nRF Toolbox app, which is available on both iOS (App Store) and Android (Google Play).

You can also test the application with the Master Control Panel by performing the following steps:

1. Compile and program the application. Observe that the BSP_INDICATE_ADVERTISING state is indicated.
2. Connect to the device from Master Control Panel (the device will be advertising as 'Nordic_Prox'), then bond and perform service discovery. Observe that the BSP_INDICATE_CONNECTED state is indicated.
3. Set the AlertLevel characteristic in Immediate Alert Service to 1 (click the 'hex' radio button, enter '01' in the text box, and click the 'Write' button), and observe the Mild alert (BSP_INDICATE_ALERT_0).
4. Change the AlertLevel value to 2 and observe the High alert (BSP_INDICATE_ALERT_3).
5. Change the AlertLevel value to 0 and observe BSP_INDICATE_ALERT_OFF.
6. Set the AlertLevel characteristic in Link Loss Service to 1.
7. Simulate a link loss situation (for example by shielding the Master Emulator) and observe that both BSP_INDICATE_ALERT_0 and BSP_INDICATE_ADVERTISING are indicated.
8. Reconnect and observe that only the BSP_INDICATE_CONNECTED state is indicated.
9. Set the AlertLevel characteristic in Link Loss Service to 2.
10. Simulate a link loss situation, for example by disconnecting the Master Emulator, and observe that the BSP_INDICATE_ALERT_3 and BSP_INDICATE_ADVERTISING are indicated.
11. Reconnect and observe that only the BSP_INDICATE_CONNECTED state is indicated.
12. Select the TxPowerLevel characteristic in TX Power Service, click the 'Read' button, and verify that it was successfully read.
13. Click the 'Enable services' button to start notification of Battery Level and observe that the battery level is notified periodically (if there is a change).
14. Disconnect from the Master Control Panel and observe that BSP_INDICATE_ADVERTISING is indicated.
15. Wait until the application goes to system-off (BSP_INDICATE_IDLE).
16. Press button 1 and connect to the Master Control Panel. Observe that BSP_INDICATE_CONNECTED is indicated and that the battery level is notified periodically (if there is a change).
17. Disconnect from the Master Control Panel.
18. Connect with a different central and bond and disconnect.
19. Wait until the application goes to system-off (BSP_INDICATE_IDLE).
20. Press button 1 and reconnect to the first Master Control Panel. Observe that BSP_INDICATE_CONNECTED is indicated and that the battery level is notified periodically (if there is a change).
21. Disconnect from the Master Control Panel.
22. Connect with the second central and observe that the link encryption is on and that the battery level is not notified.
23. Disconnect from the second central and wait for the application to go to system-off.
24. Press and hold button 2 (erase bonds) for 5 seconds and connect with the first Master Control Panel. Observe that the link encryption is OFF and that no notifications are received.
25. Disconnect from Master Control Panel.

Test the Find Me locater (Immediate Alert Service Client) functionality by performing the following steps:

1. In the Master Control Panel, create the Immediate Alert Service (IAS) server by performing the following steps:
   - Click File -> Server Setup. In the window that is displayed, click File -> Load setup.
   - In the resulting window, navigate to the `<InstallFolder>\examples\ble_peripheral\ble_app_proximity` folder. Load the file `findMeMasterServer.bin`.
   - Click the 'Stop Server' button and then 'Start Server'. This restarts the server with Immediate Alert Service configured.
   - You must keep the 'Server Setup' window opened.
2. Go to the Master Control Panel main window and connect to the device.
3. Press button 1 and observe that the AlertLevel value at the 'Server setup' window of the Master Control Panel changes to 02. This indicates that the device was able to signal a High Alert to the central.
4. Press button 1 again and observe that the AlertLevel value changes to 00. This indicates that the device was able to clear the High Alert previously signalled to the central.