chumicro-timing-experimental 0.8.1

Wraparound-safe millisecond tick helpers plus wait value objects (deadlines, rates, signals) for CircuitPython, MicroPython, and CPython.

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-Experimental`)
circup install chumicro_timing

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

# CPython
pip install chumicro-timing-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_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

Symbol	Description
ticks_ms()	Current time in milliseconds — keeps counting even when it wraps around
ticks_diff(end, start)	Time elapsed between two tick values (handles wraparound correctly)
ticks_add(ticks, delta)	Add milliseconds to a tick value (handles wraparound correctly)

Value objects

Symbol	Description
Deadline(period_ms, now_ms)	A single armed timeout — expired(now) / remaining(now) / reset(now)
Rate(period_ms, now_ms)	Drift-free periodic cadence; due(now) fires at most once per period

Wait vocabulary (chumicro_timing.waits)

Opt-in completion-wait vocabulary for generator flows — import explicitly.

Symbol	Description
Signal()	A completion flag — set(value) / clear() / ready(now)
wait_for(signal, deadline_ms=None)	Generator suspension helper: yield from wait_for(signal)

Testing

Symbol	Description
FakeTicks(start_ms=0)	Deterministic tick source for host-side tests
FakeTicks.advance(amount_ms)	Move the fake clock forward

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.

Source	Runtime
supervisor.ticks_ms	CircuitPython 7+
time.ticks_ms	MicroPython, some CircuitPython builds
time.monotonic_ns	CPython, some CircuitPython boards
time.monotonic	Final fallback (float seconds → int ms)

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

Technical detail: tick wraparound

All sources are masked to a 2²⁹ ms period (~6.2 days). ticks_diff and ticks_add handle wraparound correctly, so your timers keep working even when the counter rolls over.

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

Example	What it shows
heartbeat_blink.py	Basic periodic Rate loop
multiple_heartbeats.py	Multiple Rate timers at different rates
timeout_check.py	One-shot deadline check using ticks_diff
debounce.py	Simulated button debounce
periodic_tick.py	Manual periodic loop (the same logic Rate wraps internally)
phase_locked_tick.py	Drift-free deadline carrier — same period across late loops
circuitpython_blink.py	LED blink on CircuitPython hardware
circuitpython_debounce.py	GPIO button debounce on CircuitPython
micropython_blink.py	LED blink on MicroPython hardware
micropython_debounce.py	GPIO button debounce on MicroPython

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