Contact Sales User Login
Plugin Reference Manuals

Plugins Documentation

Browse configuration schemas, route definitions, and integration guides for all official Uniflow dynamic plugins.

MQTT Client

MQTT Client

ID: uniflow.plugin.mqtt • Category: IoT & Communication Protocols • Version: v1.4.1 • Min Uniflow Version: Uniflow ≥ v1.4.0

MQTT Client Plugin Reference Manual

1. Overview

Plugin Name: MQTT Client

Type: IoT & Messaging

Identifier: uniflow.plugin.mqtt

Description

Integration with MQTT Brokers.

License Tier Restrictions

The MQTT Client plugin is available on all license tiers with the following capability differences:

CapabilityFree / TrialPro / Enterprise
Maximum Topic Points1Unlimited
Direct Access Publish✅✅
QoS 0 / 1 / 2 Support✅✅
TLS / SSL Encryption✅✅
IMPORTANT — Free Tier Limitations

On the Free and Trial tiers, the plugin restricts the total number of configurable topic points to 1. If you attempt to add a topic point that exceeds this constraint, Uniflow will display a dialog alert explaining the license restriction. Upgrading to a Pro or Enterprise license removes all limitations.

NOTE — Wildcard Topic Behavior (`+`, `#`)

Topics containing MQTT wildcard characters (+ or #) are automatically designated as Read-Only (Subscription only). Publishing to wildcard topic filters is forbidden in the MQTT specification. Consequently, wildcard topic points automatically have Publish disabled in the point editor and are excluded from Output Target rule graph nodes so they cannot be selected as write targets.

IMPORTANT — Explicit Payload Data Types & Validation

Every MQTT topic point must have an explicit data type defined in its configuration (Bool, Int16, UInt16, Int32, Int64, Double, String, DateTimeOffset, or Json). When an incoming MQTT message arrives, the adapter attempts to parse/cast the raw payload string into the configured data type. If type casting fails (e.g., an unparseable text string arrives on an Int32 or Double topic), the plugin logs a conversion error to the system log and drops the payload, ensuring invalid messages are not published to the telemetry catalog.

NOTE — MQTT Retain Flag

The Retain parameter applies exclusively to outbound publishing (Write actions). When enabled (Retain = true), the MQTT broker persists the last published message for that topic and automatically delivers it to any future or reconnecting subscribers upon connection.

2. Technical Architecture

The MQTT Client plugin provides publish/subscribe messaging over TCP/IP or WebSockets with TLS encryption using MQTTnet. It supports MQTT v3.1.1 and v5.0 protocols, manages QoS levels (0, 1, 2), handles topic subscription wildcard filters (+, #), dispatches incoming message payloads to catalog dynamic tags, and maintains automatic broker reconnect loops with Last Will and Testament (LWT) configurations.

System Interaction & Exposed Catalog Routes

The MQTT Client plugin connects to MQTT brokers with TLS/SSL encryption and QoS 0/1/2 settings. It subscribes to topic hierarchies with wildcards (+, #), parses JSON/string payloads, and publishes messages to the broker.

Catalog Routes & Node Integration

Input Event Triggers (Input Nodes):

  • mqtt.message_received - Emitted when a message arrives on a subscribed topic.
  • mqtt.connected - Broker connection established event.
  • mqtt.disconnected - Broker disconnect event.

    • Executable Actions (Action Nodes):

  • mqtt.publish_message - Publishes a message payload to a topic.
  • mqtt.subscribe_topic - Subscribes to a new topic filter.
  • mqtt.unsubscribe_topic - Unsubscribes from a topic.

    • Architecture Diagram

    VISUAL ARCHITECTURE FLOW DIAGRAM
    Rendering Flow Architecture Diagram...

    3. Configuration Parameters

    The following configuration fields are available in the User Interface for this plugin:

    Configuration SettingDescription
    Broker HostSpecifies the broker host.
    PortNumeric value specifying the port.
    Client IDSpecifies the client id.
    Keep Alive (s)Numeric value specifying the keep alive (s).
    Auth ModeSpecifies the auth mode.
    UsernameSpecifies the username.
    PasswordSpecifies the password (secure).
    Certificate Path (.pfx)Specifies the certificate path (.pfx).
    Certificate PasswordSpecifies the certificate password (secure).
    TLSToggle to enable or disable tls.
    Clean SessionToggle to enable or disable clean session.

    4. Exposed Routes & Data Types

    This plugin exposes catalog fields across the following rule graph nodes:

    Input Source

    The Input Source node reads live payload telemetry from subscribed MQTT topics.

    Human-Readable Field NameData TypeDescription
    Subscribed MQTT Topic  String` / `Json` / `Double` / `Int32` / `Bool
    ↳Telemetry payload published by remote MQTT clients to a subscribed broker topic filter.

    Event Input

    The Event Input node listens for real-time MQTT message arrival events.

    Human-Readable Field NameData TypeExposed Event Fields & Data TypesDescription
    MQTT Message Event  Event Object
    ↳
    Topic (String)
    Payload (String)
    QoS (Int32)
    Retain (Bool)
    Timestamp (DateTime)
    		Real-time event triggered whenever a message arrives on a subscribed MQTT topic.

    Output Target

    The Output Target node acts as an action sink node to publish messages to predefined or dynamic MQTT broker topics.

    Target NameData TypeAssociated ParametersParameter Data TypeRequiredDescription
    Configured Publish Topic  String` / `Json
    ↳ValueString / JsonTrueMessage payload to publish to the target configured topic.
    Direct Access  String
    ↳Topic (Topic)StringTrueTarget MQTT topic path (e.g. factory/line1/cmd).
    ↳Payload (Payload)StringTrueMessage payload string or JSON object.
    ↳QoS (QoS)Int32FalseQuality of Service level (0, 1, or 2).
    ↳Retain (Retain)BoolFalseMQTT retain flag (True to keep message on broker).

    5. Usage Examples

    Scenario A: Environmental Sensor MQTT Telemetry Triggers Modbus HVAC Register & Webhook

    Workflow Overview:

    The MQTT Client subscribes to topic sensors/zone1/telemetry. When a message arrives with Humidity > 75%, Uniflow evaluates the JSON payload and executes two actions:

    1. Writes a Modbus TCP holding register (HoldingRegister 105 = 1) to engage a dehumidifier.

    2. Sends an HTTP POST alert to the facility monitoring server.

    Rule Node Configuration:

    1. Event Input Node: MQTT Message Event

  • Topic Filter: sensors/zone1/telemetry
  • Exposed Fields: Payload (String), Topic (String)

    • 2. Logic Filter Node: JSON Path & GreaterThan

  • Path Extraction: $.humidity (Double)
  • Evaluation: humidity > 75.0

    • 3. Output Target Node A: Modbus Client Writer

  • Action Target: Direct Access
  • Type: Holding Register
  • Address: 105
  • Value: 1

    • 4. Output Target Node B: HTTP Client Action

  • Action Target: POST Request
  • URL: https://monitor.facility.local/api/humidity-alert

    • Logic Flow Diagram:

    VISUAL ARCHITECTURE FLOW DIAGRAM
    Rendering Flow Architecture Diagram...

    Scenario B: Avigilon Analytics Match Event Publishes MQTT Alert Payload to Cloud Broker

    Workflow Overview:

    When Avigilon ACC detects an analytics rule match event (ANALYTICS_RULE_MATCH), Uniflow intercepts the camera event and publishes a structured JSON payload to the MQTT broker on topic security/alerts/camera01 with QoS 1 and Retain set to True.

    Rule Node Configuration:

    1. Event Input Node: Avigilon ACC Listener

  • Event Code: ANALYTICS_RULE_MATCH
  • Exposed Fields: CameraName (String), RuleName (String), Timestamp (DateTime)

    • 2. Logic Formatter Node: JSON Builder

  • Template: {"event": "ANALYTICS_MATCH", "camera": "{CameraName}", "rule": "{RuleName}"}

    • 3. Output Target Node: MQTT Client Publisher

  • Action Target: Direct Access
  • Topic: security/alerts/camera01
  • Payload: Generated JSON string
  • QoS: 1
  • Retain: True

    • Logic Flow Diagram:

    VISUAL ARCHITECTURE FLOW DIAGRAM
    Rendering Flow Architecture Diagram...
    Architecture Flow Diagram — Full Preview