Merge branch 'feature/insights_integration' into 'main'

feature/esp-insights: Integrating esp-insights with esp-matter

See merge request app-frameworks/esp-matter!647

Author: dhrishi

docs/en/index.rst

@@ -24,4 +24,5 @@ Table of Contents
    5. Security Considerations <security>
    6. RAM and Flash Optimizations <optimizations>
    7. API Reference <api-reference/index>
+   8. Integration with esp-insights <insights>
    A1 Appendix FAQs <faq>

docs/en/insights.rst

@@ -0,0 +1,17 @@
+Enabling ESP-Insights in ESP-Matter
+===================================
+
+- To learn more about esp-insights and get started, please refer [project README.md] (https://github.com/espressif/esp-insights/blob/main/README.md).
+- Before building the app, enable the option `ESP_INSIGHTS_ENABLED` through menuconfig.
+- Follow the steps present [here](https://github.com/espressif/esp-insights/blob/main/examples/README.md#set-up-esp-insights-account) to set up an `insights_account`, and create an auth key.
+- Create a file named `insights_auth_key.txt` in the project directory of the example.
+- Download the auth key and copy Auth Key to the example.
+
+   ::
+
+      cp /path/to/auth/key.txt path/to/esp-matter/examples/generic_switch/insights_auth_key.txt
+
+- Refer the esp-matter [generic switch example](https://github.com/espressif/esp-matter/blob/main/examples/generic_switch/main/app_main.cpp) to enable the traces and metrics reported by the esp32 tracing backend in the chip SDK on the insights dashboard and about how to use the auth key for enabling insights.
+- Enable the option `ENABLE_ESP_INSIGHTS_SYSTEM_STATS` to get a report of the system metrics in the chip SDK on the insights dashboard.
+
+

examples/common/utils/enable_esp_insights.h

@@ -0,0 +1,55 @@
+// Copyright 2021 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.
+
+#pragma once
+
+#if CONFIG_ENABLE_ESP_INSIGHTS_TRACE
+#include <esp_insights.h>
+#include <esp_log.h>
+#include <platform/PlatformManager.h>
+#include <tracing/esp32_trace/esp32_tracing.h>
+#include <tracing/registry.h>
+
+#if CONFIG_ENABLE_ESP_INSIGHTS_SYSTEM_STATS
+#include <tracing/esp32_trace/insights_sys_stats.h>
+#define START_TIMEOUT_MS 60000
+#endif
+
+static void register_backend(intptr_t context)
+{
+    static chip::Tracing::Insights::ESP32Backend backend;
+    chip::Tracing::Register(backend);
+
+#if CONFIG_ENABLE_ESP_INSIGHTS_SYSTEM_STATS
+    chip::System::Stats::InsightsSystemMetrics::GetInstance().RegisterAndEnable(chip::System::Clock::Timeout(START_TIMEOUT_MS));
+#endif
+}
+
+void enable_insights(const char * insights_auth_key)
+{
+    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,
+    };
+
+    esp_err_t ret = esp_insights_init(&config);
+
+    if (ret != ESP_OK)
+    {
+        ESP_LOGE("Insights", "Failed to initialize ESP Insights, err:0x%x", ret);
+    }
+
+    chip::DeviceLayer::PlatformMgr().ScheduleWork(register_backend, reinterpret_cast<intptr_t>(nullptr));
+}
+#endif // CONFIG_ENABLE_ESP_INSIGHTS_TRACE

examples/generic_switch/CMakeLists.txt

@@ -48,6 +48,12 @@ if(CONFIG_IDF_TARGET_ESP32C2)
 endif()
 
 idf_build_set_property(CXX_COMPILE_OPTIONS "-std=gnu++17;-Os;-DCHIP_HAVE_CONFIG_H;-Wno-overloaded-virtual" APPEND)
+
+if (CONFIG_ENABLE_ESP_INSIGHTS_TRACE)
+    target_add_binary_data(generic_switch.elf "insights_auth_key.txt" TEXT)
+endif()
+
+idf_build_set_property(CXX_COMPILE_OPTIONS "-std=gnu++17;-Os;-DCHIP_HAVE_CONFIG_H" APPEND)
 idf_build_set_property(C_COMPILE_OPTIONS "-Os" APPEND)
 # For RISCV chips, project_include.cmake sets -Wno-format, but does not clear various
 # flags that depend on -Wformat

examples/generic_switch/README.md

@@ -17,6 +17,12 @@ See the [docs](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/de
 
 ## 1. Additional Environment Setup
 
+### 1.1 Enabling insights (Optional)
+
+Follow the steps mentioned [here](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/insights.html)
+
+### 1.2 Flash the factory partition 
+
 The steps below should be followed in order to access the fixed-labels.
 -   If monitoring the device using ``idf.py monitor``,press `` Ctrl + ]`` to stop the process.
 -   The following command must be executed to flash the mfg partition:
@@ -26,6 +32,8 @@ esptool.py -p [port-name] write_flash 0x10000 mfg_binaries/20202020_3841.bin
 ```
 
 -   Execute the command ``idf.py monitor``
+
+## 2.Commissioning and Control
 -   Commission the device with ``discriminator: 3841``and `` passcode: 20202020``
 
     ```
@@ -37,25 +45,27 @@ esptool.py -p [port-name] write_flash 0x10000 mfg_binaries/20202020_3841.bin
     - QRCode     :
     - ![QRCode](mfg_binaries/matter_qrcode_20202020_3841.png)
 
--   To read the fixed-labels, use chip-tool.
+### 2.1 Fixed-Labels
+- To read the fixed-labels, use chip-tool.
 
     ```
     chip-tool fixedlabel read label-list 0x7283 1
     ```
 
-The example command given below should be executed to write to the label-list of User Label Cluster.
+### 2.2 User-Labels
+- The example command given below should be executed to write to the label-list of User Label Cluster.
 
 ```
 chip-tool userlabel write label-list '[{"label":"room", "value":"bedroom 1"}, {"label":"orientation", "value":"east"}]' 0x7283 1
 ```
 
-To read label-list of User Label Cluster execute the command given below.
+- To read label-list of User Label Cluster execute the command given below.
 
 ```
 chip-tool userlabel read label-list 0x7283 1
 ```
 
-### Using the TagList Feature
+### 2.3 Using the TagList Feature
 
 To read the taglist of the Descriptor cluster execute the command given below.
 

examples/generic_switch/main/app_main.cpp

@@ -15,6 +15,7 @@
 #include <esp_matter_ota.h>
 
 #include <common_macros.h>
+#include <enable_esp_insights.h>
 #include <app_priv.h>
 #include <app_reset.h>
 #include <app/util/attribute-storage.h>
@@ -34,6 +35,11 @@ using namespace esp_matter::endpoint;
 using namespace esp_matter::cluster;
 using namespace chip::app::Clusters;
 
+#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
+
 namespace {
 // Please refer to https://github.com/CHIP-Specifications/connectedhomeip-spec/blob/master/src/namespaces
 constexpr const uint8_t kNamespaceSwitches = 43;
@@ -231,6 +237,10 @@ extern "C" void app_main()
     err = esp_matter::start(app_event_cb);
     ABORT_APP_ON_FAILURE(err == ESP_OK, ESP_LOGE(TAG, "Failed to start Matter, err:%d", err));
 
+#if CONFIG_ENABLE_ESP_INSIGHTS_TRACE
+    enable_insights(insights_auth_key_start);
+#endif
+
     SetTagList(0, chip::Span<const Descriptor::Structs::SemanticTagStruct::Type>(gEp0TagList));
     SetTagList(1, chip::Span<const Descriptor::Structs::SemanticTagStruct::Type>(gEp1TagList));