Using ESP32 Diagnostic Logs Provider#

This document outlines how to integrate the ESP32 Diagnostic Logs Provider into your Matter application.

Configuration Options#

Enable the following configuration options to use the ESP32 Diagnostic Logs Provider:

CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE=y

This option enables the diagnostic logs storage functionality.

Implementation Reference#

The ESP32 diagnostic logs provider delegate implementation is available at:

examples/platform/esp32/diagnostics/diagnostic-logs-provider-delegate-impl.h
examples/platform/esp32/diagnostics/diagnostic-logs-provider-delegate-impl.cpp

These files contain the implementation of the LogProvider class which implements the DiagnosticLogsProviderDelegate interface.

Integration Steps#

1. Include the Header File#

Add the diagnostic logs provider delegate header to your application:

#include <diagnostic-logs-provider-delegate-impl.h>

2. Define Buffer Storage#

Define buffers to store and retrieve diagnostic data:

#ifdef CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
static uint8_t retrievalBuffer[CONFIG_RETRIEVAL_BUFFER_SIZE]; // Buffer for retrieving diagnostics
static uint8_t endUserBuffer[CONFIG_END_USER_BUFFER_SIZE];    // Buffer for storing diagnostics

using namespace chip::app::Clusters::DiagnosticLogs;
#endif // CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE

The buffer sizes can be configured through Kconfig options:

CONFIG_RETRIEVAL_BUFFER_SIZE: Size of the buffer used for retrieving diagnostic data inside the diagnostic-logs-provider-delegate.
CONFIG_END_USER_BUFFER_SIZE: Size of the buffer used to store diagnostic data in esp32_diagnostic_trace backend.

3. Initialize the Log Provider#

Implement the diagnostic logs cluster initialization callback:

#ifdef CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE
void emberAfDiagnosticLogsClusterInitCallback(chip::EndpointId endpoint)
{
    auto & logProvider = LogProvider::GetInstance();
    logProvider.Init(endUserBuffer, CONFIG_END_USER_BUFFER_SIZE, retrievalBuffer, CONFIG_RETRIEVAL_BUFFER_SIZE);
    DiagnosticLogsServer::Instance().SetDiagnosticLogsProviderDelegate(endpoint, &logProvider);
}
#endif // CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE

This callback initializes the log provider with the configured buffers and sets it as the delegate for the DiagnosticLogs cluster.

4. Include Diagnostic Logs Server#

Make sure to include the diagnostic logs server in your application:

#include <app/clusters/diagnostic-logs-server/diagnostic-logs-server.h>

Additional Configuration#

Crash Logs Support#

To enable crash logs retrieval, configure the ESP32 core dump functionality:

CONFIG_ESP_COREDUMP_ENABLE_TO_FLASH=y
CONFIG_ESP_COREDUMP_DATA_FORMAT_ELF=y

Example Integration#

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.

Important Notes#

The diagnostic logs provider must be explicitly enabled through the CONFIG_ENABLE_ESP_DIAGNOSTICS_TRACE option
Buffer sizes should be adjusted based on your application’s needs
The provider supports end-user support logs and crash logs (when configured)

Using ESP32 Diagnostic Logs Provider

Contents