Utilities

pydoover includes a set of utility modules that solve common problems in IoT application development. These utilities are available from pydoover.utils and cover control systems, data manipulation, async programming, and state management.

These utilities implement classic control theory building blocks used in feedback loops and sensor processing:

• PID Controller -- a proportional-integral-derivative controller for feedback control loops such as pump speed regulation or temperature control.
• Kalman Filter -- a 1D Kalman filter for smoothing noisy sensor readings, with built-in outlier protection and decorator support.
• Alarms -- threshold monitoring with grace periods and minimum inter-alarm intervals to prevent false alarms and alarm fatigue.

• Dictionary Diff -- generate and apply minimal diffs between dictionaries. Used extensively in tag management and aggregate updates throughout the platform.
• Snowflake IDs -- generate and decode Doover-format snowflake identifiers that encode timestamp, type, region, and instance information.
• Other helpers -- sanitize_display_name() for normalising strings, map_reading() for 4-20mA sensor mapping, find_object_with_key() / find_path_to_key() for deep dictionary searching, CaseInsensitiveDict for case-insensitive key lookups, and zip_files() for in-memory ZIP creation.

• Async Helpers -- utilities for bridging synchronous and asynchronous code, including context detection, universal function callers, exception-swallowing wrappers, and change-detection decorators.

• State Machine -- an async state machine with timeout support, built on the transitions library. Define states with timeouts and auto-transitions for modelling device behaviour.

Most utilities are re-exported from the top-level pydoover.utils package:

from pydoover.utils import (
    PID,
    apply_kalman_filter,
    apply_async_kalman_filter,
    create_alarm,
    apply_diff,
    generate_diff,
    generate_snowflake_id,
    get_datetime_from_snowflake,
    map_reading,
    get_is_async,
    maybe_async,
    call_maybe_async,
    on_change,
    setup_logging,
)

The KalmanFilter1D class and Alarm class can be imported from their respective submodules:

from pydoover.utils.kalman import KalmanFilter1D
from pydoover.utils.alarm import Alarm

The StateMachine class is imported from pydoover.state:

from pydoover.state import StateMachine