aosmith-ble 0.1.0__tar.gz

aosmith_ble-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

aosmith_ble-0.1.0/.github/ISSUE_TEMPLATE/device-support.yml

@@ -0,0 +1,44 @@
+name: Device support request
+description: Ask for support for a heater that connect() refuses, using the diagnostic report.
+title: "Device support: <model> firmware <x.y>"
+labels: ["device-support"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping. This only covers **read-only** support to start with. Nothing here
+        promises support for a model, and write support needs an observed write for the exact
+        model and firmware.
+
+        Run `AOSmithBLEClient.async_diagnose()` and paste `report.to_markdown()` below (it is
+        redacted by default; never use `redact=False`). See
+        "Does my heater work?" in the documentation for the steps.
+  - type: input
+    id: model
+    attributes:
+      label: Model on the rating plate
+      description: For example the model line, not the serial number.
+    validations:
+      required: true
+  - type: textarea
+    id: report
+    attributes:
+      label: Diagnostic report
+      description: Paste the output of `report.to_markdown()`.
+      render: markdown
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: Anything else
+      description: Does the official app work with this heater? Did the Bluetooth button press change anything?
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: My report has no Bluetooth address, no 18-character `02iQk...` value and no full serial number.
+          required: true
+        - label: I understand the diagnostic call only reads, and that support is not guaranteed.
+          required: true

aosmith_ble-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uv sync --python ${{ matrix.python-version }}
+      - run: uv run pytest -q
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uvx prek run --all-files
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uvx zensical build --clean --strict

aosmith_ble-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - run: pip install zensical
+      - run: zensical build --clean --strict
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+      - uses: actions/deploy-pages@v5
+        id: deployment

aosmith_ble-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+on:
+  push:
+    tags:
+      - "v*"
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: Tag must match the pyproject version
+        run: |
+          version="$(uv version --short)"
+          if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "tag ${GITHUB_REF_NAME} does not match pyproject version ${version}" >&2
+            exit 1
+          fi
+      - run: uv sync
+      - run: uv run pytest -q
+      - run: uv build
+      - name: Smoke test the built wheel
+        run: uv run --isolated --no-project --with dist/*.whl python -I -c "import aosmith_ble; print(aosmith_ble.__version__)"
+      - uses: actions/upload-artifact@v7.0.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/aosmith-ble
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@v1.14.2

aosmith_ble-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+site/

aosmith_ble-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+# Run with prek (https://github.com/j178/prek): `prek install`, then `prek run --all-files`.
+# prek reads this file and is compatible with the pre-commit config format.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-case-conflict
+      - id: detect-private-key
+      - id: end-of-file-fixer
+        exclude: "^LICENSE$"
+      - id: mixed-line-ending
+        args: ["--fix=lf"]
+      - id: trailing-whitespace
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.2
+    hooks:
+      - id: codespell
+        additional_dependencies: [tomli]
+        exclude: "^(uv.lock|tests/fixtures/.*)$"
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.6
+    hooks:
+      - id: ruff-check
+      - id: ruff-format
+  - repo: https://github.com/tox-dev/pyproject-fmt
+    rev: v2.18.1
+    hooks:
+      - id: pyproject-fmt
+  - repo: local
+    hooks:
+      - id: check-identifiers
+        name: block real device identifiers
+        entry: python scripts/check_identifiers.py
+        language: system
+        pass_filenames: true
+        exclude: "^uv.lock$"

aosmith_ble-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+## 0.1.0
+
+- `connect()` after a link lost under the client now closes the dead link
+  before opening a new one. Without this the heater rejected the new session
+  (hardware-observed), so a reused client could not reconnect after an
+  unexpected drop.
+- `AOSmithBLEClient` takes three optional keyword-only hooks for embedding in a
+  long-running application: `client_class` (the bleak client class to connect
+  with), `device_resolver` (a callback returning the freshest `BLEDevice`, used
+  on every connect and every connection retry), and `on_disconnect` (a callback
+  for unexpected link loss). All default to the previous behavior.
+- `bleak-retry-connector` is now imported unconditionally; the unreachable
+  fallback to a bare `BleakClient` is gone.
+- `HeaterState` is removed. `AOSmithBLEClient.async_get_state()` now returns a
+  `FeatureSet` (`Mapping[FieldName, Feature]`) -- a `Feature` per profile
+  field graded at least `min_trust` (default `Trust.OK`), each carrying its
+  own `value`, `trust`, and `writable`. A field graded below `min_trust` is
+  absent from the mapping, never present with a placeholder.
+- `FieldName` (a `StrEnum`) and `FieldScope` (`STATE`/`IDENTITY`) replace bare
+  string field names and the implicit assumption that every field lives in
+  Block 11.
+- `DeviceInfo.serial` is now populated, once, at connect time.
+- New `AOSmithBLEClient.async_diagnose()`: an independent connect/probe/
+  disconnect sequence that works even for a device `connect()` would refuse
+  outright, producing a `DiagnosticReport` with the existing `to_markdown()`
+  plus a new `to_fixture_entries()` -- redacted, `tests/fixtures/frames.json`-
+  shaped output suitable for a new-profile contribution PR.
+- `Profile`/`FieldSpec`/`Match` device-profile system, with `__post_init__` structural
+  validation and inheritance (write trust demoted unless re-asserted).
+- One bundled profile (`hpts50-6.3`).
+- The connecting, writing async client (`AOSmithBLEClient`): session establishment,
+  profile matching, MTU and UNITS validation, state reads, and a single profile-gated
+  write choke point with fault-active read-only gating and write-then-read-back
+  verification.
+- Release-on-demand and `BleakOutOfConnectionSlotsError` wrapping.
+- Presence probing and the unknown-device diagnostic report.
+- Distinguishes the two 7-byte short-response forms (`ReadRefusedError` vs.
+  `SessionError`) that the 0.0.1 release's `parse_read` treated identically.
+
+## 0.0.1 - Unreleased
+
+- Initial protocol layer: frame construction/parsing, CRC-8, the session
+  handshake (pairing-slot init, challenge/response), setpoint and mode
+  codecs, fault code table.
+- No Bluetooth I/O in this release; frame building and parsing only.

aosmith_ble-0.1.0/CLAUDE.md

@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+Guidance for working in this repository.
+
+## What this is
+
+`aosmith-ble` is a Python library plus a documentation site for local Bluetooth LE
+control of A.O. Smith iCOMM heat pump water heaters (no cloud). The library is in
+`src/aosmith_ble/` (client, protocol, profiles, codecs, diagnostics). The protocol
+knowledge and research record are in `docs/`, built with Zensical. Python only.
+
+## Commands
+
+```bash
+uv sync
+uv run pytest -q                  # the test suite, no hardware needed
+uvx zensical serve                # live docs preview
+uvx zensical build --clean --strict   # must pass with zero warnings
+```
+
+Use `uv`/`uvx` for all Python work, `rg` for searching, `fd` for finding files.
+
+## Layout
+
+- `src/aosmith_ble/protocol.py`, `crc.py`: frame building and parsing, CRC-8.
+- `src/aosmith_ble/profiles/`: per-model field maps and trust grades.
+- `src/aosmith_ble/client.py`: the connecting client. All writes go through one profile-gated path.
+- `tests/`: unit tests with fixtures in `tests/fixtures/frames.json`.
+- `docs/protocol/`, `docs/hardware/`, `docs/research/`, `docs/development/`: the site.
+  The nav lives in `zensical.toml`; every page must be listed there.
+- `docs/superpowers/`: working plans and specs, if present. Excluded from the published
+  site by the exclude plugin in `zensical.toml`, so never link to it as a site page.
+
+## Safety rules
+
+- Research is read-only. Never send a write whose encoding is not proven (byte-for-byte match with a captured frame, or a verified round trip).
+- No speculative writes, no raw-write API, no blind write retries.
+- Never raise the setpoint casually. Writes are capped at 140F absolute and 130F by default; the handbook range is 95-150F.
+- Timed-mode writes are stateful: the device counts days down and reverts at zero. The setpoint is a scalar, not per-mode.
+- GUEST mode has never been observed written; do not add it to any profile's `writable_modes` until a write is observed.
+- Exploratory reads at non-zero start offsets coincided with a change in Block 11 params 9 and 14 (causation unproven). Keep reads to what the app does.
+
+## Hardware facts that cost time
+
+- Only one central can connect at a time. Stop other clients first.
+- A stale BlueZ connection blocks discovery (the heater stops advertising while connected): `bluetoothctl disconnect <mac>`.
+- After about 10 minutes with no traffic the heater sleeps and needs a Bluetooth button
+  press to wake.
+- The central must answer the heater's ATT MTU request or no notifications arrive.
+- The proprietary service UUID is not advertised. Discovery matches on the `iCOMM-*`
+  local name.
+
+## Docs rules
+
+- Tag every protocol claim as verified on hardware, from the handbook, or unverified. Never upgrade confidence while moving text.
+- Never put a real MAC, serial, assetID, pairing code or advertised name in docs,
+  fixtures or tests. Use `AA:BB:CC:DD:EE:FF`, `iCOMM-AC000W037XXXXXX`,
+  `02iQk000000EXAMPLE`, `XXXXXX`, `<plate serial>`. Part number `100350404` and model
+  `HPTS-50` are model-level and fine.
+- Test vectors are synthetic. See `docs/development/test-vectors.md` before changing
+  `ASSET_ID` or `frames.json`.
+- docs/research and docs/hardware are language-neutral: no code snippets or library
+  references. State current facts only; no revision history or dates.
+- Use `!!! warning` admonitions, not GitHub-style alerts, and relative links only.

aosmith_ble-0.1.0/LICENSE

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

aosmith_ble-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: aosmith-ble
+Version: 0.1.0
+Summary: Local Bluetooth LE client for A.O. Smith iCOMM heat pump water heaters
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: bleak-retry-connector>=3.4
+Requires-Dist: bleak>=0.21
+Description-Content-Type: text/markdown
+
+# aosmith-ble
+
+Local Bluetooth LE control of A.O. Smith iCOMM heat pump water heaters -- no cloud
+account, no vendor credentials, no internet connection involved. This project is
+independent and unaffiliated with A.O. Smith.
+
+Documentation: see the `docs/` folder or the project site.
+
+Looking for the cloud API instead? See [py-aosmith](https://github.com/bdr99/py-aosmith).
+
+## What this is
+
+An async client that connects directly to a water heater's BLE interface, matches it against a bundled device profile, and reads or writes only what that profile has verified. An unrecognized device is refused outright. To help add support for a new device, call `AOSmithBLEClient.async_diagnose()`. It connects, probes and disconnects on its own (so it works even where `connect()` refuses) and returns a `DiagnosticReport`: `to_markdown()` gives a human-readable report and `to_fixture_entries()` gives redacted, fixture-shaped captures for a profile-contribution PR.
+
+## Install
+
+    pip install git+https://github.com/stumpylog/aosmith-ble
+
+## Quickstart
+
+```python
+import asyncio
+from aosmith_ble import AOSmithBLEClient, FieldName, Mode, async_discover, pairing_code_from_name
+
+async def main():
+    devices = await async_discover()
+    device = devices[0]
+    code = pairing_code_from_name(device.name)
+    async with AOSmithBLEClient(device, pairing_code=code) as client:
+        features = await client.async_get_state()
+        setpoint = features[FieldName.SETPOINT].value
+        mode = features[FieldName.MODE].value
+        fault = features[FieldName.FAULT].value
+        print(f"{setpoint}F, mode={Mode(mode.mode).name}, fault={fault.name}")
+        await client.async_set_setpoint(124.0)
+
+asyncio.run(main())
+```
+
+## Pairing
+
+Press the Bluetooth button on the control panel once before first use. The device hands out the "assetID" it authenticates sessions against only while its pairing slot is populated. Cache `AOSmithBLEClient.asset_id` (for example with the device address) and pass it back as `asset_id=` so the button press is a one-time step.
+
+## Embedding in a long-running application
+
+A host that owns Bluetooth scanning and wants the client to survive reconnects can pass three optional, keyword-only hooks:
+
+```python
+client = AOSmithBLEClient(
+    device,
+    pairing_code=code,
+    asset_id=cached_asset_id,
+    device_resolver=lambda: my_scanner.latest_device(address),
+    client_class=MyBleakClientSubclass,
+    on_disconnect=lambda: schedule_reconnect(),
+)
+```
+
+- `device_resolver` returns the freshest `BLEDevice` for the heater, or `None` if there is nothing newer. It is called on every `connect()` and on every connection retry, so a handle that changes between connects (a different adapter or relay) is picked up. Passing a `BLEDevice` as `device` and no resolver keeps the current behavior. Passing an address string makes the library run its own scan, so a host that owns scanning should pass a `BLEDevice` or a resolver instead.
+- `client_class` is the bleak client class used to connect, `BleakClient` by default. Pass a subclass, such as `bleak_retry_connector.BleakClientWithServiceCache`, to change how the link behaves.
+- `on_disconnect` is called with no arguments when the link is lost unexpectedly. It is not called for `disconnect()`, `async_release()` or a failed `connect()`. It runs on the event loop, must not block, and an exception it raises is logged and ignored. A drop while `connect()` is still setting up the session calls it as well, and `connect()` then raises its own error.
+
+## Safety model
+
+Every write goes through one profile-gated path: setpoint and mode are checked against the profile's verified limits (never above 140F, 130F by default), a fault-active device is read-only, and every write is read back and compared before the call succeeds. The public API cannot write an arbitrary block or parameter.
+
+## What this doesn't do (yet)
+
+No current-tank-temperature reading (the manufacturer's app never reads it either). No Home Assistant integration; that is a separate, HACS-distributed package. No support for devices other than the bundled profile: `connect()` refuses an unmatched device. Diagnostics are an explicit, separate call, never part of the automatic connection flow.
+
+## License
+
+MIT. See `LICENSE`.

aosmith_ble-0.1.0/README.md

@@ -0,0 +1,73 @@
+# aosmith-ble
+
+Local Bluetooth LE control of A.O. Smith iCOMM heat pump water heaters -- no cloud
+account, no vendor credentials, no internet connection involved. This project is
+independent and unaffiliated with A.O. Smith.
+
+Documentation: see the `docs/` folder or the project site.
+
+Looking for the cloud API instead? See [py-aosmith](https://github.com/bdr99/py-aosmith).
+
+## What this is
+
+An async client that connects directly to a water heater's BLE interface, matches it against a bundled device profile, and reads or writes only what that profile has verified. An unrecognized device is refused outright. To help add support for a new device, call `AOSmithBLEClient.async_diagnose()`. It connects, probes and disconnects on its own (so it works even where `connect()` refuses) and returns a `DiagnosticReport`: `to_markdown()` gives a human-readable report and `to_fixture_entries()` gives redacted, fixture-shaped captures for a profile-contribution PR.
+
+## Install
+
+    pip install git+https://github.com/stumpylog/aosmith-ble
+
+## Quickstart
+
+```python
+import asyncio
+from aosmith_ble import AOSmithBLEClient, FieldName, Mode, async_discover, pairing_code_from_name
+
+async def main():
+    devices = await async_discover()
+    device = devices[0]
+    code = pairing_code_from_name(device.name)
+    async with AOSmithBLEClient(device, pairing_code=code) as client:
+        features = await client.async_get_state()
+        setpoint = features[FieldName.SETPOINT].value
+        mode = features[FieldName.MODE].value
+        fault = features[FieldName.FAULT].value
+        print(f"{setpoint}F, mode={Mode(mode.mode).name}, fault={fault.name}")
+        await client.async_set_setpoint(124.0)
+
+asyncio.run(main())
+```
+
+## Pairing
+
+Press the Bluetooth button on the control panel once before first use. The device hands out the "assetID" it authenticates sessions against only while its pairing slot is populated. Cache `AOSmithBLEClient.asset_id` (for example with the device address) and pass it back as `asset_id=` so the button press is a one-time step.
+
+## Embedding in a long-running application
+
+A host that owns Bluetooth scanning and wants the client to survive reconnects can pass three optional, keyword-only hooks:
+
+```python
+client = AOSmithBLEClient(
+    device,
+    pairing_code=code,
+    asset_id=cached_asset_id,
+    device_resolver=lambda: my_scanner.latest_device(address),
+    client_class=MyBleakClientSubclass,
+    on_disconnect=lambda: schedule_reconnect(),
+)
+```
+
+- `device_resolver` returns the freshest `BLEDevice` for the heater, or `None` if there is nothing newer. It is called on every `connect()` and on every connection retry, so a handle that changes between connects (a different adapter or relay) is picked up. Passing a `BLEDevice` as `device` and no resolver keeps the current behavior. Passing an address string makes the library run its own scan, so a host that owns scanning should pass a `BLEDevice` or a resolver instead.
+- `client_class` is the bleak client class used to connect, `BleakClient` by default. Pass a subclass, such as `bleak_retry_connector.BleakClientWithServiceCache`, to change how the link behaves.
+- `on_disconnect` is called with no arguments when the link is lost unexpectedly. It is not called for `disconnect()`, `async_release()` or a failed `connect()`. It runs on the event loop, must not block, and an exception it raises is logged and ignored. A drop while `connect()` is still setting up the session calls it as well, and `connect()` then raises its own error.
+
+## Safety model
+
+Every write goes through one profile-gated path: setpoint and mode are checked against the profile's verified limits (never above 140F, 130F by default), a fault-active device is read-only, and every write is read back and compared before the call succeeds. The public API cannot write an arbitrary block or parameter.
+
+## What this doesn't do (yet)
+
+No current-tank-temperature reading (the manufacturer's app never reads it either). No Home Assistant integration; that is a separate, HACS-distributed package. No support for devices other than the bundled profile: `connect()` refuses an unmatched device. Diagnostics are an explicit, separate call, never part of the automatic connection flow.
+
+## License
+
+MIT. See `LICENSE`.

aosmith_ble-0.1.0/docs/contributing/does-my-heater-work.md

@@ -0,0 +1,51 @@
+# Does my heater work?
+
+`connect()` refuses any heater without a verified profile, because the library writes to a real appliance and the firmware is not trusted to validate input. The one bundled profile is `hpts50-6.3` ([tested devices](../tested-devices.md)).
+
+If your heater is refused, you can still help. `async_diagnose()` is a separate, explicit, read-only call that connects, probes and disconnects on its own, and produces a report you can paste into an issue.
+
+## What it does and does not do
+
+- It reads only, and never writes.
+- It asks each block id from 0 to 40 for a single word starting at offset 0, with a short
+  pause between reads, to record which blocks answer.
+- It reads the identity block to record the model bytes and firmware.
+- It disconnects when finished, whether or not anything matched.
+
+## Run it
+
+Press the Bluetooth button on the control panel once first, so the heater hands out the session value the library needs ([Handshake](../protocol/handshake.md#the-assetid)). Close the official app and any other client first, since only one can connect.
+
+```python
+import asyncio
+
+from aosmith_ble import AOSmithBLEClient, async_discover, pairing_code_from_name
+
+
+async def main() -> None:
+    device = (await async_discover())[0]
+    client = AOSmithBLEClient(device, pairing_code=pairing_code_from_name(device.name))
+    report = await client.async_diagnose()
+    print(report.to_markdown())  # redacted by default
+
+
+asyncio.run(main())
+```
+
+`to_markdown()` redacts the session value, serial, Bluetooth address and any Wi-Fi name
+by default. Do not pass `redact=False` when posting publicly.
+
+## File a report
+
+Open a "Device support request" issue and paste the report. Before you
+post, check it contains none of these:
+
+- your heater's Bluetooth address
+- the 18-character session value (it starts `02iQk`)
+- the full serial number from the rating plate or the advertised name's last digits
+
+To contribute fixtures, use `report.to_fixture_entries()` (redacted frames shaped like `tests/fixtures/frames.json`), never raw captures. Why: [Test vectors](../development/test-vectors.md).
+
+## What happens next
+
+A maintainer compares your block presence and model bytes with the [block map](../protocol/blocks.md) and the evidence rules in [Research](../research/index.md). A report does not promise support for any model. A new profile starts read-only, and write support is added only after an observed write exists for that exact model and firmware.

aosmith_ble-0.1.0/docs/development/design-principles.md

@@ -0,0 +1,14 @@
+# Design principles
+
+1. **Audience.** Published for the community, aware of multiple models and firmware versions.
+2. **No speculative writes, ever.** Confidence comes from read-side validation, limits from the verified profile, and frames from range-checked values. No public raw-write API, no blind write retries.
+3. **Strict validation.** An unrecognized device is refused outright, and the refusal produces a complete diagnostic report suitable for pasting into an issue.
+4. **One connection.** Hold a single connection open and poll. Surface the sleep timeout as a repair ("press the Bluetooth button") in the Home Assistant integration.
+5. **Writes.** Setpoint, mode, and timed modes.
+6. **Two packages.** `aosmith-ble` is the library. A separate Home Assistant integration (`ha-aosmith-ble`, distributed through HACS) builds on it.
+
+## Compatibility table
+
+Compatibility table: contributors run `async_diagnose()` on an unknown device, and `DiagnosticReport.to_fixture_entries()` plus `draft_profile_stanza` become the pull request artifact for a new bundled profile.
+
+Frame formats: [Commands](../protocol/commands.md). Low-level frame builders exist for testing and cannot transmit; the [roadmap](handoff.md) tracks whether they stay public. None is a supported write API.

aosmith_ble-0.1.0/docs/development/handoff.md

@@ -0,0 +1,30 @@
+# Roadmap
+
+What is still open. Read `README.md` and `CHANGELOG.md` for what the library does today and [Design principles](design-principles.md) for why.
+
+## Smaller library items
+
+| Item | Detail |
+| --- | --- |
+| `Profile.__post_init__` message ("unless this profile is only ever used as a parent via `inherits`") promises a case that later fails in `resolve_inherits` | Fix the wording, or add an `abstract` flag. |
+| Every bundled profile is directly matchable, including future parents | `match_profile` iterates all profiles with a `match`. Harmless with one profile; needs an `abstract` concept before a second is added via `inherits`. |
+| `CODEC_REGISTRY` is a plain mutable `dict` | Wrap in `types.MappingProxyType`. |
+| `duration_days` type checking | The codec range-checks but does not type-check, so `1.5` raises `TypeError` instead of `ValidationError`, and `bool` is accepted as `0` or `1`. Neither reaches the wire. |
+| `assert self._profile is not None` in the write path | In both write methods and in session and read helpers. Stripped under `python -O`; use an explicit `if ... raise`. |
+| `protocol.set_setpoint_request` and `set_mode_request` are public but unused by the client | Only tests use them (to build expected frames), `set_setpoint_request` has no ceiling check, and neither is re-exported at top level. Keep as documented low-level helpers or move out of the public surface. |
+| `pyproject.toml` pins `bleak>=0.21` with no upper bound | Consider `bleak>=0.21,<4`. |
+
+## Home Assistant integration
+
+Needs a specification first: domain `aosmith_ble`, entity table, operation-mode mapping, config flow, coordinator, error and repair handling, diagnostics redaction. Not started. It belongs in its own repository (`ha-aosmith-ble`, via HACS). The diagnostics-only mode for unmatched devices can build on `async_diagnose()`.
+
+## Lower priority
+
+- **Stale days-remaining counters.** The Vacation counter keeps its last value after an early switch to another mode (hardware-observed), so `vacation_days_remaining` can read 5 in Hybrid. Decide whether the library should report 0 or hide a counter unless its mode is active.
+
+- **Publish to PyPI.** The package builds, but nothing has been uploaded. Do it deliberately, when someone wants it installable from an index.
+- **Fingerprint-based matching.** The third matching outcome: fingerprint matches but firmware differs, so inherit addressing and demote to read-only. Blocked on a block-length detection tool that does not exist yet. Do not start before the Home Assistant integration.
+- **GUEST mode.** No profile may add mode 3 to `writable_modes` until an observed write exists ([Open questions](../research/open-questions.md)).
+- **Current tank temperature and hot-water availability.** Open leads ([Hot water availability](../hardware/hot-water-availability.md)). The official app reads neither over BLE. The [panel experiment](../hardware/maintenance-display.md) could extend to tank temperature, otherwise a new empirical approach is needed.
+
+See also [Open questions](../research/open-questions.md).

aosmith_ble-0.1.0/docs/development/index.md

@@ -0,0 +1,8 @@
+# Development
+
+For contributors: where the project stands and how it is built.
+
+- [Roadmap](handoff.md): what is still open, item by item.
+- [Design principles](design-principles.md): the settled principles behind the library.
+- [Test vectors](test-vectors.md): why the HMAC vectors in the test suite are synthetic, and how to supply real ones.
+- [Releasing](releasing.md): how a version is tagged and published.

aosmith_ble-0.1.0/docs/development/releasing.md

@@ -0,0 +1,16 @@
+# Releasing
+
+The version lives in one place, `version` in `pyproject.toml`. `aosmith_ble.__version__` reads it from the installed package metadata.
+
+To release:
+
+1. Set the new `version` in `pyproject.toml` and move the `CHANGELOG.md` entries under that version.
+2. Merge to `main` with the tests, lint and docs jobs green.
+3. Tag the merge commit `v<version>` (for example `v0.1.0`) and push the tag.
+
+The release workflow then checks that the tag matches `pyproject.toml`, runs the tests, builds the sdist and wheel, smoke-tests the wheel in a clean environment, and publishes to PyPI. A tag that does not match the version fails before anything is built.
+
+Publishing uses PyPI trusted publishing, so no API token is stored in the repository. The PyPI project trusts the `release.yml` workflow running in the `pypi` GitHub environment.
+
+!!! warning
+    A version published to PyPI can be yanked but never replaced. Check the built files before tagging, and use a new version number for any fix.

aosmith_ble-0.1.0/docs/development/test-vectors.md

@@ -0,0 +1,19 @@
+# Test vectors
+
+The test vectors for the `0xF1` challenge response and the init response are synthetic. The HMAC vectors in `tests/test_protocol_session.py` and the `init_response_slot_populated` frame in `tests/fixtures/frames.json` are computed from a placeholder assetID (`02iQk000000EXAMPLE`, 18 characters like a real one). Tests use a dummy pairing code (`123456`).
+
+## What that means
+
+A real capture is an independent check: the official app produced those bytes, so a match proves the code builds the same response. A synthetic vector is computed with `hmac` and `hashlib` using the same construction as the code under test, so it catches regressions but not a wrong construction.
+
+The construction is in [Handshake](../protocol/handshake.md).
+
+## Supplying real vectors privately
+
+For example from a capture of the official app, all from one device:
+
+1. Take the 18-character ASCII assetID from the `0xF2` init response (`DB 2F 18 01 <assetID> 80 <crc>`).
+2. For several sessions of that same device, take the 2-byte nonce from each `0xF4` response (`DB 4F 07 <nonce> 80 <crc>`) and the 20-byte payload from the `0xF1` write that follows it (`BD F1 19 01 <payload> <crc>`).
+3. In `tests/test_protocol_session.py`, replace `ASSET_ID` and `CHALLENGE_RESPONSE_PAIRS` with those values.
+4. Other tests and `tests/fixtures/frames.json` reuse the placeholder. If you change it everywhere, recompute the CRC of `init_response_slot_populated` in `frames.json`. See [CRC](../protocol/crc.md).
+5. Redact device-identifying values, or keep real vectors private and run them locally.