node-red-contrib-room-tools 1.9.1 → 1.9.4

package/panel-momentary.js

@@ -0,0 +1,93 @@
+const { resolveBoundCommand } = require('./control-bound-protocol')
+const crypto = require('node:crypto')
+
+function createMomentaryControls ({ routes, send, onError = () => {}, leaseMs = 3000,
+  now = Date.now, setTimer = setTimeout, clearTimer = clearTimeout }) {
+  const records = new Map()
+  const epoch = crypto.randomBytes(16).toString('hex')
+  let timer = null
+  let closed = false
+  const destination = command => JSON.stringify([command.device, command.path])
+  const occupied = key => [...records.values()].some(record => record.active && record.target === key)
+
+  function release (record) {
+    if (!record.active) return
+    record.active = false
+    if (!occupied(record.target)) {
+      try { send(record.off, record.identity) } catch (error) { onError(error) }
+    }
+  }
+  function sweep () {
+    const time = now()
+    for (const [key, record] of records) {
+      if (record.active && record.until <= time) release(record)
+      if (record.identity.expiry <= time) { release(record); records.delete(key) }
+    }
+  }
+  function schedule () {
+    if (timer) clearTimer(timer)
+    timer = null
+    const deadlines = [...records.values()].filter(record => record.active).map(record => record.until)
+    if (closed || !deadlines.length) return
+    timer = setTimer(() => { timer = null; sweep(); schedule() }, Math.max(1, Math.min(...deadlines) - now()))
+    timer.unref?.()
+  }
+  function handle (message, identity) {
+    if (closed) throw Error('Momentary controls unavailable')
+    const request = message?._controlPanel
+    const hold = request?.hold
+    const route = routes.get(request?.id)
+    if (route?.control.buttonBehavior !== 'momentary' || route.control.mode !== 'both') {
+      throw Error('This control is not a momentary button')
+    }
+    if (!hold || hold.epoch !== epoch || !/^[A-Za-z0-9_-]{1,64}$/.test(hold.client || '') ||
+      !Number.isSafeInteger(hold.seq) || hold.seq < 1 ||
+      !['start', 'renew', 'release'].includes(hold.action) ||
+      request.value !== (hold.action !== 'release') ||
+      typeof identity?.token !== 'string' || !Number.isFinite(identity.expiry) || identity.expiry <= now()) {
+      throw Error('Invalid momentary command')
+    }
+    const command = resolveBoundCommand(routes, message)
+    sweep()
+    const key = JSON.stringify([identity.token, request.id, hold.client])
+    let record = records.get(key)
+    if (!record) {
+      if (records.size >= 1024) throw Error('Momentary client limit reached')
+      record = { seq: 0, active: false, target: destination(command), identity,
+        off: resolveBoundCommand(routes, { _controlPanel: { kind: 'command', id: request.id, value: false, final: true } }) }
+      records.set(key, record)
+    }
+    // Keep the sequence watermark after release: a delayed press must not re-enable the device.
+    if (hold.seq <= record.seq) return { held: record.active }
+    record.seq = hold.seq
+    if (hold.action === 'release') release(record)
+    else if (hold.action === 'start') {
+      const alreadyHeld = occupied(record.target)
+      if (!alreadyHeld) send(command, identity)
+      record.active = true
+      record.until = Math.min(now() + leaseMs, identity.expiry)
+    } else if (record.active) record.until = Math.min(now() + leaseMs, identity.expiry)
+    schedule()
+    return { held: record.active }
+  }
+  return {
+    epoch,
+    handle,
+    isHeld (command) { sweep(); return occupied(destination(command)) },
+    releaseSession (token) {
+      for (const [key, record] of records) {
+        if (record.identity.token === token) { release(record); records.delete(key) }
+      }
+      schedule()
+    },
+    close () {
+      closed = true
+      if (timer) clearTimer(timer)
+      timer = null
+      for (const record of records.values()) release(record)
+      records.clear()
+    }
+  }
+}
+
+module.exports = { createMomentaryControls }

package/panel-telemetry-send.js

@@ -0,0 +1,13 @@
+function emitTelemetryFrame (event, frame, subscribers) {
+  const sockets = [...subscribers.values()].map(entry => entry.socket)
+  if (!sockets.length) return
+  const namespace = sockets[0].nsp
+  // A namespace broadcast encodes once, but targets only authenticated socket IDs.
+  if (typeof namespace?.to === 'function' && sockets.every(socket => socket.nsp === namespace)) {
+    namespace.to(sockets.map(socket => socket.id)).volatile.emit(event, frame)
+  } else {
+    for (const socket of sockets) socket.volatile.emit(event, frame)
+  }
+}
+
+module.exports = { emitTelemetryFrame }

package/panel-template-instrumentation.js

@@ -341,6 +341,7 @@ function inspectTemplate (format) {
           (enabledBooleanProp(node, ['indeterminate']) || hasAttribute(node, ['min', 'max', 'step']))
         const candidate = {
           locator, adapter,
+          ...(adapter === 'switch' && node.tag.toLowerCase() === 'button' ? { button: true } : {}),
           ...(component ? { component } : {}),
           ...(activeRepeat ? { repeat: activeRepeat } : {}),
           label: attribute(node, 'aria-label') || attribute(node, 'label') || attribute(node, 'title') ||

package/panel-visual-bindings.js

@@ -1,11 +1,20 @@
 const { inspectTemplate } = require('./panel-template-instrumentation')
-const { compatibleTarget, controlTypeForAdapter, targetMeta } = require('./control-type-model')
+const { compatibleTarget, controlTypeForAdapter, targetMeta, bindingModes } = require('./control-type-model')
 const { meterRoute } = require('./meter-route')
 const { xySeriesRoute } = require('./xy-series-route')
 
 const ID = /^[A-Za-z][A-Za-z0-9._/-]{0,127}$/
 const INSTANCE_KEY = /^[A-Za-z0-9._:/-]{1,160}$/
-const MODES = new Set(['read', 'write', 'both'])
+
+function buttonBehavior (entry, candidate) {
+  const behavior = entry.buttonBehavior ?? 'toggle'
+  if (!['toggle', 'momentary'].includes(behavior) ||
+    (entry.buttonBehavior !== undefined && !candidate.button) ||
+    (behavior === 'momentary' && entry.mode !== 'both')) {
+    throw new Error('Button behavior requires a boolean button; momentary buttons require both mode')
+  }
+  return behavior
+}
 
 function targetKey (candidate, entry) {
   if (!candidate.repeat) return candidate.locator
@@ -40,10 +49,13 @@ function visualRoutes (config) {
       throw new Error(`Visual control moved or became ambiguous: ${id}`)
     }
     const bindingKey = targetKey(candidate, entry)
+    const behavior = buttonBehavior(entry, candidate)
+    if (behavior === 'momentary' && !['mute', 'power'].includes(entry.type)) {
+      throw new Error('Momentary buttons require a boolean control type')
+    }
     if (usedLocators.has(bindingKey)) throw new Error(`Duplicate visual control locator: ${id}`)
     usedLocators.add(bindingKey)
-    if (!MODES.has(entry.mode) || !entry.type || !entry.label ||
-      (['meter', 'xy-series', 'text-display'].includes(entry.adapter) && entry.mode !== 'read')) {
+    if (!bindingModes(entry.adapter).includes(entry.mode) || !entry.type || !entry.label) {
       throw new Error(`Invalid visual binding settings: ${id}`)
     }
     if (entry.readMeta?.meter) {
@@ -62,6 +74,7 @@ function visualRoutes (config) {
     routes.set(id, {
       control: { id, type: entry.type, mode: entry.mode, label: entry.label,
         adapter: entry.adapter, locator: entry.locator,
+        ...(candidate.button ? { buttonBehavior: behavior } : {}),
         ...(candidate.repeat ? { instanceKey: entry.instanceKey } : {}) },
       binding: entry
     })
@@ -78,15 +91,17 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
   const used = new Set()
   const usedLocators = new Set()
   const models = new Map()
+  const targetIndexes = new Map()
   for (const raw of entries) {
     if (!raw || !ID.test(raw.id) || used.has(raw.id)) throw new Error('Control IDs must be unique and valid')
     used.add(raw.id)
     const candidate = candidates.get(raw.locator)
     if (!candidate || candidate.adapter !== raw.adapter) throw new Error(`Control changed: ${raw.id}`)
     const bindingKey = targetKey(candidate, raw)
+    const behavior = buttonBehavior(raw, candidate)
     if (usedLocators.has(bindingKey)) throw new Error(`One element cannot have two bindings: ${raw.id}`)
     usedLocators.add(bindingKey)
-    if (!MODES.has(raw.mode) || (['meter', 'xy-series', 'text-display'].includes(raw.adapter) && raw.mode !== 'read')) {
+    if (!bindingModes(raw.adapter).includes(raw.mode)) {
       throw new Error(`Invalid binding mode: ${raw.id}`)
     }
     if (typeof raw.label !== 'string' || !raw.label.trim() || raw.label.length > 80) {
@@ -95,7 +110,8 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
     if (!knownDevices.has(raw.device)) throw new Error(`Unknown device: ${raw.id}`)
     const targets = targetsByDevice.get(raw.device)
     if (!targets) throw new Error(`Device catalog unavailable: ${raw.device}`)
-    const byPath = new Map(targets.map(target => [target.path, target]))
+    if (!targetIndexes.has(raw.device)) targetIndexes.set(raw.device, new Map(targets.map(target => [target.path, target])))
+    const byPath = targetIndexes.get(raw.device)
     const write = raw.mode === 'read' ? null : byPath.get(raw.writePath)
     const read = raw.mode === 'write' ? null : byPath.get(raw.readPath)
     if ((raw.mode !== 'read' && !write) || (raw.mode !== 'write' && !read)) {
@@ -115,13 +131,15 @@ function validatedVisualBindings ({ format, entries, devices, targetsByDevice })
       const identity = JSON.stringify([raw.device, read?.path, write?.path])
       const modelKey = candidate.repeat ? `${candidate.model}#${raw.instanceKey}` : candidate.model
       const previous = models.get(modelKey)
-      if (previous && (read?.meter || previous.meter) && previous.identity !== identity) {
-        throw Error(`Meter model "${candidate.model}" is already used by another binding; use a separate Vue model for the meter. Meter and volume controls must not share a model`)
+      const realtime = Boolean(read?.meter || read?.xySeries)
+      if (previous && (realtime || previous.realtime) && previous.identity !== identity) {
+        throw Error(`Realtime model "${candidate.model}" is already used by another binding; use a separate Vue model for each independent telemetry target`)
       }
-      models.set(modelKey, { identity, meter: Boolean(read?.meter) })
+      models.set(modelKey, { identity, realtime })
     }
     result[raw.id] = {
       locator: raw.locator, adapter: raw.adapter, type, label: raw.label.trim(), mode: raw.mode,
+      ...(candidate.button ? { buttonBehavior: behavior } : {}),
       ...(candidate.model ? { model: candidate.model } : {}),
       ...(candidate.repeat ? { repeat: candidate.repeat, instanceKey: raw.instanceKey } : {}),
       ...(candidate.component ? { component: candidate.component } : {}),

package/panel-xy-series.js

@@ -2,6 +2,7 @@ const crypto = require('node:crypto')
 const { createXYSeriesReceiver } = require('./xy-series-frame')
 const { readJsonBody, replyJson } = require('./panel-http')
 const { xySeriesRoute } = require('./xy-series-route')
+const { emitTelemetryFrame } = require('./panel-telemetry-send')
 
 function createXYSeriesRoom ({ room, now = Date.now, staleMs = 1000 }) {
   const sources = new Map(), panels = new Map(), ticks = new Set()
@@ -12,13 +13,21 @@ function createXYSeriesRoom ({ room, now = Date.now, staleMs = 1000 }) {
     const entries = Object.entries(bindings).filter(([, entry]) => entry.readMeta?.xySeries)
       .sort(([a], [b]) => a.localeCompare(b))
     if (!entries.length || entries.length > 256) throw Error('Invalid xy-series panel size')
-    const projections = entries.map(([id, binding]) => {
+    // Validate the whole registration before changing shared sources or references.
+    const proposed = new Map()
+    for (const [, binding] of entries) {
       const series = xySeriesRoute(binding.readMeta.xySeries)
       const key = JSON.stringify([binding.device, series.streamId])
-      let source = sources.get(key)
-      if (source && JSON.stringify(source.route) !== JSON.stringify(series)) {
+      const previous = sources.get(key)?.route || proposed.get(key)
+      if (previous && JSON.stringify(previous) !== JSON.stringify(series)) {
         throw Error(`Conflicting xy-series stream: ${series.streamId}`)
       }
+      proposed.set(key, series)
+    }
+    const projections = entries.map(([id, binding]) => {
+      const series = xySeriesRoute(binding.readMeta.xySeries)
+      const key = JSON.stringify([binding.device, series.streamId])
+      let source = sources.get(key)
       if (!source) {
         source = { device: binding.device, route: series, receiver: null,
           receivedAt: null, revision: 0, refs: new Set() }
@@ -29,7 +38,7 @@ function createXYSeriesRoom ({ room, now = Date.now, staleMs = 1000 }) {
     })
     const layout = { kind: 'room-xy-series-layout', panelId, room,
       epoch: crypto.randomBytes(16).toString('hex'), ids: entries.map(([id]) => id) }
-    panels.set(panelId, { projections, layout, sequence: 0 })
+    panels.set(panelId, { projections, streams: [...new Set(projections.map(point => point.source))], layout, sequence: 0 })
     return layout
   }
 
@@ -69,7 +78,7 @@ function createXYSeriesRoom ({ room, now = Date.now, staleMs = 1000 }) {
       const frame = source.receiver?.snapshot()
       const age = source.receivedAt === null ? null : Math.max(0, time - source.receivedAt)
       const ok = Boolean(frame && age !== null && age <= staleMs)
-      values.push(ok ? frame.points.map(point => point.slice()) : [])
+      values.push(ok ? frame.points.map(point => [point[0], point[1]]) : [])
       valid.push(ok)
       sourcesByStream.set(key, { device: source.device, streamId: source.route.streamId,
         epoch: source.receiver?.manifest.epoch || '', seq: frame?.seq || 0,
@@ -83,7 +92,7 @@ function createXYSeriesRoom ({ room, now = Date.now, staleMs = 1000 }) {
     const panel = panels.get(panelId)
     if (!panel) return ''
     const time = now()
-    return panel.projections.map(({ source }) => `${source.revision}:${source.receivedAt !== null &&
+    return panel.streams.map(source => `${source.revision}:${source.receivedAt !== null &&
       time - source.receivedAt <= staleMs}`).join(',')
   }
 
@@ -133,7 +142,7 @@ function createPanelXYSeries ({ panelId, room, bindings, hub, onSubscribe = () =
     if (revision === lastRevision) return
     lastRevision = revision
     const frame = hub.snapshot(panelId)
-    for (const { socket } of subscribers.values()) emitFrame(socket, frame)
+    emitTelemetryFrame('control-panel:xy-series-frame', frame, subscribers)
   })
   return {
     async ticket (req, res, identity, active) {

package/xy-series-frame.js

@@ -85,7 +85,7 @@ function createRoomXYSeriesReceiver (layout) {
           (valid && points.some(point => !Array.isArray(point) || point.length !== 2 ||
             !finite(point[0]) || !finite(point[1])))) return false
       }
-      latest = { values: frame.values.map(points => points.map(point => point.slice())),
+      latest = { values: frame.values.map(points => points.map(point => [point[0], point[1]])),
         valid: frame.valid.slice(), seq: frame.seq }
       pending = true
       return true