node-red-contrib-knx-ultimate/nodes/locales/zh-CN/knxUltimateIoTBridge.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, KNX AI for diagnosticsand KNX routing between interfaces. Easy to use and highly configurable.

<script type="text/markdown" data-help-name="knxUltimateIoTBridge">
# MQTT Home Assistant - IoT

在 KNX 组地址与 IoT 通道（MQTT 主题、REST 接口、Modbus 寄存器）之间创建双向桥接。每条映射都可以对数值进行缩放、格式化载荷，并向后续节点暴露元数据。

> **两种模式。** 使用节点顶部的**模式**选择器：
> - **IoT 桥接**（默认）— 下文描述的经典行为（映射列表，MQTT/REST/Modbus 输出消息）。
> - **MQTT / Home Assistant（原生）** — 节点直接连接 MQTT broker，在 KNX ↔ MQTT 之间双向桥接，并发布 Home Assistant MQTT 自动发现，使实体自动出现。

## MQTT / Home Assistant 模式

带 Home Assistant 自动发现的原生 MQTT 桥接。需要一个 Node-RED 和 Home Assistant 都能访问的 MQTT broker，并在 HA 中启用 MQTT 集成。所有实体都出现在以该节点命名的同一个设备下。

- **KNX 总线连接** — 节点如何与 KNX 交换报文：
    - *独立*（默认）— 节点直接与 KNX 网关通信，没有输入/输出端口。
    - *流消息* — 节点显示一个输入端口和一个输出端口。将一个**通用**模式的 KNXUltimate 节点的输出连接到输入端口（KNX 总线 → MQTT），并将输出端口连接到另一个**通用**模式 KNXUltimate 节点的输入（MQTT → KNX 总线）。
- **Broker URL / 用户名 / 密码** — 连接到你的 MQTT broker。
- **基础主题 / 自动发现前缀** — 状态/命令主题的根主题以及 HA 自动发现前缀（默认 `homeassistant`）。
- **要暴露的组地址** — KNX 网关中导入的每个地址（ETS 列表）都带有一个复选框。勾选的地址会作为 Home Assistant 实体发布，并根据 DPT 自动分类（switch、sensor、binary_sensor、number、text）。可使用筛选框和*全选* / *全不选*按钮。默认全部选中。每一行还有一个**只读**开关：只读地址仍会发布到 Home Assistant（状态保持可见），但绝不接受回写到 KNX 总线的命令（switch 变为 binary_sensor，number 变为 sensor）。*设为只读* / *取消只读*按钮会将其应用到当前显示的所有地址。
- **卷帘与温控器** — 将多个地址组合成一个实体：
    - *卷帘*：上/下 GA (1.008)、可选停止 GA (1.007)、可选位置 设置/状态 GA (5.001)。*反转位置* 将 KNX 约定（0% = 打开）映射到 Home Assistant（100% = 打开）。
    - *温控器*：当前温度 GA (9.001)、设定值 设置/状态 GA (9.001)、可选开/关 GA (1.001 → off/heat)，以及最低/最高温度和步长。

KNX 总线的值会发布到 MQTT，可写的数据点接受来自 Home Assistant 的命令。数据点类型在可用时取自导入的 ETS 列表，否则取自 KNX 默认值（1.008 上/下、1.007 停止、5.001 位置、9.001 温度、1.001 开/关）；为获得可靠的状态反馈，卷帘/温控器使用的地址应包含在 ETS 导入中。

---

本帮助的其余部分描述经典的 **IoT 桥接**模式。

## 输入

|属性|说明|
|--|--|
| Flow 输入 | 启用后，`topic` 或 `msg.bridge` 匹配映射的消息会被转换为 KNX 载荷并写入总线。|
| KNX 电报 | 接收到的电报会与配置的 GA 列表匹配，并作为桥接事件输出。读取请求在返回值之前会被忽略。|

## 输出

|输出|说明|
|--|--|
| 1（KNX → IoT） | 输出转换后的数值，以及 `msg.bridge` 元数据（通道类型、目标、缩放）和 `msg.knx` 细节（GA、DPT、来源、事件）。|
| 2（IoT → KNX ack） | 当 Flow 发起写入时，确认已写入的 GA 和实际写入的载荷。|

## 映射字段

- **方向** — 选择 KNX→IoT、IoT→KNX 或双向。
- **通道类型** — MQTT 将目标视为主题；REST 将其视为基础 URL；Modbus 视为寄存器标识。
- **缩放 & 偏移** — 应用于 KNX→IoT；在 IoT→KNX 时使用逆向变换。
- **模板** — 可选字符串，可替换 `{{value}}`、`{{ga}}`、`{{label}}`、`{{target}}`、`{{type}}`、`{{isoTimestamp}}`。
- **超时 / 重试** — 信息字段，用于告知下游节点应如何处理重试和时间窗口。

## 使用提示

- 在输出&nbsp;1 后串联传输节点（例如核心 `mqtt out`、`http request`，或社区包 `node-red-contrib-modbus` 的 `modbus-flex-write` 节点）。
- 使用 `switch` 节点按 `msg.bridge.type` 区分通道，或按 `msg.bridge.id` 实现每条映射的逻辑。
- 启用 *部署时读取 KNX 数值* 以在重新部署后填充仪表盘。

## 传输示例

### KNX → MQTT 发布

1. 配置映射：`方向 = 双向`、`类型 = MQTT`、`目标 = knx/status/light1`。
2. 将输出&nbsp;1 连接到配置好的 `mqtt out` 节点。
3. 每当 GA 变化时，桥接节点会输出：

```

{
  "topic": "knx/status/light1",
  "payload": true,
  "bridge": { "type": "mqtt", "id": "..." },
  "knx": { "ga": "1/1/10", "event": "GroupValue_Write" }
}
```

### MQTT 指令 → KNX 写入

1. 设定 `方向 = 双向`、`类型 = MQTT`、`目标 = knx/cmd/light1`。
2. 将同一主题的 `mqtt in` 节点连接到桥接输入。
3. 向 `knx/cmd/light1` 发布 `false`；桥接节点会向配置的 GA 写入 `0` 并在第 2 引脚输出确认。

### REST Webhook 快照

1. 配置 `方向 = KNX → IoT`、`类型 = REST`、`目标 = https://example/api/knx/light1`，以及 `模板 = {"value":{{value}},"ga":"{{ga}}"}`。
2. 将输出&nbsp;1 接入 `http request` 节点（请求方法来自 `bridge.method`）。
3. 可以将响应转发给仪表盘或日志。

### Modbus 寄存器同步

- 将桥接节点与 `node-red-contrib-modbus` 的 `modbus-flex-write` 节点配合使用。输出&nbsp;1 会在 `msg.address` 中携带 Modbus 地址，在 `msg.payload` 中携带数值。

## 示例 Flow

导入以下最小 Flow 并按需调整 GA/Topic：

```json

[
  {
    "id": "bridge1",
    "type": "knxUltimateIoTBridge",
    "z": "flow1",
    "server": "gateway1",
    "name": "灯光桥接",
    "outputtopic": "",
    "emitOnChangeOnly": true,
    "readOnDeploy": true,
    "acceptFlowInput": true,
    "mappings": [
      {
        "id": "map-light",
        "enabled": true,
        "label": "客厅灯",
        "ga": "1/1/10",
        "dpt": "1.001",
        "direction": "bidirectional",
        "iotType": "mqtt",
        "target": "knx/light/living",
        "method": "POST",
        "modbusFunction": "writeHoldingRegister",
        "scale": 1,
        "offset": 0,
        "template": "{{value}}",
        "property": "",
        "timeout": 0,
        "retry": 0
      }
    ],
    "wires": [["mqttOut1"],["debugAck"]]
  },
  {
    "id": "mqttOut1",
    "type": "mqtt out",
    "z": "flow1",
    "name": "MQTT 状态",
    "topic": "",
    "qos": "0",
    "retain": "false",
    "broker": "mqttBroker",
    "x": 530,
    "y": 120,
    "wires": []
  },
  {
    "id": "mqttIn1",
    "type": "mqtt in",
    "z": "flow1",
    "name": "MQTT 指令",
    "topic": "knx/light/living/set",
    "qos": "1",
    "datatype": "auto",
    "broker": "mqttBroker",
    "x": 120,
    "y": 180,
    "wires": [["bridge1"]]
  },
  {
    "id": "debugAck",
    "type": "debug",
    "z": "flow1",
    "name": "KNX 回执",
    "active": true,
    "tosidebar": true,
    "console": false,
    "tostatus": false,
    "complete": "true",
    "x": 540,
    "y": 180,
    "wires": []
  }
]
```

部署前请先在 Flow 中配置好 KNX 网关、MQTT Broker 以及需要的 Modbus 连接。

</script>