时间服务

时间服务提供时间校正 NTP 以及夏令时获取 DST 服务。

时间校正（NTP）

设备时钟不准确或者无时钟，需要从云端同步时间，称之为时间校正（NTP）。

• 若设备对时间精度要求不高，可以直接用服务端的时间戳，相对来说比较简单，不多介绍。
• 若设备对时间精度敏感，需要高精度校正，那么就要考虑网络耗时。假如服务端的时间戳 t3，经过网络耗时 10ms 发到设备端，设备取到的 t3 已经是 10ms 之前的时间了，需要 t3+10ms 才是相对准确的时间。

示例

假设请求的耗时和响应的耗时相等，响应耗时是总体网络耗时的一半。可以参考如下图示：

• t4 − t1 = 总耗时
• t3 − t2 = 服务端系统耗时
• 总体网络耗时 = 总耗时 − 服务端耗时
• 响应耗时 = 总体网络耗时 ÷ 2=(总耗时 − 服务端耗时) ÷ 2 = (t4 − t1 − (t3 − t2)) ÷ 2 = (t4 − t1 − t3 + t2) ÷ 2
• 精准时间 = t3 + 响应耗时 = t3 + (t4 − t1 − t3 + t2) ÷ 2=（t4 − t1 + t3 + t2) ÷ 2

所以设备端请求时需要传递设备请求时间 t1，云端返回 (t1,t2,t3) 三元组，由设备端通过精准时间公式计算得到校准的时间。

设备发送消息

设备请求服务端提供时间校正（NTP）服务。

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	设备 ID。如果是子设备的身份，deviceId 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	获取时间服务参数	是	获取时间服务参数。
data.bizType	string	时间业务类型	是	取值：NTP 表示时间校正服务。
data.dst	number	设备请求时间戳 device send time	否	设备请求时的 Unix 时间戳，13 位毫秒级。bizType = NTP，时间校正服务调用时，若需要高精度校正则必填，否则返回的是服务端的时间戳。

设备接收消息

响应设备请求的时间校正（NTP）。

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	设备 ID。如果是子设备的身份，deviceId 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	获取 OTA 参数	是	获取 OTA 参数。
data.bizType	string	时间业务类型	是	NTP：时间校正服务。
data.dst	number	设备请求时间戳 device send time	否	设备请求时的 Unix 时间戳，13 位毫秒级。bizType = NTP，且请求中传 dst 参数，该字段才返回。
data.srt	number	服务端收到请求时间戳 server receive time	否	服务端收到请求时的 Unix 时间戳，13 位毫秒级。bizType = NTP，且请求中传 dst 参数，该字段才返回。
data.sst	number	服务端响应时间戳 server send time	否	服务端响应的 Unix 时间戳，13 位毫秒级。bizType = NTP 时才返回，若请求中没有传 dst 参数，则只返回该字段。

状态码说明

状态码	说明
0	默认状态，代表成功。
1001	服务异常。

夏令时获取

夏令时（Daylight Saving Time，DST），又称日光节约时制和夏令时间，是一种为节约能源而人为规定地方时间的制度。设备端如有显示时间或者本地定时任务的需求，那么有时间戳还不够，还需要夏令时数据。不然会导致在夏令时切换时，任务执行与用户预期不一致。

夏令时分为入夏令时时间和出夏令时时间，成对存在，例如：[1680422400,1698562800]。

要获取夏令时数据，需要 timezoneId，设备可以传给服务端。如果设备无法获取 timezoneId，也可以在平台为设备设置 timezoneId，设备本地的优先级要高于平台设置的。如果设备本地和平台都没有 timezoneId，则无法获取夏令时数据。

夏令时不需要频繁更新，需要注意查询频率，一般建议一个月查询一次夏令时服务。

设备发送消息

设备请求服务端提供夏令时获取服务。

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	设备 ID。如果是子设备的身份，deviceId 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	获取时间服务参数	是	获取时间服务参数。
data.bizType	string	时间业务类型	是	取值：DST 表示夏令时获取服务。
data.timezoneId	string	时区位置，即地区	否	bizType = DST，夏令时获取服务调用时必须传该值。timeZoneId 示例：asia/shanghai。

设备接收消息

响应设备请求的夏令时获取服务。

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

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

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	设备 ID。如果是子设备的身份，deviceId 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	获取 OTA 参数	是	获取 OTA 参数。
data.bizType	string	时间业务类型	是	DST：夏令时获取服务。
data.stdTimeZone	string	timeZoneId 对应的时区	否	bizType = DST 时才返回。stdTimeZone 示例：+08:00。
data.dstIntervals	array	夏令时分为入夏令时时间和出夏令时时间，成对存在	否	bizType = DST时才返回，例如：[1680422400,1698562800]。默认当前 timezoneId 地区的 1 年内进入夏令时和出夏令时数据。建议设备请求获取夏令时的频次不需要很高，一般定时一月请求一次。

状态码说明

状态码	说明
0	默认状态，代表成功。
1001	服务异常。

更多协议内容

更多信息，请参考 MQTT 标准协议概览。