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, toggling on/off every second, when the main loop is running and the device is advertising.

LED 2:

Lit 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 Configuring and building an application for other building scenarios, Programming an application for programming steps, and Testing and optimization 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, nRF Connect Serial Terminal). See Testing and optimization for the required settings and steps.

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, nRF Connect Serial Terminal). See Testing and optimization for the required settings and steps.

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

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

• 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:

• Apple Notification Center Service (ANCS) Client

• Generic Attribute (GATT) Profile

• GATT Discovery Manager

• DK Buttons and LEDs

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:

• Trusted Firmware-M