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	Board target
nRF54H20 DK	PCA10175	nrf54h20dk	nrf54h20dk/nrf54h20/cpuapp
nRF5340 DK	PCA10095	nrf5340dk	nrf5340dk/nrf5340/cpuapp/ns nrf5340dk/nrf5340/cpuapp
nRF52 DK	PCA10040	nrf52dk	nrf52dk/nrf52832
nRF52840 DK	PCA10056	nrf52840dk	nrf52840dk/nrf52840

When built for a board target with the */ns variant, 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, or a computer with 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

nRF52 and nRF53 DKsnRF54 DKs

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:

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 a board target with the */ns variant, 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, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

Note

When using the nRF54H20 DK Engineering B (from v0.8.0 to 0.8.2), you must build samples and applications using the board revision 0.8.0 with the <board>@<revision> syntax. For example, nrf54h20dk@0.8.0/nrf54h20/cpuapp when building for the application core, or nrf54h20dk@0.8.0/nrf54h20/cpurad when building for the radio core.

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

nRF52 and nRF53 DKsnRF54 DKs

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

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: a. Select the Server setup tab. #. Select Dongle configuration > Load setup. #. 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

nRF52 and nRF53 DKsnRF54 DKs

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:

nRF52 and nRF53 DKsnRF54 DKs

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

nRF52 and nRF53 DKsnRF54 DKs

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 shows 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 shows 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

• API:

  • 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