chumicro-ntp-experimental 0.12.1

Runner-shaped SNTP client over an injected UDP socket — pure-Python, cross-runtime.

chumicro-ntp

An SNTP client that runs in your tick loop without blocking it.

Polls one server, advances on each runner tick, and gives you the unix seconds when the response lands. Pure Python, no compiled module, no time.sleep() — your LED keeps blinking through the network hop. UDP transport is injected so apps with a custom socket layer don't drag chumicro-sockets into the device deploy.

Part of the ChuMicro family — small, focused Python libraries for microcontrollers and laptops. Browse all libraries.

Install

# CircuitPython (after `circup bundle-add ChuMicro/ChuMicro-Bundle`)
circup install chumicro-ntp

# MicroPython
mpremote mip install github:ChuMicro/ChuMicro-Bundle/chumicro_ntp

# CPython
pip install chumicro-ntp

For bundle setup, pre-compiled .mpy bundles, the experimental channel, and details on PyPI naming, see the chumicro INSTALL guide.

Quick example

from chumicro_ntp import NTPClient
from chumicro_ntp.sockets_factory import chumicro_sockets_factory
from chumicro_timing import ticks_ms

# On CircuitPython pass radio=wifi.radio; the kwarg is ignored on MP / CPython.
sock = chumicro_sockets_factory(radio=None)
sock.setblocking(False)                     # required — a blocking recv wedges on packet loss
client = NTPClient(socket=sock, server="pool.ntp.org")
request = client.query()
while not request.done:
    if client.check(ticks_ms()):
        client.handle(ticks_ms())
print("unix seconds:", request.unix_seconds)

chumicro_sockets_factory lives in its own submodule so apps with a custom UDP transport don't pull chumicro-sockets into their device deploy. Pass any object satisfying the sendto / recvfrom_into / close / setblocking contract (see NTPClient's docstring) to NTPClient(socket=...) — chumicro_sockets.udp_socket and chumicro_sockets.testing.FakeUDPSocket are the built-in producers.

What's included

Symbol	Purpose
NTPClient(socket, *, server="pool.ntp.org", port=123, timeout_ms=5000, ticks=None)	Runner-shaped SNTP client. Single in-flight query at a time; mirrors HttpClient.busy.
NTPClient.query()	Send a request; returns a NTPResult to poll.
NTPClient.check(now_ms) / handle(now_ms)	Runner contract — handle drains the recv socket and detects timeouts.
NTPClient.cancel()	Abort an in-flight query.
NTPResult	Per-query handle. done, unix_seconds, error.
NTPError	OSError subclass raised on protocol-level failures (short/malformed response, kiss-of-death, timeout, cancel).
chumicro_ntp.sockets_factory.chumicro_sockets_factory(radio=None)	One-line default UDP socket wired through chumicro-sockets. Importable separately so the deploy graph doesn't pull chumicro-sockets for apps with a custom transport.

Where this fits

Depends on chumicro-sockets for UDP transport and chumicro-timing for ticks. A single pip install chumicro-ntp brings the stack. Used directly in app code; no other ChuMicro library depends on it.

Platform support

Pure-Python; runs identically on CPython, MicroPython, and CircuitPython.

Examples

Example	What it shows
examples/ntp_query.py	Real query against pool.ntp.org — wifi up, UDP socket via factory, runner-shaped poll loop. Cross-runtime (CP + MP).

Contributing

Working on chumicro-ntp itself? Clone the mono-repo if you haven't already — the rest of the workflow assumes you're inside that workspace.

pip install -e .[test]
pytest tests/                  # host-side tests
pytest functional_tests/       # on-device tests (needs a board registered in devices.yml)

Register a board before running functional tests: chumicro-workspace add-device <id> --address <port>.

Docs

📖 Stable docs · Experimental docs

Find this library

• PyPI: chumicro-ntp
• Bundle: ChuMicro-Bundle (CircuitPython & MicroPython)
• Experimental bundle: ChuMicro-Bundle-Experimental
• Source: libraries/ntp

License

MIT