homebridge-zwave-usb 3.6.0 → 3.6.2

package/README.md

@@ -107,7 +107,7 @@ npm install -g homebridge-zwave-usb
 
 When pairing a Security 2 (S2) device, you must enter a 5-digit PIN found on the device label or box.
 
-### Method 1: Using HomeKit (Recommended)
+### Method 1: Using a Third-Party HomeKit App (Recommended)
 1. Use a third-party app like **Controller for HomeKit**, **Eve**, or **Home+**.
 2. Find the **"Z-Wave Controller"** accessory and the **"Z-Wave Manager"** service.
 3. Write the 5-digit PIN into the **"S2 PIN Entry"** field.
@@ -131,21 +131,26 @@ This plugin adds a management accessory to your Home app to handle network opera
 - **Heal Network**: A switch to trigger a background mesh network optimization.
 - **Prune Dead Nodes**: Automatically removes devices marked as "Dead" (failed) from the network. **Safe for battery devices**: This only removes nodes the controller has confirmed as failed (Status 3); it will never remove a device that is simply "Asleep" (Status 1).
 
+Controller switch labels are exposed using a compatibility path for Home app visibility. Some HomeKit apps may still render these actions differently.
+
 ### 🛠️ Advanced Management
 
 The plugin provides additional tools for network maintenance:
 
 - **Dual S2 PIN Entry**: When a device requires a PIN, you can enter it via the Homebridge terminal (`echo "12345" > s2_pin.txt`) or via the `S2 PIN Entry` characteristic in third-party HomeKit apps.
-- **Automated Reconciliation**: Orphaned accessories are automatically removed from HomeKit 60 seconds after startup if the node is no longer present in the Z-Wave network.
+- **Explicit Stale Accessory Cleanup**: The custom UI includes a maintenance action to remove stale cached accessories when a node has been removed from the Z-Wave network but Homebridge still has an old cached entry.
 
 ## 🛠️ Maintenance & Firmware Updates
 
 The plugin includes a dedicated **Maintenance** tab within the Homebridge custom UI (accessible via the plugin settings).
 
 - **Node Overview**: View a complete list of all Z-Wave nodes in your network, including their status and current firmware versions.
+- **HomeKit Publication State**: See whether a node is already published to HomeKit, still cached and waiting for interview wake-up, or intentionally deferred until interview metadata is available.
+- **Node Rename**: Rename the Z-Wave node from the plugin UI without recreating the HomeKit accessory.
 - **Official Updates**: Click "Check Update" to query the official Z-Wave JS Firmware Update Service. If a manufacturer-approved update is available, you can start the OTA transfer with a single click.
 - **Battery Device Support**: Firmware updates are supported for battery-powered devices. You will be prompted to manually wake the device after starting the process to initiate the transfer.
 - **Real-time Progress**: Monitor the progress of the firmware transfer via a live progress bar.
+- **Clean Up Stale Accessories**: Remove stale cached Homebridge accessories explicitly from the maintenance UI instead of relying on automatic startup pruning.
 
 ## ❓ Troubleshooting
 

package/dist/accessories/ZWaveAccessory.js

@@ -220,14 +220,14 @@ class ZWaveAccessory {
         }
     }
     getDesiredName() {
-        return this.node.name || this.node.deviceConfig?.label || `Node ${this.node.nodeId}`;
+        return this.node.name || this.node.label || this.node.deviceConfig?.label || `Node ${this.node.nodeId}`;
     }
     getEffectiveName() {
         return this.platformAccessory.displayName || this.getDesiredName();
     }
     applyAccessoryMetadata(options = {}) {
-        const manufacturer = this.node.deviceConfig?.manufacturer || 'Unknown';
-        const model = this.node.deviceConfig?.label || `Node ${this.node.nodeId}`;
+        const manufacturer = this.node.manufacturer || this.node.deviceConfig?.manufacturer || 'Unknown';
+        const model = this.node.label || this.node.deviceConfig?.label || `Node ${this.node.nodeId}`;
         const serial = `Node ${this.node.nodeId}`;
         const name = this.getEffectiveName();
         const firmwareRevision = this.node.firmwareVersion || '1.0.0';

package/dist/platform/ZWaveUsbPlatform.d.ts

@@ -17,6 +17,7 @@ export declare class ZWaveUsbPlatform implements DynamicPlatformPlugin {
      */
     private discoveryInFlight;
     private firmwareProgress;
+    private refreshStates;
     constructor(log: Logger, config: PlatformConfig, api: API);
     private startIpcServer;
     private stopIpcServer;

package/dist/platform/ZWaveUsbPlatform.js

@@ -31,6 +31,7 @@ class ZWaveUsbPlatform {
      */
     discoveryInFlight = new Set();
     firmwareProgress = new Map();
+    refreshStates = new Map();
     constructor(log, config, api) {
         this.log = log;
         this.config = config;
@@ -111,14 +112,15 @@ class ZWaveUsbPlatform {
                     const nodes = Array.from(this.zwaveController?.nodes.values() || []).map((node) => ({
                         nodeId: node.nodeId,
                         name: node.name,
-                        label: node.deviceConfig?.label,
-                        manufacturer: node.deviceConfig?.manufacturer,
+                        label: node.label || node.deviceConfig?.label,
+                        manufacturer: node.manufacturer || node.deviceConfig?.manufacturer,
                         status: node.status,
                         ready: node.ready,
                         firmwareVersion: node.firmwareVersion,
                         isListening: node.isListening,
                         isFrequentListening: node.isFrequentListening,
                         firmwareProgress: this.firmwareProgress.get(node.nodeId),
+                        refreshState: this.refreshStates.get(node.nodeId),
                         homekitState: this.getHomeKitPublicationState(node),
                     }));
                     return sendJson(nodes);
@@ -153,6 +155,24 @@ class ZWaveUsbPlatform {
                     });
                     return;
                 }
+                if (normalizedUrl.startsWith('/nodes/') &&
+                    normalizedUrl.endsWith('/refresh-info') &&
+                    method === 'POST') {
+                    const parts = normalizedUrl.split('/');
+                    const nodeId = parseInt(parts[2], 10);
+                    this.zwaveController
+                        ?.refreshNodeInfo(nodeId)
+                        .then((result) => {
+                        this.refreshStates.set(nodeId, result.requiresWakeUp ? 'waiting-wakeup' : 'refreshing');
+                        sendJson({
+                            success: true,
+                            refreshState: this.refreshStates.get(nodeId),
+                            ...result,
+                        });
+                    })
+                        .catch((err) => sendJson({ error: err.message }, 500));
+                    return;
+                }
                 if (normalizedUrl === '/accessories/prune-stale' && method === 'POST') {
                     try {
                         const removed = this.pruneStaleAccessories();
@@ -308,11 +328,21 @@ class ZWaveUsbPlatform {
         this.syncNodeAccessory(node);
     }
     handleNodeReady(node) {
-        const nodeName = node.name || node.deviceConfig?.label || `Node ${node.nodeId}`;
+        this.refreshStates.delete(node.nodeId);
+        const nodeName = node.name || node.label || node.deviceConfig?.label || `Node ${node.nodeId}`;
         this.log.info(`Node ${node.nodeId} (${nodeName}) ready`);
         this.syncNodeAccessory(node);
     }
     handleNodeUpdated(node) {
+        const refreshState = this.refreshStates.get(node.nodeId);
+        if (refreshState) {
+            if (node.ready) {
+                this.refreshStates.delete(node.nodeId);
+            }
+            else if (node.status !== 1) {
+                this.refreshStates.set(node.nodeId, 'refreshing');
+            }
+        }
         this.syncNodeAccessory(node);
     }
     syncNodeAccessory(node) {
@@ -432,6 +462,7 @@ class ZWaveUsbPlatform {
         return staleAccessories.length;
     }
     handleNodeRemoved(node) {
+        this.refreshStates.delete(node.nodeId);
         this.log.info(`Node ${node.nodeId} removed`);
         const homeId = this.zwaveController?.homeId;
         const liveAccessory = this.zwaveAccessories.get(node.nodeId);

package/dist/zwave/ZWaveController.d.ts

@@ -61,6 +61,10 @@ export declare class ZWaveController extends EventEmitter implements IZWaveContr
      */
     setNodeName(nodeId: number, name: string): Promise<void>;
     getAvailableFirmwareUpdates(nodeId: number): Promise<unknown[]>;
+    refreshNodeInfo(nodeId: number): Promise<{
+        nodeId: number;
+        requiresWakeUp: boolean;
+    }>;
     beginFirmwareUpdate(nodeId: number, update: unknown): Promise<void>;
     abortFirmwareUpdate(nodeId: number): Promise<void>;
 }

package/dist/zwave/ZWaveController.js

@@ -155,7 +155,7 @@ class ZWaveController extends events_1.EventEmitter {
          */
         const statusMap = ['Unknown', 'Asleep', 'Awake', 'Dead', 'Alive'];
         const status = statusMap[node.status] || node.status.toString();
-        const nodeName = node.name || node.deviceConfig?.label || `Node ${node.nodeId}`;
+        const nodeName = node.name || node.label || node.deviceConfig?.label || `Node ${node.nodeId}`;
         this.log.info(`Node ${node.nodeId} (${nodeName}) added to controller (Status: ${status}, Interview Stage: ${node.interviewStage})`);
         const onReady = () => {
             this.log.info(`Node ${node.nodeId} is ready (Interview Stage: ${node.interviewStage})`);
@@ -726,6 +726,21 @@ class ZWaveController extends events_1.EventEmitter {
             return [];
         }
     }
+    async refreshNodeInfo(nodeId) {
+        const node = this.nodes.get(nodeId);
+        if (!node) {
+            throw new Error(`Node ${nodeId} not found`);
+        }
+        const requiresWakeUp = !node.isListening && !node.isFrequentListening;
+        this.log.info(`Refreshing interview information for Node ${nodeId}${requiresWakeUp ? ' (manual wake-up likely required)' : ''}...`);
+        // Do not await refreshInfo() here. For sleepy nodes zwave-js may wait until
+        // the next wake-up before it begins the fresh interview, and the UI should be
+        // able to show "queued" state immediately instead of blocking on that wake-up.
+        void node.refreshInfo().catch((err) => {
+            this.log.error(`Failed to refresh node info for Node ${nodeId}:`, err);
+        });
+        return { nodeId, requiresWakeUp };
+    }
     async beginFirmwareUpdate(nodeId, update) {
         const node = this.nodes.get(nodeId);
         if (!node) {

package/dist/zwave/interfaces.d.ts

@@ -21,6 +21,10 @@ export interface IZWaveController extends EventEmitter {
     stopHealing(): Promise<boolean>;
     removeFailedNode(nodeId: number): Promise<void>;
     setNodeName(nodeId: number, name: string): Promise<void>;
+    refreshNodeInfo(nodeId: number): Promise<{
+        nodeId: number;
+        requiresWakeUp: boolean;
+    }>;
     setS2Pin(pin: string): void;
     getAvailableFirmwareUpdates(nodeId: number): Promise<unknown[]>;
     beginFirmwareUpdate(nodeId: number, update: unknown): Promise<void>;
@@ -44,6 +48,8 @@ export interface IZWaveController extends EventEmitter {
 export interface IZWaveNode {
     nodeId: number;
     name?: string;
+    manufacturer?: string;
+    label?: string;
     deviceConfig?: {
         label?: string;
         manufacturer?: string;
@@ -52,6 +58,8 @@ export interface IZWaveNode {
     interviewStage: InterviewStage;
     status: number;
     firmwareVersion?: string;
+    isListening?: boolean | string;
+    isFrequentListening?: boolean | string;
     getValue(valueId: ValueID): unknown;
     setValue(valueId: ValueID, value: unknown): Promise<SetValueResult>;
     supportsCC(cc: number): boolean;

package/homebridge-ui/public/index.html

@@ -187,7 +187,7 @@
           </div>
           <div class="d-flex justify-content-between align-items-center mb-2">
             <div class="text-muted small">
-              Nodes that have not completed interview yet are intentionally held back from HomeKit until their service metadata is stable.
+              Nodes that have not completed interview yet are intentionally held back from HomeKit until their service metadata is stable. Use Refresh Info to force a fresh interview when metadata looks incomplete.
             </div>
             <button class="btn btn-sm btn-outline-danger" id="cleanupStaleAccessories">
               Clean Up Stale Accessories
@@ -245,6 +245,7 @@
       let isPromptOpen = false;
       let activeNodeId = null;
       let activeUpdateData = null;
+      let activeMaintenanceAction = null;
       const uiHelpers = window.ZWaveUsbUiHelpers;
 
       const getInt = (id, def) => {
@@ -315,6 +316,10 @@
 	        'cached-pending': 'Cached in HomeKit, waiting for interview wake-up',
 	        'pending-interview': 'Not in HomeKit yet, waiting for interview metadata',
 	      };
+	      const refreshStateMap = {
+	        'waiting-wakeup': 'Refresh queued, waiting for wake-up',
+	        refreshing: 'Refresh in progress',
+	      };
 
       const loadNodes = async () => {
         if (isPromptOpen) return;
@@ -336,6 +341,7 @@
 	            const progress = node.firmwareProgress;
 	            const nodeName = node.name || node.label || 'Node ' + node.nodeId;
 	            const homeKitState = homeKitStateMap[node.homekitState] || '';
+	            const refreshState = refreshStateMap[node.refreshState] || '';
 
 	            let actionHtml = '';
             if (progress) {
@@ -351,6 +357,7 @@
               actionHtml = `
                 <div class="btn-group">
                   <button class="btn btn-sm btn-outline-secondary rename-node" data-nodeid="${node.nodeId}">Rename</button>
+                  <button class="btn btn-sm btn-outline-secondary refresh-node-info" data-nodeid="${node.nodeId}" data-requires-wakeup="${!node.isListening && !node.isFrequentListening}">Refresh Info</button>
                   <button class="btn btn-sm btn-outline-primary check-update" data-nodeid="${node.nodeId}">Check Update</button>
                 </div>
               `;
@@ -361,6 +368,7 @@
 	              <td id="node-name-${node.nodeId}">${nodeName}</td>
 	              <td>
 	                <span class="badge badge-${status === 'Alive' || status === 'Awake' ? 'success' : 'secondary'}">${status}</span>
+	                ${refreshState ? `<div class="small text-muted mt-1">${refreshState}</div>` : ''}
 	                ${homeKitState ? `<div class="small text-muted mt-1">${homeKitState}</div>` : ''}
 	              </td>
 	              <td>${node.firmwareVersion || 'Unknown'}</td>
@@ -390,6 +398,7 @@
         isPromptOpen = false;
         activeNodeId = null;
         activeUpdateData = null;
+        activeMaintenanceAction = null;
       };
 
       // Event Delegation for Table Actions (Rename & Firmware)
@@ -409,6 +418,17 @@
           return;
         }
 
+        if (target.classList.contains('refresh-node-info')) {
+          activeNodeId = nodeId;
+          activeMaintenanceAction = 'refresh-node-info';
+          const requiresWakeUp = target.getAttribute('data-requires-wakeup') === 'true';
+          document.getElementById('confirmMessage').textContent = requiresWakeUp
+            ? 'This resets the node interview state and requests fresh metadata. Keep the device awake while the refresh runs so it can answer interview commands.'
+            : 'This resets the node interview state and requests fresh metadata from the node. Continue?';
+          showModal('confirmModal');
+          return;
+        }
+
         // 2. Check Update Logic
         if (target.classList.contains('check-update')) {
           target.disabled = true;
@@ -469,11 +489,21 @@
 	      document.getElementById('executeConfirm').addEventListener('click', async () => {
         const nodeId = activeNodeId;
         const updateData = activeUpdateData;
+        const maintenanceAction = activeMaintenanceAction;
         hideModals();
 
         try {
-          await window.homebridge.request('start-update', { nodeId, update: updateData });
-          window.homebridge.toast.success('Firmware update started!');
+          if (maintenanceAction === 'refresh-node-info') {
+            const result = await window.homebridge.request('refresh-node-info', nodeId);
+            window.homebridge.toast.success(
+              result?.refreshState === 'waiting-wakeup'
+                ? `Refresh queued for Node ${nodeId}. Wake the device until the interview finishes.`
+                : `Refresh started for Node ${nodeId}.`,
+            );
+          } else {
+            await window.homebridge.request('start-update', { nodeId, update: updateData });
+            window.homebridge.toast.success('Firmware update started!');
+          }
           loadNodes();
         } catch (err) {
           window.homebridge.toast.error(err.message);

package/homebridge-ui/server.js

@@ -15,6 +15,10 @@ class UiServer extends HomebridgePluginUiServer {
       return await this.ipcRequest(`/nodes/${nodeId}/name`, 'POST', { name });
     });
 
+    this.onRequest('refresh-node-info', async (nodeId) => {
+      return await this.ipcRequest(`/nodes/${nodeId}/refresh-info`, 'POST');
+    });
+
     this.onRequest('cleanup-stale-accessories', async () => {
       return await this.ipcRequest('/accessories/prune-stale', 'POST');
     });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-zwave-usb",
   "displayName": "Homebridge Z-Wave USB",
-  "version": "3.6.0",
+  "version": "3.6.2",
   "description": "A Homebridge dynamic platform plugin for Z-Wave USB controllers using zwave-js.",
   "license": "Polyform-Noncommercial-1.0.0",
   "funding": {