Merge branch 'task/group-topics' into 'master'

esp_rmaker_groups: Add handling for group ids for direct MQTT messaging

See merge request app-frameworks/esp-rainmaker!607

Author: shahpiyushv

components/esp_rainmaker/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.8.6
+
+### New Feature
+
+- Added Groups service to enable direct MQTT communication between nodes and clients (phone apps/controllers).
+    - Setting group_id via the Groups service routes local param updates to group-specific topics
+      (`node/<node_id>/params/local/<group_id>`) for lower latency.
+    - Also added `esp_rmaker_publish_direct()` API to publish messages on `node/<node_id>/direct/params/local/<group_id>`
+      for direct client-to-node communication, bypassing cloud processing for reduced cost and latency.
+    - Clients can also publish param updates directly to `node/<node_id>/params/remote/<group_id>` instead of
+      using the set params API.
+
 ## 1.8.5
 
 ### Changes

components/esp_rainmaker/CMakeLists.txt

@@ -12,6 +12,7 @@ set(core_srcs "src/core/esp_rmaker_core.c"
         "src/core/esp_rmaker_node_auth.c"
         "src/core/esp_rmaker_schedule.c"
         "src/core/esp_rmaker_scenes.c"
+        "src/core/esp_rmaker_groups.c"
         "src/core/esp_rmaker_secure_boot_digest.c"
         "src/core/esp_rmaker_aws_credentials.c"
     )

components/esp_rainmaker/idf_component.yml

@@ -1,4 +1,5 @@
-version: "1.8.5"
+## IDF Component Manager Manifest File
+version: "1.8.6"
 description: ESP RainMaker firmware agent
 url: https://github.com/espressif/esp-rainmaker/tree/master/components/esp_rainmaker
 repository: https://github.com/espressif/esp-rainmaker.git

components/esp_rainmaker/include/esp_rmaker_core.h

@@ -1181,6 +1181,33 @@ esp_rmaker_aws_credentials_t* esp_rmaker_get_aws_security_token(const char *role
  */
 void esp_rmaker_free_aws_credentials(esp_rmaker_aws_credentials_t *credentials);
 
+/** Store group_id in NVS
+ *
+ * @param[in] group_id The group_id to store
+ *
+ * @return ESP_OK on success
+ * @return error in case of failure
+ */
+esp_err_t esp_rmaker_store_group_id(const char *group_id);
+
+/** Retrieve group_id from NVS
+ *
+ * @param[out] group_id The group_id to retrieve. Should be freed by the caller.
+ *
+ * @return ESP_OK on success
+ * @return error in case of failure
+ */
+esp_err_t esp_rmaker_get_stored_group_id(char **group_id);
+
+/**
+ * @brief Publish a string message to direct params topic
+ *
+ * @param[in] message The message to publish
+ *
+ * @return ESP_OK on success
+ */
+esp_err_t esp_rmaker_publish_direct(const char *message);
+
 #ifdef __cplusplus
 }
 #endif

components/esp_rainmaker/include/esp_rmaker_groups.h

@@ -0,0 +1,48 @@
+/*
+ * SPDX-FileCopyrightText: 2020-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+/** Enable Groups Service
+ *
+ * This API enables the groups service for the node. This allows phone apps to
+ * set the parent group ID (pgrp_id) in which the node is added.
+ *
+ * Once set, all local params will be reported on
+ * node/<node_id>/params/local/<pgrp_id> instead of node/<node_id>/params/local/
+ *
+ * Additionally, application code can use the esp_rmaker_publish_direct()
+ * API to publish any message on node/<node_id>/direct/params/local/<pgrp_id>
+ *
+ * Phone apps can subscribe to these topics to get these messages directly
+ * from the MQTT broker:
+ * - node/+/params/local/<pgrp_id>
+ * - node/+/direct/params/local/<pgrp_id>
+ *
+ * For local params update, this change helps to improve the latency
+ * of param reporting.
+ *
+ * The direct reporting allows to bypass the cloud side processing to send
+ * messages directly to phone apps at very low cost.
+ *
+ * Phone apps can also publish param updates directly to
+ * node/<node_id>/params/remote/<pgrp_id> instead of using the set params API.
+ *
+ * @note This API should be called after esp_rmaker_node_init() but before esp_rmaker_start().
+ *
+ * @return ESP_OK on success.
+ * @return error in case of failure.
+ */
+esp_err_t esp_rmaker_groups_service_enable(void);
+
+#ifdef __cplusplus
+}
+#endif

components/esp_rainmaker/include/esp_rmaker_standard_params.h

@@ -380,11 +380,12 @@ esp_rmaker_param_t *esp_rmaker_base_url_param_create(const char *param_name);
  * This will create the standard Group ID parameter.
  *
  * @param[in] param_name Name of the parameter
+ * @param[in] val Default Value of the parameter
  *
  * @return Parameter handle on success.
  * @return NULL in case of failures.
  */
-esp_rmaker_param_t *esp_rmaker_group_id_param_create(const char *param_name);
+esp_rmaker_param_t *esp_rmaker_group_id_param_create(const char *param_name, const char *val);
 
 #ifdef __cplusplus
 }

components/esp_rainmaker/include/esp_rmaker_standard_services.h

@@ -135,6 +135,21 @@ esp_rmaker_device_t *esp_rmaker_create_local_control_service(const char *serv_na
  */
 esp_rmaker_device_t *esp_rmaker_create_user_auth_service(const char *serv_name, esp_rmaker_device_bulk_write_cb_t bulk_write_cb, esp_rmaker_device_bulk_read_cb_t read_cb, void *priv_data);
 
+/** Create a standard Groups service
+ *
+ * This creates a Groups service with the mandatory parameters. The default parameter names will be used.
+ * Refer \ref esp_rmaker_standard_params.h for default names.
+ *
+ * @param[in] serv_name The unique service name
+ * @param[in] write_cb Bulk write callback.
+ * @param[in] priv_data (Optional) Private data associated with the service. This should stay
+ * allocated throughout the lifetime of the service.
+ *
+ * @return service_handle on success.
+ * @return NULL in case of any error.
+ */
+esp_rmaker_device_t *esp_rmaker_create_groups_service(const char *serv_name, esp_rmaker_device_bulk_write_cb_t write_cb, char *group_id, void *priv_data);
+
 #ifdef __cplusplus
 }
 #endif

components/esp_rainmaker/include/esp_rmaker_standard_types.h

@@ -67,8 +67,6 @@ extern "C"
 #define ESP_RMAKER_PARAM_BASE_URL       "esp.param.base-url"
 #define ESP_RMAKER_PARAM_GROUP_ID       "esp.param.group-id"
 
-
-
 /********** STANDARD DEVICE TYPES **********/
 
 #define ESP_RMAKER_DEVICE_SWITCH        "esp.device.switch"
@@ -101,6 +99,7 @@ extern "C"
 #define ESP_RMAKER_SERVICE_SYSTEM       "esp.service.system"
 #define ESP_RMAKER_SERVICE_LOCAL_CONTROL    "esp.service.local_control"
 #define ESP_RMAKER_SERVICE_USER_AUTH        "esp.service.rmaker-user-auth"
+#define ESP_RMAKER_SERVICE_GROUPS       "esp.service.groups"
 
 #ifdef __cplusplus
 }

components/esp_rainmaker/src/core/esp_rmaker_groups.c

@@ -0,0 +1,55 @@
+/*
+ * SPDX-FileCopyrightText: 2020-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <string.h>
+#include <esp_log.h>
+#include <esp_err.h>
+#include <esp_rmaker_core.h>
+#include <esp_rmaker_standard_services.h>
+#include <esp_rmaker_standard_params.h>
+#include <esp_rmaker_groups.h>
+#include "esp_rmaker_internal.h"
+
+static const char *TAG = "esp_rmaker_groups";
+
+static esp_err_t groups_write_cb(const esp_rmaker_device_t *device, const esp_rmaker_param_write_req_t write_req[],
+        uint8_t count, void *priv_data, esp_rmaker_write_ctx_t *ctx)
+{
+    if (ctx) {
+        ESP_LOGI(TAG, "Received write request via : %s", esp_rmaker_device_cb_src_to_str(ctx->src));
+    }
+    for (uint8_t i = 0; i < count; i++) {
+        if (strcmp(esp_rmaker_param_get_name(write_req[i].param), ESP_RMAKER_DEF_GROUP_ID_NAME) == 0) {
+            esp_rmaker_param_update(write_req[i].param, write_req[i].val);
+            esp_rmaker_register_for_group_params(write_req[i].val.val.s);
+        }
+    }
+    return ESP_OK;
+}
+
+esp_err_t esp_rmaker_groups_service_enable(void)
+{
+    char *group_id = NULL;
+    esp_rmaker_device_t *service = NULL;
+    esp_err_t err = esp_rmaker_get_stored_group_id(&group_id);
+    if (err == ESP_OK && group_id) {
+        service = esp_rmaker_create_groups_service("Groups", groups_write_cb, group_id, NULL);
+        free(group_id);
+    } else {
+        service = esp_rmaker_create_groups_service("Groups", groups_write_cb, "", NULL);
+    }
+    if (!service) {
+        return ESP_ERR_NO_MEM;
+    }
+    err = esp_rmaker_node_add_device(esp_rmaker_get_node(), service);
+    if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to add Groups service to node");
+        esp_rmaker_device_delete(service);
+        return err;
+    }
+    ESP_LOGD(TAG, "Groups Service Enabled");
+    return ESP_OK;
+}

components/esp_rainmaker/src/core/esp_rmaker_internal.h

@@ -135,3 +135,15 @@ static inline esp_err_t esp_rmaker_post_event(esp_rmaker_event_t event_id, void*
 }
 esp_rmaker_state_t esp_rmaker_get_state(void);
 esp_err_t esp_rmaker_cmd_response_enable(void);
+
+/** Register for group parameter updates
+ *
+ * This function handles group subscriptions and manages MQTT topics for group communication.
+ * If there's an existing group subscription, it will be unsubscribed before subscribing to the new group.
+ *
+ * @param[in] pgrp The group identifier string
+ *
+ * @return ESP_OK on success
+ * @return error in case of failure
+ */
+esp_err_t esp_rmaker_register_for_group_params(const char *pgrp);