chumicro-timing

Timers that don't block. Your loop keeps ticking.

Capture ticks_ms() once per loop pass, hand it to a Rate or a Deadline, and you've got clean drift-free timing on CircuitPython, MicroPython, or CPython. Tick-source detection is automatic, wraparound is handled, and there are no dependencies on anything else in ChuMicro. It's where every other library starts.

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_timing

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

# CPython
pip install chumicro-timing

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

Quick example

from chumicro_timing import Rate, ticks_ms

rate = Rate(1000, ticks_ms())

while True:
    now = ticks_ms()
    if rate.due(now):
        print("one second elapsed")
    # ... do other work ...

What's included

Tick functions

Value objects

Wait vocabulary (chumicro_timing.waits)

Opt-in completion-wait vocabulary for generator flows. Import it explicitly.

Testing

Where this fits

Leaf: no upstream ChuMicro deps. Everything in ChuMicro that owns time depends on it: runner, sockets, ntp, requests, http_server, mqtt, websockets.

Platform support

You don't need to pick a tick source. The library picks the best one available on your runtime. Behavior is identical regardless of which source is used.

The library tries them top-to-bottom and uses the first one your runtime supports.

Testing your code

The chumicro_timing.testing module provides FakeTicks for deterministic host-side tests with no wall-clock waits:

from chumicro_timing import Rate
from chumicro_timing.testing import FakeTicks

fake = FakeTicks()
rate = Rate(100, fake.ticks_ms())

assert rate.due(fake.ticks_ms()) is False

fake.advance(100)
assert rate.due(fake.ticks_ms()) is True

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-timing
• Bundle: ChuMicro-Bundle (CircuitPython & MicroPython)
• Experimental bundle: ChuMicro-Bundle-Experimental
• Source: libraries/timing

License

MIT