eman · eman · May 15, 2026 · May 15, 2026 · May 15, 2026 · May 15, 2026
diff --git a/.gitignore b/.gitignore
@@ -51,3 +51,4 @@ traffic_db
 site
 tox_output.log
 tools
+.obsidian
diff --git a/docs/TESTING_STRATEGY.md b/docs/TESTING_STRATEGY.md
@@ -2,7 +2,7 @@
 
 ## Overview
 
-This document outlines the testing strategy for the alpha-hwr library, covering reliability, maintainability, and serving as a reference for other language implementations.
+This document describes the testing strategy for the alpha-hwr library, designed to ensure reliability and maintainability, and to serve as a reference for other language implementations.
 
 ## Testing Pyramid
 
@@ -261,7 +261,7 @@ tests/
 │
 └── fixtures/
     ├── conftest.py              # Pytest fixtures
-    ├── sample_packets.py        # Real packet captures
+    ├── sample_packets.py        # Protocol sample data
     └── test_vectors.py          # Protocol test vectors
 ```
 
@@ -284,8 +284,8 @@ tests/
 
 ## Test Data & Fixtures
 
-### Real Packet Captures
-Store real packet captures for validation:
+### Protocol Sample Data
+Store known-good protocol frames for validation:
 
 ```python
 # tests/fixtures/sample_packets.py

diff --git a/docs/api/constants.md b/docs/api/constants.md
@@ -69,7 +69,7 @@ Addresses for Legacy Class 3 Register Polling.
 
 ## ERROR_CODES (Dictionary)
 
-A lookup table mapping error codes to human-readable descriptions. Extracted from the GENI profile.
+A lookup table mapping error codes to human-readable descriptions. Defined in the GENI profile.
 
 ```python
 from alpha_hwr.constants import ERROR_CODES

diff --git a/docs/guides/control_modes.md b/docs/guides/control_modes.md
@@ -1,6 +1,6 @@
 # Control Modes and Setpoints
 
-This guide covers the ALPHA HWR's control modes and setpoint configuration.
+This guide provides details on the ALPHA HWR's control modes and setpoint configuration.
 
 ## Overview
 

diff --git a/docs/guides/historical_data.md b/docs/guides/historical_data.md
@@ -16,7 +16,7 @@ Unlike basic telemetry which is real-time, historical data allows you to analyze
 
 ## Historical Trends (Object 53)
 
-The pump maintains two resolutions of trend data for key metrics:
+The pump maintains two resolutions of trend data:
 1. **High Resolution**: Last 10 cycles.
 2. **Standard Resolution**: Last 100 cycles.
 

diff --git a/docs/guides/time_management.md b/docs/guides/time_management.md
@@ -6,7 +6,7 @@ The Grundfos ALPHA HWR pump maintains an internal real-time clock (RTC) used for
 
 The pump's timekeeping is managed via GENI DataObjects (Class 10). While older protocols used simple Unix timestamps (Class 14/16), modern firmware relies on **Object 94**, which provides a structured date and time representation (Year, Month, Day, Hour, Minute, Second, etc.).
 
-### Key Objects
+### Objects
 
 | Object | SubID | Name | Description |
 | :--- | :--- | :--- | :--- |

diff --git a/docs/guides/understanding_telemetry.md b/docs/guides/understanding_telemetry.md
@@ -1,6 +1,6 @@
 # Understanding Pump Telemetry
 
-This guide explains the key metrics reported by the ALPHA HWR pump and how to interpret them for optimal system performance.
+This guide explains the metrics reported by the ALPHA HWR pump and how to interpret them for optimal system performance.
 
 ## Core Metrics
 

diff --git a/docs/integrations/esphome.md b/docs/integrations/esphome.md
@@ -120,7 +120,7 @@ async def to_code(config):
 
 ### 2. Protocol Constants (`alpha_hwr.h`)
 
-Key sections of the header file:
+Sections of the header file:
 
 ```cpp
 #pragma once

diff --git a/docs/protocol/architecture.md b/docs/protocol/architecture.md
@@ -107,7 +107,7 @@ stateDiagram-v2
 
 ## 6. Layer Responsibilities
 
-| Layer | Responsibility | Key Components |
+| Layer | Responsibility | Components |
 | :--- | :--- | :--- |
 | **Application** | User Interface | CLI, Scripts |
 | **Client** | Unified API | `AlphaHWRClient` |

diff --git a/docs/protocol/autoadapt_modes.md b/docs/protocol/autoadapt_modes.md
@@ -177,12 +177,9 @@ alpha-hwr control set-autoadapt-combined --value 3.5
 
 ## Testing Methodology
 
-### Hardware Probing
+### Test Commands
 
 ```bash
-# Probe for configuration SubIDs
-python probe_autoadapt_config.py <DEVICE_ADDRESS>
-
 # Test mode switching
 python test_mode_support.py <DEVICE_ADDRESS>
 

diff --git a/docs/protocol/ble_architecture.md b/docs/protocol/ble_architecture.md
@@ -200,7 +200,7 @@ ObjID: 16-bit identifier (big-endian)
 
 ### Object IDs and SubIDs
 
-**Key Objects:**
+**Objects:**
 
 | Object | SubID Range | Type | Purpose |
 | :--- | :--- | :--- | :--- |
@@ -450,7 +450,7 @@ The ALPHA HWR BLE architecture uses:
 3. **GENI protocol** for operations (Class 10 DataObjects)
 4. **Schedule layers** for application logic (5 independent SubIDs)
 
-**Key Takeaways:**
+**Summary:**
 
 - Schedule layers are **SubIDs within Object 84**, not separate BLE characteristics
 - Multi-chunk splitting is **critical** for packets >20 bytes

diff --git a/docs/protocol/control_modes.md b/docs/protocol/control_modes.md
@@ -1,6 +1,6 @@
 # Control Modes - Complete Support Matrix
 
-This document covers all 32 control modes defined in the GENI protocol and their support status on the Grundfos ALPHA HWR pump.
+This document provides an overview of all 32 control modes defined in the GENI protocol and their support status on the Grundfos ALPHA HWR pump.
 
 ## Executive Summary
 
@@ -184,7 +184,6 @@ alpha-hwr control set-temperature --min 35 --max 39
 **Hardware Support:**
 -   Mode switching works reliably (mode byte 0x19, suffix 0x38 0xC6 0x70 0x00)
 -   Successfully operates on ALPHA HWR hardware
--   Exposed in Grundfos GO mobile app
 -   Supports configurable ON/OFF durations (1-60 minutes)
 
 **Implementation:**
@@ -318,7 +317,7 @@ These methods still exist in the service layer for GENI protocol compatibility b
 ### For Developers
 
 1. **No Further Investigation Needed:** All GENI protocol modes have been verified for ALPHA HWR compatibility.
-2. **Mode 25 Protocol:** See issue #14 for ongoing work to reverse engineer cycle time parameter protocol.
+2. **Mode 25 Protocol:** See issue #14 for ongoing work to document the cycle time parameter protocol.
 3. **Documentation Complete:** Support matrix is fully documented for the 5 ALPHA HWR modes.
 
 ---

diff --git a/docs/protocol/packet_traces/06_alarms_warnings.md b/docs/protocol/packet_traces/06_alarms_warnings.md
@@ -196,7 +196,7 @@ All these OpSpecs use the 7-byte header before data:
 [OpSpec] [Seq-H] [Seq-L] [ID-H] [ID-L] [Res-H] [Res-L] [DataLen] [Data...]
 ```
 
-The key difference is that OpSpec 0x09 contains **uint16 codes** rather than **IEEE 754 floats**.
+The main difference is that OpSpec 0x09 contains **uint16 codes** rather than **IEEE 754 floats**.
 
 ## Integration Notes
 
@@ -235,13 +235,13 @@ text_sensor:
 
 ### Initial Confusion (Now Resolved)
 
-Early Python implementations incorrectly expected **OpSpec 0x13** for alarm responses. This was based on speculation before hardware validation.
+Early Python implementations incorrectly expected **OpSpec 0x13** for alarm responses. This was based on speculation before testing against actual hardware.
 
-**Hardware validation (ESPHome, Feb 2025)** confirmed that the pump actually responds with **OpSpec 0x09**, using the standard Active Query Response format.
+**Testing** confirmed that the pump actually responds with **OpSpec 0x09**, using the standard Active Query Response format.
 
-### Key Discovery
+### Discovery
 
-The breakthrough came from analyzing 100+ real packet captures showing consistent OpSpec 0x09 responses with data value `0x0000`, which was initially misinterpreted as "not supported." In reality, `0x0000` simply means "no active alarms."
+Testing against real hardware revealed consistent OpSpec 0x09 responses with data value `0x0000`, which was initially misinterpreted as "not supported." In reality, `0x0000` simply means "no active alarms."
 
 ## References
 
@@ -254,7 +254,7 @@ The breakthrough came from analyzing 100+ real packet captures showing consisten
 
 This documentation is based on:
 
-- 100+ real packet captures from ALPHA HWR pump (Feb 2025)
+- Real-world testing with an ALPHA HWR pump
 - Successful ESPHome C++ implementation (tested on ESP32-C3)
 - Cross-validation between Python and ESPHome implementations
 - Protocol documentation at https://eman.github.io/alpha-hwr/reimplementation/
diff --git a/docs/protocol/schedules.md b/docs/protocol/schedules.md
@@ -23,7 +23,7 @@ The ALPHA HWR supports **5 independent schedule layers** that allow complex sche
 - **Layer 3 (SubID 1003)**: Seasonal/temporary adjustments
 - **Layer 4 (SubID 1004)**: Special events or overrides
 
-**Key Features:**
+**Features:**
 - Each layer contains a full 7-day schedule (42 bytes)
 - Layers can have **overlapping time windows** (e.g., Layer 0 and Layer 1 both active on Monday)
 - The pump operates whenever **any layer** is active
@@ -118,7 +118,7 @@ await client.delete_schedule()
 ## Unsupported Features
 
 ### Alternative Schedules
-Traffic analysis and hardware probing confirmed that "Alternative Schedule" slots (typically associated with SubIDs 1100+) are **not supported** on this firmware version. The `ClockProgramOverview` (Obj 84, Sub 1) reports `max_nof_alternative_events_per_day = 0`.
+Testing confirmed that "Alternative Schedule" slots (typically associated with SubIDs 1100+) are **not supported** on this firmware version. The `ClockProgramOverview` (Obj 84, Sub 1) reports `max_nof_alternative_events_per_day = 0`.
 
 ## Python Implementation
 
@@ -220,7 +220,7 @@ Different schedule operations require different OpSpec codes:
 - `0x93` = `(4 << 5) | 19` = OpSpec 4, Length 19
 - `0xB3` = `(5 << 5) | 19` = OpSpec 5, Length 19
 
-**Key Differences:**
+**Differences:**
 - **OpSpec 0x93**: Used for enable/disable (Type 218 ClockProgramOverview, 10 bytes)
 - **OpSpec 0xB3**: Used for schedule writes (Type 222 ClockProgramWeekDayInterval, 42 bytes)
 - The OpSpec determines which structure type the pump expects
@@ -613,7 +613,7 @@ alpha-hwr schedule
 
 ## Schedule Validation
 
-The library validates schedule entries to prevent conflicts and errors.
+The library includes validation for schedule entries to prevent conflicts and errors.
 
 ### ScheduleEntry Model
 

diff --git a/docs/protocol/telemetry.md b/docs/protocol/telemetry.md
@@ -151,7 +151,7 @@ Older firmware or specific integration scenarios might require active polling in
 * **Command**: `READ` (OpCode `0x03`)
 * **Frame Start**: `0x27` (Request)
 
-### Key Registers
+### Registers
 
 | Register Address | Name | Data Contained |
 | :--- | :--- | :--- |

diff --git a/docs/reference/data_models.md b/docs/reference/data_models.md
@@ -154,7 +154,7 @@ if alarms:
 
 ## ScheduleEntry Model
 
-The `ScheduleEntry` class represents a single schedule time window. All fields are validated on construction.
+The `ScheduleEntry` class represents a single schedule time window with built-in validation.
 
 ### Properties
 
@@ -179,7 +179,7 @@ The `ScheduleEntry` class represents a single schedule time window. All fields a
 | `begin_time_obj` | `datetime.time` | Begin time as time object |
 | `end_time_obj` | `datetime.time` | End time as time object |
 
-### Key Methods
+### Methods
 
 #### Duration and Validation
 

diff --git a/docs/reimplementation/README.md b/docs/reimplementation/README.md
@@ -33,7 +33,7 @@ The ALPHA HWR pump uses the GENI protocol over Bluetooth Low Energy (BLE). This
 
 - Grundfos ALPHA HWR pump (any variant)
 - BLE-capable computer or device
-- BLE debugging tools (nRF Connect, Wireshark with BTLE, etc.)
+- BLE debugging tools (nRF Connect, LightBlue, etc.)
 
 ## Implementation Approach
 
@@ -116,7 +116,7 @@ graph TD
 ```
 
 
-### Key Concepts
+### Concepts
 
 #### 1. Authentication
 The pump requires a specific sequence of "magic packets" to unlock:

diff --git a/docs/reimplementation/architecture.md b/docs/reimplementation/architecture.md
@@ -25,7 +25,7 @@ graph TD
 - `session.py` - Connection state machine
 - `transport.py` - BLE send/receive abstraction
 
-**Key Responsibilities**:
+**Responsibilities**:
 - Manage BLE connection lifecycle
 - Execute authentication sequence
 - Handle packet transmission/reception
@@ -40,7 +40,7 @@ graph TD
 - `frame_parser.py` - Parse GENI frames
 - `telemetry_decoder.py` - Decode telemetry payloads
 
-**Key Responsibilities**:
+**Responsibilities**:
 - Build valid GENI protocol packets
 - Parse received packets
 - Calculate CRC checksums
@@ -56,7 +56,7 @@ graph TD
 - `schedule.py` - Schedule management
 - `configuration.py` - Backup/restore
 
-**Key Responsibilities**:
+**Responsibilities**:
 - Expose high-level operations
 - Handle complex multi-step workflows
 - Validate inputs
@@ -67,7 +67,7 @@ graph TD
 
 **File**: `client.py`
 
-**Key Responsibilities**:
+**Responsibilities**:
 - Single entry point for applications
 - Manage service lifecycles
 - Handle connection/disconnection
@@ -187,7 +187,7 @@ stateDiagram-v2
 - **RECEIVING**: Processing notification
 - **ERROR**: Communication failure
 
-## Key Design Patterns
+## Design Patterns
 
 ### 1. Layered Architecture
 Each layer has clear boundaries and responsibilities. Upper layers depend only on adjacent lower layers.

diff --git a/docs/reimplementation/checklist.md b/docs/reimplementation/checklist.md
@@ -248,7 +248,7 @@ Your implementation is considered **complete** when:
 - [x] Documentation complete
 
 Your implementation is considered **production-ready** when:
-- [x] Error handling robust
+- [x] Error handling complete
 - [x] Performance optimized
 - [x] Security reviewed
 - [x] Cross-platform tested

diff --git a/docs/reimplementation/common_pitfalls.md b/docs/reimplementation/common_pitfalls.md
@@ -177,7 +177,7 @@ class Transport:
                 self._response_buffer.clear()
 ```
 
-**Key Points:**
+**Notes:**
 - Frame start: `0x24` (response) or `0x27` (request)
 - Expected length: `packet[1] + 4` (length field + start byte + length byte + 2-byte CRC)
 - Buffer fragments until complete
@@ -457,7 +457,7 @@ Decoded floats from offset 13:
   [5] 0x45653AD0 = 3667.7 RPM (speed)
 ```
 
-**Key Differences:**
+**Differences:**
 | Aspect | Passive Notification (0x0E) | Register-Read Response (0x30/0x2b) |
 |--------|---------------------------|----------------------------------|
 | **OpSpec** | 0x0E | 0x30, 0x2b, 0x14, etc |
@@ -635,7 +635,7 @@ def parse_frame(data):
         raise InvalidFrame()
 ```
 
-**Key:**
+**Legend:**
 - `0x27` = Request (from client to pump)
 - `0x24` = Response (from pump to client)
 
@@ -899,8 +899,6 @@ assert session.is_authenticated()
 ### Use BLE Debugging Tools
 
 - **nRF Connect** - Monitor BLE traffic
-- **Wireshark** - Capture BLE packets
-- **Logic Analyzer** - Hardware-level debugging
 
 ---
-Original file line number
+Diff line change
@@ Expand Up / @@ -51,3 +51,4 @@ traffic_db @@
     site
     tox_output.log
     tools
+    .obsidian