feat: add custom exception classes for better error handling

- Add OmniEquipmentNotReadyError for equipment in non-ready states
- Add OmniEquipmentNotInitializedError for uninitialized equipment
- Add OmniConnectionError for controller communication failures
- Export all exceptions in __init__.py for easy importing
- Replace ValueError with OmniEquipmentNotInitializedError in ColorLogicLight methods

All exceptions inherit from OmniLogicLocalError base class and include
comprehensive docstrings with usage examples.

Author: cryptk

pyomnilogic_local/__init__.py

@@ -1,3 +1,15 @@
 from .omnilogic import OmniLogic
+from .util import (
+    OmniConnectionError,
+    OmniEquipmentNotInitializedError,
+    OmniEquipmentNotReadyError,
+    OmniLogicLocalError,
+)
 
-__all__ = ["OmniLogic"]
+__all__ = [
+    "OmniLogic",
+    "OmniLogicLocalError",
+    "OmniEquipmentNotReadyError",
+    "OmniEquipmentNotInitializedError",
+    "OmniConnectionError",
+]

pyomnilogic_local/colorlogiclight.py

@@ -11,6 +11,7 @@
     ColorLogicSpeed,
     LightShows,
 )
+from pyomnilogic_local.util import OmniEquipmentNotInitializedError
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -70,13 +71,13 @@ def special_effect(self) -> int:
     async def turn_on(self) -> None:
         """Turns the light on."""
         if self.bow_id is None or self.system_id is None:
-            raise ValueError("Cannot turn on light: bow_id or system_id is None")
+            raise OmniEquipmentNotInitializedError("Cannot turn on light: bow_id or system_id is None")
         await self._api.async_set_equipment(self.bow_id, self.system_id, True)
 
     async def turn_off(self) -> None:
         """Turns the light off."""
         if self.bow_id is None or self.system_id is None:
-            raise ValueError("Cannot turn off light: bow_id or system_id is None")
+            raise OmniEquipmentNotInitializedError("Cannot turn off light: bow_id or system_id is None")
         await self._api.async_set_equipment(self.bow_id, self.system_id, False)
 
     async def set_show(
@@ -102,7 +103,7 @@ async def set_show(
                 brightness = ColorLogicBrightness.ONE_HUNDRED_PERCENT
 
         if self.bow_id is None or self.system_id is None:
-            raise ValueError("Cannot set light show: bow_id or system_id is None")
+            raise OmniEquipmentNotInitializedError("Cannot set light show: bow_id or system_id is None")
 
         await self._api.async_set_light_show(
             self.bow_id,

pyomnilogic_local/util.py

@@ -11,6 +11,37 @@ class OmniLogicLocalError(Exception):
     """Base exception for python-omnilogic-local."""
 
 
+class OmniEquipmentNotReadyError(OmniLogicLocalError):
+    """Raised when equipment cannot accept commands due to its current state.
+
+    Examples:
+        - Light in FIFTEEN_SECONDS_WHITE state
+        - Light in CHANGING_SHOW state
+        - Light in POWERING_OFF state
+        - Light in COOLDOWN state
+        - Equipment performing initialization or calibration
+    """
+
+
+class OmniEquipmentNotInitializedError(OmniLogicLocalError):
+    """Raised when equipment has not been properly initialized.
+
+    This typically occurs when required identifiers (bow_id or system_id) are None,
+    indicating the equipment hasn't been populated from telemetry data yet.
+    """
+
+
+class OmniConnectionError(OmniLogicLocalError):
+    """Raised when communication with the OmniLogic controller fails.
+
+    Examples:
+        - UDP socket timeout
+        - Network unreachable
+        - Invalid response from controller
+        - Protocol errors
+    """
+
+
 class PrettyEnum(Enum):
     def pretty(self) -> str:
         return self.name.replace("_", " ").title()