nRF Connect Bluetooth Low Energy User Guide

Revision History

Previous versions

PDF files for relevant previous versions are available here:

• nRF Connect Bluetooth ® Low Energy User Guide v2.1 (corresponds to nRF Connect Bluetooth ® Low Energy v2.1.0)
• nRF Connect Getting Started Guide v1.1 (corresponds to nRF Connect v1.1.0)
• nRF Connect Getting Started Guide v1.0 (corresponds to nRF Connect v1.0.0)

1 Introduction

nRF Connect Bluetooth Low Energy is an app for the nRF Connect desktop application for getting familiar with, developing, and testing Bluetooth Low Energy devices. It allows users to set up a local device, connect it to advertising devices, discover their services, maintain the connection and connection parameters, pair devices, and change the server setup for the local device. It also offers a detailed log for troubleshooting purposes.

Supported devices

• PCA10056 nRF52 Development Kit
• PCA10040 nRF52 Development Kit
• PCA10059 nRF52 USB Dongle
• PCA10028 nRF51 Development Kit
• PCA10031 nRF51 Dongle

Supported operating systems

• Microsoft Windows 7, 8, and 10
• OS X 10.10 and above
• Ubuntu Linux 14.04, 16.04, and 18.04

2 Installing the Bluetooth Low Energy app

The Bluetooth Low Energy app is installed as an app for nRF Connect for Desktop. Before installing the Bluetooth Low Energy app, users must download and install nRF Connect for Desktop.

To install the Bluetooth Low Energy app:

1. Open nRF Connect for Desktop.
2. Click Add/remove apps.
3. Find the Bluetooth Low Energy app and click Install.

Once the app is installed, the green Installed tag is displayed next to the More information button. The app can now be launched from the Launch app screen. For easy access, a desktop shortcut can be created by clicking the arrow down button and selecting Create shortcut.

3 Bluetooth Low Energy app overview

After starting the nRF Connect Bluetooth Low Energy app, the application window is displayed. The application window consists of the following main elements:

Main view

The main view in the center is initially empty but will be populated with local and remote Bluetooth Low Energy devices when they are discovered.

Navigation bar

In the bar at the top, users can select the device and switch between different application screens. Clicking the three-dash button in the top-left corner displays information about the app or allows launching another app.

Discovered devices

In this view on the right side, users can start scanning and view discovered devices.

Log

The log view at the bottom shows the most important log events, tagged with a time stamp.

[Image: Screenshot of the nRF Connect Bluetooth Low Energy application window showing the main view, navigation bar, discovered devices list, and log.]

4 Establishing serial port connection to a local device

The nRF Connect Bluetooth Low Energy app requires a serial port connection to a local development kit or dongle. The nRF SoC (System on Chip) on the device is controlled by the app, which sends serialized commands to it over a serial port.

To set up a local device:

1. Connect a development kit or dongle to the computer with USB.
2. In the navigation bar, click on the Select device menu.
3. Select a device by clicking on its name in the drop-down list.

When the serial port is selected, the Select device menu shows the name of the selected port. If the device has not been used with the nRF Connect Bluetooth Low Energy app before, users may be asked to update the J-Link firmware and connectivity firmware for the device. The correct connectivity firmware must be on the nRF SoC to continue. When the nRF SoC has been programmed with the correct firmware, the nRF Connect Bluetooth Low Energy app proceeds to connect to it over UART. When the connection is established, the device appears in the main view.

Important: When using OS X, an issue with the SEGGER J-Link OB firmware leads to the corruption of long packets over UART. See www.nordicsemi.com/nRFConnectOSXfix for more information.

[Image: Screenshot showing the local device view in the nRF Connect application, displaying the adapter details and attribute table.]

The local device is labeled "adapter" to signal that it is connected locally to the computer. The device name and Bluetooth device address are shown at the top. The attribute table of the device is shown below them. To expand a menu that shows actions and configurations available for the local device, click the Device options icon [gear icon].

5 Establishing Bluetooth Low Energy connections

The nRF Connect Bluetooth Low Energy app can establish and maintain up to eight simultaneous Bluetooth Low Energy connections.

To connect to devices:

1. To scan for nearby Bluetooth devices, click the Start scan button in the Discovered devices view.

Advertising devices start to appear in a list in the Discovered devices view. Each entry in the list shows the name, address, and RSSI of the received advertising packet. For information on how to set up advertising for a device, see Setting up advertising on page 17. To view the advertising type and data fields of a packet, select the packet entry in the list. To sort the list according to signal strength and thus according to which device is closest, click Options and select Sort by signal strength.

2. To establish a Bluetooth connection with a peer device, click the Connect button associated with the device.

[Image: Screenshot showing discovered Bluetooth Low Energy devices with their services listed.]

When the connection has been established, a new device appears in the main view to the right of the local device. The nRF Connect Bluetooth Low Energy app automatically performs an initial service discovery. The discovered services are listed below the connected device. Attributes known to the application are shown by their name. Attributes unknown to the application are shown by their UUID only. For information on how to add UUID definitions, see Adding UUID definitions on page 21.

A line connects the local and remote device, signaling that they are connected over Bluetooth. To open a connection info dialog displaying the parameters of the connection, encryption, and bond state, hover the mouse pointer over the padlock icon [padlock icon].

[Image: Screenshot showing connection information details, including connection interval, slave latency, timeout, and bonding status.]

6 Viewing service details

The nRF Connect Bluetooth Low Energy app can discover and display services, characteristics, and descriptors of a connected peer device's attribute table.

[Image: Screenshot displaying detailed service information for a connected Bluetooth Low Energy device.]

• To view the handle and UUID of an attribute, move the mouse pointer over the attribute name. A hover text is displayed.
• To view the characteristics of a service, click the Expand/collapse icon [*]. The characteristics have different buttons available depending on the associated properties. Read, write, and notify actions are available if the corresponding properties are available for the characteristic.
• To view descriptors, expand the characteristics.
• To configure the peer device to start sending notifications, click the Toggle notifications icon [square with arrow]. When a device receives a notification, the corresponding attribute is highlighted and its value is updated. If a service or characteristic does not have any child attributes, the list is empty when the Expand/collapse icon [*] is clicked.

7 Updating connection parameters

In a connection, users can request new connection parameters and respond to an incoming connection parameter update request.

To define connection parameters:

1. To view device options for the connected device, click the Device options icon [gear icon].
2. To open the Connection update dialog, click Update connection….

[Image: Screenshot of the Connection update dialog box.]

3. Set the desired parameters in the dialog, then click Update.
4. To close the Connection update dialog, click Close.

There are two main options for responding to update requests: letting the nRF Connect Bluetooth Low Energy app accept the request automatically (default) or responding to the request manually.

To select the responding option:

1. Click the local Device options icon [gear icon].
2. Select or deselect Auto accept update requests.

[Image: Screenshot showing the 'Events and actions' dialog with the 'Connection update' section and the 'Auto accept update requests' option.]

8 Pairing devices

Pairing is the process of exchanging security keys and establishing an encrypted link. The level of security is configurable, ranging from an unencrypted link with no security to an encrypted link with authentication and protection against man-in-the-middle attacks.

To pair with a connected device:

1. To view device options for the connected device, click the Device options icon [gear icon].
2. To open the Pairing dialog, click Pair....

[Image: Screenshot of the Pairing dialog box.]

3. Set the desired parameters in the dialog, then click Pair.

Depending on the chosen security parameters, an additional dialog may be shown for passkey, out-of-band data, or numerical comparison input. To close the Pairing dialog, click Close.

When the pairing procedure is completed, the following changes are displayed:

• A log entry shows the new security level of the connection.
• The connection info padlock changes to locked if the connection is encrypted.
• The event view text turns green to indicate success.

Bonding can also be established, which means creating and exchanging long-term keys used for reestablishing an encrypted link without having to go through the pairing process again.

The nRF Connect Bluetooth Low Energy app can reply automatically to an incoming pairing request by default, or it can be handled by the user.

To select the reply option for pairing requests:

1. Click the local Device options icon [gear icon].
2. Select or deselect Auto reply security requests.

[Image: Screenshot of the 'Events and actions' dialog with the 'Pairing' section and the 'Auto reply security requests' option.]

When Auto reply security requests is selected, the nRF Connect Bluetooth Low Energy app uses the settings specified in Security parameters when automatically replying to the request.

To edit security parameters:

1. Click the local Device options icon [gear icon].
2. To open the Security parameters dialog, click Security parameters.
3. Click Apply when done.

Important:

• Bonding is supported, but the keys are not retained across application restarts.
• Address resolving is currently not supported. Therefore, using keys from a bond after the device has changed address will most likely fail.

9 Configuring server setup

The nRF Connect Bluetooth Low Energy app supports the configuration of the local device's GATT (Generic Attribute profile) attribute table, also known as server setup. Adding attributes to the server setup allows the local device to exchange data with a connected peer device.

The default server setup consists of two mandatory services: GATT and GAP (Generic Access Profile). These services can be modified but not removed, and users cannot extend them with more characteristics or descriptors.

To add new attributes to the server setup:

1. In the navigation bar, click the Server setup button. Initially, the default server setup displayed contains only GAP and GATT services.
2. Click New service.
3. Select the service just added. A form is displayed.
4. Define the attribute values, then click Save.
5. To add a new characteristic, expand the added New Service, then click New characteristic.
6. Select the characteristic just added. A form is displayed.
7. Define the attribute values, then click Save.

Important: When adding a notify or indicate property on a characteristic, a Client Characteristic Configuration Descriptor (CCCD) needs to be added for that characteristic.

8. To add a new descriptor, expand the added New Characteristic, then click New descriptor.
9. Select the descriptor just added. A form is displayed.
10. Define the attribute values, then click Save.
11. When the server setup is completed, click Apply to device to upload the setup to the local device.

[Image: Screenshot of the Server setup interface, showing options to add new services, characteristics, and descriptors.]

To save a server setup to a file for later use:

1. Click the local Device options icon [gear icon].
2. Click Save setup....
3. Choose a directory and type a file name, then click Save.

To load a previously saved server setup from a file:

1. Click the local Device options icon [gear icon].
2. Click Load setup....
3. Navigate to the correct directory and select the file, then click Open.

Important: If a setup is removed or overwritten on the device, it needs to be reset and reopened. Confirm the reset when prompted.

After the setup is applied to the device, the resulting setup can be viewed by clicking the Connection map button in the navigation bar. The new setup is reflected in the local device.

10 Setting up advertising

The nRF Connect Bluetooth Low Energy app enables the local device to operate as a peripheral that can send connectable advertising packets. The contents of the advertising packets can be configured in the advertising setup.

To start sending advertising packets:

1. Click the local Device options icon [gear icon].
2. To start advertising the device, click Start advertising.
3. Specify the contents of the advertising packets:

a) Click the local Device options icon [gear icon].

b) To display the Advertising setup dialog, click Advertising setup.

c) From the AD type drop-down menu, select an AD type.

d) In the Value field, add a data value.

e) Select Add to advertising data or Add to scan response.

f) Repeat until all wanted fields are present.

g) Click Apply, then click Close.

[Image: Screenshot of the Advertising setup dialog, showing options for AD type, value, and adding data to advertising or scan response.]

11 Updating firmware over the air

If the connected device has the Nordic Device Firmware Update (DFU) Service, the firmware on the device can be updated. For more information on the DFU process, see Device Firmware Update process. For DFU bootloader examples, see DFU bootloader examples.

For a device with DFU Service, Secure DFU appears in the device's list of discovered services, and the Start Secure DFU button appears in the list header.

[Image: Screenshot showing Secure DFU in the list of discovered services.]

To update the firmware:

1. To open the DFU dialog, click the Start Secure DFU button [button with text 'Start Secure DFU'].
2. Browse and select a DFU zip package file on the computer.

Important: To create the DFU zip package file, use the nrfutil tool. See the nrfutil documentation for more information.

Information on the content of the DFU zip package is displayed in the Package info field.

[Image: Screenshot of the Device Firmware Upgrade (DFU) dialog showing file selection and package information.]

3. To start the transfer of the DFU package to the connected peer device, click Start DFU. The progress bar shows the progress of the transfer.

[Image: Screenshot showing the DFU transfer progress bar.]

4. When the progress bar has reached 100%, click Close.

[Image: Screenshot showing the DFU transfer completion.]

To stop the transfer, click Stop DFU. The transfer continues from where it was stopped when Start DFU is clicked again. If Close is clicked before the DFU transfer is completed, a confirmation dialog appears. Clicking OK in the confirmation dialog cancels the transfer.

12 Adding UUID definitions

The nRF Connect Bluetooth Low Energy app comes with a list of predefined names and UUIDs for some well-known profiles. This list can be extended with custom definitions.

To extend the list of known UUIDs:

1. To expand the device options for the local device, click the Device options icon [gear icon].
2. Click Open UUID definitions file. The definitions file is opened in the default application for .json files.
3. Following the examples in the file, add custom UUIDs, then save the file.
4. To load the changes, reconnect to the adapter or reload the application (CTRL + r).

13 Troubleshooting

For troubleshooting, the nRF Connect Bluetooth Low Energy app has a more detailed log file than the one shown in the log view. To open the detailed log file, click the Open log file button in the log view.

Firmware programming

If the error "Could not connect to debug probe" is received, verify that J-Link software is properly installed on the system.

If the device has been programmed with memory protection, the nRF Connect Bluetooth Low Energy app cannot program the firmware. To erase the device, download nRF Command Line Tools from Nordic Semiconductor and issue the following command from the command line:

In Windows: If the error "Could not load nrfjprog DLL" is received, verify that nRF Command Line Tools are installed.

OS X J-Link issue

In OS X: An issue with the SEGGER J-Link OB firmware leads to the corruption of long packets over UART. See www.nordicsemi.com/nRFConnectOSXfix for more information.

Serial port access permissions on Ubuntu Linux

If errors are received when trying to open the serial port in the nRF Connect Bluetooth Low Energy app on Ubuntu Linux, users may need to grant serial port access permissions to their user. To do this, run the following command:

nRF52840 USB problems

If errors related to the nRF52840 Dongle USB connection are received on Windows, see GitHub.

Legal notices

By using this documentation, users agree to Nordic Semiconductor's terms and conditions of use. Nordic Semiconductor may change these terms and conditions at any time without notice.

Liability disclaimer

Nordic Semiconductor ASA reserves the right to make changes without further notice to the product to improve reliability, function, or design. Nordic Semiconductor ASA does not assume any liability arising out of the application or use of any product or circuits described herein. Nordic Semiconductor ASA does not give any representations or warranties, expressed or implied, as to the accuracy or completeness of such information and shall have no liability for the consequences of use of such information. If there are any discrepancies, ambiguities, or conflicts in Nordic Semiconductor's documentation, the Product Specification prevails. Nordic Semiconductor ASA reserves the right to make corrections, enhancements, and other changes to this document without notice.

Life support applications

Nordic Semiconductor products are not designed for use in life support appliances, devices, or systems where malfunction of these products can reasonably be expected to result in personal injury. Nordic Semiconductor ASA customers using or selling these products for use in such applications do so at their own risk and agree to fully indemnify Nordic Semiconductor ASA for any damages resulting from such improper use or sale.

RoHS and REACH statement

Nordic Semiconductor products meet the requirements of Directive 2011/65/EU of the European Parliament and of the Council on the Restriction of Hazardous Substances (RoHS 2) and the requirements of the REACH regulation (EC 1907/2006) on Registration, Evaluation, Authorization and Restriction of Chemicals. The SVHC (Substances of Very High Concern) candidate list is continually being updated. Complete hazardous substance reports, material composition reports, and the latest version of Nordic's REACH statement can be found on the website www.nordicsemi.com.

Trademarks

All trademarks, service marks, trade names, product names, and logos appearing in this documentation are the property of their respective owners.

Copyright notice

© 2019 Nordic Semiconductor ASA. All rights are reserved. Reproduction in whole or in part is prohibited without the prior written permission of the copyright holder.

COMPANY WITH QUALITY SYSTEM CERTIFIED BY DNV GL $=$ ISO 9001