feat: add schema 47 driver commands (2/4) (#1510)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: AlCalzone <dominic.griesel@nabucasa.com>

Author: 3 people

API_SCHEMA.md

@@ -343,3 +343,5 @@ Base schema.
 - Added controller state properties: `isSIS`, `maxPayloadSize`, `maxPayloadSizeLR`, `zwaveApiVersion`, `zwaveChipType`
 - Added driver events: `all nodes ready`, `error`, `bootloader ready`
 - Added controller events: `network found`, `network joined`, `network left`, `joining network failed`, `leaving network failed`
+- Added driver commands: `soft_reset_and_restart`, `enter_bootloader`, `leave_bootloader`, `get_supported_cc_version`, `get_safe_cc_version`, `update_user_agent`, `enable_frequent_rssi_monitoring`, `disable_frequent_rssi_monitoring`
+- Automatic ZIP extraction for firmware update commands

README.md

@@ -443,6 +443,8 @@ interface {
 }
 ```
 
+The server will automatically attempt to extract firmware from a ZIP archive.
+
 If `fileFormat` is not provided in Option 1, the format will be guessed based on the filename and file payload.
 
 Returns:
@@ -472,6 +474,102 @@ interface {
 }
 ```
 
+#### [Soft Reset and Restart](https://zwave-js.github.io/node-zwave-js/#/api/driver?id=softresetandrestart)
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "driver.soft_reset_and_restart";
+}
+```
+
+#### [Enter Bootloader](https://zwave-js.github.io/node-zwave-js/#/api/driver?id=enterbootloader)
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "driver.enter_bootloader";
+}
+```
+
+#### [Leave Bootloader](https://zwave-js.github.io/node-zwave-js/#/api/driver?id=leavebootloader)
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "driver.leave_bootloader";
+}
+```
+
+#### [Get Supported CC Version](https://zwave-js.github.io/node-zwave-js/#/api/driver?id=getsupportedccversion)
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "driver.get_supported_cc_version";
+  cc: CommandClasses;
+  nodeId: number;
+  endpointIndex?: number;
+}
+```
+
+#### [Get Safe CC Version](https://zwave-js.github.io/node-zwave-js/#/api/driver?id=getsafeccversion)
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "driver.get_safe_cc_version";
+  cc: CommandClasses;
+  nodeId: number;
+  endpointIndex?: number;
+}
+```
+
+#### [Update User Agent](https://zwave-js.github.io/node-zwave-js/#/api/driver?id=updateuseragent)
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "driver.update_user_agent";
+  components: Record<string, string | null | undefined>;
+}
+```
+
+#### [Enable Frequent RSSI Monitoring](https://zwave-js.github.io/node-zwave-js/#/api/driver?id=enablefrequentrssimonitoring)
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "driver.enable_frequent_rssi_monitoring";
+  durationMs: number;
+}
+```
+
+#### [Disable Frequent RSSI Monitoring](https://zwave-js.github.io/node-zwave-js/#/api/driver?id=disablefrequentrssimonitoring)
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "driver.disable_frequent_rssi_monitoring";
+}
+```
+
 ### Controller level commands
 
 `zwave-js-server` supports all of the controller methods listed in the [Z-Wave JS documentation](https://zwave-js.github.io/node-zwave-js/#/api/controller?id=controller-methods). `zwave-js-server` uses [snake casing](https://en.wikipedia.org/wiki/Snake_case) for commands and prefixes every controller command with `controller.`, so `beginInclusion` is called using the `controller.begin_inclusion` command.

src/lib/common.ts

@@ -8,7 +8,15 @@ import {
   ZWaveNode,
 } from "zwave-js";
 import type { ConfigurationCCAPISetOptions } from "@zwave-js/cc";
-import { SupervisionResult, MaybeNotKnown } from "@zwave-js/core";
+import {
+  extractFirmware,
+  Firmware,
+  FirmwareFileFormat,
+  guessFirmwareFileFormat,
+  MaybeNotKnown,
+  SupervisionResult,
+  tryUnzipFirmwareFile,
+} from "@zwave-js/core";
 import {
   IncomingCommandNodeGetRawConfigParameterValue,
   IncomingCommandNodeSetRawConfigParameterValue,
@@ -109,3 +117,41 @@ export async function getRawConfigParameterValue(
   );
   return { value };
 }
+
+// Precedence:
+// 1. Always try ZIP extraction first — firmware files may be zipped
+//    regardless of filename extension or explicit format.
+// 2. If an explicit format is provided, use it (on the unzipped data if
+//    applicable, otherwise on the raw data as-is).
+// 3. Fall back to guessing the format from the filename and raw data.
+function parseFirmwareFile(
+  filename: string,
+  rawData: Uint8Array<ArrayBuffer>,
+  explicitFormat?: FirmwareFileFormat,
+): { rawData: Uint8Array<ArrayBuffer>; format: FirmwareFileFormat } {
+  const unzipped = tryUnzipFirmwareFile(rawData);
+  if (unzipped) {
+    return explicitFormat !== undefined
+      ? { rawData: unzipped.rawData, format: explicitFormat }
+      : unzipped;
+  }
+
+  if (explicitFormat !== undefined) {
+    return { rawData, format: explicitFormat };
+  }
+
+  return { rawData, format: guessFirmwareFileFormat(filename, rawData) };
+}
+
+/**
+ * Parses a firmware file (handling format detection and ZIP extraction)
+ * and extracts the firmware data.
+ */
+export async function parseAndExtractFirmware(
+  filename: string,
+  rawData: Uint8Array<ArrayBuffer>,
+  explicitFormat?: FirmwareFileFormat,
+): Promise<Firmware> {
+  const parsed = parseFirmwareFile(filename, rawData, explicitFormat);
+  return extractFirmware(parsed.rawData, parsed.format);
+}

src/lib/driver/command.ts

@@ -21,4 +21,15 @@ export enum DriverCommand {
   firmwareUpdateOTW = "driver.firmware_update_otw",
   // Schema version >= 41:
   isOTWFirmwareUpdateInProgress = "driver.is_otw_firmware_update_in_progress",
+  softResetAndRestart = "driver.soft_reset_and_restart",
+  enterBootloader = "driver.enter_bootloader",
+  leaveBootloader = "driver.leave_bootloader",
+  // CC version queries
+  getSupportedCCVersion = "driver.get_supported_cc_version",
+  getSafeCCVersion = "driver.get_safe_cc_version",
+  // User agent
+  updateUserAgent = "driver.update_user_agent",
+  // RSSI monitoring
+  enableFrequentRSSIMonitoring = "driver.enable_frequent_rssi_monitoring",
+  disableFrequentRSSIMonitoring = "driver.disable_frequent_rssi_monitoring",
 }

src/lib/driver/incoming_message.ts

@@ -1,4 +1,4 @@
-import { FirmwareFileFormat, LogConfig } from "@zwave-js/core";
+import { CommandClasses, FirmwareFileFormat, LogConfig } from "@zwave-js/core";
 import { DriverCommand } from "./command.js";
 import { IncomingCommandBase } from "../incoming_message_base.js";
 import {
@@ -109,6 +109,49 @@ export interface IncomingCommandIsOTWFirmwareUpdateInProgress extends IncomingCo
   command: DriverCommand.isOTWFirmwareUpdateInProgress;
 }
 
+interface IncomingCommandSoftResetAndRestart extends IncomingCommandBase {
+  command: DriverCommand.softResetAndRestart;
+}
+
+interface IncomingCommandEnterBootloader extends IncomingCommandBase {
+  command: DriverCommand.enterBootloader;
+}
+
+interface IncomingCommandLeaveBootloader extends IncomingCommandBase {
+  command: DriverCommand.leaveBootloader;
+}
+
+// CC version queries
+interface IncomingCommandGetSupportedCCVersion extends IncomingCommandBase {
+  command: DriverCommand.getSupportedCCVersion;
+  cc: CommandClasses;
+  nodeId: number;
+  endpointIndex?: number;
+}
+
+interface IncomingCommandGetSafeCCVersion extends IncomingCommandBase {
+  command: DriverCommand.getSafeCCVersion;
+  cc: CommandClasses;
+  nodeId: number;
+  endpointIndex?: number;
+}
+
+// User agent
+interface IncomingCommandUpdateUserAgent extends IncomingCommandBase {
+  command: DriverCommand.updateUserAgent;
+  components: Record<string, string | null | undefined>;
+}
+
+// RSSI monitoring
+interface IncomingCommandEnableFrequentRSSIMonitoring extends IncomingCommandBase {
+  command: DriverCommand.enableFrequentRSSIMonitoring;
+  durationMs: number;
+}
+
+interface IncomingCommandDisableFrequentRSSIMonitoring extends IncomingCommandBase {
+  command: DriverCommand.disableFrequentRSSIMonitoring;
+}
+
 export type IncomingMessageDriver =
   | IncomingCommandGetConfig
   | IncomingCommandUpdateLogConfig
@@ -129,4 +172,12 @@ export type IncomingMessageDriver =
   | IncomingCommandUpdateOptions
   | IncomingCommandSendTestFrame
   | IncomingCommandFirmwareUpdateOTW
-  | IncomingCommandIsOTWFirmwareUpdateInProgress;
+  | IncomingCommandIsOTWFirmwareUpdateInProgress
+  | IncomingCommandSoftResetAndRestart
+  | IncomingCommandEnterBootloader
+  | IncomingCommandLeaveBootloader
+  | IncomingCommandGetSupportedCCVersion
+  | IncomingCommandGetSafeCCVersion
+  | IncomingCommandUpdateUserAgent
+  | IncomingCommandEnableFrequentRSSIMonitoring
+  | IncomingCommandDisableFrequentRSSIMonitoring;

src/lib/driver/message_handler.ts

@@ -1,10 +1,6 @@
-import {
-  Driver,
-  extractFirmware,
-  guessFirmwareFileFormat,
-  OTWFirmwareUpdateResult,
-} from "zwave-js";
+import { Driver, OTWFirmwareUpdateResult } from "zwave-js";
 import { UnknownCommandError } from "../error.js";
+import { parseAndExtractFirmware } from "../common.js";
 import {
   Client,
   ClientsController,
@@ -136,10 +132,10 @@ export class DriverMessageHandler implements MessageHandler {
           result = await this.driver.firmwareUpdateOTW(message.updateInfo);
         } else {
           const file = Buffer.from(message.file, "base64");
-          const { data } = await extractFirmware(
+          const { data } = await parseAndExtractFirmware(
+            message.filename,
             file,
-            message.fileFormat ??
-              guessFirmwareFileFormat(message.filename, file),
+            message.fileFormat,
           );
           result = await this.driver.firmwareUpdateOTW(data);
         }
@@ -149,6 +145,49 @@ export class DriverMessageHandler implements MessageHandler {
         const progress = this.driver.isOTWFirmwareUpdateInProgress();
         return { progress };
       }
+      case DriverCommand.softResetAndRestart: {
+        await this.driver.softResetAndRestart();
+        return {};
+      }
+      case DriverCommand.enterBootloader: {
+        await this.driver.enterBootloader();
+        return {};
+      }
+      case DriverCommand.leaveBootloader: {
+        await this.driver.leaveBootloader();
+        return {};
+      }
+      // CC version queries
+      case DriverCommand.getSupportedCCVersion: {
+        const version = this.driver.getSupportedCCVersion(
+          message.cc,
+          message.nodeId,
+          message.endpointIndex,
+        );
+        return { version };
+      }
+      case DriverCommand.getSafeCCVersion: {
+        const version = this.driver.getSafeCCVersion(
+          message.cc,
+          message.nodeId,
+          message.endpointIndex,
+        );
+        return { version };
+      }
+      // User agent
+      case DriverCommand.updateUserAgent: {
+        this.driver.updateUserAgent(message.components);
+        return {};
+      }
+      // RSSI monitoring
+      case DriverCommand.enableFrequentRSSIMonitoring: {
+        this.driver.enableFrequentRSSIMonitoring(message.durationMs);
+        return {};
+      }
+      case DriverCommand.disableFrequentRSSIMonitoring: {
+        this.driver.disableFrequentRSSIMonitoring();
+        return {};
+      }
       default: {
         throw new UnknownCommandError(command);
       }

src/lib/driver/outgoing_message.ts

@@ -28,4 +28,15 @@ export interface DriverResultTypes {
   [DriverCommand.sendTestFrame]: { status?: TransmitStatus };
   [DriverCommand.firmwareUpdateOTW]: OTWFirmwareUpdateResultType;
   [DriverCommand.isOTWFirmwareUpdateInProgress]: { progress: boolean };
+  [DriverCommand.softResetAndRestart]: Record<string, never>;
+  [DriverCommand.enterBootloader]: Record<string, never>;
+  [DriverCommand.leaveBootloader]: Record<string, never>;
+  // CC version queries
+  [DriverCommand.getSupportedCCVersion]: { version: number };
+  [DriverCommand.getSafeCCVersion]: { version?: number };
+  // User agent
+  [DriverCommand.updateUserAgent]: Record<string, never>;
+  // RSSI monitoring
+  [DriverCommand.enableFrequentRSSIMonitoring]: Record<string, never>;
+  [DriverCommand.disableFrequentRSSIMonitoring]: Record<string, never>;
 }