feat: add schema 47 state properties, events, and infrastructure (1/4)

Add schema version 47 with new state properties for driver, controller,
and node dumps. Add event forwarding for driver lifecycle events and
controller network events. Include shared helpers, dependency updates,
and documentation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: raman325

API_SCHEMA.md

@@ -114,3 +114,11 @@ Base schema.
 
 - Added `allowed` property to numeric value metadata and configuration metadata
 - Added `purpose` property to configuration metadata
+
+## Schema 47
+
+- Added driver state properties: `ready`, `allNodesReady`, `configVersion`
+- Added node state properties: `canSleep`, `supportsWakeUpOnDemand`, `hardwareVersion`, `hasSUCReturnRoute`, `manufacturer`, `dsk`
+- 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`

README.md

@@ -1651,6 +1651,55 @@ interface {
 }
 ```
 
+#### `all nodes ready`
+
+[compatible with schema version: 47+]
+
+This event is sent when all nodes have been interviewed and are ready.
+
+```ts
+interface {
+  type: "event";
+  event: {
+    source: "driver";
+    event: "all nodes ready";
+  }
+}
+```
+
+#### `error`
+
+[compatible with schema version: 47+]
+
+This event is sent when a driver error occurs.
+
+```ts
+interface {
+  type: "event";
+  event: {
+    source: "driver";
+    event: "error";
+    error: string;
+  }
+}
+```
+
+#### `bootloader ready`
+
+[compatible with schema version: 47+]
+
+This event is sent when the controller enters bootloader mode.
+
+```ts
+interface {
+  type: "event";
+  event: {
+    source: "driver";
+    event: "bootloader ready";
+  }
+}
+```
+
 #### `log config updated`
 
 This event is sent whenever a client issues the `driver.update_log_config` command with the updated log config.
@@ -1769,7 +1818,7 @@ interface {
 
 #### `nvm restore progress`
 
-This event is sent on progress updates to the NVM restoration process when the [`controller.restore_nvm`](https://zwave-js.github.io/node-zwave-js/#/api/controller?id=nvm-backup-and-restore) command is issued by a client to the server and the NVM data is being restored to the controller.
+This event is sent on progress updates to the NVM restoration process when the [`controller.restore_nvm`](https://zwave-js.github.io/node-zwave-js/#/api/controller?id=nvm-backup-and-restore) or `controller.restore_nvm_raw` command is issued by a client to the server and the NVM data is being restored to the controller.
 
 ```ts
 interface {
@@ -1783,6 +1832,88 @@ interface {
 }
 ```
 
+#### `network found`
+
+[compatible with schema version: 47+]
+
+This event is sent when a new network is found during the join process (learn mode).
+
+```ts
+interface {
+  type: "event";
+  event: {
+    source: "controller";
+    event: "network found";
+    homeId: number;
+    ownNodeId: number;
+  }
+}
+```
+
+#### `network joined`
+
+[compatible with schema version: 47+]
+
+This event is sent when the controller successfully joins a network.
+
+```ts
+interface {
+  type: "event";
+  event: {
+    source: "controller";
+    event: "network joined";
+  }
+}
+```
+
+#### `network left`
+
+[compatible with schema version: 47+]
+
+This event is sent when the controller leaves the current network.
+
+```ts
+interface {
+  type: "event";
+  event: {
+    source: "controller";
+    event: "network left";
+  }
+}
+```
+
+#### `joining network failed`
+
+[compatible with schema version: 47+]
+
+This event is sent when joining a network fails.
+
+```ts
+interface {
+  type: "event";
+  event: {
+    source: "controller";
+    event: "joining network failed";
+  }
+}
+```
+
+#### `leaving network failed`
+
+[compatible with schema version: 47+]
+
+This event is sent when leaving a network fails.
+
+```ts
+interface {
+  type: "event";
+  event: {
+    source: "controller";
+    event: "leaving network failed";
+  }
+}
+```
+
 ## Schema Version
 
 In an attempt to keep compatibility between different server and client versions, we've introduced a (basic) API Schema Version.

src/lib/broadcast_node/incoming_message.ts

@@ -6,44 +6,51 @@ import { BroadcastNodeCommand } from "./command.js";
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface IncomingCommandBroadcastNodeBase extends IncomingCommandBase {}
 
-export interface IncomingCommandBroadcastNodeSetValue extends IncomingCommandBroadcastNodeBase {
+export interface IncomingCommandBroadcastNodeSetValue
+  extends IncomingCommandBroadcastNodeBase {
   command: BroadcastNodeCommand.setValue;
   valueId: ValueID;
   value: unknown;
   options?: SetValueAPIOptions;
 }
 
-export interface IncomingCommandBroadcastNodeGetEndpointCount extends IncomingCommandBroadcastNodeBase {
+export interface IncomingCommandBroadcastNodeGetEndpointCount
+  extends IncomingCommandBroadcastNodeBase {
   command: BroadcastNodeCommand.getEndpointCount;
 }
 
-export interface IncomingCommandBroadcastNodeSupportsCC extends IncomingCommandBroadcastNodeBase {
+export interface IncomingCommandBroadcastNodeSupportsCC
+  extends IncomingCommandBroadcastNodeBase {
   command: BroadcastNodeCommand.supportsCC;
   index: number;
   commandClass: CommandClasses;
 }
 
-export interface IncomingCommandBroadcastNodeGetCCVersion extends IncomingCommandBroadcastNodeBase {
+export interface IncomingCommandBroadcastNodeGetCCVersion
+  extends IncomingCommandBroadcastNodeBase {
   command: BroadcastNodeCommand.getCCVersion;
   index: number;
   commandClass: CommandClasses;
 }
 
-export interface IncomingCommandBroadcastNodeInvokeCCAPI extends IncomingCommandBroadcastNodeBase {
+export interface IncomingCommandBroadcastNodeInvokeCCAPI
+  extends IncomingCommandBroadcastNodeBase {
   command: BroadcastNodeCommand.invokeCCAPI;
   index?: number;
   commandClass: CommandClasses;
   methodName: string;
   args: unknown[];
 }
 
-export interface IncomingCommandBroadcastNodeSupportsCCAPI extends IncomingCommandBroadcastNodeBase {
+export interface IncomingCommandBroadcastNodeSupportsCCAPI
+  extends IncomingCommandBroadcastNodeBase {
   command: BroadcastNodeCommand.supportsCCAPI;
   index?: number;
   commandClass: CommandClasses;
 }
 
-export interface IncomingCommandBroadcastNodeGetDefinedValueIDs extends IncomingCommandBroadcastNodeBase {
+export interface IncomingCommandBroadcastNodeGetDefinedValueIDs
+  extends IncomingCommandBroadcastNodeBase {
   command: BroadcastNodeCommand.getDefinedValueIDs;
 }
 

src/lib/common.ts

@@ -7,8 +7,17 @@ import {
   SetValueStatus,
   ZWaveNode,
 } from "zwave-js";
+import type { GetFirmwareUpdatesOptions } from "zwave-js/Controller";
+import type { Client } from "./server.js";
 import type { ConfigurationCCAPISetOptions } from "@zwave-js/cc";
-import { SupervisionResult, MaybeNotKnown } from "@zwave-js/core";
+import {
+  FirmwareFileFormat,
+  guessFirmwareFileFormat,
+  MaybeNotKnown,
+  RFRegion,
+  SupervisionResult,
+  tryUnzipFirmwareFile,
+} from "@zwave-js/core";
 import {
   IncomingCommandNodeGetRawConfigParameterValue,
   IncomingCommandNodeSetRawConfigParameterValue,
@@ -109,3 +118,58 @@ export async function getRawConfigParameterValue(
   );
   return { value };
 }
+
+export interface FirmwareFileInfo {
+  filename: string;
+  rawData: Uint8Array<ArrayBuffer>;
+  format: FirmwareFileFormat;
+}
+
+/**
+ * Tries to determine the firmware file format, with automatic ZIP extraction fallback.
+ * First attempts guessFirmwareFileFormat. If that fails, tries to extract from ZIP archive.
+ */
+export function parseFirmwareFile(
+  filename: string,
+  rawData: Uint8Array<ArrayBuffer>,
+  explicitFormat?: FirmwareFileFormat,
+): FirmwareFileInfo {
+  // If format is explicitly provided, use it directly
+  if (explicitFormat !== undefined) {
+    return { filename, rawData, format: explicitFormat };
+  }
+
+  try {
+    // First, try to guess the format directly
+    const format = guessFirmwareFileFormat(filename, rawData);
+    return { filename, rawData, format };
+  } catch (guessError) {
+    // If guessing failed, try to extract from ZIP
+    const unzipped = tryUnzipFirmwareFile(rawData);
+    if (unzipped) {
+      return {
+        filename: unzipped.filename,
+        rawData: unzipped.rawData,
+        format: unzipped.format,
+      };
+    }
+    // If unzip also failed, re-throw the original error
+    throw guessError;
+  }
+}
+
+export function getFirmwareUpdateOptions(
+  message: {
+    apiKey?: string;
+    includePrereleases?: boolean;
+    rfRegion?: RFRegion;
+  },
+  client: Client,
+): GetFirmwareUpdatesOptions {
+  return {
+    apiKey: message.apiKey,
+    additionalUserAgentComponents: client.additionalUserAgentComponents,
+    includePrereleases: message.includePrereleases,
+    rfRegion: message.rfRegion,
+  };
+}

src/lib/config_manager/incoming_message.ts

@@ -4,48 +4,59 @@ import { ConfigManagerCommand } from "./command.js";
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface IncomingCommandConfigManagerBase extends IncomingCommandBase {}
 
-export interface IncomingCommandConfigManagerLookupDevice extends IncomingCommandConfigManagerBase {
+export interface IncomingCommandConfigManagerLookupDevice
+  extends IncomingCommandConfigManagerBase {
   command: ConfigManagerCommand.lookupDevice;
   manufacturerId: number;
   productType: number;
   productId: number;
   firmwareVersion?: string;
 }
 
-export interface IncomingCommandConfigManagerLoadManufacturers extends IncomingCommandConfigManagerBase {
+export interface IncomingCommandConfigManagerLoadManufacturers
+  extends IncomingCommandConfigManagerBase {
   command: ConfigManagerCommand.loadManufacturers;
 }
 
-export interface IncomingCommandConfigManagerLookupManufacturer extends IncomingCommandConfigManagerBase {
+export interface IncomingCommandConfigManagerLookupManufacturer
+  extends IncomingCommandConfigManagerBase {
   command: ConfigManagerCommand.lookupManufacturer;
   manufacturerId: number;
 }
-export interface IncomingCommandConfigManagerLoadDeviceIndex extends IncomingCommandConfigManagerBase {
+export interface IncomingCommandConfigManagerLoadDeviceIndex
+  extends IncomingCommandConfigManagerBase {
   command: ConfigManagerCommand.loadDeviceIndex;
 }
-export interface IncomingCommandConfigManagerGetIndex extends IncomingCommandConfigManagerBase {
+export interface IncomingCommandConfigManagerGetIndex
+  extends IncomingCommandConfigManagerBase {
   command: ConfigManagerCommand.getIndex;
 }
-export interface IncomingCommandConfigManagerLoadFulltextDeviceIndex extends IncomingCommandConfigManagerBase {
+export interface IncomingCommandConfigManagerLoadFulltextDeviceIndex
+  extends IncomingCommandConfigManagerBase {
   command: ConfigManagerCommand.loadFulltextDeviceIndex;
 }
-export interface IncomingCommandConfigManagerGetFulltextIndex extends IncomingCommandConfigManagerBase {
+export interface IncomingCommandConfigManagerGetFulltextIndex
+  extends IncomingCommandConfigManagerBase {
   command: ConfigManagerCommand.getFulltextIndex;
 }
-export interface IncomingCommandConfigManagerLookupDevicePreserveConditions extends IncomingCommandConfigManagerBase {
+export interface IncomingCommandConfigManagerLookupDevicePreserveConditions
+  extends IncomingCommandConfigManagerBase {
   command: ConfigManagerCommand.lookupDevicePreserveConditions;
   manufacturerId: number;
   productType: number;
   productId: number;
   firmwareVersion?: string;
 }
-export interface IncomingCommandConfigManagerManufacturers extends IncomingCommandConfigManagerBase {
+export interface IncomingCommandConfigManagerManufacturers
+  extends IncomingCommandConfigManagerBase {
   command: ConfigManagerCommand.manufacturers;
 }
-export interface IncomingCommandConfigManagerLoadAll extends IncomingCommandConfigManagerBase {
+export interface IncomingCommandConfigManagerLoadAll
+  extends IncomingCommandConfigManagerBase {
   command: ConfigManagerCommand.loadAll;
 }
-export interface IncomingCommandConfigManagerConfigVersion extends IncomingCommandConfigManagerBase {
+export interface IncomingCommandConfigManagerConfigVersion
+  extends IncomingCommandConfigManagerBase {
   command: ConfigManagerCommand.configVersion;
 }
 export type IncomingMessageConfigManager =

src/lib/const.ts

@@ -6,7 +6,7 @@ export const version = require("../../package.json").version;
 export const minSchemaVersion = 0;
 
 // maximal/current schema version the server supports
-export const maxSchemaVersion = 46;
+export const maxSchemaVersion = 47;
 
 export const applicationName = "zwave-js-server";
 export const dnssdServiceType = applicationName;