Bluetooth Service

This service is dedicated to interface with Bluetooth devices and provides:

  • A2DP (Advanced Audio Distribution Profile), that implements 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:

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

Structures

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

Macros

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

enum periph_bluetooth_event_id_t

brief Bluetooth peripheral event id

Values:

PERIPH_BLUETOOTH_UNKNOWN = 0

No event

PERIPH_BLUETOOTH_CONNECTED

A bluetooth device was connected

PERIPH_BLUETOOTH_DISCONNECTED

Last connection was disconnected

PERIPH_BLUETOOTH_AUDIO_STARTED

The audio session has been started

PERIPH_BLUETOOTH_AUDIO_SUSPENDED

The audio session has been suspended

PERIPH_BLUETOOTH_AUDIO_STOPPED

The audio session has been stopped