localtrv 0.2.0__tar.gz

localtrv-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,66 @@
+name: Bug report
+description: Something does not work as expected.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting. Never paste your network key, here or in an attachment.
+        Security problems go through private reporting instead (see SECURITY.md).
+  - type: input
+    id: ha_version
+    attributes:
+      label: Home Assistant version
+      placeholder: "2026.10.1"
+    validations:
+      required: true
+  - type: input
+    id: integration_version
+    attributes:
+      label: Integration version
+      placeholder: "0.2.0"
+    validations:
+      required: true
+  - type: input
+    id: bluetooth
+    attributes:
+      label: Bluetooth adapter or proxy
+      description: Local adapter model, or ESPHome proxy board and ESPHome version.
+      placeholder: "ESP32-C3, ESPHome 2026.9.1"
+    validations:
+      required: true
+  - type: input
+    id: mtu
+    attributes:
+      label: MTU log line
+      description: The `connected, mtu=…` line from the debug log.
+      placeholder: "connected, mtu=247"
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened
+      description: What you did, what you expected, and what happened instead.
+    validations:
+      required: true
+  - type: textarea
+    id: debug_log
+    attributes:
+      label: Debug log
+      description: |
+        Enable debug logging (see the README), reproduce the problem, and paste the relevant part.
+        Read it first and remove anything you do not want to share.
+      render: text
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Diagnostics
+      description: |
+        Settings > Devices & services > LocalTRV, menu, Download diagnostics.
+        Drag the file here. It contains no keys, but does contain temperatures and network metadata.
+  - type: checkboxes
+    id: no_key
+    attributes:
+      label: Network key
+      options:
+        - label: I removed my network key and did not paste it anywhere.
+          required: true

localtrv-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/jurgenj136/localtrv/security/advisories/new
+    about: Please report security problems privately. See SECURITY.md.

localtrv-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,21 @@
+name: Feature request
+description: Suggest an improvement or a new feature.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What do you want to do?
+      description: The problem or use case, in your own words.
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Your idea
+      description: How you would like it to work.
+  - type: textarea
+    id: setup
+    attributes:
+      label: Your setup
+      description: Valves, router, gateway, Bluetooth adapter or proxy, if relevant.

localtrv-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: "17 4 * * *"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - run: uv sync --locked --all-groups
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv run mypy
+      - run: uv run pytest
+      - name: Secret check
+        run: git ls-files -z | xargs -0 uv run python scripts/check_secrets.py
+
+  hassfest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: home-assistant/actions/hassfest@master
+
+  hacs:
+    # HACS only serves public repositories and cannot read a private one's files.
+    if: ${{ !github.event.repository.private }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: hacs/action@main
+        with:
+          category: integration

localtrv-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,84 @@
+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
+        with:
+          python-version: "3.14"
+      - name: Verify tag, pyproject and manifest versions agree
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import json, os, sys, tomllib
+
+          tag = os.environ["TAG"].removeprefix("v")
+          py = tomllib.load(open("pyproject.toml", "rb"))["project"]["version"]
+          manifest = json.load(open("custom_components/localtrv/manifest.json"))
+          problems = []
+          if py != tag:
+              problems.append(f"pyproject version {py} != tag {tag}")
+          if manifest["version"] != tag:
+              problems.append(f"manifest version {manifest['version']} != tag {tag}")
+          if manifest["requirements"] != [f"localtrv=={tag}"]:
+              problems.append(f"manifest requirements {manifest['requirements']} != pin {tag}")
+          if problems:
+              sys.exit("; ".join(problems))
+          PY
+      - run: uv sync --locked --all-groups
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv run mypy
+      - run: uv run pytest
+      - name: Secret check
+        run: git ls-files -z | xargs -0 uv run python scripts/check_secrets.py
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          prerelease=()
+          # PEP 440 pre/dev releases (v0.2.0a1, v0.2.0rc1, v0.2.0.dev1) are GitHub prereleases.
+          if [[ "$TAG" =~ (a|b|rc|\.dev)[0-9]+$ ]]; then prerelease=(--prerelease); fi
+          gh release create "$TAG" dist/* --repo "$GITHUB_REPOSITORY" \
+            --title "$TAG" --generate-notes "${prerelease[@]}"

localtrv-0.2.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+# Tooling caches
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.uv-cache/
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+# Secrets and captures (never commit)
+.viessmann-local/
+*.key
+*.hex
+*identity*.json
+*.pcap
+*.pcapng
+captures/
+*.capture
+.env
+.env.*
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+# Home Assistant dev config (spec 2.7)
+.ha-config/
+# Local-only notes and agent instructions (not published)
+AGENTS.md
+CLAUDE.md
+.claude/
+docs/*
+!docs/protocol.md
+!docs/images/

localtrv-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.0
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy
+        language: system
+        types: [python]
+        pass_filenames: false
+      - id: secret-check
+        name: secret check (hex key material)
+        entry: uv run python scripts/check_secrets.py
+        language: system
+        pass_filenames: true

localtrv-0.2.0/.python-version

@@ -0,0 +1 @@
+3.14

localtrv-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,124 @@
+# Contributing
+
+Thanks for helping. This file covers the development setup, the rules every change follows, and
+the code layout. User documentation lives in the [README](README.md).
+
+## Ground rules
+
+- **Never post a network key**, a Commissioning Status dump, or a raw capture in an issue, PR,
+  commit or log. If you shared one by accident, tell us at once so we can delete it.
+- **No hardware, BLE or network in tests.** The library ships a simulator
+  (`localtrv.testing`: fake R0, fake network and valves) that the tests drive.
+- **Dummy keys and EUIs only.** Public spec test vectors are fine; put `# secret-scan: allow` on
+  the same line. `scripts/check_secrets.py` fails on anything else that looks like key material.
+- Key material is wrapped in `SecretBytes` (`repr` and `str` print `<redacted>`). Never log it.
+- [Conventional Commits](https://www.conventionalcommits.org/)
+  (`feat|fix|refactor|build|ci|chore|docs|style|perf|test`), small commits.
+- Files under about 500 lines. mypy strict, fully typed, no module-level mutable state.
+- Library and simulator code use the injected `zigbee_direct.clock.Clock`. Never call
+  `asyncio.sleep`, `asyncio.timeout` or `loop.call_later` directly. Tests use `VirtualClock`.
+- Add a regression test with every bug fix when it fits.
+
+## Development setup
+
+Python 3.14.2+ and [uv](https://docs.astral.sh/uv/). Integration tests use
+[pytest-homeassistant-custom-component](https://pypi.org/project/pytest-homeassistant-custom-component/),
+pinned to Home Assistant 2026.10.x.
+
+```bash
+uv sync
+uv run pre-commit install        # git hooks: ruff, mypy, secret check
+```
+
+## Gate
+
+Run before every PR (CI runs the same, plus hassfest and the HACS action):
+
+```bash
+uv run ruff check
+uv run ruff format --check
+uv run mypy
+uv run pytest
+git ls-files -z | xargs -0 uv run python scripts/check_secrets.py
+```
+
+Or the hooks at once: `uv run pre-commit run --all-files` (ruff, mypy, secret check). It does not
+run the tests; run `uv run pytest` as well.
+
+## Run Home Assistant locally
+
+Runs HA against the working tree. `.ha-config/` is gitignored.
+
+```bash
+mkdir -p .ha-config/custom_components
+ln -s "$PWD/custom_components/localtrv" .ha-config/custom_components/localtrv
+uv run hass -c .ha-config --skip-pip-packages localtrv
+```
+
+## Test fixtures from logs
+
+`scripts/extract_npdu_fixtures.py` turns logged frames into JSON-lines fixtures. Redaction is
+best-effort: review the output by hand before committing it.
+
+From a Home Assistant log with debug logging on:
+
+```bash
+uv run python scripts/extract_npdu_fixtures.py --from-ha-log home-assistant.log > fixtures.jsonl
+```
+
+From other saved terminal output with NPDU lines:
+
+```bash
+uv run python scripts/extract_npdu_fixtures.py capture.txt \
+  --redact-eui 00:11:22:33:44:55:66:77 --redact-short 0x1234 > fixtures.jsonl
+```
+
+## Architecture
+
+```text
+ Home Assistant / CLI               ubisys R0 (ZDD)            Zigbee network
++--------------------+  BLE GATT   +----------------+   NWK   +------------------+
+| LocalTRV           | ----------> | Zigbee Direct  | ------> | coordinator (TC) |
+| (ZVD)              | <---------- | router         | <------ | ZK03840 valves   |
++--------------------+  AES-CCM    +----------------+         +------------------+
+   plaintext NPDUs inside the session; the R0 applies NWK security
+```
+
+The network key is used offline to derive the Basic Authorization Key for the BLE session.
+Protocol details: [docs/protocol.md](docs/protocol.md).
+
+Layering: `zigbee_direct` holds no Viessmann constants. `bridge.py` orchestrates but takes every
+cluster, attribute, scale, sentinel and model id from the `valves` package. `testing/valve.py` may
+hold simulator fixture data written independently of `valves`. Codec frames are
+`@dataclass(frozen=True, slots=True)` with `encode()` and `decode()`: pure, no I/O.
+
+## Package layout
+
+```text
+src/localtrv/            library (PyPI: localtrv)
+  valves/                Viessmann ZK03840 mapping (the only vendor-specific package)
+  bridge*.py             ViCareBridge: discovery, polling, setpoint transactions, cache
+  testing/               simulator: fake R0 (GATT + session crypto), fake network and valves
+  cli.py                 `scan` / `status` CLI (key from env or file only)
+  zigbee_direct/         generic Zigbee Direct, no Viessmann knowledge
+    crypto.py mmo.py     key derivation, SPEKE, AES-MMO, CCM session frames
+    session.py           sans-IO handshake initiator + SessionCipher
+    transport*.py        BLE GATT transport (bleak)
+    connection*.py       supervised connection: backoff, rejoin, repair issues
+    node*.py routing.py  virtual Zigbee node: join, requests, route replies
+    debug.py redact.py   NPDU debug logging with redaction
+    codec/               tlv, nwk, aps, zdo, zcl, commissioning, fallback
+custom_components/localtrv/  Home Assistant integration (HACS)
+scripts/                 check_secrets.py, extract_npdu_fixtures.py
+tests/                   unit, simulator and HA tests
+docs/protocol.md         protocol notes
+```
+
+## Docs
+
+- [docs/protocol.md](docs/protocol.md): protocol notes
+
+## Releases
+
+Maintainer only. `pyproject.toml`, `manifest.json` `version` and the manifest pin
+`localtrv==X.Y.Z` move in lockstep, and a `vX.Y.Z` tag runs `release.yml` (gate, build, PyPI trusted publishing, GitHub release).

localtrv-0.2.0/LICENSE

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