Experimental: BLE LE Secure Connections multirole example

This example requires one of the following SoftDevices: S130, S132

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

This example application demonstrates a simple application that uses LE Secure Connections (LESC) to enforce GAP Security Mode 1 Level 4, which requires pairing or bonding using LESC with man-in-the-middle (MITM) protection. The application uses the Peer Manager module, which supports LESC in both roles.

The application can act both as a peripheral or as a central depending on how the connection is set up. It will both advertise and scan when started up and after disconnection, and whichever role is established first will be selected for the next connection.

If you want the application to act as a peripheral, simply connect to it from a smart device or from another board running the same application. If you want the application to act as a central, simply provide a peripheral advertising with the Heart Rate Service UUID in its advertising data (this again can be either a smart device or another board running the same application).

The application includes the Heart Rate Service both as a server and as a client:

• Heart Rate Service
• Heart Rate Service Client

Security for the Client Characteristic Configuration Descriptor (CCCD) in the Heart Rate Measurement characteristic is set at Security Mode 1 Level 4, which requires LESC with MITM. This means that whenever the collector tries to enable notifications it will need first to secure it using those parameters.

Setup

Since the SoftDevice does not include the functionality required to calculate Elliptic Curve Cryptography (ECC) public keys and shared secrets, an external library is required for this purpose. Bindings and build files are provided for a well known open source library, micro-ecc, although the library itself is not provided.

Important note: micro-ecc is an open source library. Its usage requires compliance with the license of the library as stated on the LICENSE.txt file included in micro-ecc. It is the developer's responsibility to ensure compliance with all the terms present.

To use micro-ecc with this project you will need to do the following:

1. Install a version of the GCC compiler toolchain for ARM. This is needed since micro-ecc itself can only be built with GCC. You can find a toolchain for your operating system in ARM's Launchpad.
2. Clone the micro-ecc GitHub repository into InstallFolder\external\micro-ecc\micro-ecc. The revision tested at the time of the release of this SDK version is b6c0cdbe7d20af48b0c2a909a66ff00b093d1542.
3. Depending on which IC you are using, and which toolchain you plan to build your application with, go into one of the folders provided:
   • InstallFolder\external\micro-ecc\nrf51_keil\armgcc
   • InstallFolder\external\micro-ecc\nrf52_keil\armgcc
   • InstallFolder\external\micro-ecc\nrf51_iar\armgcc
   • InstallFolder\external\micro-ecc\nrf52_iar\armgcc
   • InstallFolder\external\micro-ecc\nrf51_armgcc\armgcc
   • InstallFolder\external\micro-ecc\nrf52_armgcc\armgcc
4. Run make to compile the library.
5. Open the project file with your toolchain of choice, it will be located here:
   • InstallFolder\examples\ble_central_and_peripheral\experimental\ble_app_multirole_lesc\Board\Toolchain
6. Compile and flash the appication.

Note: If you want to compile the micro-ecc library yourself using your own Makefile or other means, please make sure you use the same compilation options found in the Makefiles. This is specially important for preprocessor macros, and in particular uECC_VLI_NATIVE_LITTLE_ENDIAN=1, which needs to be set for the library to work properly with the example.

You can find the source code and the project file of the example in the following folder: <InstallFolder>\examples\ble_central_and_peripheral\experimental\ble_app_multirole_lesc

LED assignments:

• LED 1: ON if the central side is scanning.
• LED 2: ON if the central side is connected to a peripheral.
• LED 3: ON if the peripheral side is advertising.
• LED 4: ON if the peripheral side is connected to a central.

The application uses the following UART settings:

• Baud rate: 115.200
• 8 data bits
• 1 stop bit
• No parity
• HW flow control: None

Testing

Testing the application requires one of the following configurations:

1. A single board and a smart device that is compatible with LE Secure Connections
   • 1 application board: nRF5 Development Kit board containing the S13x SoftDevice and running the present application.
   • 1 smart device: A smart device (Smartphone or Tablet) running an Operating System supporting LE Secure Connections. iOS supports it from version 8.2.
2. 2 boards running the application
   • 2 application boards: nRF5 Development Kit boards containing the S13x SoftDevice and running this application.

Test the BLE LESC Multirole Example application by performing the following steps:

1. Compile the application and program both the SoftDevice and the application on the application board.
2. On the board, observe that LEDs 1 and 3 are on. This indicates that both the central and the peripheral side of the application are looking for peers.
3. Open an HRS-compatible application on your smart device (Master Control Panel, LightBlue or any other).
4. Either let the application board connect to your smart device (if the smart device is advertising the HRS UUID) or connect to the application board from the smart device's user interface.
5. If running the application board as a peripheral, try enable notifications on the HR Service from the smart device's application, this should trigger the activation of the bonding security procedure. If the application board is acting as a central, it should automatically try to enable notifications on the smart device's HR Service.
6. If numerical comparison is used, a log message (via UART or RTT) with the value to compare is displayed. Press Button 1 to validate it.
7. Observe that the bonding security procedure takes place. On the application board, the BLE_GAP_EVT_AUTH_STATUS event should be displayed with lv4 set to 1.
8. If you are testing with two sensor boards:
   1. Compile the application and program both the SoftDevice and the application on the second sensor board.
   2. Observe that the both boards are advertising and scanning.
   3. Observe that one of the boards connects to the other and the bonding security procedure takes place.