chore: merge Z-Wave LR support into master branch

CHANGELOG.md

@@ -4,6 +4,18 @@
 <!--
 	Add placeholder for next release with `wip` snippet
 -->
+## __WORK IN PROGRESS__
+This release adds support for Z-Wave Long Range thanks to the amazing work of @jtbraun. Application developers planning to add support should read [this](https://zwave-js.github.io/node-zwave-js/#/getting-started/long-range) to get started.
+
+### Features
+* Support Z-Wave Long Range (#6401, #6620)
+
+### Bugfixes
+
+### Config file changes
+
+### Changes under the hood
+
 ## 12.4.4 (2024-02-10)
 ### Bugfixes
 * NVM backups can now be restored onto 800 series controllers (#6670)

docs/_sidebar.md

@@ -6,6 +6,7 @@
   - [Our Philosophy](getting-started/philosophy.md)
   - [Frequently Asked Questions](getting-started/faq.md)
   - [Security S2](getting-started/security-s2.md)
+  - [Z-Wave Long Range](getting-started/long-range.md)
   - [Migrating to v12](getting-started/migrating-to-v12.md)
   - [Migrating to v11](getting-started/migrating-to-v11.md)
   - [Migrating to v10](getting-started/migrating-to-v10.md)

docs/api/CCs/_sidebar.md

@@ -6,6 +6,7 @@
   - [Our Philosophy](getting-started/philosophy.md)
   - [Frequently Asked Questions](getting-started/faq.md)
   - [Security S2](getting-started/security-s2.md)
+  - [Z-Wave Long Range](getting-started/long-range.md)
   - [Migrating to v12](getting-started/migrating-to-v12.md)
   - [Migrating to v11](getting-started/migrating-to-v11.md)
   - [Migrating to v10](getting-started/migrating-to-v10.md)

docs/api/controller.md

@@ -170,6 +170,7 @@ interface PlannedProvisioningEntry {
 	/** The device specific key (DSK) in the form aaaaa-bbbbb-ccccc-ddddd-eeeee-fffff-11111-22222 */
 	dsk: string;
 	securityClasses: SecurityClass[];
+	// ...other fields are irrelevant for this inclusion procedure
 }
 ```
 
@@ -238,6 +239,7 @@ provisionSmartStartNode(entry: PlannedProvisioningEntry): void
 ```
 
 Adds the given entry (DSK and security classes) to the controller's SmartStart provisioning list or replaces an existing entry. The node will be included out of band when it powers up.
+If the `protocol` field is set to `Protocols.ZWaveLongRange`, the node will be included using Z-Wave Long Range instead of Z-Wave Classic.
 
 > [!ATTENTION] This method will throw when SmartStart is not supported by the controller!
 
@@ -256,6 +258,14 @@ interface PlannedProvisioningEntry {
 	/** The device specific key (DSK) in the form aaaaa-bbbbb-ccccc-ddddd-eeeee-fffff-11111-22222 */
 	dsk: string;
 
+	/** Which protocol to use for inclusion. Default: Z-Wave Classic */
+	protocol?: Protocols;
+	/**
+	 * The protocols that are **supported** by the device.
+	 * When this is not set, applications should default to Z-Wave classic.
+	 */
+	supportedProtocols?: readonly Protocols[];
+
 	/** The security classes that have been **granted** by the user */
 	securityClasses: SecurityClass[];
 	/**
@@ -1275,6 +1285,14 @@ readonly rfRegion: RFRegion | undefined
 Which RF region the controller is currently set to, or `undefined` if it could not be determined (yet).
 This value is cached and updated automatically when using [`getRFRegion` or `setRFRegion`](#configure-rf-region).
 
+### `supportsLongRange`
+
+```ts
+readonly supportsLongRange: MaybeNotKnown<boolean>;
+```
+
+Returns whether the controller supports the Z-Wave Long Range protocol. This depends on the configured RF region.
+
 ## Controller events
 
 The `Controller` class inherits from the Node.js [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) and thus also supports its methods like `on`, `removeListener`, etc. The available events are available:

docs/api/driver.md

@@ -828,15 +828,23 @@ interface ZWaveOptions extends ZWaveHostOptions {
 	};
 
 	/**
-	 * Specify the security keys to use for encryption. Each one must be a Buffer of exactly 16 bytes.
+	 * Specify the security keys to use for encryption (Z-Wave Classic). Each one must be a Buffer of exactly 16 bytes.
 	 */
 	securityKeys?: {
-		S2_Unauthenticated?: Buffer;
-		S2_Authenticated?: Buffer;
 		S2_AccessControl?: Buffer;
+		S2_Authenticated?: Buffer;
+		S2_Unauthenticated?: Buffer;
 		S0_Legacy?: Buffer;
 	};
 
+	/**
+	 * Specify the security keys to use for encryption (Z-Wave Long Range). Each one must be a Buffer of exactly 16 bytes.
+	 */
+	securityKeysLongRange?: {
+		S2_AccessControl?: Buffer;
+		S2_Authenticated?: Buffer;
+	};
+
 	/**
 	 * Defines the callbacks that are necessary to trigger user interaction during S2 inclusion.
 	 * If not given, nodes won't be included using S2, unless matching provisioning entries exists.

docs/api/node.md

@@ -1152,6 +1152,14 @@ While the volume for sound switch commands can be provided on a per-command basi
 
 This can be done using the `defaultVolume` property. It accepts a volume between 0 and 100 (in `%`) and will be used for all sound switch commands that do not specify a volume.
 
+### `protocol`
+
+```ts
+readonly protocol: Protocols
+```
+
+Which protocol is used to communicate with this node, Z-Wave (Classic) or Z-Wave Long Range.
+
 ## ZWaveNode events
 
 The `Node` class inherits from the Node.js [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) and thus also supports its methods like `on`, `removeListener`, etc.

docs/getting-started/long-range.md

@@ -0,0 +1,12 @@
+# Supporting Z-Wave Long Range in Applications
+
+Z-Wave Long Range (ZWLR) is an addition to Z-Wave, that allows for a massively increased transmission range and up to 4000 nodes in a single network. Z-Wave Long Range uses a star topology, where all nodes communicate directly with the controller. This means that ZWLR nodes cannot be used to route messages for non-ZWLR nodes.
+
+There are a few things applications need to be aware of to support Long Range using Z-Wave JS.
+
+1. ZWLR node IDs start at 256. This can be used to distinguish between ZWLR and classic Z-Wave nodes.
+1. ZWLR has only two security classes, S2 Access Control and S2 Authenticated. Both must use a different security key than their Z-Wave Classic counterparts. To configure them, use the `securityKeysLongRange` property of the [`ZWaveOptions`](../api/driver#zwaveoptions)
+1. ZWLR inclusion works exclusively through [Smart Start](../getting-started/security-s2#smartstart).
+   \
+   ZWLR nodes advertise support for Long Range in the `supportedProtocols` field of the `QRProvisioningInformation` object (see [here](../api/utils#other-qr-codes)). When this field is present, the user **MUST** have the choice between the advertised protocols. Currently this means deciding between including the node via Z-Wave Classic (mesh) or Z-Wave Long Range (no mesh).\
+   To include a node via ZWLR, set the `protocol` field of the `PlannedProvisioningEntry` to `Protocols.ZWaveLongRange` when [provisioning the node](../api/controller#provisionsmartstartnode).

docs/getting-started/security-s2.md

@@ -136,6 +136,12 @@ For modern devices, **SmartStart** makes the inclusion even easier for the user
 
 > [!NOTE] Confirming the inclusion process like with normal S2 inclusion is recommended, so users can react to a failed bootstrapping attempt.
 
+## Z-Wave Long Range
+
+Devices using Z-Wave Long Range can only be included via SmartStart. Since not all devices support Long Range, the protocol choice in the above screenshot should only be available after scanning a QR code that indicates support for Long Range (see below), or when the provisioning entry was added manually. Note that the **S2 Unauthenticated** and **S0 Legacy** security classes are not available for Z-Wave Long Range.
+
+> [!NOTE] We recommend to **not** preselect Z-Wave Long Range, even on supporting devices. Z-Wave Long Range is a separate protocol and the devices are not part of the Z-Wave mesh, so this choice should be an opt-in rather than an opt-out.
+
 ## Using QR codes to include devices
 
 Scanning a QR code can further simplify the inclusion process, because it limits the user interaction to scanning the code (and pushing a button for conventional inclusion):

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zwave-js/repo",
-  "version": "12.4.4",
+  "version": "12.5.0-beta.1",
   "private": true,
   "description": "Z-Wave driver written entirely in JavaScript/TypeScript",
   "keywords": [],

packages/cc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zwave-js/cc",
-  "version": "12.4.4",
+  "version": "12.5.0-beta.1",
   "description": "zwave-js: Command Classes",
   "keywords": [],
   "publishConfig": {