[ESP32] Platform diagnostics framework

config/esp32/components/chip/CMakeLists.txt

@@ -302,6 +302,11 @@ if (CONFIG_ENABLE_ESP_INSIGHTS_TRACE)
   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()
@@ -314,6 +319,10 @@ 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()
+
 if (CONFIG_CHIP_DEVICE_ENABLE_DYNAMIC_SERVER)
     chip_gn_arg_append("chip_build_controller_dynamic_server" "true")
 endif()
@@ -379,6 +388,11 @@ 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()
+
+
 # When using the pregenerated files, there is a edge case where an error appears for
 # undeclared argument chip_code_pre_generated_directory. To get around with it we are
 # disabling the --fail-on-unused-args flag.

config/esp32/components/chip/Kconfig

@@ -860,6 +860,13 @@ menu "CHIP Device Layer"
                 NVS namespace. If this option is enabled, the application can use an API to set a CD,
                 the configured CD will be used for subsequent CD reads.
 
+        config ENABLE_ESP_DIAGNOSTICS_TRACE
+            bool "Enable ESP Platform Diagnostics for Matter"
+            default n
+            help
+                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
@@ -876,15 +883,14 @@ menu "CHIP Device Layer"
            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"
-           range 5 30
-           depends on ESP_INSIGHTS_ENABLED
-           default 20
-           help
-               Maximum number of group entries that can be included in the permit list for reporting
-               the traces to insights.
-
+        config MAX_PERMIT_LIST_SIZE
+            int "Set permit list size for Insights traces"
+            range 5 30
+            depends on ESP_INSIGHTS_ENABLED || 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.
     endmenu
 
 

examples/temperature-measurement-app/esp32/README.md

@@ -40,6 +40,21 @@ main/diagnostic_logs
 
 These files contain dummy data.
 
+#### To use diagnostic tracing
+
+Open menuconfig
+
+```
+ idf.py menuconfig
+```
+
+Enable `ENABLE_ESP_DIAGNOSTICS_TRACE` option from menuconfig
+
+Set diagnostic storage buffer size from `Platform Diagnostics` menu
+
+-   End user buffer default size 4096
+-   Retrieval buffer default size 4096
+
 #### To test the diagnostic logs cluster
 
 ```

examples/temperature-measurement-app/esp32/main/Kconfig.projbuild

@@ -83,3 +83,21 @@ depends on ENABLE_PW_RPC
             about available pin numbers for UART.
 
 endmenu
+
+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

examples/temperature-measurement-app/esp32/main/diagnostic-logs-provider-delegate-impl.cpp

@@ -29,6 +29,11 @@ using namespace chip::app::Clusters::DiagnosticLogs;
 LogProvider LogProvider::sInstance;
 LogProvider::CrashLogContext LogProvider::sCrashLogContext;
 
+#ifdef CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+static uint32_t sReadEntries = 0;
+static uint8_t retrievalBuffer[CONFIG_RETRIEVAL_BUFFER_SIZE];
+#endif // CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+
 namespace {
 bool IsValidIntent(IntentEnum intent)
 {
@@ -74,8 +79,16 @@ size_t LogProvider::GetSizeForIntent(IntentEnum intent)
 {
     switch (intent)
     {
-    case IntentEnum::kEndUserSupport:
+    case IntentEnum::kEndUserSupport: {
+#ifdef CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+        VerifyOrReturnError(mStorageInstance != nullptr, 0,
+                            ChipLogError(DeviceLayer, "Diagnostic Storage instance cannot be null."));
+        return mStorageInstance->GetDataSize();
+#else
         return static_cast<size_t>(endUserSupportLogEnd - endUserSupportLogStart);
+#endif // CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+    }
+    break;
     case IntentEnum::kNetworkDiag:
         return static_cast<size_t>(networkDiagnosticLogEnd - networkDiagnosticLogStart);
     case IntentEnum::kCrashLogs:
@@ -107,8 +120,24 @@ CHIP_ERROR LogProvider::PrepareLogContextForIntent(LogContext * context, IntentE
     switch (intent)
     {
     case IntentEnum::kEndUserSupport: {
+#ifdef CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+        VerifyOrReturnError(mStorageInstance != nullptr, CHIP_ERROR_INTERNAL,
+                            ChipLogError(DeviceLayer, "Diagnostic Storage instance cannot be null."));
+        MutableByteSpan endUserSupportSpan(retrievalBuffer, CONFIG_RETRIEVAL_BUFFER_SIZE);
+        VerifyOrReturnError(!mStorageInstance->IsBufferEmpty(), CHIP_ERROR_NOT_FOUND,
+                            ChipLogError(DeviceLayer, "Empty Diagnostic buffer"));
+        // Retrieve data from the diagnostic storage
+        CHIP_ERROR err = mStorageInstance->Retrieve(endUserSupportSpan, sReadEntries);
+        if (err != CHIP_NO_ERROR && err != CHIP_ERROR_BUFFER_TOO_SMALL && err != CHIP_ERROR_END_OF_TLV)
+        {
+            ChipLogError(DeviceLayer, "Failed to retrieve data: %s", ErrorStr(err));
+            return err;
+        }
+        context->EndUserSupport.span = endUserSupportSpan;
+#else
         context->EndUserSupport.span =
             ByteSpan(&endUserSupportLogStart[0], static_cast<size_t>(endUserSupportLogEnd - endUserSupportLogStart));
+#endif // CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
     }
     break;
 
@@ -277,11 +306,23 @@ CHIP_ERROR LogProvider::StartLogCollection(IntentEnum intent, LogSessionHandle &
 
 CHIP_ERROR LogProvider::EndLogCollection(LogSessionHandle sessionHandle, CHIP_ERROR error)
 {
-    if (error != CHIP_NO_ERROR)
+#ifdef CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+    VerifyOrReturnError(mStorageInstance != nullptr, CHIP_ERROR_INTERNAL,
+                        ChipLogError(DeviceLayer, "Diagnostic Storage instance cannot be null."));
+    if (error == CHIP_NO_ERROR)
     {
-        // Handle the error
-        ChipLogProgress(DeviceLayer, "End log collection reason: %s", ErrorStr(error));
+        CHIP_ERROR err = mStorageInstance->ClearBuffer(sReadEntries);
+        if (err != CHIP_NO_ERROR)
+        {
+            ChipLogError(DeviceLayer, "Failed to clear diagnostic read entries");
+        }
+        else
+        {
+            ChipLogDetail(DeviceLayer, "Cleared all read diagnostics successfully");
+        }
     }
+#endif // CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+
     VerifyOrReturnValue(sessionHandle != kInvalidLogSessionHandle, CHIP_ERROR_INVALID_ARGUMENT);
     VerifyOrReturnValue(mSessionContextMap.count(sessionHandle), CHIP_ERROR_INVALID_ARGUMENT);
 

examples/temperature-measurement-app/esp32/main/include/diagnostic-logs-provider-delegate-impl.h

@@ -19,12 +19,18 @@
 #pragma once
 
 #include <app/clusters/diagnostic-logs-server/DiagnosticLogsProviderDelegate.h>
+
 #include <map>
 
 #if defined(CONFIG_ESP_COREDUMP_ENABLE_TO_FLASH) && defined(CONFIG_ESP_COREDUMP_DATA_FORMAT_ELF)
 #include <esp_core_dump.h>
 #endif // defined(CONFIG_ESP_COREDUMP_ENABLE_TO_FLASH) && defined(CONFIG_ESP_COREDUMP_DATA_FORMAT_ELF)
 
+#ifdef CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+#include <tracing/esp32_diagnostic_trace/DiagnosticStorage.h>
+using namespace chip::Tracing::Diagnostics;
+#endif // CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+
 namespace chip {
 namespace app {
 namespace Clusters {
@@ -49,6 +55,9 @@ class LogProvider : public DiagnosticLogsProviderDelegate
     size_t GetSizeForIntent(IntentEnum intent) override;
     CHIP_ERROR GetLogForIntent(IntentEnum intent, MutableByteSpan & outBuffer, Optional<uint64_t> & outTimeStamp,
                                Optional<uint64_t> & outTimeSinceBoot) override;
+#ifdef CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+    void SetDiagnosticStorageInstance(CircularDiagnosticBuffer * bufferInstance) { mStorageInstance = bufferInstance; }
+#endif
 
 private:
     static LogProvider sInstance;
@@ -58,6 +67,11 @@ class LogProvider : public DiagnosticLogsProviderDelegate
     LogProvider(const LogProvider &)             = delete;
     LogProvider & operator=(const LogProvider &) = delete;
 
+#ifdef CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+    // If mStorageInstance is nullptr then operations related to diagnostic storage will be skipped.
+    CircularDiagnosticBuffer * mStorageInstance = nullptr;
+#endif // CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+
     struct CrashLogContext
     {
 #if defined(CONFIG_ESP_COREDUMP_ENABLE_TO_FLASH) && defined(CONFIG_ESP_COREDUMP_DATA_FORMAT_ELF)

examples/temperature-measurement-app/esp32/main/main.cpp

@@ -52,6 +52,13 @@
 #include <DeviceInfoProviderImpl.h>
 #endif // CONFIG_ENABLE_ESP32_DEVICE_INFO_PROVIDER
 
+#ifdef CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+#include <tracing/esp32_diagnostic_trace/DiagnosticTracing.h>
+static uint8_t endUserBuffer[CONFIG_END_USER_BUFFER_SIZE]; // Global static buffer used to store diagnostics
+using namespace chip::Tracing::Diagnostics;
+CircularDiagnosticBuffer diagnosticStorage(endUserBuffer, CONFIG_END_USER_BUFFER_SIZE);
+#endif // CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+
 namespace {
 #if CONFIG_ENABLE_ESP32_FACTORY_DATA_PROVIDER
 chip::DeviceLayer::ESP32FactoryDataProvider sFactoryDataProvider;
@@ -75,14 +82,17 @@ static AppDeviceCallbacks EchoCallbacks;
 static void InitServer(intptr_t context)
 {
     Esp32AppServer::Init(); // Init ZCL Data Model and CHIP App Server AND Initialize device attestation config
+#ifdef CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+    static ESP32Diagnostics diagnosticBackend(&diagnosticStorage);
+    Tracing::Register(diagnosticBackend);
+#endif // CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
 }
 
 extern "C" void app_main()
 {
 #if CONFIG_ENABLE_PW_RPC
     chip::rpc::Init();
 #endif
-
     ESP_LOGI(TAG, "Temperature sensor!");
 
     // Initialize the ESP NVS layer.
@@ -134,5 +144,8 @@ using namespace chip::app::Clusters::DiagnosticLogs;
 void emberAfDiagnosticLogsClusterInitCallback(chip::EndpointId endpoint)
 {
     auto & logProvider = LogProvider::GetInstance();
+#ifdef CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
+    logProvider.SetDiagnosticStorageInstance(&diagnosticStorage);
+#endif
     DiagnosticLogsServer::Instance().SetDiagnosticLogsProviderDelegate(endpoint, &logProvider);
 }

scripts/tools/check_includes_config.py

@@ -168,6 +168,9 @@
     'src/tracing/json/json_tracing.cpp': {'string', 'sstream'},
     'src/tracing/json/json_tracing.h': {'fstream', 'unordered_map', 'string'},
 
+    # esp32 diagnostic tracing
+    'src/tracing/esp32_diagnostic_trace/Counter.h': {'map'},
+
     # esp32 tracing
     'src/tracing/esp32_trace/esp32_tracing.h': {'unordered_map'},
 

src/tracing/esp32_diagnostic_trace/BUILD.gn

@@ -0,0 +1,48 @@
+#
+#Copyright (c) 2025 Project CHIP Authors
+#
+# 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.
+
+import("//build_overrides/build.gni")
+import("//build_overrides/chip.gni")
+
+config("tracing") {
+  include_dirs = [ "include" ]
+}
+
+static_library("backend") {
+  output_name = "libEsp32DiagnosticsBackend"
+  output_dir = "${root_out_dir}/lib"
+
+  sources = [
+    "Counter.cpp",
+    "Counter.h",
+    "DiagnosticEntry.cpp",
+    "DiagnosticEntry.h",
+    "DiagnosticStorage.cpp",
+    "DiagnosticStorage.h",
+    "DiagnosticTracing.cpp",
+    "DiagnosticTracing.h",
+  ]
+
+  public_deps = [
+    "${chip_root}/src/lib/core",
+    "${chip_root}/src/tracing",
+  ]
+}
+
+source_set("esp32_diagnostic_tracing") {
+  public = [ "include/matter/tracing/macros_impl.h" ]
+  public_configs = [ ":tracing" ]
+  deps = [ ":backend" ]
+}