coreSNTP Demo
Introduction
This demo shows how an application can use the coreSNTP library to maintain a real-time clock (or wall-clock time) in the
Co-ordinated Universal Time (UTC) zone by setting up an SNTP client to periodically synchronize system time with time
servers. The demo also showcases how the coreSNTP library can be used to communicate securely with SNTP/NTP servers using
mutual authentication. The example uses symmetric-key based AES-128-CMAC as the authentication algorithm. To run this demo
with authentication enabled, the server(s) you use must support authentication with the AES-128-CMAC algorithm, and
symmetric key(s) must be generated and pre-shared between the client (the demo) and the server(s) before you run the demo.
(Optional) Instructions for setting up a chronyd
based NTP server
To run the coreSNTP demo with AES-128-CMAC based authentication, an NTP server that supports authentication with the
algorithm is required. An NTP server can be setup with the chronyd
package with support for AES-128-CMACM
authentication. The chronyd
server can be configured to use a set of upstream servers to periodically
synchronize its time so that it can accurately respond to time requests made to it by the coreSNTP demo client.
Follow the Instructions for
setting up an NTP server (with authentication enabled) with chronyd
in an AWS EC2 Linux instance with
the Amazon Time Sync service as the upstream server.
Multithreaded Architecture - SNTP Client Task & Sample App Task
The demo architecture contains two tasks:
- SNTP Client Task - This task is a dedicated SNTP client that synchronizes time periodically with
time server(s) using the coreSNTP library. It corrects the system clock based on the received server time and
the calculated system clock drift from server time to maintain a wall-clock/real-time clock in the UTC time zone.
The logic for the SNTP client task can be seen in the demo file SNTPClientTask.c on GitHub.
- Sample Application task - This task is a sample application task that depends on real-time
information that it queries from the system. This basic application task periodically prints the real-time/wall-clock
time in UTC that is has queried from the system. The code for this sample application task that queries system time
periodically can be found in the file
SampleAppTask.c on GitHub.
All the uses of the coreSNTP library are encapsulated in the SNTP Client Task to showcase how an SNTP client task
agent/utility can be set up in a FreeRTOS system to service time requests from multiple application tasks.
Model for Wall-Clock System Clock
The demo shows how devices that do not have a Real-Time Clock hardware module can maintain a real-time clock (or wall-time
clock) in the UTC time zone in RAM. The demo uses the following mathematical model that is flexible for being updated
from periodic SNTP time synchronizations:
System Time = Base Time +
Time Elapsed since last SNTP time synchronization +
Slew Adjustment
where
BaseTime = Time set at boot or the last synchronized time
Slew Rate = Number of milliseconds of clock correction per system time second
No. of ticks since last SNTP sync = Current FreeRTOS Tick Count -
Tick count at last SNTP synchronization
Time Elapsed since last SNTP time synchronization =
No. of ticks since last SNTP synchronization
x
Number of milliseconds per FreeRTOS tick
Slew Adjustment = Slew Rate x Time Elapsed since last SNTP sync
In the above mathematical model, any frequency discrepancies in the system's clock oscillator cause clock drift that skews the execution
timing of FreeRTOS ticks in relation to actual/internet time. So, a Slew Adjustment offset is added to
the calculation of the system clock to correct for the total clock drift. In this way, the system time matches the
real-world time. The Slew Adjustment depends on the Slew Rate, which is the adjustment
that should be periodically applied to the system time to counter the clock drift of the system clock. This rate is
calculated once from the clock-offset value provided by the coreSNTP library when it receives the time from a time
server.
Clock Correction/Discipline Model
The demo uses a combination of "step" and "slew" methodologies to correct the system clock, which affect the
"Base Time" and "Slew Adjustment" parameters, respectively, of the mathematical model
of the system clock mentioned in the previous section.
- The "Step" correction updates the Base Time parameter of the system clock when it
receives the time from a server. This correction is used on EVERY successful time synchronization cycle with a time
server to immediately correct the system clock to match server time.
- The "Slew" correction approach is used to compensate for system clock drift that occurs during the
interval between successful time synchronizations with with time server(s). Clock drift occurs in the interval because
the system time is based on the HW system clock oscillator that introduces the drift due to its frequency deviation. The
"Slew Rate" that is used for slew correction is calculated ONLY once, on the occasion of the second
successful time synchronization with a time server. This is because the demo initializes the system time as (the
first second of) the
democonfigSYSTEM_START_YEAR
, and so the actual system clock drift over a
period of time can be correctly calculated only AFTER the demo system time has been synchronized once with the real-world time
obtained from a time server. Given the interval between the first and second time synchronizations with a server, the
actual system clock drift can be calculated and the Slew Rate used for clock adjustment can be
correctly established.
Here is a summary of how the clock-discipline methodology of the demo affects the system:
On every time response recevied from time server,
Base Time = Time from Server
On the 2nd successful time synchronization with time server,
Slew Rate = Clock-Offset (calculated by coreSNTP library) / Poll Period
Initialization Time in the Demo
The demo initializes the system time with the first second of the year configured with the
democonfigSYSTEM_START_YEAR
macro. For example, if the macro is configured with the year 2021,
the demo initializes system time as the 1st of January 2021 0h:0m:0s. This is done so that the system time is not
initialized as zero, but with a time that is close enough to the real-world time that it can meet the
application's needs to perform operations like server certificate validation to establish a TLS connection before
it is able to synchronize its time with a time server to obtain accurate real-world time. This is useful for those
device platforms that do not have a battery backed Real-Time Clock (RTC) hardware module and so do not have a hardware mechanism
to obtain the real-world time at system startup.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.