zwave-js 11.0.0 → 11.2.0

package/build/lib/controller/Controller.js

@@ -74,7 +74,7 @@ const NodeInformationFrame_1 = require("./NodeInformationFrame");
 const ZWaveSDKVersions_1 = require("./ZWaveSDKVersions");
 const _Types_3 = require("./_Types");
 const utils_1 = require("./utils");
-let ZWaveController = class ZWaveController extends shared_1.TypedEventEmitter {
+let ZWaveController = exports.ZWaveController = class ZWaveController extends shared_1.TypedEventEmitter {
     /** @internal */
     constructor(driver, bootloaderOnly = false) {
         super();
@@ -644,6 +644,18 @@ let ZWaveController = class ZWaveController extends shared_1.TypedEventEmitter {
     async hardReset() {
         // begin the reset process
         try {
+            const associations = this.nodes.get(this._ownNodeId)?.associations;
+            if (associations?.length) {
+                this.driver.controllerLog.print("Notifying associated nodes about reset...");
+                for (const nodeId of associations) {
+                    const node = this.nodes.get(nodeId);
+                    if (!node)
+                        continue;
+                    void node.sendResetLocallyNotification().catch(() => {
+                        // ignore
+                    });
+                }
+            }
             this.driver.controllerLog.print("performing hard reset...");
             await this.driver.sendMessage(new HardResetRequest_1.HardResetRequest(this.driver), {
                 supportCheck: false,
@@ -1031,11 +1043,8 @@ let ZWaveController = class ZWaveController extends shared_1.TypedEventEmitter {
                     direction: "inbound",
                 });
                 node.updateNodeInfo(msg.nodeInformation);
-                // Tell the send thread that we received a NIF from the node
-                this.driver["sendThread"].send({
-                    type: "NIF",
-                    nodeId: node.id,
-                });
+                // Resolve active pings that would fail otherwise
+                this.driver.resolvePendingPings(node.id);
                 if (node.canSleep &&
                     node.supportsCC(core_1.CommandClasses["Wake Up"])) {
                     // In case this is a sleeping node and there are no messages in the queue, the node may go back to sleep very soon
@@ -1147,7 +1156,8 @@ supported CCs: ${nodeInfo.supportedCCs
                     // No command received, bootstrap node by ourselves
                     this.driver.controllerLog.logNode(nodeId, "no initiate command received, bootstrapping node...");
                     // Assign SUC return route to make sure the node knows where to get its routes from
-                    newNode.hasSUCReturnRoute = await this.assignSUCReturnRoute(newNode.id);
+                    newNode.hasSUCReturnRoute =
+                        await this.assignSUCReturnRoutes(newNode.id);
                     // Include using the default inclusion strategy:
                     // * Use S2 if possible,
                     // * only use S0 if necessary,
@@ -1184,8 +1194,6 @@ supported CCs: ${nodeInfo.supportedCCs
                         }
                     }
                 }
-                // Bootstrap the node's lifelines, so it knows where the controller is
-                await this.bootstrapLifelineAndWakeup(newNode);
                 // We're done adding this node, notify listeners
                 const result = bootstrapFailure != undefined
                     ? {
@@ -1200,7 +1208,9 @@ supported CCs: ${nodeInfo.supportedCCs
                     const step = initiate.step;
                     newNode.once("ready", () => {
                         this.driver.controllerLog.logNode(nodeId, `Notifying node ${inclCtrlrId} of finished inclusion`);
-                        void inclCtrlr.commandClasses["Inclusion Controller"]
+                        // Create API without checking for support
+                        const api = inclCtrlr.createAPI(core_1.CommandClasses["Inclusion Controller"], false);
+                        void api
                             .completeStep(step, cc_1.InclusionControllerStatus.OK)
                             // eslint-disable-next-line @typescript-eslint/no-empty-function
                             .catch(() => { });
@@ -1253,8 +1263,6 @@ supported CCs: ${nodeInfo.supportedCCs
             }
             // Perform S0/S2 bootstrapping
             const bootstrapFailure = await this.proxyBootstrap(newNode, inclCtrlr);
-            // Bootstrap the node's lifelines, so it knows where the controller is
-            await this.bootstrapLifelineAndWakeup(newNode);
             // We're done adding this node, notify listeners
             const result = bootstrapFailure != undefined
                 ? {
@@ -1267,7 +1275,9 @@ supported CCs: ${nodeInfo.supportedCCs
             // And notify the inclusion controller after we're done interviewing
             newNode.once("ready", () => {
                 this.driver.controllerLog.logNode(inclCtrlr.nodeId, `Notifying inclusion controller of finished inclusion`);
-                void inclCtrlr.commandClasses["Inclusion Controller"]
+                // Create API without checking for support
+                const api = inclCtrlr.createAPI(core_1.CommandClasses["Inclusion Controller"], false);
+                void api
                     .completeStep(initiate.step, cc_1.InclusionControllerStatus.OK)
                     // eslint-disable-next-line @typescript-eslint/no-empty-function
                     .catch(() => { });
@@ -1869,97 +1879,6 @@ supported CCs: ${nodeInfo.supportedCCs
             this.cancelBootstrapS2Promise = undefined;
         }
     }
-    /** Ensures that the node knows where to reach the controller */
-    async bootstrapLifelineAndWakeup(node) {
-        // If the node was bootstrapped with S2, all these requests must happen securely
-        if ((0, core_1.securityClassIsS2)(node.getHighestSecurityClass())) {
-            for (const cc of [
-                core_1.CommandClasses["Wake Up"],
-                core_1.CommandClasses.Association,
-                core_1.CommandClasses["Multi Channel Association"],
-                core_1.CommandClasses.Version,
-            ]) {
-                if (node.supportsCC(cc)) {
-                    node.addCC(cc, { secure: true });
-                }
-            }
-        }
-        if (node.supportsCC(core_1.CommandClasses["Z-Wave Plus Info"])) {
-            // SDS11846: The Z-Wave+ lifeline must be assigned to a node as the very first thing
-            if (node.supportsCC(core_1.CommandClasses.Association) ||
-                node.supportsCC(core_1.CommandClasses["Multi Channel Association"])) {
-                this.driver.controllerLog.logNode(node.id, {
-                    message: `Configuring Z-Wave+ Lifeline association...`,
-                    direction: "none",
-                });
-                const ownNodeId = this.driver.controller.ownNodeId;
-                try {
-                    if (node.supportsCC(core_1.CommandClasses.Association)) {
-                        await node.commandClasses.Association.addNodeIds(1, ownNodeId);
-                    }
-                    else {
-                        await node.commandClasses["Multi Channel Association"].addDestinations({
-                            groupId: 1,
-                            endpoints: [{ nodeId: ownNodeId, endpoint: 0 }],
-                        });
-                    }
-                    // After setting the association, make sure the node knows how to reach us
-                    await this.assignReturnRoute(node.id, ownNodeId);
-                }
-                catch (e) {
-                    if ((0, core_1.isTransmissionError)(e) || (0, core_1.isRecoverableZWaveError)(e)) {
-                        this.driver.controllerLog.logNode(node.id, {
-                            message: `Failed to configure Z-Wave+ Lifeline association: ${e.message}`,
-                            direction: "none",
-                            level: "warn",
-                        });
-                    }
-                    else {
-                        throw e;
-                    }
-                }
-            }
-            else {
-                this.driver.controllerLog.logNode(node.id, {
-                    message: `Cannot configure Z-Wave+ Lifeline association: Node does not support associations...`,
-                    direction: "none",
-                    level: "warn",
-                });
-            }
-        }
-        if (node.supportsCC(core_1.CommandClasses["Wake Up"])) {
-            try {
-                // Query the version, so we can setup the wakeup destination correctly.
-                let supportedVersion;
-                if (node.supportsCC(core_1.CommandClasses.Version)) {
-                    supportedVersion =
-                        await node.commandClasses.Version.getCCVersion(core_1.CommandClasses["Wake Up"]);
-                }
-                // If querying the version can't be done, we should at least assume that it supports V1
-                supportedVersion ?? (supportedVersion = 1);
-                if (supportedVersion > 0) {
-                    node.addCC(core_1.CommandClasses["Wake Up"], {
-                        version: supportedVersion,
-                    });
-                    const instance = node.createCCInstance(core_1.CommandClasses["Wake Up"]);
-                    await instance.interview(this.driver);
-                }
-            }
-            catch (e) {
-                if ((0, core_1.isTransmissionError)(e) || (0, core_1.isRecoverableZWaveError)(e)) {
-                    this.driver.controllerLog.logNode(node.id, {
-                        message: `Cannot configure wakeup destination: ${e.message}`,
-                        direction: "none",
-                        level: "warn",
-                    });
-                }
-                else {
-                    // we want to pass all other errors through
-                    throw e;
-                }
-            }
-        }
-    }
     /**
      * Is called when an AddNode request is received from the controller.
      * Handles and controls the inclusion process.
@@ -2066,7 +1985,7 @@ supported CCs: ${nodeInfo.supportedCCs
                 // If it is actually a sleeping device, it will be marked as such later
                 newNode.markAsAlive();
                 // Assign SUC return route to make sure the node knows where to get its routes from
-                newNode.hasSUCReturnRoute = await this.assignSUCReturnRoute(newNode.id);
+                newNode.hasSUCReturnRoute = await this.assignSUCReturnRoutes(newNode.id);
                 const opts = this._inclusionOptions;
                 let bootstrapFailure;
                 let smartStartFailed = false;
@@ -2180,10 +2099,6 @@ supported CCs: ${nodeInfo.supportedCCs
                         });
                     }
                 }
-                else {
-                    // Bootstrap the node's lifelines, so it knows where the controller is
-                    await this.bootstrapLifelineAndWakeup(newNode);
-                }
                 this.setInclusionState(Inclusion_1.InclusionState.Idle);
                 // We're done adding this node, notify listeners
                 const result = bootstrapFailure != undefined
@@ -2253,7 +2168,8 @@ supported CCs: ${nodeInfo.supportedCCs
                     // If it is actually a sleeping device, it will be marked as such later
                     newNode.markAsAlive();
                     // Assign SUC return route to make sure the node knows where to get its routes from
-                    newNode.hasSUCReturnRoute = await this.assignSUCReturnRoute(newNode.id);
+                    newNode.hasSUCReturnRoute =
+                        await this.assignSUCReturnRoutes(newNode.id);
                     // Try perform the security bootstrap process. When replacing a node, we don't know any supported CCs
                     // yet, so we need to trust the chosen inclusion strategy.
                     const strategy = this._inclusionOptions.strategy;
@@ -2287,8 +2203,6 @@ supported CCs: ${nodeInfo.supportedCCs
                             newNode.securityClasses.set(secClass, false);
                         }
                     }
-                    // Bootstrap the node's lifelines, so it knows where the controller is
-                    await this.bootstrapLifelineAndWakeup(newNode);
                     // We're done adding this node, notify listeners. This also kicks off the node interview
                     const result = bootstrapFailure != undefined
                         ? {
@@ -2575,18 +2489,9 @@ supported CCs: ${nodeInfo.supportedCCs
                     message: `refreshing neighbor list (attempt ${attempt})...`,
                     direction: "outbound",
                 });
-                // During inclusion, the timeout is mainly required for the node to detect all neighbors
-                // We do the same here, so we just reuse the timeout
-                const discoveryTimeout = (0, AddNodeToNetworkRequest_1.computeNeighborDiscoveryTimeout)(this.driver, 
-                // Controllers take longer, just assume the worst case here
-                core_1.NodeType.Controller);
                 try {
-                    const resp = await this.driver.sendMessage(new RequestNodeNeighborUpdateMessages_1.RequestNodeNeighborUpdateRequest(this.driver, {
-                        nodeId,
-                        discoveryTimeout,
-                    }));
-                    if (resp.updateStatus ===
-                        RequestNodeNeighborUpdateMessages_1.NodeNeighborUpdateStatus.UpdateDone) {
+                    const result = await this.discoverNodeNeighbors(nodeId);
+                    if (result) {
                         this.driver.controllerLog.logNode(nodeId, {
                             message: "neighbor list refreshed...",
                             direction: "inbound",
@@ -2595,7 +2500,6 @@ supported CCs: ${nodeInfo.supportedCCs
                         break;
                     }
                     else {
-                        // UpdateFailed
                         this.driver.controllerLog.logNode(nodeId, {
                             message: "refreshing neighbor list failed...",
                             direction: "inbound",
@@ -2616,24 +2520,16 @@ supported CCs: ${nodeInfo.supportedCCs
                 }
             }
             // 2. re-create the SUC return route, just in case
-            if (await this.deleteSUCReturnRoute(nodeId)) {
-                node.hasSUCReturnRoute = false;
-            }
-            node.hasSUCReturnRoute = await this.assignSUCReturnRoute(nodeId);
-            // 3. delete all return routes so we can assign new ones
+            node.hasSUCReturnRoute || (node.hasSUCReturnRoute = await this.assignSUCReturnRoutes(nodeId));
+            // 3. delete all return routes to get rid of potential priority return routes
             for (let attempt = 1; attempt <= maxAttempts; attempt++) {
                 this.driver.controllerLog.logNode(nodeId, {
                     message: `deleting return routes (attempt ${attempt})...`,
                     direction: "outbound",
                 });
-                try {
-                    await this.driver.sendMessage(new DeleteReturnRouteMessages_1.DeleteReturnRouteRequest(this.driver, { nodeId }));
-                    // this step was successful, continue with the next
+                if (await this.deleteReturnRoutes(nodeId)) {
                     break;
                 }
-                catch (e) {
-                    this.driver.controllerLog.logNode(nodeId, `deleting return routes failed: ${(0, shared_1.getErrorMessage)(e)}`, "warn");
-                }
                 if (attempt === maxAttempts) {
                     this.driver.controllerLog.logNode(nodeId, {
                         message: `failed to delete return routes after ${maxAttempts} attempts, healing failed`,
@@ -2643,22 +2539,18 @@ supported CCs: ${nodeInfo.supportedCCs
                     return false;
                 }
             }
-            // 4. Assign up to 4 return routes for associations, one of which should be the controller
+            // 4. Assign return routes to all association destinations.
             let associatedNodes = [];
-            const maxReturnRoutes = 4;
             try {
                 associatedNodes = (0, arrays_1.distinct)((0, shared_1.flatMap)([...this.getAssociations({ nodeId }).values()], (assocs) => assocs.map((a) => a.nodeId))).sort();
             }
             catch {
                 /* ignore */
             }
-            // Always include ourselves first
+            // One of those should probably be the controller. Not sure if the SUC return route is enough.
             if (!associatedNodes.includes(this._ownNodeId)) {
                 associatedNodes.unshift(this._ownNodeId);
             }
-            if (associatedNodes.length > maxReturnRoutes) {
-                associatedNodes = associatedNodes.slice(0, maxReturnRoutes);
-            }
             this.driver.controllerLog.logNode(nodeId, {
                 message: `assigning return routes to the following nodes:
 ${associatedNodes.join(", ")}`,
@@ -2670,17 +2562,10 @@ ${associatedNodes.join(", ")}`,
                         message: `assigning return route to node ${destinationNodeId} (attempt ${attempt})...`,
                         direction: "outbound",
                     });
-                    try {
-                        await this.driver.sendMessage(new AssignReturnRouteMessages_1.AssignReturnRouteRequest(this.driver, {
-                            nodeId,
-                            destinationNodeId,
-                        }));
+                    if (await this.assignReturnRoutes(nodeId, destinationNodeId)) {
                         // this step was successful, continue with the next
                         break;
                     }
-                    catch (e) {
-                        this.driver.controllerLog.logNode(nodeId, `assigning return route failed: ${(0, shared_1.getErrorMessage)(e)}`, "warn");
-                    }
                     if (attempt === maxAttempts) {
                         this.driver.controllerLog.logNode(nodeId, {
                             message: `failed to assign return route after ${maxAttempts} attempts, healing failed`,
@@ -2715,23 +2600,145 @@ ${associatedNodes.join(", ")}`,
         }));
         return result.isOK();
     }
-    async assignSUCReturnRoute(nodeId) {
+    // After a lot of experimenting, it seems to make sense to document how assigning return routes works in the controller.
+    // Each node has a list of 4 return routes per destination (and probably a separate list for the SUC):
+    // - #0, repeaters..., speed, wakeup
+    // - #1, repeaters..., speed, wakeup
+    // - #2, repeaters..., speed, wakeup
+    // - #3, repeaters..., speed, wakeup
+    //
+    // Empty slots are filled with 0 repeaters, 9.6kbit/s, no wakeup
+    //
+    // Calling assignReturnRoute will assign all 4 slots, some of which may be empty.
+    // Calling deleteReturnRoute will assign an empty route to all 4 slots.
+    //
+    // Priority return routes are indicated by a separate "pointer" byte which tells the node which route is the priority.
+    // Calling assignPriorityReturnRoute will first assign 4 routes, one of which is then marked as priority.
+    // This is not fully understood yet, but it seems that the priority route is actually the last non-empty route.
+    // If the priority byte points to an empty route, it is ignored.
+    //
+    // Calling assignReturnRoute after having assigned a priority return route will not clear that pointer byte. This
+    // means that a previously-assigned priority route can randomly change if assignReturnRoute assigns enough routes.
+    // deleteReturnRoute does also clear the priority byte.
+    /** @deprecated Use {@link assignSUCReturnRoutes} instead */
+    assignSUCReturnRoute(nodeId) {
+        return this.assignSUCReturnRoutes(nodeId);
+    }
+    /**
+     * Instructs the controller to assign static routes from the given end node to the SUC.
+     * This will assign up to 4 routes, depending on the network topology (that the controller knows about).
+     */
+    async assignSUCReturnRoutes(nodeId) {
         this.driver.controllerLog.logNode(nodeId, {
             message: `Assigning SUC return route...`,
             direction: "outbound",
         });
+        // Since there is only one SUC, we can do the right thing here and delete all routes first, which clears any dangling priority return routes.
+        // Afterwards, we'll set up all routes again anyways.
+        await this.deleteSUCReturnRoutes(nodeId);
         try {
             const result = await this.driver.sendMessage(new AssignSUCReturnRouteMessages_1.AssignSUCReturnRouteRequest(this.driver, {
                 nodeId,
             }));
-            return this.handleRouteAssignmentTransmitReport(result, nodeId);
+            const success = this.handleRouteAssignmentTransmitReport(result, nodeId);
+            if (success) {
+                // Custom assigned are no longer valid
+                this.setCustomSUCReturnRoutesCached(nodeId, undefined);
+            }
+            return success;
         }
         catch (e) {
             this.driver.controllerLog.logNode(nodeId, `Assigning SUC return route failed: ${(0, shared_1.getErrorMessage)(e)}`, "error");
             return false;
         }
     }
-    async deleteSUCReturnRoute(nodeId) {
+    /**
+     * Returns which custom static routes are currently assigned from the given end node to the SUC.
+     *
+     * **Note:** This only considers routes that were assigned using {@link assignCustomSUCReturnRoutes}.
+     * If another controller has assigned routes in the meantime, this information may be out of date.
+     */
+    getCustomSUCReturnRoutesCached(nodeId) {
+        return (this.driver.cacheGet(NetworkCache_1.cacheKeys.node(nodeId).customSUCReturnRoutes) ?? []);
+    }
+    setCustomSUCReturnRoutesCached(nodeId, routes) {
+        this.driver.cacheSet(NetworkCache_1.cacheKeys.node(nodeId).customSUCReturnRoutes, routes);
+    }
+    /**
+     * Assigns static routes from the given end node to the SUC. Unlike {@link assignSUCReturnRoutes}, this method assigns
+     * the given routes instead of having the controller calculate them. At most 4 routes can be assigned. If less are
+     * specified, the remaining routes are cleared.
+     *
+     * **Note:** Calling {@link assignSUCReturnRoutes} or {@link deleteSUCReturnRoutes} will override the custom routes.
+     */
+    async assignCustomSUCReturnRoutes(nodeId, routes) {
+        this.driver.controllerLog.logNode(nodeId, {
+            message: `Assigning custom SUC return routes...`,
+            direction: "outbound",
+        });
+        // Since there is only one SUC, we can do the right thing here and delete all routes first, which clears the priority return routes.
+        await this.deleteSUCReturnRoutes(nodeId);
+        let result = true;
+        const MAX_ROUTES = 4;
+        // Keep track of which routes have been assigned
+        const assignedRoutes = this.getCustomSUCReturnRoutesCached(nodeId);
+        while (assignedRoutes.length < MAX_ROUTES) {
+            assignedRoutes.push(core_1.EMPTY_ROUTE);
+        }
+        for (let i = 0; i < MAX_ROUTES; i++) {
+            const route = routes[i] ?? core_1.EMPTY_ROUTE;
+            const isEmpty = (0, core_1.isEmptyRoute)(route);
+            // We are always listening
+            const targetWakeup = false;
+            const cc = new cc_1.ZWaveProtocolCCAssignSUCReturnRoute(this.driver, {
+                nodeId,
+                // Empty routes are marked with a nodeId of 0
+                destinationNodeId: isEmpty ? 0 : this.ownNodeId ?? 1,
+                routeIndex: i,
+                repeaters: route.repeaters,
+                destinationSpeed: route.routeSpeed,
+                destinationWakeUp: (0, cc_1.FLiRS2WakeUpTime)(targetWakeup ?? false),
+            });
+            try {
+                // TODO: add a better method to send ZWaveProtocolCC
+                await this.driver.sendCommand(cc, {
+                    priority: core_1.MessagePriority.MultistepController,
+                    autoEncapsulate: false,
+                    changeNodeStatusOnMissingACK: false,
+                    maxSendAttempts: 1,
+                    useSupervision: false,
+                    transmitOptions: core_1.TransmitOptions.AutoRoute | core_1.TransmitOptions.ACK,
+                });
+                // Remember that this route has been assigned
+                assignedRoutes[i] = route;
+            }
+            catch (e) {
+                this.driver.controllerLog.logNode(nodeId, {
+                    message: `Assigning custom SUC return route #${i} failed`,
+                    direction: "outbound",
+                    level: "warn",
+                });
+                result = false;
+            }
+        }
+        // Trim empty routes off the end. We may end up with empty routes in the middle
+        // if an assignment fails.
+        while (assignedRoutes.length > 0 &&
+            (0, core_1.isEmptyRoute)(assignedRoutes[assignedRoutes.length - 1])) {
+            assignedRoutes.pop();
+        }
+        this.setCustomSUCReturnRoutesCached(nodeId, assignedRoutes);
+        return result;
+    }
+    /** @deprecated use {@link deleteSUCReturnRoutes} instead */
+    deleteSUCReturnRoute(nodeId) {
+        return this.deleteReturnRoutes(nodeId);
+    }
+    /**
+     * Instructs the controller to assign static routes from the given end node to the SUC.
+     * This will assign up to 4 routes, depending on the network topology (that the controller knows about).
+     */
+    async deleteSUCReturnRoutes(nodeId) {
         this.driver.controllerLog.logNode(nodeId, {
             message: `Deleting SUC return route...`,
             direction: "outbound",
@@ -2740,16 +2747,52 @@ ${associatedNodes.join(", ")}`,
             const result = await this.driver.sendMessage(new DeleteSUCReturnRouteMessages_1.DeleteSUCReturnRouteRequest(this.driver, {
                 nodeId,
             }));
-            return this.handleRouteAssignmentTransmitReport(result, nodeId);
+            const success = this.handleRouteAssignmentTransmitReport(result, nodeId);
+            if (success) {
+                // Custom assigned and priority return routes are no longer valid
+                this.setPrioritySUCReturnRouteCached(nodeId, undefined);
+                this.setCustomSUCReturnRoutesCached(nodeId, undefined);
+            }
+            return success;
         }
         catch (e) {
             this.driver.controllerLog.logNode(nodeId, `Deleting SUC return route failed: ${(0, shared_1.getErrorMessage)(e)}`, "error");
             return false;
         }
     }
-    async assignReturnRoute(nodeId, destinationNodeId) {
+    /**
+     * Returns which custom static routes are currently assigned between the given end nodes.
+     *
+     * **Note:** This only considers routes that were assigned using {@link assignCustomReturnRoutes}.
+     * If another controller has assigned routes in the meantime, this information may be out of date.
+     */
+    getCustomReturnRoutesCached(nodeId, destinationNodeId) {
+        return (this.driver.cacheGet(NetworkCache_1.cacheKeys.node(nodeId).customReturnRoutes(destinationNodeId)) ?? []);
+    }
+    setCustomReturnRoutesCached(nodeId, destinationNodeId, routes) {
+        this.driver.cacheSet(NetworkCache_1.cacheKeys.node(nodeId).customReturnRoutes(destinationNodeId), routes);
+    }
+    clearCustomReturnRoutesCached(nodeId) {
+        // This is a bit ugly, but the best we can do right now.
+        for (let dest = 1; dest <= core_1.MAX_NODES; dest++) {
+            this.setCustomReturnRoutesCached(nodeId, dest, undefined);
+        }
+    }
+    /** @deprecated use {@link assignReturnRoutes} instead */
+    assignReturnRoute(nodeId, destinationNodeId) {
+        return this.assignReturnRoutes(nodeId, destinationNodeId);
+    }
+    /**
+     * Instructs the controller to assign static routes between the two given end nodes.
+     * This will assign up to 4 routes, depending on the network topology (that the controller knows about).
+     */
+    async assignReturnRoutes(nodeId, destinationNodeId) {
+        // Make sure this is not misused by passing the controller's node ID
+        if (destinationNodeId === this.ownNodeId) {
+            return this.assignSUCReturnRoutes(nodeId);
+        }
         this.driver.controllerLog.logNode(nodeId, {
-            message: `Assigning return route to node ${destinationNodeId}...`,
+            message: `Assigning return routes to node ${destinationNodeId}...`,
             direction: "outbound",
         });
         try {
@@ -2757,14 +2800,105 @@ ${associatedNodes.join(", ")}`,
                 nodeId,
                 destinationNodeId,
             }));
-            return this.handleRouteAssignmentTransmitReport(result, nodeId);
+            const success = this.handleRouteAssignmentTransmitReport(result, nodeId);
+            if (success) {
+                // Custom assigned are no longer valid
+                this.setCustomReturnRoutesCached(nodeId, destinationNodeId, undefined);
+                // The priority route probably is invalid too now, but it may also point to a random route
+                if (this.hasPriorityReturnRouteCached(nodeId, destinationNodeId) !== false) {
+                    this.setPriorityReturnRouteCached(nodeId, destinationNodeId, core_1.UNKNOWN_STATE);
+                }
+            }
+            return success;
         }
         catch (e) {
-            this.driver.controllerLog.logNode(nodeId, `Assigning return route failed: ${(0, shared_1.getErrorMessage)(e)}`, "error");
+            this.driver.controllerLog.logNode(nodeId, `Assigning return routes failed: ${(0, shared_1.getErrorMessage)(e)}`, "error");
             return false;
         }
     }
-    async deleteReturnRoute(nodeId) {
+    /**
+     * Assigns static routes between the two given end nodes. Unlike {@link assignReturnRoutes}, this method assigns
+     * the given routes instead of having the controller calculate them. At most 4 routes can be assigned. If less are
+     * specified, the remaining routes are cleared.
+     *
+     * **Note:** Calling {@link assignReturnRoutes} or {@link deleteReturnRoutes} will override the custom routes.
+     */
+    async assignCustomReturnRoutes(nodeId, destinationNodeId, routes) {
+        // Make sure this is not misused by passing the controller's node ID
+        if (destinationNodeId === this.ownNodeId) {
+            return this.assignCustomSUCReturnRoutes(nodeId, routes);
+        }
+        this.driver.controllerLog.logNode(nodeId, {
+            message: `Assigning custom return routes to node ${destinationNodeId}...`,
+            direction: "outbound",
+        });
+        let result = true;
+        const MAX_ROUTES = 4;
+        // Keep track of which routes have been assigned
+        const assignedRoutes = this.getCustomReturnRoutesCached(nodeId, destinationNodeId);
+        while (assignedRoutes.length < MAX_ROUTES) {
+            assignedRoutes.push(core_1.EMPTY_ROUTE);
+        }
+        for (let i = 0; i < MAX_ROUTES; i++) {
+            const route = routes[i] ?? core_1.EMPTY_ROUTE;
+            const isEmpty = (0, core_1.isEmptyRoute)(route);
+            const targetWakeup = !isEmpty
+                ? this.nodes.get(destinationNodeId)?.isFrequentListening
+                : undefined;
+            const cc = new cc_1.ZWaveProtocolCCAssignReturnRoute(this.driver, {
+                nodeId,
+                // Empty routes are marked with a nodeId of 0
+                destinationNodeId: isEmpty ? 0 : destinationNodeId,
+                routeIndex: i,
+                repeaters: route.repeaters,
+                destinationSpeed: route.routeSpeed,
+                destinationWakeUp: (0, cc_1.FLiRS2WakeUpTime)(targetWakeup ?? false),
+            });
+            try {
+                // TODO: add a better method to send ZWaveProtocolCC
+                await this.driver.sendCommand(cc, {
+                    priority: core_1.MessagePriority.MultistepController,
+                    autoEncapsulate: false,
+                    changeNodeStatusOnMissingACK: false,
+                    maxSendAttempts: 1,
+                    useSupervision: false,
+                    transmitOptions: core_1.TransmitOptions.AutoRoute | core_1.TransmitOptions.ACK,
+                });
+                // Remember that this route has been assigned
+                assignedRoutes[i] = route;
+            }
+            catch (e) {
+                this.driver.controllerLog.logNode(nodeId, {
+                    message: `Assigning custom return route #${i} failed`,
+                    direction: "outbound",
+                    level: "warn",
+                });
+                result = false;
+            }
+        }
+        // Trim empty routes off the end. We may end up with empty routes in the middle
+        // if an assignment fails.
+        while (assignedRoutes.length > 0 &&
+            (0, core_1.isEmptyRoute)(assignedRoutes[assignedRoutes.length - 1])) {
+            assignedRoutes.pop();
+        }
+        this.setCustomReturnRoutesCached(nodeId, destinationNodeId, assignedRoutes);
+        // The priority route is probably invalid now, but it may also point to a random route
+        if (this.hasPriorityReturnRouteCached(nodeId, destinationNodeId) !==
+            false) {
+            this.setPriorityReturnRouteCached(nodeId, destinationNodeId, core_1.UNKNOWN_STATE);
+        }
+        return result;
+    }
+    /** @deprecated use {@link deleteReturnRoutes} instead */
+    deleteReturnRoute(nodeId) {
+        return this.deleteReturnRoutes(nodeId);
+    }
+    /**
+     * Instructs the controller to delete all static routes between the given node and all
+     * other end nodes, including the priority return routes.
+     */
+    async deleteReturnRoutes(nodeId) {
         this.driver.controllerLog.logNode(nodeId, {
             message: `Deleting all return routes...`,
             direction: "outbound",
@@ -2773,7 +2907,13 @@ ${associatedNodes.join(", ")}`,
             const result = await this.driver.sendMessage(new DeleteReturnRouteMessages_1.DeleteReturnRouteRequest(this.driver, {
                 nodeId,
             }));
-            return this.handleRouteAssignmentTransmitReport(result, nodeId);
+            const success = this.handleRouteAssignmentTransmitReport(result, nodeId);
+            if (success) {
+                // All custom assigned routes are no longer valid
+                this.clearPriorityReturnRoutesCached(nodeId);
+                this.clearCustomReturnRoutesCached(nodeId);
+            }
+            return success;
         }
         catch (e) {
             this.driver.controllerLog.logNode(nodeId, `Deleting return routes failed: ${(0, shared_1.getErrorMessage)(e)}`, "error");
@@ -2788,6 +2928,10 @@ ${associatedNodes.join(", ")}`,
      * @param routeSpeed The transmission speed to use for the route
      */
     async assignPriorityReturnRoute(nodeId, destinationNodeId, repeaters, routeSpeed) {
+        // Make sure this is not misused by passing the controller's node ID
+        if (destinationNodeId === this.ownNodeId) {
+            return this.assignPrioritySUCReturnRoute(nodeId, repeaters, routeSpeed);
+        }
         this.driver.controllerLog.logNode(nodeId, {
             message: `Assigning priority return route to node ${destinationNodeId}...`,
             direction: "outbound",
@@ -2799,13 +2943,45 @@ ${associatedNodes.join(", ")}`,
                 repeaters,
                 routeSpeed,
             }));
-            return this.handleRouteAssignmentTransmitReport(result, nodeId);
+            const success = this.handleRouteAssignmentTransmitReport(result, nodeId);
+            if (success) {
+                // Update the cached priority route
+                this.setPriorityReturnRouteCached(nodeId, destinationNodeId, {
+                    repeaters,
+                    routeSpeed,
+                });
+            }
+            return success;
         }
         catch (e) {
             this.driver.controllerLog.logNode(nodeId, `Assigning priority return route failed: ${(0, shared_1.getErrorMessage)(e)}`, "error");
             return false;
         }
     }
+    hasPriorityReturnRouteCached(nodeId, destinationNodeId) {
+        const ret = this.driver.cacheGet(NetworkCache_1.cacheKeys.node(nodeId).priorityReturnRoute(destinationNodeId));
+        if (ret === core_1.UNKNOWN_STATE)
+            return core_1.UNKNOWN_STATE;
+        return ret !== undefined;
+    }
+    setPriorityReturnRouteCached(nodeId, destinationNodeId, route) {
+        this.driver.cacheSet(NetworkCache_1.cacheKeys.node(nodeId).priorityReturnRoute(destinationNodeId), route);
+    }
+    clearPriorityReturnRoutesCached(nodeId) {
+        // This is a bit ugly, but the best we can do right now.
+        for (let dest = 1; dest <= core_1.MAX_NODES; dest++) {
+            this.setPriorityReturnRouteCached(nodeId, dest, undefined);
+        }
+    }
+    /**
+     * Returns which priority route is currently assigned between the given end nodes.
+     *
+     * **Note:** This is using cached information, since there's no way to query priority routes from a node.
+     * If another controller has assigned routes in the meantime, this information may be out of date.
+     */
+    getPriorityReturnRouteCached(nodeId, destinationNodeId) {
+        return this.driver.cacheGet(NetworkCache_1.cacheKeys.node(nodeId).priorityReturnRoute(destinationNodeId));
+    }
     /**
      * Assigns a priority route from an end node to the SUC. This route will always be used for the first transmission attempt.
      * @param nodeId The ID of the end node for which to assign the route
@@ -2823,13 +2999,36 @@ ${associatedNodes.join(", ")}`,
                 repeaters,
                 routeSpeed,
             }));
-            return this.handleRouteAssignmentTransmitReport(result, nodeId);
+            const success = this.handleRouteAssignmentTransmitReport(result, nodeId);
+            if (success) {
+                // Update the cached priority route
+                this.setPrioritySUCReturnRouteCached(nodeId, {
+                    repeaters,
+                    routeSpeed,
+                });
+                // The command above assigns a full set of new routes, so
+                // custom SUC return routes are no longer valid
+                this.setCustomSUCReturnRoutesCached(nodeId, undefined);
+            }
+            return success;
         }
         catch (e) {
             this.driver.controllerLog.logNode(nodeId, `Assigning priority SUC return route failed: ${(0, shared_1.getErrorMessage)(e)}`, "error");
             return false;
         }
     }
+    setPrioritySUCReturnRouteCached(nodeId, route) {
+        this.driver.cacheSet(NetworkCache_1.cacheKeys.node(nodeId).prioritySUCReturnRoute, route);
+    }
+    /**
+     * Returns which priority route is currently assigned from the given end node to the SUC.
+     *
+     * **Note:** This is using cached information, since there's no way to query priority routes from a node.
+     * If another controller has assigned routes in the meantime, this information may be out of date.
+     */
+    getPrioritySUCReturnRouteCached(nodeId) {
+        return this.driver.cacheGet(NetworkCache_1.cacheKeys.node(nodeId).prioritySUCReturnRoute);
+    }
     handleRouteAssignmentTransmitReport(msg, nodeId) {
         switch (msg.transmitStatus) {
             case core_1.TransmitStatus.OK:
@@ -2980,7 +3179,7 @@ ${associatedNodes.join(", ")}`,
         // Nodes need a return route to be able to send commands to other nodes
         const destinationNodeIDs = (0, arrays_1.distinct)(destinations.map((d) => d.nodeId)).filter((id) => id !== this.ownNodeId);
         for (const id of destinationNodeIDs) {
-            await this.assignReturnRoute(source.nodeId, id);
+            await this.assignReturnRoutes(source.nodeId, id);
         }
     }
     /**
@@ -3243,6 +3442,35 @@ ${associatedNodes.join(", ")}`,
         }
         return result.maxPayloadSize;
     }
+    /**
+     * Instructs a node to (re-)discover its neighbors.
+     *
+     * **WARNING:** On some controllers, this can cause new SUC return routes to be assigned.
+     *
+     * @returns `true` if the update was successful and the new neighbors can be retrieved using
+     * {@link getKnownNodeNeighbors}. `false` if the update failed.
+     */
+    async discoverNodeNeighbors(nodeId) {
+        // TODO: Consider making this not block the send queue.
+        // However, I haven't actually seen a UpdateStarted callback in the wild,
+        // so we don't know if that would even work.
+        // During inclusion, the timeout is mainly required for the node to detect all neighbors
+        // We do the same here, so we just reuse the timeout
+        const discoveryTimeout = (0, AddNodeToNetworkRequest_1.computeNeighborDiscoveryTimeout)(this.driver, 
+        // Controllers take longer, just assume the worst case here
+        core_1.NodeType.Controller);
+        const resp = await this.driver.sendMessage(new RequestNodeNeighborUpdateMessages_1.RequestNodeNeighborUpdateRequest(this.driver, {
+            nodeId,
+            discoveryTimeout,
+        }));
+        const success = resp.updateStatus === RequestNodeNeighborUpdateMessages_1.NodeNeighborUpdateStatus.UpdateDone;
+        if (success) {
+            // Not sure why, but Zniffer traces show that a node neighbor update can cause the controller to
+            // also do AssignSUCReturnRoute. As a result, we need to invalidate our route cache.
+            this.setCustomSUCReturnRoutesCached(nodeId, undefined);
+        }
+        return success;
+    }
     /**
      * Returns the known list of neighbors for a node
      */
@@ -4199,8 +4427,7 @@ ${associatedNodes.join(", ")}`,
         }
     }
 };
-ZWaveController = __decorate([
+exports.ZWaveController = ZWaveController = __decorate([
     (0, shared_1.Mixin)([ControllerStatistics_1.ControllerStatisticsHost])
 ], ZWaveController);
-exports.ZWaveController = ZWaveController;
 //# sourceMappingURL=Controller.js.map