esp-idf/examples/bluetooth/bluedroid/classic_bt/a2dp_source/README.md

| Supported Targets | ESP32 |
| ----------------- | ----- |

A2DP-SOURCE EXAMPLE
========================

Example of A2DP audio source role

This is the example of using Advanced Audio Distribution Profile (A2DP) APIs to transmit audio stream. Application can take advantage of this example to implement portable audio players or microphones to transmit audio stream to A2DP sink devices.

## How to use this example

### Hardware Required

This example is able to run on any commonly available ESP32 development board, and is supposed to connect to [A2DP sink example](../a2dp_sink) in ESP-IDF.

### Configure the project

```
idf.py menuconfig
```

* Enable Classic Bluetooth and A2DP under Component config --> Bluetooth --> Bluedroid Enable

### Build and Flash

Build the project and flash it to the board, then run monitor tool to view serial output.

```
idf.py -p PORT flash monitor
```

(Replace PORT with the name of the serial port to use.)

(To exit the serial monitor, type ``Ctrl-]``.)

See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.

## Example Output

For the first step, this example performs device discovery to search for a target device (A2DP sink) whose device name is "ESP_SPEAKER" and whose "Rendering" bit of its Service Class field is set in its Class of Device (COD). If a candidate target is found, the local device will initiate connection with it.

After connection with A2DP sink is established, the example performs the following running loop 1-2-3-4-1:
1. audio transmission starts and lasts for a while
2. audio transmission stops
3. disconnect with target device
4. reconnect to target device

The example implements an event loop triggered by a periodic "heart beat" timer and events from Bluetooth protocol stack callback functions.

After the local device discovers the target device and initiates connection, there will be logging message like this:

```
I (4090) BT_AV: Found a target device, address xx:xx:xx:xx:xx:xx, name ESP_SPEAKER
I (4090) BT_AV: Cancel device discovery ...
I (4100) BT_AV: Device discovery stopped.
I (4100) BT_AV: a2dp connecting to peer: ESP_SPEAKER
```

If connection is set up successfully, there will be such message:

```
I (5100) BT_AV: a2dp connected
```

Starting of audio transmission has the following notification message:

```
I (10880) BT_AV: a2dp media ready checking ...
...
I (10880) BT_AV: a2dp media ready, starting ...
...
I (11400) BT_AV: a2dp media start successfully.
```

Stop of audio transmission, and disconnection with remote device generate the following notification message:

```
I (110880) BT_AV: a2dp media stopping...
...
I (110920) BT_AV: a2dp media stopped successfully, disconnecting...
...
I (111040) BT_AV: a2dp disconnected
```

## Troubleshooting
* For current stage, the supported audio codec in ESP32 A2DP is SBC. SBC audio stream is encoded from PCM data normally formatted as 44.1kHz sampling rate, two-channel 16-bit sample data.
* The raw PCM media stream in the example is generated by a sequence of random number, so the sound played on the sink side will be piercing noise.
* As a usage limitation, ESP32 A2DP source can support at most one connection with remote A2DP sink devices. Also, A2DP source cannot be used together with A2DP sink at the same time, but can be used with other profiles such as SPP and HFP.
* Usually, the `ACL_CONN_NUM` is set to `2` but not `1` as one is used for a2dp connection and the other is used for avrcp connection.
build_app: make multi target support readable 2020-04-09 04:40:57 -04:00			`\| Supported Targets \| ESP32 \|`
			`\| ----------------- \| ----- \|`

optimize a2dp demo documents 2021-12-23 08:05:18 -05:00			`A2DP-SOURCE EXAMPLE`
component/bt: implement A2DP source 1. Modified symbol names of A2DP sink APIs include: - esp_a2d_data_cb_t --> esp_a2d_sink_data_cb_t - esp_a2d_register_data_callback --> esp_a2d_sink_register_data_callback 2017-12-25 06:39:37 -05:00			`========================`

optimize a2dp demo documents 2021-12-23 08:05:18 -05:00			`Example of A2DP audio source role`
component/bt: implement A2DP source 1. Modified symbol names of A2DP sink APIs include: - esp_a2d_data_cb_t --> esp_a2d_sink_data_cb_t - esp_a2d_register_data_callback --> esp_a2d_sink_register_data_callback 2017-12-25 06:39:37 -05:00
optimize a2dp demo documents 2021-12-23 08:05:18 -05:00			`This is the example of using Advanced Audio Distribution Profile (A2DP) APIs to transmit audio stream. Application can take advantage of this example to implement portable audio players or microphones to transmit audio stream to A2DP sink devices.`
component/bt: fix the format and add more content to A2DP source example document and source code 2018-08-16 08:08:00 -04:00
			`## How to use this example`

			`### Hardware Required`

optimize a2dp demo documents 2021-12-23 08:05:18 -05:00			`This example is able to run on any commonly available ESP32 development board, and is supposed to connect to [A2DP sink example](../a2dp_sink) in ESP-IDF.`
component/bt: fix the format and add more content to A2DP source example document and source code 2018-08-16 08:08:00 -04:00
			`### Configure the project`

			```
build system: Use CMake-based build system as default when describing commands 2019-06-22 21:54:31 -04:00			`idf.py menuconfig`
component/bt: fix the format and add more content to A2DP source example document and source code 2018-08-16 08:08:00 -04:00			```

			`* Enable Classic Bluetooth and A2DP under Component config --> Bluetooth --> Bluedroid Enable`

			`### Build and Flash`

			`Build the project and flash it to the board, then run monitor tool to view serial output.`

			```
build system: Use CMake-based build system as default when describing commands 2019-06-22 21:54:31 -04:00			`idf.py -p PORT flash monitor`
component/bt: fix the format and add more content to A2DP source example document and source code 2018-08-16 08:08:00 -04:00			```

optimize a2dp demo documents 2021-12-23 08:05:18 -05:00			`(Replace PORT with the name of the serial port to use.)`

component/bt: fix the format and add more content to A2DP source example document and source code 2018-08-16 08:08:00 -04:00			(To exit the serial monitor, type ``Ctrl-]``.)

optimize a2dp demo documents 2021-12-23 08:05:18 -05:00			`See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.`

component/bt: fix the format and add more content to A2DP source example document and source code 2018-08-16 08:08:00 -04:00			`## Example Output`

optimize a2dp demo documents 2021-12-23 08:05:18 -05:00			`For the first step, this example performs device discovery to search for a target device (A2DP sink) whose device name is "ESP_SPEAKER" and whose "Rendering" bit of its Service Class field is set in its Class of Device (COD). If a candidate target is found, the local device will initiate connection with it.`
component/bt: fix the format and add more content to A2DP source example document and source code 2018-08-16 08:08:00 -04:00
			`After connection with A2DP sink is established, the example performs the following running loop 1-2-3-4-1:`
			`1. audio transmission starts and lasts for a while`
			`2. audio transmission stops`
			`3. disconnect with target device`
			`4. reconnect to target device`

			`The example implements an event loop triggered by a periodic "heart beat" timer and events from Bluetooth protocol stack callback functions.`

			`After the local device discovers the target device and initiates connection, there will be logging message like this:`

			```
optimize a2dp demo documents 2021-12-23 08:05:18 -05:00			`I (4090) BT_AV: Found a target device, address xx:xx:xx:xx:xx:xx, name ESP_SPEAKER`
component/bt: fix the format and add more content to A2DP source example document and source code 2018-08-16 08:08:00 -04:00			`I (4090) BT_AV: Cancel device discovery ...`
			`I (4100) BT_AV: Device discovery stopped.`
			`I (4100) BT_AV: a2dp connecting to peer: ESP_SPEAKER`
			```

			`If connection is set up successfully, there will be such message:`

			```
			`I (5100) BT_AV: a2dp connected`
			```

optimize a2dp demo documents 2021-12-23 08:05:18 -05:00			`Starting of audio transmission has the following notification message:`
component/bt: fix the format and add more content to A2DP source example document and source code 2018-08-16 08:08:00 -04:00
			```
			`I (10880) BT_AV: a2dp media ready checking ...`
			`...`
			`I (10880) BT_AV: a2dp media ready, starting ...`
			`...`
			`I (11400) BT_AV: a2dp media start successfully.`
			```

			`Stop of audio transmission, and disconnection with remote device generate the following notification message:`

			```
			`I (110880) BT_AV: a2dp media stopping...`
			`...`
			`I (110920) BT_AV: a2dp media stopped successfully, disconnecting...`
			`...`
			`I (111040) BT_AV: a2dp disconnected`
			```

			`## Troubleshooting`
optimize a2dp demo documents 2021-12-23 08:05:18 -05:00			`* For current stage, the supported audio codec in ESP32 A2DP is SBC. SBC audio stream is encoded from PCM data normally formatted as 44.1kHz sampling rate, two-channel 16-bit sample data.`
component/bt: fix the format and add more content to A2DP source example document and source code 2018-08-16 08:08:00 -04:00			`* The raw PCM media stream in the example is generated by a sequence of random number, so the sound played on the sink side will be piercing noise.`
			`* As a usage limitation, ESP32 A2DP source can support at most one connection with remote A2DP sink devices. Also, A2DP source cannot be used together with A2DP sink at the same time, but can be used with other profiles such as SPP and HFP.`
optimize a2dp demo documents 2021-12-23 08:05:18 -05:00			* Usually, the `ACL_CONN_NUM` is set to `2` but not `1` as one is used for a2dp connection and the other is used for avrcp connection.