feat: implement discoverable and transparently-typed CC value definit…

…ions (#4704)
zwave-js · Jul 19, 2022 · 040dff8 · 040dff8
1 parent bc03601
commit 040dff8
Show file tree

Hide file tree

Showing 125 changed files with 9,489 additions and 5,073 deletions.
diff --git a/.vscode/typescript.code-snippets b/.vscode/typescript.code-snippets
@@ -430,16 +430,20 @@
 		"prefix": "zwcc",
 		"body": [
 			"import {",
-			"\tCCCommand,",
 			"\tCommandClass,",
-			"\tcommandClass,",
-			"\texpectedCCResponse,",
-			"\timplementedVersion,",
 			"\tgotDeserializationOptions,",
 			"\ttype CCCommandOptions,",
 			"\ttype CommandClassDeserializationOptions,",
 			"} from \"../lib/CommandClass\";",
 			"import {",
+			"\tCCCommand,",
+			"\tccValue,",
+			"\tccValues,",
+			"\tcommandClass,",
+			"\texpectedCCResponse,",
+			"\timplementedVersion,",
+			"} from \"../lib/CommandClassDecorators\";",
+			"import {",
 			"\tCommandClasses,",
 			"\tMessageOrCCLogEntry,",
 			"\tMessagePriority,",
@@ -457,6 +461,7 @@
 			"",
 			"@commandClass(CommandClasses.${1})",
 			"@implementedVersion(${2:1})",
+			"@ccValues(${1}CCValues)",
 			"export class ${1}CC extends CommandClass {",
 			"\tdeclare ccCommand: ${1}Command;",
 			"}",
@@ -465,6 +470,91 @@
 		],
 		"description": "Z-Wave Command Class implementation"
 	},
+	"Z-Wave CC Values": {
+		"scope": "typescript",
+		"prefix": "zwccvalues",
+		"body": [
+			"export const ${1:${TM_FILENAME_BASE/(.*)CC$/$1/}}CCValues = Object.freeze({",
+			"\t...V${0}.defineStaticCCValues(CommandClasses.${2:${TM_FILENAME_BASE/(.*)CC$/$1/}}, {",
+			"\t\t// Static CC values go here",
+			"\t}),",
+			"",
+			"\t...V.defineDynamicCCValues(CommandClasses.${2}, {",
+			"\t\t// Dynamic CC values go here",
+			"\t}),",
+			"});",
+			""
+		],
+		"description": "Z-Wave Command Class values definition"
+	},
+	"Z-Wave CC Value (static, property only)": {
+		"scope": "typescript",
+		"prefix": "zwccvaluestatic",
+		"body": [
+			"...V.staticProperty(",
+			"\t\"${1:property}\",",
+			"\t${2:// undefined, // meta}",
+			"\t${3:// { internal: true \\}, // value options}",
+			"),"
+		],
+		"description": "Static CC value"
+	},
+	"Z-Wave CC Value (static, named property)": {
+		"scope": "typescript",
+		"prefix": "zwccvaluestaticname",
+		"body": [
+			"...V.staticPropertyWithName(",
+			"\t\"${1:valueName}\",",
+			"\t\"${2:property}\",",
+			"\t${3:// undefined, // meta}",
+			"\t${4:// { internal: true \\}, // value options}",
+			"),"
+		],
+		"description": "Static CC value with name"
+	},
+	"Z-Wave CC Value (static, named, property & key)": {
+		"scope": "typescript",
+		"prefix": "zwccvaluestaticpropkey",
+		"body": [
+			"...V.staticPropertyAndKeyWithName(",
+			"\t\"${1:valueName}\",",
+			"\t\"${2:property}\",",
+			"\t\"${3:propertyKey}\",",
+			"\t${4:// undefined, // meta}",
+			"\t${5:// { internal: true \\}, // value options}",
+			"),"
+		],
+		"description": "Static CC value with name, property and propertyKey"
+	},
+	"Z-Wave CC Value (dynamic, named property)": {
+		"scope": "typescript",
+		"prefix": "zwccvaluedynamicname",
+		"body": [
+			"...V.dynamicPropertyWithName(",
+			"\t\"${1:valueName}\",",
+			"\t(${2:arg1}: ${3:number}) => ${0:${2}},",
+			"\t({ property }) => typeof property === \"${3}\",",
+			"\t// (${2}: ${3}) => ({ ...ValueMetadata.Any }), // meta, can also be a static value",
+			"\t// (${2}: ${3}) => ({ internal: true }), // value options, can also be a static value",
+			"),"
+		],
+		"description": "Dynamic CC value with name"
+	},
+	"Z-Wave CC Value (dynamic, named, property & key)": {
+		"scope": "typescript",
+		"prefix": "zwccvaluedynamicpropkey",
+		"body": [
+			"...V.dynamicPropertyAndKeyWithName(",
+			"\t\"${1:valueName}\",",
+			"\t\"${1}\",",
+			"\t(${2:arg1}: ${3:number}) => ${0:${2}},",
+			"\t({ property, propertyKey }) => property === \"${1}\",",
+			"\t// (${2}: ${3}) => ({ ...ValueMetadata.Any }), // meta, can also be a static value",
+			"\t// (${2}: ${3}) => ({ internal: true }), // value options, can also be a static value",
+			"),"
+		],
+		"description": "Dynamic CC value with name, property and propertyKey"
+	},
 	"Z-Wave CC Command": {
 		"scope": "typescript",
 		"prefix": "zwcccmd",

diff --git a/docs/api/CCs/AlarmSensor.md b/docs/api/CCs/AlarmSensor.md
@@ -21,3 +21,66 @@ Retrieves the current value from this sensor.
 ```ts
 async getSupportedSensorTypes(): Promise<readonly AlarmSensorType[] | undefined>;
 ```
+
+## Alarm Sensor CC values
+
+### `duration(sensorType: AlarmSensorType)`
+
+```ts
+{
+	commandClass: CommandClasses["Alarm Sensor"],
+	endpoint: number,
+	property: "duration",
+	propertyKey: AlarmSensorType,
+}
+```
+
+-   **label:** `${string} duration`
+-   **description:** For how long the alarm should be active
+-   **min. CC version:** 1
+-   **readable:** true
+-   **writeable:** false
+-   **stateful:** true
+-   **secret:** false
+-   **value type:** `"number"`
+
+### `severity(sensorType: AlarmSensorType)`
+
+```ts
+{
+	commandClass: CommandClasses["Alarm Sensor"],
+	endpoint: number,
+	property: "severity",
+	propertyKey: AlarmSensorType,
+}
+```
+
+-   **label:** `${string} severity`
+-   **min. CC version:** 1
+-   **readable:** true
+-   **writeable:** false
+-   **stateful:** true
+-   **secret:** false
+-   **value type:** `"number"`
+-   **min. value:** 1
+-   **max. value:** 100
+
+### `state(sensorType: AlarmSensorType)`
+
+```ts
+{
+	commandClass: CommandClasses["Alarm Sensor"],
+	endpoint: number,
+	property: "state",
+	propertyKey: AlarmSensorType,
+}
+```
+
+-   **label:** `${string} state`
+-   **description:** Whether the alarm is active
+-   **min. CC version:** 1
+-   **readable:** true
+-   **writeable:** false
+-   **stateful:** true
+-   **secret:** false
+-   **value type:** `"boolean"`
diff --git a/docs/api/CCs/BarrierOperator.md b/docs/api/CCs/BarrierOperator.md
@@ -42,3 +42,86 @@ async setEventSignaling(
 	subsystemState: SubsystemState,
 ): Promise<void>;
 ```
+
+## Barrier Operator CC values
+
+### `currentState`
+
+```ts
+{
+	commandClass: CommandClasses["Barrier Operator"],
+	endpoint: number,
+	property: "currentState",
+}
+```
+
+-   **label:** Current Barrier State
+-   **min. CC version:** 1
+-   **readable:** true
+-   **writeable:** false
+-   **stateful:** true
+-   **secret:** false
+-   **value type:** `"number"`
+-   **min. value:** 0
+-   **max. value:** 255
+
+### `position`
+
+```ts
+{
+	commandClass: CommandClasses["Barrier Operator"],
+	endpoint: number,
+	property: "position",
+}
+```
+
+-   **label:** Barrier Position
+-   **min. CC version:** 1
+-   **readable:** true
+-   **writeable:** false
+-   **stateful:** true
+-   **secret:** false
+-   **value type:** `"number"`
+-   **min. value:** 0
+-   **max. value:** 100
+
+### `signalingState(subsystemType: SubsystemType)`
+
+```ts
+{
+	commandClass: CommandClasses["Barrier Operator"],
+	endpoint: number,
+	property: "signalingState",
+	propertyKey: SubsystemType,
+}
+```
+
+-   **label:** `Signaling State (${string})`
+-   **min. CC version:** 1
+-   **readable:** true
+-   **writeable:** true
+-   **stateful:** true
+-   **secret:** false
+-   **value type:** `"number"`
+-   **min. value:** 0
+-   **max. value:** 255
+
+### `targetState`
+
+```ts
+{
+	commandClass: CommandClasses["Barrier Operator"],
+	endpoint: number,
+	property: "targetState",
+}
+```
+
+-   **label:** Target Barrier State
+-   **min. CC version:** 1
+-   **readable:** true
+-   **writeable:** true
+-   **stateful:** true
+-   **secret:** false
+-   **value type:** `"number"`
+-   **min. value:** 0
+-   **max. value:** 255
diff --git a/docs/api/CCs/Basic.md b/docs/api/CCs/Basic.md
@@ -15,3 +15,83 @@ async get(): Promise<Pick<BasicCCReport, "currentValue" | "targetValue" | "durat
 ```ts
 async set(targetValue: number): Promise<void>;
 ```
+
+## Basic CC values
+
+### `compatEvent`
+
+```ts
+{
+	commandClass: CommandClasses.Basic,
+	endpoint: number,
+	property: "event",
+}
+```
+
+-   **label:** Event value
+-   **min. CC version:** 1
+-   **readable:** true
+-   **writeable:** false
+-   **stateful:** false
+-   **secret:** false
+-   **value type:** `"number"`
+-   **min. value:** 0
+-   **max. value:** 255
+
+### `currentValue`
+
+```ts
+{
+	commandClass: CommandClasses.Basic,
+	endpoint: number,
+	property: "currentValue",
+}
+```
+
+-   **label:** Current value
+-   **min. CC version:** 1
+-   **readable:** true
+-   **writeable:** false
+-   **stateful:** true
+-   **secret:** false
+-   **value type:** `"number"`
+-   **min. value:** 0
+-   **max. value:** 99
+
+### `duration`
+
+```ts
+{
+	commandClass: CommandClasses.Basic,
+	endpoint: number,
+	property: "duration",
+}
+```
+
+-   **label:** Remaining duration
+-   **min. CC version:** 1
+-   **readable:** true
+-   **writeable:** false
+-   **stateful:** true
+-   **secret:** false
+-   **value type:** `"duration"`
+
+### `targetValue`
+
+```ts
+{
+	commandClass: CommandClasses.Basic,
+	endpoint: number,
+	property: "targetValue",
+}
+```
+
+-   **label:** Target value
+-   **min. CC version:** 1
+-   **readable:** true
+-   **writeable:** true
+-   **stateful:** true
+-   **secret:** false
+-   **value type:** `"number"`
+-   **min. value:** 0
+-   **max. value:** 255