gatt-link-ble 0.1.1__tar.gz

gatt_link_ble-0.1.1/.github/agents/phase-builder.agent.md

@@ -0,0 +1,11 @@
+---
+description: Executes a single implementation phase from ARCHITECTURE.md with automated lint, typecheck, and pytest verification.
+tools: ['edit', 'runNotebooks', 'search', 'new', 'runCommands', 'problems', 'usages', 'findTestFiles']
+---
+
+You are an expert Python and Open Home Foundation developer.
+1. Read `ARCHITECTURE.md` and inspect the current directory tree to see which phases are already complete.
+2. Implement ONLY the requested phase (or the next incomplete phase) cleanly and completely.
+3. Write unit/functional tests covering edge cases (negative numbers, malformed payloads, disconnects) alongside the implementation.
+4. Run the verification suite in terminal (`uv run ruff check --fix . && uv run ruff format . && uv run mypy . && uv run pytest`) and resolve any failures before responding.
+5. Keep your final summary concise (under 10 bullet points) to conserve tokens.

gatt_link_ble-0.1.1/.github/copilot-instructions.md

@@ -0,0 +1,8 @@
+# Copilot Instructions — `gatt-link-ble`
+
+- **Architecture:** Always follow `ARCHITECTURE.md` in the repo root. Execute one phase at a time.
+- **Strict Boundary:** NEVER import `homeassistant` or `habluetooth`. This is a pure Python PyPI library.
+- **Tooling:** Always use `uv run` for commands (`uv run pytest`, `uv run mypy src tests`, `uv run ruff check .`). Never use raw `pip`.
+- **BLE Rules:** Use `bleak-retry-connector` (`establish_connection` + `BleakClientWithServiceCache`). Unpack binary payloads strictly with Python's `struct` module—never slice hex strings.
+- **Code Quality:** Enforce Python 3.12+ type annotations (`mypy --strict`) and immutable `@dataclass(frozen=True)` state models.
+- **Verification:** Before finishing any task, run `uv run ruff check . && uv run mypy src tests && uv run pytest` and fix all errors in the same turn.

gatt_link_ble-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, windows-2025]
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          enable-cache: true
+
+      - run: uv sync --locked --all-groups
+      - run: uv run --locked ruff check .
+      - run: uv run --locked mypy src tests
+      - run: uv run --locked pytest

gatt_link_ble-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing version tag to publish
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build, verify, and publish
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/project/gatt-link-ble/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.tag || github.ref }}
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          enable-cache: true
+
+      - name: Install locked dependencies
+        run: uv sync --locked --all-groups
+
+      - run: uv run --locked ruff check .
+      - run: uv run --locked mypy src tests
+      - run: uv run --locked pytest
+      - run: uv build
+
+      - name: Publish to PyPI using OIDC
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

gatt_link_ble-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-main
+  cancel-in-progress: false
+
+jobs:
+  release:
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == 'main' &&
+      !startsWith(github.event.workflow_run.head_commit.message, 'chore(release):')
+    name: Create semantic release
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: main
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_PAT }}
+
+      - name: Confirm CI checked the current main commit
+        id: current-main
+        env:
+          CI_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          if [[ "$(git rev-parse HEAD)" == "$CI_SHA" ]]; then
+            echo "current=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "CI result is stale; main has advanced"
+            echo "current=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        if: steps.current-main.outputs.current == 'true'
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        if: steps.current-main.outputs.current == 'true'
+        with:
+          enable-cache: true
+
+      - name: Install uv.lock
+        if: steps.current-main.outputs.current == 'true'
+        run: uv sync --locked --all-groups
+
+      - name: Release with Python Semantic Release
+        if: steps.current-main.outputs.current == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_PAT }}
+        run: uv run --with python-semantic-release==10.7.0 --no-project semantic-release version

gatt_link_ble-0.1.1/.gitignore

@@ -0,0 +1,8 @@
+ARCHITECTURE.md
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+dist/

gatt_link_ble-0.1.1/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+Release notes are generated from Conventional Commit messages by
+Python Semantic Release.

gatt_link_ble-0.1.1/LICENSE

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

gatt_link_ble-0.1.1/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: gatt-link-ble
+Version: 0.1.1
+Summary: Async BLE GATT discovery, parsing, and state updates.
+Author: infoyouth
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: bleak-retry-connector>=3.6.0
+Requires-Dist: bleak>=0.22.0
+Description-Content-Type: text/markdown
+
+# gatt-link-ble
+
+An asynchronous, framework-independent Python library for discovering BLE GATT
+services, decoding sensor values, and receiving device-state updates.
+
+The package owns BLE transport and parsing. It has no Home Assistant, MQTT, or
+UI-framework dependencies.
+
+## Requirements and installation
+
+- Python 3.12 or newer
+- BLE adapter and a device advertising supported GATT services
+
+Install from PyPI:
+
+```shell
+python -m pip install gatt-link-ble
+```
+
+## Poll once
+
+```python
+import asyncio
+
+from bleak import BleakScanner
+
+from gatt_link_ble import ConnectionMode, GattLinkClient
+
+
+async def main() -> None:
+    address = "AA:BB:CC:DD:EE:FF"
+    device = await BleakScanner.find_device_by_address(address, timeout=10)
+    if device is None:
+        raise RuntimeError(f"BLE device not found: {address}")
+
+    client = GattLinkClient(device, mode=ConnectionMode.POLL_AND_DISCONNECT)
+    state = await client.poll()
+    print(state)
+
+
+asyncio.run(main())
+```
+
+## Receive push updates
+
+```python
+import asyncio
+
+from bleak import BleakScanner
+
+from gatt_link_ble import GattLinkClient
+
+
+async def main() -> None:
+    address = "AA:BB:CC:DD:EE:FF"
+    device = await BleakScanner.find_device_by_address(address, timeout=10)
+    if device is None:
+        raise RuntimeError(f"BLE device not found: {address}")
+
+    client = GattLinkClient(device, state_callback=print)
+    await client.start()
+    try:
+        await asyncio.Event().wait()
+    finally:
+        await client.stop()
+
+
+asyncio.run(main())
+```
+
+`PUSH` keeps the connection open, sends an initial state after connecting, and
+reconnects after unexpected disconnects. `POLL_AND_DISCONNECT` reads available
+characteristics once and disconnects before returning.
+
+## Supported profiles
+
+| Profile | Service UUID | Characteristics |
+| --- | --- | --- |
+| Battery Service | `0x180F` | Battery Level `0x2A19` |
+| Device Information | `0x180A` | Manufacturer `0x2A29`, Model `0x2A24`, Firmware `0x2A26`, Hardware `0x2A27` |
+| Environmental Sensing | `0x181A` | Temperature `0x2A6E`, Humidity `0x2A6F`, Pressure `0x2A6D` |
+| Nordic Thingy Environment | `ef680200-9b35-4933-9b10-52ffa9740042` | Temperature, pressure, humidity, eCO2, TVOC |
+
+Parsed values are available through the immutable `GattDeviceState`,
+`DeviceMetadata`, and `GattSensorData` models.
+
+## Inspect a device
+
+The hardware diagnostic script lists nearby devices and, when passed an
+address, dumps raw bytes from readable characteristics:
+
+```shell
+uv run python scripts/live_scan.py
+uv run python scripts/live_scan.py AA:BB:CC:DD:EE:FF --timeout 10
+```
+
+## Development
+
+```shell
+uv sync --locked --all-groups
+uv run ruff check .
+uv run mypy src tests
+uv run pytest
+uv build
+```
+
+Tests use mocked BLE clients and GATT services; no hardware is needed.
+`ARCHITECTURE.md` is a local implementation guide and is intentionally not
+included in the public repository.
+
+## Releases
+
+After CI succeeds on `main`, Python Semantic Release uses Conventional Commits
+(`feat:` for minor, `fix:` or `perf:` for patch, and `!` for breaking changes)
+to update the version, create a GitHub release, and push a tag. Configure the
+repository Actions secret `RELEASE_PAT` with a GitHub token that can write to
+this repository and whose account is allowed to bypass the `main` branch rules.
+
+The PAT is only for GitHub release operations; it is not a PyPI token. PyPI
+publishing uses OIDC Trusted Publishing. Configure the PyPI publisher for this
+repository's `publish.yml` workflow before the first upload.

gatt_link_ble-0.1.1/README.md

@@ -0,0 +1,121 @@
+# gatt-link-ble
+
+An asynchronous, framework-independent Python library for discovering BLE GATT
+services, decoding sensor values, and receiving device-state updates.
+
+The package owns BLE transport and parsing. It has no Home Assistant, MQTT, or
+UI-framework dependencies.
+
+## Requirements and installation
+
+- Python 3.12 or newer
+- BLE adapter and a device advertising supported GATT services
+
+Install from PyPI:
+
+```shell
+python -m pip install gatt-link-ble
+```
+
+## Poll once
+
+```python
+import asyncio
+
+from bleak import BleakScanner
+
+from gatt_link_ble import ConnectionMode, GattLinkClient
+
+
+async def main() -> None:
+    address = "AA:BB:CC:DD:EE:FF"
+    device = await BleakScanner.find_device_by_address(address, timeout=10)
+    if device is None:
+        raise RuntimeError(f"BLE device not found: {address}")
+
+    client = GattLinkClient(device, mode=ConnectionMode.POLL_AND_DISCONNECT)
+    state = await client.poll()
+    print(state)
+
+
+asyncio.run(main())
+```
+
+## Receive push updates
+
+```python
+import asyncio
+
+from bleak import BleakScanner
+
+from gatt_link_ble import GattLinkClient
+
+
+async def main() -> None:
+    address = "AA:BB:CC:DD:EE:FF"
+    device = await BleakScanner.find_device_by_address(address, timeout=10)
+    if device is None:
+        raise RuntimeError(f"BLE device not found: {address}")
+
+    client = GattLinkClient(device, state_callback=print)
+    await client.start()
+    try:
+        await asyncio.Event().wait()
+    finally:
+        await client.stop()
+
+
+asyncio.run(main())
+```
+
+`PUSH` keeps the connection open, sends an initial state after connecting, and
+reconnects after unexpected disconnects. `POLL_AND_DISCONNECT` reads available
+characteristics once and disconnects before returning.
+
+## Supported profiles
+
+| Profile | Service UUID | Characteristics |
+| --- | --- | --- |
+| Battery Service | `0x180F` | Battery Level `0x2A19` |
+| Device Information | `0x180A` | Manufacturer `0x2A29`, Model `0x2A24`, Firmware `0x2A26`, Hardware `0x2A27` |
+| Environmental Sensing | `0x181A` | Temperature `0x2A6E`, Humidity `0x2A6F`, Pressure `0x2A6D` |
+| Nordic Thingy Environment | `ef680200-9b35-4933-9b10-52ffa9740042` | Temperature, pressure, humidity, eCO2, TVOC |
+
+Parsed values are available through the immutable `GattDeviceState`,
+`DeviceMetadata`, and `GattSensorData` models.
+
+## Inspect a device
+
+The hardware diagnostic script lists nearby devices and, when passed an
+address, dumps raw bytes from readable characteristics:
+
+```shell
+uv run python scripts/live_scan.py
+uv run python scripts/live_scan.py AA:BB:CC:DD:EE:FF --timeout 10
+```
+
+## Development
+
+```shell
+uv sync --locked --all-groups
+uv run ruff check .
+uv run mypy src tests
+uv run pytest
+uv build
+```
+
+Tests use mocked BLE clients and GATT services; no hardware is needed.
+`ARCHITECTURE.md` is a local implementation guide and is intentionally not
+included in the public repository.
+
+## Releases
+
+After CI succeeds on `main`, Python Semantic Release uses Conventional Commits
+(`feat:` for minor, `fix:` or `perf:` for patch, and `!` for breaking changes)
+to update the version, create a GitHub release, and push a tag. Configure the
+repository Actions secret `RELEASE_PAT` with a GitHub token that can write to
+this repository and whose account is allowed to bypass the `main` branch rules.
+
+The PAT is only for GitHub release operations; it is not a PyPI token. PyPI
+publishing uses OIDC Trusted Publishing. Configure the PyPI publisher for this
+repository's `publish.yml` workflow before the first upload.

gatt_link_ble-0.1.1/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gatt-link-ble"
+version = "0.1.1"
+description = "Async BLE GATT discovery, parsing, and state updates."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "infoyouth" }]
+dependencies = [
+    "bleak>=0.22.0",
+    "bleak-retry-connector>=3.6.0",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.11.0",
+    "pytest>=8.3.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.6.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gatt_link_ble"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+mypy_path = "src"
+packages = ["gatt_link_ble"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+addopts = [
+    "--strict-config",
+    "--strict-markers",
+    "--cov=gatt_link_ble",
+    "--cov-report=term-missing",
+    "--cov-fail-under=95",
+]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+commit_parser = "conventional"
+tag_format = "v{version}"
+commit_message = "chore(release): {version}"
+build_command = "uv lock --no-upgrade && uv build"
+allow_zero_version = true
+
+[tool.semantic_release.commit_parser_options]
+parse_squash_commits = true
+ignore_merge_commits = true
+
+[tool.semantic_release.branches.main]
+match = "^main$"
+
+[tool.semantic_release.changelog]
+default_templates = { changelog_file = "CHANGELOG.md" }

gatt_link_ble-0.1.1/scripts/live_scan.py

@@ -0,0 +1,99 @@
+"""Discover nearby BLE devices and dump readable GATT characteristic values."""
+
+import argparse
+import asyncio
+import logging
+
+from bleak import BleakScanner
+from bleak.backends.device import BLEDevice
+from bleak.exc import BleakError
+from bleak_retry_connector import (
+    BleakClientWithServiceCache,
+    establish_connection,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "address",
+        nargs="?",
+        help="BLE address to inspect; omit to list discovered devices",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=5.0,
+        help="scan duration in seconds (default: 5)",
+    )
+    return parser.parse_args()
+
+
+async def _inspect_device(device: BLEDevice) -> None:
+    client = await establish_connection(
+        BleakClientWithServiceCache,
+        device,
+        device.name or device.address,
+        max_attempts=3,
+    )
+    try:
+        for service in client.services:
+            print(f"\nService {service.uuid}")
+            for characteristic in service.characteristics:
+                properties = ", ".join(characteristic.properties)
+                print(f"  Characteristic {characteristic.uuid} [{properties}]")
+                if "read" not in characteristic.properties:
+                    continue
+                try:
+                    value = await client.read_gatt_char(characteristic)
+                except BleakError as err:
+                    _LOGGER.warning(
+                        "Could not read characteristic %s: %s",
+                        characteristic.uuid,
+                        err,
+                    )
+                    continue
+                print(f"    Raw: {value.hex(' ')}")
+    finally:
+        await client.disconnect()
+
+
+async def _run(args: argparse.Namespace) -> None:
+    try:
+        devices = await BleakScanner.discover(timeout=args.timeout)
+    except BleakError as err:
+        raise SystemExit(f"BLE scan failed: {err}") from err
+
+    for device in devices:
+        print(f"{device.address}  {device.name or '(unnamed)'}")
+
+    if args.address is None:
+        return
+
+    match = next(
+        (
+            candidate
+            for candidate in devices
+            if candidate.address.casefold() == args.address.casefold()
+        ),
+        None,
+    )
+    if match is None:
+        raise SystemExit(f"No discovered BLE device matches {args.address}")
+
+    try:
+        await _inspect_device(match)
+    except BleakError as err:
+        raise SystemExit(f"Unable to inspect {match.address}: {err}") from err
+
+
+def main() -> None:
+    """Run the BLE scanner CLI."""
+    logging.basicConfig(level=logging.WARNING, format="%(levelname)s: %(message)s")
+    asyncio.run(_run(_parse_args()))
+
+
+if __name__ == "__main__":
+    main()

gatt_link_ble-0.1.1/src/gatt_link_ble/__init__.py

@@ -0,0 +1,21 @@
+"""Asynchronous BLE GATT discovery and parsing."""
+
+from .client import GattLinkClient
+from .exceptions import GattConnectionError, GattLinkError, GattParseError
+from .models import (
+    ConnectionMode,
+    DeviceMetadata,
+    GattDeviceState,
+    GattSensorData,
+)
+
+__all__ = [
+    "ConnectionMode",
+    "DeviceMetadata",
+    "GattConnectionError",
+    "GattDeviceState",
+    "GattLinkClient",
+    "GattLinkError",
+    "GattParseError",
+    "GattSensorData",
+]