esp_rmaker_time_sync: Add support for POSIX timezones

Raw APIs as well as a RainMaker service have been provided to manage timezones.
Timezone information is stored in NVS so that it stays even across reboots.

A config option CONFIG_ESP_RMAKER_DEF_TIMEZONE has also been added to set the
default timezone.

Author: shahpiyushv

components/esp_rainmaker/CMakeLists.txt

@@ -6,6 +6,7 @@ set(core_srcs "src/core/esp_rmaker_core.c"
         "src/core/esp_rmaker_node_config.c"
         "src/core/esp_rmaker_client_data.c"
         "src/core/esp_rmaker_time_sync.c"
+        "src/core/esp_rmaker_timezone.c"
         "src/core/esp_rmaker_storage.c"
         "src/core/esp_rmaker_user_mapping.pb-c.c"
         "src/core/esp_rmaker_utils.c"

components/esp_rainmaker/Kconfig.projbuild

@@ -85,6 +85,14 @@ menu "ESP RainMaker Config"
         default 1 if ESP_RMAKER_MQTT_PORT_443
         default 2 if ESP_RMAKER_MQTT_PORT_8883
 
+    config ESP_RMAKER_DEF_TIMEZONE
+        string "Default Timezone"
+        default ""
+        help
+            Default Timezone to use. Eg. "Asia/Shanghai", "America/Los_Angeles".
+            Check documentation for complete list of valid values. This value
+            will be used only if no timezone is set using the C APIs.
+
     config ESP_RMAKER_SNTP_SERVER_NAME
         string "ESP RainMaker SNTP Server Name"
         default "pool.ntp.org"

components/esp_rainmaker/include/esp_rmaker_standard_params.h

@@ -41,6 +41,8 @@ extern "C"
 #define ESP_RMAKER_DEF_OTA_STATUS_NAME      "status"
 #define ESP_RMAKER_DEF_OTA_INFO_NAME        "info"
 #define ESP_RMAKER_DEF_OTA_URL_NAME         "url"
+#define ESP_RMAKER_DEF_TIMEZONE_NAME        "tz"
+#define ESP_RMAKER_DEF_TIMEZONE_POSIX_NAME  "tz_posix"
 
 /**
  * Create standard name param
@@ -216,6 +218,31 @@ esp_rmaker_param_t *esp_rmaker_ota_info_param_create(const char *param_name);
  */
 esp_rmaker_param_t *esp_rmaker_ota_url_param_create(const char *param_name);
 
+/**
+ * Create standard Timezone param
+ *
+ * This will create the standard timezone parameter.
+ *
+ * @param[in] param_name Name of the parameter
+ * @param[in] val Default Value of the parameter (Eg. "Asia/Shanghai"). Can be kept NULL.
+ *
+ * @return Parameter handle on success.
+ * @return NULL in case of failures.
+ */
+esp_rmaker_param_t *esp_rmaker_timezone_param_create(const char *param_name, const char *val);
+
+/**
+ * Create standard POSIX Timezone param
+ *
+ * This will create the standard posix timezone parameter.
+ *
+ * @param[in] param_name Name of the parameter
+ * @param[in] val Default Value of the parameter (Eg. "CST-8"). Can be kept NULL.
+ *
+ * @return Parameter handle on success.
+ * @return NULL in case of failures.
+ */
+esp_rmaker_param_t *esp_rmaker_timezone_posix_param_create(const char *param_name, const char *val);
 #ifdef __cplusplus
 }
 #endif

components/esp_rainmaker/include/esp_rmaker_standard_services.h

@@ -37,6 +37,23 @@ extern "C"
  */
 esp_rmaker_device_t *esp_rmaker_ota_service_create(const char *serv_name, void *priv_data);
 
+/** Create a standard OTA service
+ *
+ * This creates an OTA 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] timezone Default value of timezone string (Eg. "Asia/Shanghai"). Can be kept NULL.
+ * @param[in] timezone_posix Default value of posix timezone string (Eg. "CST-8"). Can be kept NULL.
+ * @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_time_service_create(const char *serv_name, const char *timezone,
+        const char *timezone_posix, void *priv_data);
+
 #ifdef __cplusplus
 }
 #endif

components/esp_rainmaker/include/esp_rmaker_standard_types.h

@@ -41,7 +41,8 @@ extern "C"
 #define ESP_RMAKER_PARAM_OTA_STATUS     "esp.param.ota_status"
 #define ESP_RMAKER_PARAM_OTA_INFO       "esp.param.ota_info"
 #define ESP_RMAKER_PARAM_OTA_URL        "esp.param.ota_url"
-
+#define ESP_RMAKER_PARAM_TIMEZONE       "esp.param.tz"
+#define ESP_RMAKER_PARAM_TIMEZONE_POSIX       "esp.param.tz_posix"
 
 /********** STANDARD DEVICE TYPES **********/
 
@@ -52,6 +53,7 @@ extern "C"
 
 /********** STANDARD SERVICE TYPES **********/
 #define ESP_RMAKER_SERVICE_OTA          "esp.service.ota"
+#define ESP_RMAKER_SERVICE_TIME         "esp.service.time"
 
 #ifdef __cplusplus
 }

components/esp_rainmaker/include/esp_rmaker_utils.h

@@ -13,6 +13,7 @@
 // limitations under the License.
 #pragma once
 #include <stdint.h>
+#include <sntp.h>
 #include <esp_err.h>
 
 #ifdef __cplusplus
@@ -23,6 +24,12 @@ extern "C"
 typedef struct esp_rmaker_time_config {
     /** If not specified, then 'CONFIG_ESP_RMAKER_SNTP_SERVER_NAME' is used as the SNTP server. */
     char *sntp_server_name;
+    /** Optional callback to invoke, whenever time is synchronised. This will be called
+     * periodically as per the SNTP polling interval (which is 60min by default).
+     * If kept NULL, the default callback will be invoked, which will just print the
+     * current local time.
+     */
+    sntp_sync_time_cb_t sync_time_cb;
 } esp_rmaker_time_config_t;
 
 /** Reboot the chip after a delay
@@ -104,6 +111,64 @@ bool esp_rmaker_time_check(void);
  */
 esp_err_t esp_rmaker_time_wait_for_sync(uint32_t ticks_to_wait);
 
+/** Set POSIX timezone
+ *
+ * Set the timezone (TZ environment variable) as per the POSIX format
+ * specified in the [GNU libc documentation](https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html).
+ * Eg. For China: "CST-8"
+ *     For US Pacific Time (including daylight saving information): "PST8PDT,M3.2.0,M11.1.0"
+ *
+ * @param[in] tz_posix NULL terminated TZ POSIX string
+ *
+ * @return ESP_OK on success
+ * @return error on failure
+ */
+esp_err_t esp_rmaker_time_set_timezone_posix(const char *tz_posix);
+
+/** Set timezone location string
+ *
+ * Set the timezone as a user friendly location string.
+ * Check [here](https://rainmaker.espressif.com/docs/time-service.html) for a list of valid values.
+ *
+ * Eg. For China: "Asia/Shanghai"
+ *     For US Pacific Time: "America/Los_Angeles"
+ *
+ * @note Setting timezone using this API internally also sets the POSIX timezone string.
+ *
+ * @param[in] tz NULL terminated Timezone location string
+ *
+ * @return ESP_OK on success
+ * @return error on failure
+ */
+esp_err_t esp_rmaker_time_set_timezone(const char *tz);
+
+/** Enable Timezone Service
+ *
+ * This enables the ESP RainMaker standard timezone service which can be used to set
+ * timezone, either in POSIX or location string format. Please refer the specifications
+ * for additional details.
+ *
+ * @return ESP_OK on success
+ * @return error on failure
+ */
+esp_err_t esp_rmaker_timezone_service_enable(void);
+
+/** Get printable local time string
+ *
+ * Get a printable local time string, with information of timezone and Daylight Saving.
+ * Eg. "Tue Sep  1 09:04:38 2020 -0400[EDT], DST: Yes"
+ * "Tue Sep  1 21:04:04 2020 +0800[CST], DST: No"
+ *
+ *
+ * @param[out] buf Pointer to a pre-allocated buffer into which the time string will
+ *                  be populated.
+ * @param[in] buf_len Length of the above buffer.
+ *
+ * @return ESP_OK on success
+ * @return error on failure
+ */
+esp_err_t esp_rmaker_get_local_time_str(char *buf, size_t buf_len);
+
 #ifdef __cplusplus
 }
 #endif