esp_rmaker_core: Add support for triggering phone app notifications

Supports two types of notifications
1. Parameter updates
2. Alerts

Please check the API docs for more information

Author: shahpiyushv

components/esp_rainmaker/include/esp_rmaker_core.h

@@ -24,7 +24,8 @@ extern "C"
 
 #define ESP_RMAKER_CONFIG_VERSION    "2020-03-20"
 
-#define MAX_VERSION_STRING_LEN  16
+/* Maximum length of the alert message that can be passed to esp_rmaker_raise_alert() */
+#define ESP_RMAKER_MAX_ALERT_LEN    100
 
 /** @cond **/
 /** ESP RainMaker Event Base */
@@ -741,6 +742,46 @@ esp_err_t esp_rmaker_param_add_array_max_count(const esp_rmaker_param_t *param,
  */
 esp_err_t esp_rmaker_param_update_and_report(const esp_rmaker_param_t *param, esp_rmaker_param_val_t val);
 
+/** Update and notify a parameter
+ *
+ * Calling this API will update the parameter and report it to ESP RainMaker cloud similar to
+ * esp_rmaker_param_update_and_report(). However, additionally, it will also trigger a notification
+ * on the phone apps (if enabled).
+ *
+ * @note This should be used only when some local change requires explicit notification even when the
+ * phone app is in background, not otherwise.
+ * Eg. Alarm got triggered, temperature exceeded some threshold, etc.
+ *
+ * Alternatively, the esp_rmaker_raise_alert() API can also be used to trigger notification
+ * on the phone apps with pre-formatted text.
+ *
+ * @param[in] param Parameter handle.
+ * @param[in] val New value of the parameter.
+ *
+ * @return ESP_OK if the parameter was updated successfully.
+ * @return error in case of failure.
+ */
+esp_err_t esp_rmaker_param_update_and_notify(const esp_rmaker_param_t *param, esp_rmaker_param_val_t val);
+
+/** Trigger an alert on the phone app
+ *
+ * This API will trigger a notification alert on the phone apps (if enabled) using the formatted text
+ * provided. Note that this does not send a notification directly to the phone, but reports the alert
+ * to the ESP RainMaker cloud which then uses the Notification framework to send notifications to the
+ * phone apps. The value does not get stored anywhere, nor is it linked to any node parameters.
+ *
+ * @note This should be used only if some event requires explicitly alerting the user even when the
+ * phone app is in background, not otherwise.
+ * Eg. "Motion Detected", "Fire alarm triggered"
+ *
+ * @param[in] alert_str NULL terminated pre-formatted alert string.
+ *     Maximum length can be ESP_RMAKER_MAX_ALERT_LEN, excluding NULL character.
+ *
+ * @return ESP_OK on success.
+ * @return error in case of failure.
+ */
+esp_err_t esp_rmaker_raise_alert(const char *alert_str);
+
 /** Get parameter name from handle
  *
  * @param[in] param Parameter handle.

components/esp_rainmaker/src/core/esp_rmaker_internal.h

@@ -18,7 +18,8 @@
 #include <json_generator.h>
 #include <esp_rmaker_core.h>
 
-#define RMAKER_PARAM_FLAG_VALUE_CHANGE   0x01
+#define RMAKER_PARAM_FLAG_VALUE_CHANGE   (1 << 0)
+#define RMAKER_PARAM_FLAG_VALUE_NOTIFY   (1 << 1)
 #define ESP_RMAKER_NVS_PART_NAME            "nvs"
 
 typedef enum {

components/esp_rainmaker/src/core/esp_rmaker_param.c

@@ -30,9 +30,13 @@
 #define NODE_PARAMS_LOCAL_INIT_TOPIC_SUFFIX     "params/local/init"
 #define NODE_PARAMS_REMOTE_TOPIC_SUFFIX         "params/remote"
 #define TIME_SERIES_DATA_TOPIC_SUFFIX           "params/ts_data"
+#define NODE_PARAMS_ALERT_TOPIC_SUFFIX          "alert"
+
+#define ESP_RMAKER_ALERT_KEY                    "esp.alert.str"
 
 #define MAX_PUBLISH_TOPIC_LEN           64
-#define RMAKER_PARAMS_SIZE_MARGIN       50
+#define RMAKER_PARAMS_SIZE_MARGIN       50 /* To accommodate for changes in param values while creating JSON */
+#define RMAKER_ALERT_STR_MARGIN         25 /* To accommodate rest of the alert payload {"esp.alert.str":""}  */
 
 static size_t max_node_params_size = CONFIG_ESP_RMAKER_MAX_PARAM_DATA_SIZE;
 /* This buffer will be allocated once and will be reused for all param updates.
@@ -210,17 +214,25 @@ static esp_err_t esp_rmaker_allocate_and_populate_params(uint8_t flags, bool res
     return err;
 }
 
-esp_err_t esp_rmaker_report_param_internal(void)
+static esp_err_t esp_rmaker_report_param_internal(uint8_t flags)
 {
     esp_err_t err = esp_rmaker_allocate_and_populate_params(RMAKER_PARAM_FLAG_VALUE_CHANGE, true);
     if (err == ESP_OK) {
         /* Just checking if there are indeed any params to report by comparing with a decent enough
          * length as even the smallest possible data, Eg. '{"d":{"p":0}}' will be > 10 bytes.
          */
         if (strlen(node_params_buf) > 10) {
-            snprintf(publish_topic, sizeof(publish_topic), "node/%s/%s",
-                    esp_rmaker_get_node_id(), NODE_PARAMS_LOCAL_TOPIC_SUFFIX);
-            ESP_LOGI(TAG, "Reporting params: %s", node_params_buf);
+            if (flags == RMAKER_PARAM_FLAG_VALUE_CHANGE) {
+                snprintf(publish_topic, sizeof(publish_topic), "node/%s/%s",
+                        esp_rmaker_get_node_id(), NODE_PARAMS_LOCAL_TOPIC_SUFFIX);
+                ESP_LOGI(TAG, "Reporting params: %s", node_params_buf);
+            } else if (flags == RMAKER_PARAM_FLAG_VALUE_NOTIFY) {
+                snprintf(publish_topic, sizeof(publish_topic), "node/%s/%s",
+                        esp_rmaker_get_node_id(), NODE_PARAMS_ALERT_TOPIC_SUFFIX);
+                ESP_LOGI(TAG, "Notifying params: %s", node_params_buf);
+            } else {
+                return ESP_FAIL;
+            }
             if (esp_rmaker_params_mqtt_init_done) {
                 esp_rmaker_mqtt_publish(publish_topic, node_params_buf, strlen(node_params_buf), RMAKER_MQTT_QOS1, NULL);
             } else {
@@ -688,7 +700,21 @@ esp_err_t esp_rmaker_param_report(const esp_rmaker_param_t *param)
         return ESP_ERR_INVALID_ARG;
     }
     ((_esp_rmaker_param_t *)param)->flags |= RMAKER_PARAM_FLAG_VALUE_CHANGE;
-    return esp_rmaker_report_param_internal();
+    return esp_rmaker_report_param_internal(RMAKER_PARAM_FLAG_VALUE_CHANGE);
+}
+
+esp_err_t esp_rmaker_param_notify(const esp_rmaker_param_t *param)
+{
+    if (!param) {
+        ESP_LOGE(TAG, "Param handle cannot be NULL.");
+        return ESP_ERR_INVALID_ARG;
+    }
+    ((_esp_rmaker_param_t *)param)->flags |= (RMAKER_PARAM_FLAG_VALUE_CHANGE | RMAKER_PARAM_FLAG_VALUE_NOTIFY);
+    esp_err_t err = esp_rmaker_report_param_internal(RMAKER_PARAM_FLAG_VALUE_NOTIFY);
+    if (err != ESP_OK) {
+        ESP_LOGW(TAG, "Failed to report parameter");
+    }
+    return esp_rmaker_report_param_internal(RMAKER_PARAM_FLAG_VALUE_CHANGE);
 }
 
 esp_err_t esp_rmaker_param_update_and_report(const esp_rmaker_param_t *param, esp_rmaker_param_val_t val)
@@ -701,6 +727,16 @@ esp_err_t esp_rmaker_param_update_and_report(const esp_rmaker_param_t *param, es
     return err;
 }
 
+esp_err_t esp_rmaker_param_update_and_notify(const esp_rmaker_param_t *param, esp_rmaker_param_val_t val)
+{
+    esp_err_t err = esp_rmaker_param_update(param, val);
+    /** Report parameter only if the RainMaker has started */
+    if ((err == ESP_OK) && (esp_rmaker_get_state() == ESP_RMAKER_STATE_STARTED)) {
+        err = esp_rmaker_param_notify(param);
+    }
+    return err;
+}
+
 char *esp_rmaker_param_get_name(const esp_rmaker_param_t *param)
 {
     if (!param) {
@@ -718,3 +754,15 @@ char *esp_rmaker_param_get_type(const esp_rmaker_param_t *param)
     }
     return ((_esp_rmaker_param_t *)param)->type;
 }
+
+esp_err_t esp_rmaker_raise_alert(const char *alert_str)
+{
+    char msg[ESP_RMAKER_MAX_ALERT_LEN + 1]; /* + 1 for NULL terminattion */
+    strlcpy(msg, alert_str, sizeof(msg));
+    char buf[ESP_RMAKER_MAX_ALERT_LEN + RMAKER_ALERT_STR_MARGIN];
+    snprintf(buf, sizeof(buf), "{\"%s\":\"%s\"}", ESP_RMAKER_ALERT_KEY, msg);
+    snprintf(publish_topic, sizeof(publish_topic), "node/%s/%s",
+            esp_rmaker_get_node_id(), NODE_PARAMS_ALERT_TOPIC_SUFFIX);
+    ESP_LOGI(TAG, "Reporting alert: %s", buf);
+    return esp_rmaker_mqtt_publish(publish_topic, buf, strlen(buf), RMAKER_MQTT_QOS1, NULL);
+}