Time Service

This topic describes the time service that enables Network Time Protocol (NTP) based time synchronization and request for daylight saving time (DST).

NTP time synchronization

If a device’s clock is not configured or shows a time drift, the device synchronizes time with an NTP server to get the latest time.

• For non-time-sensitive devices, they can directly use the NTP server timestamp.
• For time-sensitive devices that require high-precision time correction, network cost should be taken into consideration. Suppose the NTP server timestamp is t3, and after 10 ms, the device receives the timestamp. Therefore, t3 + 10 ms should be the accurate time synchronized with the device.

Example

Suppose the request cost is equal to the response cost, and the response cost is half the total network cost, as shown in the following figure.

• t4 − t1 = Total Cost

• t3 − t2 = Server Cost

• Total Network Cost = Total Cost − Server Cost

• Response Cost = Total Network Cost ÷ 2 = (Total Cost − Server Cost) ÷ 2 = (t4 − t1 − (t3 − t2)) ÷ 2 = (t4 − t1 − t3 + t2) ÷ 2

• Accurate Time = t3 + Response Cost = t3 + (t4 − t1 − t3 + t2) ÷ 2 = (t4 − t1 + t3 + t2) ÷ 2

  

When making an NTP time request, a device should pass in the request time (t1) to the server. The server returns the t1, t2, and t3. Then, the device can calculate the accurate time.

Device sends messages

The device initiates an NTP time request.

Topic: tylink/${deviceId}/ext/time/request

{
    "msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
        "bizType":"NTP",
        "dst":1655957399000
    }
}

Description

Device receives messages

The device receives a response from the NTP server.

Topic: tylink/${deviceId}/ext/time/response

{
    "msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
        "bizType":"NTP",
        "dst":1655957399000,
        "srt":1655957399100,
        "sst":1655957399300,
    }
}

Description

The description of status codes

Request for DST

DST is the practice of moving the clocks forward one hour from standard time during the summer months and changing them back again in the fall. If a device has features such as time display and local schedules, DST data is required. Otherwise, the scheduled task cannot be run as expected when DST applies.

The time when DST begins and ends comes in pairs, such as [1680422400,1698562800].

To get the DST data, the device should pass timezoneId to the server. If a device cannot get the timezoneId, you can specify a timezoneId on the Tuya Developer Platform for the device. The local time zone takes precedence over the one specified on the platform. If a device has no timezoneId specified both on the local and the platform, DST data cannot be obtained.

Frequently updating DST data is not needed. It is recommended to query the DST data once per month.

Device sends messages

The device initiates a DST data request.

Topic: tylink/${deviceId}/ext/time/request

{
    "msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
        "bizType":"DST",
        "timezoneId":"asia/shanghai"
    }
}

Description

Device receives messages

The device receives a response from the server.

Topic: tylink/${deviceId}/ext/time/response

{
    "msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
        "bizType":"DST",
        "stdTimeZone":"+08:00",
        "dstIntervals":[1680422400,1698562800]
    }
}

Description

The description of status codes

Reference

For more information, see MQTT Topics.