smart-home-engine 1.20.1 → 1.20.3

package/dist/web/assets/{tsMode-BNcOSQVq.js → tsMode-DBmTyMNv.js}

@@ -1,4 +1,4 @@
-import{m as O}from"./monaco-langs-Dt8a9eeo.js";import{t as I}from"./index-DxR31sxM.js";/*!-----------------------------------------------------------------------------
+import{m as O}from"./monaco-langs-Dt8a9eeo.js";import{t as I}from"./index-BbXC7eVn.js";/*!-----------------------------------------------------------------------------
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Version: 0.52.2(404545bded1df6ffa41ea0af4e8ddb219018c6c1)
  * Released under the MIT license

package/dist/web/index.html

@@ -172,10 +172,10 @@
                 }
             })();
         </script>
-      <script type="module" crossorigin src="/assets/index-DxR31sxM.js"></script>
+      <script type="module" crossorigin src="/assets/index-BbXC7eVn.js"></script>
       <link rel="modulepreload" crossorigin href="/assets/monaco-langs-Dt8a9eeo.js">
       <link rel="stylesheet" crossorigin href="/assets/monaco-langs-DyX1CsEw.css">
-      <link rel="stylesheet" crossorigin href="/assets/index-CjRDTePT.css">
+      <link rel="stylesheet" crossorigin href="/assets/index-B4M4MeEk.css">
     </head>
     <body>
         <div id="app"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "smart-home-engine",
-    "version": "1.20.1",
+    "version": "1.20.3",
     "description": "Node.js based script runner for use in MQTT based Smart Home environments",
     "main": "src/index.js",
     "scripts": {

package/src/index.js

@@ -498,6 +498,28 @@ if (config.url) {
 
         if (shedb.handleMqttMessage(topic, payload)) return;
 
+        // An empty payload deletes the topic from the state store (mqtt-smarthome
+        // convention; also how a retained message is cleared per MQTT spec). The
+        // retain flag cannot be used to detect this: MQTT 3.1.1 brokers clear it
+        // when forwarding to established subscriptions, so a retained-clear
+        // arrives here as a plain empty message. Previously an empty payload was
+        // stored as { val: NaN }, so the MQTT tab kept showing cleared topics.
+        // Subscription callbacks are still dispatched (empty publishes are also
+        // used as plain triggers) with val '' — only the stored state is dropped.
+        if (payload.length === 0) {
+            const emptyOld = store.getObject('mqtt::' + topic) || {};
+            if (store.delete('mqtt::' + topic)) {
+                log.debug('empty payload, removed topic from state store:', topic);
+            }
+            const delArr = topic.split('/');
+            if (delArr[0] === config.variablePrefix && delArr[1] === 'status') {
+                store.delete('var::' + delArr.slice(2).join('/'));
+            }
+            const ts = new Date().getTime();
+            stateChange(topic, { val: '', ts, lc: ts }, emptyOld, msg);
+            return;
+        }
+
         const state = require('./lib/parse-payload')(payload);
 
         const topicArr = topic.split('/');

package/src/lib/redis.js

@@ -63,6 +63,13 @@ async function init({ url, store, log }) {
         });
     });
 
+    // Write-through: StateStore deletions (e.g. cleared retained messages) → hdel
+    store.on('delete', (key) => {
+        client.hdel('she:state', key).catch((err) => {
+            log.error('redis: hdel failed:', err.message);
+        });
+    });
+
     log.info('redis: connected', url);
 }
 

package/src/lib/state-store.js

@@ -10,6 +10,7 @@
  *
  * Events:
  *   'change' (key, val, obj, prevObj)
+ *   'delete' (key, prevObj)
  */
 
 const { EventEmitter } = require('events');
@@ -47,6 +48,21 @@ class StateStore extends EventEmitter {
         this.emit('change', key, obj.val, obj, prev);
     }
 
+    /**
+     * Remove a key from the store (e.g. when a retained MQTT message is
+     * deleted via an empty retained publish). Emits 'delete' (key, prevObj)
+     * when the key existed; a no-op otherwise.
+     * @param {string} key
+     * @returns {boolean} true when the key existed and was removed
+     */
+    delete(key) {
+        const prev = this._map.get(key);
+        if (prev === undefined) return false;
+        this._map.delete(key);
+        this.emit('delete', key, prev);
+        return true;
+    }
+
     /**
      * @param {string} key
      * @returns {*} the val of the stored state, or undefined

package/src/matter/controller.js

@@ -9,7 +9,11 @@
  * All nodeIds are exposed as decimal strings (BigInt serialization boundary).
  */
 
-const { Environment, ServerNode, ControllerBehavior } = require('@matter/main');
+const { Environment, ServerNode, ControllerBehavior, Logger, LogLevel, LogFormat } = require('@matter/main');
+
+// Upper bound for a commissioning attempt — matter.js has internal retries that
+// can keep an HTTP request (and the pairing wizard) hanging for a very long time.
+const COMMISSION_TIMEOUT_MS = 120000;
 
 /** @type {import('@matter/main').ServerNode | null} */
 let _server = null;
@@ -105,6 +109,17 @@ async function init(storagePath, log, broadcastFn) {
     if (_server) throw new Error('Matter controller already started');
     _log = log;
 
+    // Route matter.js's own diagnostics into the daemon logger so commissioning
+    // problems (discovery, PASE failures, retries) are visible in the Logs tab —
+    // by default matter.js writes straight to stdout, bypassing she's logging.
+    Logger.format = LogFormat.PLAIN;
+    Logger.level = LogLevel.INFO;
+    Logger.destinations.default.write = (text, message) => {
+        if (message.level >= LogLevel.ERROR) _log.error('matter.js:', text);
+        else if (message.level === LogLevel.WARN) _log.warn('matter.js:', text);
+        else _log.debug('matter.js:', text);
+    };
+
     // Configure storage before anything else touches StorageService
     Environment.default.vars.set('storage.path', storagePath);
 
@@ -240,6 +255,44 @@ function listPaired() {
  */
 async function commission(options) {
     if (!_server) throw new Error('Matter controller not started');
+
+    // Accept QR-code payloads ("MT:...") — matter.js's pairingCode option only
+    // decodes 11/21-digit manual pairing codes, so decode QR payloads here.
+    if (typeof options.pairingCode === 'string' && options.pairingCode.trim().toUpperCase().startsWith('MT:')) {
+        const { QrPairingCodeCodec } = require('@matter/types');
+        const [decoded] = QrPairingCodeCodec.decode(options.pairingCode.trim());
+        const { pairingCode: _pc, ...rest } = options;
+        options = { ...rest, passcode: decoded.passcode, discriminator: decoded.discriminator };
+        _log.debug('matter: decoded QR pairing code, discriminator', decoded.discriminator);
+    }
+
+    const label = options.pairingCode !== undefined ? 'pairing code' : `passcode${options.discriminator !== undefined ? ' + discriminator ' + options.discriminator : ''}`;
+    _log.info(`matter: commissioning start (${label}${options.discoveryAddress ? ', direct address ' + options.discoveryAddress : ''})`);
+    let timer;
+    try {
+        const nodeId = await Promise.race([
+            _commissionInner(options),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(
+                    () =>
+                        reject(
+                            new Error(`commissioning timed out after ${COMMISSION_TIMEOUT_MS / 1000} s — check that the pairing window is still open and the device is reachable`),
+                        ),
+                    COMMISSION_TIMEOUT_MS,
+                );
+            }),
+        ]);
+        _log.info('matter: commissioning succeeded, nodeId', nodeId);
+        return nodeId;
+    } catch (err) {
+        _log.error('matter: commissioning failed:', err.message);
+        throw err;
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+async function _commissionInner(options) {
     const { discoveryAddress, ...commissionOpts } = options;
     let clientNode;
     if (discoveryAddress) {
@@ -273,6 +326,11 @@ async function commission(options) {
     if (!addr) throw new Error('Commission succeeded but node has no peerAddress');
     const nodeId = _nodeIdStr(addr.nodeId);
     _subscribeNodeLifecycle(clientNode, nodeId);
+    // A freshly commissioned node is already online, so the lifecycle 'online'
+    // event (the other place this is wired) will not fire again — attach the
+    // attribute watchers now or the node stays without live updates until the
+    // next daemon restart.
+    _broadcastNodeAttributes(clientNode, nodeId);
     _broadcast?.({ type: 'matter:deviceList', devices: listPaired() });
     return nodeId;
 }
@@ -341,11 +399,77 @@ async function getAttribute(nodeId, endpointId, clusterName, attrName) {
     return clusterState[attrName];
 }
 
+/**
+ * Write a single attribute value (a remote write for client nodes — the
+ * attribute must be writable per the device's Matter data model).
+ *
+ * @param {string}  nodeId
+ * @param {number}  endpointId
+ * @param {string}  clusterName  camelCase cluster name, e.g. "basicInformation"
+ * @param {string}  attrName     camelCase attribute name, e.g. "nodeLabel"
+ * @param {*}       value
+ * @returns {Promise<void>}
+ */
+async function setAttribute(nodeId, endpointId, clusterName, attrName, value) {
+    const node = _findClientNode(nodeId);
+    const endpoint = _resolveEndpoint(node, endpointId);
+    await endpoint.set({ [_clusterName(clusterName)]: { [attrName]: value } });
+}
+
+/**
+ * Rename a device by writing basicInformation.nodeLabel on the root endpoint —
+ * the Matter-standard writable user label (max 32 chars), persisted on the
+ * device itself. she prefers nodeLabel over productName wherever names are
+ * shown or matched, so the new name is immediately usable in scripts.
+ *
+ * @param {string} nodeId
+ * @param {string} name
+ * @returns {Promise<void>}
+ */
+async function rename(nodeId, name) {
+    await setAttribute(nodeId, 0, 'basicInformation', 'nodeLabel', String(name));
+    _log?.info(`matter: renamed node ${nodeId} to "${name}"`);
+    _broadcast?.({ type: 'matter:deviceList', devices: listPaired() });
+}
+
 // ── Commands ──────────────────────────────────────────────────────────────────
 
+/**
+ * Best-effort: list the mandatory field names (camelCase) of a command's
+ * request schema. Handles both shapes matter.js uses: a TLV ObjectSchema
+ * (fieldDefinitions, camelCase keys) and a CommandModel (children with
+ * PascalCase names and conformance flags). Returns [] when unresolvable.
+ * @param {object} cluster      the behavior's cluster definition
+ * @param {string} commandName
+ * @returns {string[]}
+ */
+function _mandatoryCommandFields(cluster, commandName) {
+    try {
+        const cmd = cluster?.commands?.[commandName];
+        const schema = cmd?.schema ?? cmd?.requestSchema;
+        if (schema?.fieldDefinitions) {
+            return Object.entries(schema.fieldDefinitions)
+                .filter(([, def]) => !def?.optional)
+                .map(([name]) => name);
+        }
+        if (schema?.children) {
+            return [...schema.children].filter((c) => c.effectiveConformance?.isMandatory !== false).map((c) => c.name.charAt(0).toLowerCase() + c.name.slice(1));
+        }
+    } catch {
+        /* best-effort — fall through */
+    }
+    return [];
+}
+
 /**
  * Invoke a cluster command.
  *
+ * Mandatory boilerplate fields that scripts rarely care about are filled with
+ * neutral defaults when omitted: optionsMask/optionsOverride → {} (bitmap 0,
+ * "obey the device's options") and transitionTime → 0 (instant). So
+ * she.matter.send('x', 1, 'levelControl', 'moveToLevel', { level: 128 }) works
+ * without spelling out the full Matter command schema.
+ *
  * @param {string}  nodeId
  * @param {number}  endpointId
  * @param {string}  clusterName  camelCase cluster name, e.g. "onOff"
@@ -363,10 +487,17 @@ async function sendCommand(nodeId, endpointId, clusterName, commandName, args) {
         if (!clusterAgent) throw new Error(`Cluster "${clusterName}" not found on endpoint ${endpointId}`);
         const cmd = clusterAgent[commandName];
         if (typeof cmd !== 'function') throw new Error(`Command "${commandName}" not found in cluster "${clusterName}"`);
-        // Only pass args when the caller actually provided non-empty args.
+        // Fill neutral defaults for mandatory boilerplate fields the caller omitted.
+        const merged = args !== undefined && args !== null && typeof args === 'object' ? { ...args } : {};
+        for (const field of _mandatoryCommandFields(clusterAgent.cluster, commandName)) {
+            if (merged[field] !== undefined) continue;
+            if (field === 'optionsMask' || field === 'optionsOverride') merged[field] = {};
+            else if (field === 'transitionTime') merged[field] = 0;
+        }
+        // Only pass args when there is actually a payload.
         // Void commands (e.g. onOff.off) fail TLV validation if passed an empty object.
-        const hasArgs = args !== undefined && args !== null && Object.keys(args).length > 0;
-        return hasArgs ? cmd.call(clusterAgent, args) : cmd.call(clusterAgent);
+        const hasArgs = Object.keys(merged).length > 0;
+        return hasArgs ? cmd.call(clusterAgent, merged) : cmd.call(clusterAgent);
     });
 }
 
@@ -414,7 +545,14 @@ function _broadcastNodeAttributes(node, nodeId) {
                 }
             }
         }
-        _log?.info(`matter: watching ${count} attribute(s) on node ${nodeId}`);
+        if (count === 0) {
+            // Endpoint structure not populated yet (e.g. right after commissioning)
+            // — drop the guard so the next lifecycle 'online' event retries.
+            _attrBroadcastNodes.delete(nodeId);
+            _log?.debug(`matter: no watchable attributes on node ${nodeId} yet, will retry on next online event`);
+        } else {
+            _log?.info(`matter: watching ${count} attribute(s) on node ${nodeId}`);
+        }
     } catch (err) {
         _attrBroadcastNodes.delete(nodeId); // allow retry
         _log?.warn(`matter: attribute broadcast setup failed for ${nodeId}: ${err.message}`);
@@ -533,6 +671,8 @@ module.exports = {
     getEndpoints,
     getDeviceSubtitle,
     getAttribute,
+    setAttribute,
+    rename,
     sendCommand,
     subscribeAttribute,
     unsubscribe,

package/src/web/matter-api.js

@@ -58,6 +58,25 @@ router.post('/commission', async (req, res) => {
     }
 });
 
+// POST /she/matter/devices/:nodeId/rename — { name } → writes basicInformation.nodeLabel
+router.post('/devices/:nodeId/rename', async (req, res) => {
+    if (!isReady()) return notReady(res);
+    const name = req.body?.name;
+    if (typeof name !== 'string' || !name.trim()) {
+        return res.status(400).json({ error: 'body must contain a non-empty name' });
+    }
+    if (name.trim().length > 32) {
+        return res.status(400).json({ error: 'name must be at most 32 characters (Matter nodeLabel limit)' });
+    }
+    try {
+        await getController().rename(req.params.nodeId, name.trim());
+        res.json({ ok: true });
+    } catch (err) {
+        if (err.message.includes('not found')) return res.status(404).json({ error: err.message });
+        res.status(500).json({ error: err.message });
+    }
+});
+
 // GET /she/matter/devices/:nodeId — node detail
 router.get('/devices/:nodeId', (req, res) => {
     if (!isReady()) return notReady(res);

package/src/web/mqtt-api.js

@@ -12,7 +12,8 @@
  * (or null when no broker is configured).
  *
  * State changes for mqtt:: keys are automatically broadcast to WebSocket clients
- * as { type: 'mqtt', topic, val, ts }.
+ * as { type: 'mqtt', topic, val, ts }; deletions (retained message cleared via
+ * an empty retained publish) as { type: 'mqtt', topic, deleted: true, ts }.
  */
 
 const express = require('express');
@@ -43,6 +44,12 @@ function init(store, getMqttClient) {
             broadcastBrokerLog(topic.slice('$SYS/broker/log/'.length), String(obj.val), obj.ts);
         }
     });
+
+    // Forward deletions (retained message cleared) so clients drop the topic
+    store.on('delete', (key) => {
+        if (!key.startsWith('mqtt::')) return;
+        broadcast({ type: 'mqtt', topic: key.slice(6), deleted: true, ts: Date.now() });
+    });
 }
 
 // GET /she/mqtt/state — sorted snapshot of all retained MQTT topic values