Generic MQTT Connector

Connector details Generic

The Generic MQTT connector allows the platform to publish data either on its own MQTT broker or an external MQTT broker. The main difference compared to an MQTT Channel is that publishing is done either by API or the Rule Engine, and the data can be reformatted before publishing. This provides the benefit that both the topic and data format can be adapted to match the requirements of an external system.

⚠️ It is currently not possible to use the Generic MQTT connector to subscribe to an MQTT broker.

Publishing Data on the Platform Internal MQTT Broker

To publish data on the platform MQTT broker, a basicCredentialSetId must first be created. This currently needs to be done through the API / Swagger at the endpoint:
https://staging.yggio.net/swagger/#/BasicCredentialsSets/createBasicCredentialsSet

Steps

1. Log in to Swagger with your credentials:
   https://staging.yggio.net/swagger/#/Authorization/login
2. Copy the token.
3. Go to the top-right corner in Swagger and add the token in the "Authorize" box.
4. Navigate to the Basic Credential Set endpoint and create your username and password.
5. Note the returned ID.

These credentials (username, password, and ID) will be used together with the topic by your external system to subscribe to the published data.

Required Information

To set up a Generic MQTT connector, provide the following:

• a. Basic Credential Set ID: The ID of the Basic Credential Set that defines the MQTT username and password.

Configure remote system

To subscribe to the platform MQTT broker, configure the remote system as follows:

• a. MQTT broker URL: mqtt.staging.yggio.net
• b. Port:
  • 8883 for secure TLS (strongly recommended)
  • 1883 for unencrypted data
• c. Topic: The base topic for the platform internal MQTT broker cannot be configured. It will always be yggio/push/v1/<BasicCredentialsSetId>/#. The # symbol in the topic will be replaced with a device-specific unique identifier by the publish command.
• d. MQTT username: As defined in the Basic Credential Set.
• e. MQTT password: As defined in the Basic Credential Set.
• f. MQTT version: You can subscribe with either MQTT v3.1.1 or MQTT v5.

Publishing Data on an External MQTT Broker

To publish data on an external MQTT broker it must first be configured to accept receive the data published by the platform, i.e. topic, username and password must be configured and the host URL known.

Configure remote system

Configure the remote system as follows:

• a. Port:
  • 8883 for secure TLS (strongly recommended)
  • 1883 for unencrypted data
• b. Topic: The base topic the platform should publish data on. Then in the actual publish command will append the topic with device unique identifier as subtopic.
• c. MQTT username: The username.
• d. MQTT password: The password.

Required Information

To set up a Generic MQTT connector to publish on an external MQTT broker, provide the following as configured in the remote system:

• a. MQTT broker URL: The URL of the MQTT broker
• b. Port: The port number
• c. Topic: The base topic the platform should publish data on.
• c. MQTT username: The username.
• d. MQTT password: The password.

Using the Platform MQTT Broker as an External Broker

It is feasible to use the platform MQTT broker as an external broker in the Generic MQTT integration. This opens up some interesting use cases:

• Share data from one platform instance to another.
• Remove sensitive data before sharing it with another user.
• Use command buttons to trigger events in the platform.

Setup Instructions

1. Log in to Swagger in the platform instance you want to publish data to, by following the instructions above.
   (It could be the same instance where you configure the Generic MQTT Connector.)

2. Create a Basic Credential Set:
   https://staging.yggio.net/swagger/#/BasicCredentialsSets/createBasicCredentialsSet

3. Reserve MQTT Sub Topics for all IoT nodes you want to publish data on:
   https://staging.yggio.net/swagger/#/ReservedMqttTopics/createReservedMqttTopic

   • The topic must follow the structure: yggio/generic/v2/<unique identifier>

4. Create the Generic MQTT Connector with the following configuration:

   • MQTT broker URL: mqtt.staging.yggio.net
     (or another platform instance)
   • Port: 8883 (Secure TLS)
   • Topic: yggio/generic/v2
   • MQTT username: As defined in the Basic Credential Set.
   • MQTT password: As defined in the Basic Credential Set.

Result

When you publish data, a New IoT node will be created in the platform. You can then:

• Share it with specific users, or
• Add a custom translator with specific logic to handle the incoming data.

Publishing Data with the Generic MQTT Connector

In the sections above, we created different types of Generic MQTT Connectors but did not publish any data.
To publish data, you must either:

1. Create a Rule with a Command Action in the rule engine, or
2. Send a Command directly to the connector through the API.

Create a rule

Using the Rule Engine to publish data is the most common use case for the Generic MQTT Connector.

The principle is simple:

• Use any type of trigger for the Rule.
• Add a Command Action as the Action.
• In the Command Action, create and filter the data you want to publish using dynamic information.

⚠️ Note: If you use a JSON message, every double quote " must be escaped with a backslash \.
It’s recommended to validate the final JSON with an online validator to ensure it is 100% correct.

Setup Instructions

1. Go to the Rule Engine.
2. Navigate to Actions.
3. Add a new Action of the type Command.
4. As Command, use: sendDownlink
5. As Data, define a JSON with the following keys:

• message
  The actual JSON stringified.
  The easiest way to generate this correctly is to use an online tool like JSON Stringify Online.

• mqttTopic
  The sub-topic that will be appended to the base topic.
  Since the sub-topic usually needs to be unique, common options are:

  • "${iotnode._id}"
  • "${iotnode.devEui}"
  • "${iotnode.secret}"

(See command examples below.)

6. Create a Rule with a suitable trigger condition, or use a command button as the trigger.
   Add the Command Action to the Actions (DO) section, with the Generic MQTT Connector as the target.

For details on how to use dynamic information in an Action, see the Rule Engine Guide.

Example Command Actions for reference (Command: sendDownlink)

Command button as trigger to set power level to 50%

{
	"message": "{\"powerLevel\":50}",
	"mqttTopic": "${iotnode._id}"
}

Command button as trigger to set power to off

{
	"message": "{\"command\":\"off\"}",
	"mqttTopic": "${iotnode._id}"
}

Reformat temperature to NGSI-LD format

{
	"message": "{\"temperature\":{\"value\":${iotnode.temperature},\"unit\":\"°C\",\"type\":\"property\"}}",
	"mqttTopic": "${iotnode.devEui}"
}

Reformat LoRaWAN signal quality parameters to NGSI-LD format

{
"message": "{\"rssi\":{\"value\":${iotnode.rssi},\"unit\":\"dB\",\"type\":\"property\"},\"snr\":{\"value\":${iotnode.snr},\"unit\":\"dB\",\"type\":\"property\"},\"frameCount\":{\"value\":${iotnode.frameCount},\"type\":\"property\"},\"spreadingFactor\":{\"value\":${iotnode.spreadingFactor},\"type\":\"property\"}}",
"mqttTopic": "${iotnode.devEui}"
}

Command API

The Generic MQTT Connector will publish data if it is gets a sendDownlink command through the API. This is an example

curl --location --request PUT "https://staging.yggio.net/api/connectors/command" \
    --header "Authorization: Bearer <token>" \
    --header "Content-Type: application/json" \
    --data '{
        "command": "sendDownlink",
        "integrationName": "Generic",
        "connectorId": "<connector _id>",
        "data": {
            "mqttTopic": "subTopic",
            "message": "myMessage as stringified JSON"
        }
    }'