API Reference¶
Tick Functions¶
chumicro_timing.ticks
¶
Cross-runtime millisecond tick helpers.
Provides wraparound-safe tick functions that work identically on
CircuitPython, MicroPython, and CPython. The API mirrors MicroPython's
time.ticks_ms / time.ticks_diff / time.ticks_add contract
with a fixed wrap period of 2**29 ms (~6.2 days).
The 229 period keeps add/subtract results below 230, avoiding heap-allocated long integers on boards without big-int support.
Design note¶
The wraparound-safe tick contract and the 2**29 period originate from
MicroPython's time module and are also used by Adafruit's
adafruit_ticks library (MIT-licensed). This module is an
independent implementation written from the mathematical specification
of modular/ring arithmetic for tick counters.
ticks_ms()
¶
Return a monotonic millisecond count in [0 .. 2**29 - 1].
Values wrap every ~6.2 days. Use ticks_diff and ticks_add
for arithmetic; plain subtraction gives wrong results near the
wrap boundary.
ticks_add(ticks, delta)
¶
Add delta milliseconds to a tick value, wrapping at 2**29.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ticks
|
int
|
Base tick value. |
required |
delta
|
int
|
Milliseconds to add. |
required |
Returns:
| Type | Description |
|---|---|
int
|
Wrapped tick value. |
Raises:
| Type | Description |
|---|---|
OverflowError
|
If delta is outside (-228 .. 228). |
ticks_diff(end, start)
¶
Signed difference end minus start with wraparound handling.
Correct as long as end and start are no more than 2**28 ms (~3.1 days) apart.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
end
|
int
|
Later tick value. |
required |
start
|
int
|
Earlier tick value. |
required |
Returns:
| Type | Description |
|---|---|
int
|
Signed difference in milliseconds. |
Heartbeat¶
chumicro_timing.heartbeat
¶
Periodic heartbeat driven by cross-runtime tick helpers.
Heartbeat
¶
Track whether a periodic heartbeat is due based on monotonic ticks.
Pass a shared now_ms timestamp to poll() and is_due() on
each loop iteration. The timestamp should be captured once per loop
and shared across all components to avoid time drift.
By default, uses the module-level ticks_diff helper for
wraparound-safe comparison. Pass a ticks object with ticks_ms
and ticks_diff methods to override (e.g. for tests).
period_ms
property
¶
Return the configured heartbeat period in milliseconds.
__init__(period_ms, ticks=None)
¶
Create a heartbeat that becomes due once every period_ms milliseconds.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
period_ms
|
int
|
Interval between beats. |
required |
ticks
|
object | None
|
Optional tick source (must have |
None
|
reset(now_ms)
¶
Reset the heartbeat schedule to start counting from now_ms.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
now_ms
|
int
|
Current tick value. |
required |
is_due(now_ms)
¶
Return whether the heartbeat period has elapsed since the last beat.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
now_ms
|
int
|
Current tick value. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
|
poll(now_ms)
¶
Return True once per elapsed period and advance the heartbeat state.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
now_ms
|
int
|
Current tick value. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
|