Merge branch 'feature/cmd_resp_framework' into 'main'

Added command-response interface

See merge request app-frameworks/esp-insights!163

CHANGELOG.md

@@ -1,3 +1,11 @@
+## 24-Jul-2024 (Command Response Framework and Components update)
+- Added support for command response framework
+  - To demonstrate this, a simple reboot command has been added. Admins can trigger this command from the Insights dashboard (under Node's Settings tab) to reboot the device.
+  - This feature is currently supported only for nodes claimed from the RainMaker CLI and when MQTT transport is enabled.
+- Updated components:
+  - Updated the rmaker_common submodule.
+  - Bumped up the component versions for `esp_diagnostics` and `esp_insights`.
+
 ## 23-Feb-2024 (Added support for new metadata structure 2.0)
 
 - This change has been introduced for better management of metrics and variables hierarchy

FEATURES.md

@@ -8,6 +8,7 @@ Below are some of the features offered by ESP Insights:
 - [Transport Sharing](#transport-sharing)
 - [Optimising Device-Cloud Communication](#optimising-device-cloud-communication)
 - [Group Analytics](#group-analytics)
+- [Command Response](#command-response)
 
 ### Core Dump
 In case of a firmware crash, the Insights agent captures the core dump information into the flash memory and reports it to the ESP Insights cloud in the subsequent boot-up. This allows you to look at all the crash logs that the devices may be generating in the field.
@@ -123,7 +124,7 @@ esp_diag_wifi_metrics_dump();
 ```
 
 #### Custom Metrics
-It is fairly simple to register your own metrics as well. This can be done as: 
+It is fairly simple to register your own metrics as well. This can be done as:
 
 ```
 /* Register a metrics to track room temperature */
@@ -180,7 +181,7 @@ As you may notice, every variable has some metadata associated with it. Some exp
 ### Transport Sharing
 The Insights agent supports sending data to the cloud using HTTPS or MQTT (TLS) transport.
 
-Creating a separate TLS session on the device could add to the memory consumption on the device. 
+Creating a separate TLS session on the device could add to the memory consumption on the device.
 To avoid this, the Insights agent shares the transport (MQTT) with your cloud agent.
 Currently the RainMaker cloud agent is supported.
 This ensures that we reuse the socket/TLS connection without adding a connection memory overhead on your device.
@@ -222,3 +223,7 @@ You can change the interval to hour or aggregate to week or a month interval.
 ![Group Analytics 5](docs/_static/group_analytics_5.png)
 
 - List of top nodes having the most number of events and can be drilled down to category level
+
+### Command Response
+ESP Insights leverages RainMaker's command response feature to enable the device to be controllable from the Insights dashboard.
+- When enabled, this feature lists options under the Node's Settings tab. These interactive options can be used to control the device. For example, an admin can remotely reboot the device, enable or disable diagnostics collection, or granularly choose to enable or disable features such as Metrics and Variables.

components/esp_diagnostics/idf_component.yml

@@ -1,4 +1,4 @@
-version: "1.1.0"
+version: "1.2.0"
 description: Diagnostics component used in ESP Insights, which is a remote diagnostics solution to monitor the health of ESP devices in the field.
 url: https://github.com/espressif/esp-insights/tree/main/components/esp_diagnostics
 repository: https://github.com/espressif/esp-insights.git

components/esp_diagnostics/include/esp_diagnostics.h

@@ -104,6 +104,8 @@ typedef enum {
     ESP_DIAG_DATA_TYPE_STR,      /*!< Data type string */
     ESP_DIAG_DATA_TYPE_IPv4,     /*!< Data type IPv4 address */
     ESP_DIAG_DATA_TYPE_MAC,      /*!< Data type MAC address */
+    ESP_DIAG_DATA_TYPE_NULL,     /*!< No type */
+    ESP_DIAG_DATA_TYPE_MAX,      /*!< Max type */
 } esp_diag_data_type_t;
 
 /**

components/esp_insights/CMakeLists.txt

@@ -3,6 +3,7 @@ set(srcs "src/esp_insights.c"
         "src/esp_insights_transport.c"
         "src/esp_insights_client_data.c"
         "src/esp_insights_encoder.c"
+        "src/esp_insights_cmd_resp.c"
         "src/esp_insights_cbor_decoder.c"
         "src/esp_insights_cbor_encoder.c")
 

components/esp_insights/Kconfig

@@ -41,6 +41,16 @@ menu "ESP Insights"
 
     endchoice
 
+    config ESP_INSIGHTS_CMD_RESP_ENABLED
+        depends on (ESP_INSIGHTS_ENABLED && ESP_INSIGHTS_TRANSPORT_MQTT)
+        bool "Enable command response module"
+        default n
+        help
+            Enabling this option adds control of certain insights options remotely.
+            When enabled, the available configurations, should be shown on the dashboard
+            and controllable from there.
+            Please note, the feature is only available with RainMaker MQTT nodes for now.
+
     config ESP_INSIGHTS_TRANSPORT_HTTPS_HOST
         depends on ESP_INSIGHTS_TRANSPORT_HTTPS
         string "Insights https host"

components/esp_insights/idf_component.yml

@@ -1,4 +1,4 @@
-version: "1.1.0"
+version: "1.2.0"
 description: Firmware agent for ESP Insights, which is a remote diagnostics solution to monitor the health of ESP devices in the field.
 url: https://github.com/espressif/esp-insights/tree/main/components/esp_insights
 repository: https://github.com/espressif/esp-insights.git
@@ -13,7 +13,7 @@ dependencies:
     version: "~1.0"
     override_path: '../esp_diag_data_store/'
   espressif/esp_diagnostics:
-    version: "~1.1"
+    version: ">=1.2.0"
     override_path: '../esp_diagnostics/'
   espressif/cbor:
     version: "~0.6"

components/esp_insights/include/esp_insights.h

@@ -5,6 +5,7 @@
  */
 
 #pragma once
+
 #include <stdint.h>
 #include <esp_err.h>
 #include <esp_event_base.h>
@@ -200,6 +201,53 @@ void esp_insights_disable(void);
  * @return Pointer to a NULL terminated Node ID string.
  */
 const char *esp_insights_get_node_id(void);
+
+/**
+ * @brief Check if insights reporting is enabled
+ *
+ * @return true reporting is on
+ * @return false reporting is off
+ */
+bool esp_insights_is_reporting_enabled(void);
+
+/**
+ * @brief Turn on the Insights reporting
+ *
+ * @return esp_err_t ESP_OK on success, apt error otherwise
+ */
+esp_err_t esp_insights_reporting_enable();
+
+/**
+ * @brief Turn off the Insights repoting
+ *
+ * @return esp_err_t ESP_OK on success, apt error otherwise
+ * @note meta message if changed and the boot message will still be
+ *  sent as this information is critical for Insights working with the
+ *  cloud. You may disable insight completely using esp_insights_disable
+ */
+esp_err_t esp_insights_reporting_disable();
+
+/**
+ * @brief Encode and parse the command directly using esp-insight's parser
+ *
+ * This tests only if the parser is working as expected.
+ */
+esp_err_t esp_insights_test_cmd_handler();
+
+/**
+ * @brief Enable esp-insights command-response module
+ *
+ * This API registers esp-insights command parser which when data is received,
+ * parses it to filter out insights specific data, modifies configs accordingly,
+ * and prepares and gives response data to the module
+ *
+ * The \ref esp_insights_init takes care of initializing command response and
+ * enabling the same. In cases where, only esp_insights_enable is called, e.g.,
+ * ESP Rainmaker's app_insights module, user needs to call this API, before or
+ * after \ref esp_insights_enable
+ */
+esp_err_t esp_insights_cmd_resp_enable(void);
+
 #ifdef __cplusplus
 }
 #endif