Time Service

Last Updated on : 2022-11-04 15:31:27download

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.

  • t4t1 = Total Cost

  • t3t2 = 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

    Time Service

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

Parameter Type Description Required Remark
${deviceId} string Device ID Yes The device ID. If this is a sub-device, the deviceId should be the ID of the sub-device.
version string Protocol version No The protocol version defaults to 1.0, which is the only valid value currently.
msgId string Message ID Yes A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time number Message timestamp Yes The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data object Time service parameters Yes Get the time service parameters.
data.bizType string Time service type Yes Value: NTP indicates time synchronization with the NTP server.
data.dst number The request timestamp (that is, device send time). No The Unix timestamp when an NTP time request is sent from the device, in milliseconds (13-digit value). When bizType is NTP, this field is required if you need a high-precision time. Otherwise, the NTP server timestamp is returned.

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

Parameter Type Description Required Remark
${deviceId} string Device ID Yes The device ID. If this is a sub-device, the deviceId should be the ID of the sub-device.
version string Protocol version No The protocol version defaults to 1.0, which is the only valid value currently.
msgId string Message ID Yes A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time number Message timestamp Yes The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data object OTA update parameters Yes Get the OTA update parameters.
data.bizType string Time service type Yes NTP: Time synchronization with the NTP server.
data.dst number The request timestamp (that is, device send time). No The Unix timestamp when an NTP time request is sent from the device, in milliseconds (13-digit value). This parameter is returned only when bizType is NTP and dst is specified in the request.
data.srt number The receiving time (that is, server receive time). No The Unix timestamp when an NTP time request is received by the server, in milliseconds (13-digit value). This parameter is returned only when bizType is NTP and dst is specified in the request.
data.sst number The response timestamp (that is, server send time). No The Unix timestamp when a response is returned from the server, in milliseconds (13-digit value). This parameter is returned when bizType is NTP. If dst is not specified in the request, only this parameter is returned.

The description of status codes

Status code Description
0 The default status, indicating success.
1001 Service exception.

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 IoT Development 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

Parameter Type Description Required Remark
${deviceId} string Device ID Yes The device ID. If this is a sub-device, the deviceId should be the ID of the sub-device.
version string Protocol version No The protocol version defaults to 1.0, which is the only valid value currently.
msgId string Message ID Yes A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time number Message timestamp Yes The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data object Time service parameters Yes Get the time service parameters.
data.bizType string Time service type Yes Value: DST indicates the DST service.
data.timezoneId string The time zone ID No The value of this parameter must be specified when bizType is DST. Example of timeZoneId: asia/shanghai

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

Parameter Type Description Required Remark
${deviceId} string Device ID Yes The device ID. If this is a sub-device, the deviceId should be the ID of the sub-device.
version string Protocol version No The protocol version defaults to 1.0, which is the only valid value currently.
msgId string Message ID Yes A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time number Message timestamp Yes The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data object OTA update parameters Yes Get the OTA update parameters.
data.bizType string Time service type Yes DST: The DST service.
data.stdTimeZone string The time zone offset of timeZoneId. No This parameter is returned when bizType is DST. Example of stdTimeZone: +08:00
data.dstIntervals array The time when DST begins and ends comes in pairs. No This parameter is returned when bizType is DST. For example, [1680422400,1698562800]. A one-year DST time change schedule for the current timezoneId is returned by default. It is recommended to query the DST data once per month.

The description of status codes

Status code Description
0 The default status, indicating success.
1001 Service exception.

Reference

For more information, see MQTT Topics.