python-jebao 0.1.0__py3-none-any.whl

jebao/retry.py

@@ -0,0 +1,77 @@
+"""Retry logic for handling transient failures."""
+import asyncio
+import functools
+import logging
+from typing import Callable, Type, Tuple
+
+from .exceptions import JebaoConnectionError, JebaoTimeoutError
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def async_retry(
+    max_attempts: int = 3,
+    delay: float = 0.5,
+    backoff: float = 2.0,
+    exceptions: Tuple[Type[Exception], ...] = (JebaoConnectionError, JebaoTimeoutError),
+):
+    """Decorator to retry async functions on specific exceptions.
+
+    Args:
+        max_attempts: Maximum number of attempts (default 3)
+        delay: Initial delay between retries in seconds (default 0.5)
+        backoff: Multiplier for delay on each retry (default 2.0)
+        exceptions: Tuple of exception types to retry on
+
+    Example:
+        @async_retry(max_attempts=3, delay=1.0)
+        async def send_command(self):
+            # Code that might fail due to garbage bytes
+            pass
+    """
+
+    def decorator(func: Callable):
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs):
+            attempt = 1
+            current_delay = delay
+
+            while attempt <= max_attempts:
+                try:
+                    return await func(*args, **kwargs)
+                except exceptions as e:
+                    if attempt == max_attempts:
+                        _LOGGER.error(
+                            f"{func.__name__} failed after {max_attempts} attempts: {e}"
+                        )
+                        raise
+
+                    # Check if error message indicates garbage issue
+                    error_msg = str(e).lower()
+                    is_garbage_issue = (
+                        "synchronization" in error_msg
+                        or "garbage" in error_msg
+                        or "invalid header" in error_msg
+                    )
+
+                    if is_garbage_issue:
+                        _LOGGER.warning(
+                            f"{func.__name__} attempt {attempt}/{max_attempts} failed "
+                            f"due to garbage bytes, retrying in {current_delay}s: {e}"
+                        )
+                    else:
+                        _LOGGER.warning(
+                            f"{func.__name__} attempt {attempt}/{max_attempts} failed, "
+                            f"retrying in {current_delay}s: {e}"
+                        )
+
+                    await asyncio.sleep(current_delay)
+                    attempt += 1
+                    current_delay *= backoff
+
+            # This should never be reached due to raise in loop
+            return None
+
+        return wrapper
+
+    return decorator

python_jebao-0.1.0.dist-info/METADATA

@@ -0,0 +1,367 @@
+Metadata-Version: 2.4
+Name: python-jebao
+Version: 0.1.0
+Summary: Python library for controlling Jebao aquarium pumps
+Home-page: https://github.com/jrigling/python-jebao
+Author: Justin Rigling
+Author-email: Justin Rigling <jrigling@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jrigling/python-jebao
+Project-URL: Repository, https://github.com/jrigling/python-jebao
+Project-URL: Issues, https://github.com/jrigling/python-jebao/issues
+Project-URL: Documentation, https://github.com/jrigling/python-jebao#readme
+Keywords: jebao,aquarium,pump,home-assistant,iot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: netifaces>=0.11.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: build
+Requires-Dist: build>=0.10.0; extra == "build"
+Requires-Dist: twine>=4.0.0; extra == "build"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# python-jebao
+
+Python library for controlling Jebao aquarium pumps over local network.
+
+## Supported Models
+
+- **MDP-20000**: Variable-speed circulation pump (30-100% speed control)
+- **MD-4.4**: 4-channel dosing pump (planned)
+
+## Features
+
+- 🔍 **UDP Discovery** - Automatic device discovery with multi-subnet support
+- 🔌 **Local Control** - Direct TCP control, no cloud dependency
+- ⚡ **Full Protocol** - On/Off, speed control, feed mode, status monitoring
+- 🏠 **Home Assistant Ready** - Designed for HA integration
+- 🔒 **Type Safe** - Full type hints for better IDE support
+
+## Installation
+
+```bash
+pip install python-jebao
+```
+
+For development:
+```bash
+git clone https://github.com/jrigling/python-jebao.git
+cd python-jebao
+pip install -e .
+```
+
+## Quick Start
+
+### Discovery
+
+```python
+import asyncio
+from jebao import discover_devices
+
+async def main():
+    # Discover all Jebao devices on network
+    devices = await discover_devices()
+
+    for device in devices:
+        print(f"Found: {device.model} at {device.ip_address}")
+        print(f"  Device ID: {device.device_id}")
+        print(f"  MAC: {device.mac_address}")
+
+asyncio.run(main())
+```
+
+### Multi-Subnet Discovery
+
+If you have multiple network interfaces (e.g., IoT VLAN, main network):
+
+```python
+# Discover on all interfaces
+devices = await discover_devices()
+
+# Or specify interfaces explicitly
+devices = await discover_devices(interfaces=['eth0', 'eth1'])
+```
+
+### Basic Control
+
+```python
+from jebao import MDP20000Device
+
+async def main():
+    # Connect to device
+    async with MDP20000Device(host="10.20.20.13") as pump:
+        # Ensure in manual mode (exits Program mode if needed)
+        await pump.ensure_manual_mode()
+
+        # Turn on
+        await pump.turn_on()
+
+        # Set speed to 75%
+        await pump.set_speed(75)
+
+        # Check status
+        await pump.update()
+        print(f"State: {pump.state.name}")
+        print(f"Speed: {pump.speed}%")
+        print(f"Is on: {pump.is_on}")
+
+        # Turn off
+        await pump.turn_off()
+
+asyncio.run(main())
+```
+
+### Feed Mode
+
+```python
+async def feed_mode_example():
+    async with MDP20000Device(host="10.20.20.13") as pump:
+        await pump.ensure_manual_mode()
+        await pump.turn_on()
+        await pump.set_speed(75)
+
+        # Start 2-minute feed (pump stops temporarily)
+        await pump.start_feed(minutes=2)
+        print("Feed started, pump will auto-resume in 2 minutes")
+
+        # Check status during feed
+        await pump.update()
+        print(f"In feed mode: {pump.is_feed_mode}")
+
+        # Or cancel early
+        # await pump.cancel_feed(resume_speed=75)
+```
+
+### Long-Running Connection
+
+```python
+async def monitor_pump():
+    pump = MDP20000Device(host="10.20.20.13")
+
+    try:
+        await pump.connect()
+        await pump.ensure_manual_mode()
+
+        # Control pump
+        await pump.turn_on()
+        await pump.set_speed(50)
+
+        # Monitor status periodically
+        while True:
+            await pump.update()
+            print(f"Status: {pump.state.name} @ {pump.speed}%")
+            await asyncio.sleep(30)
+
+    finally:
+        await pump.disconnect()
+```
+
+## Device States
+
+```python
+from jebao import DeviceState
+
+# State values
+DeviceState.OFF      # 0x10 - Manual mode, stopped
+DeviceState.ON       # 0x11 - Manual mode, running
+DeviceState.FEED     # 0x15 - Feed mode (temporary pause)
+DeviceState.PROGRAM  # 0x19 - Program mode (scheduled)
+
+# Check state
+if pump.state == DeviceState.FEED:
+    print("Pump is in feed mode")
+
+# Helper properties
+pump.is_on           # True if ON or FEED
+pump.is_off          # True if OFF
+pump.is_feed_mode    # True if FEED
+pump.is_program_mode # True if PROGRAM
+pump.is_manual_mode  # True if ON or OFF
+```
+
+## API Reference
+
+### MDP20000Device
+
+#### Connection
+- `async connect(timeout=5.0)` - Connect and authenticate
+- `async disconnect()` - Disconnect from device
+- `is_connected` - Check connection status
+- `async update()` - Refresh device status
+
+#### Control
+- `async turn_on()` - Turn pump on
+- `async turn_off()` - Turn pump off
+- `async set_speed(percentage)` - Set speed (30-100%)
+
+#### Feed Mode
+- `async set_feed_duration(minutes)` - Configure feed timer (1-10 minutes)
+- `async start_feed(minutes=None)` - Start feed mode
+- `async cancel_feed(resume_speed=None)` - Cancel feed and resume
+
+#### Program Mode
+- `async ensure_manual_mode()` - Exit Program mode if active
+
+#### Properties
+- `state: DeviceState` - Current state
+- `speed: int` - Current speed (30-100)
+- `is_on: bool` - Pump is running
+- `is_off: bool` - Pump is stopped
+- `is_feed_mode: bool` - In feed mode
+- `is_program_mode: bool` - In program mode
+- `is_manual_mode: bool` - In manual mode
+
+### Discovery
+
+```python
+from jebao import JebaoDiscovery, discover_devices
+
+# Convenience function
+devices = await discover_devices(timeout=2.0, interfaces=['eth0'])
+
+# Or use class directly
+discovery = JebaoDiscovery()
+devices = await discovery.discover(timeout=2.0, interfaces=['eth0'])
+
+# Filter by model
+mdp20000_devices = [d for d in devices if d.is_mdp20000]
+md44_devices = [d for d in devices if d.is_md44]
+```
+
+### DiscoveredDevice
+
+```python
+device.device_id      # Device ID (e.g., "POAKSFXJNJ")
+device.ip_address     # IP address
+device.mac_address    # MAC address
+device.product_key    # Product key
+device.model          # Model name (e.g., "MDP-20000")
+device.is_mdp20000    # True if MDP-20000
+device.is_md44        # True if MD-4.4
+```
+
+## Home Assistant Integration
+
+This library is designed for use with Home Assistant. See the separate
+[homeassistant-jebao](https://github.com/jrigling/homeassistant-jebao) repository
+for the ready-to-use HA integration.
+
+## Reliability Features
+
+The library includes automatic retry logic for enhanced reliability:
+- Commands automatically retry up to 3 times on transient failures
+- Handles garbage byte accumulation from pump firmware
+- Exponential backoff for retry delays
+- Typical success rate >97% even with flaky network conditions
+
+## Multi-Subnet Considerations
+
+When Home Assistant runs on a system with multiple network interfaces:
+
+1. **Automatic Discovery**: The library will scan all interfaces by default
+2. **Interface Selection**: You can specify which interfaces to scan
+3. **Broadcast Support**: Each interface gets its own broadcast address
+4. **IoT VLANs**: Works great with isolated IoT networks
+
+Example: HA connected to both `192.168.1.0/24` (main) and `10.20.20.0/24` (IoT):
+
+```python
+# Discovers on both networks automatically
+devices = await discover_devices()
+
+# Or be explicit
+devices = await discover_devices(interfaces=['eth0', 'eth1'])
+```
+
+## Error Handling
+
+```python
+from jebao import (
+    JebaoError,
+    JebaoConnectionError,
+    JebaoAuthenticationError,
+    JebaoCommandError,
+    JebaoTimeoutError,
+    JebaoInvalidStateError,
+)
+
+try:
+    async with MDP20000Device(host="10.20.20.13") as pump:
+        await pump.turn_on()
+except JebaoConnectionError:
+    print("Failed to connect - check IP and network")
+except JebaoAuthenticationError:
+    print("Authentication failed")
+except JebaoCommandError:
+    print("Command execution failed")
+except JebaoTimeoutError:
+    print("Operation timed out")
+except JebaoError as e:
+    print(f"General error: {e}")
+```
+
+## Logging
+
+The library uses Python's standard logging:
+
+```python
+import logging
+
+# Enable debug logging
+logging.basicConfig(level=logging.DEBUG)
+
+# Or just for jebao
+logging.getLogger('jebao').setLevel(logging.DEBUG)
+```
+
+## Requirements
+
+- Python 3.9+
+- `netifaces` - For multi-interface network discovery
+
+## License
+
+MIT License - See LICENSE file
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+## Credits
+
+This library builds upon the excellent work from:
+- [jebao-dosing-pump-md-4.4](https://github.com/tancou/jebao-dosing-pump-md-4.4) by [@tancou](https://github.com/tancou) - Original Node.js implementation for MD 4.4 pumps that provided the foundation for understanding the GizWits protocol
+
+Protocol for MDP-20000 was reverse-engineered through packet capture analysis of the official Jebao mobile app.
+
+## Disclaimer
+
+This is an unofficial library not affiliated with Jebao. Use at your own risk.
+Device warranty may be affected by third-party control software.

python_jebao-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+jebao/__init__.py,sha256=0FRNVM0yhzfm1vJthqhe7TgFSfyRtHn_ao74LbkDXO4,761
+jebao/const.py,sha256=KasF1RntYAwC_2Gv4wmF4VE4OQgTzQ5UAYugdvk8oBg,1621
+jebao/device.py,sha256=1NF-EG6H5_DtavRdXdwdPFxHKBAU7zdrwBsPxMCfAL0,4023
+jebao/discovery.py,sha256=nyXhu_BPXKzjF5lBeK2W62R_RtVhNnpcuulVvH20X9k,13365
+jebao/exceptions.py,sha256=S8jO0kxaw9l_TMdITgZm2gx-olJdGB3746tLB8UahJ0,501
+jebao/mdp20000.py,sha256=eyEDTpNm3DJ1uEIaqi2MLou1I63X9-GQzJXo-9xggok,9559
+jebao/protocol.py,sha256=r2tZX_qnxJRY957qWXApicRDSXNW78HholkEsk4Opxc,25044
+jebao/retry.py,sha256=N9biedjTigFRVmVrEAE_iPmuTW2GZJrv8B_zMQ8hC_A,2646
+python_jebao-0.1.0.dist-info/licenses/LICENSE,sha256=xz5RpUswwNDP6Agh5an2XKA3BJfABxtPaeqPTDn1y2k,1071
+python_jebao-0.1.0.dist-info/METADATA,sha256=btSVlVg--7HRXJrK2_RCA3clTTXYtbrkv0qWRejCEwI,10143
+python_jebao-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+python_jebao-0.1.0.dist-info/top_level.txt,sha256=Bj9cYMUNXSj-Q_ViTIEIYJyfKOmnoywBAspe6ZprUkY,6
+python_jebao-0.1.0.dist-info/RECORD,,

python_jebao-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_jebao-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justin Rigling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_jebao-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+jebao