project-chip · pimpalemahesh · Feb 7, 2025 · Feb 20, 2025 · Mar 5, 2025 · Mar 6, 2025
@@ -297,28 +297,15 @@ if (CONFIG_SEC_CERT_DAC_PROVIDER)
     chip_gn_arg_append("chip_use_secure_cert_dac_provider"                 "true")
 endif()
 
-if (CONFIG_ENABLE_ESP_INSIGHTS_TRACE)
-  chip_gn_arg_bool("matter_enable_tracing_support"  "true")
-  chip_gn_arg_append("matter_trace_config" "\"${CHIP_ROOT}/src/tracing/esp32_trace:esp32_trace_tracing\"")
-endif()
-
 if (CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE)
     chip_gn_arg_bool("matter_enable_tracing_support"  "true")
     chip_gn_arg_append("matter_trace_config" "\"${CHIP_ROOT}/src/tracing/esp32_diagnostic_trace:esp32_diagnostic_tracing\"")
 endif()
 
-if (CONFIG_ENABLE_ESP_INSIGHTS_SYSTEM_STATS)
-     chip_gn_arg_append("matter_enable_esp_insights_system_stats"            "true")
-endif()
-
 if (CONFIG_USE_ESP32_ECDSA_PERIPHERAL)
     chip_gn_arg_append("chip_use_esp32_ecdsa_peripheral" "true")
 endif()
 
-if (CONFIG_ENABLE_ESP_INSIGHTS_TRACE)
-   target_include_directories(${COMPONENT_LIB} INTERFACE "${CHIP_ROOT}/src/tracing/esp32_trace/include")
-endif()
-
 if (CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE)
     target_include_directories(${COMPONENT_LIB} INTERFACE "${CHIP_ROOT}/src/tracing/esp32_diagnostic_trace/include")
 endif()
@@ -384,10 +371,6 @@ if(CONFIG_ENABLE_PW_RPC)
   list(APPEND chip_libraries "${CMAKE_CURRENT_BINARY_DIR}/lib/libPwRpc.a")
 endif()
 
-if (CONFIG_ENABLE_ESP_INSIGHTS_TRACE)
-  list(APPEND chip_libraries "${CMAKE_CURRENT_BINARY_DIR}/lib/libEsp32TracingBackend.a")
-endif()
-
 if (CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE)
   list(APPEND chip_libraries "${CMAKE_CURRENT_BINARY_DIR}/lib/libEsp32DiagnosticsBackend.a")
 endif()

@@ -861,30 +861,13 @@ menu "CHIP Device Layer"
                 Enables the ESP Diagnostics platform to collect, store, and retrieve diagnostic data for the Matter protocol.
                 This feature helps monitor system health and performance by providing insights through diagnostics logs.
 
-       config ENABLE_ESP_INSIGHTS_TRACE
-           bool "Enable Matter ESP Insights"
-           depends on ESP_INSIGHTS_ENABLED
-           default y
-           help
-               ESP Insights is a remote diagnostics solution to monitor the health of ESP devices in the field.
-               Enabling the above option will enable the esp32 specific tracing functionality and report the
-               diagnostic information to the insights cloud.
-
-      config ENABLE_ESP_INSIGHTS_SYSTEM_STATS
-           bool "Enable System Stats for insights"
-           depends on ESP_INSIGHTS_ENABLED
-           default n
-           help
-               This option enables the system statistics to be sent to the insights cloud.
-
         config MAX_PERMIT_LIST_SIZE
-            int "Set permit list size for Insights traces"
+            int "Set permit list size for filtered traces"
             range 5 30
-            depends on ESP_INSIGHTS_ENABLED || ENABLE_ESP_DIAGNOSTICS_TRACE
+            depends on ENABLE_ESP_DIAGNOSTICS_TRACE
             default 20
             help
-                Set the maximum number of group entries that can be included in the permit list for reporting
-                traces to Insights or diagnostics. This ensures proper management of trace reporting capacity.
+                Set the maximum number of group entries that can be included in the permit list for filtering traces.
     endmenu
 
 

@@ -16,15 +16,6 @@ dependencies:
         rules:
             - if: "idf_version >=4.4"
 
-    espressif/esp_insights:
-        version: "^1.2.4"
-        require: public
-        # There is an issue with IDF-Component-Manager when ESP Insights is included.
-        # Issue: https://github.com/project-chip/connectedhomeip/issues/29125
-        rules:
-            - if: "idf_version >=5.0"
-            - if: "target != esp32h2"
-
     espressif/esp_rcp_update:
         version: "~1.3.0"
         rules:

@@ -56,6 +56,35 @@ The buffer sizes can be configured through Kconfig options:
 -   `CONFIG_END_USER_BUFFER_SIZE`: Size of the buffer used to store diagnostic
     data in esp32_diagnostic_trace backend.
 
+### Kconfig Configuration
+
+Add the following configuration menu to your application's
+`main/Kconfig.projbuild` file:
+
+```kconfig
+menu "Platform Diagnostics"
+
+    config END_USER_BUFFER_SIZE
+        int "Set buffer size for end user diagnostic data"
+        depends on ENABLE_ESP_DIAGNOSTICS_TRACE
+        default 4096
+        help
+            Defines the buffer size (in bytes) for storing diagnostic data related to end user activity.
+            This buffer will hold logs and traces relevant to user interactions with the Matter protocol.
+
+    config RETRIEVAL_BUFFER_SIZE
+        int "Set buffer size for retrieval of diagnostics from diagnostic storage"
+        depends on ENABLE_ESP_DIAGNOSTICS_TRACE
+        default 4096
+        help
+            Defines the buffer size (in bytes) for retrieval of diagnostic data.
+endmenu
+```
+
+**Note**: The
+`examples/temperature-measurement-app/esp32/main/Kconfig.projbuild` demonstrates
+this complete configuration.
+
 ### 3. Initialize the Log Provider
 
 Implement the diagnostic logs cluster initialization callback:
@@ -99,9 +128,184 @@ The `examples/temperature-measurement-app/esp32/` demonstrates proper
 integration: For more information related to the retrieval of diagnostics
 through diagnosticlogs cluster refer readme.md in app folder.
 
+# Using ESP32 Insights Integration
+
+This section describes how to integrate ESP Insights functionality for automatic
+diagnostic data collection and cloud reporting.
+
+## Configuration Options
+
+Enable the following configuration options to use ESP Insights:
+
+```
+CONFIG_ESP_INSIGHTS_ENABLED=y
+CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE=y
+```
+
+Both options are required:
+
+-   `CONFIG_ESP_INSIGHTS_ENABLED`: Enables ESP Insights cloud integration
+-   `CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE`: Enables diagnostic data collection
+
+## Implementation Reference
+
+The ESP32 Insights delegate implementation is available at:
+
+```
+examples/platform/esp32/diagnostics/insights/insights-delegate.h
+examples/platform/esp32/diagnostics/insights/insights-delegate.cpp
+```
+
+These files contain the implementation of the `InsightsDelegate` class which
+handles diagnostic data collection and transmission to ESP Insights.
+
+## Integration Steps
+
+### 1. Include the Header File
+
+Add the insights delegate header to your application:
+
+```cpp
+#if CONFIG_ESP_INSIGHTS_ENABLED && CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+#include <insights-delegate.h>
+#endif
+```
+
+### 2. Define Buffer Storage and Auth Key
+
+Define buffers and authentication key for insights:
+
+```cpp
+#if CONFIG_ESP_INSIGHTS_ENABLED && CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+#define START_TIMEOUT_MS 10000
+static uint8_t endUserBuffer[CONFIG_END_USER_BUFFER_SIZE]; // Global static buffer used to store diagnostics
+extern const char insights_auth_key_start[] asm("_binary_insights_auth_key_txt_start");
+extern const char insights_auth_key_end[] asm("_binary_insights_auth_key_txt_end");
+#endif
+```
+
+### 3. Create Auth Key File
+
+Create an `insights_auth_key.txt` file in your application's main directory
+containing your ESP Insights authentication key.
+
+### 4. Initialize Insights
+
+Implement the insights initialization function:
+
+```cpp
+static void InitInsights()
+{
+#if CONFIG_ESP_INSIGHTS_ENABLED && CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+    chip::Insights::InsightsInitParams initParams = {
+        .diagnosticBuffer     = endUserBuffer,
+        .diagnosticBufferSize = CONFIG_END_USER_BUFFER_SIZE,
+        .authKey              = insights_auth_key_start
+    };
+
+    chip::Insights::InsightsDelegate & insightsDelegate = chip::Insights::InsightsDelegate::GetInstance();
+    CHIP_ERROR error = insightsDelegate.Init(initParams);
+    VerifyOrReturn(error == CHIP_NO_ERROR, ESP_LOGE(TAG, "Failed to initialize ESP Insights"));
+
+    error = insightsDelegate.StartPeriodicInsights(chip::System::Clock::Timeout(START_TIMEOUT_MS));
+    VerifyOrReturn(error == CHIP_NO_ERROR, ESP_LOGE(TAG, "Failed to start periodic insights"));
+
+    error = insightsDelegate.SetSamplingInterval(chip::System::Clock::Timeout(10000));
+    VerifyOrReturn(error == CHIP_NO_ERROR, ESP_LOGE(TAG, "Failed to set sampling interval"));
+#endif
+}
+```
+
+### 5. CMakeLists.txt Configuration
+
+Add the following to your application's CMakeLists.txt:
+
+```cmake
+if (CONFIG_ESP_INSIGHTS_ENABLED AND CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE)
+    list(APPEND PRIV_INCLUDE_DIRS_LIST "${CHIP_ROOT}/examples/platform/esp32/diagnostics/insights/")
+    list(APPEND SRC_DIRS_LIST "${CHIP_ROOT}/examples/platform/esp32/diagnostics/insights/")
+    target_add_binary_data(${COMPONENT_TARGET} "insights_auth_key.txt" TEXT)
+endif()
+```
+
+### Kconfig Configuration for Insights
+
+Add the following configuration menu to your application's
+`main/Kconfig.projbuild` file:
+
+```kconfig
+menu "Platform Diagnostics"
+
+    config END_USER_BUFFER_SIZE
+        int "Set buffer size for end user diagnostic data"
+        depends on ENABLE_ESP_DIAGNOSTICS_TRACE
+        default 4096
+        help
+            Defines the buffer size (in bytes) for storing diagnostic data related to end user activity.
+            This buffer will hold logs and traces relevant to user interactions with the Matter protocol.
+endmenu
+```
+
+**Note**: For ESP Insights, only the `END_USER_BUFFER_SIZE` configuration is
+required. Reference implementations can be found in:
+
+-   `examples/lighting-app/esp32/main/Kconfig.projbuild`
+-   `examples/energy-management-app/esp32/main/Kconfig.projbuild`
+
+## Features
+
+The ESP Insights integration provides:
+
+-   **Automatic Data Collection**: Collects diagnostic traces and metrics
+-   **Cloud Integration**: Automatically sends data to ESP Insights dashboard
+-   **Periodic Reporting**: Configurable sampling intervals for data
+    transmission
+-   **Trace Data**: Logs string-based diagnostic events
+-   **Metric Data**: Reports signed and unsigned integer metrics
+-   **Memory Monitoring**: Tracks heap usage and other system metrics
+
+## API Reference
+
+### InsightsDelegate Methods
+
+-   `Init(InsightsInitParams & initParams)`: Initialize insights with buffer and
+    auth key
+-   `StartPeriodicInsights(timeout)`: Start periodic data transmission
+-   `StopPeriodicInsights()`: Stop periodic data transmission
+-   `SetSamplingInterval(timeout)`: Configure data sampling interval
+
+### Configuration Parameters
+
+-   `diagnosticBuffer`: Buffer for storing diagnostic data
+-   `diagnosticBufferSize`: Size of the diagnostic buffer
+-   `authKey`: ESP Insights authentication key
+
+## Insights Example Integration
+
+The following examples demonstrate proper ESP Insights integration:
+
+### Working Examples
+
+-   **`examples/lighting-app/esp32/`** - Complete implementation showing:
+
+    -   Conditional compilation guards
+    -   Buffer initialization and auth key setup
+    -   Periodic insights reporting with configurable intervals
+    -   Integration with diagnostic trace collection
+
+-   **`examples/energy-management-app/esp32/`** - Alternative implementation
+    demonstrating:
+
+For more detailed information about insights integration refer to the README.md
+file in each application folder.
+
 ## Important Notes
 
 -   The diagnostic logs provider **must** be explicitly enabled through the
     `CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE` option
+-   ESP Insights requires both `CONFIG_ESP_INSIGHTS_ENABLED` and
+    `CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE`
 -   Buffer sizes should be adjusted based on your application's needs
 -   The provider supports end-user support logs and crash logs (when configured)
+-   Authentication key must be obtained from ESP Insights dashboard and stored
+    in `insights_auth_key.txt`
@@ -73,10 +73,6 @@ chip_configure_data_model(${COMPONENT_LIB}
     ZAP_FILE ${ENERGY_GATEWAY_DIR}/energy-gateway-common/energy-gateway-app.zap
 )
 
-if(CONFIG_ENABLE_ESP_INSIGHTS_TRACE)
-  target_add_binary_data(${COMPONENT_TARGET} "insights_auth_key.txt" TEXT)
-endif()
-
 set_property(TARGET ${COMPONENT_LIB} PROPERTY CXX_STANDARD 17)
 target_compile_options(${COMPONENT_LIB} PRIVATE "-DCHIP_HAVE_CONFIG_H")
 target_compile_options(${COMPONENT_LIB} PUBLIC

@@ -62,24 +62,13 @@
 #include <platform/ESP32/ESP32SecureCertDACProvider.h>
 #endif
 
-#if CONFIG_ENABLE_ESP_INSIGHTS_TRACE
-#include <esp_insights.h>
-#include <tracing/esp32_trace/esp32_tracing.h>
-#include <tracing/registry.h>
-#endif
-
 using namespace ::chip;
 using namespace chip::app;
 using namespace chip::app::Clusters;
 using namespace ::chip::Credentials;
 using namespace ::chip::DeviceManager;
 using namespace ::chip::DeviceLayer;
 
-#if CONFIG_ENABLE_ESP_INSIGHTS_TRACE
-extern const char insights_auth_key_start[] asm("_binary_insights_auth_key_txt_start");
-extern const char insights_auth_key_end[] asm("_binary_insights_auth_key_txt_end");
-#endif
-
 static const char * TAG = "energy-gateway-app";
 
 static AppDeviceCallbacks EchoCallbacks;
@@ -136,22 +125,6 @@ static void InitServer(intptr_t context)
     DeviceCallbacksDelegate::Instance().SetAppDelegate(&sAppDeviceCallbacksDelegate);
     Esp32AppServer::Init(); // Init ZCL Data Model and CHIP App Server AND
                             // Initialize device attestation config
-#if CONFIG_ENABLE_ESP_INSIGHTS_TRACE
-    esp_insights_config_t config = {
-        .log_type = ESP_DIAG_LOG_TYPE_ERROR | ESP_DIAG_LOG_TYPE_WARNING | ESP_DIAG_LOG_TYPE_EVENT,
-        .auth_key = insights_auth_key_start,
-    };
-
-    esp_err_t ret = esp_insights_init(&config);
-
-    if (ret != ESP_OK)
-    {
-        ESP_LOGE(TAG, "Failed to initialize ESP Insights, err:0x%x", ret);
-    }
-
-    static Tracing::Insights::ESP32Backend backend;
-    Tracing::Register(backend);
-#endif
 
     // Application code should always be initialised after the initialisation of
     // server.

@@ -12,8 +12,8 @@ guides to get started.
 
 ### Enabling ESP-Insights:
 
--   Before building the app, enable the option: `ESP_INSIGHTS_ENABLED` through
-    menuconfig.
+-   Before building the app, enable the options: `ESP_INSIGHTS_ENABLED` and
+    `ENABLE_ESP_DIAGNOSTICS_TRACE` through menuconfig.
 
 -   Create a file named `insights_auth_key.txt` in the main directory of the
     example.