node-red-contrib-knx-ultimate 7.1.4 → 8.0.2

package/nodes/utils/lightEngines/canonicalLight.js

@@ -1,75 +0,0 @@
-'use strict'
-// Canonical, engine-agnostic light model.
-//
-// The Light node's behaviour logic (dimming ramps, day/night presets, blink,
-// colour cycle, HSV...) speaks ONLY this vocabulary. Each concrete engine
-// (Hue, Matter, future Shelly) translates a canonical patch into its native
-// shape and back. Keeping the node blind to the ecosystem is what prevents the
-// "if engine === 'hue'" spaghetti.
-//
-// A canonical patch is a plain object with any subset of:
-//   { on: boolean,
-//     brightnessPct: number 0..100,
-//     colorTempK: number (kelvin),
-//     rgb: { r, g, b } (0..255) }
-
-const clamp = (v, min, max) => Math.min(max, Math.max(min, Number(v)))
-
-const clampByte = (v, max = 254) => {
-  let n = Math.round(Number(v))
-  if (Number.isNaN(n)) n = 0
-  if (n < 0) n = 0
-  if (n > max) n = max
-  return n
-}
-
-// Kelvin <-> mired. Same physical unit; Hue calls it "mirek", Matter "mireds".
-const kelvinToMired = (kelvin) => {
-  const k = Number(kelvin)
-  if (!k || Number.isNaN(k)) return 0
-  return Math.round(1000000 / k)
-}
-const miredToKelvin = (mired) => {
-  const m = Number(mired)
-  if (!m || Number.isNaN(m)) return 0
-  return Math.round(1000000 / m)
-}
-
-// sRGB (0..255) -> CIE 1931 xy, using the Wide RGB D65 conversion Philips Hue expects.
-const rgbToXy = ({ r, g, b }) => {
-  const norm = (c) => {
-    const v = clamp(c, 0, 255) / 255
-    return v > 0.04045 ? Math.pow((v + 0.055) / 1.055, 2.4) : v / 12.92
-  }
-  const rn = norm(r)
-  const gn = norm(g)
-  const bn = norm(b)
-  const X = rn * 0.649926 + gn * 0.103455 + bn * 0.197109
-  const Y = rn * 0.234327 + gn * 0.743075 + bn * 0.022598
-  const Z = rn * 0.0000000 + gn * 0.053077 + bn * 1.035763
-  const sum = X + Y + Z
-  if (sum === 0) return [0, 0]
-  return [Number((X / sum).toFixed(4)), Number((Y / sum).toFixed(4))]
-}
-
-// RGB (0..255) -> HSV. hue in 0..360, sat/val in 0..1.
-const rgbToHsv = ({ r, g, b }) => {
-  const rn = clamp(r, 0, 255) / 255
-  const gn = clamp(g, 0, 255) / 255
-  const bn = clamp(b, 0, 255) / 255
-  const max = Math.max(rn, gn, bn)
-  const min = Math.min(rn, gn, bn)
-  const d = max - min
-  let h = 0
-  if (d !== 0) {
-    if (max === rn) h = ((gn - bn) / d) % 6
-    else if (max === gn) h = (bn - rn) / d + 2
-    else h = (rn - gn) / d + 4
-    h *= 60
-    if (h < 0) h += 360
-  }
-  const s = max === 0 ? 0 : d / max
-  return { h, s, v: max }
-}
-
-module.exports = { clamp, clampByte, kelvinToMired, miredToKelvin, rgbToXy, rgbToHsv }

package/nodes/utils/lightEngines/hueLightEngine.js

@@ -1,51 +0,0 @@
-'use strict'
-const { LightEngine } = require('./lightEngine')
-const { clampByte, kelvinToMired, miredToKelvin, rgbToXy } = require('./canonicalLight')
-
-// Hue speaks a single COMPOSITE, atomic state object (Hue API v2 shape):
-//   { on:{on}, dimming:{brightness}, color:{xy}, color_temperature:{mirek} }
-// so a canonical patch collapses into ONE writeHueQueueAdd call.
-class HueLightEngine extends LightEngine {
-  constructor (opts = {}) {
-    super(opts)
-    this.manager = opts.manager // hue-config's hueManager (writeHueQueueAdd)
-    this.operation = opts.grouped ? 'setGroupedLight' : 'setLight'
-  }
-
-  get kind () { return 'hue' }
-
-  capabilities () {
-    return { onOff: true, dimming: true, colorTemp: true, color: true, effects: true }
-  }
-
-  translate (patch) {
-    const state = {}
-    if (patch.on !== undefined) state.on = { on: !!patch.on }
-    if (patch.brightnessPct !== undefined) state.dimming = { brightness: clampByte(patch.brightnessPct, 100) }
-    if (patch.colorTempK !== undefined) state.color_temperature = { mirek: kelvinToMired(patch.colorTempK) }
-    if (patch.rgb !== undefined) state.color = { xy: { x: rgbToXy(patch.rgb)[0], y: rgbToXy(patch.rgb)[1] } }
-    return state
-  }
-
-  applyState (patch) {
-    const state = this.translate(patch)
-    if (Object.keys(state).length === 0) return []
-    if (this.manager && typeof this.manager.writeHueQueueAdd === 'function') {
-      this.manager.writeHueQueueAdd(this.deviceId, state, this.operation)
-    }
-    return [{ api: 'writeHueQueueAdd', deviceId: this.deviceId, state, operation: this.operation }]
-  }
-
-  // Hue resource object (as delivered to handleSendHUE) -> canonical patch.
-  parseIncoming (event) {
-    if (!event) return null
-    if (event.id !== undefined && event.id !== this.deviceId) return null
-    const patch = {}
-    if (event.on && event.on.on !== undefined) patch.on = !!event.on.on
-    if (event.dimming && event.dimming.brightness !== undefined) patch.brightnessPct = Number(event.dimming.brightness)
-    if (event.color_temperature && event.color_temperature.mirek) patch.colorTempK = miredToKelvin(event.color_temperature.mirek)
-    return Object.keys(patch).length ? patch : null
-  }
-}
-
-module.exports = { HueLightEngine }

package/nodes/utils/lightEngines/index.js

@@ -1,25 +0,0 @@
-'use strict'
-// Factory + registry for light engines. Adding a new ecosystem (e.g. Shelly)
-// is a one-line registration here + one new *LightEngine file: the Light node
-// and its behaviour logic stay untouched.
-const { LightEngine } = require('./lightEngine')
-const { HueLightEngine } = require('./hueLightEngine')
-const { MatterLightEngine } = require('./matterLightEngine')
-
-const ENGINES = {
-  hue: HueLightEngine,
-  matter: MatterLightEngine
-  // shelly: ShellyLightEngine  <-- future: just add the class + this line
-}
-
-function createLightEngine (kind, opts = {}) {
-  const Engine = ENGINES[kind]
-  if (!Engine) {
-    throw new Error(`Unknown light engine "${kind}". Available: ${Object.keys(ENGINES).join(', ')}`)
-  }
-  return new Engine(opts)
-}
-
-const availableEngines = () => Object.keys(ENGINES)
-
-module.exports = { createLightEngine, availableEngines, LightEngine, HueLightEngine, MatterLightEngine }

package/nodes/utils/lightEngines/knxLightCommand.js

@@ -1,79 +0,0 @@
-'use strict'
-const { miredToKelvin } = require('./canonicalLight')
-
-// Linear scale, mirrors hueColorConverter.ColorConverter.scale.
-const scale = (v, [inMin, inMax], [outMin, outMax]) =>
-  outMin + ((Number(v) - inMin) * (outMax - outMin)) / (inMax - inMin)
-
-const truthy = (v) => v === true || v === 1 || v === '1' || v === 'true' || v === 'on'
-
-// Pure, engine-agnostic mapping of a DECODED KNX light group-address value into a
-// canonical patch. `value` is the already dpt-decoded payload, so this stays free
-// of knxultimate/dptlib and is trivially unit-testable.
-//
-// Returns:
-//   { patch }              -> a canonical patch to push to the engine
-//   { unsupported: reason } -> a Hue-only behaviour with no Matter equivalent
-//   null                   -> destination not handled by the light command path
-function canonicalizeKnxLightCommand ({ config, destination, value, dayTime = true }) {
-  switch (destination) {
-    case config.GALightSwitch: {
-      const on = truthy(value)
-      const patch = { on }
-      // Parity with the Hue switch-on preset (temperature mode): a Matter light
-      // turns on with the same day/night brightness + colour temperature.
-      if (on && config.specifySwitchOnBrightness === 'temperature') {
-        const preset = (dayTime === false && config.enableDayNightLighting === 'temperature')
-          ? config.colorAtSwitchOnNightTime
-          : config.colorAtSwitchOnDayTime
-        if (preset && typeof preset === 'object') {
-          if (preset.brightness !== undefined) patch.brightnessPct = Number(preset.brightness)
-          if (preset.kelvin !== undefined) patch.colorTempK = Number(preset.kelvin)
-        }
-      }
-      return { patch }
-    }
-    case config.GALightBrightness: {
-      const pct = Number(value)
-      if (Number.isNaN(pct)) throw new Error('Invalid KNX brightness payload')
-      return { patch: { brightnessPct: pct, on: pct > 0 } }
-    }
-    case config.GALightKelvin: {
-      const kelvin = Math.min(6535, Math.max(2000, Number(value)))
-      return { patch: { colorTempK: kelvin } }
-    }
-    case config.GALightKelvinPercentage: {
-      if (config.dptLightKelvinPercentage !== '5.001') return null
-      const mirek = scale(100 - Number(value), [0, 100], [153, 500])
-      return { patch: { colorTempK: miredToKelvin(mirek) } }
-    }
-    case config.GALightColor: {
-      if (!value || typeof value !== 'object') return null
-      return { patch: { rgb: { r: value.red, g: value.green, b: value.blue } } }
-    }
-    case config.GALightDIM:
-    case config.GALightHSV_H_DIM:
-    case config.GALightHSV_S_DIM:
-    case config.GALightKelvinDIM:
-      return { unsupported: 'Relative/HSV dimming not supported on Matter' }
-    case config.GALightBlink:
-    case config.GALightColorCycle:
-      return { unsupported: 'Effect not supported on Matter' }
-    default:
-      return null
-  }
-}
-
-// The DPT that must be used to decode a given destination GA.
-function dptForDestination (config, destination) {
-  switch (destination) {
-    case config.GALightSwitch: return config.dptLightSwitch
-    case config.GALightBrightness: return config.dptLightBrightness
-    case config.GALightKelvin: return config.dptLightKelvin
-    case config.GALightKelvinPercentage: return config.dptLightKelvinPercentage
-    case config.GALightColor: return config.dptLightColor
-    default: return null
-  }
-}
-
-module.exports = { canonicalizeKnxLightCommand, dptForDestination }

package/nodes/utils/lightEngines/lightEngine.js

@@ -1,46 +0,0 @@
-'use strict'
-// Abstract LightEngine: the single seam between the Light node's engine-agnostic
-// behaviour logic and a concrete ecosystem (Hue, Matter, ...future Shelly).
-//
-// A concrete engine must implement:
-//   - applyState(patch): push a canonical patch toward the ecosystem
-//   - parseIncoming(event): turn a native ecosystem event into a canonical patch
-//   - capabilities(): advertise what it can honour, so the node can degrade
-//     gracefully (e.g. native Hue effects have no Matter equivalent)
-
-class LightEngine {
-  constructor (opts = {}) {
-    this.deviceId = opts.deviceId
-    this._onState = typeof opts.onStateChange === 'function' ? opts.onStateChange : () => {}
-  }
-
-  get kind () { return 'abstract' }
-
-  capabilities () {
-    return { onOff: false, dimming: false, colorTemp: false, color: false, effects: false }
-  }
-
-  // Canonical patch -> native ecosystem call(s). Returns the list of native
-  // operations issued (useful for tests and status/debug).
-  applyState (_patch) {
-    throw new Error(`${this.kind}: applyState not implemented`)
-  }
-
-  // Native ecosystem event -> canonical patch, or null when irrelevant.
-  parseIncoming (_event) {
-    return null
-  }
-
-  // Feed a native event and, when relevant, emit the canonical patch upward
-  // (to the node, which writes it to KNX). Keeps parseIncoming pure/testable.
-  handleIncoming (event) {
-    let patch = null
-    try {
-      patch = this.parseIncoming(event)
-      if (patch && Object.keys(patch).length > 0) this._onState(patch)
-    } catch (error) { /* a bad event / feedback sink must never crash the caller */ }
-    return patch
-  }
-}
-
-module.exports = { LightEngine }

package/nodes/utils/lightEngines/matterHueShim.js

@@ -1,59 +0,0 @@
-'use strict'
-// Boundary shim that lets the (copied) Hue Light logic drive a MATTER light untouched.
-// The node keeps speaking Hue-native composite states ({on:{on}}, {dimming:{brightness}},
-// {color:{xy}}, {color_temperature:{mirek}}); these pure functions translate them to the
-// canonical light model (for MatterLightEngine) and Matter attribute reports back into
-// Hue-shaped feedback patches.
-const hueColorConverter = require('../colorManipulators/hueColorConverter')
-const { matterToKnx } = require('../matterKnxConverter')
-
-// Hue-native state object -> canonical patch { on, brightnessPct, colorTempK, rgb }.
-function hueStateToCanonical (hueState) {
-  try {
-    return _hueStateToCanonical(hueState)
-  } catch (error) {
-    return null
-  }
-}
-function _hueStateToCanonical (hueState) {
-  if (!hueState || typeof hueState !== 'object') return null
-  const patch = {}
-  if (hueState.on && hueState.on.on !== undefined) patch.on = !!hueState.on.on
-  if (hueState.dimming && hueState.dimming.brightness !== undefined) patch.brightnessPct = Number(hueState.dimming.brightness)
-  if (hueState.color_temperature && hueState.color_temperature.mirek) patch.colorTempK = Math.round(1000000 / Number(hueState.color_temperature.mirek))
-  if (hueState.color && hueState.color.xy && hueState.color.xy.x !== undefined) {
-    const bri = patch.brightnessPct !== undefined ? patch.brightnessPct : 100
-    try {
-      const rgb = hueColorConverter.ColorConverter.xyBriToRgb(Number(hueState.color.xy.x), Number(hueState.color.xy.y), bri)
-      patch.rgb = { r: rgb.r, g: rgb.g, b: rgb.b }
-    } catch (error) { /* colour conversion failed: skip the colour part */ }
-  }
-  return Object.keys(patch).length ? patch : null
-}
-
-// Matter attribute report -> feedback patch for the node
-// { on } | { brightnessPct } | { colorTempK, mirek } | { xyX } | { xyY } | null.
-function matterEventToHuePatch (event) {
-  try {
-    if (!event || event.attributeName === undefined) return null
-    switch (event.attributeName) {
-      case 'onOff':
-        return { on: event.value === true }
-      case 'currentLevel': {
-        const v = matterToKnx(Number(event.clusterId), 'currentLevel', event.value)
-        return v === undefined ? null : { brightnessPct: Number(v) }
-      }
-      case 'colorTemperatureMireds': {
-        const m = Number(event.value)
-        return m > 0 ? { colorTempK: Math.round(1000000 / m), mirek: m } : null
-      }
-      case 'currentX': return { xyX: Number(event.value) / 65536 }
-      case 'currentY': return { xyY: Number(event.value) / 65536 }
-      default: return null
-    }
-  } catch (error) {
-    return null
-  }
-}
-
-module.exports = { hueStateToCanonical, matterEventToHuePatch }

package/nodes/utils/lightEngines/matterLightEngine.js

@@ -1,117 +0,0 @@
-'use strict'
-const { LightEngine } = require('./lightEngine')
-const { CLUSTER, matterToKnx } = require('../matterKnxConverter')
-const { clampByte, kelvinToMired, rgbToHsv } = require('./canonicalLight')
-
-// Standard "options" arguments required by several Matter cluster commands.
-const LEVEL_OPTS = { optionsMask: {}, optionsOverride: {} }
-
-// Matter speaks DISCRETE, per-cluster commands, so a single canonical patch
-// DECOMPOSES into N writeMatterQueueAdd calls (on + moveToLevel + colour...).
-// This engine wraps matter-config's matterManager (the controller), NOT the
-// generic Matter controller paths.
-class MatterLightEngine extends LightEngine {
-  constructor (opts = {}) {
-    super(opts)
-    this.manager = opts.manager // matter-config's matterManager (writeMatterQueueAdd)
-    this.nodeId = opts.nodeId !== undefined ? opts.nodeId : opts.deviceId // commissioned Matter node id
-    this.endpointId = opts.endpointId !== undefined ? opts.endpointId : 1
-  }
-
-  get kind () { return 'matter' }
-
-  capabilities () {
-    // No native "effects" (candle/fire/prism) equivalent -> node emulates or skips.
-    return { onOff: true, dimming: true, colorTemp: true, color: true, effects: false }
-  }
-
-  translate (patch) {
-    const ops = []
-    if (patch.on !== undefined) {
-      ops.push({ clusterId: CLUSTER.ON_OFF, kind: 'command', name: patch.on ? 'on' : 'off', args: undefined })
-    }
-    if (patch.brightnessPct !== undefined) {
-      ops.push({
-        clusterId: CLUSTER.LEVEL_CONTROL,
-        kind: 'command',
-        name: 'moveToLevelWithOnOff',
-        args: { level: clampByte(Number(patch.brightnessPct) * 254 / 100, 254), transitionTime: 0, ...LEVEL_OPTS }
-      })
-    }
-    if (patch.colorTempK !== undefined) {
-      ops.push({
-        clusterId: CLUSTER.COLOR_CONTROL,
-        kind: 'command',
-        name: 'moveToColorTemperature',
-        args: { colorTemperatureMireds: kelvinToMired(patch.colorTempK), transitionTime: 0, ...LEVEL_OPTS }
-      })
-    }
-    if (patch.rgb !== undefined) {
-      const { h, s } = rgbToHsv(patch.rgb)
-      ops.push({
-        clusterId: CLUSTER.COLOR_CONTROL,
-        kind: 'command',
-        name: 'moveToHue',
-        args: { hue: clampByte(h * 254 / 360, 254), direction: 0, transitionTime: 0, ...LEVEL_OPTS }
-      })
-      ops.push({
-        clusterId: CLUSTER.COLOR_CONTROL,
-        kind: 'command',
-        name: 'moveToSaturation',
-        args: { saturation: clampByte(s * 254, 254), transitionTime: 0, ...LEVEL_OPTS }
-      })
-    }
-    return ops
-  }
-
-  applyState (patch) {
-    const issued = []
-    let ops = []
-    try {
-      ops = this.translate(patch)
-    } catch (error) {
-      ops = []
-    }
-    ops.forEach((op) => {
-      const item = {
-        nodeId: this.nodeId,
-        endpointId: this.endpointId,
-        clusterId: op.clusterId,
-        kind: op.kind,
-        name: op.name,
-        args: op.args
-      }
-      try {
-        if (this.manager && typeof this.manager.writeMatterQueueAdd === 'function') {
-          const ret = this.manager.writeMatterQueueAdd(item)
-          // writeMatterQueueAdd is async: swallow a late rejection so this
-          // fire-and-forget call can never become an unhandled rejection (process crash).
-          if (ret && typeof ret.catch === 'function') ret.catch(() => { })
-        }
-      } catch (error) { /* one failed write must never break the batch */ }
-      issued.push({ api: 'writeMatterQueueAdd', ...item })
-    })
-    return issued
-  }
-
-  // Matter attribute report -> canonical patch. Reuses matterToKnx value scaling
-  // (currentLevel -> percent, colorTemperatureMireds -> kelvin, onOff -> bool).
-  parseIncoming (event) {
-    try {
-      if (!event) return null
-      if (event.nodeId !== undefined && this.nodeId !== undefined && event.nodeId !== this.nodeId) return null
-      const value = matterToKnx(Number(event.clusterId), event.attributeName, event.value)
-      if (value === undefined) return null
-      switch (event.attributeName) {
-        case 'onOff': return { on: !!value }
-        case 'currentLevel': return { brightnessPct: Number(value) }
-        case 'colorTemperatureMireds': return { colorTempK: Number(value) }
-        default: return null
-      }
-    } catch (error) {
-      return null
-    }
-  }
-}
-
-module.exports = { MatterLightEngine }