component/bt: modify comment formats for API headers

components/bt/bluedroid/api/include/esp_a2dp_api.h

@@ -4,39 +4,55 @@
 #include "esp_err.h"
 #include "esp_bt_defs.h"
 
-/* Media codec types */
+/// Media codec types supported by A2DP
-#define ESP_A2D_MCT_SBC         (0)
+#define ESP_A2D_MCT_SBC         (0)             /*!< SBC */
-#define ESP_A2D_MCT_M12         (0x01)
+#define ESP_A2D_MCT_M12         (0x01)          /*!< MPEG-1, 2 Audio */
-#define ESP_A2D_MCT_M24         (0x02)
+#define ESP_A2D_MCT_M24         (0x02)          /*!< MPEG-2, 4 AAC */
-#define ESP_A2D_MCT_ATRAC       (0x04)
+#define ESP_A2D_MCT_ATRAC       (0x04)          /*!< ATRAC family */
 #define ESP_A2D_MCT_NON_A2DP    (0xff)
 typedef uint8_t esp_a2d_mct_t;
 
-/* codec specific information element */
+/**
-#define ESP_A2D_CIE_LEN_SBC          (4)
+ * @brief Codec specific information for different codec types
-#define ESP_A2D_CIE_LEN_M12          (4)
+ */
-#define ESP_A2D_CIE_LEN_M24          (6)
-#define ESP_A2D_CIE_LEN_ATRAC        (7)
 
+/**
+ * @brief SBC codec specific information
+ */
 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
+ */
 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
+ */
 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
+ */
 typedef struct {
+#define ESP_A2D_CIE_LEN_ATRAC        (7)
     uint8_t oct[ESP_A2D_CIE_LEN_ATRAC];
 } esp_a2d_cie_atrac_t;
 
-/* media codec capabilities */
+/**
+ * @brief A2DP media codec capabilities union
+ */
 typedef struct {
-    esp_a2d_mct_t type;         /* A2DP media codec type*/
+    esp_a2d_mct_t type;         /*!< A2DP media codec type */
     union {
         esp_a2d_cie_sbc_t sbc;
         esp_a2d_cie_m12_t m12;
@@ -45,7 +61,7 @@ typedef struct {
     } cie;
 } esp_a2d_mcc_t;
 
-/* Bluetooth A2DP connection states */
+/// Bluetooth A2DP connection states
 typedef enum {
     ESP_A2D_CONNECTION_STATE_DISCONNECTED = 0,
     ESP_A2D_CONNECTION_STATE_CONNECTING,
@@ -53,19 +69,21 @@ typedef enum {
     ESP_A2D_CONNECTION_STATE_DISCONNECTING
 } esp_a2d_connection_state_t;
 
-/* Bluetooth A2DP datapath states */
+/// Bluetooth A2DP datapath states
 typedef enum {
     ESP_A2D_AUDIO_STATE_REMOTE_SUSPEND = 0,
     ESP_A2D_AUDIO_STATE_STOPPED,
     ESP_A2D_AUDIO_STATE_STARTED,
 } esp_a2d_audio_state_t;
 
+/// A2DP callback events
 typedef enum {
-    ESP_A2D_CONNECTION_STATE_EVT = 0,           /*!< connection state changed */
+    ESP_A2D_CONNECTION_STATE_EVT = 0,           /*!< connection state changed event */
-    ESP_A2D_AUDIO_STATE_EVT = 1,                /*!< audio stream state changed */
+    ESP_A2D_AUDIO_STATE_EVT = 1,                /*!< audio stream transmission state changed event */
     ESP_A2D_AUDIO_CFG_EVT = 2                   /*!< audio codec configuration received */
 } esp_a2d_cb_event_t;
 
+/// A2DP state callback parameters
 typedef union {
     /*< ESP_A2D_CONNECTION_STATE_EVT */
     struct a2d_conn_stat_param {
@@ -82,31 +100,77 @@ typedef union {
     /*< ESP_A2D_AUDIO_CFG_EVT */
     struct a2d_audio_cfg_param {
         esp_bd_addr_t remote_bda;
-        esp_a2d_mcc_t mcc;
+        esp_a2d_mcc_t mcc;                      /*!< A2DP media codec capability information */
     } audio_cfg;
 } esp_a2d_cb_param_t;
 
-typedef void (* esp_a2d_data_cb_t)(uint8_t *buf, uint32_t len);
-
 /**
- * NOTE:
+ * @brief           A2DP profile data callback function, data is ou
- * A2DP data path is handled via below function sets, between the Audio HAL
+ *                 
- *    and the Bluetooth stack.
+ * @param[in]       buf: data received and decoded to PCM format, buf points to a static memory
+ *                  and can be overwritten in later times
+ * @param[in]       len: size(in bytes) in buf
+ *
  */
+typedef void (* esp_a2d_data_cb_t)(const uint8_t *buf, uint32_t len);
+
 
 /**
- * Represents the A2DP sink interface.
+ * @brief           This function is called to register application callbacks
+ *                  with A2DP module; callbacks will provide the upstream events
+ *                  (type esp_a2d_cb_event_t) and paramters(type esp_a2d_cb_param_t)
+ *                  
+ * @param[in]       callback: A2DP sink event callback function
+ *
+ * @return
+ *                  - ESP_OK: success
+ *
  */
 esp_err_t esp_a2d_register_callback(esp_profile_cb_t callback);
 
+
+/**
+ * @brief           This function is called to register A2DP sink data output function
+ *                  currently only supports SBC codec, and the output data is PCM format
+ *                  
+ * @param[in]       callback: A2DP data callback function
+ *
+ * @return
+ *                  - ESP_OK: success
+ *
+ */
 esp_err_t esp_a2d_register_data_callback(esp_a2d_data_cb_t cb);
 
+
+/**
+ *
+ * @brief           This function is called to initialize the bluetooth A2DP sink module
+ *
+ * @return          
+ *                  - ESP_OK: success
+ *                  - ESP_FAIL: others
+ *
+ */
 esp_err_t esp_a2d_sink_init(void);
 
-esp_err_t esp_a2d_sink_connect(esp_bd_addr_t remote_bda);
-
-esp_err_t esp_a2d_sink_disconnect(esp_bd_addr_t remote_bda);
 
+/**
+ *
+ * @brief           This function is called to deinit and free the resources for A2DP sink module
+ *
+ */
 void esp_a2d_sink_deinit(void);
 
+
+/**
+ *
+ * @brief           This function is called to disconnect with the remote bluetooth device
+ *
+ * @return          
+ *                  - ESP_OK: disconnect request is sent to lower layer
+ *                  - ESP_FAIL: others
+ *
+ */
+esp_err_t esp_a2d_sink_disconnect(esp_bd_addr_t remote_bda);
+
 #endif /* __ESP_A2DP_API_H__ */

components/bt/bluedroid/api/include/esp_bt_stack_manager.h

@@ -1,14 +1,77 @@
+// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 #ifndef __ESP_BT_STACK_MANAGER_H__
 #define __ESP_BT_STACK_MANAGER_H__
 
 #include "esp_err.h"
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ *
+ * @brief           This function is called to initialize the bluetooth stack
+ *
+ * @return          
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if already initialized
+ *                  - ESP_FAIL: others
+ *
+ */
 esp_err_t esp_bt_init_stack(void);
 
+
+/**
+ *
+ * @brief           Deinit and free the resource for bluetooth
+ *
+ * @return          
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if not initailized yet
+ *
+ */
 esp_err_t esp_bt_deinit_stack(void);
 
+
+/**
+ *
+ * @brief           Enable bluetooth, must after esp_bt_init_stack()
+ *
+ * @return          
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if not initialized yet or already enabled
+ *                  - ESP_FAIL: others
+ *
+ */
 esp_err_t esp_bt_enable_stack(void);
 
+
+/**
+ * @brief           Disable bluetooth, must prior to esp_deinit_stack()
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if not initialized yet or already enabled
+ *                  - ESP_FAIL: others
+ *
+ */
 esp_err_t esp_bt_disable_stack(void);
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif /* __ESP_BT_STACK_MANAGER_H__ */

components/bt/bluedroid/api/include/esp_gap_bt_api.h

@@ -16,18 +16,45 @@
 #define __ESP_GAP_BT_API_H__
 
 #include <stdint.h>
-
 #include "esp_err.h"
 #include "esp_bt_defs.h"
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// Discoverability and Connectability mode
 typedef enum {
-    BT_SCAN_MODE_NONE = 0,
+    BT_SCAN_MODE_NONE = 0,                      /*!< Neither discoverable nor connectable */
-    BT_SCAN_MODE_CONNECTABLE,
+    BT_SCAN_MODE_CONNECTABLE,                   /*!< Connectable but not discoverable */
-    BT_SCAN_MODE_CONNECTABLE_DISCOVERABLE
+    BT_SCAN_MODE_CONNECTABLE_DISCOVERABLE       /*!< both discoverable and connectaable */
 } bt_scan_mode_t;
 
+/**
+ * @brief           Set discoverability and connectability mode for legacy bluetooth
+ *
+ * @param[in]       mode: one of the enums of bt_scan_mode_t
+ *
+ * @return
+ *                  - ESP_OK : Succeed
+ *                  - ESP_ERR_INVALID_ARG: if argument invalid
+ */
 esp_err_t esp_bt_gap_set_scan_mode(bt_scan_mode_t mode);
 
+
+/**
+ * @brief           Set bluetooth device name 
+ *
+ * @param[in]       name: device name to be set, will be truncated if more than 32 characters
+ *
+ * @return
+ *                  - ESP_OK : Succeed
+ *                  - ESP_ERR_INVALID_ARG: if name is NULL pointer or empty string
+ */
 esp_err_t esp_bt_gap_set_device_name(const char *name);
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif /* __ESP_GAP_BT_API_H__ */

components/bt/bluedroid/btif/btif_media_task.c

@@ -823,7 +823,7 @@ static void btif_media_task_handle_inc_media(tBT_SBC_HDR *p_msg)
     // LOG_ERROR("pre-send: %d\n", availPcmBytes);
 
     // UIPC_Send(UIPC_CH_ID_AV_AUDIO, 0, (UINT8 *)pcmData, (2 * sizeof(pcmData) - availPcmBytes));
-    BTIF_A2D_DATA_CB_TO_APP((uint8_t *)pcmData, (2 * sizeof(pcmData) - availPcmBytes));
+    BTIF_A2D_DATA_CB_TO_APP((const uint8_t *)pcmData, (2 * sizeof(pcmData) - availPcmBytes));
 
 }
 #endif

components/bt/bluedroid/btif/stack_manager.c

@@ -75,6 +75,11 @@ static bt_status_t event_start_up_stack(void)
 
 static bt_status_t event_shut_down_stack(void)
 {
+    if (!stack_is_initialized) {
+        LOG_DEBUG("%s stack not initialized yet.\n", __func__);
+        return BT_STATUS_NOT_READY;
+    }
+	
     if (!stack_is_running) {
         LOG_DEBUG("%s stack is already brought down.\n", __func__);
         return BT_STATUS_DONE;
@@ -152,7 +157,9 @@ esp_err_t esp_bt_disable_stack(void)
     status = event_shut_down_stack();
     switch (status) {
     case BT_STATUS_SUCCESS: return ESP_OK;
-    case BT_STATUS_DONE: return ESP_ERR_INVALID_STATE;
+    case BT_STATUS_NOT_READY:
+    case BT_STATUS_DONE:
+        return ESP_ERR_INVALID_STATE;
     default: return ESP_FAIL;
     }
 }