chumicro-ntp

An SNTP (Simple Network Time Protocol) 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_sockets import udp_socket
from chumicro_timing import ticks_ms

# On CircuitPython pass radio=wifi.radio; the kwarg is ignored on MP / CPython.
sock = udp_socket(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.udp_socket builds the default bound UDP socket. 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. NTPClient.from_config wires that default itself through the shared chumicro_sockets.sockets_factory module, imported lazily, so apps with a custom UDP transport keep chumicro-sockets out of their device deploy.

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_sockets.udp_socket(radio=None)`	Built-in bound UDP socket for `NTPClient(socket=...)`. `NTPClient.from_config` reaches it through the shared `chumicro_sockets.sockets_factory`; a custom transport skips that import and keeps `chumicro-sockets` out of the deploy.

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

Issues, bug reports, and pull requests are welcome, and so is "I ran it on this board and here's what happened", some of the most useful feedback a hardware project can get. Development happens in the ChuMicro repository, whose contributing guide covers setup and the test workflow.

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-0.13.1.tar.gz (22.1 kB view details)

Uploaded Aug 7, 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-0.13.1-py3-none-any.whl (7.5 kB view details)

Uploaded Aug 7, 2026 Python 3

File details

Details for the file chumicro_ntp-0.13.1.tar.gz.

File metadata

Download URL: chumicro_ntp-0.13.1.tar.gz
Upload date: Aug 7, 2026
Size: 22.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for chumicro_ntp-0.13.1.tar.gz
Algorithm	Hash digest
SHA256	`b37713308039eeef0dcf406b8b6a73c9595918a88dee281e44f73cd8a47062a6`
MD5	`dab1dd3862d2a70cf6a6694d5c503313`
BLAKE2b-256	`7e6610058598e6c98ea60e08f6e9037ed738a1ef01702facbb9d309eb07092d7`

See more details on using hashes here.

Provenance

The following attestation bundles were made for chumicro_ntp-0.13.1.tar.gz:

Publisher: promote.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-0.13.1.tar.gz
- Subject digest: b37713308039eeef0dcf406b8b6a73c9595918a88dee281e44f73cd8a47062a6
- Sigstore transparency entry: 2372558841
- Sigstore integration time: Aug 7, 2026
Source repository:
- Permalink: ChuMicro/ChuMicro@562fc9a19cb9feb31da804c9499e6d9678195774
- 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: promote.yml@562fc9a19cb9feb31da804c9499e6d9678195774
- Trigger Event: workflow_dispatch