grundfos-ble 0.1.0__tar.gz

grundfos_ble-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Nix
+result
+.direnv/
+
+# Editors
+.idea/
+.vscode/
+*.swp
+
+# Local environments and secrets
+.venv-*/
+.env
+.env.*
+.envrc
+
+# macOS
+.DS_Store

grundfos_ble-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-11-09
+
+### Added
+
+- GENIbus framing: telegrams, APDUs, CRC-16/CCITT, reassembly of notification-sized pieces,
+  classic classes 2/3/4/5/7 (GET, SET, INFO, strings, the Grundfos unit table) and class-10
+  data objects (GET, SET, headers, float/integer fields with the "not available" and NaN
+  sentinels).
+- Advertisement parser for the 0xFE5D service data, including the Bluetooth-button flag that
+  marks the pairing window.
+- ALPHA2 GO profile: process values, motor state, operation state, per-mode setpoints and
+  factory limits, panel setting and presets, flow limiters, AutoNight, proportional-pressure
+  curve, alarms and warnings, statistics, temperatures and energy, each entry tagged with how
+  it was verified and where it comes from.
+- `BleTransport` on bleak 3 and bleak-retry-connector 4: pairs on every connection, chunked
+  writes, one request in flight. `PairingRequired` means the pump refused pairing (SMP reason 82),
+  and `reply_seen` tells a silent link from an answered one. Only ESPHome proxies have been tested.
+- `GrundfosPump`: typed reads and capability probing with raw-frame capture. This is a read-only
+  release: the write methods raise `NotSupported`, and no write has ever been sent to a real pump.
+- `grundfos_ble.testing`: a replay transport, a fixture format for recorded frames, and the
+  recorded ALPHA2 GO frames as `FIXTURES`.
+
+[0.1.0]: https://github.com/83noit/grundfos-ble/releases/tag/v0.1.0

grundfos_ble-0.1.0/LICENSE

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

grundfos_ble-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.5
+Name: grundfos-ble
+Version: 0.1.0
+Summary: Async Python library for Grundfos circulator pumps over GENIbus-on-Bluetooth LE (ALPHA2 GO first)
+Project-URL: Homepage, https://github.com/83noit/grundfos-ble
+Project-URL: Repository, https://github.com/83noit/grundfos-ble
+Project-URL: Issues, https://github.com/83noit/grundfos-ble/issues
+Project-URL: Changelog, https://github.com/83noit/grundfos-ble/blob/main/CHANGELOG.md
+Author: 83noit
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alpha2,ble,bluetooth,genibus,grundfos,home-assistant,pump
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: bleak-retry-connector<5,>=4.0
+Requires-Dist: bleak<4,>=3.0
+Description-Content-Type: text/markdown
+
+# grundfos-ble
+
+Async, typed Python library for Grundfos circulator pumps that speak **GENIbus over
+Bluetooth LE**. The only supported pump today is the **ALPHA2 GO**. The framing layer is
+transport-agnostic and the pump profile is data, which should make related Grundfos Bluetooth
+pumps (ALPHA3, ALPHA HWR, SCALA1) easier to add, but none of them is supported yet.
+
+**This is a preliminary, read-only release.** It reads a pump's state and values. Writing to a
+pump is not supported yet.
+
+The library was written for use under Home Assistant, but it does not depend on it.
+
+This project is not affiliated with, endorsed by or supported by Grundfos. Product names are
+used only to identify compatible pumps.
+
+## What it does
+
+- Decodes the pump's advertisement (service UUID `0xFE5D`), including the flag that says the
+  Bluetooth button was just pressed.
+- Connects through bleak and bleak-retry-connector, pairs on every connection, and talks GENIbus
+  over the single GENI characteristic. Only ESPHome Bluetooth proxies have been tested. Other
+  bleak backends may connect, but BlueZ and WinRT pairing failures are not recognised as
+  `PairingRequired` and surface as `GrundfosConnectionError`.
+- Reads flow, head, power, voltage, current, speed, electronics temperature, control and
+  operation mode, setpoint, factory limits, the panel setting, flow limiters, AutoNight, alarms,
+  warnings and, where the pump has them, statistics, temperatures and energy. The stored panel
+  presets have no typed reader. Fetch them with `GrundfosPump.get_object` and
+  `registry.alpha2go.panel_preset`.
+- Does **not** support writes yet. The write methods (control mode, setpoint, limiters, AutoNight,
+  start/stop, alarm reset) raise `NotSupported`. See [Known limitations](#known-limitations).
+
+## Install
+
+```sh
+pip install grundfos-ble
+```
+
+Python 3.13 or newer; depends on `bleak>=3` and `bleak-retry-connector>=4`.
+
+## Usage
+
+```python
+import asyncio
+
+from bleak import BleakScanner
+
+from grundfos_ble import BleTransport, GrundfosPump, PairingRequired
+
+
+async def main() -> None:
+    device = await BleakScanner.find_device_by_address("AA:BB:CC:DD:EE:FF")
+    if device is None:
+        raise SystemExit("Pump not found")
+
+    transport = BleTransport(device, name="My pump")
+    pump = GrundfosPump(transport)
+
+    try:
+        await transport.connect()  # pairs (encrypts) every time
+    except PairingRequired:
+        print("Press the pump's Bluetooth button and connect again within 3 seconds")
+        raise
+
+    try:
+        identity = await pump.read_identity()
+        values = await pump.read_measurements()
+        print(identity.model, values.flow_m3h, "m³/h", values.head_m, "m", values.power_w, "W")
+    finally:
+        await transport.disconnect()
+
+
+asyncio.run(main())
+```
+
+The library never scans; you hand it a `BLEDevice`. Under Home Assistant that device comes
+from the Bluetooth integration and HA chooses the proxy.
+
+## Pairing, in one paragraph
+
+The pump drops any link that is not encrypted within about two seconds, and accepts pairing
+only for about three seconds after its Bluetooth button is pressed. Once paired, the bond lives
+on the adapter or proxy that paired. When tested, the pump held at least two bonds at once, a
+phone and an ESPHome proxy. Every connection must still call `pair()`; with a bond that is a quick
+re-encrypt. `PairingRequired` is raised when the pump refuses pairing (ESP-IDF reason 82, seen
+through ESPHome proxies). A link that connects but never answers shows up as `reply_seen` staying
+false. A pump losing a bond has never been observed, so how that looks is unknown.
+
+## Protocol
+
+GENIbus telegram `SD LEN DA SA APDU… CRC16` (CRC-16/CCITT, init 0xFFFF, inverted), requests
+`27 … E7 F8`, replies `24 … F8 E7`, frames written in 20-byte pieces. Most values live in
+class-10 "data objects" addressed by `(id, sub-id)` whose replies carry a
+`status type version size` header and big-endian floats. See [docs/protocol.md](https://github.com/83noit/grundfos-ble/blob/main/docs/protocol.md)
+for the full inventory with the provenance of every item.
+
+## Known limitations
+
+**Writing to a pump is not supported yet.** The write methods raise `NotSupported`, and this
+project has never sent a write to a pump. The encoders behind them are tested against frames
+captured from the Grundfos GO app, and that is all. Before writes can be enabled, at least these
+need fixing:
+
+- `set_flow_limiter` does not check the limit against the pump's range, so it accepts 0, negative,
+  NaN and huge values. A near-zero maximum flow could starve a circuit of circulation.
+- `set_setpoint` skips its range check when the factory limits are not available.
+- `Access` and `MODES_SEEN_ON_ALPHA2_GO` are not enforced, so objects whose meaning is unknown
+  could be written.
+- `set_setpoint` writes the control mode first. If the second write fails, the mode has changed
+  and the error does not say so. The read-back is returned but not compared, and the pump clamps
+  silently.
+- Read-modify-write rebuilds objects instead of patching the raw bytes, and does not refuse a
+  different object version or size.
+- Cancelling mid-write can leave part of a SET at the pump.
+
+Reads have limitations too:
+
+- The object version is not checked, so a firmware that changes a layout under the same type
+  would decode into wrong values.
+- The advertisement parser checks only the length, not the `03 01 00` prefix.
+
+## Development
+
+```sh
+nix develop          # or: uv sync --group dev && source .venv/bin/activate
+ruff check . && ruff format --check .
+mypy
+pytest --cov
+```
+
+Measurements, operation state, statistics and the other optional objects are tested against frames
+recorded from a real ALPHA2 GO (`src/grundfos_ble/testdata/`, available to dependants as
+`grundfos_ble.testing.FIXTURES`). Identity and string reads are tested only on hand-built or ALPHA
+HWR frames, and the Bluetooth connection (`establish_connection`) is always mocked. Add new captures
+in the same format (`>` request, `<` notification pieces) rather than hand-built frames.
+
+## Status
+
+Alpha, read-only. Process and motor values were checked against the panel of one ALPHA2 GO. That pump also
+answered the operation state, panel setting, flow limiters, AutoNight, alarms, warnings, statistics,
+temperatures and energy with plausible values, with no fault active. The remaining objects come from
+captured traffic or documentation for related pumps. Other pump families are unverified.
+
+## Acknowledgements
+
+This library was written from the GENIbus specification and from frames captured on real pumps.
+No code from these projects is used, but their published protocol research made the work possible:
+
+- [esphome-alpha2go](https://github.com/Birkemosen/esphome-alpha2go) (GPL-3.0): ALPHA2 GO traffic captures and object layouts
+- [alpha-hwr](https://eman.github.io/alpha-hwr/) (MIT): ALPHA HWR protocol documentation
+- [gofree](https://github.com/tatutsa888/gofree) (MIT): SCALA1 protocol documentation
+- [esphome-grundfos-alpha3](https://github.com/Seba65439/esphome-grundfos-alpha3) (MIT): ALPHA3 decoders
+
+## Licence
+
+MIT. See the `LICENSE` file.

grundfos_ble-0.1.0/README.md

@@ -0,0 +1,155 @@
+# grundfos-ble
+
+Async, typed Python library for Grundfos circulator pumps that speak **GENIbus over
+Bluetooth LE**. The only supported pump today is the **ALPHA2 GO**. The framing layer is
+transport-agnostic and the pump profile is data, which should make related Grundfos Bluetooth
+pumps (ALPHA3, ALPHA HWR, SCALA1) easier to add, but none of them is supported yet.
+
+**This is a preliminary, read-only release.** It reads a pump's state and values. Writing to a
+pump is not supported yet.
+
+The library was written for use under Home Assistant, but it does not depend on it.
+
+This project is not affiliated with, endorsed by or supported by Grundfos. Product names are
+used only to identify compatible pumps.
+
+## What it does
+
+- Decodes the pump's advertisement (service UUID `0xFE5D`), including the flag that says the
+  Bluetooth button was just pressed.
+- Connects through bleak and bleak-retry-connector, pairs on every connection, and talks GENIbus
+  over the single GENI characteristic. Only ESPHome Bluetooth proxies have been tested. Other
+  bleak backends may connect, but BlueZ and WinRT pairing failures are not recognised as
+  `PairingRequired` and surface as `GrundfosConnectionError`.
+- Reads flow, head, power, voltage, current, speed, electronics temperature, control and
+  operation mode, setpoint, factory limits, the panel setting, flow limiters, AutoNight, alarms,
+  warnings and, where the pump has them, statistics, temperatures and energy. The stored panel
+  presets have no typed reader. Fetch them with `GrundfosPump.get_object` and
+  `registry.alpha2go.panel_preset`.
+- Does **not** support writes yet. The write methods (control mode, setpoint, limiters, AutoNight,
+  start/stop, alarm reset) raise `NotSupported`. See [Known limitations](#known-limitations).
+
+## Install
+
+```sh
+pip install grundfos-ble
+```
+
+Python 3.13 or newer; depends on `bleak>=3` and `bleak-retry-connector>=4`.
+
+## Usage
+
+```python
+import asyncio
+
+from bleak import BleakScanner
+
+from grundfos_ble import BleTransport, GrundfosPump, PairingRequired
+
+
+async def main() -> None:
+    device = await BleakScanner.find_device_by_address("AA:BB:CC:DD:EE:FF")
+    if device is None:
+        raise SystemExit("Pump not found")
+
+    transport = BleTransport(device, name="My pump")
+    pump = GrundfosPump(transport)
+
+    try:
+        await transport.connect()  # pairs (encrypts) every time
+    except PairingRequired:
+        print("Press the pump's Bluetooth button and connect again within 3 seconds")
+        raise
+
+    try:
+        identity = await pump.read_identity()
+        values = await pump.read_measurements()
+        print(identity.model, values.flow_m3h, "m³/h", values.head_m, "m", values.power_w, "W")
+    finally:
+        await transport.disconnect()
+
+
+asyncio.run(main())
+```
+
+The library never scans; you hand it a `BLEDevice`. Under Home Assistant that device comes
+from the Bluetooth integration and HA chooses the proxy.
+
+## Pairing, in one paragraph
+
+The pump drops any link that is not encrypted within about two seconds, and accepts pairing
+only for about three seconds after its Bluetooth button is pressed. Once paired, the bond lives
+on the adapter or proxy that paired. When tested, the pump held at least two bonds at once, a
+phone and an ESPHome proxy. Every connection must still call `pair()`; with a bond that is a quick
+re-encrypt. `PairingRequired` is raised when the pump refuses pairing (ESP-IDF reason 82, seen
+through ESPHome proxies). A link that connects but never answers shows up as `reply_seen` staying
+false. A pump losing a bond has never been observed, so how that looks is unknown.
+
+## Protocol
+
+GENIbus telegram `SD LEN DA SA APDU… CRC16` (CRC-16/CCITT, init 0xFFFF, inverted), requests
+`27 … E7 F8`, replies `24 … F8 E7`, frames written in 20-byte pieces. Most values live in
+class-10 "data objects" addressed by `(id, sub-id)` whose replies carry a
+`status type version size` header and big-endian floats. See [docs/protocol.md](https://github.com/83noit/grundfos-ble/blob/main/docs/protocol.md)
+for the full inventory with the provenance of every item.
+
+## Known limitations
+
+**Writing to a pump is not supported yet.** The write methods raise `NotSupported`, and this
+project has never sent a write to a pump. The encoders behind them are tested against frames
+captured from the Grundfos GO app, and that is all. Before writes can be enabled, at least these
+need fixing:
+
+- `set_flow_limiter` does not check the limit against the pump's range, so it accepts 0, negative,
+  NaN and huge values. A near-zero maximum flow could starve a circuit of circulation.
+- `set_setpoint` skips its range check when the factory limits are not available.
+- `Access` and `MODES_SEEN_ON_ALPHA2_GO` are not enforced, so objects whose meaning is unknown
+  could be written.
+- `set_setpoint` writes the control mode first. If the second write fails, the mode has changed
+  and the error does not say so. The read-back is returned but not compared, and the pump clamps
+  silently.
+- Read-modify-write rebuilds objects instead of patching the raw bytes, and does not refuse a
+  different object version or size.
+- Cancelling mid-write can leave part of a SET at the pump.
+
+Reads have limitations too:
+
+- The object version is not checked, so a firmware that changes a layout under the same type
+  would decode into wrong values.
+- The advertisement parser checks only the length, not the `03 01 00` prefix.
+
+## Development
+
+```sh
+nix develop          # or: uv sync --group dev && source .venv/bin/activate
+ruff check . && ruff format --check .
+mypy
+pytest --cov
+```
+
+Measurements, operation state, statistics and the other optional objects are tested against frames
+recorded from a real ALPHA2 GO (`src/grundfos_ble/testdata/`, available to dependants as
+`grundfos_ble.testing.FIXTURES`). Identity and string reads are tested only on hand-built or ALPHA
+HWR frames, and the Bluetooth connection (`establish_connection`) is always mocked. Add new captures
+in the same format (`>` request, `<` notification pieces) rather than hand-built frames.
+
+## Status
+
+Alpha, read-only. Process and motor values were checked against the panel of one ALPHA2 GO. That pump also
+answered the operation state, panel setting, flow limiters, AutoNight, alarms, warnings, statistics,
+temperatures and energy with plausible values, with no fault active. The remaining objects come from
+captured traffic or documentation for related pumps. Other pump families are unverified.
+
+## Acknowledgements
+
+This library was written from the GENIbus specification and from frames captured on real pumps.
+No code from these projects is used, but their published protocol research made the work possible:
+
+- [esphome-alpha2go](https://github.com/Birkemosen/esphome-alpha2go) (GPL-3.0): ALPHA2 GO traffic captures and object layouts
+- [alpha-hwr](https://eman.github.io/alpha-hwr/) (MIT): ALPHA HWR protocol documentation
+- [gofree](https://github.com/tatutsa888/gofree) (MIT): SCALA1 protocol documentation
+- [esphome-grundfos-alpha3](https://github.com/Seba65439/esphome-grundfos-alpha3) (MIT): ALPHA3 decoders
+
+## Licence
+
+MIT. See the `LICENSE` file.

grundfos_ble-0.1.0/docs/protocol.md

@@ -0,0 +1,102 @@
+# GENIbus over Bluetooth LE, as spoken by the Grundfos ALPHA2 GO
+
+What this library implements and how sure we are of each part. "Measured" means read from
+a real ALPHA2 GO by this project and checked against the pump's display or a clock. "Answered"
+means a real ALPHA2 GO returned plausible values with nothing to check them against. "Captured" means
+seen in Grundfos GO app traffic recorded on an ALPHA2 GO 25-90 by the esphome-alpha2go
+author (facts only; that project is GPL and none of its code is used here). "Documented"
+means described for a related pump (ALPHA HWR = family 52 type 7, ALPHA3, SCALA1) and not yet
+confirmed on an ALPHA2 GO. The objects the library reads or writes are defined, with the same
+tags, in `grundfos_ble/registry/alpha2go.py`. The QH coefficients (93/180–184, 93/200) and the
+clock (94/101) are listed here for reference and are not in the registry.
+
+## Transport
+
+| Item | Value | Status |
+|---|---|---|
+| Advertised service UUID | 0xFE5D (Bluetooth SIG member UUID of Grundfos A/S) | measured |
+| Service data | `03 01 00 fam type ver mode flags tail(2)`; `fam type` = 52 6 for the ALPHA2 GO | measured (flags per SCALA1 docs) |
+| Flag bits | 0x10 button pressed (~4 s, pairing window), 0x01 client connected, 0x02 alarm, 0x04 warning, 0x08 LED blinking | 0x10 measured, rest documented |
+| GATT characteristic | `859cffd1-036e-432a-aa28-1a0085b87ba9`, write-without-response + notify | measured |
+| Write size | ≤ 20 bytes per write, whatever the MTU | captured, documented |
+| Reply size | ≤ 20 bytes per notification; reassemble to LEN + 4 | measured |
+| Encryption | mandatory; unencrypted link dropped ~2 s after connect; SMP accepted ~3 s after the button; at least two bonds coexist (proxy and phone) | measured |
+| While a client is connected | the pump stops advertising; the last advert seen had flag 0x08 | measured |
+| Advertising interval | ~8 s, continuous | measured |
+
+## Telegram
+
+```
+SD  LEN  DA  SA  APDU…  CRC-hi CRC-lo
+```
+
+- SD: 0x27 request, 0x26 message (no reply), 0x24 reply, 0x25 error reply.
+- LEN: bytes from DA to the last APDU byte.
+- DA/SA: pump 0xE7, client 0xF8 (requests `27 LL E7 F8`, replies `24 LL F8 E7`); broadcast 0xFF.
+- CRC-16/CCITT, poly 0x1021, init 0xFFFF, result inverted, big-endian, over LEN..last APDU byte.
+- APDU: `class`, `(op << 6) | len`, data (≤ 63 bytes). Request op: 0 GET, 2 SET, 3 INFO.
+  Reply ack: 0 OK, 1 class unknown, 2 ID unknown, 3 illegal operation.
+
+Source: GENIbus Protocol Specification (Grundfos, 2005) for everything in this section;
+measured on the ALPHA2 GO.
+
+## Classic classes
+
+| Class | Use here | Status |
+|---|---|---|
+| 2 measured data | IDs 148/149/150 = unit family/type/version (`34 06 00`) | captured; advert bytes agree (measured) |
+| 3 commands | 2 reset alarm (SCALA1), 5 stop, 6 start, 7 remote, 8 local, 21 constant flow, 22 constant speed, 23 proportional pressure, 24 constant pressure, 25 min, 26 max | captured (5, 6 tested by others), rest documented |
+| 5 reference values | ID 1 `ref_rem` answers 255 = unsupported | captured |
+| 7 ASCII strings | 1 product name, 8 product number, 9 serial, 10 production code, 17 unit name, 19 model, 21 GSC file, 50 software, 58 BLE software, 100 ECU id; reply = NUL-terminated string | captured |
+| INFO | head byte VI/BO/SIF, UNIT/ZERO/RANGE, Grundfos unit table | spec |
+
+## Class-10 data objects
+
+GET: `0A 03 id sub-hi sub-lo` (several refs may be concatenated). Reply data per object:
+`status type(2) version size(3) data(size)`. Replies name the **type**, not the id asked, so
+replies are matched by order. SET: `0A (0x80|len) id sub type(2) version size(3) data`;
+reply `0A 01 status` (0 OK, 2 busy, 4 failed). Floats are big-endian IEEE-754;
+`7F FF FF FF` = not available (and "keep the stored value" in SETs), `FF C0 00 00` = NaN.
+
+| Object | Type | Layout | Status |
+|---|---|---|---|
+| 93/290 process values | 565 v2, 36 B | flow m³/s @0, Δp Pa @4, N/A @8 @12, media °C @16, ΔT @20, flow m³/h @24, head m @28, "kv" @32 | measured (temps N/A on a heating pump) |
+| 87/69 motor state | 256 v3, 41 B | grid V @0, DC-link V @4, A @8, W @12, W @16 (shaft?), rpm @20, NaN @24 @28, electronics °C @32 | measured; @16/@32 meaning unconfirmed |
+| 86/8 realised operation | 303, 7 B | source u8, operation mode u8, control mode u8, setpoint f32 (Pa / rpm / m³/s) | captured; answered on the ALPHA2 GO |
+| 86/6 local request, 86/10 control-mode request (RW) | 303 | same; SET 86/10 as `00 06 mode 7F FF FF FF` | captured |
+| 86/13,15,17,19,21,39 factory limits | 301, 28 B | default, min, max, resulting min, Kp, Ti, Td | captured |
+| 86/14,16,18,20,22,40 user setpoint (RW) | 302, 18 B | feedback id u16, setpoint f32, Kp, Ti, Td; write = read-modify-write | captured (20/22 unverified) |
+| 86/350 panel setting | 868, 1 B | enum 0–20 | captured; answered on the ALPHA2 GO |
+| 86/351–359 panel presets | 869, 5 B | mode u8, setpoint f32 | captured |
+| 86/600, 86/601 flow limiters (RW) | 895, 18 B | id, enabled, limit m³/s, Kp, Ti, Td | captured; answered on the ALPHA2 GO |
+| 86/620, 86/621 limiter ranges | 897, 9 B | id, lower, upper (m³/s) | captured |
+| 90/8 AutoNight (RW) | 333, 1 B | bool | captured; answered on the ALPHA2 GO |
+| 90/4 PP curve | 286, 25 B | quadratic u8, foot point, ?, c0, c1, c2, foot point min | captured |
+| 93/180–184, 93/200 QH coefficients | 1114 / 563 | floats | captured |
+| 88/0 alarms, 88/11 warnings | 570 | uint16 codes, 0-terminated | answered on the ALPHA2 GO (no fault active yet) |
+| 93/1 statistics | 248 v2, 28 B | start count u32, starts 1 h u16, starts 24 h u16, operating time s u32, running time 24 h s u32, last cycle s u32, power-ups u32, power-on time s u32 | operating time and last cycle measured; rest answered. Cumulative since commissioning; survives power loss |
+| 93/300 temperatures | 534 v2, 13 B | media, PCB, ambient °C (floats), then one byte | answered on the ALPHA2 GO |
+| 87/1 energy | 232 v1, 26 B | float64 joules @0; f32 @8, u16 @12, f32 @14, repeated float64 @18 unconfirmed | answered on the ALPHA2 GO |
+| 94/101 clock | 322, 12 B | local wall clock | documented (HWR), not implemented |
+
+Error codes follow the GENI ErrorCode enum (`registry/alpha2go.py::ErrorCode`); the ALPHA2 GO
+manual's table maps panel codes E1 → 51, E2 → 40, E3 → 4/72/76/85/132, E4 → 57, E9 → 25.
+
+## Measured values (one ALPHA2 GO)
+
+| Date | Flow | Head | Grid | DC-link | Current | Power | Speed | Temp |
+|---|---|---|---|---|---|---|---|---|
+| 2026-11-07 | 1.427 m³/h | 0.148 m | 235.2 V | 332.7 V | 0.038 A | 4.01 W | 1640 rpm | 44 °C |
+| 2026-11-09 | 0.995 m³/h | 0.434 m | 230.6 V | 324.0 V | 0.038 A | 4.01 W | 1658 rpm | 39 °C |
+
+The panel showed 1.4 m³/h, 0.1 m, 4 W and 1640 rpm on 2026-11-07. Frames are in
+`src/grundfos_ble/testdata/alpha2go/`.
+
+## Open questions
+
+- Meaning of 93/290 @8, @12 and @32, and of 87/69 @16, @24, @28 on the ALPHA2 GO.
+- Which sensor 87/69 @32 reads: it differs from the PCB temperature in 93/300 (42 °C against 37 °C).
+- How the alarm objects look with a fault active.
+- Whether the alarm/warning/connected advert flag bits behave on the ALPHA2 GO as on the SCALA1.
+- How a pump behaves after losing a bond, which has never been observed.
+- SMP details (Just Works assumed; IO capability none works through ESPHome proxies).

grundfos_ble-0.1.0/pyproject.toml

@@ -0,0 +1,109 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "grundfos-ble"
+version = "0.1.0"
+description = "Async Python library for Grundfos circulator pumps over GENIbus-on-Bluetooth LE (ALPHA2 GO first)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.13"
+authors = [{ name = "83noit" }]
+keywords = ["grundfos", "alpha2", "genibus", "bluetooth", "ble", "pump", "home-assistant"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+dependencies = [
+    "bleak>=3.0,<4",
+    "bleak-retry-connector>=4.0,<5",
+]
+
+[project.urls]
+Homepage = "https://github.com/83noit/grundfos-ble"
+Repository = "https://github.com/83noit/grundfos-ble"
+Issues = "https://github.com/83noit/grundfos-ble/issues"
+Changelog = "https://github.com/83noit/grundfos-ble/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "pytest>=9",
+    "pytest-asyncio>=1.0",
+    "pytest-cov>=7",
+    "ruff>=0.14",
+    "mypy>=1.19",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/grundfos_ble"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/docs", "/README.md", "/CHANGELOG.md", "/LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W", "F", "I", "B", "UP", "N", "SIM", "RUF", "ASYNC", "PT", "T20", "D",
+    "ANN", "ARG", "C4", "DTZ", "ERA", "ICN", "ISC", "PIE", "RET", "RSE", "SLF", "TID", "TRY",
+]
+ignore = [
+    "D203",  # one-blank-line-before-class (conflicts with D211)
+    "D213",  # multi-line-summary-second-line (conflicts with D212)
+    "TRY003",  # long messages in exceptions are fine here
+    "ISC001",  # conflicts with the formatter
+    "D105",  # magic methods need no docstring
+    "D107",  # __init__ is documented by the class
+    "N818",  # exception names read better without an Error suffix here
+    "RUF001",  # × and – are used deliberately in notes and docstrings
+    "RUF002",
+    "RUF003",
+    "ASYNC109",  # explicit timeout parameters are part of the transport API
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D", "ANN", "SLF001", "PLR2004", "ARG001"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.ruff.lint.isort]
+known-first-party = ["grundfos_ble"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+warn_unreachable = true
+show_error_codes = true
+packages = ["grundfos_ble"]
+mypy_path = "src"
+
+[[tool.mypy.overrides]]
+module = ["tests.*"]
+disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+addopts = "-q --strict-markers"
+
+[tool.coverage.run]
+source = ["grundfos_ble"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false