alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

component/bt: clean up the API header and generate documentation files

Browse Source
This commit is contained in:
wangmengyang 2017-03-18 14:55:31 +08:00
parent e132e95476
commit 8ec94418de
13 changed files with 360 additions and 197 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
components/bt/bluedroid/api/include/esp_a2dp_api.h
View File

@ -28,52 +28,23 @@ extern "C" {
#define ESP_A2D_MCT_M24 (0x02) /*!< MPEG-2, 4 AAC */
#define ESP_A2D_MCT_ATRAC (0x04) /*!< ATRAC family */
#define ESP_A2D_MCT_NON_A2DP (0xff)
typedef uint8_t esp_a2d_mct_t;
/**
* @brief SBC codec specific information as defined in A2DP spec
*/
typedef struct {
#define ESP_A2D_CIE_LEN_SBC (4)
uint8_t oct[ESP_A2D_CIE_LEN_SBC];
} esp_a2d_cie_sbc_t;
/**
* @brief MPEG-1,2 Audio codec specific information as defined in A2DP spec
*/
typedef struct {
#define ESP_A2D_CIE_LEN_M12 (4)
uint8_t oct[ESP_A2D_CIE_LEN_M12];
} esp_a2d_cie_m12_t;
/**
* @brief MPEG-2,4 AAC codec specific information as defined in A2DP spec
*/
typedef struct {
#define ESP_A2D_CIE_LEN_M24 (6)
uint8_t oct[ESP_A2D_CIE_LEN_M24];
} esp_a2d_cie_m24_t;
/**
* @brief ATRAC family codec specific information as defined in A2DP spec
*/
typedef struct {
#define ESP_A2D_CIE_LEN_ATRAC (7)
uint8_t oct[ESP_A2D_CIE_LEN_ATRAC];
} esp_a2d_cie_atrac_t;
/**
* @brief A2DP media codec capabilities union
*/
/// A2DP media codec capabilities union
typedef struct {
esp_a2d_mct_t type; /*!< A2DP media codec type */
#define ESP_A2D_CIE_LEN_SBC (4)
#define ESP_A2D_CIE_LEN_M12 (4)
#define ESP_A2D_CIE_LEN_M24 (6)
#define ESP_A2D_CIE_LEN_ATRAC (7)
union {
esp_a2d_cie_sbc_t sbc;
esp_a2d_cie_m12_t m12;
esp_a2d_cie_m24_t m24;
esp_a2d_cie_atrac_t atrac;
} cie;
} esp_a2d_mcc_t;
uint8_t sbc[ESP_A2D_CIE_LEN_SBC];
uint8_t m12[ESP_A2D_CIE_LEN_M12];
uint8_t m24[ESP_A2D_CIE_LEN_M24];
uint8_t atrac[ESP_A2D_CIE_LEN_ATRAC];
} cie; /*!< A2DP codec information element */
} __attribute__((packed)) esp_a2d_mcc_t;
/// Bluetooth A2DP connection states
typedef enum {
@ -105,24 +76,30 @@ typedef enum {
/// A2DP state callback parameters
typedef union {
/*< ESP_A2D_CONNECTION_STATE_EVT */
/**
* @brief ESP_A2D_CONNECTION_STATE_EVT
*/
struct a2d_conn_stat_param {
esp_a2d_connection_state_t state; /*!< one of values from esp_a2d_connection_state_t */
esp_bd_addr_t remote_bda; /*!< remote bluetooth device address */
esp_a2d_disc_rsn_t disc_rsn; /*!< reason of disconnection for "DISCONNECTED" */
} conn_stat;
} conn_stat; /*!< A2DP connection status */
/*< ESP_A2D_AUDIO_STATE_EVT */
/**
* @brief ESP_A2D_AUDIO_STATE_EVT
*/
struct a2d_audio_stat_param {
esp_a2d_audio_state_t state; /*!< one of the values from esp_a2d_audio_state_t */
esp_bd_addr_t remote_bda; /*!< remote bluetooth device address */
} audio_stat;
} audio_stat; /*!< audio stream playing state */
/*< ESP_A2D_AUDIO_CFG_EVT */
/**
* @brief ESP_A2D_AUDIO_CFG_EVT
*/
struct a2d_audio_cfg_param {
esp_bd_addr_t remote_bda; /*!< remote bluetooth device address */
esp_a2d_mcc_t mcc; /*!< A2DP media codec capability information */
} audio_cfg;
} audio_cfg; /*!< media codec configuration infomation */
} esp_a2d_cb_param_t;
/**

26
components/bt/bluedroid/api/include/esp_avrc_api.h
View File

@ -35,19 +35,19 @@ typedef enum {
} esp_avrc_features_t;
/// AVRC passthrough command code
enum {
typedef enum {
ESP_AVRC_PT_CMD_PLAY = 0x44, /*!< play */
ESP_AVRC_PT_CMD_STOP = 0x45, /*!< stop */
ESP_AVRC_PT_CMD_PAUSE = 0x46, /*!< pause */
ESP_AVRC_PT_CMD_FORWARD = 0x4B, /*!< forward */
ESP_AVRC_PT_CMD_BACKWARD = 0x4C /*!< backward */
};
} esp_avrc_pt_cmd_t;
/// AVRC passthrough command state
enum {
typedef enum {
ESP_AVRC_PT_CMD_STATE_PRESSED = 0, /*!< key pressed */
ESP_AVRC_PT_CMD_STATE_RELEASED = 1 /*!< key released */
};
} esp_avrc_pt_cmd_state_t;
/// AVRC Controller callback events
typedef enum {
@ -58,19 +58,23 @@ typedef enum {
/// AVRC controller callback parameters
typedef union {
/*< ESP_AVRC_CT_CONNECTION_STATE_EVT */
/**
* @brief ESP_AVRC_CT_CONNECTION_STATE_EVT
*/
struct avrc_ct_conn_stat_param {
bool connected;
uint32_t feat_mask;
esp_bd_addr_t remote_bda;
} conn_stat;
bool connected; /*!< whether AVRC connection is set up */
uint32_t feat_mask; /*!< AVRC feature mask of remote device */
esp_bd_addr_t remote_bda; /*!< remote bluetooth device address */
} conn_stat; /*!< AVRC connection status */
/*< ESP_AVRC_CT_PASSTHROUGH_RSP_EVT */
/**
* @brief ESP_AVRC_CT_PASSTHROUGH_RSP_EVT
*/
struct avrc_ct_psth_rsp_param {
uint8_t tl; /*!< transaction label, 0 to 15 */
uint8_t key_code; /*!< passthrough command code */
uint8_t key_state; /*!< 0 for PRESSED, 1 for RELEASED */
} psth_rsp;
} psth_rsp; /*!< passthrough command response */
} esp_avrc_ct_cb_param_t;

4
components/bt/bluedroid/btc/profile/std/a2dp/btc_avk.c
View File

@ -905,7 +905,7 @@ static void bte_av_media_callback(tBTA_AV_EVT event, tBTA_AV_MEDIA *p_data)
memset(&arg, 0, sizeof(btc_av_args_t));
arg.mcc.type = ESP_A2D_MCT_SBC;
memcpy(&(arg.mcc.cie), (uint8_t *)p_data + 3, ESP_A2D_CIE_LEN_SBC);
memcpy(arg.mcc.cie.sbc, (uint8_t *)p_data + 3, ESP_A2D_CIE_LEN_SBC);
btc_transfer_context(&msg, &arg, sizeof(btc_av_args_t), NULL);
} else {
LOG_ERROR("ERROR dump_codec_info A2D_ParsSbcInfo fail:%d\n", a2d_status);
@ -982,7 +982,7 @@ static bt_status_t connect_int(bt_bdaddr_t *bd_addr, uint16_t uuid)
return BT_STATUS_SUCCESS;
}
bt_status_t btc_a2d_sink_connect(bt_bdaddr_t* remote_bda)
bt_status_t btc_a2d_sink_connect(bt_bdaddr_t *remote_bda)
{
LOG_DEBUG("%s\n", __FUNCTION__);
CHECK_BTAV_INIT();

3
components/bt/bluedroid/btc/profile/std/a2dp/btc_media_task.c
View File

@ -231,8 +231,9 @@ static void btc_media_data_post(void)
static void btc_media_ctrl_handler(BtTaskEvt_t *e)
{
if (e == NULL)
if (e == NULL) {
return;
}
switch (e->sig) {
case SIG_MEDIA_TASK_CMD_READY:
fixed_queue_process(btc_media_cmd_msg_queue);

84
components/bt/bluedroid/btc/profile/std/avrc/btc_avrc.c
View File

@ -60,8 +60,7 @@ typedef struct {
UINT8 label;
} btc_rc_reg_notifications_t;
typedef struct
{
typedef struct {
UINT8 label;
UINT8 ctype;
BOOLEAN is_rsp_pending;
@ -86,8 +85,7 @@ typedef struct {
UINT8 handle;
} rc_transaction_t;
typedef struct
{
typedef struct {
pthread_mutex_t lbllock;
rc_transaction_t transaction[MAX_TRANSACTIONS_PER_SESSION];
} rc_device_t;
@ -129,19 +127,16 @@ static void handle_rc_features(void)
// the following bit here:
// btc_rc_vb.rc_features &= ~BTA_AV_FEAT_ADV_CTRL;
if (btc_rc_vb.rc_features & BTA_AV_FEAT_BROWSE)
{
if (btc_rc_vb.rc_features & BTA_AV_FEAT_BROWSE) {
rc_features |= BTRC_FEAT_BROWSE;
}
if ( (btc_rc_vb.rc_features & BTA_AV_FEAT_ADV_CTRL) &&
(btc_rc_vb.rc_features & BTA_AV_FEAT_RCTG))
{
(btc_rc_vb.rc_features & BTA_AV_FEAT_RCTG)) {
rc_features |= BTRC_FEAT_ABSOLUTE_VOLUME;
}
if (btc_rc_vb.rc_features & BTA_AV_FEAT_METADATA)
{
if (btc_rc_vb.rc_features & BTA_AV_FEAT_METADATA) {
rc_features |= BTRC_FEAT_METADATA;
}
@ -164,16 +159,13 @@ static void handle_rc_connect (tBTA_AV_RC_OPEN *p_rc_open)
bt_bdaddr_t rc_addr;
#endif
if(p_rc_open->status == BTA_AV_SUCCESS)
{
if (p_rc_open->status == BTA_AV_SUCCESS) {
//check if already some RC is connected
if (btc_rc_vb.rc_connected)
{
if (btc_rc_vb.rc_connected) {
LOG_ERROR("Got RC OPEN in connected state, Connected RC: %d \
and Current RC: %d", btc_rc_vb.rc_handle,p_rc_open->rc_handle );
and Current RC: %d", btc_rc_vb.rc_handle, p_rc_open->rc_handle );
if ((btc_rc_vb.rc_handle != p_rc_open->rc_handle)
&& (bdcmp(btc_rc_vb.rc_addr, p_rc_open->peer_addr)))
{
&& (bdcmp(btc_rc_vb.rc_addr, p_rc_open->peer_addr))) {
LOG_DEBUG("Got RC connected for some other handle");
BTA_AvCloseRc(p_rc_open->rc_handle);
return;
@ -188,8 +180,9 @@ static void handle_rc_connect (tBTA_AV_RC_OPEN *p_rc_open)
btc_rc_vb.rc_handle = p_rc_open->rc_handle;
/* on locally initiated connection we will get remote features as part of connect */
if (btc_rc_vb.rc_features != 0)
if (btc_rc_vb.rc_features != 0) {
handle_rc_features();
}
#if (AVRC_CTLR_INCLUDED == TRUE)
bdcpy(rc_addr.address, btc_rc_vb.rc_addr);
/* report connection state if device is AVRCP target */
@ -202,9 +195,7 @@ static void handle_rc_connect (tBTA_AV_RC_OPEN *p_rc_open)
btc_avrc_ct_cb_to_app(ESP_AVRC_CT_CONNECTION_STATE_EVT, &param);
}
#endif
}
else
{
} else {
LOG_ERROR("%s Connect failed with error code: %d",
__FUNCTION__, p_rc_open->status);
btc_rc_vb.rc_connected = FALSE;
@ -227,8 +218,7 @@ static void handle_rc_disconnect (tBTA_AV_RC_CLOSE *p_rc_close)
#endif
LOG_DEBUG("%s: rc_handle: %d", __FUNCTION__, p_rc_close->rc_handle);
if ((p_rc_close->rc_handle != btc_rc_vb.rc_handle)
&& (bdcmp(btc_rc_vb.rc_addr, p_rc_close->peer_addr)))
{
&& (bdcmp(btc_rc_vb.rc_addr, p_rc_close->peer_addr))) {
LOG_ERROR("Got disconnect of unknown device");
return;
}
@ -241,8 +231,8 @@ static void handle_rc_disconnect (tBTA_AV_RC_CLOSE *p_rc_close)
features = btc_rc_vb.rc_features;
#endif
btc_rc_vb.rc_features = 0;
btc_rc_vb.rc_vol_label=MAX_LABEL;
btc_rc_vb.rc_volume=MAX_VOLUME;
btc_rc_vb.rc_vol_label = MAX_LABEL;
btc_rc_vb.rc_volume = MAX_VOLUME;
#if (AVRC_CTLR_INCLUDED == TRUE)
bdcpy(rc_addr.address, btc_rc_vb.rc_addr);
#endif
@ -271,16 +261,12 @@ static void handle_rc_passthrough_rsp ( tBTA_AV_REMOTE_RSP *p_remote_rsp)
{
#if (AVRC_CTLR_INCLUDED == TRUE)
const char *status;
if (btc_rc_vb.rc_features & BTA_AV_FEAT_RCTG)
{
if (btc_rc_vb.rc_features & BTA_AV_FEAT_RCTG) {
int key_state;
if (p_remote_rsp->key_state == AVRC_STATE_RELEASE)
{
if (p_remote_rsp->key_state == AVRC_STATE_RELEASE) {
status = "released";
key_state = 1;
}
else
{
} else {
status = "pressed";
key_state = 0;
}
@ -295,9 +281,7 @@ static void handle_rc_passthrough_rsp ( tBTA_AV_REMOTE_RSP *p_remote_rsp)
param.psth_rsp.key_state = key_state;
btc_avrc_ct_cb_to_app(ESP_AVRC_CT_PASSTHROUGH_RSP_EVT, &param);
} while (0);
}
else
{
} else {
LOG_ERROR("%s DUT does not support AVRCP controller role", __FUNCTION__);
}
#else
@ -316,30 +300,25 @@ static void handle_rc_passthrough_rsp ( tBTA_AV_REMOTE_RSP *p_remote_rsp)
void btc_rc_handler(tBTA_AV_EVT event, tBTA_AV *p_data)
{
LOG_DEBUG ("%s event:%s", __FUNCTION__, dump_rc_event(event));
switch (event)
{
case BTA_AV_RC_OPEN_EVT:
{
switch (event) {
case BTA_AV_RC_OPEN_EVT: {
LOG_DEBUG("Peer_features:%x", p_data->rc_open.peer_features);
handle_rc_connect( &(p_data->rc_open) );
}break;
} break;
case BTA_AV_RC_CLOSE_EVT:
{
case BTA_AV_RC_CLOSE_EVT: {
handle_rc_disconnect( &(p_data->rc_close) );
}break;
} break;
#if (AVRC_CTLR_INCLUDED == TRUE)
case BTA_AV_REMOTE_RSP_EVT:
{
case BTA_AV_REMOTE_RSP_EVT: {
LOG_DEBUG("RSP: rc_id:0x%x key_state:%d", p_data->remote_rsp.rc_id,
p_data->remote_rsp.key_state);
handle_rc_passthrough_rsp( (&p_data->remote_rsp) );
}
break;
#endif
case BTA_AV_RC_FEAT_EVT:
{
case BTA_AV_RC_FEAT_EVT: {
LOG_DEBUG("Peer_features:%x", p_data->rc_feat.peer_features);
btc_rc_vb.rc_features = p_data->rc_feat.peer_features;
handle_rc_features();
@ -388,8 +367,8 @@ static void btc_avrc_ct_init(void)
LOG_DEBUG("## %s ##", __FUNCTION__);
memset (&btc_rc_vb, 0, sizeof(btc_rc_vb));
btc_rc_vb.rc_vol_label=MAX_LABEL;
btc_rc_vb.rc_volume=MAX_VOLUME;
btc_rc_vb.rc_vol_label = MAX_LABEL;
btc_rc_vb.rc_volume = MAX_VOLUME;
}
@ -421,15 +400,12 @@ static bt_status_t btc_avrc_ct_send_passthrough_cmd(uint8_t tl, uint8_t key_code
CHECK_ESP_RC_CONNECTED;
LOG_DEBUG("%s: key-code: %d, key-state: %d", __FUNCTION__,
key_code, key_state);
if (btc_rc_vb.rc_features & BTA_AV_FEAT_RCTG)
{
if (btc_rc_vb.rc_features & BTA_AV_FEAT_RCTG) {
BTA_AvRemoteCmd(btc_rc_vb.rc_handle, tl,
(tBTA_AV_RC)key_code, (tBTA_AV_STATE)key_state);
status = BT_STATUS_SUCCESS;
LOG_INFO("%s: succesfully sent passthrough command to BTA", __FUNCTION__);
}
else
{
} else {
status = BT_STATUS_FAIL;
LOG_DEBUG("%s: feature not supported", __FUNCTION__);
}

2
docs/api/bluetooth/bt_le.rst
View File

@ -1,4 +1,4 @@
BT COMMON
BT LE
=========
.. toctree::

9
docs/api/bluetooth/classic_bt.rst Normal file
View File

@ -0,0 +1,9 @@
CLASSIC BT
==========
.. toctree::
:caption: Classic BT
BT GAP <esp_gap_bt>
BT A2DP <esp_a2dp>
BT AVRC <esp_avrc>

82
docs/api/bluetooth/esp_a2dp.rst Normal file
View File

@ -0,0 +1,82 @@
Bluetooth A2DP API
==================
Overview
--------
`Instructions`_
.. _Instructions: ../template.html
Application Example
-------------------
Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following examples:
:example:`bluetooth/a2dp_sink`
This is a A2DP sink client demo. This demo can be discovered and connected by A2DP source device and receive the audio stream from remote device.
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/bluedroid/api/include/esp_a2dp_api.h`
Macros
^^^^^^
.. doxygendefine:: ESP_A2D_MCT_SBC
.. doxygendefine:: ESP_A2D_MCT_M12
.. doxygendefine:: ESP_A2D_MCT_M24
.. doxygendefine:: ESP_A2D_MCT_ATRAC
.. doxygendefine:: ESP_A2D_MCT_NON_A2DP
.. doxygendefine:: ESP_A2D_CIE_LEN_SBC
.. doxygendefine:: ESP_A2D_CIE_LEN_M12
.. doxygendefine:: ESP_A2D_CIE_LEN_M24
.. doxygendefine:: ESP_A2D_CIE_LEN_ATRAC
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: esp_a2d_mct_t
.. doxygentypedef:: esp_a2d_cb_t
.. doxygentypedef:: esp_a2d_data_cb_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_a2d_connection_state_t
.. doxygenenum:: esp_a2d_disc_rsn_t
.. doxygenenum:: esp_a2d_audio_state_t
.. doxygenenum:: esp_a2d_cb_event_t
Structures
^^^^^^^^^^
.. doxygenstruct:: esp_a2d_cb_param_t
:members:
.. doxygenstruct:: esp_a2d_cb_param_t::a2d_conn_stat_param
:members:
.. doxygenstruct:: esp_a2d_cb_param_t::a2d_audio_stat_param
:members:
.. doxygenstruct:: esp_a2d_cb_param_t::a2d_audio_cfg_param
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: esp_a2d_register_callback
.. doxygenfunction:: esp_a2d_register_data_callback
.. doxygenfunction:: esp_a2d_sink_init
.. doxygenfunction:: esp_a2d_sink_deinit
.. doxygenfunction:: esp_a2d_sink_connect
.. doxygenfunction:: esp_a2d_sink_disconnect

65
docs/api/bluetooth/esp_avrc.rst Normal file
View File

@ -0,0 +1,65 @@
BT AVRCP APIs
=============
Overview
--------
Bluetooth AVRCP reference APIs.
`Instructions`_
Application Example
-------------------
`Instructions`_
.. _Instructions: ../template.html
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/bluedroid/api/include/esp_avrc_api.h`
Macros
^^^^^^
Type Definitions
^^^^^^^^^^^^^^^^
.. doxygentypedef:: esp_avrc_ct_cb_t
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_avrc_features_t
.. doxygenenum:: esp_avrc_pt_cmd_t
.. doxygenenum:: esp_avrc_pt_cmd_state_t
.. doxygenenum:: esp_avrc_ct_cb_event_t
Structures
^^^^^^^^^^
.. doxygenstruct:: esp_avrc_ct_cb_param_t
:members:
.. doxygenstruct:: esp_avrc_ct_cb_param_t::avrc_ct_conn_stat_param
:members:
.. doxygenstruct:: esp_avrc_ct_cb_param_t::avrc_ct_psth_rsp_param
:members:
Functions
^^^^^^^^^
.. doxygenfunction:: esp_avrc_ct_register_callback
.. doxygenfunction:: esp_avrc_ct_init
.. doxygenfunction:: esp_avrc_ct_deinit
.. doxygenfunction:: esp_avrc_ct_send_passthrough_cmd

1
docs/api/bluetooth/esp_bt_device.rst
View File

@ -45,4 +45,5 @@ Functions
^^^^^^^^^
.. doxygenfunction:: esp_bt_dev_get_address
.. doxygenfunction:: esp_bt_dev_set_device_name

47
docs/api/bluetooth/esp_gap_bt.rst Normal file
View File

@ -0,0 +1,47 @@
CLASSIC BLUETOOTH GAP API
=========================
Overview
--------
`Instructions`_
Application Example
-------------------
`Instructions`_
.. _Instructions: ../template.html
API Reference
-------------
Header Files
^^^^^^^^^^^^
* :component_file:`bt/bluedroid/api/include/esp_gap_bt_api.h`
Macros
^^^^^^
Type Definitions
^^^^^^^^^^^^^^^^
Enumerations
^^^^^^^^^^^^
.. doxygenenum:: esp_bt_scan_mode_t
Structures
^^^^^^^^^^
Functions
^^^^^^^^^
.. doxygenfunction:: esp_bt_gap_set_scan_mode

1
docs/api/bluetooth/index.rst
View File

@ -7,6 +7,7 @@ Bluetooth API
Bluetooth Controller && VHCI <controller_vhci>
Bluetooth Common <bt_common>
Bluetooth LE <bt_le>
Bluetooth Classic BT <classic_bt>
Example code for this API section is provided in :example:`bluetooth` directory of ESP-IDF examples.