voltkeeper 2026.5__py3-none-any.whl

voltkeeper/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '2026.5'
+__version_tuple__ = version_tuple = (2026, 5)
+
+__commit_id__ = commit_id = None

voltkeeper/annotate.py

@@ -0,0 +1,325 @@
+# ABOUTME: Interactive annotate REPL — live polling, register-change detection, field-name prompts.
+# ABOUTME: Unit 13 per IMPLEMENTATION_UNITS.md.
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import click
+import yaml
+
+from .bluetooth.client import BluetoothClient
+from .core.commands import ReadHoldingRegisters
+from .probe import V1_BLOCKS, V2_BLOCKS, _detect_protocol
+from .scrub import SYNTHETIC_SN_STR, scrub_profile, split_model_sn
+
+# ── Diff helper ───────────────────────────────────────────────────────
+
+
+def _diff(prev: bytes | None, curr: bytes) -> list[tuple[int, int, int]]:
+    """Compare two byte sequences, return (offset, old_byte, new_byte) for each change.
+
+    If *prev* is None (first read), returns empty list.
+    Diffs only up to the shorter of the two lengths.
+    """
+    if prev is None:
+        return []
+    length = min(len(prev), len(curr))
+    changes: list[tuple[int, int, int]] = []
+    for i in range(length):
+        if prev[i] != curr[i]:
+            changes.append((i, prev[i], curr[i]))
+    return changes
+
+
+# ── File helpers ──────────────────────────────────────────────────────
+
+
+def _load_or_init(profile_path: Path) -> dict:
+    """Load an existing YAML profile or return a fresh skeleton."""
+    if profile_path.exists():
+        with open(profile_path) as f:
+            profile = yaml.safe_load(f)
+        if isinstance(profile, dict):
+            return profile
+    return {"annotations": []}
+
+
+def _save(profile: dict, profile_path: Path) -> None:
+    """Atomically write *profile* to *profile_path* as YAML.
+
+    Writes to a sibling temp file then ``os.replace``s it into place so
+    a Ctrl-C mid-write can't truncate an existing valid YAML.
+    """
+    import os
+
+    profile_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = profile_path.with_suffix(profile_path.suffix + ".tmp")
+    with open(tmp_path, "w") as f:
+        yaml.dump(profile, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
+        f.flush()
+        os.fsync(f.fileno())
+    os.replace(tmp_path, profile_path)
+
+
+def _save_scrubbed(profile: dict, profile_path: Path) -> None:
+    """Save *profile* with the SN replaced by a synthetic placeholder.
+
+    Use this for any annotate persistence: the in-memory dict keeps the
+    real BLE name for registry-shortcut lookups across sessions, while
+    the on-disk YAML is privacy-safe to share.
+    """
+    _save(scrub_profile(profile), profile_path)
+
+
+# ── UX helpers ────────────────────────────────────────────────────────
+
+
+def _registry_field_hints() -> list[str]:
+    """Collect the union of WRITABLE_FIELD_NAMES across registered devices.
+
+    Surfaced to the user at session start so they have a vocabulary to
+    pull from when labelling changed bytes.
+    """
+    from .bluetooth import _device_registry
+
+    names: set[str] = set()
+    for cls in _device_registry().values():
+        names.update(getattr(cls, "WRITABLE_FIELD_NAMES", []))
+    return sorted(names)
+
+
+BASELINE_POLLS = 10
+"""Cycles to observe at session start before listening for user-driven changes.
+
+At ~1 second per cycle, ~10 polls is enough to catch the obvious noise
+(currents, energy counters, frequency drift) without making the user wait
+forever before they can interact with the device. Slowly-changing fields
+(SOC ticks every few minutes, chgFullTime once a minute) won't show up
+during baseline and will trigger one-off "spurious" changes during the
+listening phase — acceptable cost.
+"""
+
+
+def _annotation_index(profile: dict) -> dict[tuple[str, int], str]:
+    """Build a ``(block_name, offset) → name`` lookup from ``profile['annotations']``.
+
+    Used to surface the existing label for an already-labelled byte
+    when it changes again. Last entry wins on duplicate keys, matching
+    the latest-wins semantics enforced by ``_replace_annotation``.
+    """
+    out: dict[tuple[str, int], str] = {}
+    for entry in profile.get("annotations", []) or []:
+        if not isinstance(entry, dict):
+            continue
+        block = entry.get("block")
+        offset = entry.get("offset")
+        name = entry.get("name")
+        if isinstance(block, str) and isinstance(offset, int) and isinstance(name, str):
+            out[(block, offset)] = name
+    return out
+
+
+def _replace_annotation(profile: dict, block: str, offset: int, name: str) -> None:
+    """Set the annotation for ``(block, offset)`` to *name*, removing any prior entry.
+
+    Latest-wins: typing a new name for an already-labelled byte replaces
+    the old label rather than stacking another entry alongside it. Keeps
+    the YAML clean for downstream maintainer consumption.
+    """
+    annotations = profile.setdefault("annotations", [])
+    profile["annotations"] = [
+        e for e in annotations if not (isinstance(e, dict) and e.get("block") == block and e.get("offset") == offset)
+    ]
+    profile["annotations"].append({"block": block, "offset": offset, "name": name})
+
+
+async def _capture_baseline(
+    client: BluetoothClient,
+    blocks: list[tuple[int, int, str]],
+    polls: int = BASELINE_POLLS,
+) -> tuple[dict[str, bytes], dict[str, set[int]]]:
+    """Sample blocks for *polls* cycles. Return (last snapshot, volatile bytes).
+
+    A byte offset is "volatile" if its value changed at any point during
+    the baseline window — the listening loop suppresses changes at
+    those offsets so the user only sees signal from their own actions.
+    """
+    history: dict[str, list[bytes]] = {}
+    for cycle in range(polls):
+        for addr, size, block_name in blocks:
+            resp = await client.execute(ReadHoldingRegisters(addr, size))
+            history.setdefault(block_name, []).append(resp)
+        # In-place progress; final newline printed by caller.
+        click.echo(f"  baseline poll {cycle + 1}/{polls}\r", nl=False)
+        if cycle < polls - 1:
+            await asyncio.sleep(1)
+    click.echo()  # finalize the progress line
+
+    last: dict[str, bytes] = {}
+    volatile: dict[str, set[int]] = {}
+    for block_name, snapshots in history.items():
+        last[block_name] = snapshots[-1]
+        offsets: set[int] = set()
+        for i in range(1, len(snapshots)):
+            for offset, _, _ in _diff(snapshots[i - 1], snapshots[i]):
+                offsets.add(offset)
+        volatile[block_name] = offsets
+    return last, volatile
+
+
+def _format_change(block_name: str, addr: int, offset: int, old_byte: int, new_byte: int) -> str:
+    """Render a one-line description of a changed byte using register coords.
+
+    Modbus addresses things by register (16-bit word), so reporting
+    register + byte-within-register is more useful than a raw byte
+    offset when the user later wants to look it up in FINDINGS or the
+    APK.
+    """
+    register = addr + (offset // 2)
+    byte_in_reg = offset % 2
+    return f"  [{block_name} reg {register} byte {byte_in_reg}]: 0x{old_byte:02X} → 0x{new_byte:02X}"
+
+
+def _print_intro(profile_path: Path, model_sn: tuple[str, str] | None, num_blocks: int, hints: list[str]) -> None:
+    """One-screen onboarding shown before polling starts.
+
+    Explains the workflow (toggle on the device → watch the diff →
+    label) and lists known field names so the user has a vocabulary.
+    """
+    if model_sn:
+        model, real_sn = model_sn
+        click.echo(f"\nAnnotating {model} SN {real_sn} → {profile_path}")
+        click.echo(f"(SN scrubbed to {SYNTHETIC_SN_STR} in the saved file)\n")
+    else:
+        click.echo(f"\nAnnotating → {profile_path}\n")
+
+    click.secho("How this works:", bold=True)
+    click.echo("  1. Make a change on the device (toggle a switch, change a mode,")
+    click.echo("     wait for SOC to tick down).")
+    click.echo("  2. Watch which bytes change in the output below.")
+    click.echo("  3. Type a short field name when prompted, or press Enter to skip.")
+    click.echo("  4. Repeat for each thing you want to map.\n")
+
+    if hints:
+        click.secho("Common field names from existing models:", bold=True)
+        # Wrap the hint list to fit a typical terminal width without dominating.
+        wrapped = click.wrap_text(", ".join(hints), width=72, initial_indent="  ", subsequent_indent="  ")
+        click.echo(wrapped + "\n")
+
+    click.echo(f"Polling {num_blocks} register blocks. Press Ctrl-C to stop.\n")
+
+
+# ── Annotate loop ─────────────────────────────────────────────────────
+
+
+async def annotate_loop(
+    address: str,
+    profile_path: Path,
+    *,
+    encrypted: bool,
+    device_name: str = "",
+) -> None:
+    """Connect, poll register blocks, prompt for field names on changes.
+
+    *device_name* is the BLE-advertised name (e.g., ``"AC2A2305000"``).
+    Passing it lets ``_detect_protocol`` take the registry shortcut on
+    the first run, before the profile YAML has a ``name`` field stored.
+    """
+    profile = _load_or_init(profile_path)
+    client = BluetoothClient(address, encrypted=encrypted)
+    await client.connect()
+
+    try:
+        # Prefer the live BLE name; fall back to whatever the saved profile has.
+        detect_name = device_name or profile.get("name", "") or ""
+        info = await _detect_protocol(client, detect_name)
+
+        if info.kind == "unknown":
+            # Fall back to sweeping known V1 blocks
+            blocks: list[tuple[int, int, str]] = [
+                (addr, size_fn(0), block_name) for addr, block_name, size_fn in V1_BLOCKS
+            ]
+        elif info.kind == "v1":
+            ver = info.version or 0
+            blocks = [(addr, size_fn(ver), block_name) for addr, block_name, size_fn in V1_BLOCKS]
+        else:
+            blocks = list(V2_BLOCKS)
+
+        if not blocks:
+            click.secho("No register blocks to poll.", fg="yellow")
+            return
+
+        # Save protocol info into the profile for future runs
+        profile.setdefault("protocol", info.kind)
+        profile.setdefault("protocol_version", info.version)
+        profile.setdefault("address", address)
+        profile.setdefault("encrypted", encrypted)
+        if detect_name:
+            profile.setdefault("name", detect_name)
+        _save_scrubbed(profile, profile_path)
+
+        _print_intro(
+            profile_path=profile_path,
+            model_sn=split_model_sn(detect_name),
+            num_blocks=len(blocks),
+            hints=_registry_field_hints(),
+        )
+
+        click.echo(f"Capturing baseline ({BASELINE_POLLS} polls) to identify noisy fields...")
+        last, volatile = await _capture_baseline(client, blocks, polls=BASELINE_POLLS)
+        suppressed = sum(len(s) for s in volatile.values())
+        click.echo(f"Baseline captured. Suppressing {suppressed} volatile byte(s) from change detection.")
+        click.echo("Make a change on the device now.\n")
+
+        # Lookup of (block, offset) → name from any prior session's annotations.
+        # Refreshed in-place as the user adds new labels.
+        annotations_index = _annotation_index(profile)
+
+        while True:
+            cycle_changes: list[tuple[str, int, int, int, int]] = []
+            for addr, size, block_name in blocks:
+                resp = await client.execute(ReadHoldingRegisters(addr, size))
+                prev = last.get(block_name)
+                vol = volatile.get(block_name, set())
+                for offset, old_byte, new_byte in _diff(prev, resp):
+                    if offset in vol:
+                        continue
+                    cycle_changes.append((block_name, addr, offset, old_byte, new_byte))
+                last[block_name] = resp
+
+            if cycle_changes:
+                click.echo("─" * 60)
+                click.echo(f"{len(cycle_changes)} byte(s) changed:")
+                for block_name, addr, offset, old, new in cycle_changes:
+                    line = _format_change(block_name, addr, offset, old, new)
+                    existing = annotations_index.get((block_name, offset))
+                    if existing:
+                        line += click.style(f"   (currently: {existing})", fg="cyan")
+                    click.echo(line)
+                try:
+                    field_name = click.prompt(
+                        "\nField name for these changes (Enter to skip)",
+                        default="",
+                        show_default=False,
+                    )
+                except (click.Abort, EOFError, KeyboardInterrupt):
+                    click.echo()
+                    return
+                if field_name.strip():
+                    name_clean = field_name.strip()
+                    for block_name, _addr, offset, _old, _new in cycle_changes:
+                        _replace_annotation(profile, block_name, offset, name_clean)
+                        annotations_index[(block_name, offset)] = name_clean
+                    _save_scrubbed(profile, profile_path)
+                    click.echo(f"  ✓ recorded {len(cycle_changes)} entries as {name_clean!r}\n")
+                else:
+                    click.echo("  (skipped)\n")
+
+            await asyncio.sleep(1)
+
+    except (KeyboardInterrupt, click.Abort):
+        click.echo("\nStopped.")
+    finally:
+        await client.disconnect()

voltkeeper/bluetooth/__init__.py

@@ -0,0 +1,156 @@
+# ABOUTME: BLE scan utilities — service-UUID-based scan, device factory, encryption classification.
+
+import re
+import sys
+from dataclasses import dataclass
+
+import click
+from bleak import BleakScanner
+
+SERVICE_UUID = "0000ff00-0000-1000-8000-00805f9b34fb"
+WRITE_UUID = "0000ff02-0000-1000-8000-00805f9b34fb"
+NOTIFY_UUID = "0000ff01-0000-1000-8000-00805f9b34fb"
+_DEVICE_NAME_SN_RE = re.compile(r"^(AC2A|AC60|EP600|EP500|EB3A|AC300|AC500|AC200L|AC200PL|AC200M)(\d+)$")
+
+PREFIX_PLAINTEXT = bytes.fromhex("424c5545545449")
+PREFIX_ENCRYPTED = (
+    bytes.fromhex("424c5545545445"),
+    bytes.fromhex("424c5545545446"),
+)
+
+
+@dataclass(frozen=True)
+class ScanResult:
+    address: str
+    name: str
+    encrypted: bool | None
+
+    def display(self) -> str:
+        flag = "encrypted" if self.encrypted else "plaintext" if self.encrypted is False else "unknown"
+        return f"{self.address}  —  {self.name}  [{flag}]"
+
+
+def _parse_sn(name: str) -> str:
+    m = _DEVICE_NAME_SN_RE.match(name.strip())
+    if m:
+        return m[2]
+    return name.replace(":", "").replace("-", "")
+
+
+async def lookup_scan_result(address: str, timeout: float = 5.0) -> ScanResult:
+    devices = await BleakScanner.discover(
+        timeout=timeout,
+        service_uuids=[SERVICE_UUID],
+        return_adv=True,
+    )
+    for addr, (device, adv) in devices.items():
+        if addr.upper() == address.upper():
+            name = (device.name or adv.local_name or "").strip()
+            if not name:
+                name = address
+            encrypted = _classify(adv)
+            return ScanResult(address=address, name=name, encrypted=encrypted)
+    return ScanResult(address=address, name=address, encrypted=None)
+
+
+def _classify(adv) -> bool | None:
+    for blob in adv.manufacturer_data.values():
+        if blob.startswith(PREFIX_PLAINTEXT):
+            return False
+        if any(blob.startswith(p) for p in PREFIX_ENCRYPTED):
+            return True
+    return None
+
+
+async def scan_devices(timeout: float = 10.0) -> list[ScanResult]:
+    click.echo(f"Scanning for Bluetti devices (service {SERVICE_UUID}) ...")
+    devices = await BleakScanner.discover(
+        timeout=timeout,
+        service_uuids=[SERVICE_UUID],
+        return_adv=True,
+    )
+
+    found: list[ScanResult] = []
+    for address, (device, adv) in devices.items():
+        name = (device.name or adv.local_name or "").strip()
+        if not name:
+            name = "(unknown)"
+        encrypted = _classify(adv)
+        found.append(ScanResult(address=address, name=name, encrypted=encrypted))
+
+    return sorted(found, key=lambda x: x.address)
+
+
+async def pick_address_after_scan() -> ScanResult:
+    devices = await scan_devices()
+
+    if not devices:
+        click.secho("\nNo Bluetti devices found.", fg="red")
+        click.echo("Make sure the device is powered on and in Bluetooth range.")
+        sys.exit(1)
+
+    if len(devices) == 1:
+        sr = devices[0]
+        click.echo(f"\nFound 1 device \u2192 auto-selecting: {sr.display()}")
+        return sr
+
+    click.echo(f"\nFound {len(devices)} Bluetti devices:\n")
+    for i, sr in enumerate(devices, 1):
+        click.echo(f"  [{click.style(str(i), fg='cyan')}] {sr.display()}")
+
+    click.echo()
+    while True:
+        try:
+            choice = input(f"Select device (1-{len(devices)}): ").strip()
+            idx = int(choice) - 1
+            if 0 <= idx < len(devices):
+                return devices[idx]
+        except (ValueError, EOFError, KeyboardInterrupt):
+            click.echo()
+            sys.exit(1)
+        click.echo(f"Enter a number between 1 and {len(devices)}.")
+
+
+def _device_registry() -> dict[str, type]:
+    from ..core.devices.ac2a import AC2A
+    from ..core.devices.ac60 import AC60
+    from ..core.devices.ac200l import AC200L
+    from ..core.devices.ac200m import AC200M
+    from ..core.devices.ac200pl import AC200PL
+    from ..core.devices.ac300 import AC300
+    from ..core.devices.ac500 import AC500
+    from ..core.devices.eb3a import EB3A
+    from ..core.devices.ep500 import EP500
+    from ..core.devices.ep600 import EP600
+
+    return {
+        "AC2A": AC2A,
+        "AC60": AC60,
+        "AC200L": AC200L,
+        "AC200M": AC200M,
+        "AC200PL": AC200PL,
+        "AC300": AC300,
+        "AC500": AC500,
+        "EB3A": EB3A,
+        "EP500": EP500,
+        "EP600": EP600,
+    }
+
+
+def device_registry() -> dict[str, type]:
+    return _device_registry()
+
+
+def is_supported_device_type(prefix: str) -> bool:
+    return prefix in _device_registry()
+
+
+def build_device(address: str, name: str):
+    sn = _parse_sn(name)
+    prefix_match = _DEVICE_NAME_SN_RE.match(name.strip())
+    prefix: str | None = prefix_match[1] if prefix_match else None
+    registry = _device_registry()
+    cls = registry.get(prefix) if prefix else None
+    if cls is None:
+        raise ValueError(f"Unsupported device model: {name!r}. Known prefixes: {sorted(registry)}")
+    return cls(address, sn)

voltkeeper/bluetooth/cipher.py

@@ -0,0 +1,59 @@
+# ABOUTME: AES-128-CBC cipher with chained IV and zero-padding (no PKCS) for Bluetti BLE encryption.
+# ABOUTME: Unit 5 per IMPLEMENTATION_UNITS.md.
+#
+# Framing note: encrypt() zero-pads to a 16-byte boundary. decrypt() returns
+# the full block-aligned plaintext including any padding bytes — it does NOT
+# strip trailing zeros, because the Bluetti protocol carries plaintext bytes
+# that legitimately end in 0x00 (Modbus register values < 256, CRC high
+# bytes, ECDSA signature/checksum bytes, etc.). The upper layer (Modbus
+# parser, handshake state machine) determines actual payload length from
+# protocol-level fields and ignores trailing pad bytes.
+
+import hashlib
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+
+def derive_iv(random_md5_hex: str) -> bytes:
+    return hashlib.md5(random_md5_hex.encode("ascii")).digest()
+
+
+def _zero_pad(data: bytes, block: int = 16) -> bytes:
+    if len(data) % block == 0:
+        return data
+    return data + b"\x00" * (block - len(data) % block)
+
+
+def encrypt(plaintext: bytes, key: bytes, iv: bytes) -> bytes:
+    if len(key) != 16:
+        raise ValueError("AES-128 key must be 16 bytes")
+    if len(iv) != 16:
+        raise ValueError("IV must be 16 bytes")
+    padded = _zero_pad(plaintext)
+    cipher = Cipher(algorithms.AES(key), modes.CBC(iv))
+    enc = cipher.encryptor()
+    return enc.update(padded) + enc.finalize()
+
+
+def decrypt(ciphertext: bytes, key: bytes, iv: bytes) -> bytes:
+    if len(ciphertext) % 16 != 0:
+        raise ValueError("Ciphertext length must be a multiple of 16")
+    cipher = Cipher(algorithms.AES(key), modes.CBC(iv))
+    dec = cipher.decryptor()
+    return dec.update(ciphertext) + dec.finalize()
+
+
+class CbcSession:
+    def __init__(self, key: bytes, initial_iv: bytes):
+        self._key = key
+        self._iv = initial_iv
+
+    def encrypt(self, plaintext: bytes) -> bytes:
+        ct = encrypt(plaintext, self._key, self._iv)
+        self._iv = ct[-16:]
+        return ct
+
+    def decrypt(self, ciphertext: bytes) -> bytes:
+        pt = decrypt(ciphertext, self._key, self._iv)
+        self._iv = ciphertext[-16:]
+        return pt

voltkeeper/bluetooth/client.py

@@ -0,0 +1,114 @@
+# ABOUTME: BLE client for Bluetti devices — connect, execute Modbus commands, disconnect. No auto-reconnect.
+# ABOUTME: Supports optional AES-CBC encryption via handshake (Unit 7).
+
+import asyncio
+from typing import Optional
+
+from bleak import BleakClient, BleakError
+
+from ..core.commands import DeviceCommand
+from . import NOTIFY_UUID, WRITE_UUID
+from .cipher import CbcSession
+from .exc import BadConnectionError, ModbusError, ParseError
+from .handshake import HandshakeSession
+
+RESPONSE_TIMEOUT = 5
+MAX_RETRIES = 5
+
+
+class BluetoothClient:
+    def __init__(self, address: str, *, encrypted: bool = False):
+        self.address = address
+        self.encrypted = encrypted
+        self.client: Optional[BleakClient] = None
+        self._session: Optional[CbcSession] = None
+        self._notify_response = bytearray()
+        self._notify_future: Optional[asyncio.Future] = None
+        self._current_cmd: Optional[DeviceCommand] = None
+
+    async def connect(self, timeout: float = 15.0) -> None:
+        self.client = BleakClient(self.address)
+        await self.client.connect(timeout=timeout)
+        if self.encrypted:
+            self._session = await HandshakeSession().run(self.client)
+        await self.client.start_notify(NOTIFY_UUID, self._on_notification)  # type: ignore[arg-type]
+
+    @property
+    def is_connected(self) -> bool:
+        return self.client is not None and self.client.is_connected
+
+    async def disconnect(self) -> None:
+        if self.client and self.client.is_connected:
+            try:
+                await self.client.disconnect()
+            except BleakError:
+                pass
+
+    async def execute(self, cmd: DeviceCommand) -> bytes:
+        loop = asyncio.get_running_loop()
+        retries = 0
+
+        while True:
+            self._current_cmd = cmd
+            self._notify_future = loop.create_future()
+            self._notify_response = bytearray()
+
+            try:
+                assert self.client is not None
+                outgoing = bytes(cmd)
+                if self._session:
+                    outgoing = self._session.encrypt(outgoing)
+                await self.client.write_gatt_char(WRITE_UUID, outgoing, response=False)
+                resp = await asyncio.wait_for(self._notify_future, timeout=RESPONSE_TIMEOUT)
+            except ParseError:
+                retries += 1
+                if retries >= MAX_RETRIES:
+                    raise BadConnectionError(f"Too many retries on {cmd}")
+                continue
+            except asyncio.TimeoutError:
+                retries += 1
+                if retries >= MAX_RETRIES:
+                    raise BadConnectionError(f"Timeout on {cmd} after {MAX_RETRIES} retries")
+                continue
+
+            if self._session:
+                resp = self._session.decrypt(resp)
+                resp = resp[: cmd.response_size()]
+                if not cmd.is_valid_response(resp):
+                    retries += 1
+                    if retries >= MAX_RETRIES:
+                        raise BadConnectionError(
+                            "Encrypted handshake completed but Modbus responses do not validate. "
+                            "This device may require the per-SN key-binding step that Bluetti's "
+                            "licensed library performs (status 3 in ble_crypt_link_handler). "
+                            "Run with -v to capture the handshake transcript and open an issue."
+                        )
+                    continue
+
+            if cmd.is_exception_response(resp):
+                raise ModbusError(f"Modbus exception code: {resp[2]}")
+            return cmd.parse_response(resp)
+
+    async def perform_nowait(self, cmd: DeviceCommand) -> None:
+        await self.execute(cmd)
+
+    def _on_notification(self, _sender: int, data: bytearray) -> None:
+        if not self._notify_future or self._notify_future.done():
+            return
+
+        if data == b"AT+NAME?\r" or data == b"AT+ADV?\r":
+            self._notify_future.set_exception(BadConnectionError("Got AT+ notification"))
+            return
+
+        self._notify_response.extend(data)
+
+        assert self._current_cmd is not None
+        response_size = self._current_cmd.response_size()
+        expected = ((response_size + 15) // 16) * 16 if self._session else response_size
+
+        if len(self._notify_response) >= expected:
+            raw = bytes(self._notify_response[:expected])
+            if not self._session and not self._current_cmd.is_valid_response(raw):
+                self._notify_future.set_exception(ParseError("CRC check failed"))
+            else:
+                self._notify_future.set_result(raw)

voltkeeper/bluetooth/exc.py

@@ -0,0 +1,13 @@
+# ABOUTME: BLE/Modbus exception types used across the bluetooth layer.
+
+
+class ParseError(Exception):
+    pass
+
+
+class ModbusError(Exception):
+    pass
+
+
+class BadConnectionError(Exception):
+    pass