HiveMQ 'Hello World' Data Hub Module Example

Purpose

This repository contains a simple 'Hello World' example of a custom Data Hub Module , intended for use with the HiveMQ MQTT Broker.

This example is intended to show the files and metadata required to create a custom working module, as well as demonstrate how to implement some simple working Data Hub functionality using a custom module. This repo is also intended to be cloned and adapted for your own custom module needs, and to function as a basic starter template.

Structure of the Custom Module

Custom modules must consist of a folder with the following files:

• index.json: This file contains the metadata for the custom module. It includes details that will be shown in the Control Center, such as the name of the module, a short description, and the version of the module. It can also be used to set the the minimum HiveMQ Broker version required to use the custom module. It must also list the contents of the custom module.

• At least one policy, referenced in the index.json file. This can be either a data or behavioural policy. In this example, we show a simple data policy which validates if the incoming message is JSON and runs a short script to include a timestamp if this is the case.

• All schemas and scripts referenced in the policy.

• variables.json: This file defines the input parameters that can be used to configure the module. You can use the defined input parameters in resources such as your schema.json or data-policy.json.vm. If no variables are defined, the file still must exist with just empty {}.

Reserved variables

Reserved variables are predefined by HiveMQ and must not be overwritten in the variables.json file:

• ${instanceId}: Used in identifiers of schemas, scripts and policies. eg. "id": "my-custom-policy-${instanceId}". It’s very important to use this variable so that every module instance can create its own resources.

• All variables used for String Interpolation such as ${clientId} and ${topic}.

Available functions

• $base64.encode(): This function allows you to encode your schema definitions and script sources into base64. For example, $base64.encode('{}') results in e30=.

Import into the Broker

To import the custom module into your Broker, first zip the folder, including the files. This zip file can then be uploaded via Data Hub within the Control Center.

Support

Full documentation for Custom Modules can be found here. For help or support in building your own custom modules, join our community.

License

HiveMQ Hello World Data Hub Module is licensed under the APACHE LICENSE, VERSION 2.0. A copy of the license can be found here.