feat(cc): implement Inclusion Controller CC (#4851)

docs/api/CCs/InclusionController.md

@@ -0,0 +1,27 @@
+# Inclusion Controller CC
+
+?> CommandClass ID: `0x74`
+
+## Inclusion Controller CC methods
+
+### `initiateStep`
+
+```ts
+async initiateStep(
+	nodeId: number,
+	step: InclusionControllerStep,
+): Promise<void>;
+```
+
+Instruct the target to initiate the given inclusion step for the given node.
+
+### `completeStep`
+
+```ts
+async completeStep(
+	step: InclusionControllerStep,
+	status: InclusionControllerStatus,
+): Promise<void>;
+```
+
+Indicate to the other node that the given inclusion step has been completed.

docs/api/CCs/_sidebar.md

@@ -46,6 +46,7 @@
         -   [Humidity Control Mode CC](api/CCs/HumidityControlMode.md)
         -   [Humidity Control Operating State CC](api/CCs/HumidityControlOperatingState.md)
         -   [Humidity Control Setpoint CC](api/CCs/HumidityControlSetpoint.md)
+        -   [Inclusion Controller CC](api/CCs/InclusionController.md)
         -   [Indicator CC](api/CCs/Indicator.md)
         -   [Irrigation CC](api/CCs/Irrigation.md)
         -   [Language CC](api/CCs/Language.md)

docs/api/CCs/index.md

@@ -31,6 +31,7 @@ The **Command Classes API** provides a high-to-mid level entrypoint which allows
 -   [Humidity Control Mode CC](api/CCs/HumidityControlMode.md) · `0x6d`
 -   [Humidity Control Operating State CC](api/CCs/HumidityControlOperatingState.md) · `0x6e`
 -   [Humidity Control Setpoint CC](api/CCs/HumidityControlSetpoint.md) · `0x64`
+-   [Inclusion Controller CC](api/CCs/InclusionController.md) · `0x74`
 -   [Indicator CC](api/CCs/Indicator.md) · `0x87`
 -   [Irrigation CC](api/CCs/Irrigation.md) · `0x6b`
 -   [Language CC](api/CCs/Language.md) · `0x89`

packages/cc/src/cc/InclusionControllerCC.ts

@@ -0,0 +1,177 @@
+import {
+	CommandClasses,
+	Maybe,
+	MessageOrCCLogEntry,
+	validatePayload,
+} from "@zwave-js/core";
+import type { ZWaveApplicationHost, ZWaveHost } from "@zwave-js/host";
+import { getEnumMemberName } from "@zwave-js/shared";
+import { CCAPI } from "../lib/API";
+import {
+	CommandClass,
+	gotDeserializationOptions,
+	type CCCommandOptions,
+	type CommandClassDeserializationOptions,
+} from "../lib/CommandClass";
+import {
+	API,
+	CCCommand,
+	commandClass,
+	implementedVersion,
+} from "../lib/CommandClassDecorators";
+import {
+	InclusionControllerCommand,
+	InclusionControllerStatus,
+	InclusionControllerStep,
+} from "../lib/_Types";
+
+@commandClass(CommandClasses["Inclusion Controller"])
+@implementedVersion(1)
+export class InclusionControllerCC extends CommandClass {
+	declare ccCommand: InclusionControllerCommand;
+}
+
+@API(CommandClasses["Inclusion Controller"])
+export class InclusionControllerCCAPI extends CCAPI {
+	public supportsCommand(cmd: InclusionControllerCommand): Maybe<boolean> {
+		switch (cmd) {
+			case InclusionControllerCommand.Initiate:
+			case InclusionControllerCommand.Complete:
+				return true; // This is mandatory
+		}
+		return super.supportsCommand(cmd);
+	}
+
+	/** Instruct the target to initiate the given inclusion step for the given node */
+	public async initiateStep(
+		nodeId: number,
+		step: InclusionControllerStep,
+	): Promise<void> {
+		this.assertSupportsCommand(
+			InclusionControllerCommand,
+			InclusionControllerCommand.Initiate,
+		);
+
+		const cc = new InclusionControllerCCInitiate(this.applHost, {
+			nodeId: this.endpoint.nodeId,
+			endpoint: this.endpoint.index,
+			includedNodeId: nodeId,
+			step,
+		});
+		await this.applHost.sendCommand(cc, this.commandOptions);
+	}
+
+	/** Indicate to the other node that the given inclusion step has been completed */
+	public async completeStep(
+		step: InclusionControllerStep,
+		status: InclusionControllerStatus,
+	): Promise<void> {
+		this.assertSupportsCommand(
+			InclusionControllerCommand,
+			InclusionControllerCommand.Complete,
+		);
+
+		const cc = new InclusionControllerCCComplete(this.applHost, {
+			nodeId: this.endpoint.nodeId,
+			endpoint: this.endpoint.index,
+			step,
+			status,
+		});
+		await this.applHost.sendCommand(cc, this.commandOptions);
+	}
+}
+
+interface InclusionControllerCCCompleteOptions extends CCCommandOptions {
+	step: InclusionControllerStep;
+	status: InclusionControllerStatus;
+}
+
+@CCCommand(InclusionControllerCommand.Complete)
+export class InclusionControllerCCComplete extends InclusionControllerCC {
+	public constructor(
+		host: ZWaveHost,
+		options:
+			| CommandClassDeserializationOptions
+			| InclusionControllerCCCompleteOptions,
+	) {
+		super(host, options);
+		if (gotDeserializationOptions(options)) {
+			validatePayload(this.payload.length >= 2);
+			this.step = this.payload[0];
+			validatePayload.withReason("Invalid inclusion controller step")(
+				this.step in InclusionControllerStep,
+			);
+			this.status = this.payload[1];
+		} else {
+			this.step = options.step;
+			this.status = options.status;
+		}
+	}
+
+	public step: InclusionControllerStep;
+	public status: InclusionControllerStatus;
+
+	public serialize(): Buffer {
+		this.payload = Buffer.from([this.step, this.status]);
+		return super.serialize();
+	}
+
+	public toLogEntry(applHost: ZWaveApplicationHost): MessageOrCCLogEntry {
+		return {
+			...super.toLogEntry(applHost),
+			message: {
+				step: getEnumMemberName(InclusionControllerStep, this.step),
+				status: getEnumMemberName(
+					InclusionControllerStatus,
+					this.status,
+				),
+			},
+		};
+	}
+}
+
+interface InclusionControllerCCInitiateOptions extends CCCommandOptions {
+	includedNodeId: number;
+	step: InclusionControllerStep;
+}
+
+@CCCommand(InclusionControllerCommand.Initiate)
+export class InclusionControllerCCInitiate extends InclusionControllerCC {
+	public constructor(
+		host: ZWaveHost,
+		options:
+			| CommandClassDeserializationOptions
+			| InclusionControllerCCInitiateOptions,
+	) {
+		super(host, options);
+		if (gotDeserializationOptions(options)) {
+			validatePayload(this.payload.length >= 2);
+			this.includedNodeId = this.payload[0];
+			this.step = this.payload[1];
+			validatePayload.withReason("Invalid inclusion controller step")(
+				this.step in InclusionControllerStep,
+			);
+		} else {
+			this.includedNodeId = options.includedNodeId;
+			this.step = options.step;
+		}
+	}
+
+	public includedNodeId: number;
+	public step: InclusionControllerStep;
+
+	public serialize(): Buffer {
+		this.payload = Buffer.from([this.includedNodeId, this.step]);
+		return super.serialize();
+	}
+
+	public toLogEntry(applHost: ZWaveApplicationHost): MessageOrCCLogEntry {
+		return {
+			...super.toLogEntry(applHost),
+			message: {
+				"included node id": this.includedNodeId,
+				step: getEnumMemberName(InclusionControllerStep, this.step),
+			},
+		};
+	}
+}

packages/cc/src/cc/index.ts

@@ -203,6 +203,11 @@ export {
 	HumidityControlSetpointCCSupportedReport,
 	HumidityControlSetpointCCValues,
 } from "./HumidityControlSetpointCC";
+export {
+	InclusionControllerCC,
+	InclusionControllerCCComplete,
+	InclusionControllerCCInitiate,
+} from "./InclusionControllerCC";
 export {
 	IndicatorCC,
 	IndicatorCCGet,

packages/cc/src/lib/API.ts

@@ -543,6 +543,7 @@ type CCNameMap = {
 	"Humidity Control Mode": typeof CommandClasses["Humidity Control Mode"];
 	"Humidity Control Operating State": typeof CommandClasses["Humidity Control Operating State"];
 	"Humidity Control Setpoint": typeof CommandClasses["Humidity Control Setpoint"];
+	"Inclusion Controller": typeof CommandClasses["Inclusion Controller"];
 	Indicator: typeof CommandClasses["Indicator"];
 	Irrigation: typeof CommandClasses["Irrigation"];
 	Language: typeof CommandClasses["Language"];
@@ -646,6 +647,7 @@ export interface CCAPIs {
 	"Humidity Control Mode": import("../cc/HumidityControlModeCC").HumidityControlModeCCAPI;
 	"Humidity Control Operating State": import("../cc/HumidityControlOperatingStateCC").HumidityControlOperatingStateCCAPI;
 	"Humidity Control Setpoint": import("../cc/HumidityControlSetpointCC").HumidityControlSetpointCCAPI;
+	"Inclusion Controller": import("../cc/InclusionControllerCC").InclusionControllerCCAPI;
 	Indicator: import("../cc/IndicatorCC").IndicatorCCAPI;
 	Irrigation: import("../cc/IrrigationCC").IrrigationCCAPI;
 	Language: import("../cc/LanguageCC").LanguageCCAPI;