From 8cb5be9ba2748f0374b38d766c798f980314bb6a Mon Sep 17 00:00:00 2001 From: Mayank Tyagi Date: Tue, 17 Mar 2026 15:43:11 +0530 Subject: [PATCH] feat(nimble): ADD BLE HCI logging support for ESP Insights --- components/bt/CMakeLists.txt | 6 ++ components/bt/Kconfig | 6 ++ components/bt/common/CMakeLists.txt | 1 + components/bt/common/hci_log/bt_hci_log.c | 10 +++ .../bt/common/hci_log/bt_hci_log_insights.c | 90 +++++++++++++++++++ .../hci_log/include/hci_log/bt_hci_log.h | 11 +++ .../bt/common/include/bt_ble_insights.h | 21 +++++ components/bt/common/include/bt_common.h | 17 +++- components/bt/common/include/bt_user_config.h | 10 ++- .../bt/host/bluedroid/api/esp_bluedroid_hci.c | 9 +- components/bt/host/bluedroid/hci/hci_hal_h4.c | 9 +- .../host/nimble/esp-hci/src/esp_nimble_hci.c | 24 +++-- components/bt/host/nimble/nimble | 2 +- .../host/nimble/port/include/esp_nimble_cfg.h | 8 ++ 14 files changed, 209 insertions(+), 15 deletions(-) create mode 100644 components/bt/common/hci_log/bt_hci_log_insights.c create mode 100644 components/bt/common/include/bt_ble_insights.h diff --git a/components/bt/CMakeLists.txt b/components/bt/CMakeLists.txt index 348af5ef910..d27259fd77b 100644 --- a/components/bt/CMakeLists.txt +++ b/components/bt/CMakeLists.txt @@ -98,6 +98,12 @@ idf_component_register(SRCS "${srcs}" PRIV_REQUIRES "${bt_priv_requires}" LDFRAGMENTS "${ldscripts}") +idf_component_get_property(bt_component_type bt COMPONENT_TYPE) +if(bt_component_type STREQUAL "LIBRARY") + idf_component_optional_requires(PRIVATE ble_insights) +else() + idf_component_optional_requires(INTERFACE ble_insights) +endif() if(CONFIG_BT_ENABLED) target_compile_options(${COMPONENT_LIB} PRIVATE -Wno-implicit-fallthrough -Wno-unused-const-variable) diff --git a/components/bt/Kconfig b/components/bt/Kconfig index 37d9f32f30f..5e74f5ea6c4 100644 --- a/components/bt/Kconfig +++ b/components/bt/Kconfig @@ -119,6 +119,12 @@ menu "Bluetooth" source "$IDF_PATH/components/bt/esp_ble_audio/Kconfig.in" endmenu + config BT_HCI_LOG_INSIGHTS_ENABLE + depends on BT_HCI_LOG_DEBUG_EN + bool "Enable Insights for HCI LOGS BT Stack" + help + Enable this to allow the BT stack to send diagnostic events. + endmenu menuconfig BLE_MESH diff --git a/components/bt/common/CMakeLists.txt b/components/bt/common/CMakeLists.txt index d994bf62413..062a4498da8 100644 --- a/components/bt/common/CMakeLists.txt +++ b/components/bt/common/CMakeLists.txt @@ -94,6 +94,7 @@ list(APPEND bt_common_srcs "${CMAKE_CURRENT_LIST_DIR}/api/esp_blufi_api.c" "${CMAKE_CURRENT_LIST_DIR}/hci_log/bt_hci_log.c" "${CMAKE_CURRENT_LIST_DIR}/btc/core/btc_manage.c" + "${CMAKE_CURRENT_LIST_DIR}/hci_log/bt_hci_log_insights.c" "${CMAKE_CURRENT_LIST_DIR}/btc/core/btc_task.c" "${CMAKE_CURRENT_LIST_DIR}/btc/profile/esp/blufi/blufi_prf.c" "${CMAKE_CURRENT_LIST_DIR}/btc/profile/esp/blufi/blufi_protocol.c" diff --git a/components/bt/common/hci_log/bt_hci_log.c b/components/bt/common/hci_log/bt_hci_log.c index 5840adab856..317d4b1718c 100644 --- a/components/bt/common/hci_log/bt_hci_log.c +++ b/components/bt/common/hci_log/bt_hci_log.c @@ -40,6 +40,16 @@ static const char s_hex_to_char_mapping[16] = { static bt_hci_log_t g_bt_hci_log_data_ctl = {0}; static bt_hci_log_t g_bt_hci_log_adv_ctl = {0}; +uint8_t bt_hci_log_h4_type_to_data_type(uint8_t h4_type) +{ + switch (h4_type) { + case 0x05: + return HCI_LOG_DATA_TYPE_ISO_DATA; + default: + return h4_type; + } +} + esp_err_t bt_hci_log_init(void) { uint8_t *g_bt_hci_log_data_buffer = NULL; diff --git a/components/bt/common/hci_log/bt_hci_log_insights.c b/components/bt/common/hci_log/bt_hci_log_insights.c new file mode 100644 index 00000000000..8ab832efa4f --- /dev/null +++ b/components/bt/common/hci_log/bt_hci_log_insights.c @@ -0,0 +1,90 @@ +/* + * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Apache-2.0 + */ + +#include +#include +#include + +#include "freertos/FreeRTOS.h" +#include "freertos/portmacro.h" + +#include "esp_timer.h" +#include "bt_ble_insights.h" +#include "bt_common.h" +#include "hci_log/bt_hci_log.h" + +#if (BT_HCI_LOG_INCLUDED == TRUE) && BT_HCI_INSIGHTS_INCLUDED +static uint8_t s_hci_log_seq_num = 0; +static portMUX_TYPE s_hci_log_mux = portMUX_INITIALIZER_UNLOCKED; + +#define HCI_LOG_INSIGHTS_LINE_SIZE 128U +#define HCI_LOG_INSIGHTS_TS_LEN 8U + +static const char *bt_hci_log_insights_label(uint8_t data_type) +{ + switch (data_type) { + case HCI_LOG_DATA_TYPE_COMMAND: + return "C"; + case HCI_LOG_DATA_TYPE_H2C_ACL: + return "H"; + case HCI_LOG_DATA_TYPE_SCO: + return "S"; + case HCI_LOG_DATA_TYPE_EVENT: + return "E"; + case HCI_LOG_DATA_TYPE_ADV: + return "ADV"; + case HCI_LOG_DATA_TYPE_C2H_ACL: + return "D"; + case HCI_LOG_DATA_TYPE_ISO_DATA: + return "I"; + default: + return NULL; + } +} + +void bt_hci_log_record_insights(uint8_t data_type, const uint8_t *data, uint16_t data_len) +{ + const char *label = bt_hci_log_insights_label(data_type); + char line[HCI_LOG_INSIGHTS_LINE_SIZE]; + uint8_t ts_bytes[HCI_LOG_INSIGHTS_TS_LEN]; + uint64_t timestamp; + uint8_t seq_num; + int offset; + + if (!BT_BLE_INSIGHTS_AVAILABLE || label == NULL || data == NULL || data_len == 0) { + return; + } + + portENTER_CRITICAL(&s_hci_log_mux); + seq_num = ++s_hci_log_seq_num; + portEXIT_CRITICAL(&s_hci_log_mux); + + timestamp = esp_timer_get_time(); + memcpy(ts_bytes, ×tamp, sizeof(ts_bytes)); + + offset = snprintf(line, sizeof(line), "%02x %s:", (unsigned int)seq_num, label); + if (offset < 0 || (size_t)offset >= sizeof(line) - 1) { + return; + } + + for (size_t i = 0; i < sizeof(ts_bytes) && offset <= (int)sizeof(line) - 3; i++) { + offset += snprintf(&line[offset], sizeof(line) - offset, "%02x", ts_bytes[i]); + } + + if (offset < 0 || (size_t)offset >= sizeof(line) - 1) { + return; + } + + line[offset++] = ' '; + line[offset] = '\0'; + + for (uint16_t i = 0; i < data_len && offset <= (int)sizeof(line) - 3; i++) { + offset += snprintf(&line[offset], sizeof(line) - offset, "%02X", data[i]); + } + + ble_insights_log(line); +} +#endif diff --git a/components/bt/common/hci_log/include/hci_log/bt_hci_log.h b/components/bt/common/hci_log/include/hci_log/bt_hci_log.h index 4646862194c..74024134c5a 100644 --- a/components/bt/common/hci_log/include/hci_log/bt_hci_log.h +++ b/components/bt/common/hci_log/include/hci_log/bt_hci_log.h @@ -102,6 +102,17 @@ esp_err_t bt_hci_log_record_hci_data(uint8_t data_type, uint8_t *data, uint16_t */ esp_err_t bt_hci_log_record_hci_adv(uint8_t data_type, uint8_t *data, uint8_t data_len); +/** + * + * @brief Convert HCI H4 packet type to HCI log data type. + * + * @param h4_type : HCI H4 packet type byte + * + * @return corresponding HCI log data type + * + */ +uint8_t bt_hci_log_h4_type_to_data_type(uint8_t h4_type); + #ifdef __cplusplus } #endif diff --git a/components/bt/common/include/bt_ble_insights.h b/components/bt/common/include/bt_ble_insights.h new file mode 100644 index 00000000000..c433eed982e --- /dev/null +++ b/components/bt/common/include/bt_ble_insights.h @@ -0,0 +1,21 @@ +/* + * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Apache-2.0 + */ + +#ifndef __BT_BLE_INSIGHTS_H__ +#define __BT_BLE_INSIGHTS_H__ + +#if __has_include("ble_insights.h") +#include "ble_insights.h" +#define BT_BLE_INSIGHTS_AVAILABLE 1 +#else +#define BT_BLE_INSIGHTS_AVAILABLE 0 +static inline void ble_insights_log(const char *log) +{ + (void)log; +} +#endif + +#endif /* __BT_BLE_INSIGHTS_H__ */ diff --git a/components/bt/common/include/bt_common.h b/components/bt/common/include/bt_common.h index 372ea68e7e9..343600f36e6 100644 --- a/components/bt/common/include/bt_common.h +++ b/components/bt/common/include/bt_common.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -100,6 +100,13 @@ #define BT_HCI_LOG_INCLUDED FALSE #endif +// HCI INSIGHTS LOG +#if UC_BT_HCI_LOG_INSIGHTS_ENABLE +#define BT_HCI_INSIGHTS_INCLUDED UC_BT_HCI_LOG_INSIGHTS_ENABLE +#else +#define BT_HCI_INSIGHTS_INCLUDED FALSE +#endif + // HCI LOG TO SPI #if UC_BT_BLE_LOG_SPI_OUT_HCI_ENABLED #define BT_BLE_LOG_SPI_OUT_HCI_ENABLED UC_BT_BLE_LOG_SPI_OUT_HCI_ENABLED @@ -117,10 +124,10 @@ #if UC_BT_HCI_LOG_DATA_BUFFER_SIZE #define HCI_LOG_DATA_BUFFER_SIZE UC_BT_HCI_LOG_DATA_BUFFER_SIZE #else -#define HCI_BUFFER_SIZE (5) +#define HCI_LOG_DATA_BUFFER_SIZE (5) #endif -#if UC_BT_HCI_ADV_BUFFER_SIZE +#if UC_BT_HCI_LOG_ADV_BUFFER_SIZE #define HCI_LOG_ADV_BUFFER_SIZE UC_BT_HCI_LOG_ADV_BUFFER_SIZE #else #define HCI_LOG_ADV_BUFFER_SIZE (5) @@ -277,4 +284,8 @@ typedef struct { #define BD_ADDR_LEN 6 /* Device address length */ typedef UINT8 BD_ADDR[BD_ADDR_LEN]; /* Device address */ +#if (BT_HCI_LOG_INCLUDED == TRUE) && BT_HCI_INSIGHTS_INCLUDED +void bt_hci_log_record_insights(uint8_t data_type, const uint8_t *data, uint16_t data_len); +#endif + #endif /* _BT_COMMON_H_ */ diff --git a/components/bt/common/include/bt_user_config.h b/components/bt/common/include/bt_user_config.h index 3ddc188f13b..bc8a41c77ec 100644 --- a/components/bt/common/include/bt_user_config.h +++ b/components/bt/common/include/bt_user_config.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -176,4 +176,12 @@ #define UC_BT_HCI_LOG_ADV_BUFFER_SIZE (5) #endif + +// HCI LOG INSIGHTS +#ifdef CONFIG_BT_HCI_LOG_INSIGHTS_ENABLE +#define UC_BT_HCI_LOG_INSIGHTS_ENABLE TRUE +#else +#define UC_BT_HCI_LOG_INSIGHTS_ENABLE FALSE +#endif + #endif /* __BT_USER_CONFIG_H__ */ diff --git a/components/bt/host/bluedroid/api/esp_bluedroid_hci.c b/components/bt/host/bluedroid/api/esp_bluedroid_hci.c index 5476f43409d..59c1ab268b1 100644 --- a/components/bt/host/bluedroid/api/esp_bluedroid_hci.c +++ b/components/bt/host/bluedroid/api/esp_bluedroid_hci.c @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -8,6 +8,7 @@ #include "esp_log.h" #include "esp_bluedroid_hci.h" #include "common/bt_target.h" +#include "bt_common.h" #include "hci/hci_trans_int.h" #if (BT_CONTROLLER_INCLUDED == TRUE) #include "esp_bt.h" @@ -69,7 +70,11 @@ void hci_host_send_packet(uint8_t *data, uint16_t len) { #if (BT_HCI_LOG_INCLUDED == TRUE) if (data != NULL && len > 1) { - bt_hci_log_record_hci_data(data[0], &data[1], (uint16_t)(len - 1)); + uint8_t data_type = bt_hci_log_h4_type_to_data_type(data[0]); + bt_hci_log_record_hci_data(data_type, &data[1], (uint16_t)(len - 1)); +#if BT_HCI_INSIGHTS_INCLUDED + bt_hci_log_record_insights(data_type, &data[1], (uint16_t)(len - 1)); +#endif } #endif #if CONFIG_BT_BLE_LOG_SPI_OUT_HCI_ENABLED diff --git a/components/bt/host/bluedroid/hci/hci_hal_h4.c b/components/bt/host/bluedroid/hci/hci_hal_h4.c index cb53e8c4791..26f13d8fff5 100644 --- a/components/bt/host/bluedroid/hci/hci_hal_h4.c +++ b/components/bt/host/bluedroid/hci/hci_hal_h4.c @@ -34,6 +34,7 @@ #include "esp_bt.h" #endif #include "esp_bluedroid_hci.h" +#include "bt_common.h" #if (C2H_FLOW_CONTROL_INCLUDED == TRUE) #include "l2c_int.h" @@ -585,14 +586,20 @@ void bt_record_hci_data(uint8_t *data, uint16_t len) #endif // (BLE_50_FEATURE_SUPPORT == TRUE) )) { bt_hci_log_record_hci_adv(HCI_LOG_DATA_TYPE_ADV, &data[2], len - 2); +#if BT_HCI_INSIGHTS_INCLUDED + bt_hci_log_record_insights(HCI_LOG_DATA_TYPE_ADV, &data[2], len - 2); +#endif } else { uint8_t data_type; - if (data[0] == HCI_LOG_DATA_TYPE_ISO_DATA) { + if (data[0] == DATA_TYPE_ISO) { data_type = HCI_LOG_DATA_TYPE_ISO_DATA; } else { data_type = ((data[0] == 2) ? HCI_LOG_DATA_TYPE_C2H_ACL : data[0]); } bt_hci_log_record_hci_data(data_type, &data[1], len - 1); +#if BT_HCI_INSIGHTS_INCLUDED + bt_hci_log_record_insights(data_type, &data[1], len - 1); +#endif } #endif // (BT_HCI_LOG_INCLUDED == TRUE) } diff --git a/components/bt/host/nimble/esp-hci/src/esp_nimble_hci.c b/components/bt/host/nimble/esp-hci/src/esp_nimble_hci.c index 02065c08538..e81e9d481d9 100644 --- a/components/bt/host/nimble/esp-hci/src/esp_nimble_hci.c +++ b/components/bt/host/nimble/esp-hci/src/esp_nimble_hci.c @@ -78,7 +78,11 @@ void ble_hci_trans_cfg_hs(ble_hci_trans_rx_cmd_fn *cmd_cb, void esp_vhci_host_send_packet_wrapper(uint8_t *data, uint16_t len) { #if (BT_HCI_LOG_INCLUDED == TRUE) - bt_hci_log_record_hci_data(data[0], &data[1], len - 1); + uint8_t data_type = bt_hci_log_h4_type_to_data_type(data[0]); + bt_hci_log_record_hci_data(data_type, &data[1], len - 1); +#if BT_HCI_INSIGHTS_INCLUDED + bt_hci_log_record_insights(data_type, &data[1], len - 1); +#endif #endif #if CONFIG_BT_BLE_LOG_SPI_OUT_HCI_ENABLED ble_log_spi_out_hci_write(BLE_LOG_SPI_OUT_SOURCE_HCI_DOWNSTREAM, data, len); @@ -237,18 +241,24 @@ static void dummy_controller_rcv_pkt_ready(void) void bt_record_hci_data(uint8_t *data, uint16_t len) { #if (BT_HCI_LOG_INCLUDED == TRUE) - if ((data[0] == BLE_HCI_UART_H4_EVT) && (data[1] == BLE_HCI_EVCODE_LE_META) && ((data[3] == BLE_HCI_LE_SUBEV_ADV_RPT) || (data[3] == BLE_HCI_LE_SUBEV_DIRECT_ADV_RPT) + if (len < 2) { + return; + } + if ((len >= 4) && (data[0] == BLE_HCI_UART_H4_EVT) && (data[1] == BLE_HCI_EVCODE_LE_META) && ((data[3] == BLE_HCI_LE_SUBEV_ADV_RPT) || (data[3] == BLE_HCI_LE_SUBEV_DIRECT_ADV_RPT) || (data[3] == BLE_HCI_LE_SUBEV_EXT_ADV_RPT) || (data[3] == BLE_HCI_LE_SUBEV_PERIODIC_ADV_RPT))) { bt_hci_log_record_hci_adv(HCI_LOG_DATA_TYPE_ADV, &data[2], len - 2); +#if BT_HCI_INSIGHTS_INCLUDED + bt_hci_log_record_insights(HCI_LOG_DATA_TYPE_ADV, &data[2], len - 2); +#endif } else { uint8_t data_type; - if (data[0] == HCI_LOG_DATA_TYPE_ISO_DATA) { - data_type = HCI_LOG_DATA_TYPE_ISO_DATA; - } else { - data_type = ((data[0] == 2) ? HCI_LOG_DATA_TYPE_C2H_ACL : data[0]); - } + data_type = ((data[0] == 2) ? HCI_LOG_DATA_TYPE_C2H_ACL : bt_hci_log_h4_type_to_data_type(data[0])); bt_hci_log_record_hci_data(data_type, &data[1], len - 1); +#if BT_HCI_INSIGHTS_INCLUDED + bt_hci_log_record_insights(data_type, &data[1], len - 1); +#endif } + #endif // (BT_HCI_LOG_INCLUDED == TRUE) } diff --git a/components/bt/host/nimble/nimble b/components/bt/host/nimble/nimble index 301a2847fa5..5045cb5eb88 160000 --- a/components/bt/host/nimble/nimble +++ b/components/bt/host/nimble/nimble @@ -1 +1 @@ -Subproject commit 301a2847fa53bfb93d3cc540a2545109153c870b +Subproject commit 5045cb5eb885acb84d4ea86fbf9e5e0202cf0e84 diff --git a/components/bt/host/nimble/port/include/esp_nimble_cfg.h b/components/bt/host/nimble/port/include/esp_nimble_cfg.h index 54c854d66e2..a0f62f36aa2 100644 --- a/components/bt/host/nimble/port/include/esp_nimble_cfg.h +++ b/components/bt/host/nimble/port/include/esp_nimble_cfg.h @@ -2382,4 +2382,12 @@ #endif #endif +#ifndef MYNEWT_VAL_BT_NIMBLE_INSIGHTS_ENABLE +#ifdef CONFIG_BT_NIMBLE_INSIGHTS_ENABLE +#define MYNEWT_VAL_BT_NIMBLE_INSIGHTS_ENABLE CONFIG_BT_NIMBLE_INSIGHTS_ENABLE +#else +#define MYNEWT_VAL_BT_NIMBLE_INSIGHTS_ENABLE (0) +#endif +#endif + #endif