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

<script type="text/markdown" data-help-name="knxUltimate">
## KNX-ULTIMATE GERÄTE-NODE EINSTELLUNGEN

Dieser Node steuert eine KNX-Gruppenadresse und ist der am häufigsten verwendete.

[<i class="fa fa-code"></i> Beispiele findest du hier](https://supergiovane.github.io/node-red-contrib-knx-ultimate/wiki/-SamplesHome)

**Konfiguration**

|Eigenschaft|Beschreibung|
|--|--|
| Gateway | Zu verwendendes KNX-Gateway auswählen |
| GA-Typ (Dropdown) | Typ der Gruppenadresse. **3-Ebenen** ist Standard (Eingabe der 3-stufigen GA oder GA-Bezeichnung, sofern ETS importiert). **Global** liest die GA beim Start aus einer globalen Variablen, **Flow** analog auf Flow-Ebene. **$Env variable** liest die GA aus einer Umgebungsvariable. **Universeller Modus (alle GAs abhören)** reagiert auf ALLE Gruppenadressen. |
| Gruppenadresse | Zu steuernde Gruppenadresse. Mit importierter ETS kannst du den Gerätenamen tippen. Kann leer bleiben, wenn du sie per `msg.setConfig` setzt. |
| Datenpunkt | Der zum Node gehörende Datapoint. |

<br/>
<br/>

### Manueller Befehlsbutton

Im Editor kann pro Node ein kleiner Button angezeigt werden, über den du KNX-Telegramme ohne zusätzlichen Inject-Knoten auslösen kannst.

|Eigenschaft|Beschreibung|
|--|--|
| Manuellen Button anzeigen | Blendet den Button im Workspace und in der Knotenliste ein bzw. aus. |
| Schaltflächenaktion | Legt fest, was beim Klick geschieht. **KNX Read senden** erzeugt ein normales Read-Telegramm. **Toggle boolean** steht bei DPT 1.x zur Verfügung und wechselt zwischen _true_ und _false_. **Benutzerdefinierten Wert schreiben** sendet den angegebenen Wert (muss zum eingestellten Datapoint passen). |
| Initialer Toggle-Status | (Nur für boolesche Datapoints) Startwert der Toggle-Funktion. Der Zustand bleibt mit den ankommenden KNX-Telegrammen synchron. |
| Benutzerdefinierter Wert | Wert für den Modus „Benutzerdefinierten Wert schreiben“. Erlaubt sind JSON-Literale wie `42`, `true`, `"Text"` oder `{ "red": 255 }`. |

Der Button wird nur eingeblendet, wenn die Option aktiv ist. Im Universalmodus ist die Leseaktion deaktiviert, da keine feste Gruppenadresse vorhanden ist.

<br/>
<br/>

## TAB Erweiterte Optionen

|Eigenschaft|Beschreibung|
|--|--|
|| **Allgemein** |
| Node-Name | Anzeigename. |
| Topic | Topic der Ausgabe. Leer lassen, um die Gruppenadresse zu verwenden. |
| Passthrough | Leitet die Eingangs-Nachricht an den Ausgang weiter. |
|| **Vom Node-EINGANG zum KNX-BUS** |
| Telegrammtyp | `write` zum Senden eines Schreib-Telegramms (üblich), alternativ Reaktion auf andere Typen. |
| RBE-Filter | "Report by change". Wenn aktiv, sendet nur geänderte Werte zum BUS. Für identische Wiederholungen deaktivieren. Bei Aktivierung wird "rbe" dem Nodename hinzugefügt. |
| Periodisches Senden (gespeicherter Wert) | Wenn aktiv, sendet der Node den zuletzt gespeicherten Wert in festen Intervallen als _write_-Telegramm auf den KNX-Bus. Diese Option umgeht absichtlich den Output-RBE. |
| Intervall periodisches Senden | Intervall in Sekunden für das periodische Senden. |
|| **Vom KNX-BUS zum Node-AUSGANG** |
| Status beim Start lesen | Liest den GA-Status bei Editorstart und jeder Wiederverbindung. Werte werden in einer Datei gepuffert, Quelle wählbar (Datei/BUS). |
| RBE-Filter | Wie oben, aber für Ausgaben zum Flow. |
| Auf Schreib-Telegramme reagieren | Sendet bei eingehendem Write eine Nachricht an den Flow. |
| Auf Response-Telegramme reagieren | Sendet bei Response eine Nachricht an den Flow. |
| Auf Lese-Telegramme reagieren | Sendet bei Read eine Nachricht an den Flow (z. B. um eigene Werte zu liefern). |
| Multiply/Decimals/Negatives | Skaliert, rundet und behandelt negative Werte (nur numerische Werte). |

<br/>
<br/>

## TAB KNX Function

Mit JavaScript kannst du das Verhalten eingehender Nachrichten (vom Flow) und ausgehender Telegramme (zum BUS) anpassen. Der Editor stellt Hilfsobjekte und -funktionen bereit, um GA-Werte zu lesen - mit ETS (ohne DPT) oder ohne ETS (mit DPT).
Der Code läuft bei jeder Eingangs-Nachricht und bei jedem BUS-Telegramm. Bei Aktivierung erscheint "f(x)" im Nodename.

|Eigenschaft|Beschreibung|
|--|--|
| Search GA | Nur mit importierter ETS: tippen, GA wählen und das Feld in `getGAValue` einfügen. |

### Verfügbare Objekte/Funktionen

|Objekt/Funktion|Beschreibung|
|--|--|
| `msg` | Aktuelle Nachricht. |
| `getGAValue(GA, DPT?, readIfMissing?)` | Liest den Wert einer GA, z. B. `'1/0/1'` oder `'1/0/1 Bed table light'` (Text nach Leerzeichen wird ignoriert). Mit importierter ETS ist DPT optional; sonst muss es angegeben werden. Standardmäßig sendet die Funktion bei fehlendem Cache-Wert ein `GroupValue_Read` und wartet auf die Antwort. Mit `false` als drittem Parameter, oder als zweitem wenn kein DPT nötig ist, arbeitet die Funktion nur mit dem Cache und liefert `undefined`, wenn lokal kein Wert vorhanden ist. `getGAValue` ist asynchron, daher solltest du `await getGAValue(...)` verwenden, wenn du den echten Wert brauchst. Auch im Cache-only-Modus bleibt `await` erforderlich: ohne `await` erhältst du ein Promise-Objekt statt des GA-Werts. |
| `setGAValue(GA, value, DPT?)` | Setzt den Wert der GA; DPT wie oben. |
| `self(value)` | Setzt den eigenen Node-Wert und sendet ihn an den BUS (Achtung Schleifen). |
| `toggle()` | Toggeln wie `self`. |
| `node`, `RED`, `return(msg)` | Node-Objekt, RED-Objekt, Rückgabe der Nachricht. |

### Beispiele (Flow → BUS)

```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;
```

### Beispiele (BUS → Ausgang)

```javascript

msg.externalTemperature = await getGAValue('0/0/10'); // ohne 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)**: 3-stufige GA, z. B. `1/1/0`
- **payload (any)**: zu sendender Wert
- **event (string)**: `GroupValue_Write`, `GroupValue_Response`, `Update_NoWrite` (nur interner Wert, kein BUS-Senden)
- **readstatus (boolean)**: Leseauftrag an den BUS
- **dpt (string)**: z. B. `1.001`
- **writeraw (buffer)** + **bitlength (int)**: RAW-Senden; `bitlength` in Bit (`bitlenght` wird aus Kompatibilitaetsgruenden weiterhin akzeptiert)
- **resetRBE (boolean)**: RBE-Filter zurücksetzen
- **setConfig (json)**: GA/DPT des Nodes per Nachricht ändern

### setConfig Details

```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. Standardausgang: `payload` am PIN 1.
2. Fehler: `error` am PIN 2.

### Ausgehende Nachricht (Beispiel)

```javascript

msg = {
  topic: "0/1/2",
  payload: false,
  previouspayload: true,
  payloadmeasureunit: "%",
  payloadsubtypevalue: "Start",
  devicename: "Esstischlampe",
  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>"
  }
}
```

---

# EINGANGS-NACHRICHT AUS DEM FLOW

## KNX-Geräte steuern

Der Node nimmt Nachrichten entgegen und sendet sie auf den KNX-BUS; eingehende BUS-Telegramme werden als Nachrichten an den Flow ausgegeben. Alle Eigenschaften optional, außer `payload`.

- **msg.destination**: z. B. `0/0/1`
- **msg.payload**: z. B. `true/false/21/"Hello"`
- **msg.event**: `GroupValue_Write`/`GroupValue_Response`/`Update_NoWrite` (bei `Update_NoWrite` geben alle Nodes mit derselben GA eine Meldung mit `event: 'Update_NoWrite'` aus)

Für Read statt `event` bitte `msg.readstatus = true` verwenden.

- **msg.readstatus = true**: Read an den BUS
- **msg.dpt**: z. B. `1.001` (auch `9`, `"9"`, `"DPT9.001"`)
- **msg.dpt = raw**: eingehende Telegramme bleiben undekodiert; `msg.payload` ist `null` und die Bytes stehen in `msg.knx.rawValue`. Zum Senden von RAW-Telegrammen `msg.writeraw` verwenden
- **msg.writeraw** + **msg.bitlength**: RAW-Senden; ignoriert den am Node gesetzten DPT
- **msg.resetRBE = true**: RBE-Filter zurücksetzen

## Konfiguration per Nachricht ändern

[Siehe Beispielseite.](https://supergiovane.github.io/node-red-contrib-knx-ultimate/wiki/-Sample-setConfig)

---

# QUICK HOW TO

Weitere Beispiele [hier](https://supergiovane.github.io/node-red-contrib-knx-ultimate/wiki/-SamplesHome)

**LAMPE EINSCHALTEN**

```javascript

msg.payload = true; return msg;
```

**ABSOLUTES DIMMEN**

```javascript

msg.payload = 30; return msg;
```

**TEXT AN DISPLAY**

```javascript

msg.payload = "Output Tem. 35°C"; return msg;
```

**STATUS LESEN**

```javascript

msg.readstatus = true; return msg;
```

**RAW AN BUS SENDEN**

```javascript

msg.writeraw = Buffer.from('01','hex');
msg.bitlength = 1; return msg;
// Temperatur (DPT9): 18.4 °C = <0730>
// msg.writeraw = Buffer.from('0730','hex'); return msg;
```

</script>