feat: add schema 47 zniffer, utility, and broadcast commands (4/4)

Add zniffer Long Range and file I/O commands, utility firmware
commands, and broadcast node Long Range support.

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

Author: raman325

API_SCHEMA.md

@@ -352,3 +352,7 @@ Base schema.
 - Added node event: `check link reliability progress`
 - Added controller events: `joining network show dsk`, `joining network done`
 - Added endpoint commands: `get_ccs`, `may_support_basic_cc`, `was_cc_removed_via_config`
+- Added broadcast node Long Range support via `longRange` flag on `broadcast_node` commands
+- Added zniffer Long Range commands: `get_lr_regions`, `get_current_lr_channel_config`, `get_supported_lr_channel_configs`, `set_lr_channel_config`
+- Added zniffer file I/O commands: `save_capture_to_file`, `load_capture_from_file`, `load_capture_from_buffer`
+- Added utility commands: `guess_firmware_file_format`, `try_unzip_firmware_file`, `extract_firmware`

README.md

@@ -1491,7 +1491,9 @@ interface {
 
 ### Multicasting
 
-There are several commands available that can be multicast to multiple nodes simultaneously. If you would like to broadcast to all nodes, use the `broadcast_node` prefix for the following commands. If you would like to multicast to a subset of nodes, use the `multicast_group` prefix for the following commands, adding a `nodeIDs` list as an input parameter:
+There are several commands available that can be multicast to multiple nodes simultaneously. If you would like to broadcast to all nodes, use the `broadcast_node` prefix for the following commands. If you would like to multicast to a subset of nodes, use the `multicast_group` prefix for the following commands, adding a `nodeIDs` list as an input parameter.
+
+> NOTE: For `broadcast_node` commands, you can pass a `longRange` boolean flag to broadcast to Long Range nodes instead of classic Z-Wave nodes.
 
 ```ts
 interface IncomingCommandMulticastGroupBase extends IncomingCommandBase {
@@ -1759,6 +1761,101 @@ interface {
 }
 ```
 
+#### Get Long Range regions
+
+Gets list of Long Range capable regions.
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "zniffer.get_lr_regions";
+}
+```
+
+#### Get current Long Range channel config
+
+Gets currently configured Long Range channel configuration.
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "zniffer.get_current_lr_channel_config";
+}
+```
+
+#### Get supported Long Range channel configs
+
+Gets map of supported Long Range channel configurations.
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "zniffer.get_supported_lr_channel_configs";
+}
+```
+
+#### Set Long Range channel config
+
+Set Long Range channel configuration (800 series only).
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "zniffer.set_lr_channel_config";
+  channelConfig: number;
+}
+```
+
+#### [Save capture to file](https://zwave-js.github.io/node-zwave-js/#/api/zniffer?id=capturing-frames)
+
+Saves the captured frames to a `.zlf` file that can be read by the official Zniffer application.
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "zniffer.save_capture_to_file";
+  filePath: string;
+}
+```
+
+#### [Load capture from file](https://zwave-js.github.io/node-zwave-js/#/api/zniffer?id=capturing-frames)
+
+Loads previously saved captured frames from a `.zlf` file.
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "zniffer.load_capture_from_file";
+  filePath: string;
+}
+```
+
+#### [Load capture from buffer](https://zwave-js.github.io/node-zwave-js/#/api/zniffer?id=capturing-frames)
+
+Loads captured frames from a base64 encoded buffer.
+
+[compatible with schema version: 47+]
+
+```ts
+interface {
+  messageId: string;
+  command: "zniffer.load_capture_from_buffer";
+  data: string; // base64 encoded .zlf data
+}
+```
+
 ## Events
 
 ### `zwave-js` Events

src/lib/broadcast_node/incoming_message.ts

@@ -3,8 +3,9 @@ import { SetValueAPIOptions } from "zwave-js";
 import { IncomingCommandBase } from "../incoming_message_base.js";
 import { BroadcastNodeCommand } from "./command.js";
 
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface IncomingCommandBroadcastNodeBase extends IncomingCommandBase {}
+export interface IncomingCommandBroadcastNodeBase extends IncomingCommandBase {
+  longRange?: boolean;
+}
 
 export interface IncomingCommandBroadcastNodeSetValue extends IncomingCommandBroadcastNodeBase {
   command: BroadcastNodeCommand.setValue;

src/lib/broadcast_node/message_handler.ts

@@ -18,7 +18,9 @@ export class BroadcastNodeMessageHandler implements MessageHandler {
   ): Promise<BroadcastNodeResultTypes[BroadcastNodeCommand]> {
     const { command } = message;
 
-    const virtualNode = this.driver.controller.getBroadcastNode();
+    const virtualNode = message.longRange
+      ? this.driver.controller.getBroadcastNodeLR()
+      : this.driver.controller.getBroadcastNode();
 
     switch (message.command) {
       case BroadcastNodeCommand.setValue: {

src/lib/utils/command.ts

@@ -6,4 +6,7 @@ export enum UtilsCommand {
   buffer2hex = "utils.buffer2hex", // While made available in the server due to its availability within the driver, this functionality works best when implemented locally
   getEnumMemberName = "utils.get_enum_member_name", // While made available in the server due to its availability within the driver, this functionality works best when implemented locally
   rssiToString = "utils.rssi_to_string",
+  guessFirmwareFileFormat = "utils.guess_firmware_file_format",
+  tryUnzipFirmwareFile = "utils.try_unzip_firmware_file",
+  extractFirmware = "utils.extract_firmware",
 }

src/lib/utils/incoming_message.ts

@@ -1,4 +1,5 @@
 import { RSSI } from "zwave-js";
+import { FirmwareFileFormat } from "@zwave-js/core";
 import { IncomingCommandBase } from "../incoming_message_base.js";
 import { UtilsCommand } from "./command.js";
 
@@ -43,11 +44,31 @@ export interface IncomingCommandUtilsRssiToString extends IncomingCommandUtilsBa
   rssi: RSSI;
 }
 
+export interface IncomingCommandUtilsGuessFirmwareFileFormat extends IncomingCommandUtilsBase {
+  command: UtilsCommand.guessFirmwareFileFormat;
+  filename: string;
+  file: string; // base64 encoded
+}
+
+export interface IncomingCommandUtilsTryUnzipFirmwareFile extends IncomingCommandUtilsBase {
+  command: UtilsCommand.tryUnzipFirmwareFile;
+  file: string; // base64 encoded ZIP file
+}
+
+export interface IncomingCommandUtilsExtractFirmware extends IncomingCommandUtilsBase {
+  command: UtilsCommand.extractFirmware;
+  file: string; // base64 encoded firmware file
+  format: FirmwareFileFormat;
+}
+
 export type IncomingMessageUtils =
   | IncomingCommandUtilsParseQRCodeString
   | IncomingCommandUtilsTryParseDSKFromQRCodeString
   | IncomingCommandUtilsNum2hex
   | IncomingCommandUtilsFormatId
   | IncomingCommandUtilsBuffer2hex
   | IncomingCommandUtilsGetEnumMemberName
-  | IncomingCommandUtilsRssiToString;
+  | IncomingCommandUtilsRssiToString
+  | IncomingCommandUtilsGuessFirmwareFileFormat
+  | IncomingCommandUtilsTryUnzipFirmwareFile
+  | IncomingCommandUtilsExtractFirmware;

src/lib/utils/message_handler.ts

@@ -5,7 +5,13 @@ import {
   num2hex,
   rssiToString,
 } from "zwave-js";
-import { parseQRCodeString, tryParseDSKFromQRCodeString } from "@zwave-js/core";
+import {
+  extractFirmware,
+  guessFirmwareFileFormat,
+  parseQRCodeString,
+  tryParseDSKFromQRCodeString,
+  tryUnzipFirmwareFile,
+} from "@zwave-js/core";
 import { UnknownCommandError } from "../error.js";
 import { UtilsCommand } from "./command.js";
 import { IncomingMessageUtils } from "./incoming_message.js";
@@ -47,6 +53,35 @@ export class UtilsMessageHandler implements MessageHandler {
         const rssi = rssiToString(message.rssi);
         return { rssi };
       }
+      case UtilsCommand.guessFirmwareFileFormat: {
+        const fileBuffer = Buffer.from(message.file, "base64");
+        const format = guessFirmwareFileFormat(message.filename, fileBuffer);
+        return { format };
+      }
+      case UtilsCommand.tryUnzipFirmwareFile: {
+        const zipBuffer = Buffer.from(message.file, "base64");
+        const result = tryUnzipFirmwareFile(zipBuffer);
+        if (!result) {
+          return { file: undefined };
+        }
+        return {
+          file: {
+            filename: result.filename,
+            format: result.format,
+            data: Buffer.from(result.rawData).toString("base64"),
+          },
+        };
+      }
+      case UtilsCommand.extractFirmware: {
+        const fileBuffer = Buffer.from(message.file, "base64");
+        const firmware = await extractFirmware(fileBuffer, message.format);
+        return {
+          firmware: {
+            data: Buffer.from(firmware.data).toString("base64"),
+            firmwareTarget: firmware.firmwareTarget,
+          },
+        };
+      }
       default: {
         throw new UnknownCommandError(command);
       }

src/lib/utils/outgoing_message.ts

@@ -1,4 +1,4 @@
-import { QRProvisioningInformation } from "@zwave-js/core";
+import { FirmwareFileFormat, QRProvisioningInformation } from "@zwave-js/core";
 import { UtilsCommand } from "./command.js";
 
 export interface UtilsResultTypes {
@@ -13,4 +13,21 @@ export interface UtilsResultTypes {
   [UtilsCommand.buffer2hex]: { hex: string };
   [UtilsCommand.getEnumMemberName]: { name: string };
   [UtilsCommand.rssiToString]: { rssi: string };
+  [UtilsCommand.guessFirmwareFileFormat]: { format: FirmwareFileFormat };
+  [UtilsCommand.tryUnzipFirmwareFile]: {
+    // Returns undefined if not a valid ZIP or no compatible firmware found
+    file:
+      | {
+          filename: string;
+          format: FirmwareFileFormat;
+          data: string; // base64 encoded
+        }
+      | undefined;
+  };
+  [UtilsCommand.extractFirmware]: {
+    firmware: {
+      data: string; // base64 encoded
+      firmwareTarget?: number;
+    };
+  };
 }

src/lib/zniffer/command.ts

@@ -9,4 +9,16 @@ export enum ZnifferCommand {
   supportedFrequencies = "zniffer.supported_frequencies",
   currentFrequency = "zniffer.current_frequency",
   setFrequency = "zniffer.set_frequency",
+  // Undocumented
+  getLRRegions = "zniffer.get_lr_regions",
+  // Undocumented
+  getCurrentLRChannelConfig = "zniffer.get_current_lr_channel_config",
+  // Undocumented
+  getSupportedLRChannelConfigs = "zniffer.get_supported_lr_channel_configs",
+  // Undocumented
+  setLRChannelConfig = "zniffer.set_lr_channel_config",
+  // File I/O
+  saveCaptureToFile = "zniffer.save_capture_to_file",
+  loadCaptureFromFile = "zniffer.load_capture_from_file",
+  loadCaptureFromBuffer = "zniffer.load_capture_from_buffer",
 }

src/lib/zniffer/incoming_message.ts

@@ -48,6 +48,40 @@ export interface IncomingCommandZnifferSetFrequency extends IncomingCommandZniff
   frequency: number;
 }
 
+// Long Range
+export interface IncomingCommandZnifferGetLRRegions extends IncomingCommandZnifferBase {
+  command: ZnifferCommand.getLRRegions;
+}
+
+export interface IncomingCommandZnifferGetCurrentLRChannelConfig extends IncomingCommandZnifferBase {
+  command: ZnifferCommand.getCurrentLRChannelConfig;
+}
+
+export interface IncomingCommandZnifferGetSupportedLRChannelConfigs extends IncomingCommandZnifferBase {
+  command: ZnifferCommand.getSupportedLRChannelConfigs;
+}
+
+export interface IncomingCommandZnifferSetLRChannelConfig extends IncomingCommandZnifferBase {
+  command: ZnifferCommand.setLRChannelConfig;
+  channelConfig: number;
+}
+
+// File I/O
+export interface IncomingCommandZnifferSaveCaptureToFile extends IncomingCommandZnifferBase {
+  command: ZnifferCommand.saveCaptureToFile;
+  filePath: string;
+}
+
+export interface IncomingCommandZnifferLoadCaptureFromFile extends IncomingCommandZnifferBase {
+  command: ZnifferCommand.loadCaptureFromFile;
+  filePath: string;
+}
+
+export interface IncomingCommandZnifferLoadCaptureFromBuffer extends IncomingCommandZnifferBase {
+  command: ZnifferCommand.loadCaptureFromBuffer;
+  data: string; // base64 encoded
+}
+
 export type IncomingMessageZniffer =
   | IncomingCommandZnifferClearCapturedFrames
   | IncomingCommandZnifferGetCaptureAsZLFBuffer
@@ -58,4 +92,11 @@ export type IncomingMessageZniffer =
   | IncomingCommandZnifferSupportedFrequencies
   | IncomingCommandZnifferCurrentFrequency
   | IncomingCommandZnifferSetFrequency
-  | IncomingCommandZnifferDestroy;
+  | IncomingCommandZnifferDestroy
+  | IncomingCommandZnifferGetLRRegions
+  | IncomingCommandZnifferGetCurrentLRChannelConfig
+  | IncomingCommandZnifferGetSupportedLRChannelConfigs
+  | IncomingCommandZnifferSetLRChannelConfig
+  | IncomingCommandZnifferSaveCaptureToFile
+  | IncomingCommandZnifferLoadCaptureFromFile
+  | IncomingCommandZnifferLoadCaptureFromBuffer;