Create an MQTT Ingress
To create an MQTT Ingress, get started by navigating to the Ingresses area under the Twin Engine in the Hark Platform. Please ensure you have created an MQTT Connector before following this guide.
Getting Started
Get started by clicking Create in the top left of the list of configured Ingresses. You'll need to give the Ingress a Name and select the MQTT Connector you created prior. When you've completed those details, click Next.
To ingest telemetry via an Ingress, you'll need to provide a message body that uses a key-value structure object where the key is the Property ID or Attribute Name, and the value is the value that corresponds to that Property ID or Attribute. For example:
{
"temperature": 24,
"humidity": 35
}
If your message body does not match the above structure, you can use a UDF Transformation described below to get your message body in the correct shape for an Ingress.
Add Mappings
Mappings allow you to define what topics the Ingress should keep a look out for, and what to do with the messages on those topics when the Twin Engine receives a message on the defined topics.
To add a Mapping, click Add Mapping, you'll be presented with a form to enter details about your Mapping. Enter the MQTT Topic your mapping should use to receive telemetry. You can use wildcarded topics such as /devices/+/telemetry.
Next, configure a Mapping Type by selecting what you'd like to do with the incoming telemetry.
- Model Properties - Set Properties against a Model when the configured topic receives a message.
- Model Events - Raise an Event when the configured topic receives a message.
Configure a Model ID Mapper
The Ingress needs to know which Model ID to use when setting Model Properties, or raising Events. To do so, click on the Model ID button and select a Mapper to use. There are a wide range of Mappers you can use, such as JavaScript UDF, Static, Topic Level or more.
Note: If you use an optional transformation, configured below, the configured mapper will receive the transformed message body.
Clicking on each of the options will give you more information about what each Mapper does. When you've chosen the mapper you'd like to use, click Next and configure your mapper, saving it when you have completed the configuration.
| Mapper Name | Description |
|---|---|
| JavaScript UDF | Provide JavaScript code to retrieve the value to use for a field. topic and message variables are available for use. |
| JSON Path | Provide a JSON dot-notation path to use to get the value. e.g: $.telemetry.temperature |
| Static | Provide a static, or constant, value to use for this field. Helpful if you already know the value to use. |
| Template | Provide a Scriban template to use to retrieve the value to use for a field. Similar to the JavaScript UDF, but Scriban. |
| Topic Level | Retrieve a value from the MQTT message topic by using a Topic Level, e.g: the topic of devices/+ and the topic level of 2 to get the value that is in place of +. |
Configure an Optional Transformation
After configuring the basic details for your Mapping, you can provide an optional Transformation. This is helpful when you need to do some sort of computation or structuring in order to ingest the telemetry correctly.
To do so, click the Transformation tab or click Next after configuring your Mappings basic details. You'll need to check the checkbox to enable the use of a UDF Transformation.
If you are providing a UDF Transformation to transform your message before use in your Model Properties or Events, enter the JavaScript code to do the required transformation, and click Save. If you have entered a UDF but do not wish to use it, simply uncheck the checkbox to disable the use of your Transformation.
Add the Mapping
After configuring the basic details of your Mapping, and an optional Transformation, click Save Mapping on the bottom of the Mapping Editor and your Mapping will be added to the Ingress.
If you need to reconfigure the mapping, you can click the Edit icon on the right hand side of the Mapping in the table of Mappings on your Ingress. On the left hand side, you'll find a Trash button you can use to remove the Mapping from your Ingress.
Finalising your Ingress
When you've configured the basic details and adding Mappings to your Ingress, you can click Save on the action bar at the top, or the bottom of view. Your Ingress will be created and ready to start reciving