Bluetooth: Peripheral AMS client

The Peripheral AMS client sample demonstrates how to use the Apple Media Service (AMS) 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 AMS Server to connect with (for example, an iPhone which runs iOS, or a Bluetooth® Low Energy dongle and nRF Connect for Desktop).

Overview

The AMS client sample serves a Media Remote (MR). It can interact with a Media Source (MS), typically an iPhone or some other Apple device.

The sample prints the media details received from the MS on the UART. It can request the MS to perform certain actions, such as starting playback and jumping to next track.

User interface

LED 1:

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

LED 2:

On when connected.

Button 1:

Enable and disable MS track attributes notification.

Button 2:

Request MS to start or pause playback.

Button 3:

Request MS to jump to the next track if it is supported. Otherwise, request MS to turn up the volume.

Button 4:

Request MS to jump to the previous track if it is supported. Otherwise, request MS to turn down the volume.

Building and running

This sample can be found under samples/bluetooth/peripheral_ams_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 the Bluetooth Low Energy app of nRF Connect for Desktop that emulates an AMS 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 > Connect. When requested, proceed with pairing.

4. Open the Apple Music app and bring up a playlist with some songs.

5. Press Button 1 to enable song detail updates.

6. Press Button 2 to play a song. Press again to pause playback.

7. Press Button 3 to jump to the next song.

8. Press Button 4 to jump to the previous song.

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 the Bluetooth Low Energy app of nRF Connect for Desktop and select the connected dongle that is used for communication.

4. Set up the server:

   1. Select the Server setup tab.

   2. Select Dongle configuration > Load setup.

   3. Load the AMS_central.ncs file located under samples/bluetooth/peripheral_ams_client in the nRF Connect SDK folder structure.

5. Click Apply to device.

6. Select the Connection Map tab.

7. Select Dongle configuration > Security parameters.

8. Check Perform Bonding, and click Apply.

9. Connect to the device from the Bluetooth Low Energy app. The device is advertising as “Nordic_AMS”.

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

    Connected xx:xx:xx:xx:xx:xx (random)
    The discovery procedure succeeded
    Security changed: xx:xx:xx:xx:xx:xx (random) level 2
    Pairing completed: xx:xx:xx:xx:xx:xx (random), bonded: 1
    

11. After bonding, verify in the Bluetooth Low Energy app that the Client Characteristic Configuration (CCCD) value for Apple Remote Command and Apple Entity Update are set to 01 00.

Music setup

Complete the following steps to initiate a music player setup:

1. In the Bluetooth Low Energy app, verify that the Apple Entity Update is initiated to 00 00 01 02. The following table lists the attributes requested by the MR.

   Field	Value	Interpretation
   Entity ID	00	Player
   Attribute ID	00	Name
   Attribute ID	01	Playback Info
   Attribute ID	02	Volume

2. Press Button 1 to enable track attributes notification.

3. In the Bluetooth Low Energy app, verify that the Apple Entity Update is updated to 02 00 01 02 03. The following table lists the attributes requested by the MR.

   Field	Value	Interpretation
   Entity ID	02	Track
   Attribute ID	00	Artist
   Attribute ID	01	Album
   Attribute ID	02	Title
   Attribute ID	03	Duration

4. Set the Apple Remote Command value to 00 01 02 03 04 05 06 07 08 09 0A 0B 0C. It tells the MR the list of commands supported by the MS.

5. Verify that the UART output is as follows:

   AMS RC: 00,01,02,03,04,05,06,07,08,09,0A,0B,0C
   

6. Set the Apple Entity Update value to 00 01 00 30 2C 30 2E 30 2C 30 2E 30 30 30.

7. Verify that the UART output is as follows:

   AMS EU: 00,01,00 0,0.0,0.000
   

   The following table explains the notification.

   Field	Value	Interpretation
   Entity ID	00	Player
   Attribute ID	01	Playback Info
   Flags	00
   Value	0,0.0,0.000	Paused

8. Set the Apple Entity Update value to 02 03 00 31 32 30 2E 30 30 30.

9. Verify that the UART output is as follows:

   AMS EU: 02,03,00 120.000
   

   The following table explains the notification.

   Field	Value	Interpretation
   Entity ID	02	Track
   Attribute ID	03	Duration
   Flags	00
   Value	120.000	120 seconds

10. Set the Apple Entity Update value to 02 02 00 6E 52 46 35 32 20 53 65 72 69 65 73 20 73 6F 6E 67.

11. Verify that the UART output is as follows:

    AMS EU: 02,02,00 nRF52 Series song
    

    The following table explains the notification.

    Field	Value	Interpretation
    Entity ID	02	Track
    Attribute ID	02	Title
    Flags	00
    Value	nRF52 Series song	Current song title

Playback

To test an audio playback, complete the following steps:

1. Press Button 2 to start audio playback.

2. In the Bluetooth Low Energy app, verify that the Apple Remote Command is updated to 02.

3. Set the Apple Entity Update value to 00 01 00 31 2C 31 2E 30 2C 30 2E 30 31 34.

4. Verify that the UART output is as follows:

   AMS EU: 00,01,00 1,1.0,0.014
   

   The following table explains the notification.

   Field	Value	Interpretation
   Entity ID	00	Player
   Attribute ID	01	Playback Info
   Flags	00
   Value	1,1.0,0.014	Playing at rate 1.0. Elapsed 0.014 seconds.

Next track

To test the next track feature, complete the following steps:

1. Press Button 3 to jump to next song.

2. In the Bluetooth Low Energy app, verify that the Apple Remote Command is updated to 03.

3. Set the Apple Entity Update value to 02 03 00 31 38 30 2E 30 30 30.

4. Verify that the UART output is as follows:

   AMS EU: 02,03,00 180.000
   

   The notification informs about the updated song duration.

5. Set the Apple Entity Update value to 02 02 00 6E 52 46 35 33 20 53 65 72 69 65 73 20 73 6F 6E 67.

6. Verify that the UART output is as follows:

   AMS EU: 02,02,00 nRF53 Series song
   

   The notification informs about the updated song title.

Disconnect

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

Dependencies

This sample uses the following nRF Connect SDK libraries:

• Apple Media Service (AMS) Client

• 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