All Products
Search
Document Center

IoT Platform:NTP service

Last Updated:Nov 01, 2023

IoT Platform provides the Network Time Protocol (NTP) service. This way, IoT Platform can synchronize the server time to embedded devices with limited resources.

How it works

The NTP service works based on the NTP protocol. IoT platform is used as the NTP server. The following section describes the process of high-precision time calibration.

  1. A device sends a message to IoT Platform by using a specified topic. The message includes the deviceSendTime parameter.

  2. After IoT Platform receives the message, IoT Platform returns a response. The response includes the serverRecvTime parameter and serverSendTime parameter.

  3. When the device receives the response, the device generates the deviceRecvTime parameter based on the local time.

  4. The device calculates the time difference between the device and IoT Platform, and obtains the value of the Time parameter. This parameter indicates the system time of the server.

Important

The system time of a device can be calibrated by using the NTP service only if the device is connected to IoT Platform.

If the device is not connected to IoT Platform, the device cannot obtain an accurate time value after the device is turned on. When the device establishes a TSL-based connection to IoT Platform, the timestamp of the certificate time fails to be verified.

Topics

Request topic: /ext/ntp/${YourProductKey}/${YourDeviceName}/request

Response topic: /ext/ntp/${YourProductKey}/${YourDeviceName}/response

${YourProductKey} and ${YourDeviceName} specifies the ProductKey and DeviceName in the device certificate. You can obtain the device certificate on the Device Details page of the IoT Platform console .

Device connection

You can configure the NTP service by using only Link SDK for C. To download the sample code, see Obtain and use Link SDK for C.

For information about how to configure the NTP service on a device, see NTP service.

The following steps describe how to use the NTP service by using specified topics:

  1. The device sends a QoS 0 message to the /ext/ntp/${YourProductKey}/${YourDeviceName}/request topic. The message includes a timestamp that indicates the current time of the device. The unit of the timestamp is milliseconds. Example:

    {
        "deviceSendTime":"1571724098000"
    }
    Note
    • The data type of the timestamp can be Long or String. By default, the Long data type is used.

    • The NTP service supports only QoS 0 messages.

  2. The device receives a response from IoT Platform by using the /ext/ntp/${YourProductKey}/${YourDeviceName}/response topic. The following sample code provides an example:

    {
        "deviceSendTime":"1571724098000",
        "serverRecvTime":"1571724098110",
        "serverSendTime":"1571724098115"
    }
  3. The device calculates the accurate current time in the UNIX timestamp format.

    The device records the timestamp when the device receives the response from the NTP server as ${deviceRecvTime}. The accurate current time of the device is calculated by using the following formula: (${serverRecvTime} + ${serverSendTime} + ${deviceRecvTime} - ${deviceSendTime})/2.

Examples

Note

The timestamps that are sent by the device and the NTP server are of the same data type. For example, if the timestamp that is sent by the device is of the STRING type, the timestamp that is returned by the NTP server is also of the STRING type.

In this example, the timestamp of the device is 1571724098000. The timestamp of the NTP server is 1571724098100. The link latency is 10 milliseconds. The NTP server sends a response 5 milliseconds after the server receives a message from the device.

Operation

Device time (milliseconds)

Server time (milliseconds)

The device sends a message

1571724098000 (deviceSendTime)

1571724098100

The NTP server receives the message

1571724098010

1571724098110 (serverRecvTime)

The NTP server sends a response

1571724098015

1571724098115 (serverSendTime)

The device receives the response

1571724098025 (deviceRecvTime)

1571724098125

The device calculates the accurate current time by using the following formula: (1571724098110 + 1571724098115 + 1571724098025 - 1571724098000)/2 = 1571724098125.

If the device uses the timestamp 1571724098115 that is returned by IoT Platform, a link latency of 10 milliseconds that occurs between the device and IoT Platform is not included in the calculation.