Time Service

This topic describes how the time service works on Bluetooth sub-devices.

Overview

Concepts

Bluetooth devices support local time service. The clock starts counting from zero when the device is powered on, with a precision of one second. The accuracy depends on the precision of the chip’s internal or external low-frequency oscillator.

After the device is paired with the Tuya-enabled app, it will request time sync from the app. Based on the requested time type, the app can return its local time or the server time. Then, the device will run the local time service according to the obtained time standard.

Features

The time service includes three modules: RTC timekeeping, UTC conversion, and time sync, as shown below.

RTC timekeeping is implemented by tal_rtc.c, including chip platform-related RTC timekeeping services. UTC conversion is implemented by tal_utc, including timestamp and time format conversion. The time sync module is used to sync time with the cloud or app.

Data structure

tuya_ble_timestamp_data_t

typedef struct {
    UINT8_T timestamp_string[14];
    INT16_T time_zone;   // Multiply actual time zone by 100.
} tuya_ble_timestamp_data_t;

• timestamp_string: 13-byte Unix timestamp string in milliseconds.

• time_zone: The time zone. Its value is a signed integer and 100 times the actual time zone. For example, 800 represents GMT+8.

tuya_ble_time_noraml_data_t

typedef struct {
    UINT16_T nYear;
    UINT8_T nMonth;
    UINT8_T nDay;
    UINT8_T nHour;
    UINT8_T nMin;
    UINT8_T nSec;
    UINT8_T DayIndex; /* 0 = Sunday */
    INT16_T time_zone;   // Multiply actual time zone by 100.
} tuya_ble_time_noraml_data_t;

• nYear: Year
• nMonth: Month
• nDay: Day
• nHour: Hour
• nMin: Minute
• nSec: Second
• DayIndex: Day of week
• time_zone: The time zone. Its value is a signed integer and 100 times the actual time zone. For example, 800 represents GMT+8.

tuya_ble_timestamp_with_dst_data_t

typedef struct {
    UINT32_T timestamp;
    INT16_T time_zone;   /**< Multiply actual time zone by 100. */
    UINT8_T n_years_dst; /**< how many years of daylight saving time. */
    UINT8_T *p_data;      /**< the point of dst data. */
    UINT16_T data_len;      /**< dst data length. */
} tuya_ble_timestamp_with_dst_data_t;

• timestamp: The Unix timestamp.
• time_zone: The time zone. Its value is a signed integer and 100 times the actual time zone. For example, 800 represents GMT+8.
• n_years_dst: The upcoming years with the daylight saving time (DST) data. 0: No DST data. 1: DST data for one year.
• p_data: The DST data.
• data_len: The length of the DST data.

No.	Length	Field	Description
1 to 10	10	start_1	The DST start time in the first year, a 10-byte Unix timestamp string.
11 to 20	10	end_1	The DST end time in the first year, a 10-byte Unix timestamp string. The value must be greater than the current timestamp.
…	…	…	…
…	10	start_n	The DST start time in the n year, a 10-byte Unix timestamp string.
…	10	end_n	The DST end time in the n year, a 10-byte Unix timestamp string.

Description:

• If the app fails to retrieve the time from the cloud, it should return all zeros (zeros in binary).
• The first set of DST data (start_1 and end_1) in the response packet can be for the current year or the following year. If the current timestamp falls before or during DST for the current year, the first set of DST data corresponds to that year. Otherwise, it is for the following year.

tal_utc_date_t

typedef struct {
    UINT16_T year;
    UINT8_T month;
    UINT8_T day;
    UINT8_T hour;
    UINT8_T min;
    UINT8_T sec;
    UINT8_T dayIndex; /* 0 = Sunday */
} tal_utc_date_t;

• year: Year
• month: Month
• day: Day
• hour: Hour
• min: Minute
• sec: Second
• dayIndex: Day of week

API description

Initialize RTC

The RTC starts counting from zero when the device is powered on. Its accuracy depends on the chip or the clock source.

API description

OPERATE_RET tal_rtc_init(VOID_T);

Set RTC

API description

OPERATE_RET tal_rtc_time_set(TIME_T time_sec);

Parameter description

Parameter	Description
time_sec	4-byte Unix timestamp.

Get RTC

API description

OPERATE_RET tal_rtc_time_get(TIME_T *time_sec);

Parameter description

Parameter	Description
time_sec	The pointer to the 4-byte Unix timestamp.

Set the time zone

API description

OPERATE_RET tal_utc_set_time_zone(INT16_T time_zone);

Parameter description

Parameter	Description
time_zone	Its value is a signed integer and 100 times the actual time zone. For example, 800 represents GMT+8.

Get the time zone

API description

INT16_T tal_utc_get_time_zone(VOID_T);

Parameter description

Parameter	Description
Return value	Its value is a signed integer and 100 times the actual time zone. For example, 800 represents GMT+8.

Request the current time automatically

After the device is paired, it will automatically request a time sync. The type of time requested can be set through TUYA_BLE_AUTO_REQUEST_TIME_CONFIGURE, which defaults to 1.

#define TUYA_BLE_AUTO_REQUEST_TIME_CONFIGURE 1 // Request the current server time. The result is reported to the application layer through TUYA_BLE_CB_EVT_TIME_STAMP. See the description of tuya_ble_timestamp_data_t for the format.
#define TUYA_BLE_AUTO_REQUEST_TIME_CONFIGURE 2 // Request the app's current local time. The result is reported to the application layer through TUYA_BLE_CB_EVT_APP_LOCAL_TIME_NORMAL. See the description of  tuya_ble_time_noraml_data_t for the format.
#define TUYA_BLE_AUTO_REQUEST_TIME_CONFIGURE 3 // Request the current server time with DST. The result is reported to the application layer through TUYA_BLE_CB_EVT_TIME_STAMP_WITH_DST. See the description of tuya_ble_timestamp_with_dst_data_t for the format.

Request the current time

After the device is paired, it can call this function to request the time from the app or cloud. To regularly request the current time, call this function in the timer. Note that the device can successfully get the time when it is connected. Otherwise, an error will be returned.

API description

tuya_ble_status_t tuya_ble_time_req(UINT8_T time_type);

Parameter description

Parameter

Description

time_type

0x00: Request the current server time. The result is reported to the application layer through TUYA_BLE_CB_EVT_TIME_STAMP. See tuya_ble_timestamp_data_t for the format. 0x01: Request the current server time. The result is reported to the application layer through TUYA_BLE_CB_EVT_TIME_NORMAL. See tuya_ble_time_noraml_data_t for the format. 0x02: Request the app’s current local time. The result is reported to the application layer through TUYA_BLE_CB_EVT_APP_LOCAL_TIME_NORMAL. See tuya_ble_time_noraml_data_t for the format.

Convert timestamp to date and time

Convert a Unix timestamp to readable date and time format.

API description

OPERATE_RET tal_utc_timestamp2date(UINT32_T timestamp, tal_utc_date_t* date, BOOL_T daylightSaving)

Parameter description

Parameter	Description
timestamp	4-byte Unix timestamp.
date	See tal_utc_date_t.
daylightSaving	0x00: DST is not applied. 0x01: DST is applied.

Convert date and time to timestamp

Convert a date and time to a Unix timestamp.

API description

UINT32_T tal_utc_date2timestamp(tal_utc_date_t *date, BOOL_T daylightSaving);

Parameter description

Parameter	Description
date	See tal_utc_date_t.
daylightSaving	0x00: DST is not applied. 0x01: DST is applied.
Return value	4-byte Unix timestamp.

How to use

Each time the device is powered on, tal_rtc_init will initialize the local time to start counting from zero. At this time, the device time and network time are not synced. The time obtained through tal_rtc_time_get and tal_utc_get_time_zone is the number of seconds since power on.

After the device is paired or reconnected, it will automatically request a time sync. The type of time requested can be set through TUYA_BLE_AUTO_REQUEST_TIME_CONFIGURE. For more information about the types of time, see the macro description above.

tuya_ble_time_req can be called to proactively request time sync. To regularly request the current time, call this function in the timer. Note that the device can successfully get the time when it is connected. Otherwise, an error will be returned.

After the device receives the time data, it will call tal_rtc_time_set and then tal_utc_set_time_zone to update the local timestamp and time zone. At this time, the device time and network time are synced. The time obtained through tal_rtc_time_get and tal_utc_get_time_zone is the actual network time.

Functional testing

Test cases

TEST_CID_GET_TIME
TEST_CID_REQ_TIME
TEST_CID_SET_RTC_TIME
TEST_CID_GET_RTC_TIME

Prerequisites

• You have installed the Tuya app on your phone.
• The device must be in pairing mode.

Procedure

Communicate with the mobile app using a host that simulates a real device.

1. Query the device’s local time. Call tal_rtc_time_get and tal_utc_get_time_zone to get the device’s local timestamp and time zone. The obtained time is the number of seconds since power on.

   

2. After the device is paired, request the current time automatically. Specify the type of the requested time with TUYA_BLE_AUTO_REQUEST_TIME_CONFIGURE.

   

3. Request the current time manually. Call tuya_ble_time_req to request time sync.

   

4. Query the device’s local time. Call tal_rtc_time_get and tal_utc_get_time_zone to get the device’s local timestamp and time zone. The obtained time is the actual network time.

   

   If you have any problems with host usage, see Logic Host User Guide.

Support and help

If you have any problems with TuyaOS development, you can post your questions in the Tuya Developer Forum.