Lesson 2.7 External Data Sharing

In this lesson, we will explore how to share data outside the platform. There are three main methods:

1. HTTP Generic Webhooks: On an update event, the incoming data, delta, and changes are sent to a specified HTTP endpoint.
2. MQTT Generic: Data can be published on the platform’s own MQTT broker or reformatted and sent to an external broker via an MQTT connector.
3. Dedicated Connectors: Use a connector to send data directly to external services, such as building management systems like Delta Controls EnteliWeb or Siemens Desigo CC.

For this lesson, we will focus on the first two methods, which can be used directly within the platform without needing access to an external system.

To monitor the data being published with MQTT, we recommend using MQTT Explorer. It is a powerful tool for subscribing to MQTT topics and viewing exactly what data is being published and under which topic.

MQTT Data Sharing

MQTT is a flexible way to share data, and there are two main methods:

1. Publish on the platform’s MQTT broker using Channels, allowing other systems to subscribe to the data.
2. Publish directly to an external system’s MQTT broker.

MQTT Channels

When creating an MQTT channel, you need to decide how subscribers will authenticate. There are two options:

• Basic Credential Set: Uses a username and password. This is the most common and straightforward method.

  Security tip: Use a password with at least 14 mixed characters.

• API User Token: Uses a token from a Yggio API user. Tokens expire periodically and must be refreshed, which can be challenging for external systems.

  This method is the most secure and follows the standard OAuth flow. It is used in the Yggio UI for live data via MQTT websockets.

Create a Basic Credential Set

It is recommended to reuse the Basic Credential Set created in the previous lesson. If you do not have one, follow this guide to create a new set.

1. Open the Swagger Documentation. Click the book icon in the navigation bar and then Swagger. To run an endpoint, click Try it out.

2. Authentication options:

   • If logged in through an external IDP or with MFA enabled, /auth/local will not work. Instead, retrieve your token from your browser's developer tools:
     • Press F12 to open the debug window.
     • Navigate to Application → Cookies or Storage → Cookies.
     • Copy your token and use the Authorize button in Swagger. Paste the token into the prompt.
   • If you only have a password, go to /auth/local and enter your username and password in the correct fields.

3. Execute /users/me to verify your authentication.

4. Go to POST /basic-credentials-sets, replace the username and password placeholders with your actual credentials, and click Execute. This generates a Basic Credential Set. Copy the returned _id from the response:

{
  "_id": "123456789abcdef",
  "username": "My_basicCredentialsSet_Name"
}

5. Go to the device you want to monitor, or select multiple devices using Select Many. Open Channels and fill in the form:
   • Give the channel a descriptive Name.
   • In the Recipient field, paste your Basic Credential Set _id (use only letters and numbers, no quotes).
   • All incoming data from these devices will now be published on the platform’s MQTT broker, allowing external systems to subscribe and receive the data.

Check Your Channel Data

To view the data published on your channel, let's use MQTT Explorer.

1. Set up your MQTT connection in MQTT Explorer:
   • Update the platform URL to match your instance.
   • Enter your MQTT credentials.
   • Set the port to 8883 and enable Validate certificate and Encryption.

2. Click Advanced, remove the default root topic (#) and system topic ($SYS#), then add your specific topic. This must be done otherwise the platform will refuse your connection.

3. Add your topic to subscribe to, it should follow this format: yggio/output/v2/[Your Basic Credential Set ID]/iotnode/#

4. Click Connect. You should now see data published by the platform. Make sure your device gets an uplink to see data.

Use a MQTT Connector to Publish on an external service

In previous Lesson 2.6: Connectors we created an MQTT Connector to publish on external service and directed it to an incoming topic on the platforms MQTT broker.

5. To monitor the data you publish through the MQTT connector, configure MQTT explorer to subscribe to it.

• If youre using a new basicCredentialSet you need to set up a new connection by repeating the steps above.
• After credentials accurate add your reserved topic from previous lesson: yggio/generic/v2/[Your Reserved Topic]
• Go back to the User Guide: MQTT Connector and follow all the steps in Publishing Data with the Generic MQTT Connector to set up a Rule to publish data.

6. Click Connect again. You will now see both the data you subscribe to and the data you publish.

7. Once everything is working, save your connection for future use.

Note: For this example to work, both published and subscribed data must use the same MQTT credentials.
If using different credentials, you will need to create separate connections in MQTT Explorer.

This lesson is very practical, as there are many commercial scenarios where using an MQTT connector is necessary—either to publish data to external brokers or to an incoming topic on the platform’s MQTT broker.

HTTP Webhooks Data Sharing

HTTP Webhooks is more simple than MQTT, just create Channales on the device and enter the desired URL destination. Eventual credentials or API keys should be added inside the HTTP URL as headers.

Connectors Data Sharing

Channels can also use connectors from some services, how to configure the channel is then dependent on the external system. For example Delta Control Enteliweb channel requires a Bacnet configuration. It typically looks like this

[
  {
    "sourceField": "alarmFloodNumber",
    "deviceNumber": 125,
    "objectType": "binary-value",
    "instance": "810",
    "propertyName": "present-value",
    "createMissing": true,
    "objectName": "Washroom-11223344",
    "priority": "1",
    "dataType": "Boolean"
  }
]

Question

How do you effieciently subscribe to several iotnodes?

Answer

Use a wild card at the right location in the topic. Wildcards could # for all or +. For more info find the MQTT specification.

Question

No mqtt device shows up in Yggio, how do I check if my topic with data has been correctly published on Yggios MQtt broker?

Answer

Use Mqtt Explorer in line with instructions above to subscribe to topics with username and password on Yggios Mqtt broker.