Time and Time Zone Service

This topic describes the time and time zone service, including basic concepts, features, applicable scenarios, functionality, implementation, and APIs.

Concepts

Time zone

A time zone is a region of the Earth that has the same standard time. It is used to simplify timekeeping and ensure that clocks in different areas are set to a consistent time. The Earth is divided into 24 time zones, each approximately 15 degrees longitude wide. As one moves eastward, the time increases by one hour for each time zone, while moving westward decreases the time by one hour per time zone.

The Greenwich Mean Time (GMT) corresponds to the Coordinated Universal Time (UTC) time zone 0. UTC became the official standard of world time in 1972.

Daylight saving time (DST)

DST is the practice of adjusting the clock forward by one hour during the warmer months to extend evening daylight and conserve energy. The clock is typically set forward in the spring and set back in the fall. The main purpose of DST is to make better use of daylight during the longer days of summer. By moving the clock forward by one hour, people can enjoy more daylight in the evenings.

The specific start and end dates of DST vary from country to country. There are nearly 110 countries or regions observing DST.

Features

After a device is paired and activated, set its time zone and DST based on the latitude and longitude of the mobile phone. This allows for clock synchronization and enables time-dependent features.

Scenarios

• Time display: Get the local time.
• Time conversion: Convert time between different formats.
• Scheduled tasks: Automatically adjust the time for DST, if applicable.

How it works

Activation

After the device is paired, TuyaOS will request the time zone and DST from the cloud. The device will maintain this information and provide time services accordingly. For example, request the UTC, local time, and date, and convert time.

Time synchronization

Each time the device communicates with the cloud, it requests the current UTC timestamp from the server. The device will request time synchronization in the following cases.

• The device’s UTC is slower than the server’s.
• The device’s UTC is five seconds ahead of the server’s.
• The time has not been synchronized yet. The device performs the initial synchronization after power on.

API description

Convert date and time to timestamp

Convert the date and time to a timestamp.

/**
* @brief change posix time to TIME_T, redefine the std C func mktime
*
* @param[in] tm the time in posix time format
* @return the time in TIME_T format
*/
TIME_T tal_time_mktime(IN CONST POSIX_TM_S *tm);

Convert timestamp to date and time

Convert a timestamp to the date and time.

/**
* @brief change TIME_T to posix time, redefine the std C func gmtime_r
*
* @param[in] tm the time in TIME_T format
* @param[out] result the time in posix time format
* @return the time in posix time format
*/
POSIX_TM_S *tal_time_gmtime_r(IN CONST TIME_T *tm, OUT POSIX_TM_S *result);

Get the date and time

Get the system date and time in UTC.

/**
* @brief get TuyaOS UTC time in posix time format
*
* @param[out] tm the IoTOS UTC time in posix time format
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
OPERATE_RET tal_time_get(OUT POSIX_TM_S *tm);

Get the timestamp in seconds

Get the UTC timestamp in seconds.

/**
* @brief get TuyaOS UTC time in TIME_T format
*
* @return the current second time in TIME_T format
*/
TIME_T tal_time_get_posix(VOID);

Get the timestamp in milliseconds

Get the UTC timestamp in milliseconds.

/**
* @brief get TuyaOS UTC time in SYS_TICK_T format
*
* @return the current micro-second time in SYS_TICK_T format
*/
SYS_TICK_T tal_time_get_posix_ms(VOID);

Get the system time

Get the system uptime.

/**
* @brief how long times system run
*
* @param[out] pSecTime the current time in second
* @param[out] pMsTime the current time in micro-second
* @return VOID
*/
VOID tal_time_get_system_time(OUT TIME_S *pSecTime,OUT TIME_MS *pMsTime);

Check time synchronization

Check if the device’s time is in sync with the server’s time. If the time is not synchronized, time-dependent features might not function accurately.

/**
* @brief check TuyaOS time synchronize status
*
* @return OPRT_OK on synchronized. Others on not
*/
OPERATE_RET tal_time_check_time_sync(VOID);

Get the local time

When in_time is 0, get the device’s local time. When in_time is not 0, convert in_time to local time.

The local time is calculated taking into account the time zone and DST.

/**
* @brief get TuyaOS local time (local, contains the time zone and summer time zone)
*
* @param[in] in_time the time need translate
* @param[out] tm the local time in posix format
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*
* @note if in_time is 0, return the IoTOS local time, otherwise, translate the in_time to
* local time
*/
OPERATE_RET tal_time_get_local_time_custom(IN TIME_T in_time, OUT POSIX_TM_S *tm);

Example

OPERATE_RET sample_delaywork_service_test()
{
    // Get the current time.
    POSIX_TM_S tm;
    memset(&tm, 0, SIZEOF(tm));

    // Current local time
    tal_time_get_local_time_custom(0, &tm);
    PR_DEBUG("current local time in sec: [%02d-%02d %02d:%02d:%02d]",
                    tm.tm_mon+1, tm.tm_mday, tm.tm_hour, tm.tm_min, tm.tm_sec);


    // Current local time in milliseconds
    SYS_TICK_T time_ms = tal_time_get_posix_ms();
    TIME_T sec = (TIME_T)(time_ms / 1000);
    UINT_T ms  = (UINT_T)(time_ms % 1000);
    tal_time_get_local_time_custom(sec, &tm);
    PR_DEBUG("current local time in ms:[%02d-%02d %02d:%02d:%02d:%d]",tm.tm_mon+1, tm.tm_mday, tm.tm_hour, tm.tm_min, tm.tm_sec, ms);

    return OPRT_OK;
}