python-pooldose 0.5.1__tar.gz → 0.6.5__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/PKG-INFO +197 -38
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/README.md +196 -37
- python_pooldose-0.6.5/pyproject.toml +88 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/__init__.py +1 -0
- python_pooldose-0.6.5/src/pooldose/__main__.py +297 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/client.py +36 -19
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/constants.py +1 -1
- python_pooldose-0.6.5/src/pooldose/device_analyzer.py +411 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/mappings/mapping_info.py +6 -4
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/mock_client.py +4 -4
- python_pooldose-0.6.5/src/pooldose/py.typed +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/request_handler.py +103 -21
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/request_status.py +1 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/values/instant_values.py +2 -1
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/python_pooldose.egg-info/PKG-INFO +197 -38
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/python_pooldose.egg-info/SOURCES.txt +6 -0
- python_pooldose-0.6.5/src/python_pooldose.egg-info/entry_points.txt +2 -0
- python_pooldose-0.6.5/tests/test_device_analyzer.py +583 -0
- python_pooldose-0.6.5/tests/test_device_analyzer_integration.py +389 -0
- python_pooldose-0.5.1/pyproject.toml +0 -38
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/LICENSE +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/setup.cfg +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/mappings/__init__.py +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/mappings/model_PDPR1H1HAR1V0_FW539224.json +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/mappings/model_PDPR1H1HAW100_FW539187.json +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/values/__init__.py +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/pooldose/values/static_values.py +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/python_pooldose.egg-info/dependency_links.txt +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/python_pooldose.egg-info/requires.txt +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/src/python_pooldose.egg-info/top_level.txt +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/tests/test_client.py +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/tests/test_instant_values.py +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/tests/test_mapping_info.py +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/tests/test_request_handler.py +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/tests/test_ssl_support.py +0 -0
- {python_pooldose-0.5.1 → python_pooldose-0.6.5}/tests/test_static_values.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: python-pooldose
|
|
3
|
-
Version: 0.5
|
|
3
|
+
Version: 0.6.5
|
|
4
4
|
Summary: Unoffical async Python client for SEKO PoolDose devices
|
|
5
5
|
Author-email: Lukas Maertin <pypi@lukas-maertin.de>
|
|
6
6
|
License-Expression: MIT
|
|
@@ -28,6 +28,9 @@ This client uses an undocumented local HTTP API. It provides live readings for p
|
|
|
28
28
|
- **Dynamic sensor discovery** based on device model and firmware
|
|
29
29
|
- **Dictionary-style access** to instant values
|
|
30
30
|
- **Structured data API** with type-based organization
|
|
31
|
+
- **Device analyzer** for discovering unsupported device capabilities
|
|
32
|
+
- **PEP-561 compliant** with full type hints for Home Assistant integrations
|
|
33
|
+
- **Command-line interface** for direct device interaction and testing
|
|
31
34
|
- **Secure by default** - WiFi passwords excluded unless explicitly requested
|
|
32
35
|
- **Comprehensive error handling** with detailed logging
|
|
33
36
|
- **SSL/HTTPS support** for secure communication
|
|
@@ -169,6 +172,141 @@ client = PooldoseClient("192.168.1.100", use_ssl=True, port=8443, ssl_verify=Fal
|
|
|
169
172
|
pip install python-pooldose
|
|
170
173
|
```
|
|
171
174
|
|
|
175
|
+
## Command Line Usage
|
|
176
|
+
|
|
177
|
+
After installation, you can use python-pooldose directly from the command line:
|
|
178
|
+
|
|
179
|
+
### Connect to Real Device
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
# Basic connection
|
|
183
|
+
pooldose --host 192.168.1.100
|
|
184
|
+
|
|
185
|
+
# With HTTPS
|
|
186
|
+
pooldose --host 192.168.1.100 --ssl
|
|
187
|
+
|
|
188
|
+
# Custom port
|
|
189
|
+
pooldose --host 192.168.1.100 --ssl --port 8443
|
|
190
|
+
|
|
191
|
+
# Analyze device capabilities (discover unsupported devices)
|
|
192
|
+
pooldose --host 192.168.1.100 --analyze
|
|
193
|
+
|
|
194
|
+
# Show all widgets including hidden ones
|
|
195
|
+
pooldose --host 192.168.1.100 --analyze-all
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### Mock Mode with JSON Files
|
|
199
|
+
|
|
200
|
+
```bash
|
|
201
|
+
# Use JSON file for testing
|
|
202
|
+
pooldose --mock path/to/your/data.json
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### Alternative Module Execution
|
|
206
|
+
|
|
207
|
+
You can also run it as a Python module:
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
# Real device
|
|
211
|
+
python -m pooldose --host 192.168.1.100
|
|
212
|
+
|
|
213
|
+
# Device analysis
|
|
214
|
+
python -m pooldose --host 192.168.1.100 --analyze
|
|
215
|
+
|
|
216
|
+
# Mock mode
|
|
217
|
+
python -m pooldose --mock data.json
|
|
218
|
+
|
|
219
|
+
# Show help
|
|
220
|
+
python -m pooldose --help
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
## Device Analysis for Unsupported Devices
|
|
224
|
+
|
|
225
|
+
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:
|
|
226
|
+
|
|
227
|
+
- **New Device Discovery**: Identifying capabilities of unknown device models
|
|
228
|
+
- **Device Support Development**: Gathering data needed to add support for new devices
|
|
229
|
+
- **Troubleshooting**: Understanding how your device exposes data and controls
|
|
230
|
+
- **Widget Exploration**: Discovering all available sensors, controls, and settings
|
|
231
|
+
|
|
232
|
+
### Basic Device Analysis
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
# Analyze a device to discover its capabilities
|
|
236
|
+
pooldose --host 192.168.1.100 --analyze
|
|
237
|
+
|
|
238
|
+
# Show all widgets including hidden ones
|
|
239
|
+
pooldose --host 192.168.1.100 --analyze-all
|
|
240
|
+
|
|
241
|
+
# Analyze with HTTPS
|
|
242
|
+
pooldose --host 192.168.1.100 --ssl --analyze
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
### Analysis Output
|
|
246
|
+
|
|
247
|
+
The analyzer provides comprehensive information about your device:
|
|
248
|
+
|
|
249
|
+
```
|
|
250
|
+
=== DEVICE ANALYSIS ===
|
|
251
|
+
Device: 01234567890A_DEVICE
|
|
252
|
+
Model: PDPR1H1HAW***
|
|
253
|
+
Firmware: FW53****
|
|
254
|
+
|
|
255
|
+
=== WIDGETS (Visible UI Elements) ===
|
|
256
|
+
|
|
257
|
+
SENSORS (Read-only values)
|
|
258
|
+
temperature: 24.5°C
|
|
259
|
+
ph: 7.2
|
|
260
|
+
orp: 720 mV
|
|
261
|
+
|
|
262
|
+
SETPOINTS (Configurable values)
|
|
263
|
+
target_ph: 7.0 (Range: 6.0-8.0, Step: 0.1)
|
|
264
|
+
target_orp: 700 mV (Range: 400-900, Step: 10)
|
|
265
|
+
|
|
266
|
+
SWITCHES (On/Off controls)
|
|
267
|
+
stop_dosing: OFF
|
|
268
|
+
pump_detection: ON
|
|
269
|
+
|
|
270
|
+
SELECTS (Configuration options)
|
|
271
|
+
water_meter_unit: L/h
|
|
272
|
+
Options: [L/h, m³/h, gal/h]
|
|
273
|
+
|
|
274
|
+
ALARMS (Status indicators)
|
|
275
|
+
alarm_ph: OK
|
|
276
|
+
alarm_orp: OK
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
### Using Analysis for Device Support
|
|
280
|
+
|
|
281
|
+
When you encounter an unsupported device, the analyzer helps gather the necessary information:
|
|
282
|
+
|
|
283
|
+
1. **Run Analysis**: Use `--analyze` to discover all device capabilities
|
|
284
|
+
2. **Document Output**: Save the analysis output to understand device structure
|
|
285
|
+
3. **Check Widget Types**: Note which sensors, controls, and settings are available
|
|
286
|
+
4. **Identify Patterns**: Look for device model and firmware information
|
|
287
|
+
5. **Report Findings**: Use the analysis data to request support for your device model
|
|
288
|
+
|
|
289
|
+
### Example: Discovering New Device
|
|
290
|
+
|
|
291
|
+
```bash
|
|
292
|
+
# Unknown device analysis
|
|
293
|
+
pooldose --host 192.168.1.100 --analyze
|
|
294
|
+
|
|
295
|
+
# Output shows:
|
|
296
|
+
# Device: 01987654321B_DEVICE
|
|
297
|
+
# Model: PDPR2H2XYZ*** ← New model not yet supported
|
|
298
|
+
# Firmware: FW54**** ← New firmware version
|
|
299
|
+
#
|
|
300
|
+
# Widgets discovered: 15 sensors, 8 controls, 12 settings
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
With this information, you can:
|
|
304
|
+
- Report the new model/firmware combination
|
|
305
|
+
- Share the widget structure for mapping development
|
|
306
|
+
- Help expand device support for the community
|
|
307
|
+
|
|
308
|
+
The device analyzer makes python-pooldose extensible and helps build support for the growing ecosystem of SEKO PoolDose devices.
|
|
309
|
+
|
|
172
310
|
## Examples
|
|
173
311
|
|
|
174
312
|
The `examples/` directory contains demonstration scripts that show how to use the python-pooldose library:
|
|
@@ -189,25 +327,6 @@ python examples/demo.py
|
|
|
189
327
|
- Displays all sensor readings, alarms, setpoints, and settings
|
|
190
328
|
- Demonstrates error handling
|
|
191
329
|
|
|
192
|
-
### 2. Mock Client Demo (`examples/demo_mock.py`)
|
|
193
|
-
|
|
194
|
-
Shows how to use the mock client with JSON files for development and testing:
|
|
195
|
-
|
|
196
|
-
```bash
|
|
197
|
-
# Run with sample data
|
|
198
|
-
python examples/demo_mock.py references/testdaten/suplere/instantvalues.json
|
|
199
|
-
|
|
200
|
-
# Use custom JSON file
|
|
201
|
-
python examples/demo_mock.py path/to/your/data.json
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
**Features:**
|
|
205
|
-
|
|
206
|
-
- No hardware required
|
|
207
|
-
- Uses real device data from JSON files
|
|
208
|
-
- Same API as real client
|
|
209
|
-
- Perfect for development and CI/CD
|
|
210
|
-
|
|
211
330
|
### Benefits of the Examples
|
|
212
331
|
|
|
213
332
|
- **Learning**: Step-by-step progression from simple to advanced usage
|
|
@@ -266,14 +385,14 @@ asyncio.run(simple_test())
|
|
|
266
385
|
|
|
267
386
|
### Mock Client Command Line Usage
|
|
268
387
|
|
|
269
|
-
You can
|
|
388
|
+
You can use the mock client with custom JSON files via the command line:
|
|
270
389
|
|
|
271
390
|
```bash
|
|
272
|
-
#
|
|
273
|
-
|
|
391
|
+
# Use mock client with JSON file
|
|
392
|
+
pooldose --mock path/to/your/data.json
|
|
274
393
|
|
|
275
|
-
#
|
|
276
|
-
python
|
|
394
|
+
# Or as Python module
|
|
395
|
+
python -m pooldose --mock path/to/your/data.json
|
|
277
396
|
```
|
|
278
397
|
|
|
279
398
|
### JSON Data Format
|
|
@@ -344,8 +463,7 @@ success = client.reload_data()
|
|
|
344
463
|
|
|
345
464
|
The following sample JSON files are available in the repository:
|
|
346
465
|
|
|
347
|
-
- `references/testdaten/
|
|
348
|
-
- `references/testdaten/instantvalues_poolforum_1.json` - Additional sample data
|
|
466
|
+
- `references/testdaten/tscherno/instantvalues.json` - Sample device data for testing
|
|
349
467
|
|
|
350
468
|
### Mock Client Use Cases
|
|
351
469
|
|
|
@@ -617,13 +735,13 @@ Mapping Discovery Process:
|
|
|
617
735
|
│
|
|
618
736
|
▼
|
|
619
737
|
┌─────────────────┐
|
|
620
|
-
│ Get MODEL_ID │ ──────►
|
|
621
|
-
│ Get FW_CODE │ ──────►
|
|
738
|
+
│ Get MODEL_ID │ ──────► PDPR1H1HAW***
|
|
739
|
+
│ Get FW_CODE │ ──────► 53****
|
|
622
740
|
└─────────────────┘
|
|
623
741
|
│
|
|
624
742
|
▼
|
|
625
743
|
┌─────────────────┐
|
|
626
|
-
│ Load JSON File │ ──────►
|
|
744
|
+
│ Load JSON File │ ──────► model_PDPR1H1HAW***_FW53****.json
|
|
627
745
|
└─────────────────┘
|
|
628
746
|
│
|
|
629
747
|
▼
|
|
@@ -741,12 +859,54 @@ The `instant_values_structured()` method returns data organized by type:
|
|
|
741
859
|
|
|
742
860
|
This client has been tested with:
|
|
743
861
|
|
|
744
|
-
- **PoolDose Double/Dual WiFi** (Model:
|
|
862
|
+
- **SEKO PoolDose Double/Dual WiFi** (Model: PDPR1H1HAW***, FW: 53****)
|
|
863
|
+
- **VA dos BASIC Chlor - pH/ORP Wi-Fi** (Model: PDPR1H1HAR***, FW: 53****)
|
|
745
864
|
|
|
746
|
-
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/
|
|
865
|
+
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`).
|
|
747
866
|
|
|
748
867
|
> **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.
|
|
749
868
|
|
|
869
|
+
## Type Hints & Home Assistant Integration
|
|
870
|
+
|
|
871
|
+
This package is **PEP-561 compliant** and fully typed for use in Home Assistant integrations:
|
|
872
|
+
|
|
873
|
+
### Type Safety Features
|
|
874
|
+
|
|
875
|
+
**PEP-561 Compliance**: Package includes `py.typed` file marking it as fully typed
|
|
876
|
+
**Comprehensive Type Annotations**: All public API methods have complete type hints
|
|
877
|
+
**mypy Support**: Built-in mypy configuration for static type checking
|
|
878
|
+
**Home Assistant Ready**: Compatible with Home Assistant's strict typing requirements
|
|
879
|
+
|
|
880
|
+
### Type-Safe Usage
|
|
881
|
+
|
|
882
|
+
```python
|
|
883
|
+
from pooldose import PooldoseClient
|
|
884
|
+
from pooldose.request_status import RequestStatus
|
|
885
|
+
|
|
886
|
+
# Type checkers will infer all types automatically
|
|
887
|
+
client: PooldoseClient = PooldoseClient("192.168.1.100")
|
|
888
|
+
status: RequestStatus = await client.connect()
|
|
889
|
+
|
|
890
|
+
# Dictionary-style access with proper typing
|
|
891
|
+
status, instant_values = await client.instant_values()
|
|
892
|
+
if status == RequestStatus.SUCCESS and instant_values:
|
|
893
|
+
temperature = instant_values["temperature"] # Typed as tuple[float, str]
|
|
894
|
+
ph_value = instant_values.get("ph", "N/A") # Safe access with default
|
|
895
|
+
|
|
896
|
+
# Structured data with full type safety
|
|
897
|
+
status, structured_data = await client.instant_values_structured()
|
|
898
|
+
sensors = structured_data.get("sensor", {}) # Type: dict[str, dict[str, Any]]
|
|
899
|
+
```
|
|
900
|
+
|
|
901
|
+
### Integration Benefits
|
|
902
|
+
|
|
903
|
+
- **IDE Support**: Full autocomplete and type checking in VS Code, PyCharm, etc.
|
|
904
|
+
- **Runtime Safety**: Catch type errors before deployment
|
|
905
|
+
- **Documentation**: Self-documenting code through type annotations
|
|
906
|
+
- **Maintenance**: Easier refactoring with type-guided development
|
|
907
|
+
|
|
908
|
+
For Home Assistant integrations, add this package to your integration's dependencies and enjoy full type safety throughout your integration code.
|
|
909
|
+
|
|
750
910
|
## Security
|
|
751
911
|
|
|
752
912
|
By default, the client excludes sensitive information like WiFi passwords from device info. To include sensitive data:
|
|
@@ -761,7 +921,7 @@ status = await client.connect()
|
|
|
761
921
|
|
|
762
922
|
### Security Model
|
|
763
923
|
|
|
764
|
-
```
|
|
924
|
+
```text
|
|
765
925
|
Data Classification:
|
|
766
926
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
767
927
|
│ Public Data │ │ Sensitive Data │ │ Never Exposed │
|
|
@@ -782,9 +942,8 @@ Data Classification:
|
|
|
782
942
|
|
|
783
943
|
For detailed release notes and version history, please see [CHANGELOG.md](CHANGELOG.md).
|
|
784
944
|
|
|
785
|
-
### Latest Release (0.5
|
|
945
|
+
### Latest Release (0.6.5)
|
|
786
946
|
|
|
787
|
-
- **
|
|
788
|
-
- **
|
|
789
|
-
- **
|
|
790
|
-
- **Fixed**: Removed deprecated references and improved consistency
|
|
947
|
+
- **Device Analyzer**: New CLI command `--analyze` for comprehensive device analysis and support discovery
|
|
948
|
+
- **Code Quality**: Perfect Pylint 10.00/10 score with complete PEP-561 compliance
|
|
949
|
+
- **Enhanced Documentation**: Added device analysis guide for unsupported device discovery
|
|
@@ -10,6 +10,9 @@ This client uses an undocumented local HTTP API. It provides live readings for p
|
|
|
10
10
|
- **Dynamic sensor discovery** based on device model and firmware
|
|
11
11
|
- **Dictionary-style access** to instant values
|
|
12
12
|
- **Structured data API** with type-based organization
|
|
13
|
+
- **Device analyzer** for discovering unsupported device capabilities
|
|
14
|
+
- **PEP-561 compliant** with full type hints for Home Assistant integrations
|
|
15
|
+
- **Command-line interface** for direct device interaction and testing
|
|
13
16
|
- **Secure by default** - WiFi passwords excluded unless explicitly requested
|
|
14
17
|
- **Comprehensive error handling** with detailed logging
|
|
15
18
|
- **SSL/HTTPS support** for secure communication
|
|
@@ -151,6 +154,141 @@ client = PooldoseClient("192.168.1.100", use_ssl=True, port=8443, ssl_verify=Fal
|
|
|
151
154
|
pip install python-pooldose
|
|
152
155
|
```
|
|
153
156
|
|
|
157
|
+
## Command Line Usage
|
|
158
|
+
|
|
159
|
+
After installation, you can use python-pooldose directly from the command line:
|
|
160
|
+
|
|
161
|
+
### Connect to Real Device
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
# Basic connection
|
|
165
|
+
pooldose --host 192.168.1.100
|
|
166
|
+
|
|
167
|
+
# With HTTPS
|
|
168
|
+
pooldose --host 192.168.1.100 --ssl
|
|
169
|
+
|
|
170
|
+
# Custom port
|
|
171
|
+
pooldose --host 192.168.1.100 --ssl --port 8443
|
|
172
|
+
|
|
173
|
+
# Analyze device capabilities (discover unsupported devices)
|
|
174
|
+
pooldose --host 192.168.1.100 --analyze
|
|
175
|
+
|
|
176
|
+
# Show all widgets including hidden ones
|
|
177
|
+
pooldose --host 192.168.1.100 --analyze-all
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### Mock Mode with JSON Files
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
# Use JSON file for testing
|
|
184
|
+
pooldose --mock path/to/your/data.json
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### Alternative Module Execution
|
|
188
|
+
|
|
189
|
+
You can also run it as a Python module:
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
# Real device
|
|
193
|
+
python -m pooldose --host 192.168.1.100
|
|
194
|
+
|
|
195
|
+
# Device analysis
|
|
196
|
+
python -m pooldose --host 192.168.1.100 --analyze
|
|
197
|
+
|
|
198
|
+
# Mock mode
|
|
199
|
+
python -m pooldose --mock data.json
|
|
200
|
+
|
|
201
|
+
# Show help
|
|
202
|
+
python -m pooldose --help
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
## Device Analysis for Unsupported Devices
|
|
206
|
+
|
|
207
|
+
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:
|
|
208
|
+
|
|
209
|
+
- **New Device Discovery**: Identifying capabilities of unknown device models
|
|
210
|
+
- **Device Support Development**: Gathering data needed to add support for new devices
|
|
211
|
+
- **Troubleshooting**: Understanding how your device exposes data and controls
|
|
212
|
+
- **Widget Exploration**: Discovering all available sensors, controls, and settings
|
|
213
|
+
|
|
214
|
+
### Basic Device Analysis
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
# Analyze a device to discover its capabilities
|
|
218
|
+
pooldose --host 192.168.1.100 --analyze
|
|
219
|
+
|
|
220
|
+
# Show all widgets including hidden ones
|
|
221
|
+
pooldose --host 192.168.1.100 --analyze-all
|
|
222
|
+
|
|
223
|
+
# Analyze with HTTPS
|
|
224
|
+
pooldose --host 192.168.1.100 --ssl --analyze
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
### Analysis Output
|
|
228
|
+
|
|
229
|
+
The analyzer provides comprehensive information about your device:
|
|
230
|
+
|
|
231
|
+
```
|
|
232
|
+
=== DEVICE ANALYSIS ===
|
|
233
|
+
Device: 01234567890A_DEVICE
|
|
234
|
+
Model: PDPR1H1HAW***
|
|
235
|
+
Firmware: FW53****
|
|
236
|
+
|
|
237
|
+
=== WIDGETS (Visible UI Elements) ===
|
|
238
|
+
|
|
239
|
+
SENSORS (Read-only values)
|
|
240
|
+
temperature: 24.5°C
|
|
241
|
+
ph: 7.2
|
|
242
|
+
orp: 720 mV
|
|
243
|
+
|
|
244
|
+
SETPOINTS (Configurable values)
|
|
245
|
+
target_ph: 7.0 (Range: 6.0-8.0, Step: 0.1)
|
|
246
|
+
target_orp: 700 mV (Range: 400-900, Step: 10)
|
|
247
|
+
|
|
248
|
+
SWITCHES (On/Off controls)
|
|
249
|
+
stop_dosing: OFF
|
|
250
|
+
pump_detection: ON
|
|
251
|
+
|
|
252
|
+
SELECTS (Configuration options)
|
|
253
|
+
water_meter_unit: L/h
|
|
254
|
+
Options: [L/h, m³/h, gal/h]
|
|
255
|
+
|
|
256
|
+
ALARMS (Status indicators)
|
|
257
|
+
alarm_ph: OK
|
|
258
|
+
alarm_orp: OK
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
### Using Analysis for Device Support
|
|
262
|
+
|
|
263
|
+
When you encounter an unsupported device, the analyzer helps gather the necessary information:
|
|
264
|
+
|
|
265
|
+
1. **Run Analysis**: Use `--analyze` to discover all device capabilities
|
|
266
|
+
2. **Document Output**: Save the analysis output to understand device structure
|
|
267
|
+
3. **Check Widget Types**: Note which sensors, controls, and settings are available
|
|
268
|
+
4. **Identify Patterns**: Look for device model and firmware information
|
|
269
|
+
5. **Report Findings**: Use the analysis data to request support for your device model
|
|
270
|
+
|
|
271
|
+
### Example: Discovering New Device
|
|
272
|
+
|
|
273
|
+
```bash
|
|
274
|
+
# Unknown device analysis
|
|
275
|
+
pooldose --host 192.168.1.100 --analyze
|
|
276
|
+
|
|
277
|
+
# Output shows:
|
|
278
|
+
# Device: 01987654321B_DEVICE
|
|
279
|
+
# Model: PDPR2H2XYZ*** ← New model not yet supported
|
|
280
|
+
# Firmware: FW54**** ← New firmware version
|
|
281
|
+
#
|
|
282
|
+
# Widgets discovered: 15 sensors, 8 controls, 12 settings
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
With this information, you can:
|
|
286
|
+
- Report the new model/firmware combination
|
|
287
|
+
- Share the widget structure for mapping development
|
|
288
|
+
- Help expand device support for the community
|
|
289
|
+
|
|
290
|
+
The device analyzer makes python-pooldose extensible and helps build support for the growing ecosystem of SEKO PoolDose devices.
|
|
291
|
+
|
|
154
292
|
## Examples
|
|
155
293
|
|
|
156
294
|
The `examples/` directory contains demonstration scripts that show how to use the python-pooldose library:
|
|
@@ -171,25 +309,6 @@ python examples/demo.py
|
|
|
171
309
|
- Displays all sensor readings, alarms, setpoints, and settings
|
|
172
310
|
- Demonstrates error handling
|
|
173
311
|
|
|
174
|
-
### 2. Mock Client Demo (`examples/demo_mock.py`)
|
|
175
|
-
|
|
176
|
-
Shows how to use the mock client with JSON files for development and testing:
|
|
177
|
-
|
|
178
|
-
```bash
|
|
179
|
-
# Run with sample data
|
|
180
|
-
python examples/demo_mock.py references/testdaten/suplere/instantvalues.json
|
|
181
|
-
|
|
182
|
-
# Use custom JSON file
|
|
183
|
-
python examples/demo_mock.py path/to/your/data.json
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
**Features:**
|
|
187
|
-
|
|
188
|
-
- No hardware required
|
|
189
|
-
- Uses real device data from JSON files
|
|
190
|
-
- Same API as real client
|
|
191
|
-
- Perfect for development and CI/CD
|
|
192
|
-
|
|
193
312
|
### Benefits of the Examples
|
|
194
313
|
|
|
195
314
|
- **Learning**: Step-by-step progression from simple to advanced usage
|
|
@@ -248,14 +367,14 @@ asyncio.run(simple_test())
|
|
|
248
367
|
|
|
249
368
|
### Mock Client Command Line Usage
|
|
250
369
|
|
|
251
|
-
You can
|
|
370
|
+
You can use the mock client with custom JSON files via the command line:
|
|
252
371
|
|
|
253
372
|
```bash
|
|
254
|
-
#
|
|
255
|
-
|
|
373
|
+
# Use mock client with JSON file
|
|
374
|
+
pooldose --mock path/to/your/data.json
|
|
256
375
|
|
|
257
|
-
#
|
|
258
|
-
python
|
|
376
|
+
# Or as Python module
|
|
377
|
+
python -m pooldose --mock path/to/your/data.json
|
|
259
378
|
```
|
|
260
379
|
|
|
261
380
|
### JSON Data Format
|
|
@@ -326,8 +445,7 @@ success = client.reload_data()
|
|
|
326
445
|
|
|
327
446
|
The following sample JSON files are available in the repository:
|
|
328
447
|
|
|
329
|
-
- `references/testdaten/
|
|
330
|
-
- `references/testdaten/instantvalues_poolforum_1.json` - Additional sample data
|
|
448
|
+
- `references/testdaten/tscherno/instantvalues.json` - Sample device data for testing
|
|
331
449
|
|
|
332
450
|
### Mock Client Use Cases
|
|
333
451
|
|
|
@@ -599,13 +717,13 @@ Mapping Discovery Process:
|
|
|
599
717
|
│
|
|
600
718
|
▼
|
|
601
719
|
┌─────────────────┐
|
|
602
|
-
│ Get MODEL_ID │ ──────►
|
|
603
|
-
│ Get FW_CODE │ ──────►
|
|
720
|
+
│ Get MODEL_ID │ ──────► PDPR1H1HAW***
|
|
721
|
+
│ Get FW_CODE │ ──────► 53****
|
|
604
722
|
└─────────────────┘
|
|
605
723
|
│
|
|
606
724
|
▼
|
|
607
725
|
┌─────────────────┐
|
|
608
|
-
│ Load JSON File │ ──────►
|
|
726
|
+
│ Load JSON File │ ──────► model_PDPR1H1HAW***_FW53****.json
|
|
609
727
|
└─────────────────┘
|
|
610
728
|
│
|
|
611
729
|
▼
|
|
@@ -723,12 +841,54 @@ The `instant_values_structured()` method returns data organized by type:
|
|
|
723
841
|
|
|
724
842
|
This client has been tested with:
|
|
725
843
|
|
|
726
|
-
- **PoolDose Double/Dual WiFi** (Model:
|
|
844
|
+
- **SEKO PoolDose Double/Dual WiFi** (Model: PDPR1H1HAW***, FW: 53****)
|
|
845
|
+
- **VA dos BASIC Chlor - pH/ORP Wi-Fi** (Model: PDPR1H1HAR***, FW: 53****)
|
|
727
846
|
|
|
728
|
-
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/
|
|
847
|
+
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`).
|
|
729
848
|
|
|
730
849
|
> **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.
|
|
731
850
|
|
|
851
|
+
## Type Hints & Home Assistant Integration
|
|
852
|
+
|
|
853
|
+
This package is **PEP-561 compliant** and fully typed for use in Home Assistant integrations:
|
|
854
|
+
|
|
855
|
+
### Type Safety Features
|
|
856
|
+
|
|
857
|
+
**PEP-561 Compliance**: Package includes `py.typed` file marking it as fully typed
|
|
858
|
+
**Comprehensive Type Annotations**: All public API methods have complete type hints
|
|
859
|
+
**mypy Support**: Built-in mypy configuration for static type checking
|
|
860
|
+
**Home Assistant Ready**: Compatible with Home Assistant's strict typing requirements
|
|
861
|
+
|
|
862
|
+
### Type-Safe Usage
|
|
863
|
+
|
|
864
|
+
```python
|
|
865
|
+
from pooldose import PooldoseClient
|
|
866
|
+
from pooldose.request_status import RequestStatus
|
|
867
|
+
|
|
868
|
+
# Type checkers will infer all types automatically
|
|
869
|
+
client: PooldoseClient = PooldoseClient("192.168.1.100")
|
|
870
|
+
status: RequestStatus = await client.connect()
|
|
871
|
+
|
|
872
|
+
# Dictionary-style access with proper typing
|
|
873
|
+
status, instant_values = await client.instant_values()
|
|
874
|
+
if status == RequestStatus.SUCCESS and instant_values:
|
|
875
|
+
temperature = instant_values["temperature"] # Typed as tuple[float, str]
|
|
876
|
+
ph_value = instant_values.get("ph", "N/A") # Safe access with default
|
|
877
|
+
|
|
878
|
+
# Structured data with full type safety
|
|
879
|
+
status, structured_data = await client.instant_values_structured()
|
|
880
|
+
sensors = structured_data.get("sensor", {}) # Type: dict[str, dict[str, Any]]
|
|
881
|
+
```
|
|
882
|
+
|
|
883
|
+
### Integration Benefits
|
|
884
|
+
|
|
885
|
+
- **IDE Support**: Full autocomplete and type checking in VS Code, PyCharm, etc.
|
|
886
|
+
- **Runtime Safety**: Catch type errors before deployment
|
|
887
|
+
- **Documentation**: Self-documenting code through type annotations
|
|
888
|
+
- **Maintenance**: Easier refactoring with type-guided development
|
|
889
|
+
|
|
890
|
+
For Home Assistant integrations, add this package to your integration's dependencies and enjoy full type safety throughout your integration code.
|
|
891
|
+
|
|
732
892
|
## Security
|
|
733
893
|
|
|
734
894
|
By default, the client excludes sensitive information like WiFi passwords from device info. To include sensitive data:
|
|
@@ -743,7 +903,7 @@ status = await client.connect()
|
|
|
743
903
|
|
|
744
904
|
### Security Model
|
|
745
905
|
|
|
746
|
-
```
|
|
906
|
+
```text
|
|
747
907
|
Data Classification:
|
|
748
908
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
749
909
|
│ Public Data │ │ Sensitive Data │ │ Never Exposed │
|
|
@@ -764,9 +924,8 @@ Data Classification:
|
|
|
764
924
|
|
|
765
925
|
For detailed release notes and version history, please see [CHANGELOG.md](CHANGELOG.md).
|
|
766
926
|
|
|
767
|
-
### Latest Release (0.5
|
|
927
|
+
### Latest Release (0.6.5)
|
|
768
928
|
|
|
769
|
-
- **
|
|
770
|
-
- **
|
|
771
|
-
- **
|
|
772
|
-
- **Fixed**: Removed deprecated references and improved consistency
|
|
929
|
+
- **Device Analyzer**: New CLI command `--analyze` for comprehensive device analysis and support discovery
|
|
930
|
+
- **Code Quality**: Perfect Pylint 10.00/10 score with complete PEP-561 compliance
|
|
931
|
+
- **Enhanced Documentation**: Added device analysis guide for unsupported device discovery
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "python-pooldose"
|
|
3
|
+
dynamic = ["version"]
|
|
4
|
+
description = "Unoffical async Python client for SEKO PoolDose devices"
|
|
5
|
+
authors = [
|
|
6
|
+
{ name = "Lukas Maertin", email = "pypi@lukas-maertin.de" }
|
|
7
|
+
]
|
|
8
|
+
license = "MIT"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
dependencies = [
|
|
12
|
+
"aiohttp",
|
|
13
|
+
"aiofiles"
|
|
14
|
+
]
|
|
15
|
+
|
|
16
|
+
[project.urls]
|
|
17
|
+
Homepage = "https://github.com/lmaertin/python-pooldose"
|
|
18
|
+
Repository = "https://github.com/lmaertin/python-pooldose"
|
|
19
|
+
|
|
20
|
+
[project.scripts]
|
|
21
|
+
pooldose = "pooldose.__main__:main"
|
|
22
|
+
|
|
23
|
+
[build-system]
|
|
24
|
+
requires = ["setuptools>=61.0", "wheel"]
|
|
25
|
+
build-backend = "setuptools.build_meta"
|
|
26
|
+
|
|
27
|
+
[project.optional-dependencies]
|
|
28
|
+
dev = ["pytest", "pytest-asyncio"]
|
|
29
|
+
|
|
30
|
+
[tool.setuptools]
|
|
31
|
+
package-dir = {"" = "src"}
|
|
32
|
+
|
|
33
|
+
[tool.setuptools.dynamic]
|
|
34
|
+
version = {attr = "pooldose.__version__"}
|
|
35
|
+
|
|
36
|
+
[tool.setuptools.packages.find]
|
|
37
|
+
where = ["src"]
|
|
38
|
+
|
|
39
|
+
[tool.setuptools.package-data]
|
|
40
|
+
"pooldose.mappings" = ["*.json"]
|
|
41
|
+
"pooldose" = ["py.typed"]
|
|
42
|
+
|
|
43
|
+
[tool.pytest.ini_options]
|
|
44
|
+
testpaths = ["tests"]
|
|
45
|
+
asyncio_mode = "auto"
|
|
46
|
+
|
|
47
|
+
[tool.mypy]
|
|
48
|
+
python_version = "3.11"
|
|
49
|
+
# Home Assistant strict typing compliance
|
|
50
|
+
strict = false
|
|
51
|
+
warn_return_any = false
|
|
52
|
+
warn_unused_configs = true
|
|
53
|
+
disallow_untyped_defs = false
|
|
54
|
+
disallow_incomplete_defs = false
|
|
55
|
+
check_untyped_defs = true
|
|
56
|
+
no_implicit_optional = true
|
|
57
|
+
warn_redundant_casts = true
|
|
58
|
+
warn_unused_ignores = false
|
|
59
|
+
warn_no_return = true
|
|
60
|
+
strict_equality = true
|
|
61
|
+
ignore_missing_imports = true
|
|
62
|
+
# Focus on public API typing
|
|
63
|
+
show_error_codes = true
|
|
64
|
+
|
|
65
|
+
[[tool.mypy.overrides]]
|
|
66
|
+
module = "examples.*"
|
|
67
|
+
ignore_errors = true
|
|
68
|
+
|
|
69
|
+
[[tool.mypy.overrides]]
|
|
70
|
+
module = "tests.*"
|
|
71
|
+
ignore_errors = true
|
|
72
|
+
|
|
73
|
+
# Strict typing for core public API modules
|
|
74
|
+
[[tool.mypy.overrides]]
|
|
75
|
+
module = "pooldose.__init__"
|
|
76
|
+
disallow_untyped_defs = true
|
|
77
|
+
disallow_incomplete_defs = true
|
|
78
|
+
|
|
79
|
+
[[tool.mypy.overrides]]
|
|
80
|
+
module = "pooldose.client"
|
|
81
|
+
disallow_untyped_defs = true
|
|
82
|
+
disallow_incomplete_defs = true
|
|
83
|
+
warn_return_any = false
|
|
84
|
+
|
|
85
|
+
[[tool.mypy.overrides]]
|
|
86
|
+
module = "pooldose.request_status"
|
|
87
|
+
disallow_untyped_defs = true
|
|
88
|
+
disallow_incomplete_defs = true
|