Bluetooth: Peripheral ANCS client

The Peripheral ANCS client sample demonstrates how to use the Apple Notification Center Service (ANCS) Client.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

nRF5340 DK

PCA10095

nrf5340dk_nrf5340

nrf5340dk_nrf5340_cpuapp_ns nrf5340dk_nrf5340_cpuapp

nRF52 DK

PCA10040

nrf52dk_nrf52832

nrf52dk_nrf52832

nRF52840 DK

PCA10056

nrf52840dk_nrf52840

nrf52840dk_nrf52840

When built for an _ns build target, the sample is configured to compile and run as a non-secure application with Cortex-M Security Extensions enabled. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

The sample also requires a device running an ANCS Server to connect with (for example, an iPhone which runs iOS, or a Bluetooth® Low Energy dongle and nRF Connect for Desktop).

User interface

LED 1:
  • Blinks every two seconds, duty cycle 50%, when the main loop is running.

LED 2:
  • On when connected.

Button 1:
  • Request iOS notification attributes (content) on UART.

Button 2:
  • Request iOS app attributes on UART.

Button 3:
  • Perform a positive action as a response to the last received notification.

Button 4:
  • Perform a negative action as a response to the last received notification.

Building and running

This sample can be found under samples/bluetooth/peripheral_ancs_client in the nRF Connect SDK folder structure.

When built as firmware image for the _ns build target, the sample has Cortex-M Security Extensions (CMSE) enabled and separates the firmware between Non-Secure Processing Environment (NSPE) and Secure Processing Environment (SPE). Because of this, it automatically includes the Trusted Firmware-M (TF-M). To read more about CMSE, see Processing environments.

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

Testing

After programming the sample to your development kit, you can test it either by connecting to an iOS device or by using nRF Connect for Desktop that emulates an ANCS Server.

Testing with an iOS device

  1. Connect to the kit that runs this sample with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.

  2. Reset the kit.

  3. Select the device in the iOS settings Bluetooth menu and connect.

  4. Observe that notifications that are displayed in the iOS notification tab also show up on the UART from the sample.

  5. Press Button 1 to retrieve the notification attributes and observe that you receive, among other information, the app identifier for the last received notification. For example, if you got a notification from the Calendar app and request the app identifier, it is “com.apple.mobilecal”.

  6. Press Button 2 to retrieve the app attributes and observe that you receive the display name for the app identifier from the previous step. For example, requesting the app attributes for “com.apple.mobilecal” yields “Calendar”.

  7. If the notification has a flag for a positive or negative action, perform the notification action with Button 3 or Button 4, respectively.

Testing with nRF Connect for Desktop

  1. Connect to the kit that runs this sample with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.

  2. Reset the kit.

  3. Start nRF Connect for Desktop.

  4. Open the Bluetooth Low Energy app and select the connected dongle that is used for communication.

  5. Click the SERVER SETUP tab. Click the dongle configuration and select Load setup. Load the ANCS_central.ncs file that is located under samples/bluetooth/peripheral_ancs_client in the nRF Connect SDK folder structure.

  6. Click Apply to device.

  7. Click the CONNECTION MAP tab. Click the dongle configuration and select Security parameters. Check Perform Bonding, and click Apply.

  8. Connect to the device from nRF Connect. The device is advertising as “ANCS”.

  9. Wait until the bond is established. Verify that the UART data is received as follows:

    Connected xx:xx:xx:xx:xx:xx (random)
    Security changed: xx:xx:xx:xx:xx:xx (random) level 2
    Pairing completed: xx:xx:xx:xx:xx:xx (random), bonded: 1
    GATT Service could not be found during the discovery
    The discovery procedure for ANCS succeeded
    
  10. After bonding, verify in the Bluetooth Low Energy app that the Client Characteristic Configuration (CCCD) value for Apple Notification Source and Apple Data Source are set to 01 00.

Send an iOS notification to the application

The following table shows the format of a notification that you can send to the example application:

Field

Example value

Interpretation

Event ID

0

Notification added

Flags

18

Positive/negative action

Category

06

Email

Category count

02

Notification UID

01 02 03 04

67305985 (0x4030201)

  1. In the Bluetooth Low Energy app, set the value of Apple Notification Source to 00 18 06 02 01 02 03 04 and click Update.

  2. Verify that the UART data is received as follows:

    Notification
    Event:       Added
    Category ID: Email
    Category Cnt:2
    UID:         67305985
    Flags:
     Positive Action
     Negative Action
    
Perform a notification action

The received notification has two flags: Positive Action and Negative Action. This means that you can perform these two actions on the notification.

The following table shows the format of the message that the application must send back to perform a notification action:

Field

Example value

Interpretation

Command ID

2

Perform notification action

Notification UID

01 02 03 04

67305985 (0x4030201)

Action

00

01

Positive

Negative

  1. Press Button 3 to perform a positive action and verify that the Apple Control Point value is updated to 02 01 02 03 04 00.

  2. You can also press Button 4 and observe that the server receives a negative action 02 01 02 03 04 01.

Retrieve notification attributes

The following table shows the relevant part of a request to retrieve notification attributes:

Field

Example value

Interpretation

Command ID

0

Get notification attributes

Notification UID

01 02 03 04

67305985 (0x4030201)

Attribute ID

00

App identifier

Attribute ID

01

Title

Length

20 00

0x0020

Attribute ID

03

Message

Length

20 00

0x0020

Note that the example application will request all existing attribute types, not only a subset.

The following table shows the format of a response that contains some of the requested notification attributes:

Field

Example value

Interpretation

Command ID

0

Get notification attributes

Notification UID

01 02 03 04

67305985 (0x4030201)

Attribute ID

01

Title

Length

03 00

0x0003

Data

6E 52 46

“nRF”

Attribute ID

03

Message

Length

02 00

0x0002

Data

35 32

“52”

Attribute ID

00

App identifier

Length

03 00

0x0003

Data

63 6F 6D

“com”

  1. Press Button 1 to request notification attributes for the iOS notification that was received.

  2. In the Bluetooth Low Energy app, verify that the Apple Control Point is updated to 00 01 02 03 04 00 01 20 00 02 20 00 03 20 00 04 05 06 07.

  3. Respond to the request by sending two notification attributes: the title and the message. Set the Apple Data Source value in the Server to 00 01 02 03 04 01 03 00 6E 52 46 03 02 00 35 32.

  4. The application will print the received data on UART. Verify that the UART output is as follows:

    Title: nRF
    Message: 52
    
  5. Update the Apple Data Source value again with the app identifier 00 03 00 63 6F 6D.

  6. Verify that the notification is received and the UART output is as follows:

    App Identifier: com
    
Retrieve app attributes

With the app identifier, you can request attributes of the app that sent the notification.

The following table shows the format of a request to retrieve app attributes:

Field

Example value

Interpretation

Command ID

1

Get app attributes

App identifier

6D 6F 63 00

“com” + ‘0’

Attribute ID

0

Display name

The following table shows the format of a response that contains the requested app attributes:

Field

Example value

Interpretation

Command ID

1

Get app attributes

App identifier

6D 6F 63 00

“com” + ‘0’

Attribute ID

0

Display name

Length

04 00

0x0004

Data

4D 61 69 6C

“Mail”

  1. Press Button 2 to request app attributes for the app with the app identifier “com” (the last received app identifier).

  2. In the Bluetooth Low Energy app, verify that the Apple Control Point is updated to 01 63 6F 6D 00 00.

  3. Respond to the request by sending the app attribute. Set the Apple Data Source value in the Server to 01 63 6F 6D 00 00 04 00 4D 61 69 6C.

  4. The application will print the received data on UART. Verify that the UART output is as follows:

    Display Name: Mail
    
Disconnect

Disconnect the device in the Bluetooth Low Energy app. As the bond information is preserved by the app, you can immediately reconnect to the device by clicking Connect.

Dependencies

This sample uses the following nRF Connect SDK libraries:

In addition, it uses the following Zephyr libraries:

  • include/zephyr/types.h

  • lib/libc/minimal/include/errno.h

  • include/sys/printk.h

  • Bluetooth APIs:

    • include/bluetooth/bluetooth.h

    • include/bluetooth/conn.h

    • include/bluetooth/uuid.h

    • include/bluetooth/gatt.h

The sample also uses the following secure firmware component: