TIME (v1.1)¶

/**
 * @file tiny_time.h
 * @author SHUAIWEN CUI (SHUAIWEN001@e.ntu.edu.sg)
 * @brief Submodule for TinyToolbox - header file
 * @version 1.1
 * @date 2025-04-10
 * @copyright Copyright (c) 2025
 *
 */

#pragma once

/* ================================ DEPENDENCIES ================================ */
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>
#include <time.h>
#include <sys/time.h>
#include "esp_log.h"
#include "esp_timer.h"
#include "esp_sntp.h"
#include "node_rtc.h"
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"

#ifdef __cplusplus
extern "C"
{
#endif

/* ================================ DEFINITIONS ================================= */

typedef int64_t TinyTimeMark_t;

typedef struct TinyDateTime_t
{
    int     year;
    int     month;
    int     day;
    int     hour;
    int     minute;
    int     second;
    int32_t microsecond;
} TinyDateTime_t;

typedef struct TinyNtpSync_t
{
    uint32_t unix_sec;
    uint64_t local_us_anchor;
    uint64_t last_sync_time_us;
    uint8_t  sync_quality;
    bool     is_synced;
} TinyNtpSync_t;

/* ================================ FUNCTIONS =================================== */

/* LOCAL RUNNING TIME */
TinyTimeMark_t tiny_get_running_time(void);

/* WORLD CURRENT TIME - SNTP */
void sync_time_with_timezone(const char *timezone_str);

/* WORLD CURRENT TIME - GET */
TinyDateTime_t tiny_get_current_datetime(bool print_flag);

/* UNIX TIMESTAMP CONVERSION */
bool     tiny_unix_to_datetime(uint32_t unix_sec, TinyDateTime_t *dt);
bool     tiny_unix_us_to_datetime(uint64_t unix_us, TinyDateTime_t *dt);
uint32_t tiny_datetime_to_unix(const TinyDateTime_t *dt);
bool     tiny_is_valid_datetime(const TinyDateTime_t *dt);

static inline bool tiny_is_leap_year(uint16_t year)
{
    return (year % 4 == 0 && year % 100 != 0) || (year % 400 == 0);
}

/* TIME FORMATTING AND DISPLAY */
int tiny_format_datetime_iso8601(const TinyDateTime_t *dt, char *buf, size_t buflen);
int tiny_format_datetime_us(const TinyDateTime_t *dt, char *buf, size_t buflen);
int tiny_format_datetime_ms(const TinyDateTime_t *dt, char *buf, size_t buflen);
int tiny_format_unix_sec(uint32_t unix_sec, char *buf, size_t buflen);
int tiny_format_unix_us(uint64_t unix_us, char *buf, size_t buflen);
int tiny_format_duration_us(uint64_t duration_us, char *buf, size_t buflen);

/* NTP SYNCHRONIZATION HOOK */
void tiny_ntp_set_sync_hook(bool (*hook)(uint32_t unix_sec));

/* NTP SYNCHRONIZATION */
bool     tiny_ntp_record_sync(uint32_t unix_sec);
uint64_t tiny_ntp_get_world_time_us(void);
bool     tiny_ntp_get_sync_info(TinyNtpSync_t *sync_info);
bool     tiny_ntp_is_synced(void);
void     tiny_ntp_set_quality(uint8_t quality);
bool     tiny_ntp_get_datetime_us(TinyDateTime_t *dt);

#ifdef __cplusplus
}
#endif