kopia lustrzana https://github.com/micropython/micropython
docs/library: Add docs for ntptime.py module.
docs/library/ntptime.rst: New file. docs/library/index.rst: Add ntptime to the table of contents. Signed-off-by: Jon Foster <jon@jon-foster.co.uk>pull/14163/head
rodzic
35b2edfc24
commit
345bf8f03b
|
@ -103,6 +103,7 @@ the following libraries.
|
||||||
micropython.rst
|
micropython.rst
|
||||||
neopixel.rst
|
neopixel.rst
|
||||||
network.rst
|
network.rst
|
||||||
|
ntptime.rst
|
||||||
openamp.rst
|
openamp.rst
|
||||||
uctypes.rst
|
uctypes.rst
|
||||||
vfs.rst
|
vfs.rst
|
||||||
|
|
|
@ -0,0 +1,112 @@
|
||||||
|
*****************************************************
|
||||||
|
:mod:`ntptime` --- Network Time Protocol (NTP) Client
|
||||||
|
*****************************************************
|
||||||
|
|
||||||
|
.. module:: ntptime
|
||||||
|
:synopsis: Network Time Protocol (NTP) Client
|
||||||
|
|
||||||
|
This module provides a very simple SNTP client. It fetches the current time
|
||||||
|
from a server on the Internet, or from a server on a local network.
|
||||||
|
|
||||||
|
To use this module, a MicroPython variant/build with network capabilities must
|
||||||
|
be installed, and the ntptime module must be enabled.
|
||||||
|
|
||||||
|
For details of the SNTP protocol, see RFC 4330.
|
||||||
|
|
||||||
|
All times are in UTC. There is no timezone support in this module, although
|
||||||
|
you could apply your own timezone adjustment to the returned UTC times.
|
||||||
|
|
||||||
|
This module only provides time with 1-second resolution.
|
||||||
|
|
||||||
|
This module does not make any attempt to account for network latencies.
|
||||||
|
On a normal internet connection, this won't matter, especially given the
|
||||||
|
1 second resolution. On a high-latency internet connection, you will have to
|
||||||
|
increase the default 1 second request timeout for this module to work at all,
|
||||||
|
and then the time will be slightly wrong due to the time the response takes to
|
||||||
|
travel from the NTP server to this client.
|
||||||
|
|
||||||
|
There is no special handling of leap seconds. This probably means that time
|
||||||
|
will jump by 1 second when a leap second happens. But some NTP servers may
|
||||||
|
do "leap smearing" instead. Given that the resolution is only 1 second
|
||||||
|
anyway, leap seconds are unlikely to cause any extra issues.
|
||||||
|
|
||||||
|
There is no security whatsoever. An attacker who wants to change the time
|
||||||
|
of your system, can send forged responses to your system. If any of them
|
||||||
|
arrive after the NTP request was sent, but before the genuine NTP response
|
||||||
|
is received, then the time set by the attacker will be used. Note that for
|
||||||
|
Internet-facing devices, the attacker does not even need to spoof their IP
|
||||||
|
address for this attack to work, this module does not check the sender of the
|
||||||
|
packet in any way. A typical home NAT firewall may make the attack slightly
|
||||||
|
harder, requiring an attacker to spoof their IP address, but attackers can
|
||||||
|
do that.
|
||||||
|
|
||||||
|
This module does not do any sanity checking on the returned time to detect
|
||||||
|
faulty or malicious NTP servers.
|
||||||
|
|
||||||
|
This module does not support the "Kiss-o'-Death Packet" defined in RFC4330.
|
||||||
|
|
||||||
|
This module does not suffer from the Y2036 bug. It supports timestamps up
|
||||||
|
to and including the year 2159. It does suffer from a Y2160 bug, which will
|
||||||
|
need fixing closer to that time, if MicroPython is still being used.
|
||||||
|
|
||||||
|
For example::
|
||||||
|
|
||||||
|
# Print the current time, as seconds since the epoch.
|
||||||
|
import ntptime
|
||||||
|
print(ntptime.time())
|
||||||
|
|
||||||
|
# Set the platfom's RTC
|
||||||
|
ntptime.settime()
|
||||||
|
|
||||||
|
# Print the current time
|
||||||
|
import time
|
||||||
|
print(time.gmtime())
|
||||||
|
|
||||||
|
|
||||||
|
Functions
|
||||||
|
=========
|
||||||
|
|
||||||
|
.. function:: time() -> int
|
||||||
|
|
||||||
|
Query the configured NTP server for the current time, and returns that time.
|
||||||
|
|
||||||
|
The returned value is seconds since the Epoch, where the Epoch is as defined
|
||||||
|
in the MicroPython :mod:`time` module.
|
||||||
|
|
||||||
|
Raises an exception if the configured NTP server hostname cannot be resolved.
|
||||||
|
|
||||||
|
Raises :exc:`OSError` if the SNTP request times out.
|
||||||
|
|
||||||
|
Raises an exception if the SNTP response is too short.
|
||||||
|
|
||||||
|
.. function:: settime()
|
||||||
|
|
||||||
|
Query the configured NTP server for the current time, and set the platform's
|
||||||
|
clock to that time.
|
||||||
|
|
||||||
|
This sets the clock using :class:`machine.RTC`.
|
||||||
|
|
||||||
|
.. data:: host
|
||||||
|
:type: str
|
||||||
|
:value: "pool.ntp.org"
|
||||||
|
|
||||||
|
The hostname of the NTP server to use.
|
||||||
|
|
||||||
|
May be set by applications.
|
||||||
|
|
||||||
|
For example, may be set to an NTP server provided by your ISP, or one that
|
||||||
|
is on the local network.
|
||||||
|
|
||||||
|
For commercial products, you should set this to your assigned NTP hostname,
|
||||||
|
you should not use the default. You need to contact the NTP Pool to get
|
||||||
|
permission to use their servers, and to get your own NTP hostname assigned.
|
||||||
|
See the NTP Pool's
|
||||||
|
`Information for vendors <https://www.ntppool.org/en/vendors.html>`_
|
||||||
|
|
||||||
|
.. data:: timeout
|
||||||
|
:type: float | int
|
||||||
|
:value: 1
|
||||||
|
|
||||||
|
The timeout period for SNTP requests, in seconds.
|
||||||
|
|
||||||
|
May be changed by applications. The default is 1 second.
|
Ładowanie…
Reference in New Issue