feat: implement automatic powerlevel setting for US/EU regions (#4269)

AlCalzone · robertsLando · web-flow · commit ef54a21d2b62 · 2025-07-01T11:25:24.000+02:00
Co-authored-by: Daniel Lando &lt;daniel.sorridi@gmail.com&gt;
diff --git a/api/lib/ZwaveClient.ts b/api/lib/ZwaveClient.ts
@@ -627,10 +627,10 @@ export type ZwaveConfig = {
 	disableControllerRecovery?: boolean
 	rf?: {
 		region?: RFRegion
-		maxLongRangePowerlevel?: number
+		maxLongRangePowerlevel?: number | 'auto'
 		txPower?: {
-			powerlevel: number
-			measured0dBm: number
+			powerlevel: number | 'auto'
+			measured0dBm?: number
 		}
 	}
 }
@@ -2211,16 +2211,25 @@ class ZwaveClient extends TypedEventEmitter<ZwaveClientEventCallbacks> {
 				zwaveOptions.rf.region = region
 			}
 
-			if (typeof maxLongRangePowerlevel === 'number') {
+			if (
+				maxLongRangePowerlevel === 'auto' ||
+				typeof maxLongRangePowerlevel === 'number'
+			) {
 				zwaveOptions.rf.maxLongRangePowerlevel = maxLongRangePowerlevel
 			}
 
-			if (
-				txPower &&
-				typeof txPower.measured0dBm === 'number' &&
-				typeof txPower.powerlevel === 'number'
-			) {
-				zwaveOptions.rf.txPower = txPower
+			if (txPower) {
+				if (
+					txPower.powerlevel === 'auto' ||
+					typeof txPower.powerlevel === 'number'
+				) {
+					zwaveOptions.rf.txPower ??= {}
+					zwaveOptions.rf.txPower.powerlevel = txPower.powerlevel
+				}
+				if (typeof txPower.measured0dBm === 'number') {
+					zwaveOptions.rf.txPower ??= {}
+					zwaveOptions.rf.txPower.measured0dBm = txPower.measured0dBm
+				}
 			}
 		}
 
@@ -3173,7 +3182,21 @@ class ZwaveClient extends TypedEventEmitter<ZwaveClientEventCallbacks> {
 	async setRFRegion(region: RFRegion): Promise<boolean> {
 		if (this.driverReady) {
 			const result = await this._driver.controller.setRFRegion(region)
-			await this.updateControllerNodeProps(null, ['RFRegion'])
+
+			// Determine which properties need updating
+			const propsToUpdate: Array<
+				'powerlevel' | 'RFRegion' | 'maxLongRangePowerlevel'
+			> = ['RFRegion']
+
+			// If powerlevels are in auto mode, refresh them after region change
+			if (this.cfg.rf?.txPower?.powerlevel === 'auto') {
+				propsToUpdate.push('powerlevel')
+			}
+			if (this.cfg.rf?.maxLongRangePowerlevel === 'auto') {
+				propsToUpdate.push('maxLongRangePowerlevel')
+			}
+
+			await this.updateControllerNodeProps(null, propsToUpdate)
 			return result
 		}
 
diff --git a/src/components/nodes-table/NodeDetails.vue b/src/components/nodes-table/NodeDetails.vue
@@ -40,7 +40,7 @@
 					<v-select
 						label="RF Region"
 						:items="node.rfRegions"
-						v-model="node.RFRegion"
+						v-model="selectedRFRegion"
 						:disabled="node.RFRegion === undefined"
 						:hint="
 							node.RFRegion === undefined
@@ -80,6 +80,13 @@
 						:step="0.1"
 						suffix="dBm"
 						type="number"
+						:disabled="isAutoPowerLevelEnabled"
+						:hint="
+							isAutoPowerLevelEnabled
+								? 'Automatic mode enabled in settings'
+								: ''
+						"
+						persistent-hint
 					></v-text-field>
 				</v-col>
 				<v-col cols="12" sm="6" style="max-width: 300px">
@@ -120,8 +127,18 @@
 						label="Maximum LR Power Level"
 						:items="maxLRPowerLevels"
 						v-model="node.maxLongRangePowerlevel"
+						:disabled="isAutoLRPowerLevelEnabled"
+						:hint="
+							isAutoLRPowerLevelEnabled
+								? 'Automatic mode enabled in settings'
+								: ''
+						"
+						persistent-hint
 					>
-						<template v-slot:append-outer>
+						<template
+							v-if="!isAutoLRPowerLevelEnabled"
+							v-slot:append-outer
+						>
 							<v-btn
 								color="primary"
 								small
@@ -146,7 +163,7 @@
 					</v-select>
 				</v-col>
 			</v-row>
-			<v-col style="max-width: 700px" dense>
+			<v-col v-if="showPowerWarnings" style="max-width: 700px" dense>
 				<v-alert text type="warning">
 					<strong
 						>DO NOT CHANGE THESE VALUES UNLESS YOU KNOW WHAT YOU ARE
@@ -391,7 +408,11 @@ import { validTopic } from '../../lib/utils'
 import { maxLRPowerLevels } from '../../lib/items'
 import useBaseStore from '../../stores/base.js'
 import InstancesMixin from '../../mixins/InstancesMixin.js'
-import { isUnsupervisedOrSucceeded, ConfigValueFormat } from '@zwave-js/core'
+import {
+	isUnsupervisedOrSucceeded,
+	ConfigValueFormat,
+	RFRegion,
+} from '@zwave-js/core'
 
 export default {
 	props: {
@@ -410,6 +431,7 @@ export default {
 			maxLRPowerLevels,
 			newName: this.node.name,
 			newLoc: this.node.loc,
+			selectedRFRegion: this.node.RFRegion,
 			configCCValueFormats: [
 				{
 					text: 'Signed',
@@ -429,7 +451,33 @@ export default {
 		}
 	},
 	computed: {
-		...mapState(useBaseStore, ['mqtt']),
+		...mapState(useBaseStore, ['mqtt', 'zwave']),
+		regionSupportsAutoPowerlevel() {
+			return [
+				RFRegion.Europe,
+				RFRegion['Europe (Long Range)'],
+				RFRegion.USA,
+				RFRegion['USA (Long Range)'],
+			].includes(this.node?.RFRegion)
+		},
+		isAutoPowerLevelEnabled() {
+			return (
+				this.zwave.rf?.txPower?.powerlevel === 'auto' &&
+				this.regionSupportsAutoPowerlevel
+			)
+		},
+		isAutoLRPowerLevelEnabled() {
+			return (
+				this.zwave.rf?.maxLongRangePowerlevel === 'auto' &&
+				this.regionSupportsAutoPowerlevel
+			)
+		},
+		showPowerWarnings() {
+			// Hide warnings when auto mode is enabled for supported regions
+			return (
+				!this.isAutoPowerLevelEnabled && !this.isAutoLRPowerLevelEnabled
+			)
+		},
 		commandGroups() {
 			if (this.node) {
 				const groups = {}
@@ -652,7 +700,7 @@ export default {
 		},
 		async updateRFRegion() {
 			if (this.node) {
-				const args = [this.node.RFRegion]
+				const args = [this.selectedRFRegion]
 				const response = await this.app.apiRequest('setRFRegion', args)
 
 				if (response.success) {
diff --git a/src/views/Settings.vue b/src/views/Settings.vue
@@ -812,18 +812,31 @@
 											</v-select>
 										</v-col>
 										<v-col cols="6">
-											<v-select
-												label="Maximum LR Power Level"
+											<v-switch
+												hint="When enabled, both normal and LR power levels will be automatically set to legal limits based on the RF region whenever the region is changed. Only supported for Europe and USA regions."
 												persistent-hint
-												hint="The maximum power level to be used by the dynamic power algorithm of Z-Wave LR. Will be applied on every startup if the current setting of your Z-Wave controller differs. Only LR-capable controllers support this setting."
-												:items="maxLRPowerLevels"
-												clearable
-												v-model="
+												label="Automatic Power Level"
+												:input-value="
+													newZwave.rf.txPower
+														.powerlevel ===
+														'auto' &&
 													newZwave.rf
-														.maxLongRangePowerlevel
+														.maxLongRangePowerlevel ===
+														'auto'
+												"
+												@change="
+													(function (enabled) {
+														newZwave.rf.txPower.powerlevel =
+															enabled
+																? 'auto'
+																: undefined
+														newZwave.rf.maxLongRangePowerlevel =
+															enabled
+																? 'auto'
+																: undefined
+													})($event)
 												"
-											>
-											</v-select>
+											></v-switch>
 										</v-col>
 									</v-row>
 									<v-row class="mt-0">
@@ -838,9 +851,18 @@
 												:min="-10"
 												:max="20"
 												:step="0.1"
-												hint="Power level in dBm. Min -10, Max +14 or +20, depending on the Z-Wave chip. Will be applied on every startup if the current setting of your Z-Wave controller differs. Not all controllers support changing the powerlevel."
+												:hint="
+													newZwave.rf.txPower
+														.powerlevel === 'auto'
+														? 'Automatic mode enabled'
+														: 'Power level in dBm. Min -10, Max +14 or +20, depending on the Z-Wave chip. Will be applied on every startup if the current setting of your Z-Wave controller differs. Not all controllers support changing the powerlevel.'
+												"
 												suffix="dBm"
 												type="number"
+												:disabled="
+													newZwave.rf.txPower
+														.powerlevel === 'auto'
+												"
 												:rules="[validTxPower]"
 											></v-text-field>
 										</v-col>
@@ -862,6 +884,33 @@
 											></v-text-field>
 										</v-col>
 									</v-row>
+									<v-row class="mt-0">
+										<v-col cols="6">
+											<v-select
+												label="Maximum LR Power Level"
+												persistent-hint
+												:hint="
+													newZwave.rf
+														.maxLongRangePowerlevel ===
+													'auto'
+														? 'Automatic mode enabled'
+														: 'The maximum power level to be used by the dynamic power algorithm of Z-Wave LR. Will be applied on every startup if the current setting of your Z-Wave controller differs. Only LR-capable controllers support this setting.'
+												"
+												:items="maxLRPowerLevels"
+												clearable
+												:disabled="
+													newZwave.rf
+														.maxLongRangePowerlevel ===
+													'auto'
+												"
+												v-model="
+													newZwave.rf
+														.maxLongRangePowerlevel
+												"
+											>
+											</v-select>
+										</v-col>
+									</v-row>
 									<!-- END: RADIO CONFIGURATION -->
 
 									<!-- DRIVER LOGS -->
@@ -2385,22 +2434,25 @@ export default {
 		validTxPower() {
 			const { powerlevel, measured0dBm } = this.newZwave.rf?.txPower ?? {}
 
-			const validPower = !isUndef(powerlevel)
-			const validMeasured = !isUndef(measured0dBm)
-
-			if (validPower && (powerlevel < -10 || powerlevel > 20)) {
-				return 'Power level must be between -10 and 20'
+			// The calibration value is optional
+			if (
+				typeof measured0dBm === 'number' &&
+				(measured0dBm < -10 || measured0dBm > 10)
+			) {
+				return 'Measured @ 0dBm must be between -10 and 10'
 			}
 
-			if (validMeasured && (measured0dBm < -10 || measured0dBm > 10)) {
-				return 'Measured 0dBm must be between -10 and 10'
+			if (isUndef(powerlevel) || powerlevel === 'auto') {
+				return
 			}
 
-			return (
-				(validPower && validMeasured) ||
-				(!validPower && !validMeasured) ||
-				'Both powerlevel and measured 0 dBm must be set when using custom TX power'
-			)
+			if (
+				typeof powerlevel !== 'number' ||
+				powerlevel < -10 ||
+				powerlevel > 20
+			) {
+				return 'Powerlevel must be between -10 and 20'
+			}
 		},
 		parseCron(cron) {
 			let res
