solarflow-ble 0.1.1__tar.gz

solarflow_ble-0.1.1/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: solarflow-ble
+Version: 0.1.1
+Summary: Add your description here
+Author: Daan Vervacke
+Author-email: Daan Vervacke <daan.vervacke@proton.me>
+License-Expression: MIT
+Requires-Dist: bleak>=1.1.1
+Requires-Dist: bleak-esphome>=4.1.0
+Requires-Dist: bleak-retry-connector>=4.7.1
+Requires-Dist: habluetooth>=7.0.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# solarflow-ble
+
+Unofficial asynchronous Python library for communicating with Zendure
+SolarFlow controllers over Bluetooth Low Energy.
+
+The protocol implementation is based on
+[esphome-solarflow-ble](https://github.com/krumpholz/esphome-solarflow-ble).
+The library has been tested with a SolarFlow 2400AC through a Home Assistant
+Connect AUX-2 acting as a Bluetooth proxy. Traffic probing and debugging use
+[`bleak-esphome`](https://github.com/Bluetooth-Devices/bleak-esphome).
+
+All protocol credits and reverse-engineering efforts belong to the
+[esphome-solarflow-ble project](https://github.com/krumpholz/esphome-solarflow-ble).
+This library builds on that work in Python.
+
+Requires Python >= 3.14.
+
+## Install
+
+```bash
+uv add solarflow-ble
+```
+
+## Usage
+
+`SolarFlowClient` uses an injected transport, so applications can choose their
+own Bluetooth adapter and tests can use a fake transport without Bluetooth
+hardware.
+
+```python
+import asyncio
+
+from bleak.backends.device import BLEDevice
+
+from solarflow_ble import BleakTransport, SolarFlowClient
+
+
+async def main() -> None:
+    # Replace these values with a device discovered by your BLE adapter.
+    device = BLEDevice("AA:BB:CC:DD:EE:FF", "SolarFlow", {})
+    client = SolarFlowClient(BleakTransport(device))
+
+    try:
+        await client.connect()
+        print(client.state)
+        print(client.status)
+    finally:
+        await client.disconnect()
+
+
+asyncio.run(main())
+```
+
+The client connects, completes the BLESPP handshake, reads the initial
+`getAll` state, and keeps the session updated. Always call `disconnect()` when
+the session ends.
+
+Control methods are disabled by default. Enable them explicitly when the
+application is intended to change device settings:
+
+```python
+client = SolarFlowClient(BleakTransport(device), allow_control=True)
+try:
+    await client.connect()
+    await client.set_output_limit(800)
+finally:
+    await client.disconnect()
+```
+
+## Probe
+
+The developer-only probe captures SolarFlow GATT traffic through an ESPHome
+Bluetooth proxy (e.g. the Home Assistant Connect AUX-2).
+It does not send device-setting writes by default. It sends the BLESPP
+handshake, `getInfo`, and `getAll` protocol requests.
+
+```bash
+# Discover a SolarFlow device and capture its traffic.
+uv run scripts/probe_solarflow.py \
+  --proxy "192.168.1.157" \
+  --noise-psk "your-esphome-noise-psk" \
+  --output /tmp/solarflow.jsonl
+```
+
+List advertisements without connecting to a SolarFlow device:
+
+```bash
+uv run scripts/probe_solarflow.py \
+  --proxy "192.168.1.157" \
+  --noise-psk "your-esphome-noise-psk" \
+  --list-advertisements \
+  --scan-seconds 30
+```
+
+Advertisement addresses and parsed SolarFlow identifiers are redacted by
+default. Add `--show-identities` when selecting values for `--address` or
+`--identifier`; capture files remain redacted.
+
+Target a specific SolarFlow device by Bluetooth address:
+
+```bash
+uv run scripts/probe_solarflow.py \
+  --proxy "192.168.1.157" \
+  --noise-psk "your-esphome-noise-psk" \
+  --address "AA:BB:CC:DD:EE:FF" \
+  --scan-seconds 60 \
+  --capture-seconds 30 \
+  --output /tmp/solarflow-target.jsonl
+```
+
+Alternatively, target a device by its SolarFlow manufacturer-advertisement
+identifier:
+
+```bash
+uv run scripts/probe_solarflow.py \
+  --proxy "192.168.1.157" \
+  --noise-psk "your-esphome-noise-psk" \
+  --identifier "DEVICE_IDENTIFIER" \
+  --scan-seconds 60 \
+  --capture-seconds 30 \
+  --output /tmp/solarflow-target.jsonl
+```
+
+Connect to a device and capture notifications without sending the BLESPP
+handshake or the initial `getInfo` and `getAll` requests:
+
+```bash
+uv run scripts/probe_solarflow.py \
+  --proxy "192.168.1.157" \
+  --noise-psk "your-esphome-noise-psk" \
+  --address "AA:BB:CC:DD:EE:FF" \
+  --no-handshake \
+  --capture-seconds 30 \
+  --output /tmp/solarflow-passive.jsonl
+```
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) and targets Python 3.14+.
+
+```bash
+uv sync
+uv run python -m scripts.check
+```
+
+The development gate stops at the first failure in this order: format check,
+Ruff lint, mypy, branch-covered tests, coverage report, then package build.
+
+Run one test file or test:
+
+```bash
+uv run pytest tests/test_solarflow.py
+uv run pytest tests/test_solarflow.py -k connect_handshake
+```
+
+### Standalone library client test
+
+Use the standalone diagnostic to exercise `SolarFlowClient` through an
+ESPHome Bluetooth proxy. It discovers exactly one target by address or
+SolarFlow advertisement identifier and is read-only unless controls are
+explicitly confirmed.
+
+```bash
+uv run scripts/test_solarflow_client.py \
+  --proxy "192.168.1.157" \
+  --noise-psk "your-esphome-noise-psk" \
+  --identifier "DEVICE_IDENTIFIER" \
+  --duration 30 \
+  --output /tmp/solarflow-library-test.jsonl
+```
+
+The script prints device identities and decoded state to stdout for local
+diagnostics. The optional JSONL file is always recursively redacted. Controls
+require both `--controls` and `--confirm-controls`; they also require explicit
+`--min-soc` and `--soc` values because those original wire values are not
+available safely for restoration.
+
+The connection settings can be kept in the ignored local config file
+`scripts/test_solarflow_client.local.json`. The file may contain `proxy`,
+`noise_psk`, and exactly one of `address` or `identifier`:
+
+```json
+{
+  "proxy": "192.168.1.157",
+  "noise_psk": "your-esphome-noise-psk",
+  "identifier": "DEVICE_IDENTIFIER"
+}
+```
+
+Run the diagnostic with the default local file:
+
+```bash
+uv run scripts/test_solarflow_client.py --duration 30
+```
+
+Use `--config path/to/config.json` for another local file. Command-line values
+override values from the config file, so individual settings can be replaced
+without editing it:
+
+```bash
+uv run scripts/test_solarflow_client.py \
+  --config scripts/test_solarflow_client.local.json \
+  --identifier "OTHER_DEVICE_IDENTIFIER"
+```
+
+Do not commit this file or paste a real `noise_psk` into documentation,
+fixtures, logs, or shell history. The default local filename is ignored by
+Git; use a file with equivalent local-only handling when choosing another
+config path. The script never prints or writes `noise_psk`.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).

solarflow_ble-0.1.1/README.md

@@ -0,0 +1,213 @@
+# solarflow-ble
+
+Unofficial asynchronous Python library for communicating with Zendure
+SolarFlow controllers over Bluetooth Low Energy.
+
+The protocol implementation is based on
+[esphome-solarflow-ble](https://github.com/krumpholz/esphome-solarflow-ble).
+The library has been tested with a SolarFlow 2400AC through a Home Assistant
+Connect AUX-2 acting as a Bluetooth proxy. Traffic probing and debugging use
+[`bleak-esphome`](https://github.com/Bluetooth-Devices/bleak-esphome).
+
+All protocol credits and reverse-engineering efforts belong to the
+[esphome-solarflow-ble project](https://github.com/krumpholz/esphome-solarflow-ble).
+This library builds on that work in Python.
+
+Requires Python >= 3.14.
+
+## Install
+
+```bash
+uv add solarflow-ble
+```
+
+## Usage
+
+`SolarFlowClient` uses an injected transport, so applications can choose their
+own Bluetooth adapter and tests can use a fake transport without Bluetooth
+hardware.
+
+```python
+import asyncio
+
+from bleak.backends.device import BLEDevice
+
+from solarflow_ble import BleakTransport, SolarFlowClient
+
+
+async def main() -> None:
+    # Replace these values with a device discovered by your BLE adapter.
+    device = BLEDevice("AA:BB:CC:DD:EE:FF", "SolarFlow", {})
+    client = SolarFlowClient(BleakTransport(device))
+
+    try:
+        await client.connect()
+        print(client.state)
+        print(client.status)
+    finally:
+        await client.disconnect()
+
+
+asyncio.run(main())
+```
+
+The client connects, completes the BLESPP handshake, reads the initial
+`getAll` state, and keeps the session updated. Always call `disconnect()` when
+the session ends.
+
+Control methods are disabled by default. Enable them explicitly when the
+application is intended to change device settings:
+
+```python
+client = SolarFlowClient(BleakTransport(device), allow_control=True)
+try:
+    await client.connect()
+    await client.set_output_limit(800)
+finally:
+    await client.disconnect()
+```
+
+## Probe
+
+The developer-only probe captures SolarFlow GATT traffic through an ESPHome
+Bluetooth proxy (e.g. the Home Assistant Connect AUX-2).
+It does not send device-setting writes by default. It sends the BLESPP
+handshake, `getInfo`, and `getAll` protocol requests.
+
+```bash
+# Discover a SolarFlow device and capture its traffic.
+uv run scripts/probe_solarflow.py \
+  --proxy "192.168.1.157" \
+  --noise-psk "your-esphome-noise-psk" \
+  --output /tmp/solarflow.jsonl
+```
+
+List advertisements without connecting to a SolarFlow device:
+
+```bash
+uv run scripts/probe_solarflow.py \
+  --proxy "192.168.1.157" \
+  --noise-psk "your-esphome-noise-psk" \
+  --list-advertisements \
+  --scan-seconds 30
+```
+
+Advertisement addresses and parsed SolarFlow identifiers are redacted by
+default. Add `--show-identities` when selecting values for `--address` or
+`--identifier`; capture files remain redacted.
+
+Target a specific SolarFlow device by Bluetooth address:
+
+```bash
+uv run scripts/probe_solarflow.py \
+  --proxy "192.168.1.157" \
+  --noise-psk "your-esphome-noise-psk" \
+  --address "AA:BB:CC:DD:EE:FF" \
+  --scan-seconds 60 \
+  --capture-seconds 30 \
+  --output /tmp/solarflow-target.jsonl
+```
+
+Alternatively, target a device by its SolarFlow manufacturer-advertisement
+identifier:
+
+```bash
+uv run scripts/probe_solarflow.py \
+  --proxy "192.168.1.157" \
+  --noise-psk "your-esphome-noise-psk" \
+  --identifier "DEVICE_IDENTIFIER" \
+  --scan-seconds 60 \
+  --capture-seconds 30 \
+  --output /tmp/solarflow-target.jsonl
+```
+
+Connect to a device and capture notifications without sending the BLESPP
+handshake or the initial `getInfo` and `getAll` requests:
+
+```bash
+uv run scripts/probe_solarflow.py \
+  --proxy "192.168.1.157" \
+  --noise-psk "your-esphome-noise-psk" \
+  --address "AA:BB:CC:DD:EE:FF" \
+  --no-handshake \
+  --capture-seconds 30 \
+  --output /tmp/solarflow-passive.jsonl
+```
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) and targets Python 3.14+.
+
+```bash
+uv sync
+uv run python -m scripts.check
+```
+
+The development gate stops at the first failure in this order: format check,
+Ruff lint, mypy, branch-covered tests, coverage report, then package build.
+
+Run one test file or test:
+
+```bash
+uv run pytest tests/test_solarflow.py
+uv run pytest tests/test_solarflow.py -k connect_handshake
+```
+
+### Standalone library client test
+
+Use the standalone diagnostic to exercise `SolarFlowClient` through an
+ESPHome Bluetooth proxy. It discovers exactly one target by address or
+SolarFlow advertisement identifier and is read-only unless controls are
+explicitly confirmed.
+
+```bash
+uv run scripts/test_solarflow_client.py \
+  --proxy "192.168.1.157" \
+  --noise-psk "your-esphome-noise-psk" \
+  --identifier "DEVICE_IDENTIFIER" \
+  --duration 30 \
+  --output /tmp/solarflow-library-test.jsonl
+```
+
+The script prints device identities and decoded state to stdout for local
+diagnostics. The optional JSONL file is always recursively redacted. Controls
+require both `--controls` and `--confirm-controls`; they also require explicit
+`--min-soc` and `--soc` values because those original wire values are not
+available safely for restoration.
+
+The connection settings can be kept in the ignored local config file
+`scripts/test_solarflow_client.local.json`. The file may contain `proxy`,
+`noise_psk`, and exactly one of `address` or `identifier`:
+
+```json
+{
+  "proxy": "192.168.1.157",
+  "noise_psk": "your-esphome-noise-psk",
+  "identifier": "DEVICE_IDENTIFIER"
+}
+```
+
+Run the diagnostic with the default local file:
+
+```bash
+uv run scripts/test_solarflow_client.py --duration 30
+```
+
+Use `--config path/to/config.json` for another local file. Command-line values
+override values from the config file, so individual settings can be replaced
+without editing it:
+
+```bash
+uv run scripts/test_solarflow_client.py \
+  --config scripts/test_solarflow_client.local.json \
+  --identifier "OTHER_DEVICE_IDENTIFIER"
+```
+
+Do not commit this file or paste a real `noise_psk` into documentation,
+fixtures, logs, or shell history. The default local filename is ignored by
+Git; use a file with equivalent local-only handling when choosing another
+config path. The script never prints or writes `noise_psk`.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).

solarflow_ble-0.1.1/pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "solarflow-ble"
+version = "0.1.1"
+description = "Add your description here"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14"
+dependencies = [
+    "bleak>=1.1.1",
+    "bleak-esphome>=4.1.0",
+    "bleak-retry-connector>=4.7.1",
+    "habluetooth>=7.0.0",
+]
+
+[[project.authors]]
+name = "Daan Vervacke"
+email = "daan.vervacke@proton.me"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "coverage[toml]>=7.15.2",
+    "mypy>=2.3.1",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.16.8",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py314"
+line-length = 88
+src = [
+    "src/solarflow_ble",
+    "tests",
+    "scripts",
+]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "ANN401",
+    "CPY001",
+    "COM812",
+    "C901",
+    "EM101",
+    "EM102",
+    "FBT001",
+    "FBT002",
+    "FBT003",
+    "FURB110",
+    "D",
+    "ISC001",
+    "PLR0913",
+    "PLR0917",
+    "PLR2004",
+    "RUF036",
+    "RUF006",
+    "TRY003",
+    "TC001",
+    "TC002",
+    "TC003",
+    "TC006",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "ANN",
+    "ARG",
+    "CPY001",
+    "FBT",
+    "INP001",
+    "PLC0415",
+    "PLR2004",
+    "S101",
+    "S105",
+    "S106",
+    "SLF001",
+]
+"scripts/check.py" = [
+    "S603",
+    "T201",
+]
+
+[tool.mypy]
+python_version = "3.14"
+strict = true

solarflow_ble-0.1.1/pyproject.toml.orig

@@ -0,0 +1,83 @@
+[project]
+name = "solarflow-ble"
+version = "0.1.1"
+description = "Add your description here"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Daan Vervacke", email = "daan.vervacke@proton.me" }]
+requires-python = ">=3.14"
+dependencies = [
+    "bleak>=1.1.1",
+    "bleak-esphome>=4.1.0",
+    "bleak-retry-connector>=4.7.1",
+    "habluetooth>=7.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "coverage[toml]>=7.15.2",
+    "mypy>=2.3.1",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.16.8",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py314"
+line-length = 88
+src = ["src/solarflow_ble", "tests", "scripts"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "ANN401",
+    "CPY001",
+    "COM812",
+    "C901",
+    "EM101",
+    "EM102",
+    "FBT001",
+    "FBT002",
+    "FBT003",
+    "FURB110",
+    "D",
+    "ISC001",
+    "PLR0913",
+    "PLR0917",
+    "PLR2004",
+    "RUF036",
+    "RUF006",
+    "TRY003",
+    "TC001",
+    "TC002",
+    "TC003",
+    "TC006",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "ANN",
+    "ARG",
+    "CPY001",
+    "FBT",
+    "INP001",
+    "PLC0415",
+    "PLR2004",
+    "S101",
+    "S105",
+    "S106",
+    "SLF001",
+]
+
+"scripts/check.py" = ["S603", "T201"]
+
+[tool.mypy]
+python_version = "3.14"
+strict = true

solarflow_ble-0.1.1/src/solarflow_ble/__init__.py

@@ -0,0 +1,18 @@
+"""Python library for Zendure SolarFlow BLE devices."""
+
+from .client import BleTransport, SolarFlowClient
+from .models import Advertisement, ConnectionStatus, SolarFlowState, SolarFlowUpdate
+from .protocol import parse_advertisement
+from .transport import BleakTransport
+
+__version__ = "0.1.0"
+__all__ = [
+    "Advertisement",
+    "BleTransport",
+    "BleakTransport",
+    "ConnectionStatus",
+    "SolarFlowClient",
+    "SolarFlowState",
+    "SolarFlowUpdate",
+    "parse_advertisement",
+]

solarflow_ble-0.1.1/src/solarflow_ble/client.py

@@ -0,0 +1,333 @@
+"""Typed SolarFlow BLE client."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
+from typing import Any, Protocol
+
+from .const import (
+    DEFAULT_BLE_SPP_DELAY,
+    DEFAULT_KEEPALIVE_SECONDS,
+    DEFAULT_RESPONSE_TIMEOUT,
+    NOTIFY_CHARACTERISTIC_UUID,
+    WRITE_CHARACTERISTIC_UUID,
+)
+from .exceptions import (
+    SolarFlowCommandError,
+    SolarFlowDeviceError,
+    SolarFlowNotReadyError,
+    SolarFlowProtocolError,
+    SolarFlowTimeoutError,
+    SolarFlowValidationError,
+)
+from .models import ConnectionStatus, SolarFlowState, SolarFlowUpdate
+from .protocol import decode_json, encode_json
+
+NotificationCallback = Callable[[str, bytes], Awaitable[None] | None]
+UpdateCallback = Callable[[SolarFlowUpdate], Awaitable[None]]
+_LOGGER = logging.getLogger(__name__)
+
+
+class BleTransport(Protocol):
+    """Minimal BLE transport supplied by the caller."""
+
+    async def connect(self) -> None: ...
+    async def disconnect(self) -> None: ...
+    async def start_notify(
+        self, characteristic: str, callback: NotificationCallback
+    ) -> None: ...
+    async def stop_notify(self, characteristic: str) -> None: ...
+    async def write_gatt_char(
+        self, characteristic: str, data: bytes, response: bool = False
+    ) -> None: ...
+
+
+class SolarFlowClient:
+    """Communicate with one SolarFlow controller."""
+
+    def __init__(
+        self,
+        transport: BleTransport,
+        *,
+        device_id: str | None = None,
+        response_timeout: float = DEFAULT_RESPONSE_TIMEOUT,
+        keepalive_seconds: float = DEFAULT_KEEPALIVE_SECONDS,
+        ble_spp_delay: float = DEFAULT_BLE_SPP_DELAY,
+        initial_read_delay: float = 0.3,
+        update_callback: UpdateCallback | None = None,
+        allow_control: bool = False,
+    ) -> None:
+        self.transport = transport
+        self.device_id = device_id
+        self.response_timeout = response_timeout
+        self.keepalive_seconds = keepalive_seconds
+        self.ble_spp_delay = ble_spp_delay
+        self.initial_read_delay = initial_read_delay
+        self.update_callback = update_callback
+        self.allow_control = allow_control
+        self.state = SolarFlowState()
+        self.status = ConnectionStatus.DISCONNECTED
+        self._lock = asyncio.Lock()
+        self._reports: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+        self._write_results: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+        self._keepalive_task: asyncio.Task[None] | None = None
+        self._message_id = 1
+
+    @property
+    def connected(self) -> bool:
+        return self.status is not ConnectionStatus.DISCONNECTED
+
+    @property
+    def protocol_ready(self) -> bool:
+        return self.status in (ConnectionStatus.PROTOCOL_READY, ConnectionStatus.READY)
+
+    @property
+    def ready(self) -> bool:
+        return self.status is ConnectionStatus.READY
+
+    async def connect(self) -> None:
+        try:
+            await self.transport.connect()
+            self.status = ConnectionStatus.CONNECTED
+            await self.transport.start_notify(
+                NOTIFY_CHARACTERISTIC_UUID, self._notification
+            )
+            ble_spp = await self._wait_for_method("BLESPP")
+            self._establish_identity(ble_spp)
+            await self._write({"messageId": 1009, "method": "BLESPP_OK"})
+            await asyncio.sleep(self.ble_spp_delay)
+            timestamp = int(time.time() * 1000)
+            await self._write(
+                {
+                    "deviceId": self._require_device_id(),
+                    "messageId": self._next_message_id(),
+                    "method": "getInfo",
+                    "timestamp": timestamp,
+                }
+            )
+            await self._wait_for_method("getInfo-rsp")
+            self.status = ConnectionStatus.PROTOCOL_READY
+            await asyncio.sleep(self.initial_read_delay)
+            await self._write(
+                {
+                    "deviceId": self._require_device_id(),
+                    "messageId": self._next_message_id(),
+                    "timestamp": int(time.time() * 1000),
+                    "properties": ["getAll"],
+                    "method": "read",
+                }
+            )
+            await self._wait_for_initial_reports()
+            self._refresh_status()
+            self._keepalive_task = asyncio.create_task(self._keepalive())
+        except BaseException:
+            await self.disconnect()
+            raise
+
+    async def disconnect(self) -> None:
+        if self._keepalive_task:
+            self._keepalive_task.cancel()
+            await asyncio.gather(self._keepalive_task, return_exceptions=True)
+            self._keepalive_task = None
+        with suppress(Exception):
+            await self.transport.stop_notify(NOTIFY_CHARACTERISTIC_UUID)
+        with suppress(Exception):
+            await self.transport.disconnect()
+        self.status = ConnectionStatus.DISCONNECTED
+
+    async def _notification(self, _characteristic: str, payload: bytes) -> None:
+        message = decode_json(payload)
+        method = message.get("method")
+        self._validate_message_identity(message)
+        if method == "BLESPP":
+            await self._reports.put(message)
+            return
+        if method in {"getInfo-rsp", "read_reply"}:
+            await self._reports.put(message)
+        elif method == "report":
+            properties = message.get("properties")
+            if isinstance(properties, dict):
+                self.state = self.state.update(properties)
+                self.state = self.state.with_identity(message)
+                if "writeRsp" in properties:
+                    await self._write_results.put(message)
+            self.state = self.state.with_packs(message)
+            await self._reports.put(message)
+        elif method == "error":
+            await self._reports.put(message)
+        self._refresh_status()
+        callback = self.update_callback
+        if callback:
+            try:
+                await callback(SolarFlowUpdate(self.state, self.status, message))
+            except Exception:
+                _LOGGER.exception("SolarFlow update callback failed")
+
+    async def _write(self, message: dict[str, Any]) -> None:
+        await self.transport.write_gatt_char(
+            WRITE_CHARACTERISTIC_UUID, encode_json(message), response=False
+        )
+
+    async def _wait_for_method(self, method: str) -> dict[str, Any]:
+        deadline = asyncio.get_running_loop().time() + self.response_timeout
+        while True:
+            remaining = deadline - asyncio.get_running_loop().time()
+            if remaining <= 0:
+                raise SolarFlowTimeoutError(f"Timed out waiting for {method}")
+            try:
+                message = await asyncio.wait_for(self._reports.get(), remaining)
+            except TimeoutError as err:
+                raise SolarFlowTimeoutError(f"Timed out waiting for {method}") from err
+            if message.get("method") == method:
+                return message
+
+    def _establish_identity(self, message: dict[str, Any]) -> None:
+        device_id = message.get("deviceId")
+        if not isinstance(device_id, str) or not device_id:
+            raise SolarFlowProtocolError("BLESPP did not include deviceId")
+        if self.device_id is not None and self.device_id != device_id:
+            raise SolarFlowProtocolError(
+                "BLESPP deviceId does not match the requested device"
+            )
+        self.device_id = device_id
+        self.state = self.state.with_identity({"deviceId": device_id})
+
+    def _validate_message_identity(self, message: dict[str, Any]) -> None:
+        message_device_id = message.get("deviceId")
+        if message_device_id is None or self.device_id is None:
+            return
+        if message_device_id != self.device_id:
+            raise SolarFlowProtocolError(
+                "SolarFlow message deviceId does not match the connected device"
+            )
+
+    def _require_device_id(self) -> str:
+        if self.device_id is None:
+            raise SolarFlowProtocolError("SolarFlow device identity is not established")
+        return self.device_id
+
+    def _next_message_id(self) -> int:
+        while self._message_id == 1009:
+            self._message_id += 1
+        message_id = self._message_id
+        self._message_id += 1
+        return message_id
+
+    async def _wait_for_initial_reports(self) -> None:
+        deadline = asyncio.get_running_loop().time() + self.response_timeout
+        while self.state.smart_mode is None:
+            remaining = deadline - asyncio.get_running_loop().time()
+            if remaining <= 0:
+                raise SolarFlowTimeoutError(
+                    "Timed out waiting for initial report state"
+                )
+            try:
+                message = await asyncio.wait_for(self._reports.get(), remaining)
+            except TimeoutError as err:
+                raise SolarFlowTimeoutError(
+                    "Timed out waiting for initial report state"
+                ) from err
+            if message.get("method") == "error":
+                raise SolarFlowDeviceError(
+                    f"SolarFlow reported error: {message.get('data')}"
+                )
+
+    def _refresh_status(self) -> None:
+        if self.status is ConnectionStatus.DISCONNECTED or not self.protocol_ready:
+            return
+        self.status = (
+            ConnectionStatus.READY
+            if self.state.smart_mode == 1
+            else ConnectionStatus.PROTOCOL_READY
+        )
+
+    async def _request_write(self, property_name: str, value: int) -> None:
+        if not self.allow_control:
+            raise SolarFlowNotReadyError(
+                "SolarFlow controls are disabled for this session"
+            )
+        if not self.ready:
+            raise SolarFlowNotReadyError("SolarFlow controls are not ready")
+        async with self._lock:
+            timestamp = int(time.time() * 1000)
+            await self._write(
+                {
+                    "method": "write",
+                    "timestamp": timestamp,
+                    "deviceId": self._require_device_id(),
+                    "messageId": self._next_message_id(),
+                    "properties": {property_name: value},
+                }
+            )
+            deadline = asyncio.get_running_loop().time() + self.response_timeout
+            while True:
+                remaining = deadline - asyncio.get_running_loop().time()
+                if remaining <= 0:
+                    raise SolarFlowTimeoutError(
+                        f"Timed out waiting for {property_name} acknowledgement"
+                    )
+                try:
+                    response = await asyncio.wait_for(
+                        self._write_results.get(), remaining
+                    )
+                except TimeoutError as err:
+                    raise SolarFlowTimeoutError(
+                        f"Timed out waiting for {property_name} acknowledgement"
+                    ) from err
+                properties = response.get("properties")
+                if isinstance(properties, dict) and "writeRsp" in properties:
+                    if properties["writeRsp"] != 0:
+                        raise SolarFlowCommandError(
+                            f"SolarFlow rejected {property_name}"
+                        )
+                    return
+
+    async def set_input_limit(self, value: int) -> None:
+        self._validate_limit(value)
+        await self._request_write("inputLimit", value)
+
+    async def set_output_limit(self, value: int) -> None:
+        self._validate_limit(value)
+        await self._request_write("outputLimit", value)
+
+    async def set_min_soc(self, value: int) -> None:
+        if not 0 <= value <= 50:
+            raise SolarFlowValidationError(
+                "Minimum SOC must be between 0 and 50 percent"
+            )
+        await self._request_write("minSoc", value * 10)
+
+    async def set_soc(self, value: int) -> None:
+        if not 70 <= value <= 100:
+            raise SolarFlowValidationError(
+                "Maximum SOC must be between 70 and 100 percent"
+            )
+        await self._request_write("socSet", value * 10)
+
+    async def set_ac_mode(self, value: int) -> None:
+        if value not in (1, 2):
+            raise SolarFlowValidationError("AC mode must be 1 or 2")
+        await self._request_write("acMode", value)
+
+    async def _keepalive(self) -> None:
+        while True:
+            await asyncio.sleep(self.keepalive_seconds)
+            async with self._lock:
+                await self._write(
+                    {
+                        "deviceId": self._require_device_id(),
+                        "messageId": self._next_message_id(),
+                        "timestamp": int(time.time() * 1000),
+                        "properties": ["getAll"],
+                        "method": "read",
+                    }
+                )
+
+    @staticmethod
+    def _validate_limit(value: int) -> None:
+        if not 0 <= value <= 2400:
+            raise SolarFlowValidationError("Power limit must be between 0 and 2400 W")

solarflow_ble-0.1.1/src/solarflow_ble/const.py

@@ -0,0 +1,9 @@
+"""SolarFlow BLE constants."""
+
+SERVICE_UUID = "0000a002-0000-1000-8000-00805f9b34fb"
+WRITE_CHARACTERISTIC_UUID = "0000c304-0000-1000-8000-00805f9b34fb"
+NOTIFY_CHARACTERISTIC_UUID = "0000c305-0000-1000-8000-00805f9b34fb"
+MANUFACTURER_ID = 0x4F48
+DEFAULT_KEEPALIVE_SECONDS = 30.0
+DEFAULT_RESPONSE_TIMEOUT = 10.0
+DEFAULT_BLE_SPP_DELAY = 0.3

solarflow_ble-0.1.1/src/solarflow_ble/exceptions.py

@@ -0,0 +1,33 @@
+"""SolarFlow exceptions."""
+
+
+class SolarFlowError(Exception):
+    """Base SolarFlow error."""
+
+
+class SolarFlowConnectionError(SolarFlowError):
+    """The BLE transport could not connect or disconnected."""
+
+
+class SolarFlowTimeoutError(SolarFlowError):
+    """The device did not answer before the timeout."""
+
+
+class SolarFlowProtocolError(SolarFlowError):
+    """The device sent invalid or unexpected protocol data."""
+
+
+class SolarFlowCommandError(SolarFlowError):
+    """The device rejected a command."""
+
+
+class SolarFlowValidationError(SolarFlowError, ValueError):
+    """A command argument is outside the supported range."""
+
+
+class SolarFlowNotReadyError(SolarFlowError):
+    """The session is connected but controls are not currently ready."""
+
+
+class SolarFlowDeviceError(SolarFlowError):
+    """The device reported a protocol error event."""

solarflow_ble-0.1.1/src/solarflow_ble/models.py

@@ -0,0 +1,194 @@
+"""Typed SolarFlow models."""
+
+from dataclasses import dataclass, replace
+from enum import IntEnum, StrEnum
+from typing import Any, cast
+
+_REPORT_FIELDS = {
+    "packInputPower": "pack_input_power",
+    "outputPackPower": "output_pack_power",
+    "outputHomePower": "output_home_power",
+    "remainOutTime": "remain_out_time",
+    "dataReady": "data_ready",
+    "acMode": "ac_mode",
+    "inputLimit": "input_limit",
+    "outputLimit": "output_limit",
+    "packState": "pack_state",
+    "acStatus": "ac_status",
+    "electricLevel": "electric_level",
+    "gridState": "grid_state",
+    "faultLevel": "fault_level",
+    "smartMode": "smart_mode",
+    "chargeMaxLimit": "charge_max_limit",
+    "socLimit": "soc_limit",
+    "gridInputPower": "grid_input_power",
+    "solarInputPower": "solar_input_power",
+    "solarPower1": "solar_power_1",
+    "solarPower2": "solar_power_2",
+    "solarPower3": "solar_power_3",
+    "solarPower4": "solar_power_4",
+    "solarPower5": "solar_power_5",
+    "solarPower6": "solar_power_6",
+    "gridOffPower": "grid_off_power",
+    "socStatus": "soc_status",
+    "hyperTmp": "hyper_temperature",
+}
+
+_PACK_FIELDS = {
+    "packType": "pack_type",
+    "socLevel": "soc_level",
+    "state": "state",
+    "power": "power",
+    "maxTemp": "max_temp",
+    "totalVol": "total_voltage",
+    "batcur": "battery_current",
+    "maxVol": "max_voltage",
+    "minVol": "min_voltage",
+    "softVersion": "software_version",
+    "heatState": "heat_state",
+}
+
+
+class AcMode(IntEnum):
+    """Known AC modes."""
+
+    CHARGING = 1
+    DISCHARGING = 2
+
+
+class PackState(IntEnum):
+    """Known pack states."""
+
+    STANDBY = 0
+    CHARGING = 1
+    DISCHARGING = 2
+
+
+class ConnectionStatus(StrEnum):
+    """Protocol session status."""
+
+    DISCONNECTED = "disconnected"
+    CONNECTED = "connected"
+    PROTOCOL_READY = "protocol_ready"
+    READY = "ready"
+
+
+@dataclass(frozen=True, slots=True)
+class BatteryPack:
+    """Latest state reported for one battery pack."""
+
+    serial_number: str
+    pack_type: int | None = None
+    soc_level: int | None = None
+    state: int | None = None
+    power: int | None = None
+    max_temp: int | None = None
+    total_voltage: int | None = None
+    battery_current: int | None = None
+    max_voltage: int | None = None
+    min_voltage: int | None = None
+    software_version: int | None = None
+    heat_state: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Advertisement:
+    """A SolarFlow BLE advertisement."""
+
+    address: str
+    identifier: str
+    rssi: int | None = None
+    connectable: bool = True
+    address_type: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SolarFlowState:
+    """Latest decoded controller state."""
+
+    pack_input_power: int | None = None
+    output_pack_power: int | None = None
+    battery_power: int | None = None
+    ac_mode: int | None = None
+    input_limit: int | None = None
+    output_limit: int | None = None
+    pack_state: int | None = None
+    ac_status: int | None = None
+    electric_level: int | None = None
+    grid_state: int | None = None
+    fault_level: int | None = None
+    smart_mode: int | None = None
+    charge_max_limit: int | None = None
+    soc_limit: int | None = None
+    output_home_power: int | None = None
+    remain_out_time: int | None = None
+    data_ready: int | None = None
+    grid_input_power: int | None = None
+    solar_input_power: int | None = None
+    solar_power_1: int | None = None
+    solar_power_2: int | None = None
+    solar_power_3: int | None = None
+    solar_power_4: int | None = None
+    solar_power_5: int | None = None
+    solar_power_6: int | None = None
+    grid_off_power: int | None = None
+    soc_status: int | None = None
+    hyper_temperature: int | None = None
+    device_id: str | None = None
+    product_key: str | None = None
+    packs: tuple[BatteryPack, ...] = ()
+    raw: dict[str, object] | None = None
+
+    def update(self, values: dict[str, object]) -> SolarFlowState:
+        changes = {
+            _REPORT_FIELDS[key]: value
+            for key, value in values.items()
+            if key in _REPORT_FIELDS and isinstance(value, int)
+        }
+        current = replace(self, raw={**(self.raw or {}), **values})
+        current = replace(current, **cast(Any, changes))
+        if (
+            current.pack_input_power is not None
+            and current.output_pack_power is not None
+        ):
+            current = replace(
+                current,
+                battery_power=current.output_pack_power - current.pack_input_power,
+            )
+        return current
+
+    def with_identity(self, message: dict[str, object]) -> SolarFlowState:
+        device_id = message.get("deviceId")
+        product_key = message.get("productKey")
+        return replace(
+            self,
+            device_id=device_id if isinstance(device_id, str) else self.device_id,
+            product_key=product_key
+            if isinstance(product_key, str)
+            else self.product_key,
+        )
+
+    def with_packs(self, message: dict[str, object]) -> SolarFlowState:
+        raw_packs = message.get("packData")
+        if not isinstance(raw_packs, list):
+            return self
+        known = {pack.serial_number: pack for pack in self.packs}
+        for raw in raw_packs:
+            if not isinstance(raw, dict) or not isinstance(raw.get("sn"), str):
+                continue
+            serial_number = raw["sn"]
+            current = known.get(serial_number, BatteryPack(serial_number=serial_number))
+            changes = {
+                field: raw[key] for key, field in _PACK_FIELDS.items() if key in raw
+            }
+            known[serial_number] = replace(current, **cast(Any, changes))
+        return replace(self, packs=tuple(known.values()))
+
+
+@dataclass(frozen=True, slots=True)
+class SolarFlowUpdate:
+    """Typed state update delivered to an optional callback."""
+
+    state: SolarFlowState
+    status: ConnectionStatus
+    raw_message: dict[str, object]

solarflow_ble-0.1.1/src/solarflow_ble/protocol.py

@@ -0,0 +1,51 @@
+"""SolarFlow protocol helpers."""
+
+import json
+from typing import Any
+
+from .const import MANUFACTURER_ID
+from .exceptions import SolarFlowProtocolError
+from .models import Advertisement
+
+
+def parse_advertisement(
+    address: str,
+    manufacturer_data: dict[int, bytes],
+    *,
+    rssi: int | None = None,
+    connectable: bool = True,
+    address_type: int | None = None,
+) -> Advertisement | None:
+    """Parse the SolarFlow manufacturer advertisement."""
+    payload = manufacturer_data.get(MANUFACTURER_ID)
+    if payload is None:
+        return None
+    try:
+        identifier = (
+            payload[:-1].decode("ascii")
+            if payload.endswith(b"\x16")
+            else payload.decode("ascii")
+        )
+    except UnicodeDecodeError:
+        return None
+    return (
+        Advertisement(address, identifier, rssi, connectable, address_type)
+        if identifier
+        else None
+    )
+
+
+def decode_json(payload: bytes | bytearray) -> dict[str, Any]:
+    """Decode one JSON notification."""
+    try:
+        value = json.loads(bytes(payload))
+    except (UnicodeDecodeError, json.JSONDecodeError) as err:
+        raise SolarFlowProtocolError("Invalid SolarFlow JSON payload") from err
+    if not isinstance(value, dict):
+        raise SolarFlowProtocolError("SolarFlow payload is not an object")
+    return value
+
+
+def encode_json(message: dict[str, Any]) -> bytes:
+    """Encode compact JSON for C304."""
+    return json.dumps(message, separators=(",", ":"), ensure_ascii=False).encode()

solarflow_ble-0.1.1/src/solarflow_ble/transport.py

@@ -0,0 +1,106 @@
+"""BLE transport adapters for SolarFlow."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
+from typing import cast
+
+import bleak
+from bleak.backends.characteristic import BleakGATTCharacteristic
+from bleak.backends.device import BLEDevice
+from bleak_retry_connector import establish_connection
+
+from .client import BleTransport, NotificationCallback
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class BleakTransport(BleTransport):
+    """Adapt a Bleak client to the SolarFlow transport protocol."""
+
+    def __init__(
+        self,
+        device: BLEDevice,
+        *,
+        timeout: float = 30.0,
+        client_factory: Callable[..., bleak.BleakClient] | None = None,
+    ) -> None:
+        self.device = device
+        self.timeout = timeout
+        self._client_factory = (
+            client_factory if client_factory is not None else bleak.BleakClient
+        )
+        self._client: bleak.BleakClient | None = None
+        self._notification_tasks: set[asyncio.Task[None]] = set()
+        self._accept_notifications = True
+
+    @property
+    def client(self) -> bleak.BleakClient:
+        if self._client is None:
+            raise RuntimeError("SolarFlow BLE transport is not connected")
+        return self._client
+
+    async def connect(self) -> None:
+        self._accept_notifications = True
+        if self._client is None or not self._client.is_connected:
+            self._client = await establish_connection(
+                cast(type[bleak.BleakClient], self._client_factory),
+                self.device,
+                self.device.name or self.device.address,
+                timeout=self.timeout,
+            )
+
+    async def disconnect(self) -> None:
+        self._accept_notifications = False
+        await self._cancel_notification_tasks()
+        client = self._client
+        try:
+            if client is not None:
+                await client.disconnect()
+        finally:
+            self._client = None
+
+    async def start_notify(
+        self, characteristic: str, callback: NotificationCallback
+    ) -> None:
+        def on_notification(
+            gatt_characteristic: BleakGATTCharacteristic, payload: bytearray
+        ) -> None:
+            if not self._accept_notifications:
+                return
+            result = callback(gatt_characteristic.uuid, bytes(payload))
+            if isinstance(result, Awaitable):
+                task = asyncio.ensure_future(result)
+                self._notification_tasks.add(task)
+                task.add_done_callback(self._notification_task_done)
+
+        await self.client.start_notify(characteristic, on_notification)
+
+    async def stop_notify(self, characteristic: str) -> None:
+        if self._client is not None and self._client.is_connected:
+            await self._client.stop_notify(characteristic)
+
+    async def write_gatt_char(
+        self, characteristic: str, data: bytes, response: bool = False
+    ) -> None:
+        await self.client.write_gatt_char(characteristic, data, response=response)
+
+    def _notification_task_done(self, task: asyncio.Task[None]) -> None:
+        self._notification_tasks.discard(task)
+        if task.cancelled():
+            return
+        with suppress(asyncio.CancelledError):
+            error = task.exception()
+        if error is not None:
+            _LOGGER.error("SolarFlow notification callback failed", exc_info=error)
+
+    async def _cancel_notification_tasks(self) -> None:
+        tasks = tuple(self._notification_tasks)
+        if not tasks:
+            return
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)