majordom-homekit 0.1.3

HomeKit integration for MajorDom — bridges HomeKit accessories into the MajorDom language.

integration-homekit

A MajorDom 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. 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.
• Create your own: start from the integration template.

Documentation

Full integration-author docs — the controller lifecycle, data models, storing data, discovery, and a worked example — live at docs.majordom.io.

Development

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:

# 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"))

poetry run python run.py

To use the integration in standalone mode — discover, pair, control, or fetch a device programmatically — build the dependencies yourself and call the controller directly. Visit the MajorDom integration docs for more details, like the dependency structure and receiving discoveries/events in standalone mode by implementing a delegate.

import asyncio

from majordom_integration_sdk.dev import build_dependencies
from majordom_integration_sdk.schemas.device import ProvidedCredentials
from majordom_homekit import HomeKitController

async def main():
    deps = build_dependencies(integration=HomeKitController.name, db_path="devices.db")
    controller = HomeKitController(deps)
    await controller.start()
    # ... await controller.pair_device(discovery, ProvidedCredentials(...)), send_command, fetch ...
    await controller.stop()

asyncio.run(main())

About this integration

• Protocol / platform: Apple HomeKit Accessory Protocol (HAP) via the 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

• Discovery services registered (mDNS via zeroconf_discovery_service; BLE where applicable); cancel closures called in stop
• Discovery listeners fire and call controller_did_receive_discovery
• Re-discovery of already-paired accessories on reconnect (controller_did_connect_device)
• Device pairing (HAP pair-setup with the setup code)
• Device schema mapped: services/characteristics → parameter list with per-parameter metadata
• Hub → Device control (send_command)
• Device → Hub event subscription (controller_did_receive_events)
• identify
• unpair
• fetch
• Availability tracking while running (controller_did_lose_device / last_error)
• Graceful shutdown in stop
• 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. For commercial licensing or partnership inquiries regarding MajorDom, contact us via parker-industries.org/partnership.