alpha-hwr 0.2.0__tar.gz

alpha_hwr-0.2.0/.bumpversion.cfg

@@ -0,0 +1,27 @@
+[bumpversion]
+current_version = 0.2.0
+commit = True
+tag = True
+tag_name = v{new_version}
+tag_message = Release version {new_version}
+message = Bump version: {current_version} → {new_version}
+
+[bumpversion:file:pyproject.toml]
+search = version = "{current_version}"
+replace = version = "{new_version}"
+
+[bumpversion:file:src/alpha_hwr/__init__.py]
+search = __version__ = "{current_version}"
+replace = __version__ = "{new_version}"
+
+[bumpversion:file:CHANGELOG.md]
+search = ## [Unreleased]
+replace = ## [Unreleased]
+
+[bumpversion:file:mkdocs.yml]
+search = version: "{current_version}"
+replace = version: "{new_version}"
+
+[bumpversion:file:docs/index.md]
+search = *Version: {current_version}*
+replace = *Version: {new_version}*

alpha_hwr-0.2.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [## [Unreleased]] - 2026-02-01
+
+### Added
+
+- **BLE connection to Grundfos ALPHA HWR pumps**
+- **Telemetry reading** (Flow, Head, Power, Temperature, Voltage/Current, Speed)
+- **Passive monitoring mode** with continuous data stream
+- **CLI interface** for monitoring and control
+- **AsyncIO-based architecture** using `bleak`
+- **Type-safe API** with Pydantic models
+- **Cross-platform device addressing** (macOS UUID / Linux+Windows MAC)
+
+#### Service Enhancements
+
+- **Power-On Time History**
+  - Added power-on time trend data to HistoryService (Object 53, SubID 454)
+  - Extended TrendDataCollection model with `power_on_time_series` field
+  - Updated history CLI to display power-on time trends in hours
+- **Event Log Service - Complete Protocol Decoding**
+  - Fully decoded EventLogMetadata structure (SubID 10199, 7 bytes)
+  - CLI commands: `alpha-hwr events list`, `alpha-hwr events show INDEX`, `alpha-hwr events metadata`
+- **History Service - CLI Implementation**
+  - New CLI commands for historical/trend data access
+  - `alpha-hwr history trends [--detailed]` - Display flow/head/temperature trends
+  - `alpha-hwr history timestamps [--count 10|100]` - Show cycle timestamps
+- **Schedule Management**
+  - Read/write weekly schedules from all 5 layers (SubIDs 1000-1004)
+  - Enable/disable global schedule with `set_schedule_enabled()`
+  - CLI commands: `alpha-hwr schedule [--enable|--disable|--set-entry|--clear-day|--clear-layer]`
+  - Export/import schedules as JSON for backup/restore
+- **Configuration Backup and Restore**
+  - Save/Restore pump configuration including schedules, modes, and setpoints to JSON
+  - CLI commands: `alpha-hwr config backup` and `alpha-hwr config restore`
+
+### Changed
+
+- **Major Architectural Refactor**
+  - **Complete codebase restructure**: Moved from a monolithic client to a modular service-oriented architecture.
+  - **New `core` layer**: Handles connection, authentication, session state, and transport independently.
+  - **New `protocol` layer**: Separated frame building, parsing, and codec logic. Added support for Class 3 and Class 10 GENI protocols.
+  - **New `services` layer**: Logic split into dedicated services (Telemetry, Control, Schedule, etc.).
+  - **New `client` facade**: `AlphaHWRClient` delegates to specialized services.
+  - **New `cli` structure**: CLI commands organized by domain using Typer.
+- **Control Service - Enhanced Safety and Reliability**
+  - Added setpoint validation to all control mode setters
+  - Improved error messages for out-of-range setpoints
+  - Now uses `transport.query()` for reliable request/response transactions
+
+### Fixed
+
+- **Device Statistics Bug**: Fixed statistics returning None after BaseService refactoring.
+- **Schedule Write Operations**: Fixed to use correct OpSpec 0xB3 format discovered through protocol analysis.
+- **BLE Packet Splitting**: Fixed packet splitting logic to handle 3+ chunks for large data writes.
+- **Control Mode Reading**: Fixed incorrect byte offset in `get_control_mode()`.

alpha_hwr-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,143 @@
+# Contributing to alpha-hwr
+
+Thank you for your interest in contributing to alpha-hwr!
+
+## Development Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/eman/alpha-hwr.git
+   cd alpha-hwr
+   ```
+
+2. **Create a virtual environment and install dependencies:**
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   pip install -e ".[dev,docs]"
+   ```
+
+## Running Tests Locally
+
+We provide a convenient script to run all checks that will be executed in CI:
+
+```bash
+./scripts/check.sh
+```
+
+This will run:
+- Ruff format check
+- Ruff lint
+- MyPy type checking
+- BasedPyright type checking
+- Pytest with coverage
+
+### Running Individual Checks
+
+```bash
+# Format code
+ruff format .
+
+# Check formatting
+ruff format --check .
+
+# Lint
+ruff check .
+
+# Type check with MyPy
+mypy src/alpha_hwr
+
+# Type check with BasedPyright
+basedpyright
+
+# Run tests
+pytest tests/ -v
+
+# Run tests with coverage
+pytest tests/ --cov=alpha_hwr --cov-report=term
+
+# Run all checks with tox
+tox
+```
+
+## Code Quality
+
+- **Linting**: Code must pass `ruff check`
+- **Type Checking**: Code must pass `mypy` and `basedpyright`
+- **Testing**: All tests must pass (`pytest`)
+- **Coverage**: Maintain or improve test coverage
+
+## Code Style
+
+- We use **Ruff** for formatting and linting
+- Line length: 80 characters
+- Follow PEP 8 conventions
+- Use type hints for all functions
+- Write docstrings for public APIs (Google-style format)
+
+## Architecture
+
+Please read `copilot-instructions.md` for architecture guidelines. The project follows a strict layered architecture:
+
+- **Core**: Connection, authentication, transport (`src/alpha_hwr/core/`)
+- **Protocol**: Frame building, parsing, codec (`src/alpha_hwr/protocol/`)
+- **Services**: Business logic for Telemetry, Control, Schedule, etc. (`src/alpha_hwr/services/`)
+- **Client**: Unified facade API (`src/alpha_hwr/client.py`)
+
+## Documentation Requirements
+
+**IMPORTANT**: When adding or modifying features, you MUST update the corresponding documentation files:
+
+1. **Source Code Documentation**:
+   - Add/update docstrings in the source code
+   - Follow Google-style docstring format
+   - Include parameter types, return types, and examples
+
+2. **User-Facing Documentation** (update ALL applicable files):
+   - `README.md` - User-facing examples and CLI usage
+   - `CHANGELOG.md` - Add entry under "Unreleased" section
+   - `docs/api/client.md` - API method documentation
+   - `docs/api/models.md` - Data model documentation
+   - `docs/api/constants.md` - Constants and enums
+   - `docs/getting_started/quick_start.md` - Usage examples
+   - `docs/index.md` - Feature list and overview
+   - `docs/protocol/control.md` - Protocol details
+   - `docs/reference/data_models.md` - Reference material
+
+3. **What to Document**:
+   - New API methods or parameters
+   - New control modes or capabilities
+   - Protocol changes or discoveries
+   - CLI command additions or changes
+
+## Testing
+
+- **Unit Tests**: Test protocol logic in isolation (`tests/unit/`)
+- **Integration Tests**: Test end-to-end workflows using MockPump (`tests/integration/`)
+- **Reference Tests**: Validate against known byte-level vectors (`tests/reference/`)
+
+All new features should include appropriate tests.
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run `./scripts/check.sh` to ensure all checks pass
+5. Update relevant documentation
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to your fork (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+## Release Process
+
+Releases are managed by maintainers:
+
+1. Update CHANGELOG.md
+2. Run `bump2version [major|minor|patch]` to create version tag
+3. Push tags: `git push --tags`
+4. Create a GitHub Release - this triggers PyPI publishing automatically
+
+## Questions?
+
+Open an issue for questions, bug reports, or feature requests.

alpha_hwr-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emmanuel Levijarvi
+
+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.

alpha_hwr-0.2.0/MANIFEST.in

@@ -0,0 +1,21 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include pyproject.toml
+include .bumpversion.cfg
+recursive-include src *.py
+recursive-include tests *.py
+recursive-include docs *.md *.yml
+include mkdocs.yml
+exclude .env
+exclude .env.*
+prune .git
+prune .github
+prune .venv
+prune __pycache__
+prune *.egg-info
+prune build
+prune dist
+global-exclude *.pyc
+global-exclude .DS_Store

alpha_hwr-0.2.0/PKG-INFO

@@ -0,0 +1,419 @@
+Metadata-Version: 2.4
+Name: alpha-hwr
+Version: 0.2.0
+Summary: Modern Python library and CLI for Grundfos ALPHA HWR pumps via Bluetooth Low Energy
+Author-email: Grundfos Firmware Team <firmware@grundfos.com>
+License: MIT
+Project-URL: Homepage, https://github.com/eman/alpha-hwr
+Project-URL: Documentation, https://eman.github.io/alpha-hwr
+Project-URL: Repository, https://github.com/eman/alpha-hwr
+Project-URL: Issues, https://github.com/eman/alpha-hwr/issues
+Project-URL: Changelog, https://github.com/eman/alpha-hwr/blob/main/CHANGELOG.md
+Keywords: grundfos,alpha-hwr,pump,ble,bluetooth,iot,hardware,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Classifier: Topic :: Home Automation
+Classifier: Topic :: System :: Monitoring
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak>=0.19.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: tox>=4.0.0; extra == "dev"
+Requires-Dist: bump2version>=1.0.0; extra == "dev"
+Requires-Dist: basedpyright>=1.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Dynamic: license-file
+
+# Grundfos ALPHA HWR Python Client
+
+A modern Python library and CLI for interacting with Grundfos ALPHA HWR pumps via Bluetooth Low Energy (BLE).
+
+## Features
+
+- **Passive Monitoring**: Continuously monitor pump telemetry (Flow, Head, Power, Temperature, Voltage/Current, Speed).
+- **Status Reading**: Read current control mode, setpoint values (with min/max limits), alarms/warnings, cumulative statistics, and device information.
+- **Active Control**: Set pump modes and setpoints with automatic validation (Constant Pressure, Proportional Pressure, Constant Speed, Constant Flow, AutoAdapt variants).
+- **Schedule Management**: Read and write weekly schedules across 5 independent layers with comprehensive validation.
+- **Type-Safe**: Fully typed API using standard Python type hints and Pydantic models.
+- **AsyncIO**: Built on `bleak` for efficient asynchronous BLE communication.
+- **CLI**: Built-in command-line interface for quick diagnostics and control.
+
+## Installation
+
+```bash
+pip install .
+```
+
+## Configuration
+
+The library supports cross-platform device addressing and automatic discovery. Create a `.env` file in your project root:
+
+```bash
+# BLE Device Address
+# Format is platform-specific:
+# - macOS: Uses UUID format (e.g., "A1B2C3D4-E5F6-7890-1234-567890ABCDEF")
+# - Linux/Windows: Uses MAC address format (e.g., "00:11:22:33:44:55")
+# 
+# Seamless Cross-Platform: You can provide a comma-separated list of addresses.
+# The library automatically picks the correct one for your current OS.
+ALPHA_HWR_DEVICE_ADDRESS="A1B2C3D4-E5F6-7890-1234-567890ABCDEF, 00:11:22:33:44:55"
+```
+
+### Automatic Discovery
+
+If you don't provide a device address (either via `.env` or as a parameter), the library will automatically attempt to discover and connect to any nearby ALPHA HWR pump.
+
+## Usage
+
+### CLI
+
+**Discovery:**
+```bash
+# Scan for nearby pumps
+alpha-hwr device scan
+```
+
+**Monitoring:**
+```bash
+# Monitor default device
+alpha-hwr monitor
+```
+
+**Device Information:**
+```bash
+# Get device information
+alpha-hwr device info
+
+# Get cumulative statistics (operating hours, start count)
+alpha-hwr device stats
+
+# Check for active alarms and warnings
+alpha-hwr device alarms
+```
+
+**Control Commands:**
+```bash
+# Show current control mode and setpoint
+alpha-hwr control status
+
+# Start/stop pump
+alpha-hwr control start
+alpha-hwr control stop
+
+# Set constant pressure mode (meters of water column)
+alpha-hwr control set-pressure 1.5
+
+# Set constant speed mode (RPM)
+alpha-hwr control set-speed 2500
+```
+
+**History & Events:**
+```bash
+# Show historical trend data (last 10 cycles)
+alpha-hwr history trends
+
+# Show full 100-cycle history
+alpha-hwr history trends --detailed
+
+# List pump event log
+alpha-hwr events list
+```
+
+**Schedule Management:**
+```bash
+# Read current schedule
+alpha-hwr schedule list
+
+# Enable/disable the schedule
+alpha-hwr schedule enable
+alpha-hwr schedule disable
+```
+
+**Configuration Backup & Restore:**
+```bash
+# Backup pump configuration (schedules, modes, setpoints)
+alpha-hwr config backup pump_config.json
+
+# Restore configuration from backup
+alpha-hwr config restore pump_config.json
+```
+
+### Library
+
+**Basic Monitoring:**
+```python
+import asyncio
+from alpha_hwr import AlphaHWRClient
+
+async def main():
+    async with AlphaHWRClient("DEVICE_UUID") as client:
+        # Authenticate first
+        await client.pair_device()
+        
+        # Get single reading
+        telemetry = await client.read_telemetry()
+        print(f"Flow: {telemetry.flow_m3h} m3/h")
+        
+        # Continuous monitoring
+        async for data in client.monitor():
+            print(data)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+**Reading Status Information:**
+```python
+import asyncio
+from alpha_hwr import AlphaHWRClient
+
+async def main():
+    async with AlphaHWRClient("DEVICE_UUID") as client:
+        await client.pair_device()
+        
+        # Get current control mode
+        mode = await client.get_control_mode()
+        print(f"Mode: {mode}")
+        
+        # Read current setpoint with limits
+        setpoint = await client.read_current_setpoint(include_limits=True)
+        if setpoint:
+            value, unit = setpoint.get_display_value()
+            print(f"Setpoint: {value:.2f} {unit}")
+            
+            if setpoint.min_setpoint:
+                limits = setpoint.get_limits_display()
+                if limits:
+                    (min_val, min_unit), (max_val, max_unit) = limits
+                    print(f"Limits: {min_val:.2f} - {max_val:.2f} {max_unit}")
+        
+        # Check for alarms
+        alarms = await client.read_alarms()
+        if alarms and alarms.alarm_code and alarms.alarm_code != 0:
+            print(f"ALARM: {alarms.alarm_description}")
+        
+        # Read cumulative statistics
+        stats = await client.read_statistics()
+        if stats:
+            print(f"Operating Hours: {stats.operating_hours:.1f} h")
+            print(f"Start Count: {stats.start_count}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+**Setting Control Modes and Setpoints:**
+```python
+import asyncio
+from alpha_hwr import AlphaHWRClient
+
+async def main():
+    async with AlphaHWRClient("DEVICE_UUID") as client:
+        await client.pair_device()
+        
+        # Set constant pressure mode (automatic validation against limits)
+        success = await client.set_constant_pressure(1.5)  # 1.5 meters
+        if success:
+            print("Pressure setpoint updated successfully")
+        
+        # Set proportional pressure mode
+        success = await client.set_proportional_pressure(1.2)  # 1.2 meters
+        
+        # Set constant speed mode
+        success = await client.set_constant_speed(2500)  # 2500 RPM
+        
+        # Set constant flow mode
+        success = await client.set_constant_flow(2.0)  # 2.0 m³/h
+        
+        # Set AutoAdapt Radiator mode
+        success = await client.set_autoadapt_radiator(3.0)  # 3.0 meters
+        
+        # Set AutoAdapt Underfloor mode
+        success = await client.set_autoadapt_underfloor(2.5)  # 2.5 meters
+        
+        # Set AutoAdapt Radiator+Underfloor combined mode
+        success = await client.set_autoadapt_combined(3.5)  # 3.5 meters
+        
+        # Validate a setpoint before setting
+        is_valid, error = await client.validate_setpoint(
+            value=9804.0,  # Pascals for pressure modes
+            control_mode=0,  # Constant Pressure
+            strict=True
+        )
+        if not is_valid:
+            print(f"Invalid setpoint: {error}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+**Schedule Management:**
+```python
+import asyncio
+from alpha_hwr import AlphaHWRClient
+from alpha_hwr.models import ScheduleEntry
+
+async def main():
+    async with AlphaHWRClient("DEVICE_UUID") as client:
+        await client.pair_device()
+        
+        # Enable the schedule
+        await client.set_schedule_enabled(True)
+        
+        # Set a schedule entry for Monday 06:00-08:30
+        success = await client.set_schedule_entry(
+            day="monday",
+            begin_hour=6,
+            begin_minute=0,
+            end_hour=8,
+            end_minute=30,
+            layer=0  # Layer 0-4 (supports 5 independent schedules)
+        )
+        
+        # Set multiple entries at once
+        entries = [
+            ScheduleEntry(day="monday", begin_hour=6, begin_minute=0, 
+                         end_hour=8, end_minute=30, layer=0),
+            ScheduleEntry(day="tuesday", begin_hour=18, begin_minute=0,
+                         end_hour=22, end_minute=0, layer=0),
+        ]
+        await client.set_weekly_schedule(entries, layer=0)
+        
+        # Read current schedule
+        schedule = await client.read_weekly_schedule(layer=0)
+        for entry in schedule:
+            print(f"{entry.day}: {entry.begin_hour:02d}:{entry.begin_minute:02d} - "
+                  f"{entry.end_hour:02d}:{entry.end_minute:02d}")
+        
+        # Clear a specific day
+        await client.clear_schedule_entry("wednesday", layer=0)
+        
+        # Clear entire layer
+        await client.clear_schedule_layer(layer=0)
+        
+        # Export schedule to JSON
+        await client.export_schedule_json("schedule_backup.json")
+        
+        # Import schedule from JSON
+        import json
+        with open("schedule_backup.json", "r") as f:
+            schedule_data = json.load(f)
+        # ... process and set schedule
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+**Configuration Backup & Restore:**
+```python
+import asyncio
+from alpha_hwr import AlphaHWRClient
+
+async def main():
+    async with AlphaHWRClient("DEVICE_UUID") as client:
+        await client.pair_device()
+        
+        # Backup configuration
+        success = await client.backup_configuration("pump_backup.json")
+        if success:
+            print("Configuration backed up successfully")
+        
+        # Restore configuration
+        success = await client.restore_configuration("pump_backup.json")
+        if success:
+            print("Configuration restored successfully")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Supported Features
+
+### Control Modes
+
+The ALPHA HWR supports **8 out of 32 GENI protocol control modes** (25%), specifically those needed for residential heating applications:
+
+| Mode | Name | Status | Setpoint Range |
+|------|------|--------|----------------|
+| 0 | Constant Pressure |  Fully Supported | 0.0 - 6.0 m |
+| 1 | Proportional Pressure |  Fully Supported | 0.0 - 6.0 m |
+| 2 | Constant Speed |  Fully Supported | 1000 - 4200 RPM |
+| 8 | Constant Flow |  Fully Supported | 0.0 - 4.5 m³/h |
+| 5 | AutoAdapt (Generic) |  Limited Support | 0.0 - 6.0 m (see docs) |
+| 13 | AutoAdapt Radiator |  Fully Supported | 0.0 - 6.0 m |
+| 14 | AutoAdapt Underfloor |  Fully Supported | 0.0 - 6.0 m |
+| 15 | AutoAdapt Radiator+Underfloor |  Fully Supported | 0.0 - 6.0 m |
+
+**Unsupported Modes (24 total):** Chemical dosing (16-19), level control (9, 22), differential pressure (11, 12, 26), CEOPS/industrial modes (7, 10, 20-21, 23-25, 27-30, 128). See [Control Modes Matrix](https://eman.github.io/alpha-hwr/protocol/control_modes/) for details.
+
+### Advanced Features
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Real-time Telemetry | Supported | Flow, head, power, temp, voltage, current, RPM |
+| Setpoint Limits | Supported | Min/max/default from factory config |
+| Setpoint Validation | Supported | Automatic validation before writes |
+| Alarm/Warning System | Supported | Current state only (98+ error codes) |
+| Operating Statistics | Supported | Operating hours, start count |
+| Weekly Schedules | Supported | 5 independent layers, full CRUD |
+| Schedule Import/Export | Supported | JSON format |
+| Config Backup/Restore | Supported | Full configuration backup |
+| Historical Data | Supported | 100-cycle history for flow, head, temp, power |
+| Event Log | Supported | Last 20 pump events with timestamps and modes |
+| Multi-pump (CEOPS) | Not Available | Residential pump only |
+| Cumulative Energy (kWh) | Not Available | Instantaneous power available |
+
+## Documentation
+
+Complete documentation is available at [https://eman.github.io/alpha-hwr/](https://eman.github.io/alpha-hwr/).
+
+*   [**Getting Started**](https://eman.github.io/alpha-hwr/getting_started/installation/)
+*   [**CLI Guide**](https://eman.github.io/alpha-hwr/guides/cli_guide/)
+*   [**API Reference**](https://eman.github.io/alpha-hwr/api/client/)
+*   [**Protocol Details**](https://eman.github.io/alpha-hwr/protocol/ble_architecture/)
+
+## Project Status
+
+**Status:** Production-ready for ALPHA HWR series.
+
+**Test Coverage:** 204 passing tests, 100% of hardware features tested on real ALPHA HWR pump.
+
+**Key Features Implemented:**
+- Real-time telemetry (Flow, Head, Power, Temp, Electrical)
+- Full motor control (Start/Stop, Mode switching)
+- Advanced setpoint management with validation
+- Comprehensive weekly schedule management (5 layers)
+- Configuration backup and restore
+- Detailed device information (Serial, Firmware)
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+- All tests pass (`tox`)
+- Code follows project style (ruff, mypy, basedpyright)
+- New features include tests and documentation
+
+## License
+
+See LICENSE file for details.