Embedded devices are faced with issues such as limited resources, no Network Time Protocol (NTP) service provided by the system, and no accurate timestamp on devices. To resolve these issues, IoT Platform provides the NTP service.

How it works

Based on the principles of NTP, IoT Platform uses its server as an NTP server. A device sends a message to IoT Platform by using a specific topic. The payload contains the timestamp of the sending time on the device. The payload of the response from IoT Platform contains the timestamps of both the receiving time and the sending time in IoT Platform. After the device receives the response, in combination with the preceding three timestamps and the current time, the device calculates the time difference between itself and IoT Platform. Then, the device calculates the accurate current time to calibrate its own time.

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

For example, an embedded device does not have an accurate time after it is powered on. When a connection is being established based on the Transport Layer Security (TLS) protocol, the time of the device certificate fails the verification. This failure cannot be resolved by the NTP service, because the connection has not been established between the device and IoT Platform.

Procedure

Topic for requests: /ext/ntp/${YourProductKey}/${YourDeviceName}/request

Topic for responses: /ext/ntp/${YourProductKey}/${YourDeviceName}/response

Note The product key and device name are contained in the certificate of a device. You can obtain the device certificate from the IoT Platform console.
  1. The device subscribes to the /ext/ntp/${YourProductKey}/${YourDeviceName}/response topic.
  2. The device sends a Quality of Service 0 (QoS=0) message to the /ext/ntp/${YourProductKey}/${YourDeviceName}/request topic. The payload contains the timestamp of the current time on 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 default data type is LONG.
    • The NTP service supports only QoS=0 messages.
  3. The device receives a response from the NTP server. The payload contains the following information:
    {
        "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 on the device is calculated by using the following formula: (${serverRecvTime} + ${serverSendTime} + ${deviceRecvTime} - ${deviceSendTime})/2.

Example

Note The timestamp data that is sent by the device and the NTP server is of the same 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 on the device is 1571724098000. The timestamp on 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.

- Time on the device Time on the NTP server
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 directly uses the timestamp that is returned by IoT Platform, the result is 1571724098115, which causes a link latency of 10 milliseconds between the device and IoT Platform.