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

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

License

MIT