NTP service

How it works

The IoT Platform NTP service is based on the NTP protocol. IoT Platform acts as an NTP server. The high-precision time calibration flow is as follows:

1. A device sends a message to a specified topic on IoT Platform. The message contains its send time, deviceSendTime.

2. After IoT Platform receives the message from the device, it adds its receive time, serverRecvTime, and its response time, serverSendTime, to the response message.

3. After the device receives the response from IoT Platform, it records its receive time, deviceRecvTime, based on its local time.

4. The device calculates the time difference between itself and IoT Platform based on these four timestamps. This calculation provides the device with the precise current server-side time, Time.

Communication topics

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

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

In these topics, ${YourProductKey} and ${YourDeviceName} represent the ProductKey and DeviceName from your device certificate. You can find these values on the Device Details page in the IoT Platform console.

Device connection instructions

Currently, only the Link software development kit (SDK) for C supports the NTP service configuration. To download the demo code, see C Link SDK.

For the procedure and an example of how to configure the NTP service on a device, see NTP service.

The NTP service usage flow and topics are described as follows:

1. The device sends a Quality of Service (QoS) 0 message to the topic /ext/ntp/${YourProductKey}/${YourDeviceName}/request. The message contains the device's current timestamp in milliseconds. The following is an example:

   {
       "deviceSendTime":"1571724098000"
   }

   Note

   • The timestamp supports the Long (default) and String data types.

   • The NTP service currently supports only QoS 0 messages.

2. The device receives a response message from IoT Platform on the topic /ext/ntp/${YourProductKey}/${YourDeviceName}/response. The message contains the following information.

   Note

   The device can receive messages from the IoT Platform directly through the topic /ext/ntp/${YourProductKey}/${YourDeviceName}/response without subscribing. This topic is not displayed in the Subscribed Topics list on the device details page in the IoT Platform console.

   {
       "deviceSendTime":"1571724098000",
       "serverRecvTime":"1571724098110",
       "serverSendTime":"1571724098115"
   }

3. The device calculates the precise current server-side UNIX timestamp.

   Assuming that the request and response latencies are equal, the precise time on the device is calculated using the following formula: (${serverRecvTime}+${serverSendTime}+${deviceRecvTime}-${deviceSendTime})/2.

Usage example

For example, assume that the initial device time is 1571724098000 ms, the initial server-side time is 1571724098100 ms, the link latency is 10 ms, and the server processing interval is 5 ms.

The precise current time calculated by the device is (1571724098110+1571724098115+1571724098025-1571724098000) ms / 2 = 1571724098125 ms.

If you use the timestamp returned by IoT Platform directly, you only obtain the time 1571724098115 ms. This value is inaccurate by 10 ms compared to the actual server-side time because of the link latency.