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

• components/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.

Parameters

config – The configuration

Returns

• ESP_OK

• ESP_FAIL

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.

Returns

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.

Returns

The Peripheral handle

esp_err_t periph_bluetooth_play(esp_periph_handle_t periph)

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

Parameters

periph – [in] The periph

Returns

• ESP_OK

• ESP_FAIL

esp_err_t periph_bluetooth_pause(esp_periph_handle_t periph)

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

Parameters

periph – [in] The periph

Returns

• ESP_OK

• ESP_FAIL

esp_err_t periph_bluetooth_stop(esp_periph_handle_t periph)

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

Parameters

periph – [in] The periph

Returns

• ESP_OK

• ESP_FAIL

esp_err_t periph_bluetooth_next(esp_periph_handle_t periph)

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

Parameters

periph – [in] The periph

Returns

• ESP_OK

• ESP_FAIL

esp_err_t periph_bluetooth_prev(esp_periph_handle_t periph)

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

Parameters

periph – [in] The periph

Returns

• ESP_OK

• ESP_FAIL

esp_err_t periph_bluetooth_rewind(esp_periph_handle_t periph)

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

Parameters

periph – [in] The periph

Returns

• ESP_OK

• ESP_FAIL

esp_err_t periph_bluetooth_fast_forward(esp_periph_handle_t periph)

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

Parameters

periph – [in] The periph

Returns

• ESP_OK

• ESP_FAIL

esp_err_t periph_bluetooth_discover(esp_periph_handle_t periph)

Start device discovery.

Parameters

periph – [in] The periph

Returns

• 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

esp_err_t periph_bluetooth_cancel_discover(esp_periph_handle_t periph)

Cancel device discovery.

Parameters

periph – [in] The periph

Returns

• ESP_OK : Succeed

• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

• ESP_FAIL: others

esp_err_t periph_bluetooth_connect(esp_periph_handle_t periph, bluetooth_addr_t remote_bda)

Connect remote Device.

Parameters

• periph – [in] The periph

• remote_bda – [in] remote Bluetooth device address

Returns

• ESP_OK : Succeed

• ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

• ESP_FAIL: others

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

Returns

• ESP_OK

• ESP_FAIL

int periph_bluetooth_get_a2dp_sample_rate()

Get a2dp sample rate.

Returns

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

enumerator BLUETOOTH_A2DP_SINK

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

enumerator BLUETOOTH_A2DP_SOURCE

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

Header File

• components/bluetooth_service/include/bt_keycontrol.h

Header File

• components/bluetooth_service/include/hfp_stream.h

Header File

• components/bluetooth_service/include/a2dp_stream.h

Provide feedback about this document