node-red-contrib-knx-ultimate
Version:
Control your KNX and KNX Secure intallation via Node-Red! A bunch of KNX nodes, with integrated Philips HUE control, ETS group address importer, KNX AI for diagnosticsand KNX routing between interfaces. Easy to use and highly configurable.
240 lines (174 loc) • 9.01 kB
HTML
<script type="text/markdown" data-help-name="knxUltimate">
## KNX-ULTIMATE 设备节点设置
该节点用于控制 KNX 组地址（Group Address），是最常用的节点。
[<i class="fa fa-code"></i> 示例请见此处](https://supergiovane.github.io/node-red-contrib-knx-ultimate/wiki/-SamplesHome)
**配置**
|属性|说明|
|--|--|
| Gateway | 选择要使用的 KNX 网关 |
| GA 类型 | 组地址类型。默认 **3-层级**（可输入三层组地址或名称，若已导入 ETS）；**Global** 启动时从全局变量读取；**Flow** 在流程作用域读取；**$Env variable** 从环境变量读取；**通用模式（监听所有组地址）** 对所有 GA 做出响应。|
| Group Addr. | 需要控制的组地址。若已导入 ETS，可直接输入设备名进行匹配。也可留空，之后通过输入消息 `msg.setConfig` 设置。|
| Datapoint | 与节点关联的 Datapoint。|
<br/>
<br/>
### 手动命令按钮
编辑器可为每个节点显示一个小按钮，用于手动发送 KNX 命令，无需额外的 Inject 节点。
|属性|说明|
|--|--|
| 显示手动按钮 | 在工作区和节点列表中显示/隐藏该按钮。|
| 按钮动作 | 设置点击后的操作。**发送 KNX Read** 会发送标准读取报文；**Toggle boolean** 适用于 DPT 1.x，可在 _true_ / _false_ 之间切换；**写入自定义值** 会写入指定值（需与节点的 Datapoint 类型兼容）。|
| 切换初始状态 | （仅布尔型 Datapoint）定义切换模式的起始值。节点会根据接收到的 KNX 报文自动更新状态。|
| 自定义值 | “写入自定义值” 模式所使用的载荷。支持任何 JSON 字面量，例如 `42`、`true`、`"文本"` 或 `{ "red": 255 }`。|
仅在启用该选项时才会显示按钮。若节点处于通用模式，则读取操作被禁用，因为节点没有固定的组地址。
<br/>
<br/>
## TAB 高级选项
|属性|说明|
|--|--|
|| **通用** |
| 节点名称 | 显示名。|
| Topic | 输出消息的 topic。留空则使用组地址。|
| Passthrough | 将输入消息透传到输出。|
|| **节点输入 → KNX 总线** |
| Telegram 类型 | `write` 发送写报文（常用）；也可选择响应其他类型。|
| RBE 过滤 | 按变化上报。启用后，仅当值变化时才发送到总线。需要重复发送相同值时请关闭。启用后在节点名中显示 "rbe”。|
| 周期发送已存储的值 | 启用后，节点会按设定间隔将最后一次存储的值作为 _write_ 报文周期发送到 KNX 总线。该功能会刻意绕过输出侧 RBE。|
| 周期发送间隔 | 周期发送的间隔（秒）。|
|| **KNX 总线 → 节点输出** |
| 启动时读取状态 | 在 Node-RED 启动及每次重连时读取 GA 状态。节点会缓存值到文件，可选择从文件或总线读取。|
| RBE 过滤 | 同上，但作用于输出到流程。|
| 响应写报文 | 收到写报文时向流程输出一条消息。|
| 响应应答报文 | 收到应答报文时向流程输出。|
| 响应读报文 | 收到读报文时向流程输出（用于自定义返回值）。|
| Multiply/Decimals/Negatives | 数值缩放、四舍五入、小数与负值处理（仅数值）。|
<br/>
<br/>
## TAB KNX Function
可使用 JavaScript 自定义：对来自流程的输入消息、以及发送到总线的报文的处理逻辑。编辑器提供若干对象/函数，用于读取任意 GA 的值：导入 ETS 时可不指定 DPT，未导入则需指定 DPT。
脚本在每次收到输入消息或总线报文时执行。启用后，节点名会显示 "f(x)”。
|属性|说明|
|--|--|
| Search GA | 仅在已导入 ETS 时可用：输入并选择 GA，然后将完整字段粘贴到 `getGAValue` 中。|
### 可用对象/函数
|对象/函数|说明|
|--|--|
| `msg` | 当前消息对象。|
| `getGAValue(GA, DPT?, readIfMissing?)` | 读取 GA 的值，例如 `'1/0/1'` 或 `'1/0/1 Bed table light'`（空格后的文字会被忽略）。导入 ETS 后，DPT 为可选；未导入时则必须提供。默认情况下，如果缓存中没有该值，函数会发送一个 `GroupValue_Read` 并等待响应。若将第三个参数设为 `false`，或者在不需要 DPT 时将第二个参数设为 `false`，则函数只使用缓存；如果本地没有值，则返回 `undefined`。`getGAValue` 是异步的，所以当你需要真实值时，应写成 `await getGAValue(...)`。即使使用只读缓存模式，也要保留 `await`：不加 `await` 得到的是 Promise 对象，不是 GA 的值。|
| `setGAValue(GA, value, DPT?)` | 设置 GA 值；DPT 同上。|
| `self(value)` | 设置当前节点的值并发送到总线（注意循环）。|
| `toggle()` | 切换当前值并发送到总线。|
| `node`, `RED`, `return(msg)` | 节点对象，RED 对象，返回消息以继续流转。|
### 示例（流程 → 总线）
```javascript
const statusGA = await getGAValue('0/0/09','1.001');
if (msg.payload !== statusGA){ return msg; } else { return; }
```
```javascript
if (msg.payload){
setGAValue('0/1/8', true)
setTimeout(function(){ self(off); }, 2000);
}
return msg;
```
### 示例（总线 → 输出）
```javascript
msg.externalTemperature = await getGAValue('0/0/10'); // 未导入 ETS：await getGAValue('0/0/10','9.001')
return msg;
```
```javascript
const otherGA = await getGAValue('0/0/11','1.001');
if (msg.payload === false && otherGA === false){ return; } else { return msg; }
```
### 输入（Inputs）
- **destination (string)**：三层组地址，如 `1/1/0`
- **payload (any)**：要发送的值
- **event (string)**：`GroupValue_Write` / `GroupValue_Response` / `Update_NoWrite`（`Update_NoWrite` 仅更新内部值，不发送）
- **readstatus (boolean)**：向总线发起读取（使用 `msg.readstatus = true`）
- **dpt (string)**：如 `1.001`
- **writeraw (buffer)** + **bitlength (int)**：发送 RAW，`bitlength` 为比特长度（为兼容旧流程，`bitlenght` 仍然可用）
- **resetRBE (boolean)**：重置内部 RBE 过滤（`msg.resetRBE = true`）
- **setConfig (json)**：通过消息修改节点的 GA 与 DPT
### setConfig 详情
```javascript
var config= { setGroupAddress: "0/1/2", setDPT: "1.001" };
msg.setConfig = config; return msg;
```
```javascript
var config= { setGroupAddress: "0/1/2", setDPT: "auto" };
msg.setConfig = config; return msg;
```
### 输出（Outputs）
1. 标准输出：PIN1 上的 `payload`。
2. 错误：PIN2 上的 `error`（详细错误）。
### 输出消息示例
```javascript
msg = {
topic: "0/1/2",
payload: false,
previouspayload: true,
payloadmeasureunit: "%",
payloadsubtypevalue: "Start",
devicename: "餐桌灯",
gainfo: {
maingroupname: "Light actuators",
middlegroupname: "First flow lights",
ganame: "Table Light",
maingroupnumber: "1",
middlegroupnumber: "1",
ganumber: "0"
},
echoed: true,
knx: {
event: "GroupValue_Write",
dpt: "1.001",
dptdesc: "Humidity",
source: "15.15.22",
destination: "0/1/2",
rawValue: "<buffer>"
}
}
```
---
# 流程输入消息（INPUT FLOW MESSAGE）
## 控制 KNX 设备
节点会将来自流程的消息发送到 KNX 总线；当总线有报文到达时也会输出到流程。除 `payload` 外，下列属性均为可选。
- **msg.destination**：如 `0/0/1`
- **msg.payload**：如 `true/false/21/"Hello"`
- **msg.event**：`Write`/`Response`/`Update_NoWrite`（当为 `Update_NoWrite` 时，所有相同 GA 的节点都会向流程输出包含 `event: 'Update_NoWrite'` 的消息）
需要"读取”时请使用 `msg.readstatus = true`。
- **msg.readstatus = true**：向总线发起读取
- **msg.dpt**：如 `1.001`（也接受 `9`、`"9"`、`"DPT9.001"`）
- **msg.dpt = raw**：保持收到的报文不做解码；`msg.payload` 将为 `null`，原始字节可在 `msg.knx.rawValue` 中获取。发送 RAW 时请使用 `msg.writeraw`
- **msg.writeraw** + **msg.bitlength**：发送 RAW；会忽略节点上设置的 DPT
- **msg.resetRBE = true**：重置 RBE 过滤
## 通过消息修改配置
[示例页请见此处](https://supergiovane.github.io/node-red-contrib-knx-ultimate/wiki/-Sample-setConfig)
---
# 快速上手（QUICK HOW TO）
更多示例见：[SamplesHome](https://supergiovane.github.io/node-red-contrib-knx-ultimate/wiki/-SamplesHome)
**打开灯**
```javascript
msg.payload = true; return msg;
```
**绝对调光**
```javascript
msg.payload = 30; return msg;
```
**向显示屏发送文本**
```javascript
msg.payload = "Output Tem. 35°C"; return msg;
```
**读取状态**
```javascript
// 发送读取请求；需在节点上勾选"React to response telegrams”以接收应答
msg.readstatus = true; return msg;
```
**发送 RAW 到总线**
```javascript
// DPT1 示例：开灯 = Buffer<01>，bitlength = 1
msg.writeraw = Buffer.from('01','hex');
msg.bitlength = 1; return msg;
// 温度（DPT9）示例：18.4 °C = <0730>
// msg.writeraw = Buffer.from('0730','hex'); return msg;
```
</script>