MajorDom Device Integration Guide¶
Under active development
MajorDom is still under development.
The integration structure is now stable, but implementation details are still subject to change.
An integration is a standalone Python package that bridges MajorDom Hub with IoT devices of a specific protocol or vendor (e.g. HomeKit, Zigbee, Z-Wave). It depends only on the published majordom-integration-sdk — not on the Hub source — so it can be developed, tested, and even run on its own.
Getting started¶
Don't start from a blank folder. Every integration is scaffolded from the integration-template repository: click Use this template → Create a new repository, name it integration-<protocol>, and follow the template README's checklist (rename the placeholder package to majordom_<protocol>, poe install, wire up CI and PyPI publishing). The template ships a working example controller, tests, and CI, so you replace pieces rather than assemble them from scratch. This guide explains the concepts behind that code.
Licensing¶
The SDK and the integration template are released under the Apache License 2.0: use them freely, for MajorDom integrations or in your own projects, including library mode. We do ask you to keep what you build on them open source.
Most official integrations are source-available for noncommercial use. For a commercial license, contact us — we're open to partnership: https://parker-industries.org/partnership.
Concepts¶
| Term | Meaning |
|---|---|
| Hub | The MajorDom Hub core software |
| Integration | A protocol/vendor-specific plugin |
| Peripheral | Anything that needs or provides capabilities: a radio, a service, an in-process provider, the integration's controller itself. See Peripherals |
| Need | Something external a peripheral requires: a radio, a server, or a discovery provider (ZEROCONF, UPNP_SSDP, BLE_ROUTER). The runtime binds it and hands it over in self.peripherals |
| Discovery Service | A provider the runtime runs in-process (Zeroconf, SSDP, or the Bluetooth router) that fires raw discovery events. Needed like any other, see Discovery Services |
| Controller (capitalized) | The class your integration must implement (AbstractController subclass) |
| a controller (lowercase) | Any third-party device that can control IoT devices (smartphone, Alexa, etc.) |
| Discovery | A detected, unpaired device that is available to be paired |
| Device | A paired and controllable device saved in the Hub's database |
| Parameter | A single controllable or observable property of a device (e.g. brightness, temperature) |
A device moves through these states:
Suggested Module Structure¶
Your integration is its own package, majordom_<protocol>/ (the template starts you with this — integration_template/ renamed). An integration will typically need more than just a controller. Recommended minimal layout:
majordom_myintegration/
├── __init__.py # exports peripherals(platform): the controller and the services it brings
├── controller.py # AbstractController subclass — the only required implementation; discovery callbacks and cancel closures are typically stored here too
├── models.py # Typed integration_data schemas for Device and Parameter subclasses, see Storing Data
├── mapper.py # Protocol ↔ MajorDom domain model conversions, isolated from the controller for readability
└── parameters_map.py # Supplemental metadata for parameters that the API does not expose, usually in a form of a static dictionary. For example, device might expose min/max limits for a number via device's API, but the unit is only defined in pdf specification.
controller.py is the only required implementation. The rest are a template for keeping the controller clean — separate models, pull out conversion logic into a mapper, add metadata dictionary, etc. Of course, other files can be added as needed.
Implementation Checklist¶
Track it in your repo: the integration template README ships this and the Quality Checklist as a fillable copy — tick items there as you implement them. The list below is the reference.
- [ ] Discovery registered with the providers it needs —
self.peripherals.instance(ZEROCONF),UPNP_SSDPand/orBLE_ROUTERas appropriate; cancel closures saved and called instop - [ ] Discovery listeners fire when devices are found, and the controller calls
self.output.controller_did_receive_discovery - [ ] Every reachable paired device reported on start (
self.output.controller_did_connect_device(self, physical_id=...)): the Hub marked them all unavailable when the integration stopped - [ ]
start_pairing_windowis implemented if the protocol requires an explicit scan mode - [ ] Device pairing (
pair_deviceis implemented, and validates the incomingProvidedCredentials.typeagainstdiscovery.expected_credentials_optionsbefore using it; fills the draft it is given and returns it, without using the repository or reporting the device; setsphysical_idand callscheck_device_idonce it is known, never changes the Hub'sid) - [ ] Device schema is properly mapped: device info, parameter list, and each parameter's metadata are translated to MajorDom's domain model
- [ ] Hub → Device control (
send_commandis implemented) - [ ] Device → Hub event subscription (
self.output.controller_did_receive_eventsis called on incoming events) - [ ]
identify,unpair, andfetchare implemented:unpairalso rolls back a failed or unsaved pairing (any partial state, reverse order, only what blocks a re-pair, no waiting for the user, safe to call again) and raisesDeviceUnreachableErrorwhen the device can't be reached;pair_devicesets identity only,fetchreturns the whole device with its parameters (orNonewhen it doesn't answer); both are idempotent (check the device, re-subscribe only if the subscription is gone, bounded time) - [ ] Paired devices going offline/coming back online while the Hub is running (not just on reboot) — set
device.availableaccordingly, and clear/setlast_errorto match - [ ] Graceful shutdown in
stop - [ ] Everything external declared as a
Need— radios,BLE_ROUTER,ZEROCONF,UPNP_SSDP, the services it brings; never raw Bluetooth - [ ] Bound needs read from
self.peripherals, host facts and storage fromself.platform, reports sent throughself.output - [ ] Integration-level problems reported with a stable error id (
IntegrationError) and resolved when they clear - [ ] Quality: once it's functional, the integration meets the Quality Checklist — reliability, tests, and maintainability — before release
See Implementing a Controller for details, or Example Integration for a narrative walkthrough of the template's controller. The template README mirrors this checklist as its Progress list, so you can track your integration against it directly in your repo.
Running standalone¶
You don't need a running Hub to develop an integration. The SDK ships a dev runner that binds your controller's needs through the SDK runtime, as the Hub does (the Bluetooth router, Zeroconf, SSDP, radios and services), gives it a local repository, starts it, and logs everything it discovers:
import asyncio
from majordom_integration_sdk.dev import run_controller
import majordom_myintegration
asyncio.run(run_controller(majordom_myintegration.peripherals))
It needs the runtime extras: pip install "majordom-integration-sdk[runtime,ble,discovery]". Pass db_path=... to persist devices across restarts (a file-backed SQLite repository) instead of the default in-memory one. See Standalone Mode for the interactive CLI, build_platform for your own scripts, and running without Docker or radios.
Testing¶
Integrations run their tests against a virtual/simulated device where possible, so CI doesn't need physical hardware. The SDK's majordom_integration_sdk.testing module provides the doubles: build_test_platform() wires a RecordingControllerOutput, an in-memory repository and temp-dir storage, and FakeZeroconf, FakeSSDP, FakeBLERouter (with FakeBLESources) and FakeOffers stand in for the peripherals, so a test can drive your controller and assert on what it reported. The template's tests/ show the pattern. (Real-hardware validation lives in the Hub, not in the integration package.)
Notes¶
For IP Devices¶
- Handle IP changes. DHCP can reassign addresses. Identify devices by a stable ID (MAC, serial, mDNS hostname, domain-provided id) rather than IP. Monitor ip address regularly and keep it up to date.
- Use the Hub's provided discovery. Need
ZEROCONF,UPNP_SSDPorBLE_ROUTERand register throughself.peripherals.instance(ZEROCONF).register(...). See Discovery Services. Do not run your own discovery stack.
For all code¶
- No hand-typed keys: if a typo breaks it, type it. Static keys and formatted strings come from typed names, never from a bare string literal repeated where they're used:
- the SDK's typed needs,
BLE_ROUTER,ZEROCONFandUPNP_SSDP, read back withself.peripherals.instance(BLE_ROUTER); SettingsExtraFieldfor settings fields:Field(11, json_schema_extra={Extra.read_only: True});ComposeServicefor a service's compose definition;- your own enum or constant for anything else.
- the SDK's typed needs,
- Ids come from one helper each. Derive device and parameter ids through the SDK helpers or one function of your own, never a format string repeated across the code. It's the same rule as above: a typo makes a second id, and state and automations stop matching.
- Error messages and other text meant for people stay plain strings.