majordom-homekit 0.1.2__tar.gz

majordom_homekit-0.1.2/LICENSE

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

majordom_homekit-0.1.2/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: majordom-homekit
+Version: 0.1.2
+Summary: HomeKit integration for MajorDom — bridges HomeKit accessories into the MajorDom language.
+License-File: LICENSE
+Author: Mark Parker
+Author-email: mark@parker-programs.com
+Requires-Python: >=3.12,<3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: majordom-integration-sdk (>=0.1,<1.0)
+Requires-Dist: parker-aiohomekit (>=4.0.1,<5.0.0)
+Description-Content-Type: text/markdown
+
+# integration-homekit
+
+A [MajorDom](https://majordom.io) integration — bridges **Apple HomeKit** accessories into the
+MajorDom language.
+
+Built for the **MajorDom Hub**, but it doesn't need it: this is a standalone, standardized
+library for HomeKit that you can use on its own (see **Run it standalone** below). Built on the
+[MajorDom Integration SDK](https://github.com/MajorDom-Systems/integration-sdk). The entry point
+is `HomeKitController` (`majordom_homekit/controller.py`), which the Hub — or the SDK's dev runner —
+instantiates and drives through its lifecycle: discovery → pairing → commands → teardown.
+
+- **Other protocols:** browse the [MajorDom integrations](https://github.com/orgs/MajorDom-Systems/repositories?q=integration-).
+- **Create your own:** start from the [integration template](https://github.com/MajorDom-Systems/integration-template).
+
+## Documentation
+
+Full integration-author docs — the controller lifecycle, data models, storing data, discovery,
+and a worked example — live at **[docs.majordom.io](https://docs.majordom.io/device-integration)**.
+
+## Development
+
+```sh
+poetry install && poetry run poe install
+```
+
+| Task | Description |
+|------|-------------|
+| `poe check` | Full quality pipeline (ruff, ty, pytest, poetry build/check) |
+| `poe check --ci` | Same, plus `git diff --exit-code` |
+
+Work lands on `develop`; `master` is protected and released via **Actions → Release**. Tests drive
+the controller with the SDK's test doubles against an in-process fake HAP accessory server — no real
+accessory required (see `tests/`).
+
+## Run it standalone (without the Hub)
+
+HomeKit discovers IP accessories over mDNS on the local network (BLE accessories need a BLE
+adapter). No external service is required. Then:
+
+```python
+# run.py
+import asyncio
+
+from majordom_integration_sdk.dev import run_controller
+from majordom_homekit import HomeKitController
+
+# Watches for HomeKit accessories, logs discoveries/events. Ctrl-C to stop.
+asyncio.run(run_controller(HomeKitController, db_path="devices.db"))
+```
+
+```sh
+poetry run python run.py
+```
+
+## About this integration
+
+- **Protocol / platform:** Apple HomeKit Accessory Protocol (HAP) via the
+  [`parker-aiohomekit`](https://pypi.org/project/parker-aiohomekit/) fork of `aiohomekit`.
+- **Transport(s):** IP (Wi-Fi / Ethernet, discovered via mDNS); BLE for BLE accessories.
+- **Supported devices:** HomeKit-compatible accessories — lights, plugs, switches, sensors, locks.
+- **Credentials needed to pair:** `code` (the accessory's 8-digit HomeKit setup code).
+
+### Required harness
+
+- **Hardware adapters:** a BLE adapter only if pairing BLE accessories; IP accessories need none.
+- **Third-party software services:** none — `aiohomekit` speaks HAP directly.
+- **OS / permissions:** mDNS on the LAN for discovery; BLE access for BLE accessories.
+
+### Protocol stack (OSI)
+
+| OSI layer | Protocol | Implemented by |
+|-----------|----------|----------------|
+| Application (7) | HAP characteristics / services | **this integration** (via `aiohomekit`) |
+| Session (5) | Pair-Setup / Pair-Verify (SRP, Ed25519) | library (`aiohomekit`) |
+| Transport (4) | TCP (IP) / GATT (BLE) | OS |
+| Network + below (1–3) | IP over Wi-Fi / Ethernet (or BLE) | OS |
+
+### Progress
+
+- [x] Discovery services registered (mDNS via `zeroconf_discovery_service`; BLE where applicable); cancel closures called in `stop`
+- [x] Discovery listeners fire and call `controller_did_receive_discovery`
+- [x] Re-discovery of already-paired accessories on reconnect (`controller_did_connect_device`)
+- [x] Device pairing (HAP pair-setup with the setup code)
+- [x] Device schema mapped: services/characteristics → parameter list with per-parameter metadata
+- [x] Hub → Device control (`send_command`)
+- [x] Device → Hub event subscription (`controller_did_receive_events`)
+- [x] `identify`
+- [x] `unpair`
+- [x] `fetch`
+- [x] Availability tracking while running (`controller_did_lose_device` / `last_error`)
+- [x] Graceful shutdown in `stop`
+- [x] Tests pass against a fake HAP accessory server (`tests/`)
+
+### Notes
+
+Uses the `parker-aiohomekit` fork of `aiohomekit`; note its Python upper bound (`<3.14`).
+
+## License
+
+See [LICENSE](LICENSE). For commercial licensing or partnership inquiries regarding MajorDom,
+contact us via [parker-industries.org/partnership](https://parker-industries.org/partnership).
+

majordom_homekit-0.1.2/README.md

@@ -0,0 +1,101 @@
+# integration-homekit
+
+A [MajorDom](https://majordom.io) integration — bridges **Apple HomeKit** accessories into the
+MajorDom language.
+
+Built for the **MajorDom Hub**, but it doesn't need it: this is a standalone, standardized
+library for HomeKit that you can use on its own (see **Run it standalone** below). Built on the
+[MajorDom Integration SDK](https://github.com/MajorDom-Systems/integration-sdk). The entry point
+is `HomeKitController` (`majordom_homekit/controller.py`), which the Hub — or the SDK's dev runner —
+instantiates and drives through its lifecycle: discovery → pairing → commands → teardown.
+
+- **Other protocols:** browse the [MajorDom integrations](https://github.com/orgs/MajorDom-Systems/repositories?q=integration-).
+- **Create your own:** start from the [integration template](https://github.com/MajorDom-Systems/integration-template).
+
+## Documentation
+
+Full integration-author docs — the controller lifecycle, data models, storing data, discovery,
+and a worked example — live at **[docs.majordom.io](https://docs.majordom.io/device-integration)**.
+
+## Development
+
+```sh
+poetry install && poetry run poe install
+```
+
+| Task | Description |
+|------|-------------|
+| `poe check` | Full quality pipeline (ruff, ty, pytest, poetry build/check) |
+| `poe check --ci` | Same, plus `git diff --exit-code` |
+
+Work lands on `develop`; `master` is protected and released via **Actions → Release**. Tests drive
+the controller with the SDK's test doubles against an in-process fake HAP accessory server — no real
+accessory required (see `tests/`).
+
+## Run it standalone (without the Hub)
+
+HomeKit discovers IP accessories over mDNS on the local network (BLE accessories need a BLE
+adapter). No external service is required. Then:
+
+```python
+# run.py
+import asyncio
+
+from majordom_integration_sdk.dev import run_controller
+from majordom_homekit import HomeKitController
+
+# Watches for HomeKit accessories, logs discoveries/events. Ctrl-C to stop.
+asyncio.run(run_controller(HomeKitController, db_path="devices.db"))
+```
+
+```sh
+poetry run python run.py
+```
+
+## About this integration
+
+- **Protocol / platform:** Apple HomeKit Accessory Protocol (HAP) via the
+  [`parker-aiohomekit`](https://pypi.org/project/parker-aiohomekit/) fork of `aiohomekit`.
+- **Transport(s):** IP (Wi-Fi / Ethernet, discovered via mDNS); BLE for BLE accessories.
+- **Supported devices:** HomeKit-compatible accessories — lights, plugs, switches, sensors, locks.
+- **Credentials needed to pair:** `code` (the accessory's 8-digit HomeKit setup code).
+
+### Required harness
+
+- **Hardware adapters:** a BLE adapter only if pairing BLE accessories; IP accessories need none.
+- **Third-party software services:** none — `aiohomekit` speaks HAP directly.
+- **OS / permissions:** mDNS on the LAN for discovery; BLE access for BLE accessories.
+
+### Protocol stack (OSI)
+
+| OSI layer | Protocol | Implemented by |
+|-----------|----------|----------------|
+| Application (7) | HAP characteristics / services | **this integration** (via `aiohomekit`) |
+| Session (5) | Pair-Setup / Pair-Verify (SRP, Ed25519) | library (`aiohomekit`) |
+| Transport (4) | TCP (IP) / GATT (BLE) | OS |
+| Network + below (1–3) | IP over Wi-Fi / Ethernet (or BLE) | OS |
+
+### Progress
+
+- [x] Discovery services registered (mDNS via `zeroconf_discovery_service`; BLE where applicable); cancel closures called in `stop`
+- [x] Discovery listeners fire and call `controller_did_receive_discovery`
+- [x] Re-discovery of already-paired accessories on reconnect (`controller_did_connect_device`)
+- [x] Device pairing (HAP pair-setup with the setup code)
+- [x] Device schema mapped: services/characteristics → parameter list with per-parameter metadata
+- [x] Hub → Device control (`send_command`)
+- [x] Device → Hub event subscription (`controller_did_receive_events`)
+- [x] `identify`
+- [x] `unpair`
+- [x] `fetch`
+- [x] Availability tracking while running (`controller_did_lose_device` / `last_error`)
+- [x] Graceful shutdown in `stop`
+- [x] Tests pass against a fake HAP accessory server (`tests/`)
+
+### Notes
+
+Uses the `parker-aiohomekit` fork of `aiohomekit`; note its Python upper bound (`<3.14`).
+
+## License
+
+See [LICENSE](LICENSE). For commercial licensing or partnership inquiries regarding MajorDom,
+contact us via [parker-industries.org/partnership](https://parker-industries.org/partnership).

majordom_homekit-0.1.2/majordom_homekit/__init__.py

@@ -0,0 +1,9 @@
+"""HomeKit integration for MajorDom.
+
+Bridges HomeKit accessories into the MajorDom language. `HomeKitController` is the entry
+point the Hub (or the SDK's standalone dev runner) instantiates and drives.
+"""
+
+from majordom_homekit.controller import HomeKitController
+
+__all__ = ["HomeKitController"]

majordom_homekit-0.1.2/majordom_homekit/characteristics_storage.py

@@ -0,0 +1,89 @@
+"""
+HomeKit-specific storage adapter.
+TLDR;
+aiohomekit manages pairing and characteristics data internally, but delegates persistence to a
+pluggable storage interface.
+This class implements that interface on top of MajorDom's DeviceRepository, so HomeKit state is
+stored in the Hub's database.
+"""
+
+from collections.abc import Callable
+from contextlib import AbstractAsyncContextManager
+
+from aiohomekit.model.accessories import AccessoriesState
+from aiohomekit.model.typed_dicts import HKDeviceID
+from aiohomekit.storage.characteristics_storage import CharacteristicsStorageProtocol
+from majordom_integration_sdk.repository import DeviceRepositoryProtocol
+
+from .mapper import HKMajorDomMapper
+from .models import HKDevice, HKDeviceIntegrationData, HKDeviceState
+
+
+class HKCharacteristicsStorageMajorDom(CharacteristicsStorageProtocol):
+    def __init__(
+        self,
+        make_device_repository: Callable[[], AbstractAsyncContextManager[DeviceRepositoryProtocol]],
+        mapper: HKMajorDomMapper,
+    ):
+        self.make_device_repository = make_device_repository
+        self.mapper = mapper
+
+    @property
+    def _integration_name(self):
+        return "HomeKit"
+
+    # CharacteristicsStorageProtocol Implementation
+
+    async def get_all(self) -> dict[HKDeviceID, AccessoriesState]:
+        all = {}
+        async with self.make_device_repository() as device_repository:
+            for device in await device_repository.get_all(as_=HKDevice):
+                if accessory := device.integration_data.characteristics_cache:
+                    all[device.hk_id] = accessory
+        return all
+
+    async def get(self, id: HKDeviceID) -> AccessoriesState | None:
+        uuid = self.mapper.hap_id_to_uuid(id)
+        async with self.make_device_repository() as device_repository:
+            if (device := await device_repository.get(uuid, as_=HKDevice)) and (
+                accessory := device.integration_data.characteristics_cache
+            ):
+                return accessory
+        return None
+
+    async def save(self, id: HKDeviceID, item: AccessoriesState):
+        # NOTE: this method is called only when data model (characteristics) is updated
+        # which is detected by a change of config_num
+        # usually after the accessory's software update
+        async with self.make_device_repository() as device_repository:
+            device_id = self.mapper.hap_id_to_uuid(id)
+            device = await device_repository.state(device_id, as_=HKDeviceState)
+            assert device
+            if not device.integration_data:
+                device.integration_data = HKDeviceIntegrationData()
+
+            # fill only the unique data from AccessoryState that isn't already passed from
+            # Discovery or DeviceCreate by the core
+            # TODO: check these values with real devices
+
+            accessory = item.accessories[0]  # TODO: add later support for multiple accessories
+            device.manufacturer = accessory.manufacturer
+            device.integration_data.characteristics_cache = item
+
+            # map all homekit characteristics to majordom parameters
+
+            for accessory in item.accessories:
+                for service in accessory.services:
+                    for characteristic in service.characteristics:
+                        parameter = self.mapper.hap_char_to_majordom_parameter(device.id, accessory.aid, characteristic)
+                        device.parameters.append(parameter)
+
+            await device_repository.save(device)
+
+    async def delete(self, id: HKDeviceID):
+        # TODO: check usage, remove vs unpair, allow fast re-pairing
+        async with self.make_device_repository() as device_repository:
+            uuid = self.mapper.hap_id_to_uuid(id)
+            if device := await device_repository.get(uuid, as_=HKDevice):
+                device.integration_data.characteristics_cache = None  # TODO: empty collection?
+                await device_repository.save(device)

majordom_homekit-0.1.2/majordom_homekit/controller.py

@@ -0,0 +1,325 @@
+import asyncio
+import logging
+from collections.abc import Iterable
+from typing import override
+from uuid import UUID
+
+from aiohomekit.controller.abstract import (
+    AbstractController,
+    AbstractDiscovery,
+    AbstractPairing,
+)
+from aiohomekit.controller.relay import Controller as AioHomeKitController
+from aiohomekit.controller.relay import controller as controller_module
+from aiohomekit.model.characteristics import CharacteristicKey
+from aiohomekit.model.characteristics.characteristic_key import CharacteristicKeyValue
+from aiohomekit.model.characteristics.permissions import CharacteristicPermissions
+from aiohomekit.model.typed_dicts import HKDeviceID, Response
+from majordom_integration_sdk.controller import (
+    AbstractController as MajorDomController,  # avoid collision with aiohomekit
+)
+from majordom_integration_sdk.schemas.base import NonEmptyStr
+from majordom_integration_sdk.schemas.command import DeviceCommand
+from majordom_integration_sdk.schemas.device import (
+    CredentialsType,
+    Discovery,
+    ProvidedCredentials,
+)
+from majordom_integration_sdk.schemas.event import DeviceParameterChange
+
+from .characteristics_storage import HKCharacteristicsStorageMajorDom
+from .mapper import HKMajorDomMapper
+from .models import HKDevice, HKParameter
+from .pairings_storage import HKPairingsStorageMajorDom
+
+logger = logging.getLogger(__name__)
+
+# TODO: make a better way to pass this
+controller_module.BLE_TRANSPORT_SUPPORTED = False
+controller_module.COAP_TRANSPORT_SUPPORTED = False
+controller_module.IP_TRANSPORT_SUPPORTED = True
+
+# TODO: what are Accessory.needs_polling chars? handle them
+
+
+class HomeKitController(MajorDomController):
+    """Bridges the Hub to HomeKit (HAP) accessories over IP via aiohomekit.
+
+    aiohomekit owns the HAP protocol, discovery, pairing crypto, and the live connection;
+    this controller adapts it to the Hub's AbstractController contract and persists HomeKit
+    state in the Hub DB through the two storage adapters. See readme.md.
+    """
+
+    mapper: HKMajorDomMapper
+
+    # -------------------------------------------------------------------------
+    # AbstractController interface
+    # -------------------------------------------------------------------------
+
+    name = "HomeKit"
+
+    @property
+    def discoveries(self) -> dict[UUID, Discovery]:
+        return self._majordom_discoveries
+
+    # device_type / parameter_type let the Hub deserialize into our typed subclasses.
+
+    @property
+    @override
+    def device_type(self) -> type[HKDevice]:
+        return HKDevice
+
+    @property
+    @override
+    def parameter_type(self) -> type[HKParameter]:
+        return HKParameter
+
+    # -------------------------------------------------------------------------
+    # Lifecycle
+    # -------------------------------------------------------------------------
+
+    async def start(self):
+        # A single mapper, wired with the framework's UUID generators, is shared with both
+        # storage adapters so every HAP id maps to the same MajorDom UUID everywhere.
+        self.mapper = HKMajorDomMapper(device_uuid=self.device_uuid, parameter_uuid=self.parameter_uuid)
+        self._majordom_discoveries: dict[UUID, Discovery] = dict()
+        self._hap_discoveries: dict[UUID, AbstractDiscovery] = dict()
+        self._availability: dict[UUID, bool] = dict()  # device_id -> last signalled availability
+
+        # aiohomekit already registers the `_hap._tcp/_udp` mDNS browsers itself (given our
+        # shared AsyncZeroconf below), so we don't register them on the discovery service here.
+
+        self.hk_char_storage = HKCharacteristicsStorageMajorDom(self.dependencies.make_device_repository, self.mapper)
+        self.hk_pairing_data_storage = HKPairingsStorageMajorDom(self.dependencies.make_device_repository, self.mapper)
+
+        # TODO: BLE discovery and pairing (aiohomekit supports it; the hub only wires IP for now)
+
+        self._aiohomekit_controller = AioHomeKitController(
+            zeroconf_instance=self.dependencies.zeroconf_discovery_service.async_zeroconf,
+            char_cache=self.hk_char_storage,
+            pairing_data_storage=self.hk_pairing_data_storage,
+        )
+        self._aiohomekit_controller.on_discovery(self._aiohomekit_did_discover)
+        await self._aiohomekit_controller.start()
+
+        # aiohomekit only pushes "became available"; it never pushes "became unavailable"
+        # (see AbstractPairing.add_observer_for_availability). So we poll each paired
+        # accessory's connection state to catch both directions — mid-session drops and
+        # reconnects — and reconcile it through _set_availability.
+        self._availability_task = asyncio.create_task(self._availability_loop())
+
+    async def stop(self):
+        if task := getattr(self, "_availability_task", None):
+            task.cancel()
+        await self._aiohomekit_controller.stop()
+
+    # -------------------------------------------------------------------------
+    # Public device operations (Hub -> device)
+    # -------------------------------------------------------------------------
+
+    async def pair_device(self, discovery: Discovery, credentials: ProvidedCredentials | None):
+        if not credentials or credentials.type not in discovery.expected_credentials_options:
+            raise ValueError(
+                f"Credentials type {credentials.type if credentials else None!r} is not one of the "
+                f"types this discovery advertised: {discovery.expected_credentials_options}"
+            )
+
+        hap_discovery = self._hap_discoveries[discovery.id]
+
+        async with asyncio.timeout(1):  # TODO: timeout to settings
+            finish_pairing = await hap_discovery.start_pairing()
+
+        # TODO: check if pairing steps need to be split
+        async with asyncio.timeout(1):
+            pairing_data = await finish_pairing(str(credentials.value or ""))
+
+        pairing_id = pairing_data["AccessoryPairingID"].lower()
+        # main "patch"/"create" data is saved in majordom's core
+        # aiohomekit will save pairing data and characteristics (data model) automatically using
+        # the provided storage during finish_pairing
+        # so no need to fetch or save anything manually here
+
+        # upd: looks like it isn't implemented in aiohomekit yet, so doing it manually
+        pairing = self._aiohomekit_controller.pairings[pairing_id]
+        await pairing.fetch_accessories_and_characteristics()
+        await self.hk_char_storage.save(
+            pairing_id, pairing.accessories_state
+        )  # converts and saves parameters (aka characteristics)
+        await self.hk_pairing_data_storage.save(pairing_id, pairing_data)  # converts and saves data for connection
+
+        await self._handle_connected_pairing(pairing_id)
+        self._hap_discoveries.pop(discovery.id)
+        self._majordom_discoveries.pop(discovery.id)
+
+    async def unpair(self, device: HKDevice):
+        await self._aiohomekit_controller.remove_pairing(device.hk_id)
+        # aiohomekit will cleanup the storage, so no need to do anything here
+
+    async def identify(self, device: HKDevice):
+        await self._aiohomekit_controller.identify(device.hk_id)
+
+    async def fetch(self, device: HKDevice):
+        pairing = self._aiohomekit_controller.pairings[device.hk_id]
+        if not pairing:
+            raise RuntimeError(
+                f"Unexpected Error: Pairing {device.hk_id} for '{device.id}' aka '{device.name}' not found"
+            )
+
+        # fetching the values only; aiohomekit will save the data model on change automatically
+        response = await pairing.get_characteristics(
+            self._get_all_characteristics_keys(pairing, {CharacteristicPermissions.paired_read})
+        )
+        await self._handle_accessory_response(device.hk_id, response)
+
+    async def send_command(self, command: DeviceCommand, device: HKDevice, parameter: HKParameter):
+        hk_value = self.mapper.mj_value_to_hap(command.value)
+
+        pairing = self._aiohomekit_controller.pairings[device.hk_id]
+
+        if not pairing:
+            raise RuntimeError(
+                f"Unexpected Error: Pairing {device.hk_id} for '{device.id}' aka '{device.name}' not found"
+            )
+
+        response = await pairing.put_characteristics(
+            [CharacteristicKeyValue(parameter.integration_data.aid, parameter.integration_data.iid, hk_value)]
+        )
+        await self._handle_accessory_response(device.hk_id, response)
+
+    # -------------------------------------------------------------------------
+    # Device -> Hub: discovery (aiohomekit delegate)
+    # -------------------------------------------------------------------------
+
+    def _aiohomekit_did_discover(self, controller: AbstractController, hk_discovery: AbstractDiscovery):
+        asyncio.create_task(self._async_aiohomekit_did_discover(controller, hk_discovery))
+
+    async def _async_aiohomekit_did_discover(self, controller: AbstractController, hk_discovery: AbstractDiscovery):
+        # Already paired to us -> a reconnect, not a new discovery.
+        if hk_discovery.description.id in controller.pairings:
+            logger.debug(f"{self.name} Discovered paired device...")
+            await self._handle_connected_pairing(hk_discovery.description.id)
+            return
+
+        # Paired to some other controller -> can't offer for pairing here.
+        if hk_discovery.paired:
+            # TODO: handle this case
+            # If device supports only one controller, show as unreachable (requires unpairing)
+            # Some protocols support multiple controllers (like Matter, some HomeKit, Zigbee green with hacks, etc.)
+            # In this case, accessory might need to be put in pairing mode using the first
+            # controller to allow a second pairing with this controller
+            logger.info(f'Device "{hk_discovery.description.name}" is paired to another controller')
+            return
+
+        # A new, unpaired accessory -> surface it as a discovery.
+        logger.info(f"{self.name} Discovered new device...")
+        desc = hk_discovery.description
+        discovery_uuid = self.mapper.hap_id_to_uuid(hk_discovery.description.id)
+        mj_discovery_info = Discovery(
+            # technical
+            id=discovery_uuid,
+            integration=NonEmptyStr(self.name),
+            expected_credentials_options=[CredentialsType.code.with_mask("DDD-DD-DDD")],
+            expiration=None,  # TODO:
+            # UX
+            transport=NonEmptyStr("IP"),
+            device_name=desc.name,
+            device_manufacturer=None,  # looks like it needs device to be paired first
+            device_category=desc.category,
+            device_icon=None,  # will be implemented later
+            # device_model_id = None,
+            # ? model_name: desc.model
+        )
+        self._hap_discoveries[discovery_uuid] = hk_discovery
+        self._majordom_discoveries[discovery_uuid] = mj_discovery_info
+        await self.dependencies.output.controller_did_receive_discovery(self, mj_discovery_info)
+
+        # TODO: dismiss Discovery if discovery disapperd or expired
+
+    # -------------------------------------------------------------------------
+    # Device -> Hub: parameter events & availability
+    # -------------------------------------------------------------------------
+
+    def run_handle_accessory_response(self, hk_device_id: HKDeviceID, responses: Response):
+        asyncio.create_task(self._handle_accessory_response(hk_device_id, responses))
+
+    async def _handle_accessory_response(self, hk_device_id: HKDeviceID, responses: Response):
+        # TODO: review, test
+        parameter_changed_events = []
+        for (aid, iid), response in responses.items():
+            if "value" in response:
+                hk_value = response["value"]
+                device_id = self.mapper.hap_id_to_uuid(hk_device_id)
+                device_parameter_id = self.mapper.hap_iid_to_param_uuid(hk_device_id, aid, iid)
+                parameter_changed_events.append(
+                    DeviceParameterChange(
+                        device_id=device_id,
+                        parameter_id=device_parameter_id,
+                        value=hk_value,  # TODO: self.mapper.hap_value_to_mj(pairing.characteristic_for_key((aid, iid)))
+                    )
+                )
+            if "status" in response and response["status"] != 0:
+                raise ValueError(
+                    f'Something\'s wrong with characteristic "{aid}.{iid}": '
+                    f'status "{response["status"]}", description: {response.get("description", "none")}'
+                )
+
+        await self.dependencies.output.controller_did_receive_events(self, parameter_changed_events)
+
+    async def _set_availability(self, device_id: UUID, available: bool):
+        """Single funnel for availability transitions — dedupes so the Hub is only told on an
+        actual change, and translates it into the framework's connect / lose callbacks."""
+        if self._availability.get(device_id) == available:
+            return
+        self._availability[device_id] = available
+        if available:
+            await self.dependencies.output.controller_did_connect_device(self, device_id)
+        else:
+            await self.dependencies.output.controller_did_lose_device(self, device_id)
+
+    async def _availability_loop(self, interval: float = 30):
+        while True:
+            await asyncio.sleep(interval)
+            try:
+                for hk_id, pairing in list(self._aiohomekit_controller.pairings.items()):
+                    await self._set_availability(self.mapper.hap_id_to_uuid(hk_id), pairing.is_available)
+            except Exception:
+                logger.exception(f"{self.name} availability poll failed")
+
+    # -------------------------------------------------------------------------
+    # Private helpers: connection setup
+    # -------------------------------------------------------------------------
+
+    async def _handle_connected_pairing(self, pairing_id: HKDeviceID):
+        pairing = self._aiohomekit_controller.pairings[pairing_id.lower()]
+        await self._set_availability(self.mapper.hap_id_to_uuid(pairing_id), True)
+        # subscribe to events
+        await self._observe_characteristics(pairing)
+        # update state
+        state = await pairing.get_characteristics(
+            self._get_all_characteristics_keys(pairing, {CharacteristicPermissions.paired_read})
+        )
+        await self._handle_accessory_response(pairing_id, state)
+
+    async def _observe_characteristics(self, pairing: AbstractPairing):
+        cleanup = pairing.add_observer_for_characteristics(self.run_handle_accessory_response)
+
+        # make controller handle cleanup for us
+        if pairing.id not in self._aiohomekit_controller._pairing_cleanups:
+            self._aiohomekit_controller._pairing_cleanups[pairing.id] = []
+        self._aiohomekit_controller._pairing_cleanups[pairing.id].append(cleanup)
+
+        # pairing.add_observer_for_availability # TODO: check and use
+
+        response = await pairing.subscribe_characteristics(
+            self._get_all_characteristics_keys(pairing, {CharacteristicPermissions.events})
+        )
+        await self._handle_accessory_response(pairing.id, response)
+
+    def _get_all_characteristics_keys(
+        self, pairing: AbstractPairing, perms: set[CharacteristicPermissions]
+    ) -> Iterable[CharacteristicKey]:
+        for accessory in pairing.accessories_state.accessories:
+            for service in accessory.services:
+                for characteristic in service.characteristics:
+                    if perms.issubset(characteristic.perms):
+                        yield CharacteristicKey(accessory.aid, characteristic.iid)

majordom_homekit-0.1.2/majordom_homekit/mapper.py

@@ -0,0 +1,186 @@
+"""
+Conversion logic between HAP (HomeKit Accessory Protocol) concepts and MajorDom's domain model.
+Isolated here to keep the Controller free of boilerplate — formats, units, permissions, and valid
+enum values are all mapped in one place.
+"""
+
+import inspect
+import re
+from collections.abc import Callable, Iterable
+from enum import Enum
+from typing import Any
+from uuid import UUID
+
+from aiohomekit.model.characteristics import (
+    Characteristic,
+    CharacteristicFormats,
+    CharacteristicUnits,
+)
+from aiohomekit.model.characteristics import const as aiohomekit_consts
+from aiohomekit.model.characteristics.characteristic_types import CharacteristicsTypes
+from aiohomekit.model.characteristics.permissions import CharacteristicPermissions
+from aiohomekit.model.typed_dicts import HKDeviceID
+from majordom_integration_sdk.schemas.parameter import (
+    ParameterDataType,
+    ParameterRole,
+    ParameterUnit,
+    ParameterVisibility,
+)
+
+from majordom_homekit.models import (
+    HKParameterIntegrationData,
+    HKParameterState,
+)
+
+
+class HKMajorDomMapper:
+    def __init__(
+        self,
+        device_uuid: Callable[[str], UUID],
+        parameter_uuid: Callable[[UUID, str], UUID],
+    ):
+        # The controller's provided (framework) UUID generators — see AbstractController.
+        # HAP identifiers are turned into MajorDom UUIDs exclusively through these, so device
+        # and parameter ids are namespaced under the integration consistently with every other
+        # integration.
+        self._device_uuid = device_uuid
+        self._parameter_uuid = parameter_uuid
+
+    # -------------------------------------------------------------------------
+    # Identity: HAP identifiers -> MajorDom UUIDs
+    # -------------------------------------------------------------------------
+
+    def hap_id_to_uuid(self, hk_device_id: HKDeviceID) -> UUID:
+        return self._device_uuid(hk_device_id.lower())
+
+    def hap_iid_to_param_uuid(self, hk_device_id: HKDeviceID, aid: int, iid: int) -> UUID:
+        return self._parameter_uuid(self.hap_id_to_uuid(hk_device_id), f"{aid}.{iid}")
+
+    # -------------------------------------------------------------------------
+    # MajorDom -> HAP
+    # -------------------------------------------------------------------------
+
+    def mj_value_to_hap(self, value: Any):
+        # TODO: implement conversion if needed
+        # aiohomekit handle a lot of processing for us
+        # use characteristic.format and characteristic.unit for correct conversion
+        # checking existing mapping inside aiohomekit might be helpful
+        return value
+
+    # -------------------------------------------------------------------------
+    # HAP -> MajorDom
+    # -------------------------------------------------------------------------
+
+    def hap_char_to_majordom_parameter(
+        self, device_id: UUID, aid: int, characteristic: Characteristic
+    ) -> HKParameterState:
+        return HKParameterState(
+            id=self._parameter_uuid(device_id, f"{aid}.{characteristic.iid}"),
+            name=characteristic.description or "",
+            data_type=self._hap_format_to_mj_data_type(characteristic.format),
+            unit=self._hap_unit_to_mj(characteristic.unit),
+            role=self._hap_perms_to_mj_role(characteristic.perms),
+            visibility=ParameterVisibility.user,
+            min_value=characteristic.minValue,
+            max_value=characteristic.maxValue or characteristic.maxLen,
+            min_step=characteristic.minStep,
+            valid_values=self._valid_values(characteristic),
+            integration_data=HKParameterIntegrationData(
+                type=characteristic.type,
+                aid=aid,
+                iid=characteristic.iid,
+            ),
+        ).with_value(self.hap_value_to_mj(characteristic))
+        # UNUSED:
+        # Service.available
+        # Characteristic.available
+        # Characteristic.ev
+        # Characteristic.maxDataLen
+        # Characteristic.handle
+        # Characteristic.broadcast_events
+        # Characteristic.disconnected_events
+        # Characteristic.valid_values_range
+
+    def hap_value_to_mj(self, characteristic: Characteristic):
+        # characteristic.value should already work in most cases since aiohomekit handle a lot of processing for us
+        # otherwise use characteristic.format and characteristic.unit for correct conversion
+        # checking existing mapping inside aiohomekit might be helpful
+        return characteristic.value
+
+    def _hap_format_to_mj_data_type(self, format: str | None) -> ParameterDataType:
+        mapping: dict[str | None, ParameterDataType] = {
+            CharacteristicFormats.bool: ParameterDataType.bool,
+            CharacteristicFormats.uint8: ParameterDataType.integer,
+            CharacteristicFormats.uint16: ParameterDataType.integer,
+            CharacteristicFormats.uint32: ParameterDataType.integer,
+            CharacteristicFormats.uint64: ParameterDataType.integer,
+            CharacteristicFormats.int: ParameterDataType.integer,
+            CharacteristicFormats.int32: ParameterDataType.integer,
+            CharacteristicFormats.float: ParameterDataType.decimal,
+            CharacteristicFormats.string: ParameterDataType.string,
+            CharacteristicFormats.data: ParameterDataType.data,
+            # TODO: review
+            CharacteristicFormats.tlv8: ParameterDataType.data,
+            CharacteristicFormats.array: ParameterDataType.data,
+            CharacteristicFormats.dict: ParameterDataType.data,
+        }
+        return mapping[format]
+
+    def _hap_unit_to_mj(self, unit: str | None) -> ParameterUnit:
+        mapping: dict[str | None, ParameterUnit] = {
+            CharacteristicUnits.celsius: ParameterUnit.celsius,
+            CharacteristicUnits.percentage: ParameterUnit.percentage,
+            CharacteristicUnits.arcdegrees: ParameterUnit.arcdegree,
+            CharacteristicUnits.lux: ParameterUnit.lux,
+            CharacteristicUnits.seconds: ParameterUnit.second,
+            None: ParameterUnit.plain,
+        }
+        return mapping[unit]
+
+    def _hap_perms_to_mj_role(self, perms: Iterable[str]) -> ParameterRole:
+        # TODO: review all perms in specs
+        if CharacteristicPermissions.paired_write in perms:
+            return ParameterRole.control
+        elif CharacteristicPermissions.paired_read in perms:
+            return ParameterRole.sensor
+        else:
+            return ParameterRole.event
+
+    def _valid_values(self, characteristic: Characteristic) -> dict[int | str | float, str] | None:
+        # TODO: convert to codegen instead of runtime parsing
+        if values_enum := self._search_values_enum_for_characteristic(characteristic):
+            return {v.value: underscore_to_display_case(k) for k, v in values_enum.__members__.items()}
+        else:
+            return {key: str(key) for key in characteristic.valid_values or []}
+
+    # scrapping
+
+    def _search_values_enum_for_characteristic(self, characteristic: Characteristic) -> type[Enum] | None:
+        # try get characteristic type name by id
+        for char_type in CharacteristicsTypes:
+            if char_type == characteristic.type and (values_enum := self._search_values_enum_by_name(char_type.name)):
+                return values_enum
+
+        # try using description as a type name
+        if characteristic.description:
+            possible_enum_name = "_".join(characteristic.description.split(" ")).upper()
+            if values_enum := self._search_values_enum_by_name(possible_enum_name):
+                return values_enum
+
+        return None
+
+    def _search_values_enum_by_name(self, char_uppercase_name: str) -> type[Enum] | None:
+        # ignore = {'values', 'target', 'current', 'state', 'status', 'capabilities', 'units'}
+        searched_char_name_set = set(word.lower() for word in char_uppercase_name.split("_"))
+
+        for name, obj in inspect.getmembers(aiohomekit_consts, inspect.isclass):
+            if not issubclass(obj, Enum):
+                continue
+            member_name_set = set(word.lower() for word in re.split(r"(?<!^)(?=[A-Z])", name))
+            # compare as sets because some enum names have different word order
+            if searched_char_name_set == member_name_set:
+                return obj
+
+
+def underscore_to_display_case(name: str) -> str:
+    return " ".join([word.title() for word in name.split("_")])

majordom_homekit-0.1.2/majordom_homekit/models.py

@@ -0,0 +1,82 @@
+"""
+MajorDom's Device and Parameter schemas expose an `integration_data` field for storing protocol-specific state.
+By default it is an untyped dict persisted as JSON. Integrations can subclass Device/DeviceState
+and Parameter/ParameterState
+to declare a typed schema for that field — Hub will then handle (de-)serialization automatically
+before passing Device instance to Controller's methods or when saving to the database.
+To make the Hub instantiate these custom types, the integration's Controller must override
+`device_type` and `parameter_type`.
+"""
+
+from typing import Any
+from uuid import UUID
+
+from aiohomekit.model.accessories import AccessoriesState
+from aiohomekit.model.typed_dicts import PairingData
+from majordom_integration_sdk.schemas.base import Base
+from majordom_integration_sdk.schemas.device import Device, DeviceState, ParameterState
+from majordom_integration_sdk.schemas.parameter import Parameter
+from pydantic import BaseModel, field_serializer, field_validator
+
+# Integration data
+
+
+class HKDeviceIntegrationData(Base):
+    # NOTE: must be initializable without any arguments
+
+    pairing_data: PairingData | None = None
+    characteristics_cache: AccessoriesState | None = None
+
+    # since AccessoriesState isn't a pydantic class, we need to implement (de)serialization
+
+    model_config = {
+        "arbitrary_types_allowed": True,
+    }
+
+    @field_serializer("characteristics_cache")
+    def serialize_characteristics_cache(self, v: AccessoriesState, _info) -> dict[str, Any]:
+        return v.as_dict() if v else {}
+
+    @field_validator("characteristics_cache", mode="before")
+    @classmethod
+    def parse_characteristics_cache(cls, v: Any) -> AccessoriesState | None:
+        if not v:
+            return None
+        if isinstance(v, AccessoriesState):
+            return v
+        if isinstance(v, dict):
+            return AccessoriesState.from_dict(v)
+        raise ValueError(f"Expected dict or AccessoriesState, got {type(v)}")
+
+
+class HKParameterIntegrationData(BaseModel):
+    type: UUID
+    aid: int
+    iid: int
+
+
+# Overriding types for ease of use (shortcuts)
+
+
+class HKParameter(Parameter):
+    integration_data: HKParameterIntegrationData
+
+
+class HKParameterState(ParameterState):
+    integration_data: HKParameterIntegrationData
+
+
+class HKDevice(Device):
+    integration_data: HKDeviceIntegrationData
+
+    @property
+    def hk_id(self) -> str:
+        assert self.integration_data and self.integration_data.pairing_data
+        return self.integration_data.pairing_data["AccessoryPairingID"].lower()
+
+
+# never used
+class HKDeviceState(HKDevice, DeviceState):
+    # HKDevice + DeviceState — only used in isolation for convenient parsing, so the
+    # parameter-type narrowing is safe here.
+    parameters: list[HKParameterState]

majordom_homekit-0.1.2/majordom_homekit/pairings_storage.py

@@ -0,0 +1,69 @@
+"""
+TLDR: same purpose as characteristics_storage.py
+"""
+
+from collections.abc import Callable
+from contextlib import AbstractAsyncContextManager
+
+from aiohomekit.model.typed_dicts import HKDeviceID, PairingData
+from aiohomekit.storage.pairing_data_storage import PairingDataStorageProtocol
+from majordom_integration_sdk.repository import DeviceRepositoryProtocol
+
+from .mapper import HKMajorDomMapper
+from .models import HKDevice
+
+
+class HKPairingsStorageMajorDom(PairingDataStorageProtocol):
+    def __init__(
+        self,
+        make_device_repository: Callable[[], AbstractAsyncContextManager[DeviceRepositoryProtocol]],
+        mapper: HKMajorDomMapper,
+    ):
+        self.make_device_repository = make_device_repository
+        self.mapper = mapper
+
+    @property
+    def _integration_name(self):
+        return "HomeKit"
+
+    # aiohomekit.PairingsStorageType
+
+    async def get_all(self) -> dict[HKDeviceID, PairingData]:
+        # keyed by the HAP pairing id (HKDeviceID), matching HKCharacteristicsStorage.get_all
+        # and what aiohomekit looks pairings up by — not the MajorDom device UUID.
+        pairings: dict[HKDeviceID, PairingData] = {}
+        async with self.make_device_repository() as device_repository:
+            for device in await device_repository.get_all(as_=HKDevice):
+                if pairing_data := device.integration_data.pairing_data:
+                    pairings[device.hk_id] = pairing_data
+        return pairings
+
+    async def get(self, id: str) -> PairingData | None:
+        uuid = self.mapper.hap_id_to_uuid(id)
+        async with self.make_device_repository() as device_repository:
+            if (device := await device_repository.get(uuid, as_=HKDevice)) and (
+                pairing_data := device.integration_data.pairing_data
+            ):
+                return pairing_data
+        return None
+
+    async def save(self, id: str, item: PairingData):
+        uuid = self.mapper.hap_id_to_uuid(id)
+        async with self.make_device_repository() as device_repository:
+            if device := await device_repository.get(uuid, as_=HKDevice):
+                device.integration_data.pairing_data = item
+                await device_repository.save(device)
+
+    async def delete_model(self, id: str):
+        # TODO: check usage
+        uuid = self.mapper.hap_id_to_uuid(id)
+        async with self.make_device_repository() as device_repository:
+            if device := await device_repository.get(uuid):
+                device.integration_data.pairing_data = None
+                await device_repository.save(device)
+                # TODO: check if should delete the device
+                # Discussion:
+                # this class is responsible solely for managing pairing data storage, and should
+                # not be used for any other purpose.
+                # However, we should ensure there is no case of aiohomekit disconnecting from the
+                # device without notifying us.

majordom_homekit-0.1.2/majordom_homekit/parameters_map.py

@@ -0,0 +1,7 @@
+"""
+Supplemental metadata for parameters / characteristics that the API does not expose directly.
+Maps characteristic types to static values or callables that provide missing information — such as
+enum labels, value ranges, or units.
+"""
+
+parameters_map = {}

majordom_homekit-0.1.2/majordom_homekit/readme.md

@@ -0,0 +1,48 @@
+# HomeKit integration
+
+Bridges the Hub to HomeKit (HAP) accessories over IP, built on top of
+[`aiohomekit`](https://github.com/Jc2k/aiohomekit). `aiohomekit` owns the HAP protocol,
+discovery, pairing crypto, and the live connection; this integration adapts it to the
+Hub's `AbstractController` contract and persists HomeKit state in the Hub's database.
+
+## Files
+
+| File | Responsibility |
+|---|---|
+| `controller.py` | `AbstractController` implementation — lifecycle, pairing, control, and the aiohomekit discovery/event delegates |
+| `mapper.py` | HAP ↔ MajorDom conversions: UUIDs (via the framework helpers), characteristic → parameter, formats/units/permissions/valid-values |
+| `models.py` | Typed `integration_data` schemas (`HKDevice`, `HKParameter`, …) |
+| `characteristics_storage.py` | Adapts aiohomekit's characteristics cache onto the Hub's `DeviceRepository` |
+| `pairings_storage.py` | Adapts aiohomekit's pairing-data storage onto the Hub's `DeviceRepository` |
+
+The two storage classes implement aiohomekit's storage protocols so that all HomeKit
+state lives in the Hub DB rather than aiohomekit's own files. They share the controller's
+single `HKMajorDomMapper` instance, so every HAP id maps to the same MajorDom UUID
+everywhere.
+
+## Discovery & pairing
+
+- **Discovery** uses the Hub's shared Zeroconf service: aiohomekit browses `_hap._tcp` /
+  `_hap._udp` using the `AsyncZeroconf` handed to it from
+  `dependencies.zeroconf_discovery_service`, and calls back into
+  `_aiohomekit_did_discover`. Already-paired accessories seen again trigger a reconnect;
+  accessories paired to another controller are surfaced but not offered for pairing.
+- **Pairing** takes a HAP setup code (`CredentialsType.code`, `DDD-DD-DDD`). The credentials
+  type is validated against the discovery's `expected_credentials_options` before pairing.
+
+## Availability
+
+aiohomekit only pushes a *became-available* signal, never *became-unavailable*, so the
+controller polls each paired accessory's connection state (`_availability_loop`) and
+funnels both directions through `_set_availability`, which dedupes and emits the
+framework's `controller_did_connect_device` / `controller_did_lose_device`.
+
+## Tests
+
+`tests/test_controllers/test_homekit/` runs against aiohomekit's in-process
+`AccessoryServer` (a fake accessory) — no real hardware needed.
+
+## Not yet implemented
+
+- BLE discovery/pairing (aiohomekit supports it; the Hub wires IP only for now).
+- Multi-accessory bridges save only the first accessory's manufacturer.

majordom_homekit-0.1.2/pyproject.toml

@@ -0,0 +1,106 @@
+[project]
+name = "majordom-homekit"
+version = "0.1.2"
+description = "HomeKit integration for MajorDom — bridges HomeKit accessories into the MajorDom language."
+authors = [{ name = "Mark Parker", email = "mark@parker-programs.com" }]
+readme = "README.md"
+requires-python = ">=3.12,<3.14"  # upper bound comes from parker-aiohomekit
+dependencies = [
+    "majordom-integration-sdk (>=0.1,<1.0)",
+    "parker-aiohomekit (>=4.0.1,<5.0.0)",
+]
+
+[dependency-groups]
+dev = [
+    "poethepoet (>=0.36.0,<1.0.0)",
+    "ty",
+    "ruff",
+    "pip-audit",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "pytest-timeout",
+    "pytest-repeat",
+    "pytest-benchmark",
+    "pytest-profiling",
+    "pytest-resource-usage",
+    "coverage",
+    "pympler",
+    "psutil",
+    "faker",
+]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+requires-poetry = ">=2.0"
+packages = [{ include = "majordom_homekit" }]
+
+# DEV-MODE: local paths to the private SDK. Switch to the published PyPI package when going
+# public. (Our pydantic-discriminator fork isn't on PyPI either — see the SDK's pyproject.)
+[tool.poetry.dependencies]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = ["."]
+filterwarnings = ["once"]
+
+[tool.coverage.run]
+omit = ["tests/*"]
+
+[tool.ruff]
+line-length = 120
+indent-width = 4
+
+[tool.ruff.lint]
+select = ["E", "F", "UP", "B", "SIM", "I"]
+fixable = ["ALL"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+docstring-code-format = true
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+"tests/*" = ["E402"]
+
+
+[tool.poe.tasks.install]
+shell = """
+poetry install
+echo '#!/bin/sh\npoetry run poe check' > .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+echo "Pre-commit hook installed."
+"""
+
+[tool.poe.tasks.check]
+shell = """
+code=0
+
+echo "\nRunning ruff lint:"
+poetry run ruff check --fix || code=1
+
+echo "\nRunning ruff format:"
+poetry run ruff format || code=1
+
+echo "\nRunning ty:"
+poetry run ty check || code=1
+
+echo "\nRunning pytest:"
+poetry run pytest --cov=majordom_homekit --cov-report=xml || code=1
+
+echo "\nRunning poetry build:"
+poetry build || code=1
+
+echo "\nRunning poetry check:"
+poetry check || code=1
+
+${ci:+git diff --exit-code}
+
+exit $code
+"""
+args = [{ name = "ci", type = "boolean" }]