From a9675211dd20140a0e0cdd093955136d983502b8 Mon Sep 17 00:00:00 2001 From: Jerome Forissier Date: Wed, 25 Jun 2025 15:19:20 +0200 Subject: [PATCH] doc: add doc/cmd/sntp.rst and remove doc/README.SNTP Add a proper documentation file for the sntp command in RST format and drop doc/README.SNTP. The documentation now includes the NET_LWIP specificities. Signed-off-by: Jerome Forissier --- doc/README.SNTP | 17 ---------- doc/usage/cmd/sntp.rst | 72 ++++++++++++++++++++++++++++++++++++++++++ doc/usage/index.rst | 1 + 3 files changed, 73 insertions(+), 17 deletions(-) delete mode 100644 doc/README.SNTP create mode 100644 doc/usage/cmd/sntp.rst diff --git a/doc/README.SNTP b/doc/README.SNTP deleted file mode 100644 index da9ec459ad4..00000000000 --- a/doc/README.SNTP +++ /dev/null @@ -1,17 +0,0 @@ -To use SNTP support, add define CONFIG_CMD_SNTP to the -configuration file of the board. - -The "sntp" command gets network time from NTP time server and -syncronize RTC of the board. This command needs the command line -parameter of server's IP address or environment variable -"ntpserverip". The network time is sent as UTC. So if you want to -set local time to RTC, set the offset in second from UTC to the -environment variable "time offset". - -If the DHCP server provides time server's IP or time offset, you -don't need to set the above environment variables yourself. - -Current limitations of SNTP support: -1. The roundtrip time is ignored. -2. Only the 1st NTP server IP, in the option ntp-servers of DHCP, will - be used. diff --git a/doc/usage/cmd/sntp.rst b/doc/usage/cmd/sntp.rst new file mode 100644 index 00000000000..d97f83053f7 --- /dev/null +++ b/doc/usage/cmd/sntp.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: sntp (command) + +sntp command +============ + +Synopsis +-------- + +:: + + sntp [serverip] + sntp [servername] # NET_LWIP=y && CMD_DNS=y only + + +Description +----------- + +The sntp command gets the current time from an NTP time server and +syncronizes the Real Time Clock (RTC) of the board. This command needs +the server's IP address to be given on the command line or via the +`ntpserverip` environment variable. + +The address of the NTP server does not need to be given if the DHCP server +provides one. The legacy network stack (`CONFIG_NET=y`) can only use the +first NTP server provided in the `ntp-servers` DHCP option. + +When the network stack is lwIP (`CONFIG_NET_LWIP=y`) and the dns command +is enabled (`CONFIG_CMD_DNS=y`), then the sntp command accepts a server +name as an argument. + +The network time is sent as UTC. So, if you want to set the RTC to any local +time different from UTC, you need to set the `timeoffset` environment variable. + +Round-trip delay compensation is not implemented/not enabled. In practice +this should not matter much given that the RTC API does not have sub-second +resolution, and round-trip times are typically 10 to 100 ms at most. + +Examples +-------- + +:: + + => setenv ntpserverip 109.190.177.205 + => date + Date: 2025-06-16 (Monday) Time: 15:19:35 + => date reset + Reset RTC... + Date: 2000-01-01 (Saturday) Time: 0:00:00 + => date + Date: 2000-01-01 (Saturday) Time: 0:00:03 + => sntp + Date: 2025-06-16 Time: 15:19:43 + => date + Date: 2025-06-16 (Monday) Time: 15:19:47 + => setenv timeoffset 7200 + => sntp + Date: 2025-06-16 Time: 17:19:55 + => date + Date: 2025-06-16 (Monday) Time: 17:19:57 + +With `CONFIG_NET_LWIP=y` and `CONFIG_CMD_DNS=y`: + +:: + + => date reset + Reset RTC... + Date: 2000-01-01 (Saturday) Time: 0:00:00 + => sntp 0.us.pool.ntp.org + Date: 2025-06-16 Time: 15:10:59 diff --git a/doc/usage/index.rst b/doc/usage/index.rst index c5b45fd9290..e9e0bd04e05 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -119,6 +119,7 @@ Shell commands cmd/sleep cmd/sm cmd/smbios + cmd/sntp cmd/sound cmd/source cmd/tcpm -- 2.47.2