This example requires one of the following SoftDevices: S112, S132, S140
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. The application uses the GATT Service Client to look for an ANCS server whenever there is a change in the services on the peer device.
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 30 seconds 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 nRF Connect
You can also test the application by emulating an iOS device with nRF Connect. 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 nRf Connect, create the Apple Notification Center Service (ANCS) server by completing the following steps:
- In Server Setup, click the settings button and select "Load setup".
- In the resulting window, navigate to the
<InstallFolder>\examples\ble_peripheral\ble_app_ancs_c
folder. Load the file ANCS_central.ncs
.
- Click "Apply to device" and navigate back to Connection Map.
- Bond to the device from nRF Connect (the device is advertising as 'ANCS'). To bond, click the settings button for the server in nRF Connect, select "Security parameters", check "Perform Bonding", and click "Apply". Then connect to the device.
- Observe that the BSP_INDICATE_CONNECTED state is indicated.
- After bonding, verify in the Server setup that the Client Characteristic Configuration descriptors (CCCD) for ANCS Notification Source (0x120D) and ANCS Data Source (0xC6E9) 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) |
- In nRF Connect, set the value of ANCS 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 nRF Connect, 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 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 | 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 | 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 nRF Connect, 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 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 the device in nRF Connect 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 reconnect to nRF Connect. Observe that the BSP_INDICATE_CONNECTED state is indicated.
- Disconnect from nRF Connect.