feat: automatically prefer LR-capable RF regions over their non-LR counterparts

docs/api/controller.md

@@ -824,6 +824,8 @@ export enum RFRegion {
 }
 ```
 
+> [!NOTE] Long Range capable regions are automatically preferred over their non-LR counterparts. This behavior can be disabled by setting the driver option `rf.upgradeToLRRegion` to `false`.
+
 > [!ATTENTION] Not all controllers support configuring the RF region. These methods will throw if they are not supported
 
 #### Configure TX powerlevel

docs/api/driver.md

@@ -938,6 +938,14 @@ interface ZWaveOptions extends ZWaveHostOptions {
 		/** The RF region the radio should be tuned to. */
 		region?: RFRegion;
 
+		/**
+		 * Whether LR-capable regions should automatically be chosen over their corresponding non-LR regions, e.g. `USA` -> `USA (Long Range)`.
+		 * This also overrides the `rf.region` setting if the desired region is not LR-capable.
+		 *
+		 * Default: true.
+		 */
+		upgradeToLRRegion?: boolean;
+
 		txPower?: {
 			/** The desired TX power in dBm. */
 			powerlevel: number;

packages/zwave-js/src/lib/controller/Controller.ts

@@ -1210,6 +1210,24 @@ export class ZWaveController
 		};
 	}
 
+	/** Tries to determine the LR capable replacement of the given region. If none is found, the given region is returned. */
+	private tryGetLRCapableRegion(region: RFRegion): RFRegion {
+		// There is no official API to query whether a given region is supported,
+		// but there are ways to figure out if LR regions are.
+
+		// US_LR is supported if the controller supports changing the node ID type to 16 bit
+		if (
+			region === RFRegion.USA
+			&& this.isSerialAPISetupCommandSupported(
+				SerialAPISetupCommand.SetNodeIDType,
+			)
+		) {
+			return RFRegion["USA (Long Range)"];
+		}
+
+		return region;
+	}
+
 	/**
 	 * @internal
 	 * Queries the region and powerlevel settings and configures them if necessary
@@ -1240,14 +1258,26 @@ export class ZWaveController
 			}
 		}
 
+		let desiredRFRegion: RFRegion | undefined;
+		// If the user has set a region in the options, use that
+		if (this.driver.options.rf?.region != undefined) {
+			desiredRFRegion = this.driver.options.rf.region;
+		}
+		// Unless auto-upgrade to LR regions is disabled, try to find a suitable replacement region
+		if (this.driver.options.rf?.upgradeToLRRegion !== false) {
+			desiredRFRegion ??= this.rfRegion;
+			if (desiredRFRegion != undefined) {
+				desiredRFRegion = this.tryGetLRCapableRegion(desiredRFRegion);
+			}
+		}
+
 		if (
 			this.isSerialAPISetupCommandSupported(
 				SerialAPISetupCommand.SetRFRegion,
 			)
-			&& this.driver.options.rf?.region != undefined
-			&& this.rfRegion != this.driver.options.rf.region
+			&& desiredRFRegion != undefined
+			&& this.rfRegion != desiredRFRegion
 		) {
-			const desiredRegion = this.driver.options.rf.region;
 			this.driver.controllerLog.print(
 				`Current RF region (${
 					getEnumMemberName(
@@ -1257,12 +1287,12 @@ export class ZWaveController
 				}) differs from desired region (${
 					getEnumMemberName(
 						RFRegion,
-						desiredRegion,
+						desiredRFRegion,
 					)
 				}), configuring it...`,
 			);
 			const resp = await this.setRFRegionInternal(
-				desiredRegion,
+				desiredRFRegion,
 				// Do not soft reset here, we'll do it later
 				false,
 			).catch((e) => (e as Error).message);
@@ -1271,7 +1301,7 @@ export class ZWaveController
 					`Changed RF region to ${
 						getEnumMemberName(
 							RFRegion,
-							desiredRegion,
+							desiredRFRegion,
 						)
 					}`,
 				);
@@ -6049,6 +6079,10 @@ ${associatedNodes.join(", ")}`,
 
 	/** Configure the RF region at the Z-Wave API Module */
 	public async setRFRegion(region: RFRegion): Promise<boolean> {
+		// Unless auto-upgrade to LR regions is disabled, try to find a suitable LR replacement region
+		if (this.driver.options.rf?.upgradeToLRRegion !== false) {
+			region = this.tryGetLRCapableRegion(region);
+		}
 		return this.setRFRegionInternal(region, true);
 	}
 

packages/zwave-js/src/lib/driver/ZWaveOptions.ts

@@ -269,6 +269,14 @@ export interface ZWaveOptions extends ZWaveHostOptions {
 		/** The RF region the radio should be tuned to. */
 		region?: RFRegion;
 
+		/**
+		 * Whether LR-capable regions should automatically be chosen over their corresponding non-LR regions, e.g. `USA` -> `USA (Long Range)`.
+		 * This also overrides the `rf.region` setting if the desired region is not LR-capable.
+		 *
+		 * Default: true.
+		 */
+		upgradeToLRRegion?: boolean;
+
 		txPower?: {
 			/** The desired TX power in dBm. */
 			powerlevel: number;

test/run.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
-import { LongRangeChannel, RFRegion } from "@zwave-js/core";
+import { RFRegion } from "@zwave-js/core";
 import { wait as _wait } from "alcalzone-shared/async";
 import path from "node:path";
 import "reflect-metadata";
@@ -57,8 +57,7 @@ const driver = new Driver(port, {
 		),
 	},
 	rf: {
-		region: RFRegion["USA (Long Range)"],
-		longRangeChannel: LongRangeChannel.A,
+		region: RFRegion.USA,
 	},
 	storage: {
 		cacheDir: path.join(__dirname, "cache"),