Merge branch 'feature/timezone' into 'master'

esp_rmaker_time_sync: Add support for POSIX timezones

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

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

components/esp_rainmaker/src/console/esp_rmaker_commands.c

@@ -33,6 +33,7 @@
 
 #include <esp_rmaker_core.h>
 #include <esp_rmaker_user_mapping.h>
+#include <esp_rmaker_utils.h>
 
 #include <esp_rmaker_console_internal.h>
 
@@ -352,11 +353,61 @@ static void register_wifi_prov()
     esp_console_cmd_register(&cmd);
 }
 
+static int local_time_cli_handler(int argc, char *argv[])
+{
+    char local_time[64];
+    if (esp_rmaker_get_local_time_str(local_time, sizeof(local_time)) == ESP_OK) {
+        printf("%s: Current local time: %s\n", TAG, local_time);
+    } else {
+        printf("%s: Current local time (truncated): %s\n", TAG, local_time);
+    }
+    return ESP_OK;
+}
+
+static int tz_set_cli_handler(int argc, char *argv[])
+{
+    if (argc < 2) {
+        printf("%s: Invalid Usage.\n", TAG);
+        return ESP_ERR_INVALID_ARG;
+    }
+    if (strcmp(argv[1], "posix") == 0) {
+        if (argv[2]) {
+            esp_rmaker_time_set_timezone_posix(argv[2]);
+        } else {
+            printf("%s: Invalid Usage.\n", TAG);
+            return ESP_ERR_INVALID_ARG;
+        }
+    } else {
+        esp_rmaker_time_set_timezone(argv[1]);
+    }
+    return ESP_OK;
+}
+
+static void register_time_commands()
+{
+    const esp_console_cmd_t local_time_cmd = {
+        .command = "local-time",
+        .help = "Get the local time of device.",
+        .func = &local_time_cli_handler,
+    };
+    ESP_LOGI(TAG, "Registering command: %s", local_time_cmd.command);
+    esp_console_cmd_register(&local_time_cmd);
+
+    const esp_console_cmd_t tz_set_cmd = {
+        .command = "tz-set",
+        .help = "Set Timezone. Usage: tz-set [posix] <tz_string>.",
+        .func = &tz_set_cli_handler,
+    };
+    ESP_LOGI(TAG, "Registering command: %s", tz_set_cmd.command);
+    esp_console_cmd_register(&tz_set_cmd);
+}
+
 void register_commands()
 {
     register_generic_debug_commands();
     register_reset_to_factory();
     register_user_node_mapping();
     register_get_node_id();
     register_wifi_prov();
+    register_time_commands();
 }