majordom-matter 0.1.1

Matter integration for MajorDom — bridges Matter devices into the MajorDom language.

integration-matter

A MajorDom integration — bridges Matter (CSA Connectivity Standard) devices into the MajorDom language.

Built for the MajorDom Hub, but it doesn't need it: this is a standalone, standardized library for Matter that you can use on its own (see Run it standalone below). Built on the MajorDom Integration SDK. The entry point is MatterController (majordom_matter/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. The default suite drives the controller against a canned node with the SDK's test doubles — no matter-server, no docker (tests/test_controller_stub.py). The exhaustive real-device coverage commissions Google's Matter Virtual Devices in a dockerized matter-server (tests/test_controller.py, see docker-compose.matter-tests.yml); the MVD binaries + PAA certs are fetched, not committed.

Run it standalone (without the Hub)

Matter needs a running python-matter-server (it owns the fabric and the Thread/BLE radios) reachable over its WebSocket — set MATTER_SERVER_URL (default ws://localhost:5580/ws). Thread devices also need an OpenThread Border Router. Then:

# run.py
import asyncio

from majordom_integration_sdk.dev import run_controller
from majordom_matter import MatterController

# Watches for Matter devices, logs discoveries/events. Ctrl-C to stop.
asyncio.run(run_controller(MatterController, db_path="devices.db"))

poetry run python run.py

About this integration

• Protocol / platform: Matter (Connectivity Standards Alliance) via python-matter-server + chip.
• Transport(s): IP over Thread / Wi-Fi / Ethernet; BLE for commissioning.
• Supported devices: any Matter-certified device — lights, plugs, switches, sensors, locks, thermostats, covers, fans, appliances (verified against 30 Matter Virtual Device types).
• Credentials needed to pair: code (manual pairing code) or qr.

Required harness

• Hardware adapters: an 802.15.4 radio (e.g. a SkyConnect / Thread dongle) for Thread devices — driven by matter-server / the OTBR, not this package directly.
• Third-party software services: a matter-server instance reachable over WebSocket (MATTER_SERVER_URL), and an OpenThread Border Router (OTBR) for Thread devices.
• OS / permissions: BLE access for commissioning; mDNS on the LAN for on-network discovery.

Protocol stack (OSI)

OSI layer	Protocol	Implemented by
Application (7)	Matter clusters / data model	this integration (via chip lib)
Session (5)	CASE / PASE secure session	library (matter-server)
Transport (4)	UDP	OS
Network (3)	IPv6 · 6LoWPAN	OS · OTBR (harness)
Data link / Physical (1–2)	Thread · IEEE 802.15.4 (or Wi-Fi / Ethernet)	radio adapter (harness)

Progress

• Discovery services registered (mDNS on-network via matter-server; BLE for commissionable devices); cancel closures called in stop
• Discovery listeners fire and call controller_did_receive_discovery
• Re-discovery of already-paired devices on reconnect (controller_did_connect_device)
• Device pairing (BLE→Thread and on-network commissioning)
• Device schema mapped: device info, parameter list, per-parameter metadata → MajorDom's domain model
• 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 virtual/simulated devices (stub + dockerized MVD suite)

Notes

The MVD chef binaries are x86-64 Linux only, so the real-device suite runs in an amd64 container (Rosetta on Apple Silicon). A monthly canary fetches the latest upstream MVD release and fails if it ships something unsupported — the signal to add support.

License

See LICENSE. For commercial licensing or partnership inquiries regarding MajorDom, contact us via parker-industries.org/partnership.