majordom-matter 0.1.3

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)

majordom-matter is a standalone library — import it into your own app, or run just this integration interactively (discover, pair, control, and inspect devices from a prompt) with no Hub. It needs a running python-matter-server reachable over its WebSocket (MATTER_SERVER_URL, default ws://localhost:5580/ws); Thread devices also need an OpenThread Border Router.

See Standalone mode for the interactive CLI, watch mode, and the programmatic API.

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)

Parameter metadata sources & priority

Every parameter's UX metadata is resolved from several sources. See also the parameter-ux recipe.

Visibility / role / unit — resolved by classify_attribute() in matter_spec.py (first match wins):

#	Source	What it is
—	system cluster / sensitive (Aliro* crypto)	forced system (safety, top priority)
1	OUR_ATTRIBUTE_UX (USER_READINGS, EVERYDAY_CONTROL_ATTRIBUTES)	our hand curation
2	MATTER_HA_ATTRIBUTE_UX	judgment harvested from Home Assistant's Matter discovery (scripts/harvest_matter_ha.py, AST-parsed, vendored — no homeassistant dep)
3	fallback policy	writable → setting, else system; logs a warning on uncurated attrs. Flip _FALLBACK_HIDE_UNCURATED once coverage is validated.

Matter has no runtime quirk layer, so (unlike zigbee) there is no v2-quirk tier. The Matter Data Model (chip) already supplies names/types/bounds; the harvest adds only the entity_category (user/config/diagnostic) judgment the spec doesn't dictate.

Bounds come from the device's own limit attributes (runtime) > spec tables > wire-type range — see resolve_runtime_bounds() / METADATA_SOURCES.

Drift. scripts/check_matter_ha_drift.py re-runs the AST harvest against home-assistant/core and diffs vs the vendored artifact via the SDK's diff_specs, tiering ADD / REMOVE / RECLASSIFY.

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. The same drift machinery (the SDK's diff_specs) now also watches the harvested HA-Matter judgment.

License

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