python-pooldose 0.6.0__tar.gz → 0.6.6__tar.gz

{python_pooldose-0.6.0 → python_pooldose-0.6.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-pooldose
-Version: 0.6.0
+Version: 0.6.6
 Summary: Unoffical async Python client for SEKO PoolDose devices
 Author-email: Lukas Maertin <pypi@lukas-maertin.de>
 License-Expression: MIT
@@ -28,6 +28,7 @@ This client uses an undocumented local HTTP API. It provides live readings for p
 - **Dynamic sensor discovery** based on device model and firmware
 - **Dictionary-style access** to instant values
 - **Structured data API** with type-based organization
+- **Device analyzer** for discovering unsupported device capabilities
 - **PEP-561 compliant** with full type hints for Home Assistant integrations
 - **Command-line interface** for direct device interaction and testing
 - **Secure by default** - WiFi passwords excluded unless explicitly requested
@@ -186,6 +187,12 @@ pooldose --host 192.168.1.100 --ssl
 
 # Custom port
 pooldose --host 192.168.1.100 --ssl --port 8443
+
+# Analyze device capabilities (discover unsupported devices)
+pooldose --host 192.168.1.100 --analyze
+
+# Show all widgets including hidden ones
+pooldose --host 192.168.1.100 --analyze-all
 ```
 
 ### Mock Mode with JSON Files
@@ -203,6 +210,9 @@ You can also run it as a Python module:
 # Real device
 python -m pooldose --host 192.168.1.100
 
+# Device analysis
+python -m pooldose --host 192.168.1.100 --analyze
+
 # Mock mode
 python -m pooldose --mock data.json
 
@@ -210,6 +220,93 @@ python -m pooldose --mock data.json
 python -m pooldose --help
 ```
 
+## Device Analysis for Unsupported Devices
+
+The device analyzer is a powerful feature that helps discover and analyze PoolDose devices that are not yet officially supported. This is particularly useful for:
+
+- **New Device Discovery**: Identifying capabilities of unknown device models
+- **Device Support Development**: Gathering data needed to add support for new devices
+- **Troubleshooting**: Understanding how your device exposes data and controls
+- **Widget Exploration**: Discovering all available sensors, controls, and settings
+
+### Basic Device Analysis
+
+```bash
+# Analyze a device to discover its capabilities
+pooldose --host 192.168.1.100 --analyze
+
+# Show all widgets including hidden ones
+pooldose --host 192.168.1.100 --analyze-all
+
+# Analyze with HTTPS
+pooldose --host 192.168.1.100 --ssl --analyze
+```
+
+### Analysis Output
+
+The analyzer provides comprehensive information about your device:
+
+```
+=== DEVICE ANALYSIS ===
+Device: 01234567890A_DEVICE
+Model: PDPR1H1HAW***  
+Firmware: FW53****
+
+=== WIDGETS (Visible UI Elements) ===
+
+SENSORS (Read-only values)
+temperature: 24.5°C
+ph: 7.2
+orp: 720 mV
+
+SETPOINTS (Configurable values)  
+target_ph: 7.0 (Range: 6.0-8.0, Step: 0.1)
+target_orp: 700 mV (Range: 400-900, Step: 10)
+
+SWITCHES (On/Off controls)
+stop_dosing: OFF
+pump_detection: ON
+
+SELECTS (Configuration options)
+water_meter_unit: L/h
+  Options: [L/h, m³/h, gal/h]
+
+ALARMS (Status indicators)
+alarm_ph: OK
+alarm_orp: OK
+```
+
+### Using Analysis for Device Support
+
+When you encounter an unsupported device, the analyzer helps gather the necessary information:
+
+1. **Run Analysis**: Use `--analyze` to discover all device capabilities
+2. **Document Output**: Save the analysis output to understand device structure  
+3. **Check Widget Types**: Note which sensors, controls, and settings are available
+4. **Identify Patterns**: Look for device model and firmware information
+5. **Report Findings**: Use the analysis data to request support for your device model
+
+### Example: Discovering New Device
+
+```bash
+# Unknown device analysis
+pooldose --host 192.168.1.100 --analyze
+
+# Output shows:
+# Device: 01987654321B_DEVICE  
+# Model: PDPR2H2XYZ***        ← New model not yet supported
+# Firmware: FW54****          ← New firmware version
+# 
+# Widgets discovered: 15 sensors, 8 controls, 12 settings
+```
+
+With this information, you can:
+- Report the new model/firmware combination  
+- Share the widget structure for mapping development
+- Help expand device support for the community
+
+The device analyzer makes python-pooldose extensible and helps build support for the growing ecosystem of SEKO PoolDose devices.
+
 ## Examples
 
 The `examples/` directory contains demonstration scripts that show how to use the python-pooldose library:
@@ -638,13 +735,13 @@ Mapping Discovery Process:
          │
          ▼
 ┌─────────────────┐
-│ Get MODEL_ID    │ ──────► PDPR1H1HAW100
-│ Get FW_CODE     │ ──────► 539187
+│ Get MODEL_ID    │ ──────► PDPR1H1HAW***
+│ Get FW_CODE     │ ──────► 53****
 └─────────────────┘
          │
          ▼
 ┌─────────────────┐
-│ Load JSON File  │ ──────► model_PDPR1H1HAW100_FW539187.json
+│ Load JSON File  │ ──────► model_PDPR1H1HAW***_FW53****.json
 └─────────────────┘
          │
          ▼
@@ -762,10 +859,10 @@ The `instant_values_structured()` method returns data organized by type:
 
 This client has been tested with:
 
-- **SEKO PoolDose Double/Dual WiFi** (Model: PDPR1H1HAW100, FW: 539187)
-- **VA dos BASIC Chlor - pH/ORP Wi-Fi** (Model: PDPR1H1HAR1V0, FW: 539224)
+- **SEKO PoolDose Double/Dual WiFi** (Model: PDPR1H1HAW***, FW: 53****)
+- **VA dos BASIC Chlor - pH/ORP Wi-Fi** (Model: PDPR1H1HAR***, FW: 53****)
 
-Other SEKO PoolDose models may work but are untested. The client uses JSON mapping files to adapt to different device models and firmware versions (see e.g. `src/pooldose/mappings/model_PDPR1H1HAW100_FW539187.json`).
+Other SEKO PoolDose models may work but are untested. The client uses JSON mapping files to adapt to different device models and firmware versions (see e.g. `src/pooldose/mappings/model_PDPR1H1HAW***_FW53****.json`).
 
 > **Note:** The JSON files in the mappings directory define the device-specific data keys and their human-readable names for different PoolDose models and firmware versions.
 
@@ -845,11 +942,6 @@ Data Classification:
 
 For detailed release notes and version history, please see [CHANGELOG.md](CHANGELOG.md).
 
-### Latest Release (0.6.0)
+### Latest Release (0.6.6)
 
-- **Command Line Interface**: Complete CLI with `--host`, `--mock`, `--ssl`, and `--port` options
-- **Pip Installation**: Install as console script via `pip install python-pooldose`
-- **PEP-561 Type Compliance**: Full typing support for Home Assistant integrations
-- **Documentation Modernization**: Centralized CLI documentation
-- **Code Quality**: Pylint 10.00/10 score with strict typing and enhanced error handling
-- **Simplified Structure**: Removed deprecated demo scripts, integrated mock functionality into CLI
+- **Mapping**: Fixed for PDPR1H1HAR1V0_FW539224**

{python_pooldose-0.6.0 → python_pooldose-0.6.6}/README.md

@@ -10,6 +10,7 @@ This client uses an undocumented local HTTP API. It provides live readings for p
 - **Dynamic sensor discovery** based on device model and firmware
 - **Dictionary-style access** to instant values
 - **Structured data API** with type-based organization
+- **Device analyzer** for discovering unsupported device capabilities
 - **PEP-561 compliant** with full type hints for Home Assistant integrations
 - **Command-line interface** for direct device interaction and testing
 - **Secure by default** - WiFi passwords excluded unless explicitly requested
@@ -168,6 +169,12 @@ pooldose --host 192.168.1.100 --ssl
 
 # Custom port
 pooldose --host 192.168.1.100 --ssl --port 8443
+
+# Analyze device capabilities (discover unsupported devices)
+pooldose --host 192.168.1.100 --analyze
+
+# Show all widgets including hidden ones
+pooldose --host 192.168.1.100 --analyze-all
 ```
 
 ### Mock Mode with JSON Files
@@ -185,6 +192,9 @@ You can also run it as a Python module:
 # Real device
 python -m pooldose --host 192.168.1.100
 
+# Device analysis
+python -m pooldose --host 192.168.1.100 --analyze
+
 # Mock mode
 python -m pooldose --mock data.json
 
@@ -192,6 +202,93 @@ python -m pooldose --mock data.json
 python -m pooldose --help
 ```
 
+## Device Analysis for Unsupported Devices
+
+The device analyzer is a powerful feature that helps discover and analyze PoolDose devices that are not yet officially supported. This is particularly useful for:
+
+- **New Device Discovery**: Identifying capabilities of unknown device models
+- **Device Support Development**: Gathering data needed to add support for new devices
+- **Troubleshooting**: Understanding how your device exposes data and controls
+- **Widget Exploration**: Discovering all available sensors, controls, and settings
+
+### Basic Device Analysis
+
+```bash
+# Analyze a device to discover its capabilities
+pooldose --host 192.168.1.100 --analyze
+
+# Show all widgets including hidden ones
+pooldose --host 192.168.1.100 --analyze-all
+
+# Analyze with HTTPS
+pooldose --host 192.168.1.100 --ssl --analyze
+```
+
+### Analysis Output
+
+The analyzer provides comprehensive information about your device:
+
+```
+=== DEVICE ANALYSIS ===
+Device: 01234567890A_DEVICE
+Model: PDPR1H1HAW***  
+Firmware: FW53****
+
+=== WIDGETS (Visible UI Elements) ===
+
+SENSORS (Read-only values)
+temperature: 24.5°C
+ph: 7.2
+orp: 720 mV
+
+SETPOINTS (Configurable values)  
+target_ph: 7.0 (Range: 6.0-8.0, Step: 0.1)
+target_orp: 700 mV (Range: 400-900, Step: 10)
+
+SWITCHES (On/Off controls)
+stop_dosing: OFF
+pump_detection: ON
+
+SELECTS (Configuration options)
+water_meter_unit: L/h
+  Options: [L/h, m³/h, gal/h]
+
+ALARMS (Status indicators)
+alarm_ph: OK
+alarm_orp: OK
+```
+
+### Using Analysis for Device Support
+
+When you encounter an unsupported device, the analyzer helps gather the necessary information:
+
+1. **Run Analysis**: Use `--analyze` to discover all device capabilities
+2. **Document Output**: Save the analysis output to understand device structure  
+3. **Check Widget Types**: Note which sensors, controls, and settings are available
+4. **Identify Patterns**: Look for device model and firmware information
+5. **Report Findings**: Use the analysis data to request support for your device model
+
+### Example: Discovering New Device
+
+```bash
+# Unknown device analysis
+pooldose --host 192.168.1.100 --analyze
+
+# Output shows:
+# Device: 01987654321B_DEVICE  
+# Model: PDPR2H2XYZ***        ← New model not yet supported
+# Firmware: FW54****          ← New firmware version
+# 
+# Widgets discovered: 15 sensors, 8 controls, 12 settings
+```
+
+With this information, you can:
+- Report the new model/firmware combination  
+- Share the widget structure for mapping development
+- Help expand device support for the community
+
+The device analyzer makes python-pooldose extensible and helps build support for the growing ecosystem of SEKO PoolDose devices.
+
 ## Examples
 
 The `examples/` directory contains demonstration scripts that show how to use the python-pooldose library:
@@ -620,13 +717,13 @@ Mapping Discovery Process:
          │
          ▼
 ┌─────────────────┐
-│ Get MODEL_ID    │ ──────► PDPR1H1HAW100
-│ Get FW_CODE     │ ──────► 539187
+│ Get MODEL_ID    │ ──────► PDPR1H1HAW***
+│ Get FW_CODE     │ ──────► 53****
 └─────────────────┘
          │
          ▼
 ┌─────────────────┐
-│ Load JSON File  │ ──────► model_PDPR1H1HAW100_FW539187.json
+│ Load JSON File  │ ──────► model_PDPR1H1HAW***_FW53****.json
 └─────────────────┘
          │
          ▼
@@ -744,10 +841,10 @@ The `instant_values_structured()` method returns data organized by type:
 
 This client has been tested with:
 
-- **SEKO PoolDose Double/Dual WiFi** (Model: PDPR1H1HAW100, FW: 539187)
-- **VA dos BASIC Chlor - pH/ORP Wi-Fi** (Model: PDPR1H1HAR1V0, FW: 539224)
+- **SEKO PoolDose Double/Dual WiFi** (Model: PDPR1H1HAW***, FW: 53****)
+- **VA dos BASIC Chlor - pH/ORP Wi-Fi** (Model: PDPR1H1HAR***, FW: 53****)
 
-Other SEKO PoolDose models may work but are untested. The client uses JSON mapping files to adapt to different device models and firmware versions (see e.g. `src/pooldose/mappings/model_PDPR1H1HAW100_FW539187.json`).
+Other SEKO PoolDose models may work but are untested. The client uses JSON mapping files to adapt to different device models and firmware versions (see e.g. `src/pooldose/mappings/model_PDPR1H1HAW***_FW53****.json`).
 
 > **Note:** The JSON files in the mappings directory define the device-specific data keys and their human-readable names for different PoolDose models and firmware versions.
 
@@ -827,11 +924,6 @@ Data Classification:
 
 For detailed release notes and version history, please see [CHANGELOG.md](CHANGELOG.md).
 
-### Latest Release (0.6.0)
+### Latest Release (0.6.6)
 
-- **Command Line Interface**: Complete CLI with `--host`, `--mock`, `--ssl`, and `--port` options
-- **Pip Installation**: Install as console script via `pip install python-pooldose`
-- **PEP-561 Type Compliance**: Full typing support for Home Assistant integrations
-- **Documentation Modernization**: Centralized CLI documentation
-- **Code Quality**: Pylint 10.00/10 score with strict typing and enhanced error handling
-- **Simplified Structure**: Removed deprecated demo scripts, integrated mock functionality into CLI
+- **Mapping**: Fixed for PDPR1H1HAR1V0_FW539224**

{python_pooldose-0.6.0 → python_pooldose-0.6.6}/src/pooldose/__init__.py

@@ -1,5 +1,5 @@
 """Async API client for SEKO Pooldose."""
 from .client import PooldoseClient
 
-__version__ = "0.6.0"
+__version__ = "0.6.6"
 __all__ = ["PooldoseClient"]

{python_pooldose-0.6.0 → python_pooldose-0.6.6}/src/pooldose/__main__.py

@@ -8,7 +8,9 @@ from pathlib import Path
 
 from pooldose import __version__
 from pooldose.client import PooldoseClient, RequestStatus
+from pooldose.device_analyzer import DeviceAnalyzer
 from pooldose.mock_client import MockPooldoseClient
+from pooldose.request_handler import RequestHandler
 
 # Import demo utilities if available
 try:
@@ -43,6 +45,66 @@ except ImportError:
                     print(f"  {key}: {value}")
 
 
+async def run_device_analyzer(host: str, use_ssl: bool, port: int, show_all: bool = False) -> None:
+    """Run the DeviceAnalyzer for unknown devices."""
+    print(f"Analyzing unknown device at {host}")
+    if use_ssl:
+        print(f"Using HTTPS on port {port}")
+    else:
+        print(f"Using HTTP on port {port}")
+
+    if show_all:
+        print("Showing ALL widgets (including hidden ones)")
+    else:
+        print("Showing only VISIBLE widgets (use --analyze-all for all)")
+
+    # Create request handler
+    handler = RequestHandler(
+        host=host,
+        timeout=30,
+        use_ssl=use_ssl,
+        port=port if port != 0 else None,
+        ssl_verify=False
+    )
+
+    try:
+        # Test connection
+        print("Testing connection...")
+        if not handler.check_host_reachable():
+            print("Host not reachable!")
+            return
+        print("Host is reachable")
+
+        # Connect and initialize
+        print("\nConnecting and initializing...")
+        status = await handler.connect()
+        if status != RequestStatus.SUCCESS:
+            print(f"Connection failed: {status}")
+            return
+        print("Connected successfully")
+        print(f"   Software Version: {handler.software_version}")
+        print(f"   API Version: {handler.api_version}")
+
+        # Create and run analyzer
+        analyzer = DeviceAnalyzer(handler)
+        device_info, widgets, analysis_status = await analyzer.analyze_device()
+
+        if analysis_status != RequestStatus.SUCCESS:
+            print(f"Analysis failed: {analysis_status}")
+            return
+
+        # Display results
+        if device_info is not None:
+            analyzer.display_analysis(device_info, widgets, show_all=show_all)
+        else:
+            print("Failed to analyze device - no device info available")
+
+    except (ConnectionError, TimeoutError, OSError) as e:
+        print(f"Network error: {e}")
+    except Exception as e:  # pylint: disable=broad-except
+        print(f"Error during analysis: {e}")
+
+
 async def run_real_client(host: str, use_ssl: bool, port: int) -> None:
     """Run the real PooldoseClient."""
     print(f"Connecting to PoolDose device at {host}")
@@ -138,6 +200,12 @@ Examples:
   # Connect with HTTPS
   python -m pooldose --host 192.168.1.100 --ssl --port 443
 
+  # Analyze unknown device (visible widgets only)
+  python -m pooldose --host 192.168.1.100 --analyze
+
+  # Analyze unknown device (all widgets including hidden)
+  python -m pooldose --host 192.168.1.100 --analyze-all
+
   # Use mock client with JSON file
   python -m pooldose --mock path/to/your/data.json
         """,
@@ -170,6 +238,16 @@ Examples:
         default=0,
         help="Custom port (default: 80 for HTTP, 443 for HTTPS)"
     )
+    parser.add_argument(
+        "--analyze",
+        action="store_true",
+        help="Analyze unknown device (requires --host)"
+    )
+    parser.add_argument(
+        "--analyze-all",
+        action="store_true",
+        help="Analyze unknown device including hidden widgets (implies --analyze)"
+    )
     parser.add_argument(
         "--version",
         action="version",
@@ -178,8 +256,16 @@ Examples:
 
     args = parser.parse_args()
 
+    # Handle analyze-all implies analyze
+    if args.analyze_all:
+        args.analyze = True
+
+    # Validation: --analyze requires --host
+    if args.analyze and not args.host:
+        parser.error("--analyze requires --host to be specified")
+
     # Set UTF-8 encoding for output
-    if sys.stdout.encoding != 'utf-8':
+    if hasattr(sys.stdout, 'reconfigure') and sys.stdout.encoding != 'utf-8':
         sys.stdout.reconfigure(encoding='utf-8')
 
     print("Python PoolDose Client")
@@ -189,7 +275,13 @@ Examples:
         if args.host:
             # Real device mode
             port = args.port if args.port != 0 else (443 if args.ssl else 80)
-            asyncio.run(run_real_client(args.host, args.ssl, port))
+            if args.analyze:
+                # Device analysis mode
+                asyncio.run(run_device_analyzer(
+                    args.host, args.ssl, port, show_all=args.analyze_all))
+            else:
+                # Normal client mode
+                asyncio.run(run_real_client(args.host, args.ssl, port))
         elif args.mock:
             # Mock mode
             asyncio.run(run_mock_client(args.mock))

{python_pooldose-0.6.0 → python_pooldose-0.6.6}/src/pooldose/client.py

@@ -44,7 +44,7 @@ class PooldoseClient:
         self._port = port
         self._ssl_verify = ssl_verify
         self._last_data = None
-        self._request_handler = None
+        self._request_handler: Optional[RequestHandler] = None
 
         # Initialize device info with default or placeholder values
         self.device_info = get_default_device_info()
@@ -57,7 +57,7 @@ class PooldoseClient:
     async def connect(self) -> RequestStatus:
         """
         Asynchronously connect to the device and initialize all components.
-        
+
         Returns:
             RequestStatus: SUCCESS if connected successfully, otherwise appropriate error status.
         """
@@ -84,7 +84,14 @@ class PooldoseClient:
         _LOGGER.debug("Initialized Pooldose client with device info: %s", self.device_info)
         return RequestStatus.SUCCESS
 
-    def check_apiversion_supported(self) -> tuple[RequestStatus, dict]:
+    @property
+    def request_handler(self) -> RequestHandler:
+        """Get the request handler, ensuring it's initialized."""
+        if self._request_handler is None:
+            raise RuntimeError("Client not connected. Call connect() first.")
+        return self._request_handler
+
+    def check_apiversion_supported(self) -> Tuple[RequestStatus, Dict[str, Any]]:
         """
         Check if the loaded API version matches the supported version.
 
@@ -92,11 +99,15 @@ class PooldoseClient:
             tuple: (RequestStatus, dict)
                 - dict contains:
                     "api_version_is": the current API version (or None if not set)
-                    "api_version_should": the supported API version
-                - RequestStatus.SUCCESS if supported,
-                - RequestStatus.API_VERSION_UNSUPPORTED if not supported,
+                    "api_version_should": the expected API version
                 - RequestStatus.NO_DATA if not set.
         """
+        if self._request_handler is None:
+            return RequestStatus.NO_DATA, {
+                "api_version_is": None,
+                "api_version_should": API_VERSION_SUPPORTED,
+            }
+
         result = {
             "api_version_is": self._request_handler.api_version,
             "api_version_should": API_VERSION_SUPPORTED,
@@ -110,7 +121,7 @@ class PooldoseClient:
 
         return RequestStatus.SUCCESS, result
 
-    async def _load_device_info(self) -> RequestStatus:
+    async def _load_device_info(self) -> RequestStatus:  # pylint: disable=too-many-branches
         """
         Load device information from the request handler.
         This method should be called after a successful connection.
@@ -139,10 +150,13 @@ class PooldoseClient:
         await asyncio.sleep(0.5)
 
         # Load mapping information
-        self._mapping_info = await MappingInfo.load(
-            self.device_info.get("MODEL_ID"),
-            self.device_info.get("FW_CODE")
-        )
+        model_id = self.device_info.get("MODEL_ID")
+        fw_code = self.device_info.get("FW_CODE")
+        if model_id and fw_code:
+            self._mapping_info = await MappingInfo.load(str(model_id), str(fw_code))
+        else:
+            _LOGGER.warning("Missing MODEL_ID or FW_CODE, cannot load mapping")
+            self._mapping_info = MappingInfo(mapping=None, status=RequestStatus.NO_DATA)
 
         # WiFi station info
         status, wifi_station = await self._request_handler.get_wifi_station()
@@ -207,6 +221,9 @@ class PooldoseClient:
             tuple: (RequestStatus, InstantValues|None) - Status and instant values object.
         """
         try:
+            if self._request_handler is None:
+                return RequestStatus.NO_DATA, None
+
             status, raw_data = await self._request_handler.get_values_raw()
             if status != RequestStatus.SUCCESS or raw_data is None:
                 return status, None
@@ -214,10 +231,10 @@ class PooldoseClient:
             mapping = self._mapping_info.mapping if self._mapping_info else None
             if mapping is None:
                 return RequestStatus.UNKNOWN_ERROR, None
-            device_id = self.device_info["DEVICE_ID"]
+            device_id = str(self.device_info.get("DEVICE_ID", ""))
             device_raw_data = raw_data.get("devicedata", {}).get(device_id, {})
-            model_id = self.device_info["MODEL_ID"]
-            fw_code = self.device_info["FW_CODE"]
+            model_id = str(self.device_info.get("MODEL_ID", ""))
+            fw_code = str(self.device_info.get("FW_CODE", ""))
             prefix = f"{model_id}_FW{fw_code}_"
             return RequestStatus.SUCCESS, InstantValues(device_raw_data, mapping, prefix, device_id, self._request_handler)
         except (KeyError, TypeError, ValueError) as err:
@@ -227,13 +244,13 @@ class PooldoseClient:
     async def instant_values_structured(self) -> Tuple[RequestStatus, Dict[str, Any]]:
         """
         Get instant values in structured JSON format with types as top-level keys.
-        
+
         Returns:
             Tuple[RequestStatus, Dict[str, Any]]: Status and structured data dict.
         """
         # Get instant values object
         status, instant_values = await self.instant_values()
-        if status != RequestStatus.SUCCESS:
+        if status != RequestStatus.SUCCESS or instant_values is None:
             return status, {}
 
         try: