integration-zwave

A MajorDom integration — bridges Z-Wave devices into the MajorDom language.

Built for the MajorDom Hub, but it doesn't need it: this is a standalone, standardized library for Z-Wave that you can use on its own (see Run it standalone below). Built on the MajorDom Integration SDK. The entry point is ZwaveController (majordom_zwave/controller.py), which the Hub — or the SDK's dev runner — instantiates and drives through its lifecycle: 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

Work lands on develop; master is protected and released via Actions → Release.

Tests drive the controller with the SDK's test doubles against a mock Z-Wave network: zwave-js's own mock controller and mock devices, with a real zwave-js driver and a real zwave-js-server in front (tests/mock) — the integration connects to it exactly as to a real server, no radio or stick required. It needs Node.js 20+:

npm ci --prefix tests/mock && poetry run pytest

Command-class catalogue and canary

tests/test_catalogue.py accounts for every command class zwave-js knows (125 today): each is hosted by a mock device (a recipe in tests/mock/catalogue.mjs: 34 of them, all their capabilities switched on), is protocol plumbing, or is listed in tests/catalogue.py with the reason the mock cannot host it. Each hosted one must map exactly as EXPECTED says — name, type, role, visibility, unit, main parameter, reviewed value by value against the docs' parameter UX — pass the SDK's parameter_audit, and round-trip every writable value through the device. Seven more mock devices carry every variant zwave-js knows (88 sensor types and their scales, 14 binary sensors, 5 meters with all their scales, 22 notification types with all their states and events, 12 setpoints, 16 thermostat modes), checked against rules. Fast checks fail on a new command class, value metadata type or unit.

The monthly canary (.github/workflows/canary.yml) runs all of it against the latest zwave-js, zwave-js-server and zwave-js-server-python: red means upstream shipped something to support, or to explain.

Run it standalone (without the Hub)

majordom-zwave 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 reachable zwave-js-server instance (see below).

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

Connecting to zwave-js-server

Unlike a radio-based integration, this one never talks to the Z-Wave stick directly. It connects over WebSocket, via zwave-js-server-python, to a running zwave-js-server process (Node.js) — the same server Home Assistant's Z-Wave JS integration uses. zwave-js-server is what actually owns the serial connection to the Z-Wave USB controller and speaks the Z-Wave protocol; this integration just talks JSON over a WebSocket to it.

• Run zwave-js-server yourself (commonly via Docker) on whatever machine has the Z-Wave USB controller attached.
• Point this integration at it with the ZWAVE_SERVER_URL environment variable (default ws://localhost:3000) — see majordom_zwave/config.py.
• The integration keeps reconnecting (1 → 30 s backoff) while the server is unreachable; paired devices are reported unavailable meanwhile, with the reason as their last_error.

About this integration

• Protocol / platform: Z-Wave, via zwave-js-server / zwave-js-server-python.

• Transport(s): Z-Wave (sub-GHz RF mesh).

• Supported devices: any Z-Wave / Z-Wave Plus device exposing standard Command Classes (Binary/Multilevel Switch, Indicator, etc.) that Z-Wave JS supports.

• Credentials needed to pair: given when opening the pairing window (start_pairing_window), not at pair_device time — Z-Wave needs them during inclusion, before the device exists as a discovery; the discovery itself always expects CredentialsType.none.

  • code — the S2 PIN (the first 5 digits of the DSK on the device's label), or the whole DSK.
  • qr — the device's QR code (90…); malformed codes are rejected. An S2 code includes the device in the window; a SmartStart code provisions it instead: zwave-js includes it securely, with no PIN, whenever it is powered on (hours later, after installation), and it then arrives as a discovery. Unpairing removes it from the provisioning list, or it would join again.
  • none — the device joins, but without the S2 Authenticated / Access Control classes (they need the PIN); its discovery's last_error says so.
  • secret — not supported.

  The Hub does not pass credentials to start_pairing_window yet (the SDK's develop has the parameter).

Required harness

• Hardware adapters: a Z-Wave USB controller (e.g. Aeotec/Zooz Z-Stick) — but it's attached to whatever host runs zwave-js-server, not necessarily the Hub. This integration doesn't use dependencies.hardware_interfaces; the radio is abstracted behind the server.
• Third-party software services: zwave-js-server (Node.js) must be running and reachable at ZWAVE_SERVER_URL.
• OS / permissions: network reachability (TCP) to the zwave-js-server host:port. No special permissions needed on the Hub's own host.

Protocol stack

Manual testing (real hardware)

Verified against real hardware, on the version before the rework of 2026-10 (the rework is tested against the mock network only; to be re-run on hardware before release):

• Z-Wave controller: Z-Stick 7 (ZWA010)
• Test device: HKZW-RGB01 v1.0 (RGB bulb)

Mapping

Progress

Implementation — makes the integration functional:

• Discovery of joining devices ("node added"), and of nodes already on the network but not paired
• Discovery of already-paired devices on (re)connect — matched by home id and node id, and checked against the device's fingerprint (a node id reused by another device is not taken for the paired one)
• start_pairing_window (default, S2 PIN or DSK, S2 QR, SmartStart)
• Device pairing (completes the device the Hub created; fails cleanly and stays discovered when the device does not finish its interview)
• Device schema mapped (see Mapping)
• Hub → Device control (send_command); the state comes back as the device's report, never echoed
• Device → Hub events ("value updated", "value notification", "notification": keypads, Notification CC events, remote dimming, low battery, radio tests)
• identify — Indicator CC v3 identify; a light blinks; any other device is left alone (a relay or a motor may drive a heater, a pump or a blind)
• unpair — a failed node is removed without the device; a live one when this device confirms the exclusion
• fetch
• Availability — "dead"/"alive", the server connection, a device removed with another tool
• Graceful shutdown in stop
• Tests pass against a simulated network (mock zwave-js controller and devices)

Quality — makes it reliable and maintainable (the bar for release):

• Recovers automatically from a lost or restarted zwave-js-server (reconnects with backoff)
• No exception escapes background work — event handlers run as logged tasks; Hub calls raise after recording the reason
• Failures are surfaced, not swallowed — the reason is the device's or discovery's last_error; an unreachable server at start is reported through controller_did_encounter_error
• Re-authenticates automatically — not applicable (Z-Wave has no expiring credential)
• Fully asynchronous
• Stable identity — the SDK helpers, scoped by the network's home id
• End-to-end tests drive pair → command → fetch → events → unpair against the mock network
• Failure paths tested — unreachable or lost server, unresponsive and refusing devices, interview timeout, exclusion timeout, the wrong device excluded, a reused node id, a missing PIN
• Broad device coverage — the catalogue hosts 33 command classes (switches, dimmers, lights, sensors, meters, locks, thermostats, covers, garage doors, scene controllers, sirens, user codes, child locks, humidifiers, keypads, smoke/CO alarms, sleeping devices, …); S2 by PIN, DSK, QR and SmartStart. The others are plumbing or explained (see Command-class catalogue and canary)
• Fully typed (ty) and clean (poe check)
• Readable & structured — mapping in mapper.py, static tables in zwave_spec.py
• Efficient — subscription-based, not polling
• Diagnosable — per-area log tags ([PAIR], [CONNECT], …), reasons in last_error, causes chained
• Rich parameter metadata — role, visibility, units, limits, enum labels, main parameter; names and buckets reviewed against the docs' parameter UX for every hosted CC, and audited (parameter_audit)
• Owned — add a listed maintainer
• nice-to-have: localizable naming · firmware updates · user-facing supported-device docs

Notes

• Z-Wave discovery doesn't use zeroconf/ssdp/ble: nodes are surfaced from zwave-js-server's own events.
• Command classes zwave-js's mock cannot host (rare ones: tariffs, IP gateways, AV, schedules, irrigation) are not reviewed: their values map by the generic rules and are hidden (system), still usable by automations and the API.
• What zwave-js's mock cannot do, so the catalogue does not round-trip it: decode a Color Switch Set, keep an Indicator's state; its Thermostat Setpoint Set refuses every value above the minimum, so the harness replaces it.

License

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