feat: allow passing custom serial port implementation in port param of Driver class

packages/serial/api.md

@@ -385,6 +385,11 @@ export function isNodeQuery<T extends Message>(msg: T): msg is T & INodeQuery;
 // @public (undocumented)
 export function isSuccessIndicator<T extends Message>(msg: T): msg is T & SuccessIndicator;
 
+// Warning: (ae-missing-release-tag) "isZWaveSerialPortImplementation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public (undocumented)
+export function isZWaveSerialPortImplementation(obj: unknown): obj is ZWaveSerialPortImplementation;
+
 // Warning: (ae-missing-release-tag) "Message" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public

packages/serial/src/ZWaveSerialPortBase.ts

@@ -1,5 +1,6 @@
 import type { ZWaveLogContainer } from "@zwave-js/core";
 import { Mixin } from "@zwave-js/shared";
+import { isObject } from "alcalzone-shared/typeguards";
 import { EventEmitter } from "events";
 import { Duplex, PassThrough, Readable, Writable } from "stream";
 import { SerialLogger } from "./Logger";
@@ -51,6 +52,17 @@ export interface ZWaveSerialPortBase {
 	): boolean;
 }
 
+export function isZWaveSerialPortImplementation(
+	obj: unknown,
+): obj is ZWaveSerialPortImplementation {
+	return (
+		isObject(obj) &&
+		typeof obj.create === "function" &&
+		typeof obj.open === "function" &&
+		typeof obj.close === "function"
+	);
+}
+
 export interface ZWaveSerialPortImplementation {
 	create(): Duplex & EventEmitter;
 	open(

packages/zwave-js/api.md

@@ -147,6 +147,7 @@ import type { ZWaveNotificationCallbackParams_NotificationCC } from '@zwave-js/c
 import type { ZWaveNotificationCallbackParams_PowerlevelCC } from '@zwave-js/cc';
 import { ZWavePlusNodeType } from '@zwave-js/cc';
 import { ZWavePlusRoleType } from '@zwave-js/cc';
+import { ZWaveSerialPortImplementation } from '@zwave-js/serial';
 
 export { buffer2hex }
 
@@ -224,7 +225,7 @@ export class DeviceClass {
 export class Driver extends TypedEventEmitter<DriverEventCallbacks> implements ZWaveApplicationHost {
     // (undocumented)
     [util.inspect.custom](): string;
-    constructor(port: string, options?: DeepPartial<ZWaveOptions>);
+    constructor(port: string | ZWaveSerialPortImplementation, options?: DeepPartial<ZWaveOptions>);
     get allNodesReady(): boolean;
     // (undocumented)
     readonly cacheDir: string;

packages/zwave-js/src/lib/driver/Driver.ts

@@ -82,11 +82,13 @@ import {
 	INodeQuery,
 	isNodeQuery,
 	isSuccessIndicator,
+	isZWaveSerialPortImplementation,
 	Message,
 	MessageHeaders,
 	MessageType,
 	ZWaveSerialPort,
 	ZWaveSerialPortBase,
+	ZWaveSerialPortImplementation,
 	ZWaveSocket,
 } from "@zwave-js/serial";
 import {
@@ -407,11 +409,22 @@ export class Driver
 	implements ZWaveApplicationHost
 {
 	public constructor(
-		private port: string,
+		private port: string | ZWaveSerialPortImplementation,
 		options?: DeepPartial<ZWaveOptions>,
 	) {
 		super();
 
+		// Ensure the given serial port is valid
+		if (
+			typeof port !== "string" &&
+			!isZWaveSerialPortImplementation(port)
+		) {
+			throw new ZWaveError(
+				`The port must be a string or a valid custom serial port implementation!`,
+				ZWaveErrorCodes.Driver_InvalidOptions,
+			);
+		}
+
 		// merge given options with defaults
 		this.options = mergeDeep(options, defaultOptions) as ZWaveOptions;
 		// And make sure they contain valid values
@@ -808,22 +821,32 @@ export class Driver
 		this.sendThread.start();
 
 		// Open the serial port
-		if (this.port.startsWith("tcp://")) {
-			const url = new URL(this.port);
-			this.driverLog.print(`opening serial port ${this.port}`);
-			this.serial = new ZWaveSocket(
-				{
-					host: url.hostname,
-					port: parseInt(url.port),
-				},
-				this._logContainer,
-			);
+		if (typeof this.port === "string") {
+			if (this.port.startsWith("tcp://")) {
+				const url = new URL(this.port);
+				this.driverLog.print(`opening serial port ${this.port}`);
+				this.serial = new ZWaveSocket(
+					{
+						host: url.hostname,
+						port: parseInt(url.port),
+					},
+					this._logContainer,
+				);
+			} else {
+				this.driverLog.print(`opening serial port ${this.port}`);
+				this.serial = new ZWaveSerialPort(
+					this.port,
+					this._logContainer,
+					this.options.testingHooks?.serialPortBinding,
+				);
+			}
 		} else {
-			this.driverLog.print(`opening serial port ${this.port}`);
-			this.serial = new ZWaveSerialPort(
+			this.driverLog.print(
+				"opening serial port using the provided custom implementation",
+			);
+			this.serial = new ZWaveSerialPortBase(
 				this.port,
 				this._logContainer,
-				this.options.testingHooks?.serialPortBinding,
 			);
 		}
 		this.serial