IoT Platform provides the Network Time Protocol (NTP) service for embedded devices that have limited resources. This allows the devices to obtain accurate clocks in real time.

How it works

The NTP service is based on the NTP protocol. IoT platform is used as the NTP server. The following steps describe 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 and serverSendTime parameters.
  3. When the device receives the response, the device generates the deviceRecvTime parameters based on the local time.
  4. The device calculates the time difference between the device and IoT Platform and obtain the Time parameter. This parameter indicates the current time of the server.
Notice The time of a device can be calibrated by using the NTP service only when the device is connected to IoT Platform.

Otherwise, the device cannot obtain an accurate time after it is powered on. When the device establishes a TSL connection with IoT Platform, 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 only by using Link SDK for C. To download the sample code, see Obtain and use the SDK.

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

  1. The device subscribes to the /ext/ntp/${YourProductKey}/${YourDeviceName}/response topic.
  2. 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. The following code shows an example:
    {
        "deviceSendTime":"1571724098000"
    }
    Note
    • The data type of the timestamp can be Long or String. The Long data type is used be default.
    • The NTP service supports only QoS 0 messages.
  3. The device receives a response from IoT Platform by using the /ext/ntp/${YourProductKey}/${YourDeviceName}/response topic. The following code shows an example:
    {
        "deviceSendTime":"1571724098000",
        "serverRecvTime":"1571724098110",
        "serverSendTime":"1571724098115",
    }
  4. The device calculates the accurate current time in the UNIX timestamp format.

    The device marks the time when it 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.

Example

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 it 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 that is returned by IoT Platform 1571724098115, a link latency of 10 milliseconds between the device and IoT Platform is not calculated.