feat: rework compat flags for Basic CC mapping (#6773)

.github/workflows/zwave-js-bot_comment.yml

@@ -477,7 +477,7 @@ jobs:
   # Adds a compat flag to an existing file when an authorized person posts
   # @zwave-js-bot add compat flag to <deviceId>
   # ```
-  # enableBasicSetMapping: true
+  # mapBasicSet: "auto"
   # ```
   add-compat-flag:
     if: |

.vscode/deviceSnippets.code-snippets

@@ -135,7 +135,7 @@
 		"body": [
 			"\"compat\": {",
 			"\t$LINE_COMMENT This device incorrectly ${1:[problem]}",
-			"\t\"${2|disableBasicMapping,disableStrictEntryControlDataValidation,disableStrictMeasurementValidation,enableBasicSetMapping,forceNotificationIdleReset,mapRootReportsToEndpoint,preserveRootApplicationCCValueIDs,skipConfigurationNameQuery,skipConfigurationInfoQuery,treatBasicSetAsEvent,treatMultilevelSwitchSetAsEvent,treatSetAsReport,treatDestinationEndpointAsSource|}\": true",
+			"\t\"${2|disableStrictEntryControlDataValidation,disableStrictMeasurementValidation,forceNotificationIdleReset,mapRootReportsToEndpoint,preserveRootApplicationCCValueIDs,skipConfigurationNameQuery,skipConfigurationInfoQuery,treatMultilevelSwitchSetAsEvent,treatSetAsReport,treatDestinationEndpointAsSource|}\": true",
 			"},"
 		],
 		"description": "Insert parameter condition"

docs/config-files/file-format.md

@@ -360,10 +360,6 @@ If a device reports support for a CCs but does not correctly support it, this ca
 
 Several command classes are refreshed regularly (every couple of hours) if they do not report all of their values automatically. It has been found that some devices respond with invalid reports when queried. By setting `disableAutoRefresh` to `true`, this feature can be disabled.
 
-### `disableBasicMapping`
-
-By default, received `Basic CC::Report` commands are mapped to a more appropriate CC. Setting `disableBasicMapping` to `true` disables this feature.
-
 ### `disableCallbackFunctionTypeCheck`
 
 By default, responses or callbacks for Serial API commands must have the same function type (command identifier) in order to be recognized. However, in some situations, certain controllers send a callback with an invalid function type. In this case, the faulty commands may be listed in the `disableCallbackFunctionTypeCheck` array to disable the check for a matching function type.
@@ -380,12 +376,6 @@ Without the additional integrity checks that encapsulation CCs like `CRC-16`, `S
 
 Some devices incorrectly encode this support information though, making the checks discard otherwise correct data. To disable the checks, set `disableStrictMeasurementValidation` to `true`.
 
-### `enableBasicSetMapping`
-
-`Basic CC::Set` commands are not meant to be mapped to other CCs. Some devices still use them to report status. By setting `enableBasicSetMapping` to `true`, `Basic CC::Set` commands are mapped just like `Basic CC::Report`s.
-
-> [!NOTE] The option `disableBasicMapping` has precedence. If that is `true`, no `Basic` commands will be mapped.
-
 ### `forceNotificationIdleReset`
 
 Version 8 of the `Notification CC` added the requirement that devices must issue an idle notification after a notification variable is no longer active. Several legacy devices and some misbehaving V8 devices do not return their variables to idle automatically. By setting `forceNotificationIdleReset` to `true`, `zwave-js` auto-idles supporting notification variables after 5 minutes.
@@ -398,6 +388,23 @@ The specifications mandate that each `Scene Controller Configuration CC` Group I
 
 Some legacy devices emit an NIF when a local event occurs (e.g. a button press) to signal that the controller should request a status update. However, some of these devices require a delay before they are ready to respond to this request. `manualValueRefreshDelayMs` specifies that delay, expressed in milliseconds. If unset, there will be no delay.
 
+### `mapBasicReport`
+
+`Basic CC::Report` commands are like their name implies, Basic. They contain no information about **what** they are reporting. By default, Z-Wave JS uses the device type to map these commands to a more appropriate CC. The `mapBasicReport` can influence this behavior. It has the following options:
+
+- `false`: treat the report verbatim without mapping
+- `"auto"` **(default)**: Depending on the device type (Binary Switch, Multilevel Switch, or Binary Sensor), the command is mapped to the corresponding report for that device type. If no matching mapping is found, the command is treated verbatim without mapping.
+- `"Binary Sensor"`: Regardless of the device type, the command is treated like a `Binary Sensor CC::Report`.
+
+### `mapBasicSet`
+
+`Basic CC::Set` commands are meant to control other devices, yet some devices use them to "report" their status or expose secondary functionality. The `mapBasicSet` flag defines how Z-Wave JS should handle these commands:
+
+- `"report"` **(default)**: The command is treated like a `Basic CC::Report`, but the **target value** is used as the **current value**.
+- `"auto"`: Depending on the device type (Binary Switch, Multilevel Switch, or Binary Sensor), the command is mapped to the corresponding report for that device type. If no matching mapping is found, the command is treated like a `Basic CC::Report`, but the **target value** is used as the **current value**.
+- `"event"`: Emit a `value event` for the Basic `"event"` property.
+- `"Binary Sensor"`: Regardless of the device type, the command is treated like a `Binary Sensor CC::Report`.
+
 ### `mapRootReportsToEndpoint`
 
 Some multi-channel devices incorrectly report state changes for one of their endpoints via the root device, however there is no way to automatically detect for which endpoint these reports are meant. The flag `mapRootReportsToEndpoint` can be used to specify which endpoint these reports are mapped to. Without this flag, reports to the root device are silently ignored, unless `preserveRootApplicationCCValueIDs` is `true`.
@@ -492,13 +499,6 @@ Some devices spam the network with lots of `ConfigurationCC::NameReport`s in res
 
 Some devices spam the network with lots of (sometimes invalid) `ConfigurationCC::InfoReport`s in response to the `InfoGet` command. Set this flag to `true` to skip this query for affected devices.
 
-### `treatBasicSetAsEvent`
-
-By default, `Basic CC::Set` commands are interpreted as status updates. This flag causes the driver to emit a `value event` for the `"event"` property instead. Note that this property is exclusively used in this case in order to avoid conflicts with regular value IDs.
-
-> [!NOTE]
-> If this option is `true`, it has precedence over `disableBasicMapping`.
-
 ### `treatMultilevelSwitchSetAsEvent`
 
 By default, `Multilevel Switch CC::Set` commands are ignored, because they are meant to control end devices. This flag causes the driver to emit a `value event` for the `"event"` property instead, so applications can react to these commands, e.g. for remotes.

docs/config-files/style-guide.md

@@ -17,7 +17,7 @@ Our device files are parsed as JSON5 and may contain comments. Comments may (and
 	// ...
 	"compat": {
 		// The device is a Binary Sensor, but uses Basic Sets to report its status
-		"enableBasicSetMapping": true
+		"mapBasicSet": "auto"
 	}
 }
 ```

maintenance/schemas/device-config.json

@@ -565,9 +565,6 @@
 				"disableAutoRefresh": {
 					"const": true
 				},
-				"disableBasicMapping": {
-					"const": true
-				},
 				"disableCallbackFunctionTypeCheck": {
 					"type": "array",
 					"items": {
@@ -582,9 +579,6 @@
 				"disableStrictMeasurementValidation": {
 					"const": true
 				},
-				"enableBasicSetMapping": {
-					"const": true
-				},
 				"forceNotificationIdleReset": {
 					"const": true
 				},
@@ -597,6 +591,21 @@
 					"type": "number",
 					"minimum": 0
 				},
+				"mapBasicReport": {
+					"oneOf": [
+						{
+							"const": false
+						},
+						{
+							"type": "string",
+							"enum": ["auto", "Binary Sensor"]
+						}
+					]
+				},
+				"mapBasicSet": {
+					"type": "string",
+					"enum": ["event", "report", "auto", "Binary Sensor"]
+				},
 				"mapRootReportsToEndpoint": {
 					"type": "number",
 					"minimum": 1
@@ -696,9 +705,6 @@
 				"skipConfigurationInfoQuery": {
 					"const": true
 				},
-				"treatBasicSetAsEvent": {
-					"const": true
-				},
 				"treatMultilevelSwitchSetAsEvent": {
 					"const": true
 				},

packages/cc/src/cc/BasicCC.ts

@@ -328,8 +328,8 @@ remaining duration: ${basicResponse.duration?.toString() ?? "undefined"}`;
 		}
 
 		if (
-			!!applHost.getDeviceConfig?.(endpoint.nodeId)?.compat
-				?.treatBasicSetAsEvent
+			applHost.getDeviceConfig?.(endpoint.nodeId)?.compat?.mapBasicSet
+				=== "event"
 		) {
 			// Add the compat event value if it should be exposed
 			ret.push(BasicCCValues.compatEvent.endpoint(endpoint.index));

packages/config/config/devices/0x0005/pe653.json

@@ -523,7 +523,7 @@
 			},
 			// The device sometimes sends BASIC_SET to the lifeline association when the state of Switch 1
 			// changes but the value is always 0 so treat it as an event.
-			"treatBasicSetAsEvent": true
+			"mapBasicSet": "event"
 		},
 		{
 			"commandClasses": {

packages/config/config/devices/0x001a/rf9501.json

@@ -110,6 +110,6 @@
 		}
 	],
 	"compat": {
-		"enableBasicSetMapping": true
+		"mapBasicSet": "auto"
 	}
 }

packages/config/config/devices/0x001a/rf9540-n_0.0_1.1.json

@@ -172,6 +172,6 @@
 		}
 	],
 	"compat": {
-		"enableBasicSetMapping": true
+		"mapBasicSet": "auto"
 	}
 }

packages/config/config/devices/0x001a/rf9540-n_1.2.json

@@ -180,6 +180,6 @@
 		}
 	],
 	"compat": {
-		"enableBasicSetMapping": true
+		"mapBasicSet": "auto"
 	}
 }

packages/config/config/devices/0x001a/rf9542.json

@@ -122,6 +122,6 @@
 		}
 	],
 	"compat": {
-		"enableBasicSetMapping": true
+		"mapBasicSet": "auto"
 	}
 }

packages/config/config/devices/0x001a/rfwc5.json

@@ -89,6 +89,6 @@
 	],
 	"compat": {
 		// Basic CC is required to react to Scene Off commands
-		"disableBasicMapping": true
+		"mapBasicReport": false
 	}
 }

packages/config/config/devices/0x0039/39336_39443_zw3104.json

@@ -145,7 +145,7 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	},
 	"metadata": {
 		"inclusion": "1. Follow the instructions for your Z-Wave certified controller to add\nthe smart dimmer to the Z-Wave network.\n2. Once the controller is ready to add your smart dimmer, single\npress and release the manual/program button on the smart\ndimmer to add it in the network.\nPlease reference the controller/gateway’s manual for instructions",

packages/config/config/devices/0x0039/39339_39346_zw3107.json

@@ -131,7 +131,7 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	},
 	"metadata": {
 		"inclusion": "1. Follow the instructions for your Z-Wave certified controller to add\nthe smart dimmer to the Z-Wave network.\n2. Once the controller is ready to add your smart dimmer, single\npress and release the manual/program button on the smart\ndimmer to add it in the network.\nPlease reference the controller/gateway’s manual for instructions",

packages/config/config/devices/0x0039/39342_39449_zw4106.json

@@ -55,7 +55,7 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	},
 	"metadata": {
 		"inclusion": "Adding your device to a Z-Wave network:\n1. Follow the instructions for your Z-Wave certified controller to\ninclude the device to the Z-Wave network.\n2. Once the controller is ready to include your smart switch,\nsingle press and release the manual/program button on the\nsmart switch to include it in the network.\nNow you have complete control to turn your lamp ON/OFF\naccording to groups, scenes, schedules and interactive\nautomations programmed by your controller.\nIf your Z-Wave certified controller features Remote Access,\nyou can now control your lighting from your mobile devices",

packages/config/config/devices/0x0039/39348_39455_zw4005.json

@@ -89,8 +89,8 @@
 		}
 	],
 	"compat": {
-		"disableBasicMapping": true,
-		"treatBasicSetAsEvent": true
+		"mapBasicReport": false,
+		"mapBasicSet": "event"
 	},
 	"metadata": {
 		"inclusion": "1. Follow the instructions for your Z-Wave certified controller to include a device to the Z-Wave network.\n2. Once the controller is ready to include your device, press and release the top or bottom of the wireless smart switch(rocker) to include it in the network.\n3. Once your controller has confirmed that the device has been included, refresh the Z-Wave network to optimize performance",

packages/config/config/devices/0x0039/39348_39455_zw4008.json

@@ -77,7 +77,7 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	},
 	"metadata": {
 		"inclusion": "1. Follow the instructions for your Z-Wave certified controller to add a device to the Z-Wave network.\n2. Once the controller is ready to add your device, press and release the top or bottom of the wireless smart switch (rocker) to add it in the network.\n\nIf prompted by the controller to enter the S2 security code, refer to the QR code/security number on the back of the box, or the QR code label on the product",

packages/config/config/devices/0x0039/39351_39458_zw3005.json

@@ -131,7 +131,7 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	},
 	"metadata": {
 		"inclusion": "1. Follow the instructions for your Z-Wave certified controller to\ninclude a device to the Z-Wave network.\n2. Once the controller is ready to add your device,\npress and release the top or bottom of the wireless smart\nswitch (rocker) to add it in the network.\nPlease reference the controller’s manual for instructions",

packages/config/config/devices/0x0039/39351_39458_zw3010.json

@@ -143,7 +143,7 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	},
 	"metadata": {
 		"inclusion": "1. Follow the instructions for your Z-Wave certified controller to add a device to the Z-Wave network.\n2. Once the controller is ready to add your device, press and release the top or bottom of the wireless smart dimmer (rocker) to add it in the network.\nIf prompted by the controller to enter the S2 security code, refer to the QR code/security number on the back of the box, or the QR code label on the product",

packages/config/config/devices/0x0039/39354_39461_zw4003.json

@@ -86,7 +86,7 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	},
 	"metadata": {
 		"inclusion": "1. Follow the instructions for your Z-Wave certified controller to add a device to the Z-Wave network.\n2. Once the controller is ready to add your device, press up on the toggle.\n\nA. If prompted by the controller to enter the S2 security code, refer to the QR code/security number on the back of the box, or the QR code label on the product.\n\nNow you have complete control to turn your fixture ON/OFF according to groups, scenes, schedules and interactive automations programmed by your controller. If your Z-Wave certified controller features remote access, you can control your fixture from your mobile devices",

packages/config/config/devices/0x0039/39354_39461_zw4009.json

@@ -86,7 +86,7 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	},
 	"metadata": {
 		"inclusion": "1. Follow the instructions for your Z-Wave certified controller to add a device to the Z-Wave network.\n2. Once the controller is ready to add your device, press up on the toggle.\n\nA. If prompted by the controller to enter the S2 security code, refer to the QR code/security number on the back of the box, or the QR code label on the product.\n\nNow you have complete control to turn your fixture ON/OFF according to groups, scenes, schedules and interactive automations programmed by your controller. If your Z-Wave certified controller features remote access, you can control your fixture from your mobile devices",

packages/config/config/devices/0x0039/39357_39464_zw3004.json

@@ -134,7 +134,7 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	},
 	"metadata": {
 		"inclusion": "1. Follow the instructions for your Z-Wave certified controller to\ninclude a device to the Z-Wave network.\n2. Once the controller is ready to include your device, press\nand release the top or bottom of the wireless smart dimmer\n(rocker) to include it in the network",

packages/config/config/devices/0x0039/39357_39464_zw3011.json

@@ -126,7 +126,7 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	},
 	"metadata": {
 		"inclusion": "1. Follow the instructions for your Z-Wave certified controller to add a device to the Z-Wave network.\n2. Once the controller is ready to add your device, press up and release the toggle.\nIf prompted by the controller to enter the S2 security code, refer to the QR code/security number on the back of the box, or the QR code label on the product",

packages/config/config/devices/0x0039/39358_39465_zw4002.json

@@ -50,7 +50,7 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true,
+		"mapBasicSet": "event",
 		"commandClasses": {
 			"remove": {
 				"Supervision": {

packages/config/config/devices/0x0039/39363_39470_zw4203.json

@@ -72,7 +72,7 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	},
 	"metadata": {
 		"inclusion": "1. Follow the instructions for your Z-Wave certified controller to add a device to the Z-Wave network. \n\n2. Once the controller is ready to add your device, press and the manual/program button on the smart switch.\n\nIf prompted by the controller to enter the S2 security code, refer to the QR code/security number on the box or the QR code label on the product. Enter the 5-digit code",

packages/config/config/devices/0x0060/hac01.json

@@ -44,7 +44,7 @@
 		}
 	],
 	"compat": {
-		"enableBasicSetMapping": true,
+		"mapBasicSet": "auto",
 		// The device supports Binary Switch CC, despite the Version query telling otherwise
 		"commandClasses": {
 			"add": {

packages/config/config/devices/0x0060/hsp02.json

@@ -104,6 +104,6 @@
 	],
 	"compat": {
 		// The device is a Binary Sensor, but uses Basic Sets to report its status
-		"enableBasicSetMapping": true
+		"mapBasicSet": "auto"
 	}
 }

packages/config/config/devices/0x0060/sm103.json

@@ -48,6 +48,6 @@
 	],
 	"compat": {
 		// The device is a Binary Sensor, but uses Basic Sets to report its status
-		"enableBasicSetMapping": true
+		"mapBasicSet": "auto"
 	}
 }

packages/config/config/devices/0x0063/12729_zw3004.json

@@ -61,6 +61,6 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	}
 }

packages/config/config/devices/0x0063/12730_zw4002.json

@@ -40,7 +40,7 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true,
+		"mapBasicSet": "event",
 		"commandClasses": {
 			"remove": {
 				"Supervision": {

packages/config/config/devices/0x0063/14287_zw4002.json

@@ -42,7 +42,7 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true,
+		"mapBasicSet": "event",
 		"commandClasses": {
 			"remove": {
 				"Supervision": {

packages/config/config/devices/0x0063/14291_zw4005.json

@@ -45,6 +45,6 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	}
 }

packages/config/config/devices/0x0063/14292_zw4003.json

@@ -40,6 +40,6 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	}
 }

packages/config/config/devices/0x0063/14294_zw3005.json

@@ -65,6 +65,6 @@
 		}
 	],
 	"compat": {
-		"treatBasicSetAsEvent": true
+		"mapBasicSet": "event"
 	}
 }