BR/EDR Audio

The purpose of this document is to provide an overview of the BR/EDR audio demo application. The BR/EDR audio project gives a simple example on how to use A2DP and HFP. This project implements SRC and SNK role for A2DP. And for HFP, AG and HF unit are implemented.

Requirements

The sample supports the following development kits:

Development Kits
Hardware Platforms	Board Name	Build Target
RTL87x3E HDK	RTL87x3E EVB	`bt_audio_demo_4M_bank0` `bt_audio_demo_16M_bank0`
RTL87x3D HDK	RTL87x3D EVB	`bt_audio_demo_16M_bank0`

Note

To purchase EVB, please visit https://www.realmcu.com/en/Home/Shop.

This sample project can be found under board\evb\bt_audio in SDK folder structure. Developers can choose the project according to the Board Name and choose the Build Target according to the flash map.

When built for an xxx_4M_xxx build target, the sample is configured to compile and run with a 4M flash map.

When built for an xxx_16M_xxx build target, the sample is configured to compile and run with a 16M flash map.

To quickly set up the development environment, please refer to the detailed instructions provided in Quick Start.

Tip

You can directly reference Quick Start to avoid repetitive descriptions.

The TX and RX PINMUX of console is defined in app_audio_demo_main.c. It is important to note that the pins need to be wired in reverse, which means that the TX of console should be connected to P3_0, and the RX should be connected to P3_1 in order to establish a connection with the serial port.

#define BT_AUDIO_UART_TX          P3_1
#define BT_AUDIO_UART_RX          P3_0

Configurations

APP configurable functions are defined in sdk\src\sample\bt_audio\app_flags.h.

The user can easily change the value of the macro definition to switch the function.

Building and Downloading

Note

This section introduces sample compilation methods (such as Keil, GCC, etc.) and how to download them to EVB (J-Link, MPPG Tool, etc.).

Take the project rtl87x3e_bt_audio_demo.uvprojx and target bt_audio_demo_4M_bank0 as an example, to build and run the sample with Keil development environment, follow the steps listed below:

Open rtl87x3e_bt_audio_demo.uvprojx.
Choose the build target bt_audio_demo_4M_bank0.

Choose Build Target
Building the target.

Building
Download APP bin into EVB board.

Tip

Quick Start includes sections like Generating APP Image and Images Download. If they are consistent, please directly reference them.

Experimental Verification

Note

This section introduces the console commands and test procedure during the experimental process.

BR/EDR Commands

BR/EDR Address Set

Users can use this command to congifure bredr address of local device or remote device which be connected to.

BR/EDR Local Address Set Command
Information	Description
Command	`bredr addr_set local`
Parameters	Local Bluetooth Address
Usage	Set local device bredr address.
Example	`bredr addr_set local 0x01 0x02 0x03 0x04 0x 05 0x06`

BR/EDR Remote Address Set Command
Information	Description
Command	`bredr addr_set remote`
Parameters	Local Bluetooth Address
Usage	Set remote device bredr address.
Example	`bredr addr_set remote 0x01 0x02 0x03 0x04 0x 05 0x06`

BR/EDR Inquiry

BR/EDR Inquiry Command
Information	Description
Command	`bredr inquiry`
Parameters	None
Usage	Start general inquiry.

BR/EDR Name Set

BR/EDR Inquiry Command
Information	Description
Command	`bredr name_set`
Parameters	Local Device Name
Usage	Set local device bredr name.
Example	`bredr name_set bt_audio_sink`

BR/EDR Device Mode Set

BR/EDR Device Mode Set Command
Information	Description
Command	`bredr device_mode_set idle`
Command	`bredr device_mode_set discoverable`
Command	`bredr device_mode_set discoverable_connectable`
Usage	Set local device discoverable or undiscoverable and connectable or unconnectable.

BR/A2DP Commands

A2DP Connect

The description of A2DP connect can be divided into the following information:

A2DP Connect Command
Information	Description
Command	`a2dp connect`
Usage	Connect A2DP with remote device.

The reference API can be found in bt_a2dp_connect_req().

A2DP connect flow is shown in Figure below.

../../../_images/a2dp_connect_flow.png — A2DP Connect

A2DP Disconnect

The description of A2DP disconnect can be divided into the following information:

A2DP Disconnect Command
Information	Description
Command	`a2dp disconnect`
Usage	Disconnect A2DP with remote device.

The reference API can be found in bt_a2dp_disconnect_req().

A2DP disconnect flow is shown in Figure below.

../../../_images/a2dp_disconnect_flow.png — A2DP Disconnect

A2DP Start

The description of A2DP start can be divided into the following information:

A2DP Start Command
Information	Description
Command	`a2dp start`
Usage	Start audio streaming.

The reference API can be found in bt_a2dp_stream_start_req().

A2DP start flow is shown in Figure below.

../../../_images/a2dp_start_flow.png — A2DP Start

A2DP Suspend

The description of A2DP suspend can be divided into the following information:

A2DP Suspend Command
Information	Description
Command	`a2dp suspend`
Usage	Suspend audio streaming.

The reference API can be found in bt_a2dp_stream_suspend_req().

A2DP suspend flow is shown in Figure below.

../../../_images/a2dp_suspend_flow.png — A2DP Suspend

A2DP Volume Up

The description of A2DP volume up can be divided into the following information:

A2DP Volume Up Command
Information	Description
Command	`a2dp vol+`
Usage	Increase A2DP volume.

A2DP Volume Down

The description of A2DP volume down can be divided into the following information:

A2DP Volume Down Command
Information	Description
Command	`a2dp vol-`
Usage	Decrease A2DP volume.

The reference API can be found in bt_avrcp_absolute_volume_set().

A2DP volume control flow is shown in Figure below.

../../../_images/a2dp_volume_control_flow.png — A2DP Volume Control

AVRCP Commands

AVRCP Connect

The description of AVRCP cover art connect can be divided into the following information:

AVRCP Connect Command
Information	Description
Command	`avrcp cover_art_connect`
Usage	Connect AVRCP cover art with remote device.

The reference API can be found in bt_avrcp_cover_art_connect_req().

AVRCP cover art connect flow is shown in Figure below.

../../../_images/avrcp_cover_art_connect_flow.png — AVRCP Cover Art Connect

AVRCP Cover Art Get

The description of AVRCP cover art get can be divided into the following information:

AVRCP Cover Art Get Command
Information	Description
Command	`avrcp cover_art_get`
Usage	Get cover art of current playing media.

The reference API can be found in bt_avrcp_cover_art_get().

AVRCP cover art get flow is shown in Figure below.

../../../_images/avrcp_cover_art_get_flow.png — AVRCP Cover Art Get

AVRCP Cover Art Disconnect

The description of AVRCP cover art disconnect can be divided into the following information:

AVRCP Cover Art Disconnect Command
Information	Description
Command	`avrcp cover_art_disconnect`
Usage	Disconnect AVRCP cover art.

The reference API can be found in bt_avrcp_cover_art_disconnect_req().

AVRCP cover art disconnect flow is shown in Figure below.

../../../_images/avrcp_cover_art_disconnect_flow.png — AVRCP Cover Art Disconnect

AVRCP Element Attribute Get

The description of AVRCP element attribute get can be divided into the following information:

AVRCP Element Attribute Get Command
Information	Description
Command	`avrcp attr_get`
Parameters	Attr ID, refer to `T_BT_AVRCP_ELEM_ATTR`.
Usage	Get element attribute of current playing media.
Example	`avrcp attr_get 0x01`

The reference API can be found in bt_avrcp_get_element_attr_req().

AVRCP element attribute get flow is shown in Figure below.

../../../_images/avrcp_get_elem_attr_flow.png — AVRCP Element Attribute Get

HFP Commands

HFP Connect

The description of HFP connect can be divided into the following information:

HFP Connect Command
Information	Description
Command	`hfp connect`
Usage	Connect HFP with remote device.

The reference API can be found in bt_hfp_connect_req().

HFP connect flow is shown in Figure below.

../../../_images/hfp_connect_flow.png — HFP Connect

HFP Disconnect

The description of HFP disconnect can be divided into the following information:

HFP Disconnect Command
Information	Description
Command	`hfp disconnect`
Usage	Disconnect HFP with remote device.

The reference API can be found in bt_hfp_disconnect_req().

HFP disconnect flow is shown in Figure below.

../../../_images/hfp_disconnect_flow.png — HFP Disconnect

HFP SCO Connect

The description of HFP SCO connect can be divided into the following information:

HFP SCO Connect Command
Information	Description
Command	`sco connect`
Usage	Connect SCO with remote device.

The reference API can be found in bt_hfp_audio_connect_req().

HFP SCO connect flow is shown in Figure below.

../../../_images/sco_connect_flow.png — HFP SCO Connect

HFP SCO Disconnect

The description of HFP SCO disconnect can be divided into the following information:

HFP SCO Disconnect Command
Information	Description
Command	`sco disconnect`
Usage	Disconnect SCO with remote device.

The reference API can be found in bt_hfp_audio_disconnect_req().

HFP SCO disconnect flow is shown in Figure below.

../../../_images/sco_disconnect_flow.png — HFP SCO Disconnect

HFP Call Answer

The description of HFP call answer can be divided into the following information:

HFP Call Answer Command
Information	Description
Command	`hfp call_answer`
Usage	Answer HFP incoming call.

The reference API can be found in bt_hfp_call_answer_req().

HFP call answer flow is shown in Figure below.

../../../_images/call_answer_flow.png — HFP Call Answer

HFP Call Terminate

The description of HFP call terminate can be divided into the following information:

HFP Call Terminate Command
Information	Description
Command	`hfp call_terminate`
Usage	Terminate HFP incoming/active call.

The reference API can be found in bt_hfp_call_terminate_req().

HFP call terminate flow is shown in Figure below.

../../../_images/call_terminate_flow.png — HFP Call Terminate

Preparation Phase

Prepare two development boards named EVB-1 and EVB-2 respectively, and use DebugAnalyzer Tool to get the logs.
Set the macro BT_AUDIO_DEMO_ROLE as 1, and then build the BT Audio demo application, and download images into EVB-1.
Set the macro BT_AUDIO_DEMO_ROLE as 2, and then build the BT Audio demo application, and download images into EVB-2.

Test Procedure

This section describes the testing process and expected test results of BR/EDR Audio Demo.

A2DP Test

Follow the steps below to continue the test procedure.

Modify configuration in app_flags.h for A2DP SRC, then build and download the BR/EDR audio demo application to EVB-1. According to the configuration below, EVB-1 acts as A2DP SRC.
```
#define BT_AUDIO_DEMO_ROLE  1
#define A2DP_DEMO_SUPPORT   1
```
Modify configuration in app_flags.h for A2DP SINK, then build and download the BR/EDR audio demo application to EVB-2. According to the configuration below, EVB-2 acts as A2DP SINK.
```
#define BT_AUDIO_DEMO_ROLE  2
#define A2DP_DEMO_SUPPORT   1
```
Remote address is the computer address.The user can input corresponding command referring to BR/A2DP Commands.
- Input CMD a2dp connect to connect A2DP with remote device.
A2DP Connect

Uart Command to Input

Output of Uart Response

Description

a2dp connect

A2DP Connected!

Connect A2DP withremote device.
- Input CMD a2dp start to start audio streaming. A piece of music shall be heard if a speaker is connected to EVB-2. The title of this royalty free music is Running Through Fields Of Wheat, and it is derived from https://motionarray.com/royalty-free-music/running-through-fields-of-wheat-557514/.
A2DP Start

Uart Command to Input

Output of Uart Response

Description

a2dp start

A2DP Streaming Started!

Start audio streaming.
- Input CMD a2dp suspend to suspend audio streaming.
A2DP Suspended

Uart Command to Input

Output of Uart Response

Description

a2dp suspend

A2DP Streaming Suspended!

Suspend audio streaming.
- Input CMD a2dp vol+ to increase A2DP volume. If volume is set to maximum already, serial port assistant tool shows: A2DP Volume Max Level: [Level]
Increase A2DP Volume

Uart Command to Input

Output of Uart Response

Description

a2dp vol+

A2DP Volume Level: [Level]

Increase A2DP volume.
- Input CMD a2dp vol- to decrease A2DP volume. If volume is set to maximum already, serial port assistant tool shows: A2DP Volume Min Level: [Level]
Decrease A2DP Volume

Uart Command to Input

Output of Uart Response

Description

a2dp vol-

A2DP Volume Level: [Level]

Decrease A2DP volume.
- Input CMD a2dp disconnect to disconnect A2DP with remote device.
A2DP Disconnect

Uart Command to Input

Output of Uart Response

Description

a2dp disconnect

A2DP Disconnected!

Disconnect A2DP with remote device.

AVRCP Test

Prepare one EVB as A2DP SINK, and a phone. Follow the steps below to continue the test procedure.

Modify configuration in app_flags.h for A2DP SINK, then build and download the BR/EDR audio demo application. According to the configuration below, EVB acts as A2DP SINK.
```
#define BT_AUDIO_DEMO_ROLE  2
#define A2DP_DEMO_SUPPORT   1
```
Power on EVB, turn on Bluetooth from phone setting, and pair to bt audio snk.
Start playing music.
Users can input corresponding command referring to AVRCP Commands.
- Input CMD avrcp cover_art_connect to initiate AVRCP cover art connection.
AVRCP Cover Art Connect

Uart Command to Input

Output of Uart Response

Description

avrcp cover_art_connect

AVRCP Cover Art Connected!

Connect cover art with remote device.
- Input CMD avrcp cover_art_get to get cover art of current playing media.
AVRCP Cover Art Get

Uart Command to Input

Output of Uart Response

Description

avrcp cover_art_get`

AVRCP Cover Art Get Success!

Get cover art of current playing media.
- Input CMD avrcp get_attr to get element attribute of current playing media.
AVRCP Cover Art Get

Uart Command to Input

Output of Uart Response

Description

avrcp get_attr`

[Attribute]: [Content]

Get element attribute of current playing media.
- Input CMD avrcp cover_art_disconnect to disconnect AVRCP cover art.
AVRCP Cover Art Get

Uart Command to Input

Output of Uart Response

Description

avrcp cover_art_disconnect

AVRCP Cover Art Disconnected!

Disconnect AVRCP cover art.

HFP Test

To demonstrate the HFP of BR/EDR Audio Demo Application, need to prepare 2 sets of Evolution Boards, EVB-1 and EVB-2. Then follow the steps below to continue the test procedure.

Modify configuration in app_flags.h for HFP AG, then build and download the BR/EDR audio demo application to EVB-1. According to the configuration below, EVB-1 acts as HFP AG.
```
#define BT_AUDIO_DEMO_ROLE  1
#define HFP_DEMO_SUPPORT    1
```
Modify configuration in app_flags.h for HFP HF, then build and download the BR/EDR audio demo application to EVB-2. According to the configuration below, EVB-2 acts as HFP HF.
```
#define BT_AUDIO_DEMO_ROLE  2
#define HFP_DEMO_SUPPORT    1
```
Reset and power on two EVBs.

The user can input corresponding command referring to HFP Commands.

Input CMD hfp connect to initiate HFP connection.

HFP Connect
Uart Command to Input	Output of Uart Response	Description
`hfp connect`	`HFP Connected!`	Connect HFP with remote demo EVB.

When HFP is connected, input CMD hfp call_incoming to inform application of a call is incoming.

HFP Call Incoming
Uart Command to Input	Output of Uart Response	Description
`hfp call_incoming`	`Call incoming!`	Inform application of a call is incoming.

When a call is incoming, input CMD hfp call_answer to answer HFP incoming call.

HFP Call answer
Uart Command to Input	Output of Uart Response	Description
`hfp call_answer`	`Call active!`	Answer HFP incoming call.

When a call is incoming or active, input CMD hfp call_terminate to terminate HFP incoming/active call.

HFP Call answer
Uart Command to Input	Output of Uart Response	Description
`hfp call_terminate`	`Call idle`	Answer HFP incoming call.
	`SCO Disconnected!`	Inform application of SCO disconnection complete.

If another calll process need to be create, more command in HFP Commands can be used.

Code Overview

Note

This chapter provides a brief analysis of important code.

The BR/EDR audio demo application overview will be introduced according to the following parts:

The directories of the project and source code files will be introduced in chapter Source Code Directory.
The main function will be introduced in chapter Source Code Overview.

Source Code Directory

Project directory: sdk\board\evb\bt_audio.
Source code directory: sdk\src\sample\bt_audio.

Source files in the sample project are currently categorized into several groups as below.

└── Project: bt_audio
    ├── include                       ROM UUID header files. Users do not need to modify it.
         └── cmsis                          The cmsis source code. Users do not need to modify it.
                  ├── startup_rtl87x3e.c
                  └── system_rtl87x3.c
         ├── Lib                                    Includes all binary symbol files that user application is built on.
         └── APP                                    The application source code.
                  ├── console_uart.c
                  ├── app_dlps.c
                  ├── app_io_msg.c
                  ├── app_console_msg.c
                  ├── app_bt_audio_console.c
                  ├── app_bt_audio_link.c
                  ├── app_bt_audio_main.c
                  ├── app_bt_audio_gap.c
                  ├── app_bt_audio_avrcp.c
                  ├── app_sbc_data.c
                  ├── app_bt_audio_a2dp.c
                  └── app_bt_audio_hfp.c

Source Code Overview

Initialization

Main function is invoked when the application is powered on or the chip resets and performs the following initialization functions.

int main(void)
{
   board_init();
   driver_init();
   task_init();
   framework_init();
   app_bt_gap_init();
   app_bt_profile_init();
   app_bt_audio_gap_init();
   app_bt_audio_cmd_register();

   os_sched_start();

   return 0;
}

Please refer to app_bt_audio_mian.c for initialization function declaration. More information on Bluetooth Profiles initialization can be found in A2DP Init of A2DP and HFP Init of HFP.

Profile Callback Message

APP can register different callback functions to handle different profiles.

void app_bt_audio_a2dp_init(uint8_t role)
{
   ...

   bt_mgr_cback_register(app_bt_audio_a2dp_cback);
}

void app_bt_audio_avrcp_init(void)
{
   ...

   bt_mgr_cback_register(app_bt_audio_avrcp_cback);
}

void app_bt_audio_hfp_init(uint8_t role)
{
   ...

   bt_mgr_cback_register(app_bt_audio_hfp_cback);
}