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

package/control-type-model.js

@@ -11,6 +11,48 @@ function createTargetMatcher (typeContract) {
     return ['meter', 'xy-series', 'text-display'].includes(adapter)
       ? ['read'] : ['both', 'write', 'read']
   }
+  function states (target) {
+    if (target.meter || target.xySeries || !['boolean', 'integer', 'float', 'enum', 'string', 'dstring'].includes(target.type)) return null
+    if (Array.isArray(target.enums) && target.enums.length) {
+      if (target.enums.length !== 2) return null
+      const values = target.enums.map(entry => entry && typeof entry === 'object' ? entry.value : entry)
+      if (values.some(value => !['boolean', 'string', 'number'].includes(typeof value) ||
+        (typeof value === 'number' && !Number.isFinite(value))) || values[0] === values[1]) return null
+      if (target.type === 'integer' && values.some(value => !Number.isSafeInteger(value))) return null
+      if (target.type === 'float' && values.some(value => typeof value !== 'number')) return null
+      if (target.type === 'boolean' && values.some(value => typeof value !== 'boolean')) return null
+      if (['string', 'dstring'].includes(target.type) && values.some(value => typeof value !== 'string')) return null
+      return values
+    }
+    if (target.type === 'boolean') return [false, true]
+    if (target.type === 'integer' && Number.isSafeInteger(target.min) &&
+      Number.isSafeInteger(target.max) && target.max - target.min === 1) return [target.min, target.max]
+    return null
+  }
+  // Native readonly numeric parameters need no custom frame/manifest route.
+  function meterTarget (target) {
+    return target.access === 'ro' && !target.xySeries &&
+      ['integer', 'float'].includes(target.type) &&
+      Boolean(target.meter || (!target.enums?.length && !states(target)))
+  }
+  function reverse (binding = {}, write = binding.writeMeta, read = binding.readMeta) {
+    if (Object.hasOwn(binding, 'stateReverse')) {
+      if (typeof binding.stateReverse !== 'boolean') throw new Error('State reverse must be boolean')
+      return binding.stateReverse
+    }
+    const point = write || read
+    const mapping = write
+      ? (Object.hasOwn(binding, 'writeMapping') ? binding.writeMapping : binding.writeMeta?.booleanMapping)
+      : (Object.hasOwn(binding, 'readMapping') ? binding.readMapping : binding.readMeta?.booleanMapping)
+    if (mapping === undefined) return false
+    const values = point && states(point)
+    if (!values || !mapping || typeof mapping !== 'object' || Array.isArray(mapping) ||
+      !Object.hasOwn(mapping, 'falseValue') || !Object.hasOwn(mapping, 'trueValue') ||
+      Object.is(mapping.falseValue, mapping.trueValue) ||
+      !values.some(value => Object.is(value, mapping.falseValue)) ||
+      !values.some(value => Object.is(value, mapping.trueValue))) throw new Error('Invalid two-state mapping')
+    return Object.is(mapping.trueValue, values[0])
+  }
   function family (target) {
     if (target.xySeries) return 'xy-series'
     if (target.controlSchemaVersion !== typeContract.schemaVersion) return null
@@ -26,28 +68,43 @@ function createTargetMatcher (typeContract) {
     return definition.family
   }
   function compatible (adapter, target, direction, candidate = {}) {
-    if (adapter === 'meter' && !target.meter) return false
+    if (adapter === 'meter' && !meterTarget(target)) return false
+    if (adapter === 'range' && meterTarget(target)) return false
     if (adapter === 'xy-series' && !target.xySeries) return false
     if (target.meter && (adapter !== 'meter' || direction !== 'read' || target.access !== 'ro')) return false
     if (target.xySeries && (adapter !== 'xy-series' || direction !== 'read' || target.access !== 'ro')) return false
-    if (target.kind !== 'param' || !families[adapter]?.includes(family(target))) return false
+    if (target.kind !== 'param' || !(adapter === 'switch'
+      ? states(target) : families[adapter]?.includes(family(target)))) return false
     if (direction === 'write' && ['meter', 'xy-series', 'text-display'].includes(adapter)) return false
     if (!['read', 'write'].includes(direction)) return false
     if (!(direction === 'write' ? ['wo', 'rw'] : ['ro', 'rw']).includes(target.access)) return false
     if (candidate.unit && candidate.unit !== target.unit) return false
     return true
   }
-  return { family, compatible, modes }
+  return { family, compatible, modes, states, reverse, meterTarget }
 }
 
-const { family: targetFamily, compatible: compatibleTarget, modes: bindingModes } = createTargetMatcher(contract)
+const { family: targetFamily, compatible: compatibleTarget, modes: bindingModes, states: targetStates, reverse: stateReverse, meterTarget: isMeterTarget } = createTargetMatcher(contract)
+
+function switchMapping (target, mapping, reverse = false) {
+  const states = targetStates(target)
+  if (!states) throw new Error('Switch target must describe exactly two distinct states')
+  const result = mapping === undefined ? { falseValue: states[reverse ? 1 : 0], trueValue: states[reverse ? 0 : 1] } : mapping
+  if (!result || typeof result !== 'object' || Array.isArray(result) ||
+    !Object.hasOwn(result, 'falseValue') || !Object.hasOwn(result, 'trueValue') ||
+    Object.is(result.falseValue, result.trueValue) ||
+    !states.some(value => Object.is(value, result.falseValue)) ||
+    !states.some(value => Object.is(value, result.trueValue))) throw new Error('Invalid two-state mapping')
+  return { falseValue: result.falseValue, trueValue: result.trueValue }
+}
 
 function controlTypeForAdapter (adapter, target) {
   if (!compatibleTarget(adapter, target, 'read') && !compatibleTarget(adapter, target, 'write')) {
     throw new Error('Target is incompatible with this control')
   }
-  if (adapter === 'meter' && target.meter) return 'meter'
+  if (adapter === 'meter') return 'meter'
   if (adapter === 'xy-series' && target.xySeries) return 'xy-series'
+  if (adapter === 'switch') return 'mute'
   const family = targetFamily(target)
   if (family === 'number') return 'level'
   if (family === 'boolean') return 'mute'
@@ -56,7 +113,7 @@ function controlTypeForAdapter (adapter, target) {
   throw new Error('Unsupported control family')
 }
 
-function targetMeta (target, onebased) {
+function targetMeta (target, onebased, booleanMapping) {
   if (typeof target.onebased !== 'boolean' && typeof onebased !== 'boolean') {
     throw new Error('Select target numbering mode')
   }
@@ -65,10 +122,13 @@ function targetMeta (target, onebased) {
     onebased: typeof target.onebased === 'boolean' ? target.onebased : onebased,
     min: target.min, max: target.max, enums: target.enums,
     ...(target.booleanEncoding ? { booleanEncoding: target.booleanEncoding } : {}),
+    ...(booleanMapping ? { booleanMapping: switchMapping(target, booleanMapping) } : {}),
     controlType: target.controlType, controlSchemaVersion: target.controlSchemaVersion,
     ...(target.meter ? { meter: meterRoute(target.meter), unit: target.unit || '' } : {}),
-    ...(target.xySeries ? { xySeries: require('./xy-series-route').xySeriesRoute(target.xySeries) } : {})
+    ...(target.xySeries ? { xySeries: require('./xy-series-route').xySeriesRoute(target.xySeries) } : {}),
+    ...(target.availability ? { availability: require('./device-availability').availabilityRoute(target.availability,
+      typeof target.onebased === 'boolean' ? target.onebased : onebased) } : {})
   }
 }
 
-module.exports = { contract, createTargetMatcher, compatibleTarget, controlTypeForAdapter, targetFamily, targetMeta, bindingModes }
+module.exports = { contract, createTargetMatcher, compatibleTarget, controlTypeForAdapter, targetFamily, targetMeta, bindingModes, targetStates, switchMapping, stateReverse, isMeterTarget }

package/device-availability.js

@@ -0,0 +1,104 @@
+function availabilityRoute (value, onebased) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw Error('Invalid device availability route')
+  const result = {}
+  for (const role of ['online', 'ready']) {
+    const point = value[role]
+    if (!point && role === 'ready') continue
+    if (!point || typeof point.path !== 'string' || !/^\/\/[^\s]{1,1024}$/.test(point.path) ||
+      (typeof point.onebased !== 'boolean' && typeof onebased !== 'boolean')) throw Error('Invalid ' + role + ' availability point')
+    result[role] = { path: point.path, onebased: point.onebased ?? onebased }
+  }
+  return result
+}
+
+function createDeviceAvailability (routes) {
+  const groups = new Map()
+  const controls = new Map()
+  const needsFeedback = new Set()
+  const fresh = new Set()
+  for (const [id, { binding, control }] of routes) {
+    const keys = new Set()
+    for (const meta of [binding.readMeta, binding.writeMeta]) {
+      if (!meta?.availability) continue
+      const route = availabilityRoute(meta.availability)
+      const key = JSON.stringify([binding.device, route])
+      if (!groups.has(key)) groups.set(key, { device: binding.device, route, online: false, ready: false })
+      keys.add(key)
+    }
+    if (keys.size) {
+      controls.set(id, [...keys])
+      if (control.mode !== 'write' && !binding.readMeta?.meter && !binding.readMeta?.xySeries) needsFeedback.add(id)
+    }
+  }
+  const pending = new Map()
+  const healthy = id => !controls.has(id) || controls.get(id).every(key => {
+    const group = groups.get(key)
+    return group.online === true && (!group.route.ready || group.ready === true)
+  })
+  const allowed = id => healthy(id) && (!needsFeedback.has(id) || fresh.has(id))
+  const snapshot = () => [...controls.keys()].map(id => ({ id, available: allowed(id) }))
+  let previous = JSON.stringify(snapshot())
+  let dirty = false
+  return {
+    allowed,
+    snapshot,
+    changes () {
+      if (!dirty) return null
+      dirty = false
+      const items = snapshot()
+      const next = JSON.stringify(items)
+      if (next === previous) return null
+      previous = next
+      return items
+    },
+    update (message) {
+      if (message?.kind !== 'device-availability') return null
+      const value = message.payload === true || message.payload === 'true' ? true
+        : message.payload === false || message.payload === 'false' ? false : null
+      if (value === null) return null
+      let changed = false
+      for (const group of groups.values()) {
+        if (group.device !== message.device) continue
+        for (const role of ['online', 'ready']) {
+          if (group.route[role]?.path !== message.path) continue
+          if (group[role] !== value) changed = true
+          group[role] = value
+          if (role === 'online' && !value) group.ready = false
+        }
+      }
+      if (!changed) return null
+      dirty = true
+      for (const id of controls.keys()) if (!healthy(id)) {
+        fresh.delete(id)
+        if (!controls.get(id).every(key => groups.get(key).online)) pending.delete(id)
+      }
+      return snapshot()
+    },
+    feedback (items) {
+      const result = []
+      for (const item of items) {
+        if (healthy(item.id)) {
+          if (controls.has(item.id) && !fresh.has(item.id)) { fresh.add(item.id); dirty = true }
+          result.push(item)
+        }
+        else {
+          // Fresh initialization replies may arrive before stateReady=true.
+          // Never retain values received while the transport is offline.
+          if (controls.get(item.id)?.every(key => groups.get(key).online)) pending.set(item.id, item)
+        }
+      }
+      return result
+    },
+    takePending () {
+      const result = []
+      for (const [id, item] of pending) if (healthy(id)) {
+        if (!fresh.has(id)) { fresh.add(id); dirty = true }
+        result.push(item)
+        pending.delete(id)
+      }
+      return result
+    }
+  }
+}
+
+module.exports = { availabilityRoute, createDeviceAvailability }

package/gateway.cjs

@@ -114,11 +114,22 @@ function createGateway ({
     return message
   }
 
+  let availability = []
+  function boundAvailability (items) {
+    if (!Array.isArray(items) || items.some(item => typeof item?.id !== 'string' || typeof item.available !== 'boolean')) {
+      throw Error('Invalid bound availability')
+    }
+    availability = items.map(item => ({ id: item.id, available: item.available }))
+    boundRevision++
+    broadcastFeedback({ room, kind: 'bound-availability', availability, revision: boundRevision })
+  }
+
   function boundSnapshot () {
     return {
       room, kind: 'bound-snapshot',
       items: [...boundState].map(([id, value]) => ({ id, value })),
-      revision: boundRevision
+      revision: boundRevision,
+      ...(availability.length ? { availability } : {})
     }
   }
 
@@ -276,6 +287,7 @@ function createGateway ({
   return {
     handler,
     boundFeedback,
+    boundAvailability,
     sessionActive: token => !closed && (sessions.get(token)?.expiry || 0) > Date.now(),
     sessionSnapshot () {
       return new Map([...sessions].filter(([, session]) => session.expiry > Date.now())

package/managed-native-bridge.js

@@ -24,9 +24,11 @@ function panelTargets (panel) {
       const target = {
         device: binding.device, path, kind: meta.kind, type: meta.type,
         access: meta.access, onebased: meta.onebased,
+        min: meta.min, max: meta.max, enums: meta.enums,
         ...(meta.booleanEncoding ? { booleanEncoding: meta.booleanEncoding } : {}),
         ...(meta.meter ? { meter: meta.meter } : {}),
-        ...(meta.xySeries ? { xySeries: meta.xySeries } : {})
+        ...(meta.xySeries ? { xySeries: meta.xySeries } : {}),
+        ...(meta.availability ? { availability: meta.availability } : {})
       }
       const key = JSON.stringify([target.device, target.path])
       const previous = targets.get(key)

package/meter-frame.js

@@ -99,7 +99,13 @@ function createRoomMeterReceiver (layout) {
         frame.valid.some((flag, index) => typeof flag !== 'boolean' || (flag
           ? typeof frame.values[index] !== 'number' || !Number.isFinite(frame.values[index])
           : frame.values[index] !== null))) return false
-      latest = { values: frame.values.slice(), valid: frame.valid.slice(), seq: frame.seq }
+      if (frame.sources !== undefined && (!Array.isArray(frame.sources) || frame.sources.length > 256 ||
+        frame.sources.some(source => typeof source?.device !== 'string' || source.device.length > 128 ||
+          typeof source.streamId !== 'string' || source.streamId.length > 128 ||
+          typeof source.epoch !== 'string' || source.epoch.length > 128 ||
+          !Number.isSafeInteger(source.seq) || source.seq < 0))) return false
+      latest = { values: frame.values.slice(), valid: frame.valid.slice(), seq: frame.seq,
+        ...(frame.sources ? { sources: frame.sources.map(({ device, streamId, epoch, seq }) => ({ device, streamId, epoch, seq })) } : {}) }
       pending = true
       return true
     },

package/native-binding-plan.js

@@ -1,6 +1,8 @@
 const { configuredRoutes } = require('./control-bound-protocol')
 const { meterRoute } = require('./meter-route')
 const { xySeriesRoute } = require('./xy-series-route')
+const { targetStates, isMeterTarget } = require('./control-type-model')
+const { availabilityRoute } = require('./device-availability')
 
 const supportedTypes = {
   boolean: { eventType: 'Boolean', eventOptions: { boolParamFilter: 'Any' } },
@@ -32,21 +34,23 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
   const writeTargets = new Map()
   const meterStreams = new Map()
   const xySeriesStreams = new Map()
+  const healthTargets = new Map()
   const commandRules = []
   const commandWires = []
 
-  function metadata (device, path, type, access) {
+  function metadata (device, path, type, access, adapter) {
     const target = targetIndex.get(JSON.stringify([device, path]))
     if (!target) throw new Error(`Missing target descriptor: ${device} ${path}`)
     if (target.kind !== 'param') throw new Error(`Only parameter targets are supported: ${path}`)
     if (!target.xySeries && !Object.hasOwn(supportedTypes, target.type)) {
       throw new Error(`Unsupported native parameter type: ${path} (${target.type})`)
     }
-    if (['mute', 'power'].includes(type) && target.type !== 'boolean' &&
+    if (['mute', 'power'].includes(type) && !targetStates(target) &&
       !(target.type === 'integer' && target.booleanEncoding === 'integer01')) {
       throw new Error(`Boolean control bound to ${target.type}: ${path}`)
     }
-    if (['level', 'dimmer', 'position'].includes(type) && !['integer', 'float'].includes(target.type)) {
+    if (['level', 'dimmer', 'position'].includes(type) &&
+      (!['integer', 'float'].includes(target.type) || (adapter === 'range' && isMeterTarget(target)))) {
       throw new Error(`Numeric control bound to ${target.type}: ${path}`)
     }
     if (type === 'text' && !['string', 'dstring'].includes(target.type)) {
@@ -55,7 +59,7 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
     if (['source', 'preset'].includes(type) && !['enum', 'integer', 'string'].includes(target.type)) {
       throw new Error(`Choice control bound to ${target.type}: ${path}`)
     }
-    if (type === 'meter' && (!target.meter || !['integer', 'float'].includes(target.type) || target.access !== 'ro')) {
+    if (type === 'meter' && !isMeterTarget(target)) {
       throw new Error(`Meter control must bind to a readonly Meter target: ${path}`)
     }
     if (type === 'xy-series' && (!target.xySeries || target.access !== 'ro')) {
@@ -70,6 +74,34 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
     if (typeof target.onebased !== 'boolean') {
       throw new Error(`Target numbering mode is required: ${path}`)
     }
+    if (target.availability) {
+      for (const point of Object.values(availabilityRoute(target.availability, target.onebased))) {
+        const key = JSON.stringify([device, point.path])
+        if (healthTargets.has(key)) {
+          if (healthTargets.get(key).onebased !== point.onebased) throw Error('Conflicting availability numbering')
+          continue
+        }
+        const index = healthTargets.size + 1
+        const statusId = `${scopeId}-health-read-${index}`
+        const eventId = `${scopeId}-health-watch-${index}`
+        const tagId = `${scopeId}-health-tag-${index}`
+        healthTargets.set(key, { statusId, tagId, onebased: point.onebased })
+        nodes.push({ id: statusId, type: 'Status', z: subflowId,
+          name: `Read availability ${device} ${point.path}`, x: 440, y: 340 + index * 170,
+          mojo: { version: '1.0', device: [device], parameter: point.path, onebased: point.onebased }, wires: [[tagId]] })
+        nodes.push({ id: eventId, type: 'Event', z: subflowId,
+          name: `Watch availability ${device} ${point.path}`, x: 440, y: 400 + index * 170,
+          mojo: { version: '1.0', device: [device], event: point.path, eventKind: 'Parameter',
+            paramType: 'Boolean', boolParamFilter: 'Any', onebased: point.onebased }, wires: [[tagId]] })
+        nodes.push({ id: tagId, type: 'change', z: subflowId,
+          name: `Identify availability ${device} ${point.path}`, x: 900, y: 370 + index * 170,
+          rules: [
+            { t: 'set', p: 'kind', pt: 'msg', to: 'device-availability', tot: 'str' },
+            { t: 'set', p: 'device', pt: 'msg', to: device, tot: 'str' },
+            { t: 'set', p: 'path', pt: 'msg', to: point.path, tot: 'str' }
+          ], wires: [[]] })
+      }
+    }
     return target
   }
 
@@ -77,7 +109,7 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
     if (!binding?.device) throw new Error(`Missing device binding: ${id}`)
     if (control.mode !== 'read') {
       if (!binding.writePath) throw new Error(`Missing write path: ${id}`)
-      const target = metadata(binding.device, binding.writePath, control.type, 'w')
+      const target = metadata(binding.device, binding.writePath, control.type, 'w', control.adapter)
       const key = JSON.stringify([target.device, target.path])
       if (!writeTargets.has(key)) {
         const nodeId = `${scopeId}-write-${writeTargets.size + 1}`
@@ -97,7 +129,7 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
 
     if (control.mode !== 'write') {
       if (!binding.readPath) throw new Error(`Missing read path: ${id}`)
-      const target = metadata(binding.device, binding.readPath, control.type, 'r')
+      const target = metadata(binding.device, binding.readPath, control.type, 'r', control.adapter)
       if (target.meter) {
         const meter = meterRoute(target.meter)
         if (control.mode !== 'read' || control.adapter !== 'meter') throw Error(`Meter is read-only: ${id}`)
@@ -224,6 +256,9 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
   const commandSwitchId = `${scopeId}-commands`
   // Ordinary feedback, Meter, and XY-series each get a separate vertical band.
   for (const node of nodes) {
+    if (node.id.startsWith(`${scopeId}-health-`)) {
+      node.y += readTargets.size * 170 + (meterStreams.size + xySeriesStreams.size) * 280
+    }
     if (node.id.startsWith(`${scopeId}-meter-`) || node.id.startsWith(`${scopeId}-xy-series-`)) {
       node.y += readTargets.size * 170
       if (node.id.startsWith(`${scopeId}-xy-series-`)) node.y += meterStreams.size * 280
@@ -249,19 +284,20 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
     ],
     checkall: 'false', repair: false, outputs: 2,
     wires: [commandRules.length ? [commandSwitchId] : [],
-      [...readTargets.values(), ...meterStreams.values(), ...xySeriesStreams.values()].map(target => target.statusId)]
+      [...readTargets.values(), ...meterStreams.values(), ...xySeriesStreams.values(), ...healthTargets.values()].map(target => target.statusId)]
   })
   const subflow = {
     id: subflowId, type: 'subflow', name: `Binding bridge ${scopeId}`,
     info: 'Generated panel binding bridge. Requires a Controller node and authenticated command source.',
     category: 'panel binding',
     in: [{ x: 170, y: 150, wires: [{ id: routerId }] }],
-    out: readTargets.size || meterStreams.size || xySeriesStreams.size
+    out: readTargets.size || meterStreams.size || xySeriesStreams.size || healthTargets.size
       ? [{ x: meterStreams.size || xySeriesStreams.size ? 1600 : 1290,
         y: Math.round((390 + (readTargets.size + meterStreams.size + xySeriesStreams.size + 1) * 85) / 10) * 10,
         wires: [...readTargets.values()].map(target => ({ id: target.tagId, port: 0 }))
           .concat([...meterStreams.values()].flatMap(target => target.tagIds.map(id => ({ id, port: 0 }))))
-          .concat([...xySeriesStreams.values()].flatMap(target => target.tagIds.map(id => ({ id, port: 0 })))) }]
+          .concat([...xySeriesStreams.values()].flatMap(target => target.tagIds.map(id => ({ id, port: 0 }))))
+          .concat([...healthTargets.values()].map(target => ({ id: target.tagId, port: 0 }))) }]
       : [],
     env: [], meta: {}, color: '#96bca7'
   }
@@ -270,7 +306,8 @@ function compileNativeBindingPlan ({ panel, targets, scopeId }) {
     manifest: {
       subflowId,
       controls: routes.size,
-      nativeReads: readTargets.size + meterStreams.size + xySeriesStreams.size,
+      nativeReads: readTargets.size + meterStreams.size + xySeriesStreams.size + healthTargets.size,
+      ...(healthTargets.size ? { nativeAvailabilityReads: healthTargets.size } : {}),
       nativeMeterStreams: meterStreams.size,
       nativeXYSeriesStreams: xySeriesStreams.size,
       nativeWrites: writeTargets.size,

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "node-red-contrib-room-tools",
-  "version": "1.9.4",
+  "version": "1.9.5",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "node-red-contrib-room-tools",
-      "version": "1.9.4",
+      "version": "1.9.5",
       "license": "UNLICENSED",
       "dependencies": {
         "@vue/compiler-sfc": "3.5.42",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-room-tools",
-  "version": "1.9.4",
+  "version": "1.9.5",
   "description": "Authenticated visual control panel binding for Node-RED and MUSE Automator",
   "license": "UNLICENSED",
   "scripts": {
@@ -26,6 +26,7 @@
     "control-catalog.js",
     "control-type-contract.json",
     "control-type-model.js",
+    "device-availability.js",
     "meter-route.js",
     "meter-frame.js",
     "panel-meter.js",