Encoder/Decoder Format Conventions and Examples

BuildingPro Suites offers powerful tools like JSONPath and MQTT Wildcards to dynamically and precisely assign incoming data to the correct assets. While JSONPath allows for flexible selection of values from JSON data, MQTT wildcards enable the use of dynamic values from topic structures. This documentation shows how you can effectively use both methods to optimize your data processing.

---

JSONPath Convention

JSONPath is a syntax for selecting and processing values in a JSON document. The basic structure and symbols of JSONPath:

1. $: The root node of the JSON document.

2. .: Access to a child element.

3. []: Allows access to an element by index or a condition.

4. ?(): Filter expression to select elements based on a condition.

5. @: Represents the current element in the filter expression.

6. *: Wildcard to select all elements of an array or object.

7. ..: Recursive access to find all instances of a specific name in the hierarchy.

---

Example 1: Simple Query from a JSON Payload

JSON Data:

[here goes the code]

JSONPath Queries and Results:

1. Query all device data: JSONPath: $.devices[*] Result:

   [here goes the code]

2. Query the temperature of all devices: JSONPath: $.devices[*].wifiSwitchTemp Result:

   [here goes the code]

3. Query a device with a specific ID: JSONPath: $.devices[?(@.id=="A8032A13B850")] Result:

   [here goes the code]

4. Query only the temperature of a specific device: JSONPath: $.devices[?(@.id=="A8032A13B850")].wifiSwitchTemp Result:

[here goes the code]

Example for when you want a specific device.

---

Example: Function for generating a GAI/Associated ID when the payload does not contain an identifier

If an incoming payload does not contain a unique identifier or the identifier depends on several elements in the payload, a custom function can be used to generate the identifier.

Scenario: No Identifier in the Payload

Let's imagine the following example for a payload:

[here goes the code]

In this example, the payload does not contain a direct identifier because there might be several WiFi switches, but the combination of building, floor, and room can be used to create a unique identifier.

Solution: Create a function

Use a custom function in BuildingPro Suites to generate the identifier from the components of the payload.

Code example: Generate identifier from multiple fields

[here goes the code]

---

Configuration in BuildingPro Suites

1. Create function:

   • Go to the "Create function" option in the menu.

   • Give the function a name, e.g., parsePayloadCustom.

   • Insert the code above into the Code Editor.

2. Connect function with a format:

   • In the "Configure Format" menu, select the corresponding format.

   • Add the function with the "Append function" button.

3. Use identifier:

   • The format uses the generated identifier (eliona.uin) to map incoming data to the correct asset. For this, either External for the associated ID or GAI can be selected depending on where you want the ID to be.

   

---

Using MQTT Wildcards for GAI/Associated ID Creation

MQTT Topic Structure in the example:

[here goes the code]

Wildcards in MQTT

MQTT supports two wildcard types that can be used in the topics:

1. + (Single-level wildcard)

   • Represents "all values at this topic level."

   • Example: The topic building_01/+/room_01 matches the following topics:

     • building_01/floor_01/room_01

     • building_01/floor_02/room_01

2. # (Multi-level wildcard)

   • Represents "all values from this level and below."

   • Can only be used at the end of a topic.

   • Example: The topic building_01/# matches the following topics:

     • building_01/floor_01

     • building_01/floor_01/room_01

     • building_01/floor_02/room_02

---

How MQTT wildcards work

• + wildcard: Each + wildcard replaces exactly one part of the topic. If there are several + wildcards in a topic, you can access them in BuildingPro Suites using numbers (1, 2, etc.). Example: In the topic building_01/+/+, it represents:

  • 1: the first part that was replaced by +.

  • 2: the second part that was replaced by +.

• # wildcard: Captures all values and levels from the position where it stands. Everything that takes the place of # in the topic can be referenced directly via # in BuildingPro Suites.

---

Examples of MQTT wildcard usage

Example 1: Using # to capture rooms

Subscription topic: building_01/#

Received message: building_01/floor_01/room_01

Configuration in BuildingPro Suites:

• Identifier: #

Result: The topic floor_01/room_01 is used as the GAI/Associated ID.

---

Example 2: Using + to identify a level

Subscription topic: building_01/+/room_01

Received message: building_01/floor_02/room_01

Configuration in BuildingPro Suites:

• Identifier: 1

Result: The value floor_02 (the level that was replaced by the first +) is used as the GAI/Associated ID.

---

Example 3: Combination of + and # to capture multiple levels

Subscription topic: building_01/+/+/#

Received message: building_01/floor_01/room_02/sensor_01

Configuration in BuildingPro Suites:

• Identifier:

  • 1 → floor_01 (first + wildcard)

  • 2 → room_02 (second + wildcard)

  • # → sensor_01 (all values that replace #)

Result: The values floor_01, room_02, and sensor_01 can be used individually as GAI/Associated ID.

---

Important Notes

1. MQTT wildcards only work with the topic mode: In the identification, select "Topic" as shown in the following image:

   
2. Automatic processing in BuildingPro Suites:

   • BuildingPro Suites automatically replaces wildcards with the actual values of the topic.

   • No additional processing is required.

3. Note the numbering of the + wildcards:

   • Use the corresponding number (1, 2, etc.) to access the specific values.