Bluetooth Service¶

[中文]

The Bluetooth service is dedicated to interface with Bluetooth devices and provides support for the following protocols:

HFP (Hands-Free Profile): remotely controlling the mobile phone by the Hands-Free device and the voice connections between them
A2DP (Advanced Audio Distribution Profile): implementing streaming of multimedia audio using a Bluetooth connection
AVRCP (Audio Video Remote Control Profile): used together with A2DP for remote control of devices such as headphones, car audio systems, or speakers

Application Example¶

Implementation of this API is demonstrated in the following example:

player/pipeline_bt_sink

Header File¶

bluetooth_service/include/bluetooth_service.h

Functions¶

esp_err_t bluetooth_service_start(bluetooth_service_cfg_t *config)¶

Initialize and start the Bluetooth service. This function can only be called for one time, and bluetooth_service_destroy must be called after use.

Return

ESP_OK
ESP_FAIL

Parameters

config: The configuration

audio_element_handle_t bluetooth_service_create_stream()¶

Create Bluetooth stream, it is valid when Bluetooth service has started. The returned audio stream compatible with existing audio streams and can be used with the Audio Pipeline.

Return: The Audio Element handle

esp_periph_handle_t bluetooth_service_create_periph()¶

Create Bluetooth peripheral, it is valid when Bluetooth service has started. The returned bluetooth peripheral compatible with existing peripherals and can be used with the ESP Peripherals.

Return: The Peripheral handle

esp_err_t periph_bluetooth_play(esp_periph_handle_t periph)¶

Send the AVRC passthrough command (PLAY) to the Bluetooth device.

Return

ESP_OK
ESP_FAIL

Parameters

[in] periph: The periph

esp_err_t periph_bluetooth_pause(esp_periph_handle_t periph)¶

Send the AVRC passthrough command (PAUSE) to the Bluetooth device.

Return

ESP_OK
ESP_FAIL

Parameters

[in] periph: The periph

esp_err_t periph_bluetooth_stop(esp_periph_handle_t periph)¶

Send the AVRC passthrough command (STOP) to the Bluetooth device.

Return

ESP_OK
ESP_FAIL

Parameters

[in] periph: The periph

esp_err_t periph_bluetooth_next(esp_periph_handle_t periph)¶

Send the AVRC passthrough command (NEXT) to the Bluetooth device.

Return

ESP_OK
ESP_FAIL

Parameters

[in] periph: The periph

esp_err_t periph_bluetooth_prev(esp_periph_handle_t periph)¶

Send the AVRC passthrough command (PREV) to the Bluetooth device.

Return

ESP_OK
ESP_FAIL

Parameters

[in] periph: The periph

esp_err_t periph_bluetooth_rewind(esp_periph_handle_t periph)¶

Send the AVRC passthrough command (REWIND) to the Bluetooth device.

Return

ESP_OK
ESP_FAIL

Parameters

[in] periph: The periph

esp_err_t periph_bluetooth_fast_forward(esp_periph_handle_t periph)¶

Send the AVRC passthrough command (FAST FORWARD) to the Bluetooth device.

Return

ESP_OK
ESP_FAIL

Parameters

[in] periph: The periph

esp_err_t periph_bluetooth_discover(esp_periph_handle_t periph)¶

Start device discovery.

Return

ESP_OK : Succeed
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_ERR_INVALID_ARG: if invalid parameters are provided
ESP_FAIL: others

Parameters

[in] periph: The periph

esp_err_t periph_bluetooth_cancel_discover(esp_periph_handle_t periph)¶

Cancel device discovery.

Return

ESP_OK : Succeed
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others

Parameters

[in] periph: The periph

esp_err_t periph_bluetooth_connect(esp_periph_handle_t periph, bluetooth_addr_t remote_bda)¶

Connect remote Device.

Return

ESP_OK : Succeed
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others

Parameters

[in] periph: The periph
[in] remote_bda: remote Bluetooth device address

esp_err_t bluetooth_service_destroy()¶

Destroy and cleanup bluetooth service, this function must be called after destroying the Bluetoth Stream and Bluetooth Peripheral created by bluetooth_service_create_stream and bluetooth_service_create_periph

Return

ESP_OK
ESP_FAIL

int periph_bluetooth_get_a2dp_sample_rate()¶

Get a2dp sample rate.

Return

sample rate

Structures¶

struct bluetooth_service_user_cb_t¶

brief Bluetooth service user callback

Public Members

esp_a2d_cb_t user_a2d_cb¶: callback for a2dp

esp_a2d_sink_data_cb_t user_a2d_sink_data_cb¶: callback for a2dp sink data

esp_a2d_source_data_cb_t user_a2d_source_data_cb¶: callback for a2dp source data

esp_avrc_ct_cb_t user_avrc_ct_cb¶: callback for avrc ct

struct bluetooth_service_cfg_t¶

brief Bluetooth service configuration

Public Members

const char *device_name¶: Bluetooth local device name

const char *remote_name¶: Bluetooth remote device name

bluetooth_service_mode_t mode¶: Bluetooth working mode

bluetooth_service_user_cb_t user_callback¶: Bluetooth user callback

Macros¶

ESP_A2DP_SAMPLE_RATE¶

BLUETOOTH_ADDR_LEN¶: brief Bluetooth address length

Type Definitions¶

typedef uint8_t bluetooth_addr_t[BLUETOOTH_ADDR_LEN]¶: brief Bluetooth device address

Enumerations¶

enum bluetooth_service_mode_t¶

brief Bluetooth service working mode

Values:

BLUETOOTH_A2DP_SINK¶: A2DP Bluetooth sink audio, ESP32 will receive audio data from other bluetooth devices

BLUETOOTH_A2DP_SOURCE¶: A2DP Bluetooth source audio, ESP32 can send audio data to other bluetooth devices