docs: enhance docstrings for all equipment classes

Author: cryptk

pyomnilogic_local/_base.py

@@ -18,11 +18,40 @@
 
 
 class OmniEquipment(Generic[MSPConfigT, TelemetryT]):
-    """Base class for OmniLogic equipment.
+    """Base class for all OmniLogic equipment.
 
-    Generic parameters:
+    This is an abstract base class that provides common functionality for all equipment
+    types in the OmniLogic system. It handles configuration updates, telemetry updates,
+    and provides access to the API for control operations.
+
+    All equipment classes inherit from this base and are strongly typed using generic
+    parameters for their specific configuration and telemetry types.
+
+    Generic Parameters:
         MSPConfigT: The specific MSP configuration type (e.g., MSPBoW, MSPRelay)
-        TelemetryT: The specific telemetry type (e.g., TelemetryBoW, TelemetryRelay, or None for equipment without telemetry)
+        TelemetryT: The specific telemetry type (e.g., TelemetryBoW, TelemetryRelay, or None)
+
+    Attributes:
+        mspconfig: Configuration data from the MSP XML
+        telemetry: Live telemetry data (may be None for equipment without telemetry)
+        child_equipment: Dictionary of child equipment indexed by system_id
+
+    Properties:
+        bow_id: The body of water ID this equipment belongs to
+        name: Equipment name from configuration
+        system_id: Unique system identifier
+        omni_type: OmniLogic type identifier
+        is_ready: Whether equipment can accept commands (checks backyard state)
+
+    Example:
+        Equipment classes should not be instantiated directly. Access them through
+        the OmniLogic instance:
+
+        >>> omni = OmniLogic("192.168.1.100")
+        >>> await omni.refresh()
+        >>> # Access equipment through the backyard
+        >>> pool = omni.backyard.bow["Pool"]
+        >>> pump = pool.pumps["Main Pump"]
     """
 
     mspconfig: MSPConfigT

pyomnilogic_local/backyard.py

@@ -19,7 +19,78 @@
 
 
 class Backyard(OmniEquipment[MSPBackyard, TelemetryBackyard]):
-    """Represents the backyard equipment in the OmniLogic system."""
+    """Represents the backyard (top-level equipment container) in the OmniLogic system.
+
+    The Backyard is the root equipment container that holds all pool and spa
+    equipment. It contains:
+    - Bodies of Water (BoW): Pools and spas
+    - Backyard-level lights: Lights not associated with a specific body of water
+    - Backyard-level relays: Auxiliary equipment, landscape lighting, etc.
+    - Backyard-level sensors: Air temperature, etc.
+
+    The Backyard also provides system-wide status information including air
+    temperature, service mode state, and firmware version.
+
+    Attributes:
+        mspconfig: Configuration data for the backyard
+        telemetry: Real-time system-wide telemetry
+        bow: Collection of Bodies of Water (pools/spas)
+        lights: Collection of backyard-level lights
+        relays: Collection of backyard-level relays
+        sensors: Collection of backyard-level sensors
+
+    Properties (Telemetry):
+        status_version: Telemetry protocol version number
+        air_temp: Current air temperature (Fahrenheit)
+        state: System state (ON, OFF, SERVICE_MODE, CONFIG_MODE, etc.)
+        config_checksum: Configuration checksum (status_version 11+)
+        msp_version: MSP firmware version string (status_version 11+)
+        is_service_mode: True if in any service/config mode
+
+    Example:
+        >>> omni = OmniLogic("192.168.1.100")
+        >>> await omni.refresh()
+        >>>
+        >>> # Access backyard
+        >>> backyard = omni.backyard
+        >>>
+        >>> # Check system status
+        >>> print(f"Air temp: {backyard.air_temp}°F")
+        >>> print(f"System state: {backyard.state}")
+        >>> print(f"Firmware: {backyard.msp_version}")
+        >>>
+        >>> # Check service mode
+        >>> if backyard.is_service_mode:
+        ...     print("System is in service mode - equipment cannot be controlled")
+        >>>
+        >>> # Access bodies of water
+        >>> for bow in backyard.bow:
+        ...     print(f"Body of Water: {bow.name} ({bow.equip_type})")
+        >>>
+        >>> # Access backyard equipment
+        >>> for light in backyard.lights:
+        ...     print(f"Backyard light: {light.name}")
+        >>>
+        >>> for relay in backyard.relays:
+        ...     print(f"Backyard relay: {relay.name}")
+
+    Service Mode:
+        When the backyard is in service mode (SERVICE_MODE, CONFIG_MODE, or
+        TIMED_SERVICE_MODE), equipment control is disabled. This typically
+        occurs during:
+        - System maintenance
+        - Configuration changes
+        - Timed service operations
+
+        Always check is_service_mode or is_ready before controlling equipment.
+
+    Note:
+        - The Backyard is the root of the equipment hierarchy
+        - All equipment belongs to either the Backyard or a Body of Water
+        - Service mode blocks all equipment control operations
+        - Configuration changes require backyard state changes
+        - Air temperature sensor must be configured for air_temp readings
+    """
 
     mspconfig: MSPBackyard
     telemetry: TelemetryBackyard

pyomnilogic_local/bow.py

@@ -21,7 +21,108 @@
 
 
 class Bow(OmniEquipment[MSPBoW, TelemetryBoW]):
-    """Represents a bow in the OmniLogic system."""
+    """Represents a Body of Water (BoW) - pool or spa - in the OmniLogic system.
+
+    A Body of Water (commonly abbreviated as BoW) is a pool or spa, along with
+    all of its associated equipment. Each BoW contains:
+    - Filtration pumps
+    - Heating equipment
+    - Chlorination/sanitization systems
+    - Chemistry monitoring (CSAD)
+    - Lighting
+    - Auxiliary pumps (water features, etc.)
+    - Relays (jets, blowers, etc.)
+    - Sensors (water temperature, flow, etc.)
+
+    The Bow class provides access to all equipment associated with a specific
+    pool or spa, as well as water temperature monitoring and spillover control
+    for pool/spa combination systems.
+
+    Attributes:
+        mspconfig: Configuration data for this body of water
+        telemetry: Real-time operational data
+        filters: Collection of filtration pumps
+        heater: Virtual heater (if configured)
+        relays: Collection of relays (jets, blowers, aux equipment)
+        sensors: Collection of sensors (water temp, flow, etc.)
+        lights: Collection of ColorLogic lights
+        pumps: Collection of pumps (water features, etc.)
+        chlorinator: Chlorinator system (if configured)
+        csads: Collection of CSAD (chemistry) systems
+
+    Properties (Configuration):
+        equip_type: Body of water type (BOW_POOL or BOW_SPA)
+        supports_spillover: Whether spillover is available
+
+    Properties (Telemetry):
+        water_temp: Current water temperature (Fahrenheit)
+        flow: True if flow is detected, False otherwise
+
+    Control Methods:
+        set_spillover(speed): Set spillover pump speed (0-100%)
+        turn_on_spillover(): Turn on spillover at maximum speed
+        turn_off_spillover(): Turn off spillover
+
+    Example:
+        >>> omni = OmniLogic("192.168.1.100")
+        >>> await omni.refresh()
+        >>>
+        >>> # Access pool
+        >>> pool = omni.backyard.bow["Pool"]
+        >>> print(f"Water temp: {pool.water_temp}°F")
+        >>> print(f"Flow detected: {pool.flow > 0}")
+        >>>
+        >>> # Access pool equipment
+        >>> if pool.heater:
+        ...     await pool.heater.set_temperature(85)
+        >>>
+        >>> if pool.chlorinator:
+        ...     print(f"Salt level: {pool.chlorinator.avg_salt_level} ppm")
+        >>>
+        >>> for filter in pool.filters:
+        ...     print(f"Filter: {filter.name}, Speed: {filter.speed}%")
+        >>>
+        >>> for light in pool.lights:
+        ...     await light.set_show(ColorLogicShow25.TROPICAL)
+        >>>
+        >>> # Spillover control (pool/spa combo systems)
+        >>> if pool.supports_spillover:
+        ...     await pool.turn_on_spillover()
+        ...     await pool.set_spillover(75)  # 75% speed
+        ...     await pool.turn_off_spillover()
+
+    Pool vs Spa:
+        Bodies of water can be either pools or spas, distinguished by the
+        equip_type property:
+
+        >>> if pool.equip_type == BodyOfWaterType.POOL:
+        ...     print("This is a pool")
+        >>> elif pool.equip_type == BodyOfWaterType.SPA:
+        ...     print("This is a spa")
+
+    Spillover Systems:
+        Some installations have combined pool/spa systems with spillover
+        capability that allows water to flow from spa to pool or vice versa:
+
+        - supports_spillover indicates if the feature is available
+        - Spillover is controlled by a dedicated pump
+        - Speed range is 0-100% (0 turns spillover off)
+        - Convenience methods simplify on/off operations
+
+    Equipment Collections:
+        Equipment is stored in EquipmentDict collections which allow access by:
+        - Name (string): pool.filters["Main Filter"]
+        - System ID (int): pool.filters[123]
+        - Index (int): pool.filters[0]
+        - Iteration: for filter in pool.filters: ...
+
+    Note:
+        - Water temperature returns -1 if sensor not available
+        - Flow telemetry typically reads 255 or 1 for flow, 0 for no flow, we simplify to bool
+        - Not all bodies of water have all equipment types
+        - Some equipment (heater, chlorinator) may be None if not configured
+        - Spillover operations raise ValueError if not supported
+    """
 
     mspconfig: MSPBoW
     telemetry: TelemetryBoW
@@ -56,13 +157,17 @@ def water_temp(self) -> int:
         return self.telemetry.water_temp
 
     @property
-    def flow(self) -> int:
+    def flow(self) -> bool:
         """Current flow sensor reading.
 
         Returns:
-            Flow value (255 typically indicates flow present, 0 indicates no flow)
+            bool: True if flow is present, False otherwise.
         """
-        return self.telemetry.flow
+        # Flow values:
+        # 255 seems to indicate "assumed flow", for example, because a filter pump is on
+        # 1 seems to indicate "certain flow", for example, when there is an actual flow sensor
+        # 0 indicates no flow
+        return self.telemetry.flow > 0
 
     # Control methods
     @dirties_state()

pyomnilogic_local/colorlogiclight.py

@@ -24,7 +24,90 @@
 
 
 class ColorLogicLight(OmniEquipment[MSPColorLogicLight, TelemetryColorLogicLight]):
-    """Represents a color logic light."""
+    """Represents a ColorLogic or compatible LED light in the OmniLogic system.
+
+    ColorLogic lights are intelligent LED pool and spa lights that can display
+    various color shows, patterns, and effects. The OmniLogic system supports
+    multiple light models with different capabilities:
+
+    Light Models:
+        - ColorLogic 2.5: Classic model with 10 preset shows
+        - ColorLogic 4.0: Enhanced model with 15 preset shows
+        - ColorLogic UCL (UniversaLogic): Universal controller for various lights
+        - ColorLogic SAM: Smart lighting system
+        - Pentair and Zodiac compatible lights (limited functionality)
+
+    Each light model supports different shows, speeds, and brightness levels.
+    The ColorLogicLight class automatically handles these differences.
+
+    Attributes:
+        mspconfig: Configuration data for this light from MSP XML
+        telemetry: Real-time operational state and settings
+
+    Properties (Configuration):
+        model: Light model type (TWO_FIVE, FOUR_ZERO, UCL, SAM, etc.)
+        v2_active: Whether V2 protocol features are active
+        effects: List of available light shows for this model
+
+    Properties (Telemetry):
+        state: Current power state (ON, OFF, transitional states)
+        show: Currently selected light show
+        speed: Show animation speed (1x, 2x, 4x, 8x)
+        brightness: Light brightness (25%, 50%, 75%, 100%)
+        special_effect: Special effect setting
+
+    Properties (Computed):
+        is_on: True if light is currently on
+        is_ready: True if light can accept commands (not in transitional state)
+
+    Control Methods:
+        turn_on(): Turn on light (starts at saved show)
+        turn_off(): Turn off light
+        toggle(): Toggle light on/off
+        set_show(show): Set light to specific show
+        set_speed(speed): Set animation speed (1x-8x)
+        set_brightness(brightness): Set brightness (25%-100%)
+
+    Example:
+        >>> pool = omni.backyard.bow["Pool"]
+        >>> pool_light = pool.lights["Pool Light"]
+        >>>
+        >>> # Check light capabilities
+        >>> print(f"Light model: {pool_light.model}")
+        >>> print(f"Available shows: {pool_light.effects}")
+        >>>
+        >>> # Check current state
+        >>> if pool_light.is_on:
+        ...     print(f"Show: {pool_light.show}")
+        ...     print(f"Speed: {pool_light.speed}")
+        ...     print(f"Brightness: {pool_light.brightness}")
+        >>>
+        >>> # Control light
+        >>> await pool_light.turn_on()
+        >>> await pool_light.set_show(ColorLogicShow25.TROPICAL)
+        >>> await pool_light.set_speed(ColorLogicSpeed.TWO_TIMES)
+        >>> await pool_light.set_brightness(ColorLogicBrightness.SEVENTY_FIVE_PERCENT)
+        >>> await pool_light.turn_off()
+
+    Important - Light State Transitions:
+        ColorLogic lights go through several transitional states when changing
+        settings. During these states, the light is NOT ready to accept commands:
+
+        - FIFTEEN_SECONDS_WHITE: 15-second white period after power on
+        - CHANGING_SHOW: Actively cycling through shows
+        - POWERING_OFF: In process of turning off
+        - COOLDOWN: Cooling down after being turned off
+
+        Always check is_ready before sending commands, or wait for state to
+        stabilize after each command.
+
+    Note:
+        - Different light models support different show sets
+        - Non-ColorLogic lights (Pentair, Zodiac) have limited control
+        - Speed and brightness may not be adjustable on all models
+        - Some shows may require specific light hardware
+        - V2 protocol enables enhanced features on compatible lights
+    """
 
     mspconfig: MSPColorLogicLight
     telemetry: TelemetryColorLogicLight