MQTT is a network protocol ideal for Internet of Things (IoT) devices. Its lightweight header and message size and broker-managed communication model make it ideal for transferring data like sensor values and meter readings into VertiGIS FM Energy. Using the MQTT protocol, you can scale and connect a broker service to millions of IoT devices in your network.

Refer to VertiGIS FM Energy for general information about meters and sensors.

Configure and manage your organization's MQTT connections on the MQTT administration page (Administration > Interfaces > MQTT).

MQTT Administration Page

MQTT uses a broker to handle communication between publisher and subscriber clients. Publisher clients like smart meters and sensors send messages to a topic on an MQTT broker, and subscriber clients you create in VertiGIS FM query the topic for new messages. Values published to the subscribed topic (typically meter and sensor reading values) are then imported into VertiGIS FM as meter readings.

If your organization has its own MQTT broker, add it in the MQTT-Broker section, and then select it in the MQTT-Broker menu for each client you subscribe to the broker.

Adding Your Own MQTT Broker in VertiGIS FM

Add subscriptions to individual topics in the MQTT-Subscription section. If you plan to use a broker from a managed MQTT service, enter its endpoint and your authentication credentials in the entry for each subscriber client you add in the MQTT-Subscription section.

MQTT Brokers

Your organization can decide what kind of MQTT broker it wants to use in its implementation. You can

•use your own MQTT broker.

•use a broker provided by VertiGIS FM on the Azure platform, available to all customers.

•use an alternative managed MQTT service.

Most VertiGIS FM customers use a managed MQTT service for their broker.

Using Your Own Broker

If your organization has the infrastructure, MQTT broker software, security components, and operational knowledge to run and maintain its own MQTT broker, you can add it in the MQTT-Broker section on the MQTT administration page.

You can select brokers you add in the MQTT-Broker section from the MQTT-Broker menu when you add an MQTT subscriber.

Selecting Your Own MQTT Broker in the Subscriber

Using a Managed MQTT Service

If your organization plans to use a managed MQTT service (for example, Azure IoT Hub and Event Hub, AWS IoT Core, or HiveMQ Cloud), you only require an account or subscription to the service, authentication credentials, and a URL endpoint for the broker. In VertiGIS FM, specify the broker, credentials, and endpoint when you add a subscriber client. Do not add the broker in the MQTT-Broker section.

Add a Subscriber Client

Regardless of whether your organization uses its own broker or a third-party managed MQTT service, you can subscribe clients to it on the MQTT administration page in VertiGIS FM.

To Add an MQTT Subscriber Client

1.Navigate to the MQTT administration page (Administration > Interfaces > MQTT).

2.In the MQTT-Subscription section, click the Add () icon.

3.Enter a name for the new subscription in the Name field.

4.Enter the broker authentication and client configuration properties in the corresponding data fields. The following fields are mandatory:

▪Broker URL

▪Username

▪Filter topics

Refer to MQTT Subscriber Details for descriptions of all form fields.

The new subscriber form has multiple password menus for different MQTT authentication options. Refer to MQTT Subscription Details to ensure you are entering the password in the correct field.

5.Click Save or Save and Close.

MQTT Subscriber Details

MQTT Gateway

Your local infrastructure requires an MQTT gateway that acts as a publishing client for readings collected by your devices. The gateway publishes messages to the broker so that subscriber clients you create in VertiGIS FM can retrieve them from their topics.

Gateway JSON File

For VertiGIS FM to process MQTT data, the gateway payload must adhere to a nodal structure that uses specific keys. Certain values in the JSON must map to energy form and sensor type data in your VertiGIS FM implementation.

Structure

Currently, only JSON files with nodal structure that includes a top-level "muc" object for gateway data, a "meter" key with an object for sensor data for each sensor with readings in the file, and a "data" array with a payload for each reading associated with the meter or sensor are supported.

JSON File with Supported Structure

VertiGIS FM will support the use of other JSON files in the future.

Data Mapping

Values in JSON objects for the sensor and reading must match certain catalog values in VertiGIS FM. The meter key's array of objects must specify the energy form catalog entry assigned to the sensor, and the data's array of objects must specify the sensor type catalog entry assigned to the sensor, as well as the scale and unit of measurement specified in the sensor type catalog entry.

For example, refer to the JSON file below.

Sensor Catalog Data in MQTT Gateway JSON File

To see the energy form and sensor type assigned to a sensor, go to its details page.

Sensor Details Page

You can see the Scale and Unit values associated with the sensor type if you open the sensor type catalog entry selected in the Type of Sensor field.

Type of Sensor Catalog Entry

Important Keys in MQTT Gateway JSON File

The diagram below outlines the relationship between sensors, readings, and administrative data in VertiGIS FM Energy.

Diagram Showing Relationships Between Catalog Entries, Metering Points, and Sensors in the VertiGIS FM Administration