Create an MQTT Collector

Before you begin

  1. Deploy Proficy Historian for Azure Cloud.
  2. Install collectors. You can install them on-premises or on a VNet (which can be different from the one on which Proficy Historian for Azure Cloud is deployed).

About this task

The MQTT collector collects data published to a topic using an MQTT broker. The data should be in Predix time series data format.
Supported MQTT versions:
  • MQTT V5
  • MQTT V3.1.1
Supported data formats:
  • Sparkplug B V1.0
  • KairosDB (that is, the Predix Timeseries format)
Features:
  • You can subscribe for multiple-level topics using a wildcard.
  • Only the unsolicited data collection is supported; polled collection is not supported.
  • The timestamp resolution is seconds, milliseconds, and microseconds.
  • Boolean, floating point, integer, and string data types are supported.
How it works:
  1. The MQTT collector connects to an MQTT broker and subscribes to a topic. You can use username/password-based authentication or certificate-based authentication. Transport Layer Security (TLS) authentication is used for subscribing the data from message broker to avoid middleware attacks so that the data is securely transferred from message broker to the MQTT collector.
  2. The collector converts the data from the Sparkplug B v1.0 or the KairosDB format to a Historian-understandable format.
  3. It verifies whether the tag is available in Historian; if not, it will add the tag and then add the data samples, and streams the data to the Historian server or a cloud destination.
KairosDB Message Format: 
{
"body":
[
    {
        "attributes":{"machine_type":"<value>"},
        "datapoints":[[<value>,<value>,<value>]],
        "name":"<value>"}],
        "messageId":"<value>"}
The following table describes these parameters.
JSON Parameter Description Required/Optional
machine_type The name of the machine from which you want to collect data. Optional
datapoints Time (in epoch format), value, and quality. Required
name The tag name Required
messageId The type of the message Optional
Note: For the parameters marked optional, you need not enter values. However, you must enter the parameter names. For example:
{"body":[{"attributes":{"machine_type":" "},
"datapoints":[[1558110998983,9547909,3]],"name":"QuadInteger"}],"messageId":" "}
Supported Data Types
Source Data Type Historian Data Type
DoubleFloat, DoubleInteger, FixedByte, QuadInteger, SingleFloat ihDoubleFloat
ByteString, String ihVariableString
Boolean ihBool

Procedure

  1. Run Command Prompt as an administrator.
  2. Run the AzureCloudHistorianConfigurationUtility.exe file. It is provided along with the collectors installer. After you install collectors, it will be available in the C:\Program Files\GE Digital\Historian Cloud Config folder by default.
  3. Enter the number corresponding to creating a collector instance.
  4. Enter the number corresponding to the collector that you want to create.
  5. Enter the following details:
    Field Description
    Interface Name Enter the name that you want to provide for the collector instance.
    Azure Load Balancer IP

    Enter the Azure Load Balancer IP. A value is required.

    Tip: To find the Azure Load Balancer IP:
    1. Go to the Azure portal.
    2. Go to the Resource Group that was specified during deployment.
    3. Select the cluster_name-IP to access the resource of type Public IP Address.
    4. Select or copy the IP Address.
    Username Enter the username to connect to Proficy Historian for Azure Cloud. A value is required.
    Password Enter the password to connect to Proficy Historian for Azure Cloud. A value is required.
    Tip: For the default user, ihCloudHistAdmin, this is the value you entered in the Password field at the time of deployment.
    MQTT server Enter the IP address or host name of the MQTT broker using which you want to collect data. A value is required. By default, it considers the local host name.
    MQTT topic Enter the MQTT topic from which you want to collect data. A value is required. You can enter multiple topics separated by commas.

    If you want to use the SparkplugB format, enter a value in the following format: namespace/group_id/message_type/edge_node_id/device_id

    where:
    • namespace is the Sparkplug version. Enter spBv1.0.
    • group_id is the ID of the group of nodes from which you want to collect data.
    • message_type is the message type from which you want to collect data. The collector processes data only from NDATA and DDATA message types.
    • edge_node_id is used to identify the MQTT EoN node within the infrastructure.
    • device_id a device attached to the MQTT EoN node either physically or logically.
    You can use the wildcard character # for any of these parameters (except for namespace).
    MQTT port Enter the port number of the MQTT broker. A value is required.
    Quality of service Enter the quality of service that you want to use while collecting data from an MQTT broker.
    • 0: Indicates that the message is delivered at most once or it is not delivered at all.
    • 1: Indicates that the message is always delivered at least once.
    • 2: Indicates that the message is delivered once.
    For more information, refer to https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels/.
    MQTT version Enter the version of the MQTT broker that you want to use.
    Clean session Enter one of the following values:
    • true: Enter this value if you do not want to create a new session when the MQTT broker and the collector are disconnected from each other.
    • false: Enter this value if you want to retain the session when the MQTT broker and the collector are disconnected from each other. This ensures that there is no loss of data. If you want to choose this option, ensure that you have entered 1 or 2 for the quality of service.
  6. If you do not want to use MQTT broker authentication, for the Authentication enabled for MQTT broker field, enter N.
    The MQTT collector is created and started.
  7. If you want to use certificate-based authentication to connect to the MQTT broker, enter values as described in the following table.
    Field Description
    Authentication enabled for MQTT broker Enter Y.
    Certificate-based authentication Enter Y.
    Root CA server certificate file path Enter the path to the CA server root file to connect to the MQTT broker. A value is required.
    Client certificate file path Enter the path to the client certificate file to connect to the MQTT broker. A value is required.
    Client key file path Enter the path to the private key file to connect to the MQTT broker. A value is required.
    The MQTT collector is created and started.
  8. If you want to use username-password-based authentication to connect to the MQTT broker, enter values as described in the following table.
    Field Description
    Authentication enabled for MQTT broker Enter Y.
    Certificate-based authentication Enter N.
    MQTT username Enter the username to connect to the MQTT broker. A value is required.
    MQTT password Enter the password to connect to the MQTT broker. A value is required.
    The MQTT collector is created and started.