lmaertin · lmaertin · Mar 26, 2026 · Mar 26, 2026 · Mar 26, 2026 · Mar 26, 2026
diff --git a/README.md b/README.md
diff --git a/docs/api-reference.md b/docs/api-reference.md
@@ -0,0 +1,104 @@
+# API Reference
+
+## PooldoseClient Class
+
+### Constructor
+
+```python
+PooldoseClient(host, timeout=30, *, websession=None, include_sensitive_data=False, include_mac_lookup=False, use_ssl=False, port=None, ssl_verify=True, debug_payload=False, retry_delay=0.1)
+```
+
+**Parameters:**
+
+- `host` (str): The hostname or IP address of the device
+- `timeout` (int): Request timeout in seconds (default: 30)
+- `websession` (Optional[aiohttp.ClientSession]): Optional external ClientSession for HTTP requests. If provided, will be used for all API calls (mainly for Home Assistant integration) (default: None)
+- `include_sensitive_data` (bool): Whether to include sensitive data like WiFi passwords (default: False)
+- `include_mac_lookup` (bool): Whether to include MAC lookup via ARP (default: False)
+- `use_ssl` (bool): Whether to use HTTPS instead of HTTP (default: False)
+- `port` (Optional[int]): Custom port for connections. Defaults to 80 for HTTP, 443 for HTTPS (default: None)
+- `ssl_verify` (bool): Whether to verify SSL certificates when using HTTPS (default: True)
+- `debug_payload` (bool): If True, log and store payloads sent to device for debugging (default: False)
+- `retry_delay` (float): Delay in seconds between consecutive API requests during connect. Prevents overwhelming the embedded device (default: 0.1)
+
+### Methods
+
+- `async connect()` → `RequestStatus` - Connect to device and initialize all components
+- `static_values()` → `tuple[RequestStatus, StaticValues | None]` - Get static device information
+- `async instant_values()` → `tuple[RequestStatus, InstantValues | None]` - Get current sensor readings and device state
+- `async instant_values_structured()` → `tuple[RequestStatus, dict[str, Any]]` - Get structured data organized by type
+- `check_apiversion_supported()` → `tuple[RequestStatus, dict]` - Check API version compatibility
+- `async set_switch(key, value)` → `bool` - Set a mapped switch value (convenience wrapper)
+- `async set_number(key, value)` → `bool` - Set a mapped numeric value (convenience wrapper)
+- `async set_select(key, value)` → `bool` - Set a mapped select option (convenience wrapper)
+
+### Properties
+
+- `is_connected: bool` - Check if client is connected to device
+- `device_info: dict` - Dictionary containing device information
+
+## RequestStatus
+
+All client methods return `RequestStatus` enum values:
+
+```python
+from pooldose.request_status import RequestStatus
+
+RequestStatus.SUCCESS                    # Operation successful
+RequestStatus.HOST_UNREACHABLE           # Device not reachable
+RequestStatus.PARAMS_FETCH_FAILED        # Failed to fetch device parameters
+RequestStatus.API_VERSION_UNSUPPORTED    # API version not supported
+RequestStatus.NO_DATA                    # No data received
+RequestStatus.LAST_DATA                  # Last valid data used
+RequestStatus.CLIENT_ERROR_SET           # Error setting client value
+RequestStatus.UNKNOWN_ERROR              # Other error occurred
+```
+
+## InstantValues Interface
+
+The `InstantValues` class provides dictionary-style access to sensor data:
+
+```python
+# Dictionary Interface
+value = instant_values["sensor_name"]                    # Direct access
+value = instant_values.get("sensor_name", default)      # Get with default
+exists = "sensor_name" in instant_values                 # Check existence
+
+# Setting values (async, with validation)
+await instant_values.set_number("ph_target", 7.2)       # Set number value
+await instant_values.set_switch("stop_dosing", True)    # Set switch value
+await instant_values.set_select("unit", "L/h")          # Set select value
+```
+
+## Structured Data Format
+
+The `instant_values_structured()` method returns data organized by type:
+
+```python
+{
+    "sensor": {
+        "temperature": {"value": 25.5, "unit": "°C"},
+        "ph": {"value": 7.2, "unit": None}
+    },
+    "number": {
+        "target_ph": {"value": 7.0, "unit": None, "min": 6.0, "max": 8.0, "step": 0.1}
+    },
+    "switch": {
+        "stop_dosing": {"value": False}
+    },
+    "binary_sensor": {
+        "alarm_ph": {"value": False}
+    },
+    "select": {
+        "water_meter_unit": {"value": "L/h"}
+    }
+}
+```
+
+### Data Types
+
+- **sensor**: Read-only sensor values with optional units
+- **number**: Configurable numeric values with min/max/step constraints
+- **switch**: Boolean on/off controls  
+- **binary_sensor**: Read-only boolean status indicators
+- **select**: Configurable selection options
diff --git a/docs/cli.md b/docs/cli.md
@@ -0,0 +1,143 @@
+# Command Line Usage
+
+After installation, you can use python-pooldose directly from the command line.
+
+> **Note:** `--host` and `--mock` are mutually exclusive — you must specify exactly one.
+> `--analyze` and `--analyze-all` require `--host` (they cannot be used in mock mode).
+
+## Connect to Real Device
+
+```bash
+# Basic connection
+pooldose --host 192.168.1.100
+
+# With HTTPS
+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
+
+# Show version
+pooldose --version
+```
+
+## Mock Mode with JSON Files
+
+```bash
+# Use JSON file for testing
+pooldose --mock path/to/your/data.json
+```
+
+## Alternative Module Execution
+
+You can also run it as a Python module:
+
+```bash
+# 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
+
+# Show help
+python -m pooldose --help
+
+# Show version
+python -m pooldose --version
+```
+
+## 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 ID: PDZZ1H1HATEST1V1  
+Firmware Code: 654321
+
+=== 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 ID: PDZZ1H1HATEST1V1     ← New model not yet supported
+# Firmware Code: 654321            ← 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 or VÁGNER POOL devices.
diff --git a/docs/device-support.md b/docs/device-support.md
@@ -0,0 +1,51 @@
+# Device Support
+
+## Supported Devices
+
+This client has been tested with:
+
+| Device | PRODUCT_CODE | FW Code | Notes |
+|---|---|---|---|
+| SEKO PoolDose Double | PDPR1H1HAW100 | 539187 | |
+| SEKO PoolDose Double Spa | PDPR1H04AW100 | 539292 | |
+| SEKO POOLDOSE pH+ORP CF Group Wi-Fi | PDPR1H1HAW102 | 539187 | Alias for PDPR1H1HAW100 mapping |
+| SEKO PoolDose pH | PDPH1H1HAW100 | 539176 | pH-only device |
+| VÁGNER POOL VA DOS BASIC | PDHC1H1HAR1V0 | 539224 | |
+| VÁGNER POOL VA DOS EXACT | PDHC1H1HAR1V1 | 539224 | Alias for PDPR1H1HAR1V0 mapping |
+
+Other SEKO or VÁGNER POOL 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`).
+
+> **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.
+
+## How to Request Support for a New Device
+
+If your device is not yet supported, please help us by creating a GitHub issue and providing the following information:
+
+1. **Run low-level analysis and share the output files:**
+    - Use the following curl commands. 
+    - Replace the IP address and DeviceId (get the id from the header of the instantvalues.json file, e.g., '012345679_DEVICE') as needed:
+
+    - Download debug config info:
+      ```bash
+      curl http://<YOUR_DEVICE_IP>/api/v1/debug/config/info -o debuginfo.json
+      ```
+      **Important:** Before uploading, open `debuginfo.json` and remove any WiFi credentials.
+    - Download instant values
+      ```bash
+      curl --location --request POST http://<YOUR_DEVICE_IP>/api/v1/DWI/getInstantValues -o instantvalues.json
+      ```
+    - Download device language strings
+      ```bash
+      curl --location http://<YOUR_DEVICE_IP>/api/v1/DWI/getDeviceLanguage --data-raw '{"DeviceId":"YOUR_DEVICE_ID","LANG":"en"}' -o strings.json
+      ```
+2. **Optional: Run the analyzer and share the output:**
+    - Run this command if you set up python-pooldose already:
+      ```bash
+      pooldose --host <YOUR_DEVICE_IP> --analyze
+      ```
+    - Copy and paste the full output into your issue (remove any sensitive data).
+
+3. **Create a GitHub issue:**
+    - Attach the the 3 JSON files from above.
+    - Optionally attach the analyzer output if available.
+    - This will help us add support for your device faster!