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_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

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

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