node-red-contrib-ycznwl-knx-gateway 1.0.0

package/README.md

@@ -0,0 +1,40 @@
+# node-red-contrib-knx-gateway
+
+Node-RED 节点包，对接 YCZNWL KNX 智能家居网关。
+
+## 包含节点
+
+| 节点 | 功能 |
+|------|------|
+| **knx-gateway-scene** | 场景执行 — 按名称或 UUID 触发场景 |
+| **knx-gateway-device** | 设备控制 — 灯光、窗帘、空调、地暖、开关、门锁、风扇、净化器、播放器 |
+| **knx-gateway-sensor** | 传感器轮询 — 温度/湿度/照度/CO₂/PM2.5/人体存在/移动/烟雾/漏水/门磁 |
+
+## 安装
+
+```bash
+# 进入 Node-RED 目录
+cd ~/.node-red
+npm install /path/to/node-red-contrib-knx-gateway
+node-red-restart
+```
+
+## 使用示例
+
+### 场景执行
+注入节点 → knx-gateway-scene（选"明亮"）→ debug
+
+### 灯光控制
+注入节点（payload: `{brightness:80}`）→ knx-gateway-device（选主灯，动作: set_brightness）
+
+### 空调控制
+注入节点 `msg.action="set_target_temperature" msg.params={target_temperature:25}` → knx-gateway-device
+
+### 温度传感器
+knx-gateway-sensor → function（阈值判断）→ knx-gateway-device（开关空调）
+
+## 配置
+
+先拖一个 **knx-gateway-config** 节点，填入：
+- API 地址: `http://网关IP/api/v1`
+- Token: 从网关网页 → 头像 → Get API Token 获取

package/knx-gateway-config.html

@@ -0,0 +1,29 @@
+<script type="text/x-red" data-template-name="ycznwl-knx-gateway-config">
+  <div class="form-row">
+    <label for="node-config-input-baseUrl"><i class="fa fa-globe"></i> API 地址</label>
+    <input type="text" id="node-config-input-baseUrl" placeholder="http://192.168.2.39/api/v1">
+  </div>
+  <div class="form-row">
+    <label for="node-config-input-token"><i class="fa fa-key"></i> API Token</label>
+    <input type="password" id="node-config-input-token" placeholder="Bearer Token">
+  </div>
+</script>
+
+<script type="text/x-red" data-help-name="ycznwl-knx-gateway-config">
+  <h3>KNX Gateway 配置</h3>
+  <p>填入网关 API 地址和 Token，其他节点共享此配置。</p>
+  <p><b>获取 Token：</b> 打开网关网页 → 右上角头像 → Get API Token</p>
+</script>
+
+<script type="text/javascript">
+  RED.nodes.registerType('ycznwl-knx-gateway-config', {
+    category: 'config',
+    defaults: {
+      baseUrl: { value: 'http://192.168.2.39/api/v1', required: true },
+      token: { value: '', required: true }
+    },
+    label: function() {
+      return this.baseUrl.replace('http://', '');
+    }
+  });
+</script>

package/knx-gateway-config.js

@@ -0,0 +1,8 @@
+module.exports = function(RED) {
+  function KnxGatewayConfig(n) {
+    RED.nodes.createNode(this, n);
+    this.baseUrl = n.baseUrl.replace(/\/+$/, '');
+    this.token = n.token;
+  }
+  RED.nodes.registerType('ycznwl-knx-gateway-config', KnxGatewayConfig);
+};

package/knx-gateway-device.html

@@ -0,0 +1,135 @@
+<script type="text/x-red" data-template-name="ycznwl-knx-gateway-device">
+  <div class="form-row">
+    <label for="node-input-gateway"><i class="fa fa-server"></i> 网关</label>
+    <input type="text" id="node-input-gateway">
+  </div>
+  <div class="form-row">
+    <label for="node-input-device"><i class="fa fa-microchip"></i> 设备</label>
+    <select id="node-input-device" style="width:100%">
+      <option value="">—— 动态输入(msg.payload) ——</option>
+    </select>
+  </div>
+  <div class="form-row">
+    <label for="node-input-action"><i class="fa fa-bolt"></i> 动作</label>
+    <select id="node-input-action" style="width:100%">
+      <option value="">—— 动态输入(msg.action) ——</option>
+      <option value="turn_on">开</option>
+      <option value="turn_off">关</option>
+      <option value="toggle">切换</option>
+      <option value="set_brightness">设置亮度</option>
+      <option value="set_color_temperature">设置色温</option>
+      <option value="set_color">设置颜色</option>
+      <option value="open">打开</option>
+      <option value="close">关闭</option>
+      <option value="stop">停止</option>
+      <option value="set_position">设置位置</option>
+      <option value="set_slat_position">设置百叶角度</option>
+      <option value="set_target_temperature">设置目标温度</option>
+      <option value="set_mode">设置模式</option>
+      <option value="set_fan_speed">设置风速%</option>
+      <option value="set_fan_speed_mode">设置风速档位</option>
+      <option value="set_swing_mode">设置摆风</option>
+      <option value="lock">上锁</option>
+      <option value="unlock">解锁</option>
+      <option value="activate_scene">激活场景</option>
+      <option value="play">播放</option>
+      <option value="pause">暂停</option>
+      <option value="play_pause">播放/暂停</option>
+      <option value="next_track">下一首</option>
+      <option value="set_volume">设置音量</option>
+      <option value="mute">静音</option>
+      <option value="unmute">取消静音</option>
+      <option value="toggle_mute">切换静音</option>
+    </select>
+  </div>
+  <div class="form-row" id="row-params">
+    <label for="node-input-params"><i class="fa fa-cog"></i> 参数 (JSON)</label>
+    <input type="text" id="node-input-params" placeholder='{"brightness":80} 或空'>
+  </div>
+  <div class="form-row" style="margin-top:8px">
+    <label>&nbsp;</label>
+    <button id="node-input-refresh-devices" class="red-ui-button" style="width:100%">
+      <i class="fa fa-refresh"></i> 刷新设备列表
+    </button>
+  </div>
+  <hr>
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> 名称</label>
+    <input type="text" id="node-input-name">
+  </div>
+</script>
+
+<script type="text/x-red" data-help-name="ycznwl-knx-gateway-device">
+  <h3>设备控制</h3>
+  <p>通用设备控制节点，支持灯光、窗帘、空调、地暖、开关、门锁、风扇、净化器、播放器等。</p>
+  <h4>输入 (msg) — 优先级高于面板配置</h4>
+  <ul>
+    <li><code>msg.device_uuid</code> — 设备 UUID</li>
+    <li><code>msg.device_id</code> — 设备数字 ID（备选）</li>
+    <li><code>msg.action</code> — 动作名</li>
+    <li><code>msg.params</code> — 参数对象，如 <code>{ brightness: 80 }</code></li>
+    <li><code>msg.payload</code> — 快捷写法，直接传参对象（需面板设好设备和动作）</li>
+  </ul>
+  <h4>常用动作示例</h4>
+  <ul>
+    <li>灯光: <code>turn_on</code> / <code>set_brightness:80</code> / <code>set_color_temperature:4000</code></li>
+    <li>窗帘: <code>open</code> / <code>close</code> / <code>set_position:50</code></li>
+    <li>空调: <code>turn_on</code> / <code>set_mode:cool</code> / <code>set_target_temperature:25</code> / <code>set_fan_speed_mode:auto</code></li>
+    <li>地暖: <code>turn_on</code> / <code>set_target_temperature:22</code></li>
+    <li>门锁: <code>lock</code> / <code>unlock</code></li>
+  </ul>
+  <h4>输出 (msg)</h4>
+  <ul>
+    <li><code>msg.payload</code> — 控制结果</li>
+  </ul>
+</script>
+
+<script type="text/javascript">
+  RED.nodes.registerType('ycznwl-knx-gateway-device', {
+    category: 'knx',
+    color: '#10B981',
+    defaults: {
+      gateway: { type: 'ycznwl-knx-gateway-config', required: true },
+      device: { value: '' },
+      action: { value: '' },
+      params: { value: '' },
+      name: { value: '' }
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: 'cog',
+    label: function() {
+      return this.name || '设备控制';
+    },
+    oneditprepare: function() {
+      var devSelect = $('#node-input-device');
+      var gwField = $('#node-input-gateway');
+
+      function fetchDevices() {
+        var gw = RED.nodes.node(gwField.val());
+        if (!gw) {
+          devSelect.empty().append('<option value="">—— 请先选择网关 ——</option>');
+          return;
+        }
+        devSelect.empty().append('<option value="">—— 动态输入(msg) ——</option>');
+        $.getJSON(gw.baseUrl + '/devices', function(data) {
+          (data.data || []).forEach(function(d) {
+            if (d.type === 'scene' && d.protocol === 'scene') return; // skip virtual scene devices
+            var label = (d.room_name ? d.room_name + '·' : '') + d.name + ' [' + d.type + '/' + d.sub_type + ']';
+            devSelect.append($('<option>', { value: d.uuid, text: label }));
+          });
+        }).fail(function() {
+          devSelect.empty().append('<option value="">—— 加载失败 ——</option>');
+        });
+      }
+
+      $('#node-input-refresh-devices').click(function(e) {
+        e.preventDefault();
+        fetchDevices();
+      });
+
+      gwField.change(fetchDevices);
+      fetchDevices();
+    }
+  });
+</script>

package/knx-gateway-device.js

@@ -0,0 +1,138 @@
+const http = require('http');
+
+module.exports = function(RED) {
+  function KnxGatewayDevice(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+    const gw = RED.nodes.getNode(config.gateway);
+
+    if (!gw) { node.error('未配置网关'); return; }
+
+    node.on('input', function(msg) {
+      // resolve device UUID
+      const deviceUuid = msg.device_uuid || msg.device_id || config.device;
+      if (!deviceUuid || deviceUuid === '') {
+        node.error('未指定设备');
+        node.status({ fill: 'red', shape: 'dot', text: '缺少设备' });
+        return;
+      }
+
+      // resolve action
+      const action = msg.action || config.action;
+      if (!action || action === '') {
+        node.error('未指定动作');
+        node.status({ fill: 'red', shape: 'dot', text: '缺少动作' });
+        return;
+      }
+
+      // resolve params: msg.params > msg.payload > config.params
+      let params = {};
+      let raw = msg.params || config.params;
+      if (typeof raw === 'string' && raw.trim() !== '') {
+        try { params = JSON.parse(raw); } catch(e) {
+          // try key:value shorthand like "brightness:80"
+          const m = raw.match(/^(\w+):(.+)$/);
+          if (m) {
+            const val = parseFloat(m[2]);
+            params = { [m[1]]: isNaN(val) ? m[2] : val };
+          }
+        }
+      } else if (typeof raw === 'object' && raw !== null) {
+        params = raw;
+      } else if (typeof msg.payload === 'object' && msg.payload !== null
+                 && !msg.payload.device_uuid && !msg.payload.action) {
+        // msg.payload used as params shortcut (only when it's a plain param object)
+        params = msg.payload;
+      }
+
+      node.status({ fill: 'yellow', shape: 'dot', text: action + '...' });
+
+      // find device numeric ID by UUID
+      findDeviceId(gw, deviceUuid, function(err, deviceId) {
+        if (err) {
+          node.error(err.message);
+          node.status({ fill: 'red', shape: 'dot', text: '设备未找到' });
+          return;
+        }
+
+        const body = JSON.stringify({ action: action, params: params });
+        const url = new URL(gw.baseUrl + '/devices/' + deviceId + '/control');
+
+        const opts = {
+          hostname: url.hostname,
+          port: url.port || 80,
+          path: url.pathname,
+          method: 'POST',
+          headers: {
+            'Authorization': 'Bearer ' + gw.token,
+            'Content-Type': 'application/json; charset=utf-8',
+            'Content-Length': Buffer.byteLength(body)
+          }
+        };
+
+        const req = http.request(opts, function(res) {
+          let buf = '';
+          res.on('data', function(c) { buf += c; });
+          res.on('end', function() {
+            try {
+              const result = JSON.parse(buf);
+              if (result.code === 0) {
+                msg.payload = result.data || result;
+                node.status({ fill: 'green', shape: 'dot', text: 'OK' });
+                setTimeout(function() { node.status({}); }, 3000);
+                node.send(msg);
+              } else {
+                node.error('控制失败: ' + result.message);
+                node.status({ fill: 'red', shape: 'dot', text: result.message });
+              }
+            } catch(e) {
+              node.error('解析响应失败: ' + buf);
+              node.status({ fill: 'red', shape: 'dot', text: '解析失败' });
+            }
+          });
+        });
+
+        req.on('error', function(e) {
+          node.error('请求失败: ' + e.message);
+          node.status({ fill: 'red', shape: 'dot', text: '网络错误' });
+        });
+        req.write(body);
+        req.end();
+      });
+    });
+
+    function findDeviceId(gw, uuid, cb) {
+      // cache device list for 60s
+      if (node._deviceCache && (Date.now() - node._cacheTime < 60000)) {
+        const d = node._deviceCache.find(function(d) { return d.uuid === uuid; });
+        if (d) return cb(null, d.id);
+      }
+
+      const url = new URL(gw.baseUrl + '/devices');
+      http.get({
+        hostname: url.hostname,
+        port: url.port || 80,
+        path: url.pathname,
+        headers: { 'Authorization': 'Bearer ' + gw.token }
+      }, function(res) {
+        let body = '';
+        res.on('data', function(c) { body += c; });
+        res.on('end', function() {
+          try {
+            const data = JSON.parse(body);
+            node._deviceCache = data.data || [];
+            node._cacheTime = Date.now();
+            const d = node._deviceCache.find(function(d) { return d.uuid === uuid; });
+            if (d) cb(null, d.id);
+            else cb(new Error('未找到设备: ' + uuid));
+          } catch(e) {
+            cb(new Error('获取设备列表失败'));
+          }
+        });
+      }).on('error', function(e) {
+        cb(new Error('网络请求失败: ' + e.message));
+      });
+    }
+  }
+  RED.nodes.registerType('ycznwl-knx-gateway-device', KnxGatewayDevice);
+};

package/knx-gateway-scene.html

@@ -0,0 +1,84 @@
+<script type="text/x-red" data-template-name="ycznwl-knx-gateway-scene">
+  <div class="form-row">
+    <label for="node-input-gateway"><i class="fa fa-server"></i> 网关</label>
+    <input type="text" id="node-input-gateway">
+  </div>
+  <div class="form-row">
+    <label for="node-input-scene"><i class="fa fa-film"></i> 场景</label>
+    <select id="node-input-scene" style="width:100%">
+      <option value="">—— 动态输入(msg.payload) ——</option>
+    </select>
+  </div>
+  <div class="form-row" style="margin-top:8px">
+    <label>&nbsp;</label>
+    <button id="node-input-refresh" class="red-ui-button" style="width:100%">
+      <i class="fa fa-refresh"></i> 刷新场景列表
+    </button>
+  </div>
+  <hr>
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> 名称</label>
+    <input type="text" id="node-input-name">
+  </div>
+</script>
+
+<script type="text/x-red" data-help-name="ycznwl-knx-gateway-scene">
+  <h3>场景执行</h3>
+  <p>触发时调用网关 API 执行指定场景。</p>
+  <h4>输入 (msg)</h4>
+  <ul>
+    <li><code>msg.payload</code> — 场景名 或 UUID（当上方选择「动态输入」时）</li>
+    <li><code>msg.scene</code> — 场景名 或 UUID（优先级高于 payload）</li>
+  </ul>
+  <h4>输出 (msg)</h4>
+  <ul>
+    <li><code>msg.payload</code> — <code>{ success, actions_executed, actions_failed, duration_ms }</code></li>
+  </ul>
+</script>
+
+<script type="text/javascript">
+  RED.nodes.registerType('ycznwl-knx-gateway-scene', {
+    category: 'knx',
+    color: '#3B82F6',
+    defaults: {
+      gateway: { type: 'ycznwl-knx-gateway-config', required: true },
+      scene: { value: '' },
+      name: { value: '' }
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: 'film',
+    label: function() {
+      return this.name || (this.scene || '动态场景');
+    },
+    oneditprepare: function() {
+      var node = this;
+      var sceneSelect = $('#node-input-scene');
+      var gatewayField = $('#node-input-gateway');
+
+      function fetchScenes() {
+        var gw = RED.nodes.node(gatewayField.val());
+        if (!gw) {
+          sceneSelect.empty().append('<option value="">—— 请先选择网关 ——</option>');
+          return;
+        }
+        sceneSelect.empty().append('<option value="">—— 动态输入(msg.payload) ——</option>');
+        $.getJSON(gw.baseUrl + '/scenes', function(data) {
+          (data.data.scenes || []).forEach(function(s) {
+            sceneSelect.append($('<option>', { value: s.uuid, text: s.name }));
+          });
+        }).fail(function(err) {
+          sceneSelect.empty().append('<option value="">—— 加载失败 ——</option>');
+        });
+      }
+
+      $('#node-input-refresh').click(function(e) {
+        e.preventDefault();
+        fetchScenes();
+      });
+
+      gatewayField.change(fetchScenes);
+      fetchScenes();
+    }
+  });
+</script>

package/knx-gateway-scene.js

@@ -0,0 +1,124 @@
+const http = require('http');
+
+module.exports = function(RED) {
+  function KnxGatewayScene(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+    const gw = RED.nodes.getNode(config.gateway);
+
+    if (!gw) {
+      node.error('未配置网关');
+      return;
+    }
+
+    node.on('input', function(msg) {
+      // scene_uuid: config first, then msg.scene, then msg.payload
+      let sceneId = config.scene;
+      if (!sceneId || sceneId === '') {
+        sceneId = msg.scene || msg.payload;
+      }
+
+      if (!sceneId || sceneId === '') {
+        node.error('未指定场景');
+        node.status({ fill: 'red', shape: 'dot', text: '缺少场景' });
+        return;
+      }
+
+      // determine if it's a UUID or scene name
+      node.status({ fill: 'yellow', shape: 'dot', text: '执行中...' });
+
+      // if it looks like a name (not UUID), resolve it first
+      if (!/-/.test(sceneId)) {
+        resolveByName(gw, sceneId, function(err, uuid) {
+          if (err) return handleErr(err);
+          executeScene(gw, uuid);
+        });
+      } else {
+        executeScene(gw, sceneId);
+      }
+
+      function executeScene(gw, uuid) {
+        const url = new URL(gw.baseUrl + '/scenes/' + encodeURIComponent(uuid) + '/execute');
+        const opts = {
+          hostname: url.hostname,
+          port: url.port || 80,
+          path: url.pathname,
+          method: 'POST',
+          headers: {
+            'Authorization': 'Bearer ' + gw.token,
+            'Content-Type': 'application/json; charset=utf-8'
+          }
+        };
+
+        const req = http.request(opts, function(res) {
+          let body = '';
+          res.on('data', function(chunk) { body += chunk; });
+          res.on('end', function() {
+            try {
+              const result = JSON.parse(body);
+              if (result.code === 0 && result.data) {
+                msg.payload = result.data;
+                node.status({
+                  fill: result.data.success ? 'green' : 'yellow',
+                  shape: 'dot',
+                  text: result.data.actions_executed + '/' +
+                        (result.data.actions_executed + result.data.actions_failed)
+                });
+                setTimeout(function() { node.status({}); }, 5000);
+                node.send(msg);
+              } else {
+                node.error('场景执行失败: ' + (result.message || body));
+                node.status({ fill: 'red', shape: 'dot', text: '失败' });
+              }
+            } catch(e) {
+              node.error('解析响应失败: ' + body);
+              node.status({ fill: 'red', shape: 'dot', text: '解析失败' });
+            }
+          });
+        });
+
+        req.on('error', function(e) {
+          node.error('请求失败: ' + e.message);
+          node.status({ fill: 'red', shape: 'dot', text: '网络错误' });
+        });
+        req.end();
+      }
+
+      function resolveByName(gw, name, cb) {
+        const url = new URL(gw.baseUrl + '/scenes');
+        const opts = {
+          hostname: url.hostname,
+          port: url.port || 80,
+          path: url.pathname,
+          headers: { 'Authorization': 'Bearer ' + gw.token }
+        };
+
+        http.get(opts, function(res) {
+          let body = '';
+          res.on('data', function(chunk) { body += chunk; });
+          res.on('end', function() {
+            try {
+              const data = JSON.parse(body);
+              const scenes = (data.data && data.data.scenes) || [];
+              const match = scenes.find(function(s) {
+                return s.name === name || s.uuid === name;
+              });
+              if (match) cb(null, match.uuid);
+              else cb(new Error('未找到场景: ' + name));
+            } catch(e) {
+              cb(new Error('解析场景列表失败'));
+            }
+          });
+        }).on('error', function(e) {
+          cb(new Error('获取场景列表失败: ' + e.message));
+        });
+      }
+
+      function handleErr(err) {
+        node.error(err.message);
+        node.status({ fill: 'red', shape: 'dot', text: err.message });
+      }
+    });
+  }
+  RED.nodes.registerType('ycznwl-knx-gateway-scene', KnxGatewayScene);
+};

package/knx-gateway-sensor.html

@@ -0,0 +1,106 @@
+<script type="text/x-red" data-template-name="ycznwl-knx-gateway-sensor">
+  <div class="form-row">
+    <label for="node-input-gateway"><i class="fa fa-server"></i> 网关</label>
+    <input type="text" id="node-input-gateway">
+  </div>
+  <div class="form-row">
+    <label for="node-input-device"><i class="fa fa-thermometer-half"></i> 传感器</label>
+    <select id="node-input-device" style="width:100%">
+      <option value="">—— 请先选择网关 ——</option>
+    </select>
+  </div>
+  <div class="form-row">
+    <label for="node-input-interval"><i class="fa fa-clock-o"></i> 轮询间隔 (秒)</label>
+    <input type="number" id="node-input-interval" value="30" min="1" max="3600" style="width:100%">
+  </div>
+  <div class="form-row">
+    <label for="node-input-threshold"><i class="fa fa-filter"></i> 变化阈值</label>
+    <input type="text" id="node-input-threshold" placeholder="仅在变化时输出，空=每次都输出">
+  </div>
+  <div class="form-row" style="margin-top:8px">
+    <label>&nbsp;</label>
+    <button id="node-input-refresh-sensors" class="red-ui-button" style="width:100%">
+      <i class="fa fa-refresh"></i> 刷新传感器列表
+    </button>
+  </div>
+  <hr>
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> 名称</label>
+    <input type="text" id="node-input-name">
+  </div>
+</script>
+
+<script type="text/x-red" data-help-name="ycznwl-knx-gateway-sensor">
+  <h3>传感器轮询</h3>
+  <p>定时轮询传感器数据，变化时输出。支持温度、湿度、照度、CO₂、PM2.5、PM10、TVOC、空气质量、人体存在、移动、烟雾、漏水、门磁、电量等。</p>
+  <h4>输入 (msg) — 触发立即查询</h4>
+  <ul>
+    <li><code>msg.payload</code> — 任意值，触发一次立即查询</li>
+  </ul>
+  <h4>输出 (msg)</h4>
+  <ul>
+    <li><code>msg.payload</code> — 传感器状态对象</li>
+    <li><code>msg.topic</code> — 设备名</li>
+    <li><code>msg.device_uuid</code> — 设备 UUID</li>
+    <li><code>msg.online</code> — 在线状态</li>
+    <li>各传感器值作为顶层属性，如 <code>msg.temperature</code>, <code>msg.humidity</code>, <code>msg.motion</code> 等</li>
+  </ul>
+  <h4>变化阈值</h4>
+  <p>格式: <code>temperature:0.5,humidity:1</code> — 温度变化超0.5°C或湿度变化超1%才输出。</p>
+</script>
+
+<script type="text/javascript">
+  RED.nodes.registerType('ycznwl-knx-gateway-sensor', {
+    category: 'knx',
+    color: '#F59E0B',
+    defaults: {
+      gateway: { type: 'ycznwl-knx-gateway-config', required: true },
+      device: { value: '', required: true },
+      interval: { value: 30, required: true, validate: RED.validators.number() },
+      threshold: { value: '' },
+      name: { value: '' }
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: 'thermometer-half',
+    label: function() {
+      return this.name || '传感器';
+    },
+    oneditprepare: function() {
+      var devSelect = $('#node-input-device');
+      var gwField = $('#node-input-gateway');
+
+      function fetchSensors() {
+        var gw = RED.nodes.node(gwField.val());
+        if (!gw) {
+          devSelect.empty().append('<option value="">—— 请先选择网关 ——</option>');
+          return;
+        }
+        devSelect.empty();
+        $.getJSON(gw.baseUrl + '/devices', function(data) {
+          var sensors = (data.data || []).filter(function(d) {
+            return d.type === 'sensor';
+          });
+          if (sensors.length === 0) {
+            devSelect.append('<option value="">—— 无传感器 ——</option>');
+          }
+          sensors.forEach(function(s) {
+            if (s.id === '') return;
+            var label = (s.room_name ? s.room_name + '·' : '') + s.name + ' [' + s.sub_type + ']';
+            devSelect.append($('<option>', { value: s.uuid, text: label }));
+          });
+        }).fail(function() {
+          devSelect.empty().append('<option value="">—— 加载失败 ——</option>');
+        });
+      }
+
+      $('#node-input-refresh-sensors').click(function(e) {
+        e.preventDefault();
+        fetchSensors();
+      });
+
+      gwField.change(fetchSensors);
+      fetchSensors();
+    }
+  });
+</script>

package/knx-gateway-sensor.js

@@ -0,0 +1,183 @@
+const http = require('http');
+
+module.exports = function(RED) {
+  function KnxGatewaySensor(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+    const gw = RED.nodes.getNode(config.gateway);
+
+    if (!gw) { node.error('未配置网关'); return; }
+    if (!config.device || config.device === '') {
+      node.error('未选择传感器');
+      return;
+    }
+
+    const interval = Math.max(1, parseInt(config.interval) || 30) * 1000;
+    let lastStatus = null;
+    let timer = null;
+
+    // parse threshold config: "temperature:0.5,humidity:1"
+    const thresholds = {};
+    if (config.threshold && config.threshold.trim() !== '') {
+      config.threshold.split(',').forEach(function(pair) {
+        const parts = pair.split(':');
+        if (parts.length === 2) {
+          thresholds[parts[0].trim()] = parseFloat(parts[1].trim());
+        }
+      });
+    }
+
+    function poll() {
+      // determine numeric device ID from UUID
+      fetchDeviceId(gw, config.device, function(err, deviceId) {
+        if (err) {
+          node.error(err.message);
+          node.status({ fill: 'red', shape: 'dot', text: '找不到设备' });
+          return;
+        }
+
+        const url = new URL(gw.baseUrl + '/devices/' + deviceId);
+        http.get({
+          hostname: url.hostname,
+          port: url.port || 80,
+          path: url.pathname,
+          headers: { 'Authorization': 'Bearer ' + gw.token }
+        }, function(res) {
+          let body = '';
+          res.on('data', function(c) { body += c; });
+          res.on('end', function() {
+            try {
+              const data = JSON.parse(body);
+              if (data.code !== 0 || !data.data) {
+                node.error('查询失败: ' + (data.message || body));
+                node.status({ fill: 'red', shape: 'dot', text: '查询失败' });
+                return;
+              }
+
+              const dev = data.data;
+              const status = dev.status || {};
+              const online = dev.is_online;
+
+              // build msg
+              const msg = {
+                payload: status,
+                topic: dev.name,
+                device_uuid: dev.uuid,
+                device_id: dev.id,
+                device_name: dev.name,
+                device_type: dev.type + '/' + dev.sub_type,
+                online: online
+              };
+
+              // flatten sensor values to msg properties
+              Object.keys(status).forEach(function(key) {
+                msg[key] = status[key];
+              });
+
+              // check thresholds
+              let changed = false;
+              if (lastStatus) {
+                Object.keys(thresholds).forEach(function(key) {
+                  const prev = lastStatus[key];
+                  const curr = status[key];
+                  if (prev !== undefined && curr !== undefined
+                      && Math.abs(curr - prev) >= thresholds[key]) {
+                    changed = true;
+                  }
+                });
+                // also output if online state changed
+                if (lastStatus._online !== online) changed = true;
+              } else {
+                // first poll, always output
+                changed = true;
+              }
+
+              lastStatus = Object.assign({}, status, { _online: online });
+
+              if (changed || Object.keys(thresholds).length === 0) {
+                node.status({
+                  fill: online ? 'green' : 'grey',
+                  shape: 'dot',
+                  text: formatStatus(status, dev.sub_type)
+                });
+                node.send(msg);
+              }
+            } catch(e) {
+              node.error('解析失败: ' + e.message);
+              node.status({ fill: 'red', shape: 'dot', text: '解析失败' });
+            }
+          });
+        }).on('error', function(e) {
+          node.error('请求失败: ' + e.message);
+          node.status({ fill: 'red', shape: 'dot', text: '网络错误' });
+        });
+      });
+    }
+
+    function formatStatus(s, subType) {
+      switch(subType) {
+        case 'sensor_temperature': return (s.temperature || '--') + '°C';
+        case 'sensor_humidity': return (s.humidity || '--') + '%';
+        case 'sensor_co2': return (s.co2 || '--') + 'ppm';
+        case 'sensor_illuminance': return (s.illuminance || '--') + 'lux';
+        case 'sensor_pm25': return 'PM2.5:' + (s.pm25 || '--');
+        case 'sensor_pm10': return 'PM10:' + (s.pm10 || '--');
+        case 'sensor_presence': return s.presence ? '有人' : '无人';
+        case 'sensor_motion': return s.motion ? '移动' : '静止';
+        case 'sensor_smoke': return s.smoke ? '⚠烟雾' : '正常';
+        case 'sensor_leak': return s.leak ? '⚠漏水' : '正常';
+        case 'sensor_contact': return s.contact ? '开' : '关';
+        case 'sensor_tvoc': return 'TVOC:' + (s.tvoc || '--');
+        case 'sensor_air_quality': return 'AQI:' + (s.air_quality || '--');
+        default: return s._online !== false ? '在线' : '离线';
+      }
+    }
+
+    function fetchDeviceId(gw, uuid, cb) {
+      if (node._deviceCache && (Date.now() - node._cacheTime < 60000)) {
+        const d = node._deviceCache.find(function(d) { return d.uuid === uuid; });
+        if (d) return cb(null, d.id);
+      }
+
+      const url = new URL(gw.baseUrl + '/devices');
+      http.get({
+        hostname: url.hostname,
+        port: url.port || 80,
+        path: url.pathname,
+        headers: { 'Authorization': 'Bearer ' + gw.token }
+      }, function(res) {
+        let body = '';
+        res.on('data', function(c) { body += c; });
+        res.on('end', function() {
+          try {
+            const data = JSON.parse(body);
+            node._deviceCache = data.data || [];
+            node._cacheTime = Date.now();
+            const d = node._deviceCache.find(function(d) { return d.uuid === uuid; });
+            if (d) cb(null, d.id);
+            else cb(new Error('未找到设备: ' + uuid));
+          } catch(e) {
+            cb(new Error('获取设备列表失败'));
+          }
+        });
+      }).on('error', function(e) {
+        cb(new Error('网络请求失败: ' + e.message));
+      });
+    }
+
+    // start polling
+    timer = setInterval(poll, interval);
+    // do initial poll immediately
+    setTimeout(poll, 500);
+
+    // allow msg input to trigger immediate poll
+    node.on('input', function(msg) {
+      poll();
+    });
+
+    node.on('close', function() {
+      if (timer) { clearInterval(timer); timer = null; }
+    });
+  }
+  RED.nodes.registerType('ycznwl-knx-gateway-sensor', KnxGatewaySensor);
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "node-red-contrib-ycznwl-knx-gateway",
+  "version": "1.0.0",
+  "description": "Node-RED nodes for YCZNWL KNX Gateway — scenes, lights, curtains, AC, thermostat, sensors",
+  "license": "MIT",
+  "author": {
+    "name": "Your Name",
+    "email": "your@email.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourname/node-red-contrib-ycznwl-knx-gateway"
+  },
+  "bugs": {
+    "url": "https://github.com/yourname/node-red-contrib-ycznwl-knx-gateway/issues"
+  },
+  "homepage": "https://github.com/yourname/node-red-contrib-ycznwl-knx-gateway#readme",
+  "keywords": ["node-red", "knx", "smart-home", "gateway", "ycznwl", "home-automation"],
+  "node-red": {
+    "nodes": {
+      "ycznwl-knx-gateway-config": "knx-gateway-config.js",
+      "ycznwl-knx-gateway-scene": "knx-gateway-scene.js",
+      "ycznwl-knx-gateway-device": "knx-gateway-device.js",
+      "ycznwl-knx-gateway-sensor": "knx-gateway-sensor.js"
+    }
+  },
+  "dependencies": {},
+  "engines": {
+    "node": ">=14"
+  }
+}