diff --git a/docs/en/index.rst b/docs/en/index.rst index 84b1c0211..49b98c017 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -24,4 +24,5 @@ Table of Contents 5. Security Considerations 6. RAM and Flash Optimizations 7. API Reference + 8. Integration with esp-insights A1 Appendix FAQs diff --git a/docs/en/insights.rst b/docs/en/insights.rst new file mode 100644 index 000000000..c6ac1a99b --- /dev/null +++ b/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. + + diff --git a/examples/common/utils/enable_esp_insights.h b/examples/common/utils/enable_esp_insights.h new file mode 100644 index 000000000..a4a619bf9 --- /dev/null +++ b/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 +#include +#include +#include +#include + +#if CONFIG_ENABLE_ESP_INSIGHTS_SYSTEM_STATS +#include +#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(nullptr)); +} +#endif // CONFIG_ENABLE_ESP_INSIGHTS_TRACE diff --git a/examples/generic_switch/CMakeLists.txt b/examples/generic_switch/CMakeLists.txt index 81a144fac..5aa4bdc93 100644 --- a/examples/generic_switch/CMakeLists.txt +++ b/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 diff --git a/examples/generic_switch/README.md b/examples/generic_switch/README.md index 204731e1b..3df32c288 100644 --- a/examples/generic_switch/README.md +++ b/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. diff --git a/examples/generic_switch/main/app_main.cpp b/examples/generic_switch/main/app_main.cpp index a090c49ac..9b92a8975 100644 --- a/examples/generic_switch/main/app_main.cpp +++ b/examples/generic_switch/main/app_main.cpp @@ -15,6 +15,7 @@ #include #include +#include #include #include #include @@ -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(gEp0TagList)); SetTagList(1, chip::Span(gEp1TagList));