docs: add documentation

zwave-js · Jan 19, 2024 · c58c2fa · c58c2fa
1 parent 098b8d1
commit c58c2fa
Show file tree

Hide file tree

Showing 4 changed files with 23 additions and 0 deletions.
diff --git a/docs/_sidebar.md b/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)

diff --git a/docs/api/CCs/_sidebar.md b/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)

diff --git a/docs/api/controller.md b/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[];
 	/**

diff --git a/docs/getting-started/long-range.md b/docs/getting-started/long-range.md
@@ -0,0 +1,11 @@
+# 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.
+2. 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).