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

nrf5340dk_nrf5340_cpuapp_ns

nRF52840 DK

PCA10056

nrf52840dk_nrf52840

nrf52840dk_nrf52840

nRF52833 DK

PCA10100

nrf52833dk_nrf52833

nrf52833dk_nrf52833

nRF52 DK

PCA10040

nrf52dk_nrf52832

nrf52dk_nrf52832

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.

See Building and programming an application for information about how to build and program the application.

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:

In addition, it uses the following Zephyr libraries:

  • include/zephyr/types.h

  • lib/libc/minimal/include/errno.h

  • include/sys/printk.h

  • Bluetooth:

    • include/bluetooth/bluetooth.h

    • include/bluetooth/conn.h

    • include/bluetooth/uuid.h

    • include/bluetooth/gatt.h