From ba71df50f262449b5244e50538c565f6451a4bd8 Mon Sep 17 00:00:00 2001
From: AlCalzone <dominic.griesel@nabucasa.com>
Date: Mon, 24 Jun 2024 11:44:23 +0200
Subject: [PATCH] feat: add method to query supported RF regions (#6957)

---
 docs/api/controller.md                        |  8 +++++
 .../zwave-js/src/lib/controller/Controller.ts | 35 +++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/docs/api/controller.md b/docs/api/controller.md
index 6175ffd6a163..6c56b46956a6 100644
--- a/docs/api/controller.md
+++ b/docs/api/controller.md
@@ -828,6 +828,14 @@ export enum RFRegion {
 
 > [!ATTENTION] Not all controllers support configuring the RF region. These methods will throw if they are not supported
 
+To determine which regions are supported by the current controller, use the following method:
+
+```ts
+getSupportedRFRegions(filterSubsets: boolean): MaybeNotKnown<readonly RFRegion[]>
+```
+
+The `filterSubsets` parameter (`true` by default) can be used to filter out regions that are subsets of other supported regions. For example, if the controller supports both `USA` and `USA (Long Range)`, only `USA (Long Range)` will be returned, since it includes the `USA` region.
+
 #### Configure TX powerlevel
 
 ```ts
diff --git a/packages/zwave-js/src/lib/controller/Controller.ts b/packages/zwave-js/src/lib/controller/Controller.ts
index 342fa80652b2..3e0d87e7ed76 100644
--- a/packages/zwave-js/src/lib/controller/Controller.ts
+++ b/packages/zwave-js/src/lib/controller/Controller.ts
@@ -6235,6 +6235,41 @@ ${associatedNodes.join(", ")}`,
 		return result.region;
 	}
 
+	/**
+	 * Returns the RF regions supported by this controller, or `undefined` if the information is not known yet.
+	 *
+	 * @param filterSubsets Whether to exclude regions that are subsets of other regions,
+	 * for example `USA` which is a subset of `USA (Long Range)`
+	 */
+	public getSupportedRFRegions(
+		filterSubsets: boolean = true,
+	): MaybeNotKnown<readonly RFRegion[]> {
+		// FIXME: Once supported in firmware, query the controller for supported regions instead of hardcoding
+		const ret = new Set([
+			// Always supported
+			RFRegion.Europe,
+			RFRegion.USA,
+			RFRegion["Australia/New Zealand"],
+			RFRegion["Hong Kong"],
+			RFRegion.India,
+			RFRegion.Israel,
+			RFRegion.Russia,
+			RFRegion.China,
+			RFRegion.Japan,
+			RFRegion.Korea,
+			RFRegion["Default (EU)"],
+		]);
+
+		if (this.isLongRangeCapable()) {
+			ret.add(RFRegion["USA (Long Range)"]);
+			if (filterSubsets) {
+				ret.delete(RFRegion.USA);
+			}
+		}
+
+		return [...ret].sort((a, b) => a - b);
+	}
+
 	/** Configure the Powerlevel setting of the Z-Wave API */
 	public async setPowerlevel(
 		powerlevel: number,