ntpclient NTP client

The NTP (Network Time Protocol) client is a network utility that synchronizes the system clock with time servers over the Internet. This implementation provides a minimal but functional NTP client for NuttX.

What is NTP?

The Network Time Protocol (NTP) is a networking protocol designed to synchronize clocks of computer systems over packet-switched, variable-latency data networks. NTP is one of the oldest Internet protocols still in use, originally designed by David L. Mills of the University of Delaware.

Key features of NTP:

  • High Precision: NTP can achieve sub-millisecond accuracy on local area networks and typically 10-100 millisecond accuracy over the Internet

  • Robust Algorithm: Uses sophisticated algorithms to filter out network jitter and select the best time sources

  • Hierarchical Structure: Uses a stratum system where stratum 0 devices are atomic clocks, stratum 1 servers sync with stratum 0, and so on

  • Fault Tolerance: Can handle multiple time sources and automatically switch between them

NTP Protocol Overview

NTP uses UDP port 123 and follows a client-server model. The protocol exchanges timestamps to calculate:

  • Offset: The difference between the client’s clock and the server’s clock

  • Delay: The round-trip network delay

  • Dispersion: The maximum error due to clock frequency tolerance

The NTP packet format (version 3) includes:

  • Leap Indicator: Warns of an impending leap second

  • Version Number: NTP version (3 in this implementation)

  • Mode: Client, server, broadcast, etc.

  • Stratum: Clock level (0-15)

  • Poll Interval: Maximum interval between successive messages

  • Precision: Clock precision

  • Root Delay/Dispersion: Total delay and dispersion to the reference clock

  • Reference Identifier: Identifies the reference source

  • Reference Timestamp: Time when the system clock was last set

  • Originate Timestamp: Time when the request departed the client

  • Receive Timestamp: Time when the request arrived at the server

  • Transmit Timestamp: Time when the reply departed the server

Implementation Details

The NuttX NTP client implementation consists of several key components:

Source Code Structure

ntpclient.c - Main implementation file containing:

  • Daemon Management: Functions to start, stop, and manage the NTP daemon

  • Time Synchronization: Core algorithms for calculating clock offset and delay

  • Network Communication: UDP socket handling and NTP packet exchange

  • Sample Collection: Gathering multiple time samples for statistical filtering

ntpv3.h - NTP version 3 packet format definitions:

  • ntp_datagram_s: Complete NTP packet structure

  • ntp_timestamp_s: 64-bit NTP timestamp format

  • Protocol Constants: NTP version, modes, and stratum definitions

Key Functions

  • ntpc_start_with_list(): Starts the NTP daemon with a list of servers

  • ntpc_start(): Starts the NTP daemon with default configuration

  • ntpc_stop(): Stops the running NTP daemon

  • ntpc_status(): Retrieves current synchronization status and samples

  • ntpc_daemon(): Main daemon loop that:

    • Connects to configured NTP servers

    • Sends NTP requests and processes responses

    • Calculates clock offset and delay

    • Applies time corrections to the system clock

    • Continues polling at configured intervals

  • ntpc_get_ntp_sample(): Performs a single NTP transaction:

    • Creates UDP socket to NTP server

    • Sends NTP request packet with current timestamp

    • Receives and validates NTP response

    • Calculates offset and delay using NTP algorithms

  • ntpc_calculate_offset(): Implements the NTP clock filter algorithm

    • Uses four timestamps, calculates offset and delay

    • Applies statistical filtering to reduce jitter

  • ntpc_settime(): Applies time correction to system clock:

    • Uses calculated offset to adjust system time

    • Handles both positive and negative time adjustments

    • Maintains monotonic clock consistency

Configuration Options

The NTP client can be configured through Kconfig options:

  • CONFIG_NETUTILS_NTPCLIENT_SERVER: List of NTP server hostnames

  • CONFIG_NETUTILS_NTPCLIENT_PORTNO: NTP server port (default: 123)

  • CONFIG_NETUTILS_NTPCLIENT_STACKSIZE: Daemon task stack size

  • CONFIG_NETUTILS_NTPCLIENT_SERVERPRIO: Daemon task priority

  • CONFIG_NETUTILS_NTPCLIENT_STAY_ON: Keep polling continuously

  • CONFIG_NETUTILS_NTPCLIENT_POLLDELAYSEC: Polling interval in seconds

  • CONFIG_NETUTILS_NTPCLIENT_NUM_SAMPLES: Number of samples for filtering

  • CONFIG_NETUTILS_NTPCLIENT_TIMEOUT_MS: Network timeout in milliseconds

Usage

The NTP client is typically used through the system commands:

Note

The NTP client functionality requires enabling the SYSTEM_NTPC option in your configuration. Make sure to select this option in menuconfig or your Kconfig fragment before building.

  • ntpcstart: Start the NTP daemon

  • ntpcstop: Stop the NTP daemon

  • ntpcstatus: Display synchronization status

Example workflow:

  1. Configure network connectivity

  2. Start NTP client: ntpcstart

  3. Check status: ntpcstatus

  4. Verify time: date command

  5. Stop when needed: ntpcstop

The client will automatically: - Connect to configured NTP servers - Exchange time information - Calculate and apply clock corrections - Continue periodic synchronization

Limitations

This is a minimal NTP client implementation with some limitations:

  • No Authentication: Does not support NTP authentication (MD5/SHA1)

  • Basic Filtering: Uses simple statistical filtering, not full NTP algorithms

  • Single Reference: Does not implement full NTP reference clock selection

  • No Leap Seconds: Does not handle leap second announcements

  • Limited Error Handling: Basic error recovery and retry mechanisms

Despite these limitations, the implementation provides sufficient accuracy for most embedded applications requiring network time synchronization.

Dependencies

The NTP client requires:

  • CONFIG_NET: Network support

  • CONFIG_NET_UDP: UDP protocol support

  • CONFIG_NET_SOCKOPTS: Socket options support

  • CONFIG_LIBC_NETDB: DNS resolution (recommended)

  • CONFIG_HAVE_LONG_LONG: 64-bit integer support

For best results, ensure: - Stable network connectivity - Access to reliable NTP servers - Sufficient system resources for daemon operation