node-red-contrib-knx-ultimate/nodes/locales/zh-CN/knxUltimate.html

Control your KNX and KNX Secure intallation via Node-Red! A bunch of KNX nodes, with integrated Philips HUE control, ETS group address importer, and KNX routing between interfaces. Easy to use and highly configurable.

<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?)` | 读取 GA 值，如 `'1/0/1'` 或 `'1/0/1 Bed table light'`（空格后的文字被忽略）。未导入 ETS 时需提供 DPT。|
| `setGAValue(GA, value, DPT?)` | 设置 GA 值；DPT 同上。|
| `self(value)` | 设置当前节点的值并发送到总线（注意循环）。|
| `toggle()` | 切换当前值并发送到总线。|
| `node`, `RED`, `return(msg)` | 节点对象，RED 对象，返回消息以继续流转。|

### 示例（流程 → 总线）

```javascript

const statusGA = 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 = getGAValue('0/0/10'); // 未导入 ETS：getGAValue('0/0/10','9.001')
return msg;
```

```javascript
if (msg.payload === false && getGAValue('0/0/11','1.001') === 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)** + **bitlenght (int)**：发送 RAW，`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.writeraw** + **msg.bitlenght**：发送 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.bitlenght = 1; return msg;
// 温度（DPT9）示例：18.4 °C = <0730>
// msg.writeraw = Buffer.from('0730','hex'); return msg;
```

</script>