elke27 0.1.2__tar.gz

elke27-0.1.2/.copier-answers.yml

@@ -0,0 +1,9 @@
+# Changes here will be overwritten by Copier. Do not edit manually.
+_commit: v0.2.21
+_src_path: gh:jlevy/simple-modern-uv
+package_author_email: mitchmitchell1616@msn.com
+package_author_name: mitchmitchell
+package_description: Library for interfacing with the Elk Products E27 Alarm Engine
+package_github_org: mitchmitchell
+package_module: elke27_lib
+package_name: elke27

elke27-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: CI
+
+on:
+  push:
+    # Use ["main", "master"] for CI only on the default branch.
+    # Use ["**"] for CI on all branches.
+    branches: ["main", "master"]
+  pull_request:
+    branches: ["main", "master"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        # Update this as needed:
+        # Common platforms: ["ubuntu-latest", "macos-latest", "windows-latest"]
+        os: ["ubuntu-latest"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    # Linux only by default. Use ${{ matrix.os }} for other OSes.
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      # Generally following uv docs:
+      # https://docs.astral.sh/uv/guides/integration/github/
+
+      - name: Checkout (official GitHub action)
+        uses: actions/checkout@v6
+        with:
+          # Important for versioning plugins:
+          fetch-depth: 0
+
+      - name: Remove accidental venv checked into repo
+        run: rm -rf bin include pyvenv.cfg lib lib64 .venv
+
+      - name: Install uv (official Astral action)
+        uses: astral-sh/setup-uv@v7
+        with:
+          # Update this as needed:
+          version: "0.9.25"
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up Python (using uv)
+        run: uv python install
+
+      # Alternately can use the official Python action:
+      # - name: Set up Python (using actions/setup-python)
+      #   uses: actions/setup-python@v5
+      #   with:
+      #     python-version: ${{ matrix.python-version }}
+
+      - name: Install all dependencies
+        run: uv sync --all-extras
+
+      - name: Run linting
+        run: uv run python devtools/lint.py
+
+      - name: Run tests
+        run: uv run pytest

elke27-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: # Enable manual trigger.
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # Mandatory for OIDC.
+      contents: read
+    steps:
+      - name: Checkout (official GitHub action)
+        uses: actions/checkout@v6
+        with:
+          # Important for versioning plugins:
+          fetch-depth: 0
+
+      - name: Remove accidental venv checked into repo
+        run: rm -rf bin include pyvenv.cfg lib lib64 .venv
+
+      - name: Install uv (official Astral action)
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.9.25"
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Set up Python (using uv)
+        run: uv python install
+
+      - name: Install all dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always
+        # Although uv is newer and faster, the "official" publishing option is the one from PyPA,
+        # which uses twine. If desired, replace `uv publish` with:
+        # uses: pypa/gh-action-pypi-publish@release/v1

elke27-0.1.2/.gitignore

@@ -0,0 +1,188 @@
+# Additions to standard GitHub .gitignore:
+*.bak
+*.orig
+tmp/
+trash/
+attic/
+.kash/
+
+# test run logs
+artifacts/test_runs/*.jsonl
+test/artifacts/test_runs/*.jsonl
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Virtualenvs created directly in the repo root (critical for uv / CI)
+bin/
+include/
+pyvenv.cfg
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# PyPI configuration file
+.pypirc

elke27-0.1.2/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

elke27-0.1.2/LICENSE

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

elke27-0.1.2/Makefile

@@ -0,0 +1,32 @@
+# Makefile for easy development workflows.
+# See docs/development.md for docs.
+# Note GitHub Actions call uv directly, not this Makefile.
+
+.DEFAULT_GOAL := default
+
+.PHONY: default install lint test upgrade build clean
+
+default: install lint test 
+
+install:
+	uv sync --all-extras
+
+lint:
+	uv run python devtools/lint.py
+
+test:
+	uv run pytest
+
+upgrade:
+	uv sync --upgrade --all-extras --dev
+
+build:
+	uv build
+
+clean:
+	-rm -rf dist/
+	-rm -rf *.egg-info/
+	-rm -rf .pytest_cache/
+	-rm -rf .mypy_cache/
+	-rm -rf .venv/
+	-find . -type d -name "__pycache__" -exec rm -rf {} +

elke27-0.1.2/PKG-INFO

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: elke27
+Version: 0.1.2
+Summary: Library for interfacing with the Elk Products E27 Alarm Engine
+Project-URL: Repository, https://github.com/mitchmitchell/elke27
+Author-email: mitchmitchell <mitchmitchell1616@msn.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.11
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: typing-extensions>=4.9.0
+Description-Content-Type: text/markdown
+
+# elke27
+
+# elke27_lib
+
+`elke27_lib` is a Python 3.11+ library for interfacing with the **Elk Products E27 Alarm Engine** over the E27 IP protocol. It is designed to be consumed by **Home Assistant** (and standalone tools) while keeping the protocol implementation encapsulated behind a stable client API.
+
+This repository also includes:
+- a comprehensive pytest suite (unit + live-on-panel tests)
+- example programs for discovery, linking, connecting, event monitoring, and basic API usage
+- ADRs and protocol notes used to guide implementation
+
+---
+
+## What this library does
+
+### Core capabilities
+- **Discovery**: Find E27 panels on the LAN and return identity details (panel name, MAC, serial, host/port, etc.).
+- **Linking (provisioning)**: Perform the E27 *API_LINK* flow to obtain long-lived link keys (encryption + HMAC keys) used to establish trusted sessions.
+- **Session establishment**: Connect to a panel, perform HELLO + session bootstrap, and transition to a ready state.
+- **Event-driven updates**: Receive unsolicited panel messages and dispatch them as structured events.
+- **Command execution**: Send API requests and receive responses using a strict one-in-flight model (request/response sequencing).
+- **Snapshots**: Provide read-only state “snapshots” for Home Assistant (or other clients) to read stable views of current panel state.
+
+### Stable public surface for Home Assistant
+Home Assistant is intended to import and use **only** the public client API defined in:
+
+- `docs/CLIENT_CONTRACT.md`
+
+As described there:
+- Home Assistant imports only:
+  - `from elke27_lib.client import Elke27Client, Result`
+- Home Assistant must **not** import internal modules (session, dispatcher, features, handlers, etc.).
+- The contract is treated as stable during refactors.
+
+If you are building a Home Assistant integration, start by reading:
+- `docs/CLIENT_CONTRACT.md`
+- `docs/PERMISSIONS.md`
+- `docs/adr/*`
+
+---
+
+## High-level architecture (mental model)
+
+### 1) Discovery
+Discovery is used to locate panels and present them to the user by **panel name**, while binding identity definitively by **MAC address**.
+
+Implementation entry points:
+- `elke27_lib.discovery`
+- `Elk.discover()` (facade used in examples)
+
+### 2) Linking (API_LINK provisioning)
+Linking is a provisioning-time operation that produces long-lived keys. These keys are persisted externally (for example, by Home Assistant) and reused on subsequent connections.
+
+Implementation entry points:
+- `Elke27Client.async_link(...)`
+- `Elk.link(...)` (facade used in examples)
+
+### 3) Session connect + readiness
+Connecting establishes a framed/encrypted session, performs session bootstrap, and transitions the client to “ready”.
+
+Per the client contract, readiness is defined by:
+- Session ACTIVE, AND
+- `panel_info.session_id` present, AND
+- `table_info` present
+
+Implementation entry points:
+- `Elke27Client.async_connect(host, port, link_keys)`
+- `Elke27Client.wait_ready(timeout_s=...)`
+
+### 4) Features (domain APIs)
+The library exposes “feature” modules (domains) that implement E27 API handlers such as:
+- areas, zones, outputs, thermostats, keypads, control/system, network parameters, rules, logs, users, etc.
+
+These are internal to the library; Home Assistant should not import them directly and should rely on the client contract and snapshots/events.
+
+---
+
+## Installation / Development setup
+
+The project is packaged via `pyproject.toml` and requires Python >=3.11.
+
+Typical development setup (example):
+- create a virtual environment
+- install with development extras
+- run pytest
+
+(Exact tooling choice is up to you; the repository includes standard pyproject-based metadata and pytest configuration.)
+
+---
+
+## Example programs
+
+Examples live under `examples/` and are intended to be runnable against a real panel on your LAN.
+
+### Environment setup (required)
+
+Before running any example programs **or live tests**, you should:
+
+1. Edit the file:
+   - `elk-e27-env-vars.sh`
+
+2. Set the appropriate values for your environment, such as:
+   - panel host / port
+   - access code
+   - passphrase
+   - optional identity fields
+
+3. Source the file into your shell:
+   - `source elk-e27-env-vars.sh`
+
+This ensures all required environment variables are defined consistently for
+example programs and pytest live tests.
+
+### 1) Discover panels (no linking, no connect)
+- `examples/e27_aioscanner.py`
+  - Scans the LAN and prints discovered panels.
+
+### 2) Provisioning (link only)
+- `examples/e27_api_link.py`
+  - Performs API_LINK and prints the resulting link credentials.
+  - Does not start a full session or send operational requests.
+
+### 3) Minimal “hello world” connect + version info
+- `examples/e27_simple_program.py`
+  - Discover → link → connect → request `control.get_version_info` → pump events until results arrive.
+
+### 4) Monitor unsolicited messages/events
+- `examples/e27_unsolicited_monitor.py`
+  - Link → connect → print unsolicited messages/events.
+
+### 5) Client contract examples (Home Assistant–style usage)
+- `examples/e27_client_contract.py`
+- `examples/e27_client_contract_example.py`
+  - Demonstrate the “stable client contract” flow:
+    - create client → connect → wait_ready → subscribe → receive event → read a snapshot
+
+### 6) Network parameter example with authorization retry
+- `examples/e27_network_param_live.py`
+  - Demonstrates a privileged call path that may require PIN authorization.
+
+### 7) Live version info printout
+- `examples/e27_live_version_info.py`
+  - End-to-end link/connect/version info with PanelState printing.
+
+### Common environment variables used by examples
+Examples rely on environment variables typically defined via
+`elk-e27-env-vars.sh`, including:
+- `ELKE27_HOST`, `ELKE27_PORT`
+- `ELKE27_ACCESS_CODE`, `ELKE27_PASSPHRASE`
+- Identity fields (optional): `ELKE27_MN`, `ELKE27_SN`, `ELKE27_FWVER`,
+  `ELKE27_HWVER`, `ELKE27_OSVER`
+
+Many examples also accept command-line arguments (for example, `--host`,
+`--port`) which override environment defaults.
+
+---
+
+## Tests
+
+Tests live under `test/` and are split into:
+- **unit tests** (run without a live panel)
+- **live tests** (require a real E27 panel and credentials)
+
+### Running unit tests
+Unit tests should run with a normal pytest invocation.
+
+### Running live tests
+Live tests are gated and will skip unless enabled. In addition to sourcing
+`elk-e27-env-vars.sh`, live tests must be explicitly enabled via environment
+configuration.
+
+If required environment values are missing, tests are skipped with a message
+indicating what is needed.
+
+### Test artifacts / reporting
+The test harness supports writing artifacts for each pytest invocation, typically
+in JSONL and optionally YAML.
+
+Relevant pytest options:
+- `--e27-report` : `jsonl` (default), `yaml`, `both`, or `none`
+- `--e27-artifacts-dir` : output directory (default: `artifacts/test_runs`)
+
+You can also set:
+- `ELK_E27_REPORT_FORMAT`
+- `ELK_E27_ARTIFACTS_DIR`
+
+Artifacts are designed to support debugging and regression tracking across
+protocol changes.
+
+### Notable test coverage areas
+The test suite includes coverage for:
+- framing and presentation layer behavior
+- sequence handling and request/response correlation
+- bootstrap readiness
+- configured inventory enumeration
+- paging behavior and dispatcher correctness
+- keepalive and reconnect-adjacent behaviors
+- permissions and authorization flows (including live tests)
+
+---
+
+## Documentation
+
+Key documents:
+- `docs/CLIENT_CONTRACT.md` — the stable Home Assistant–facing API contract
+- `docs/PERMISSIONS.md` — permission and authorization semantics
+- `docs/adr/` — architecture decision records guiding behavior and boundaries
+
+If you are working on a Home Assistant integration:
+- follow the import boundary rules in `CLIENT_CONTRACT.md`
+- prefer consuming snapshots and events rather than internal protocol details
+
+---
+
+## Notes for Home Assistant integration authors
+
+- This library is event-driven and designed for a “hub” style Home Assistant
+  integration.
+- Linking keys are long-lived and should be persisted by Home Assistant.
+- Session keys and `session_id` are ephemeral and should not be persisted.
+- Privileged authorization is temporary (vendor-defined behavior); Home Assistant
+  should be prepared to re-authorize as needed and should not assume privilege
+  persists indefinitely.
+- Request concurrency should remain conservative (one request at a time per
+  panel session) to avoid exhausting panel resources.
+
+---
+
+## Repository layout (high level)
+
+- `src/elke27_lib/` — library implementation
+- `docs/` — client contract, permissions, and ADRs
+- `examples/` — runnable sample programs
+- `test/` — pytest suite (unit + live)
+
+---
+
+## Support / Contributing
+
+- Keep Home Assistant–facing changes aligned with `docs/CLIENT_CONTRACT.md`.
+- Prefer small, testable changes.
+- When adding new feature coverage, consider:
+  - unit tests for parsing, dispatch, and mapping
+  - live tests for end-to-end behavior (when hardware is available)
+  - updating documentation or ADRs if behavior changes
+
+---
+
+* * *
+
+## Project Docs
+
+For how to install uv and Python, see [installation.md](docs/installation.md).
+
+For development workflows, see [development.md](docs/development.md).
+
+For instructions on publishing to PyPI, see [publishing.md](docs/publishing.md).
+
+* * *
+
+*This project was built from
+[simple-modern-uv](https://github.com/jlevy/simple-modern-uv).*