diff --git a/Documentation/applications/netutils/ntpclient/index.rst b/Documentation/applications/netutils/ntpclient/index.rst index 222be2a946..6dde8fe632 100644 --- a/Documentation/applications/netutils/ntpclient/index.rst +++ b/Documentation/applications/netutils/ntpclient/index.rst @@ -2,5 +2,174 @@ ``ntpclient`` NTP client ======================== -This is a fragmentary NTP client. It neither well-tested nor -mature nor complete at this point in time. +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 :code:`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