This example requires one of the following SoftDevices: S130, S132
Important: Before you run this example, make sure to program the SoftDevice.
The ANCS Client Application is an example that implements an Apple Notification Center Service client. This client receives iOS notifications and is therefore a Notification Consumer. It can be connected with a Notification Provider, typically an iPhone or some other Apple device, which functions as ANCS server.
For detailed information about the Apple Notification Center Service, see Apple's iOS Developer Library.
When the application is connected to a Notification Provider, it receives and prints incoming notifications on the UART. Pressing Button 1 requests the attributes of the last received notification. For example, if the notification indicates a new email, notification attributes contain the app identifier, the title of the email, the actual message, the sent date, and so on. Pressing Button 2 requests the attributes of the app that sent the notification (currently, the app attributes contain only the name of the app). If any attributes are received, they are printed to the UART.
Notifications can have positive and negative actions associated with them, depending on the app that is sending the notification. For example, a notification for an incoming call is usually associated with the positive action to answer the call and the negative action to reject it. After receiving a notification, the available actions are indicated by flags on UART. Push Button 3 to perform the positive action as response to the notification, or Button 4 to perform the negative action.
- Note
- This application is not power optimized!
-
The application will stop advertising after 3 minutes and go to system-off mode. Push Button 1 to restart advertising.
Setup
You can find the source code and the project file of the example in the following folder: <InstallFolder>\examples\ble_peripheral\ble_app_ancs_c
Button assignments - in addition to those defined in BSP BLE Button Assignments:
- During connection:
- Button 1: Request iOS notification attributes (content) on UART.
- Button 2: Request iOS app attributes on UART.
- Button 3: Perform a positive action as response to the last received notification.
- Button 4: Perform a negative action as response to the last received notification.
Testing with an iOS device
Perform the following steps to test the ANCS Client Application with an iOS device (for example, an iPhone):
- Start a terminal emulator like PuTTY and connect to the used COM port with the following UART settings:
-
Baud rate: 115.200
-
8 data bits
-
1 stop bit
-
No parity
-
HW flow control: None
- Compile and program the application. Observe that the BSP_INDICATE_ADVERTISING state is indicated.
- Select the device in the iOS settings -> Bluetooth menu and connect.
- Observe that the BSP_INDICATE_CONNECTED state is indicated.
- Observe that notifications that are displayed in the iOS notification tab also show up on the UART from the example application.
- 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".
- 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".
- 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 Master Control Panel
You can also test the application by emulating an iOS device with the Master Control Panel. To do so, perform the following steps (see the respective sections for detailed information):
- Establish a connection.
- Send an iOS notification to the application.
- Perform a notification action.
- Retrieve notification attributes.
- Retrieve app attributes.
- Disconnect.
Establish a connection
- Start a terminal emulator like PuTTY and connect to the used COM port with the following UART settings:
-
Baud rate: 115.200
-
8 data bits
-
1 stop bit
-
No parity
-
HW flow control: None
- Compile and program the application. Observe that the BSP_INDICATE_ADVERTISING state is indicated.
- In the Master Control Panel, create the Apple Notification Center Service (ANCS) server by completing the following steps:
- Click File -> Server setup. In the window that opens up, click File -> Load setup.
- In the resulting window, navigate to the
<InstallFolder>\examples\ble_peripheral\ble_app_ancs_c
folder. Load the file ANCS_central.bin
.
- Stop the server, and then start it again.
- You must keep the Server setup window open.
- Select the device from Master Control Panel (the device will be advertising as 'ANCS').
- Connect and bond.
- Observe that the BSP_INDICATE_CONNECTED state is indicated.
- Observe that the server is started.
- After bonding, verify in the Server setup that the Client Characteristic Configuration descriptors (CCCD) for Notification Source (0x120D) and Data Source (0xC6E9) are set to 00-01.
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) |
- In the Server setup, set the value of Notification Source (characteristic 0x120D) to 00-18-06-02-01-02-03-04 and click Update.
- 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 ANCS Control Point (0xD8F3) 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" |
- Press Button 1 to request notification attributes for the iOS notification that was received.
- In the Server setup, verify that the ANCS Control Point (0xD8F3) is updated to 00-01-02-03-04-00-01-20-00-02-20-00-03-20-00-04-05-06-07.
- Respond to the request by sending two notification attributes: the title and the message. To do this, first set the Data Source (characteristic 0xC6E9) in the Server setup to 00-01-02-03-04-01-03-00-6E-52-46-03-02-00-35-32.
- The application will print the received data on UART. Verify that the UART output is as follows:
Title: nRF
Message: 52
- Update the Data Source again with the app identifier 00-03-00-63-6F-6D.
- 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 | 63-6F-6D-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 | 63-6F-6D-00 | "com" + '\0' |
Attribute ID | 0 | Display name |
Length | 04-00 | 0x0004 |
Data | 4D-61-69-6C | "Mail" |
- Press Button 2 to request app attributes for the app with the app identifier "com" (the last received app identifier).
- In the Server setup, verify that the ANCS Control Point (0xD8F3) is updated to 01-63-6F-6D-00-00.
- Respond to the request by sending the app attribute. To do this, set the Data Source (characteristic 0xC6E9) in the Server setup to 01-63-6F-6D-00-00-04-00-4D-61-69-6C.
- The application will print the received data on UART. Verify that the UART output is as follows:
Display Name: Mail
Disconnect
- Disconnect from the Master Control Panel and observe that the BSP_INDICATE_ADVERTISING_WHITELIST state is indicated.
- Wait until the application goes to system-off (BSP_INDICATE_IDLE).
- Press (and hold) Button 1 and connect to the Master Control Panel. Observe that the BSP_INDICATE_CONNECTED state is indicated.
- Disconnect from the Master Control Panel.