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

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.

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

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

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: