Skill MQTT TagProvider

---
title: "MQTT TagProvider Integration"
tags: [mqtt, tagprovider, uns, iiot, asset-navigation, dynamic-tags]
description: "Connect to an MQTT broker via TagProvider, explore its namespace, link selected nodes into the UNS AssetTree, and build an asset-navigation UI with DataGrid, TrendChart, and AlarmViewer — all driven by dynamic Asset() bindings."
version: "0.1-draft"
author: "Tatsoft"
---

Connect FrameworX to an external MQTT broker using TagProvider (zero-local-tags), auto-discover topic trees, link them into the UNS AssetTree, and build a dynamic asset-navigation UI with DataGrid, TrendChart, and AlarmViewer — all driven by Asset() bindings and Client.Context properties.

MQTT Broker ??? TagProvider ??? UNS Namespace (dynamic)
                                    ?
                              AssetTree Folder
                                    ?
                    ?????????????????????????????????
                  Header        AssetTree         MainPage
                 (Canvas)    (Navigation)     (DataGrid + Trend)
                                    ?
                          Client.Context.AssetPath
                          drives all content dynamically

When to Use This Skill

Use this skill when:

• The user wants to connect to an external MQTT broker (not create local simulated data)
• The data structure is dynamic or unknown upfront — the broker defines what exists
• The user mentions TagProvider, MQTT, IIoT, UNS integration, or auto-discovery
• The user wants an asset-navigation UI where selecting a tree node changes the displayed data
• The application is monitoring/visualization focused (not tight SCADA control)

Do NOT use this skill when:

• The user wants explicit point-by-point control over specific MQTT topics — use Device Module approach instead (Channel → Node → Points)
• The user needs local tags with alarms and historian on individual points with strict validation — use Device Module
• The data source is not MQTT (for OPC UA TagProviders, similar patterns apply but connection details differ)
• The user just needs a simple dashboard with simulated data — use ValueSimulator with standard Tags

Decision guide:

Prerequisites

• Solution must be open (open_solution or create_solution completed)
• An MQTT broker must be accessible from the machine (local or remote)
• For testing without an external broker: FrameworX has a built-in MQTT broker and a SparkplugB simulator that can be started from Data Explorer → MQTT Tools

MCP Tools and Tables Involved

Implementation Steps

Step 0: Discover the MQTT Broker Data (Interactive)

Before creating any configuration, you need to see what data the broker has. This step is interactive — it involves the user.

If using the built-in broker for testing:

designer_action('start_mqtt_broker')
designer_action('start_mqtt_simulator')

This starts a local MQTT broker and a SparkplugB simulator that publishes sample data (solar panels, cities, sensors).

Navigate to MQTT Tools:

designer_action('navigate', 'DataExplorer.MQTTTools')

Connect to the broker:

designer_action('connect_mqtt_explorer', '<PrimaryStation string>')

The PrimaryStation format for MQTT is a semicolon-delimited string with 14 fields:

{Host};{Port};{ClientID};{Username};{Password};{CertFile};{KeyFile};{TLS};{CleanSession};{WillTopic};{QoS};{KeepAlive};{RetainPublish};{UseWebSocket};

Common examples:

Ask the user to explore and select:

The MQTT browser is now connected. Please navigate the tree to explore the available data. When you've identified the nodes you want to integrate into the Unified Namespace, select them and let me know — or I can read your current selection.

Read the user's selection:

get_designer_state()

This returns the current MQTT Tools state including which nodes the user has selected (or browsed to). Use this information to determine the initial tree nodes for the TagProvider link.

Step 1: Create the TagProvider Connection

Fetch the schema and protocol details:

get_table_schema('UnsTagProviders')
list_protocols('mqtt')

Write the TagProvider object:

{
  "table_type": "UnsTagProviders",
  "data": [
    {
      "Name": "MQTT",
      "Protocol": "MQTT",
      "PrimaryStation": "localhost;1883;FrameworX-001;;;;;None;False;;AtLeastOnce;10;False;False;",
      "Separators": "BranchSeparator=/;AttributeSeparator=/;",
      "Description": "Production MQTT Broker"
    }
  ]
}

Key decisions:

• Name: This becomes the root of the dynamic namespace — Tag.MQTT.*. Choose a meaningful name (e.g., ProductionMQTT, FactoryBroker).
• Separators: BranchSeparator=/;AttributeSeparator=/; maps MQTT topic hierarchy (plant/line1/temp) to UNS path hierarchy. This is almost always the correct default for MQTT.
• PrimaryStation: Must match the connection details confirmed in Step 0.

After creation, the TagProvider immediately starts discovering topics when runtime starts. Topics appear as dynamic tags under Tag.<ProviderName>.<topic.path>.

Step 2: Create the Linked Folder in AssetTree

The AssetTree folder is what makes the TagProvider data visible and navigable in the UI. A Linked Folder connects an AssetTree node to a TagProvider and specifies which initial nodes from the provider's namespace to display.

{
  "table_type": "UnsAssetTree",
  "data": [
    {
      "Name": "Production",
      "TagProviderLink": "MQTT",
      "InitialPath": "spBv1.0/GroupID",
      "Description": "MQTT production data from SparkplugB broker"
    }
  ]
}

Key decisions:

• Name: The folder name in the AssetTree — what operators see in the navigation tree.
• TagProviderLink: Must match the TagProvider Name from Step 1 exactly.
• InitialPath: The starting node(s) selected by the user in Step 0. Everything below this path in the broker automatically expands into the folder.

From this point down, the AssetTree is dynamic — the platform auto-expands the tree based on whatever the MQTT broker publishes. No further tag creation needed.

Step 3: Build the Layout (Header + AssetTree + Content)

The standard pattern for asset-navigation applications is a Layout with three regions:

get_table_schema('DisplaysLayouts')
list_elements('Layout')

{
  "table_type": "DisplaysLayouts",
  "data": [
    {
      "Name": "Startup",
      "Header": "Header",
      "Menu": "AssetTreeMenu",
      "Content": "MainPage",
      "Description": "Asset navigation layout — tree on left, dynamic content on right"
    }
  ]
}

The Layout Startup (ID 0) is the predefined startup layout — modifying it changes what loads on application launch.

Regions:

• Header: Top bar — title, navigation buttons, status indicators
• Menu (left side): The AssetTree control — users click here to navigate assets
• Content (main area): The display that reacts to the selected asset

Step 4: Create the Header Display

A simple Canvas display with the application title:

get_table_schema('DisplaysList')
list_elements('TextBlock,Button')

{
  "table_type": "DisplaysList",
  "data": [
    {
      "Name": "Header",
      "PanelType": "Canvas",
      "Width": 1200,
      "Height": 60,
      "Description": "Application header bar",
      "Objects": [
        {
          "Type": "TextBlock",
          "Name": "Title",
          "Left": 20,
          "Top": 15,
          "Text": "MQTT Production Monitor",
          "FontSize": 18,
          "FontWeight": "Bold"
        }
      ]
    }
  ]
}

Step 5: Create the AssetTree Menu Display

A Canvas display containing the AssetTree control that drives navigation:

list_elements('AssetsTree')

{
  "table_type": "DisplaysList",
  "data": [
    {
      "Name": "AssetTreeMenu",
      "PanelType": "Canvas",
      "Width": 300,
      "Height": 700,
      "Description": "Asset tree navigation panel",
      "Objects": [
        {
          "Type": "AssetsTree",
          "Name": "NavTree",
          "Left": 0,
          "Top": 0,
          "Width": 300,
          "Height": 700
        }
      ]
    }
  ]
}

When the user clicks a node in the AssetsTree, the platform automatically updates:

These properties drive the content display reactively.

Step 6: Create the MainPage (Dynamic Content)

The MainPage uses Asset() bindings to react to the user's tree selection. All content is driven by Client.Context.AssetPath.

list_elements('DataGrid,TrendChart,TextBlock,AlarmViewer')

{
  "table_type": "DisplaysList",
  "data": [
    {
      "Name": "MainPage",
      "PanelType": "Dashboard",
      "Columns": 2,
      "Rows": 3,
      "Description": "Dynamic content — reacts to AssetTree selection",
      "Objects": [
        {
          "Type": "TextBlock",
          "Name": "AssetTitle",
          "Row": 0,
          "Column": 0,
          "ColSpan": 2,
          "Text": "",
          "LinkedValue": "@Client.Context.AssetName",
          "FontSize": 20,
          "FontWeight": "Bold"
        },
        {
          "Type": "DataGrid",
          "Name": "AssetData",
          "Row": 1,
          "Column": 0,
          "ColSpan": 2,
          "LinkedValue": "@Tag",
          "LinkedContext": "@Client.Context.AssetPath",
          "Width": 800,
          "Height": 300
        },
        {
          "Type": "TrendChart",
          "Name": "AssetTrend",
          "Row": 2,
          "Column": 0,
          "Width": 500,
          "Height": 250,
          "Duration": "00:05:00"
        },
        {
          "Type": "AlarmViewer",
          "Name": "AssetAlarms",
          "Row": 2,
          "Column": 1,
          "Width": 400,
          "Height": 250
        }
      ]
    }
  ]
}

Key pattern — the DataGrid LinkedValue:

When you set the DataGrid's LinkedValue to @Tag and provide a LinkedContext pointing to @Client.Context.AssetPath, the DataGrid automatically shows all children (sub-tags and attributes) of whatever the user selected in the AssetTree. This is the heart of the dynamic pattern — one display serves the entire asset hierarchy.

The Asset() syntax for code and expressions:

// In scripts or CodeBehind:
double value = Asset(@Client.Context.AssetPath + "/Temperature");

// In display element LinkedValue fields:
// Static: @Tag.MQTT.plant.line1.temperature
// Dynamic: Asset(Client.Context.AssetPath + "/Temperature")

Step 7: Start Runtime and Verify

designer_action('start_runtime')

After starting:

1. The TagProvider connects to the MQTT broker and discovers topics
2. The AssetTree populates with the linked folder structure
3. Clicking any node in the tree updates Client.Context properties
4. The DataGrid, TrendChart, and other elements on MainPage react to the selection

Take a single screenshot to verify:

get_screenshot('runtime')

Code Examples

Asset() in CodeBehind (Display Events)

void Opening()
{
    // Optionally set a default branch to expand
    @Client.Context.TreeInitialBranch = "MQTT/spBv1.0/GroupID";
}

Asset() in Scripts

public static double GetTemperature(string assetPath)
{
    return TK.ToDouble(Asset(assetPath + "/Temperature"));
}

Data Type Handling for HTML5/Portable Clients

// WPF (.NET Framework 4.8) — automatic type resolution
var value = Asset("/MQTT/plant/line1/temperature");

// HTML5/Portable (NetStandard 2.0) — explicit conversion required
int intValue = TK.ToInt(Asset("/MQTT/plant/line1/count"));
double dblValue = TK.ToDouble(Asset("/MQTT/plant/line1/temperature"));
string strValue = TK.ToString(Asset("/MQTT/plant/line1/status"));
bool boolValue = TK.ToDigital(Asset("/MQTT/plant/line1/running"));

Verification

1. get_objects('UnsTagProviders') — verify the TagProvider was created with correct PrimaryStation
2. designer_action('navigate', 'Uns.AssetTree') → get_designer_state() — confirm the linked folder appears with the TagProvider reference
3. designer_action('start_runtime') → get_runtime_state() — confirm the TagProvider connection is active
4. get_screenshot('runtime') — verify the AssetTree populates and the Layout renders correctly
5. Ask the user to click different nodes in the AssetTree and confirm the DataGrid updates dynamically

Common Pitfalls

Variations

Variation A: Mixed Approach (TagProvider + Device Module)

• Use TagProvider for browsing and monitoring the full MQTT namespace
• Use Device Module for specific critical tags that need alarms, historian, and strict validation
• Both can connect to the same MQTT broker in the same solution
• Useful when 90% of data is for monitoring, but 10% needs SCADA-grade control

Variation B: SparkplugB-Specific

• Use MQTTspB protocol instead of MQTT in the TagProvider
• SparkplugB provides richer metadata (data types, birth/death certificates)
• Change Separators to match SparkplugB topic structure
• Useful when the MQTT broker uses Sparkplug B specification

Variation C: Multiple Brokers

• Create multiple TagProviders, each with a different Name and PrimaryStation
• Create separate AssetTree linked folders for each provider
• The same Layout and MainPage pattern works — Client.Context handles any source
• Useful when aggregating data from multiple factories or edge gateways

Variation D: Add Historian to Dynamic Tags

• For specific TagProvider paths that need historical trending, create a Historian TagProvider connection
• TrendCharts can use Asset() syntax to automatically query historical data from historian TagProviders
• Useful when you need long-term trending on external data without creating local tags

Related Skills

• skill-device-mqtt — Explicit MQTT integration using Device Module (Channel → Node → Points)
• skill-asset-navigation — Generic asset-navigation UI patterns (not MQTT-specific)
• skill-sparkplugb-collector — SparkplugB Collector setup with Device Module

Documentation References

• TagProvider Services — Concept overview
• TagProvider Services How-to — Step-by-step procedures
• UNS TagProvider Services Reference — All properties and settings
• TagProvider Services Technology — Architecture deep dive
• MQTT Tools Reference — Data Explorer MQTT browser
• MQTT Integration Reference — TagProvider vs Device comparison

Open Items (Draft Notes)

DRAFT

In this section...