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-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.adapter.radio (your chumicro-wifi
# WifiService's board 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)

In a program with more going on, hand the loop to chumicro-runner:

from chumicro_runner import Runner

runner = Runner()
runner.add(client)

while not request.done:
    now = runner.tick()
    runner.wait(now)

wait() parks the CPU until the reply lands.

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

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