documentation: add documentation for NTP Client

Add missing documentation for the NTP client implementation.

Signed-off-by: Filipe Cavalcanti <filipe.cavalcanti@espressif.com>

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