# Konventionen und Beispiele für Encoder-/Decoder-Formate

BuildingPro Suites bietet leistungsstarke Werkzeuge wie **JSONPath** und **MQTT-Wildcards** um eingehende Daten dynamisch und präzise den richtigen Assets zuzuordnen. Während JSONPath eine flexible Auswahl von Werten aus JSON-Daten ermöglicht, erlauben MQTT-Wildcards die Verwendung dynamischer Werte aus Topic-Strukturen. Diese Dokumentation zeigt, wie Sie beide Methoden effektiv nutzen können, um Ihre Datenverarbeitung zu optimieren.

***

## JSONPath-Konvention

JSONPath ist eine Syntax zum Auswählen und Verarbeiten von Werten in einem JSON-Dokument. Die grundlegende Struktur und die Symbole von JSONPath:

1. **`$`**: Der Wurzelknoten des JSON-Dokuments.
2. **`.`**: Zugriff auf ein untergeordnetes Element.
3. **`[]`**: Ermöglicht den Zugriff auf ein Element über einen Index oder eine Bedingung.
4. **`?()`**: Filterausdruck zum Auswählen von Elementen basierend auf einer Bedingung.
5. **`@`**: Repräsentiert das aktuelle Element im Filterausdruck.
6. **`*`**: Platzhalter zum Auswählen aller Elemente eines Arrays oder Objekts.
7. **`..`**: Rekursiver Zugriff, um alle Vorkommen eines bestimmten Namens in der Hierarchie zu finden.

***

## Beispiel 1: Einfache Abfrage aus einer JSON-Nutzlast

**JSON-Daten:**

\[hier kommt der Code hin]

**JSONPath-Abfragen und Ergebnisse:**

1. **Alle Gerätedaten abfragen**: **JSONPath**: `$.devices[*]` **Ergebnis**:

   \[hier kommt der Code hin]
2. **Die Temperatur aller Geräte abfragen**: **JSONPath**: `$.devices[*].wifiSwitchTemp` **Ergebnis**:

   \[hier kommt der Code hin]
3. **Ein Gerät mit einer bestimmten ID abfragen**: **JSONPath**: `$.devices[?(@.id=="A8032A13B850")]` **Ergebnis**:

   \[hier kommt der Code hin]
4. **Nur die Temperatur eines bestimmten Geräts abfragen**: **JSONPath**: `$.devices[?(@.id=="A8032A13B850")].wifiSwitchTemp` **Ergebnis**:

\[hier kommt der Code hin]

<figure><img src="https://3489494878-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9GvUpaatBiReR43XFSMg%2Fuploads%2F7ah3wD056uspgpzMiyCZ%2Fimage.png?alt=media&#x26;token=74d2b880-4efc-48dc-b71b-5c25a22a5b5d" alt=""><figcaption><p>Beispiel, wenn Sie ein bestimmtes Gerät wünschen.</p></figcaption></figure>

***

## Beispiel: Funktion zur Generierung einer GAI/Associated ID, wenn die Nutzlast keinen Bezeichner enthält

Wenn eine eingehende Nutzlast keinen eindeutigen Bezeichner enthält oder der Bezeichner von mehreren Elementen in der Nutzlast abhängt, kann eine benutzerdefinierte Funktion verwendet werden, um den Bezeichner zu erzeugen.

### Szenario: Kein Bezeichner in der Nutzlast

Stellen Sie sich das folgende Beispiel für eine Nutzlast vor:

\[hier kommt der Code hin]

In diesem Beispiel enthält die Nutzlast keinen direkten Bezeichner, da es mehrere WiFi-Schalter geben könnte, aber die Kombination aus **Gebäude**, **Stockwerk**, und **Raum** kann verwendet werden, um einen eindeutigen Bezeichner zu erstellen.

### Lösung: Eine Funktion erstellen

Verwenden Sie eine benutzerdefinierte Funktion in BuildingPro Suites, um den Bezeichner aus den Komponenten der Nutzlast zu generieren.

**Codebeispiel: Bezeichner aus mehreren Feldern generieren**

\[hier kommt der Code hin]

***

#### Konfiguration in BuildingPro Suites

1. **Funktion erstellen:**
   * Gehen Sie zur **"Create function"** Option im Menü.
   * Geben Sie der Funktion einen Namen, z. B. `parsePayloadCustom`.
   * Fügen Sie den obigen Code in den **Code-Editor**.
2. **Funktion mit einem Format verbinden:**
   * Wählen Sie im Menü "Configure Format" das entsprechende Format aus.
   * Fügen Sie die Funktion mit der Schaltfläche **"Append function"** hinzu.
3. **Bezeichner verwenden:**

   * Das Format verwendet den generierten Bezeichner (`eliona.uin`) um eingehende Daten dem richtigen Asset zuzuordnen. Dafür kann je nach gewünschter Position der ID entweder **External für die associated ID oder GAI** ausgewählt werden.

   <img src="https://3489494878-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9GvUpaatBiReR43XFSMg%2Fuploads%2FjiRRXVxt62vfQCkVHTrj%2Fimage.png?alt=media&#x26;token=8852cac4-2196-424e-a4e3-5ea4fc9e3350" alt="" data-size="original">

***

## MQTT-Wildcards für die Erstellung von GAI/Associated ID verwenden

### **MQTT-Topic-Struktur im Beispiel:**

\[hier kommt der Code hin]

### **Wildcards in MQTT**

MQTT unterstützt zwei Wildcard-Typen, die in den Topics verwendet werden können:

1. **`+` (Single-Level-Wildcard)**
   * Repräsentiert "alle Werte auf dieser Topic-Ebene."
   * Beispiel: Das Topic `building_01/+/room_01` passt zu den folgenden Topics:
     * `building_01/floor_01/room_01`
     * `building_01/floor_02/room_01`
2. **`#` (Multi-Level-Wildcard)**
   * Repräsentiert "alle Werte ab dieser Ebene und darunter."
   * Kann **nur am Ende** eines Topics verwendet werden.
   * Beispiel: Das Topic `building_01/#` passt zu den folgenden Topics:
     * `building_01/floor_01`
     * `building_01/floor_01/room_01`
     * `building_01/floor_02/room_02`

***

### **So funktionieren MQTT-Wildcards**

* **`+` Wildcard:** Jede `+` Wildcard ersetzt genau einen Teil des Topics. Wenn es mehrere `+` Wildcards in einem Topic gibt, können Sie in BuildingPro Suites mit Zahlen darauf zugreifen (`1`, `2`, usw.). Beispiel: Im Topic `building_01/+/+`steht es für:
  * `1`: der erste Teil, der durch `+`.
  * `2`: der zweite Teil, der durch `+`.
* **`#` Wildcard:** Erfasst alle Werte und Ebenen ab der Position, an der es steht. Alles, was an die Stelle von `#` im Topic tritt, kann direkt über `#` in BuildingPro Suites referenziert werden.

***

### **Beispiele für die Verwendung von MQTT-Wildcards**

#### **Beispiel 1: Verwendung von `#` zum Erfassen von Räumen**

**Abonnement-Topic:** `building_01/#`

**Empfangene Nachricht:** `building_01/floor_01/room_01`

**Konfiguration in BuildingPro Suites:**

* **Bezeichner**: `#`

**Ergebnis:** Das Topic `floor_01/room_01` wird als GAI/Associated ID verwendet.

***

### **Beispiel 2: Verwendung von `+` um eine Ebene zu identifizieren**

**Abonnement-Topic:** `building_01/+/room_01`

**Empfangene Nachricht:** `building_01/floor_02/room_01`

**Konfiguration in BuildingPro Suites:**

* **Bezeichner**: `1`

**Ergebnis:** Der Wert `floor_02` (die Ebene, die durch das erste `+`ersetzt wurde) wird als GAI/Associated ID verwendet.

***

### **Beispiel 3: Kombination von `+` und `#` zum Erfassen mehrerer Ebenen**

**Abonnement-Topic:** `building_01/+/+/#`

**Empfangene Nachricht:** `building_01/floor_01/room_02/sensor_01`

**Konfiguration in BuildingPro Suites:**

* **Bezeichner**:
  * `1` → `floor_01` (erstes `+` Wildcard)
  * `2` → `room_02` (zweites `+` Wildcard)
  * `#` → `sensor_01` (alle Werte, die `#`)

**Ergebnis:** Die Werte `floor_01`, `room_02`, und `sensor_01` können einzeln als GAI/Associated ID verwendet werden.

***

## **Wichtige Hinweise**

1. **MQTT-Wildcards funktionieren nur mit dem Topic-Modus:** Wählen Sie bei der Identifizierung **"Topic"** wie im folgenden Bild gezeigt:

   <figure><img src="https://3489494878-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9GvUpaatBiReR43XFSMg%2Fuploads%2FRdNeTJgkVp3OyorkKM5J%2Fimage.png?alt=media&#x26;token=9ebdb53d-1f78-424e-b35b-43adfffe1b58" alt=""><figcaption></figcaption></figure>
2. **Automatische Verarbeitung in BuildingPro Suites:**
   * BuildingPro Suites ersetzt Wildcards automatisch durch die tatsächlichen Werte des Topics.
   * Es ist keine zusätzliche Verarbeitung erforderlich.
3. **Beachten Sie die Nummerierung der `+` Wildcards:**
   * Verwenden Sie die entsprechende Nummer (`1`, `2`, usw.), um auf die spezifischen Werte zuzugreifen.