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-Experimental`)
circup install chumicro_ntp

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

# CPython
pip install chumicro-ntp-experimental

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-experimental 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)

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

chumicro_ntp_experimental-0.12.2.tar.gz (22.0 kB view details)

Uploaded Jul 19, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

chumicro_ntp_experimental-0.12.2-py3-none-any.whl (8.0 kB view details)

Uploaded Jul 19, 2026 Python 3

File details

Details for the file chumicro_ntp_experimental-0.12.2.tar.gz.

File metadata

Download URL: chumicro_ntp_experimental-0.12.2.tar.gz
Upload date: Jul 19, 2026
Size: 22.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for chumicro_ntp_experimental-0.12.2.tar.gz
Algorithm	Hash digest
SHA256	`191e01c0b379dfb1a8b6b707f20f26e3c51f7bdf471272a1b404a91a45a07537`
MD5	`bddf5df9b5c7f96c4dfd9f3b85f0430b`
BLAKE2b-256	`0ccebc4f6d540acf14ffe39425a301389aa5e2336c136178bb1fab282ede556d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for chumicro_ntp_experimental-0.12.2.tar.gz:

Publisher: release.yml on ChuMicro/ChuMicro

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: chumicro_ntp_experimental-0.12.2.tar.gz
- Subject digest: 191e01c0b379dfb1a8b6b707f20f26e3c51f7bdf471272a1b404a91a45a07537
- Sigstore transparency entry: 2199635206
- Sigstore integration time: Jul 19, 2026
Source repository:
- Permalink: ChuMicro/ChuMicro@bd5a08ba89ce08ea17dd027ff20cebf5d20244f8
- Branch / Tag: refs/heads/main
- Owner: https://github.com/ChuMicro
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@bd5a08ba89ce08ea17dd027ff20cebf5d20244f8
- Trigger Event: push