Skip to content

Quality Checklist

The Implementation Checklist gets your integration functional — it launches, pairs, controls, and reports. This checklist gets it reliable and maintainable: it's the bar an integration must clear before it's released.

Items are ordered from vital (never ship without them) to nice-to-have.

Track it in your repo, not here

The integration template README ships both checklists as a fillable copy — tick items there as you implement them and your CI goes green. This page is the reference that explains the why behind each item.


Reliability — vital

An integration must never take the Hub down, and never spam the logs. The Hub isolates a crashing integration where it can, but a quality integration doesn't rely on that.

  • [ ] Recovers automatically. Connection loss, an offline device, or a restarted backend/radio must recover on their own — no manual restart. Reconnection is retried with backoff, not a tight loop.
  • [ ] No exception escapes the controller. Every background task, subscription loop, and callback catches its own errors. An unhandled exception in a background task dies silently; one raised inside a self.output.* call propagates back into the Hub. Neither is acceptable.
  • [ ] Failures are surfaced, not raised. An expected/transient failure (device offline, bad reading, timeout) is logged once (no repeated spam) and reflected on the device — device.available = False and a human-readable last_error — then cleared on recovery. It does not bubble up as an exception.
  • [ ] Re-authenticates automatically when credentials expire or are rejected (if the protocol uses credentials).
  • [ ] Fully asynchronous. No blocking I/O on the event loop; blocking or CPU-heavy work runs off-loop (a thread/executor) so it can't stall the Hub.
  • [ ] Availability is live. Offline/online is detected while the Hub is running, not only on reboot (this also appears on the implementation checklist — it's a reliability requirement, so it's repeated here).
  • [ ] Stable identity. Device and parameter UUIDs are derived through the SDK helpers, so they stay identical across restarts and re-pairs — state and automations survive.
  • [ ] No environment variables and no device paths. Radios, servers, discovery and options arrive from the Hub. Nothing is read from the environment or hardcoded, so the integration works with whatever stick the user plugs in.
  • [ ] Everything external declared as a Need — radios, BLE_ROUTER, ZEROCONF, UPNP_SSDP, and the companion servers it brings as Services. Never raw Bluetooth (ble/bluez): the router holds every adapter. Optional (BLE_ROUTER(is_required=False)) where the integration still works without it.
  • [ ] Bound needs read from self.peripherals, host facts and storage from self.platform, settings from self.settings, reports through self.output.
  • [ ] Integration-level problems reported with a stable error id (IntegrationError) and resolved when they clear (controller_did_resolve_error), e.g. once the server is back.

Tested — vital

  • [ ] End-to-end automated tests drive the controller through pair → command → fetch → events → unpair against a virtual/simulated device (the SDK's majordom_integration_sdk.testing doubles), with no physical hardware required.
  • [ ] Failure paths are tested — offline device, transport error, rejected credentials, a failed pairing rolled back by unpair(draft) and then retried, unpair of an unreachable device raising DeviceUnreachableError — asserting the integration degrades gracefully (sets available/last_error, does not raise).
  • [ ] Behaviour without a required radio is tested. Losing the radio or service while running reports an IntegrationError with is_still_running=False, so the Hub restarts the integration, instead of hanging; an unbound optional need doesn't stop it from starting.
  • [ ] Broad device coverage where the protocol has many device/parameter types — exercise the full mapping surface, not one happy-path device. (A protocol-provided virtual-device catalogue, run in CI, is the ideal.)

Maintainable — important

  • [ ] Fully typed — passes ty with no package-wide ignore blocks; any exceptions are file/rule-scoped and commented with why.
  • [ ] Clean — passes the full poe check (ruff lint + format, ty, tests, build) with no warnings.
  • [ ] Readable & structured — clear names, comments where the intent isn't obvious; conversion logic lives in a mapper and models are separated, per the template layout.
  • [ ] Efficient — prefer event subscriptions over polling; batch or chunk reads; avoid redundant network and CPU work.
  • [ ] Diagnosable — logging at the right levels, enough to debug a device problem from the logs alone. A device-state diagnostic dump is a bonus.
  • [ ] Owned — a listed maintainer who keeps it working as the protocol and the upstream library evolve.

User experience — important

  • [ ] Settings have plain-language titles. Every settings field has a title (and a description where it helps) written for the user, and a default.
  • [ ] Rich parameter metadata. Every parameter has the correct visibility (user / setting / system) and the device's main parameter is set — so the app can present a clean control-center action, a sensible on-tap parameter list, a settings page, and hidden system internals. Getting this right is what makes a device feel native rather than a raw dump of protocol attributes; a poorly-mapped device is a poor device, however reliable it is.

Extras — nice-to-have

  • [ ] Logical, localizable naming — device and parameter names read well to a non-technical user and can be translated.
  • [ ] Firmware/software updates — device firmware can be updated through the Hub, where supported. (The update API is still WIP.)
  • [ ] User documentation — a supported-device list, setup notes, and troubleshooting aimed at non-technical users.

Reporting errors

The reliability rules above hinge on one habit: catch errors at the edges and turn them into state, not exceptions.

  • Inside a background task or subscription loop, wrap the body in a try/except. On a per-device failure, set that device's available/last_error and keep the loop alive.
  • Never let an exception cross into a self.output.* call — the Hub treats those callbacks as trusted and an exception there can disrupt Hub-side handling.
  • Log an expected failure once at the appropriate level; don't re-log the same condition every poll.

For controller-level problems that aren't tied to a single device (e.g. the backend/radio went away entirely), call controller_did_encounter_error with an IntegrationError — it surfaces a plain-language message to the user until you resolve its id with controller_did_resolve_error, and is_still_running=False marks the whole integration as failed. See Reporting errors to the user.